Custom Fields With Virtuemart 2. Simple Custom Fields. Creating a Custom Field Type

Transcription

1 Customization in Virtuemart 2 Custom Fields With Virtuemart 2 Custom Plugin Fields in Virtuemart 2 Part 1. Installing and Using Custom Plugin Fields Custom Plugin Fields in Virtuemart 2 Part 2. Programming Custom Plugin Fields Custom Fields With Virtuemart 2 Creating a Custom Field Type Creating custom fields with Virtuemart 2 can be (thankfully) quite a lot more straightforward than with previous versions. But there are also far more options available with custom fields, including the scope for creating specialist plugin fields. The disadvantage is that there is no longer any support for 'product types', which could be a useful feature of Virtuemart 1.1x, however the option for creating custom plugins may offer more flexibility as developers produce applications in the future. We will discuss plugin fields in more depth in a later article, for now we will look at simpler usage of custom fields. Simple Custom Fields Firstly, we will consider the process of creating a simple custom field to convey extra information about the product, such as the age group it is aimed at. Our age group field will be displayed on the product page to give shoppers that information in a standard format. To do this, in your Virtuemart admin, you go to products->custom fields, and click the 'new' button. You will first need to select the custom field type, the types available are: string, integer, parent, boolean, date, time, image, cart variant, generic cart variant, editor, textarea, plugins. For a simple information field such as 'age group', choosing the 'string' field type will be sufficient. We will discuss some of the complex field types below. Give the field a title ('age group' for example). It helps if the title is meaningful, because this is the field name that will be shown when a custom field is selected for a product. You can leave the rest of the options as they are, although you may find it helpful to add a description and a default value. These will be visible on the product details page as well as in the product admin. 1/16

2 If you are creating a page that will be of use only to administrators you can set the 'hidden' option. For example you can use custom fields to supply additional product information with our GooglebaseXML component, to create a product feed that can be uploaded to Google. You may not necessarily want to display the information on the product page, using a hidden field can allow you to tailor the information you submit to Google without having to display it to customers. Leave the cart attribute option at 'no' for now, we will discuss cart attributes below. Click 'save and close'. You have now created a simple custom field type, you just need to add it to your products. Adding a Custom Field to a Product Go to products->products in your Virtuemart admin, and click on the name of the product in order to open its editor. Click on the 'custom fields' tab. Go down to the box labelled 'custom field type'. Click on the selector, and select the name of the field that you want to add (if you have not created any other fields yet there will only be one name). The new field should now be automatically created. Type in its value in the value box (eg 0 to 4 in our age group example), and click 'save and close'. You have now created a custom field type, and added an instance of the field to a product. You can add the same field type (such as our 'age group' example) to as many products as you wish, you only need to create it once. Creating more complex field types simply involves modifying the above process, such as creating list options. Creating List Options Rather than simply creating the age group field type as a single value that will be added for each product, you might want to specify a list of predefined age groups (0 to 4, 5 to 9, 9 to 14 etc), from which the relevant age group will be selected for a particular product. To do this, you can modify the custom field type. Go to products->custom fields in your Virtuemart admin, and click on the 'age group' field type. Change the 'is a list?' option to 'yes', and change the default value to a list of the possible values, separated by semi-colons, for example '0 to 4; 5 to 9; 9 to 14; 14+'. Click 'save and close'. Now go back to the products list, find your product, open the product details editor, and click on the custom field tab. You will need to delete the existing age group field (click the x button next to it). Now click on the custom field type box and add the field again, as described above in 'adding a custom field to a product'. This time you should see that the value of the field now appears as a drop-down list, from which you can select the value. Cart Attributes So far we have looked at custom fields which are not cart attributes. The distinction is important. Ordinary, non-cart attribute fields will simply appear as extra information on the product page. Cart attribute fields on the other hand will be displayed when the customer views his or her shopping cart, and also near the add to cart button on the product page. They can optionally have a custom price attached to them, providing a way to create a set of selectable options that will cause the final price to vary. 2/16

