VirtueMart

h1. Product Plugins

h2. for user  

The product plugin is installed as a standard joomla plugin

To see it you must publish it in joomla extention after installation.

After you do that, you can find it in the customfields on edit Choice : 

*Custom Field Type* : plugin

After choicing the plugin you can setup the defaut value depending on your plugin.

h2. for developper.

h3. Language files :

XML install file must use the name in this form plg_vmcustom_YOURPLUGINNAME

EG. for textinput french and english

    <languages>

        <language tag="en-GB">en-GB.plg_vmcustom_textinput.ini</language>

        <language tag="fr-FR">fr-FR.plg_vmcustom_textinput.ini</language>

    </languages>

the constructor include directly the language file to simplify using JTEXT

Try to always use this convention name in the ini files :

VMCUSTOM_YOURPLUGINNAME_STRING="my string in english"

EG. for texinput plugin , string : size

VMCUSTOM_TEXTINPUT_INPUT_SIZE="Size of input"

h3. Write your plugin :

Product plugin is always created from *vmCustomPlugin* base class eg...

<pre>

class plgvmcustomvmcalendar extends vmCustomPlugin {

	function __construct(& $subject, $config) {

		parent::__construct($subject, $config);

		$this->_tablepkey = 'id';

		$this->tableFields = array_keys($this->getTableSQLFields());

		$varsToPush = array(	'from'=>array('1977-01-01','date'), 'to'=>array('1977-01-01','date')

		);

		$this->setConfigParameterable('custom_params',$varsToPush);

	}

</pre>

_List of function to write in your plugin_

*plgVmOnProductEdit($field,$param,$row, $product_id);*

	render the plugin with param  to display on product edit customfields TAB

	(called by customfields inputTypePlugin)

*plgVmOnDisplayProductFE( $field, $param, $product, $idx);*

	display the plugin on product FE

	return $html

*plgVmOnViewCartModule( $product,$custom_param,$productCustom, $row);*

	display the product plugin on cart module

	return $html

*plgVmOnViewCart($product, $param,$productCustom, $row);*

	display the product plugin on cart

	return $html

*plgVmOnViewCartOrder($product, $param,$productCustom, $row)*

	handel $param before adding it in the order

	return $param;

        *currently (2.0.2) not implemented/obsolete*	

*plgVmDisplayInOrderFE($item, $param,$productCustom, $row);*

	display the plugin in order for customers

	$item is the order item line

	Eg. to Get the statut ( $item->order_status == 'S'  )

        *currently (2.0.2) not implemented*

*plgVmDisplayInOrderBE($item, $param,$productCustom, $row);*

	display the plugin in order for vendor

	$item is the order item line

        *currently (2.0.2) not implemented*

*modifyPrice( $product, $field,$param,$selected )*

	overide the defaut price modifation by plugin

	you have to rewrite it in your plugin to do other calculations

	_you must return $field->custom_price at end to include your changes or the price varaint is set to 0;_

*plgVmGetProductStockToUpdateByCustom(&$product,$param, $productCustom)*

        Gets called after cart item is stored to database. 

        Developer can read product and parameters and eventually do own modifications.

        $param contains plugin values(if applicable) so developer can read those values

        Necessary check have to be performed...here check against field is not possible

        so eg. at least such a vaidation have to be done:

<pre>

		if ( !empty($param['vmcalendar']) && is_array($param['vmcalendar']))

		{

			$rf = $param['vmcalendar']['reservation_from'];

			$rt = $param['vmcalendar']['reservation_to'];

                        ....

</pre>

*See samples - specification/stockable/textinput to get inspiration and know-how*

h3. Use of plugin XML parameters :

*XML Exemple for textinput*

<pre>

<?xml version="1.0" encoding="UTF-8" ?>

<install version="1.5" type="plugin" group="vmcustom" >	

    <name>VMCustom - textinput</name>

    <creationDate>June 2011</creationDate>

    <author>The VirtueMart Development Team</author>

    <authorUrl>http://www.virtuemart.net</authorUrl>

    <copyright>Copyright (C) 2004-2011 Virtuemart Team. All rights reserved.</copyright>

    <license>http://www.gnu.org/licenses/gpl-3.0.html GNU/GPL</license>

    <version>1.9.8</version>

    <description>text input plugin for product</description>

    <languages>

        <language tag="en-GB">en-GB.plg_vmcustom_textinput.ini</language>

        <language tag="fr-FR">fr-FR.plg_vmcustom_textinput.ini</language>

    </languages>

    <files>

        <filename plugin="textinput">textinput.php</filename>

    </files>

    <params addpath="/administrator/components/com_virtuemart/elements">

        <param type="vmjpluginwarning" />

        <param name="custom_name" type="text" size="20"  default="COM_VIRTUEMART_COMMENT" label="VMCUSTOM_NAME_INFO" description="VMCUSTOM_NAME_INFO_DESC" />

        <param name="custom_size" type="text"  size="5"  default="10" label="VMCUSTOM_TEXTINPUT_SIZE" description="VMCUSTOM_TEXTINPUT_SIZE_DESC" />

        <param name="custom_price_by_letter" type="list"  default="0" label="VMCUSTOM_PRICE_BY_LETTER" description="VMCUSTOM_PRICE_BY_LETTER_DESC" >

			<option value="0">No</option>

			<option value="1">Yes</option>

		</param>		

    </params>

</install>

</pre>

*You can see somes differences with joomla standard XML files :*

<pre>

<install version="1.5" type="plugin" group="vmcustom" >	

</pre>

inform joomla the plugin is a "vmcustom" plugin(product customfield plugin)

<pre>

    <params addpath="/administrator/components/com_virtuemart/elements">

</pre>

Overide the joomla system by virtuemart 2 to enchance it.

_Always add this or your plugin have chance to not work_

<pre>

        <param type="vmjpluginwarning" />

</pre>

inform that the parameters are saved by virtuemart2 for each plugin variant.

h3. transmited parameters by functions

*$product_id*

is the selected product_id

*$product*

is the selected product

*$param*

 are the plugin parameters

*$productCustom ,$field*

 are the product customfield attributes

*$selected,$row or $idx*

 is the parameter to find or write the right "index/row"

TODO : add more details for parameters

_See texinput plugin for eg._