3 For example, suppose your product comes in three sizes: small, medium and large, and the price varies according to the size. You want the add to cart button to include a selector that allows the customer to choose the preferred size, and display the amended price. First you need to create your size field type. As before, go to products->custom fields, and click the 'new' button. Give the field the title 'size'. This time we need to give the custom field the type 'cart variant'. Set the 'is a cart attribute' and 'is a list' options to 'yes'. Set the default value to 'small;medium;large'. Click 'save and close'. Open your product in the product editor and click on the 'custom fields' tab as before. Now in the custom field type selector box click on 'size' to add the size field. You should see a drop down list of the available sizes in the value column, and a text box in the 'price' column. Select a size value (eg small), and add the appropriate price. Now add another size field using the custom field type selector box, give it a size value (eg medium) and a price. You can do this as for as many times as you have available size options. When you have finished click on the 'save and close' button. Now when the product is viewed by a shopper they should see a drop down list box with the available sizes near to the add to cart button. Selecting a size should result in the product price being updated. Note that the custom price values will be added to the product base price, so you may find it convenient to set the base price equal to the lowest value option, and give that option a custom price of zero. For example, if your prices are 25 for size small, 30 for medium and 40 for the large size, your base price would be 25. You would give the small size a custom price of zero, the medium size a price of 5, and the large size a price of 15. Other Field Types As we saw above, there are many other options available for field types. Some, such as the integer and boolean types allow you to restrict the value of the field to particular data types, such as numbers or yes/no values. Parent fields allow you to group other fields together and add them to products as a group. The most interesting is the 'plugin' field type since this allows for the use of 3rd party extensions to create additional product attributes. Because it is such a large subject area we will discuss plugins separately in a future article. Author Profile 3/16

4 Custom Plugin Fields in Virtuemart 2 Part 1. Installing and Using Custom Plugin Fields In an earlier article we looked at simple custom fields in Virtuemart 2. We will now look at custom plugins. We are dividing this survey into two parts: this part will look at installing and using Virtuemart custom plugin fields, with particular attention to the stockable variants plugin. The second part of the survey, to be published in a separate article, will look at programming custom field plugins in Virtuemart 2, and is mainly aimed at programmers, however others may find it useful as an overview of how custom plugins work. Custom Plugins Custom plugins (also known as product plugins) are used to add extra functionality to the Virtuemart product. There are three custom plugins that are distributed with Virtuemart: the specification plugin, which allows you to create searchable custom specifications for a product; the stockable variants plugin, which allows you to display child products as variants that are selectable in the parent product add-to-cart button; and the text input plugin, which allows the customer to add their own customized text when ordering a product. Using a Custom Plugin Custom plugins, like all Virtuemart plugins, are also Joomla plugins, and to use them you must first upload and install them using the Joomla installer, then enable them in the plugin manager. Then you need to switch to the Virtuemart and go to products->custom fields, then click the 'New' to start creating a new plugin field which you will later attach to your products. 4/16

5 5/16

6 You will see a list of parameters. You need to set the Custom Field Type parameter to 'plugin'. You should then see a select box appear at the bottom of the list labelled 'Select a plugin'. You should see your plugin listed, if not, you have probably forgotten to enable it. Select your plugin type, when you have done so you may now see appear some parameters specific to the plugin - set these as you require. Going back to the top of the parameters list, you should also set a title for the plugin, this is the name of the field that will be displayed in the product editor and on the product page, so make it informative. Whether or not 'Cart Attribute' is set to no or yes will depend on the plugin. Plugins that in some way modify the add-to-cart operation, which is probably most of them, will have this set to yes, but you may need to check the plugin documentation. Remember to set 'Published' to yes. You should leave 'Default' alone, this value may be important to the correct functioning of the plugin, and once you have saved the parameters it should be set automatically to the system name of the plugin. You can leave the other parameters alone for now, though you can add a description if you want. Click 'Save and close' when you are finished. Now you are ready to use the new field with your products. Open up a product in the product editor and click on the 'Custom Fields' tab. Just as with ordinary custom fields you attach a new custom plugin field by selecting it, then setting its options. The difference with plugin fields is that they generally include more complex behaviours. You can attach the custom plugin field to as many products as you require. Example: the Stockable Variants Plugin The stockable variants plugin allows you to treat child products as variants which can be selected in the add-to-cart functions of the parent product. You can achieve a somewhat similar effect with a simple string field type by creating a list, as described in a previous article, so it is worth considering whether you actually need to use the stockable variants plugin, because it is more complicated to set up. However the advantage of the stockable variants plugin is that it does allow you to track stock levels for the child products. Children whose stock level has fallen to zero will not be displayed as options in the cart. Moreover the plugin does allow you to set up complex multi-dimensional attributes for products (such as size and color), and to check stock levels for the combination of attributes, so that only those combinations that are in stock are displayed. Usage Install the plugin as described above, and create a new instance by going to products->custom fields and clicking the 'New' button.. Select 'plug-ins' as the 'Custom Field Type', and in the 'Select a plug-in' box that appears at the bottom, choose 'VM Custom, stockable variants'. You should now see a set of pairs of text boxes for the option names and values. In our example we will look at creating a simple 'Size' attribute, that can take the values small, medium and large, with a child product assigned to each value. So in the first 'Option name' text box, put 'Size'. In the first 'Option values' text box put:- Small Medium Large 6/16

7 with one value per line. There are also some other parameters you must set up, once you have finished with the options. For the other custom field parameters put 'Choose a Size' for the title. Set 'Cart Attribute' to 'yes', and the same for 'published'. Then click 'Save and Close'. Now we are ready to attach the new field to one or more products. Open up a product in the product editor, and click on the 'Custom Fields' tab. From the 'Custom Field Type' select box, select the 'Choose a size' field. Child Products Now you need to create some child products to attach to the available options (small, medium and large). In theory you can do this from the parameters of the custom field, but this process is a bit buggy. It is more reliable to click on 'Save and Close' at this point, and create some child products via the Virtuemart products list. Creating Child Products In the Virtuemart products listing, click the checkbox next to the parent product name, and click the 'Child Product' button. This will open a new product editor for a child product. You can leave most of the information for the product blank, but give it an informative name such as 'Shirt size small', it is also helpful to give it a SKU, and you need to set the number in stock (on the product status tab). You can leave the price at 0, the price will be set through the custom field parameters later. Then save and close. Once you have returned to the product listing you can find the parent product listed, it should have '1 children' in the 'product has children' column. Now you can click on this, which should open a listing for the child products. Again you can click on the 'Child Product' button, and add a child product which will store the stock information for the medium size, do the same for the large size. Attaching the Children to the Product Variants Once you have the 3 children set up, it is time to return to the parent product - you should see the link for this above the child product lists. Re-open the custom field tab. For the 'Choose a size' field you should now see the 3 children listed. All that is required now is to select the size option from the select box which is attached to each product, and set the custom price (additional charge) which will be applied for the option. This will be in addition to the price for the parent product. So if your basic price for the smallest option is 15, 25 for the medium size and 35 for large, you may set this up by setting the price of the parent product to 15. Then the additional charge for the small size will be zero, for the medium size it will be 10, for the large size it will be 20. 7/16

8 You also need to make sure that the 'Parent Variant' box is checked for each option, so that all the options are displayed in the cart. Now save and close the product. If you navigate to the product in the front end of the site you should now see that a select box is displayed next to the add to cart button. As the selected option is changed the displayed price should automatically update. Further Points There is not an easy way to re-order child products, and the options are displayed ordered by the id number of the attached child product, therefore the earliest created is displayed first. So it makes sense to create them in the order that you want to display them, for example the small size first. If you want to change the ordering the only way to do this is to edit the child products themselves, and swap all the information around. For example if you have the medium and small sizes displaying in the wrong order you will need to rename the medium child product to 'small' and vice versa (remembering also the swap the SKU and stock information). Then change the options they are attached to on the parent custom field tab. Not a quick process. Deleting an option is quite easy though, you can just delete the child product. Alternatively you can uncheck the 'Parent Variant' box on the parent custom field tab to keep the child product defined but not have it displayed in the add to cart selection box. Multi-dimensional Options Setting up multi-dimensional options is done through much the same process. For example, imagine instead of just a size option we want customers to be able to choose both size and colour. Then when creating the custom field in addition to our size options we create a second list of options. In the second option name box put colour, and in the second option values box list the possible colours, one per line. 8/16

9 9/16

10 You will need to create a child product with stock levels for each size and colour combination. Now when you open the custom field tab for your parent product and select the size/colour plugin field, you should see select boxes for both the size and colour options. Again it is just a matter of attaching the correct options to each child product and setting any additional charges. When the parent product is viewed in the front end of the site there should be select boxes for both size and colour. 10/16

11 Now the power of product variants should also be apparent, because only those combinations of size and colour which are actually in stock should be selectable. For example suppose your large size is only available in pink, whereas the small and medium are available in white, green or pink. If the customer selects 'large', then only the pink option will be selectable, but if she selects small or medium she will see a choice of white, green or pink. This is not something that can be achieved with a simple custom field. However if you have a lot of size and colour combinations then it can rapidly become very tedious trying to create all the necessary child products by hand. You will probably want to look at creating the child products programmatically, for example by creating them as rows in a CSV spreadsheet and then importing them directly into Virtuemart. There are several extensions listed in the Joomla extensions directory that will do this for you. Then all you will need to do by hand is to attach the children to the options of the stocakble variant plugin, which is quite a quick process. Other Plugins I hope that this has provided a useful overview of using Virtuemart custom plugin fields. I have concentrated on the stockable variants plugin because this is the most difficult to set up, usage for other plugins is very similar, but without the complications involved in setting up child products. You simply define the custom field type in the custom fields manager through the process described above then attach it to a product on the custom fields tab, setting any parameters that are required. Author Profile 11/16

12 Custom Plugin Fields in Virtuemart 2 Part 2. Programming Custom Plugin Fields In part 1 of this survey we looked at how to install and use custom plugin fields in Virtuemart 2. We will now look at programming custom plugins. This article is mainly aimed at programmers, however others may find it useful as an overview of how custom plugins work. This article is not a basic 'how-to' guide for creating a custom plugin, because it assumes that you are already familiar with the basics of creating Joomla plugins. If not, you can find a useful introduction to Joomla plugins on the Joomla documentation site. What we will do is survey the main issues involved in programming a Virtuemart custom plugin. One of the big advances in Virtuemart 2 over its predecessors is its support for a plugin framework. This framework includes potential support for a wide variety of plugin groups - I say 'potential' because some of these groups do not seem to be developed yet. As well as payment and shipping plugin groups, the Virtuemart framework includes currency, coupon, calculation, shopper, extended (to add extra features into the Virtuemart core), and the custom plugin group that we will be discussing. If you want to explore these other plugin groups there are abstract classes defined for all these in the folder administrator/components/com_virtuemart/plugins. To see examples of the custom, payment and shipping plugins you can look at the Virtuemart all-in-one installer component, in the admin/plugins folder, which contains examples of all three groups. There is also some developer documentation available on the Virtuemart site here. Custom Plugins Custom plugins (also known as product plugins) are used to add extra functionality to the Virtuemart product. There are three custom plugins that are distributed with Virtuemart: the specification plugin, which allows you to create searchable custom specifications for a product; the stockable variants plugin, which allows you to display child products as variants that are selectable in the parent product add-to-cart button; and the text input plugin, which allows the customer to add their own customized text when ordering a product. If you want to create your own custom plugin for Virtuemart you will probably find it very helpful to study the code in these three plugins in addition to reading this article. We will also draw some examples from our free download field plugin available here (for free of course). Plugin Basics The first thing to note about Virtuemart 2 plugins is that they are Joomla plugins, meaning that they can be installed using the Joomla installer, and require an xml installation manifest. However this manifest is unusual because for Joomla 1.6+ it uses the Joomla 1.5 <param> tag to define the plugin parameters, rather than 12/16

13 normal the <field> tag. This is because the parameters are set through the Virtuemart admin, not the Joomla plugin manager, so the <field> tag is not required. For this reason you should include the following in your xml manifest: <params addpath="/administrator/components/com_virtuemart/elements"> <param type="vmjpluginwarning" /> </params> This will output a message warning the administrator that parameters should be set through Virtuemart. As with general Joomla plugins, at a minimum the plugin should consist of the xml manifest plugin plus a PHP code file, which should be defined as normal in the manifest. The plugin will belong to the to vmcustom plugin group, so this should also be set in the <extension> tag:- 1 <extension version="2.5" type="plugin" group="vmcustom" method="upgrade"> PHP Code A custom field plugin should extend the vmcustomplugin class, you will need to include this at the start of your plugin php file:- 1 if (!class_exists('vmcustomplugin')) require(jpath_vm_plugins. DS. 'vmcustomplugin.php'); This class defines various methods which we use to create the plugin functionality. Database Tables When a user creates an instance of the plugin field the definition is stored in the virtuemart_customs database table. You will need to define to the plugin parameters that must be stored in the table, through the following code in the constructor: function construct(& $subject, $config) { parent:: construct($subject, $config); $this->_tablepkey = 'id'; $this->tablefields = array_keys($this->gettablesqlfields()); $this->varstopush = array( /* array of parameter definitions here */ ); $this->setconfigparameterable('custom_params',$this->varstopush); } 13/16

14 For example our free download plugin includes the following definition for the parameters: $varstopush = array( 'media_id'=>array(0,'int'), 'requires_registration'=>array(0,'int'), 'shopper_groups'=>array(array(),'array'), 'redirect_url'=>array('','char'), 'title'=>array('','char'), 'description'=>array('','char'), 'loadstylesheet'=>array('','char') ); Each definition is an array consisting of the default value and the parameter type. Data Table Some plugins also require their own data tables, which should be named after the plugin. For example the specification plugin uses a database table called 'virtuemart_product_custom_plg_specification'. In order to use a data table the plugin should include calls to the methods getvmplugincreatetablesql() and gettablesqlfields(), which defines the SQL for the table creation. for example the specification plugin includes the following: public function getvmplugincreatetablesql() { return $this->createtablesql('product Specification Table'); } function gettablesqlfields() { $SQLfields = array( 'id' => 'int(11) unsigned NOT NULL AUTO_INCREMENT', 'virtuemart_product_id' => 'int(11) UNSIGNED DEFAULT NULL', 'virtuemart_custom_id' => 'int(11) UNSIGNED DEFAULT NULL', 'custom_specification_default1' => 'varchar(1024) NOT NULL DEFAULT \'\' ', 'custom_specification_default2' => 'varchar(1024) NOT NULL DEFAULT \'\' ' ); return $SQLfields; } However we found that in order to ensure that the table was actually created we also needed to include the following call in the plugin constructor:- 1 $this->onstoreinstallplugintable($this->_pstype); 14/16

15 Alternatively you can explicitly create the table through running a custom installation script (which is possible with plugins for Joomla 2.5 but not 1.5). Creating the Backend Administration The HTML to generate the parameter form should be returned by the method plgvmonproductedit($field, $product_id, &$row,&$retvalue). This method should define a set of form fields for the parameter input by attaching them to the end of the $retvalue parameter, and return a boolean value of true. I suggest studying the versions of this method in the specification, stockable and textinput plugins for ideas on how to define these. The method output can be complex and include javascript as well as HTML. There are a couple of things to note, firstly you gain access to the current values of the parameters with a call to 1 $this->parsecustomparams($field); The values can then be accessed as properties of the $field object, eg $field->param_name, where param_name is replaced by the actual parameter name. The input fields are defined as a two-dimensional array indexed by $row and the parameter name, eg custom_param['.$row.'][param_name]. There is also a method to generate output when an order for a product is viewed:- 1 function plgvmdisplayinorderbe($item, $row, &$html) This is only relevant if the plugin is defined as a cart attribute (see below), and can be used to display custom information about the order, and even to allow some modification of the order. Frontend Output Depending on whether the plugin custom field type is or is not a cart attribute, there are two methods which are used to generate the front-end output. Only one of these methods will be appropriate for a particular plugin, and it should be made clear to the user whether or not the plugin should be a cart attribute Non-cart Attributes If a plugin is not defined as a cart attribute then it just generates some extra output which is displayed on the product page. It does not affect the add-to-cart operations. An example is our free download field, which simply displays a download link on the product page. In this case the appropriate method to generate the output is:- 1 function plgvmondisplayproductfe($product,&$idx,&$field) 15/16

16 Cart Attributes If a plugin is defined as a cart attribute then in some way it will affect the cart functionality. An example is the stockable variants plugin. In this case the method to generate the output is 1 function plgvmondisplayproductvariantfe($field,&$idx,&$group) In either case the method should include the following code to stop execution when it is not appropriate. 1 if ($field->custom_element!= $this->_name) return ''; As in the backend a call to 1 $this->parsecustomparams($field); will provide access to the parameter values. Other Methods The plugin should also call the following methods to ensure its correct functioning: protected function plgvmonstoreinstallplugintable($pstype) { return $this->onstoreinstallplugintable($pstype); } function plgvmdeclarepluginparamscustom($pstype,$name,$id, &$data){ return $this->declarepluginparams($pstype, $name, $id, $data); } function plgvmsetontablepluginparamscustom($name, $id, &$table){ return $this->setontablepluginparams($name, $id, $table); } function plgvmondisplayedit($virtuemart_custom_id,&$customplugin){ return $this->ondisplayeditbecustom($virtuemart_custom_id,$customplugin); } 16/16