RO CSVI

Writing a rule plugin

Rule plugins are a powerful new tool in CSV Improved because it allows us with surgical precision to tailor the import and export process. Out of the box CSV Improved comes with 4 such plugins:

  • Combine
    This adds the option to combine fields
  • Copy
    This adds the option to copy the content of one field to other fields
  • Margin
    This adds the option to recalculate prices
  • Replace
    This adds the option to replace values in a field

These four plugins are useful but not always what you are looking for as you may need something specific. That is why CSV Improved can be extended by writing your own plugins.

Structure of a rule plugin

A CSVI rule plugin is actually a regular Joomla plugin of the type csvirules. A plugin consists of these files:

  • foo.php
  • form_foo.xml
  • foo.xml

The main file

The main file is foo.php, this file contains all the code that does all the work. This is a class that is created like this:

class PlgCsvirulesFoo extends RantaiPluginDispatcher

A rule plugin must always extend the RantaiPluginDispatcher as this dispatcher calls the plugin.

The class contains several mandatory functions and variables:

  • private $id = 'csvifoo';
  • public function getName() {}
  • public function getSingleName($plugin) {}
  • public function getForm($plugin, $options=array()) {}
  • public function runRule($plugin, $settings, $field, CsviHelperFields $fields) {}
$id

This is the unique ID of your rule.

getName()

The getName() function provides CSVI with the name and ID of your rule, this is shown in the dropdown of available rules when creating a new template field.

getSingleName()

The getSingleName() function provides CSVI with only the name of your rule. This is used for display purposes.

getForm()

The getForm() function provides CSVI with a form the user can fill in if your rule requires certain settings. For example a field that allows the user to set which fields should be affected, or a field with values that needs to be matched. It can be almost anything. This function relies on the existence of the form_foo.xml file.

runRule()

The runRule() function does the actual work, this is where the magic happens. In this function you put all the logic of your rule and update the fields with their new values.

The form file

The form file is form_foo.php. This file is optional and only needed if you want to get input from the user. The fields used are standard JForm fields so you can use any field available in Joomla. The structure of the file looks like this:

<?xml version="1.0" encoding="utf-8"?>
<form>
 <fields name="pluginform">
 <fieldset name="foo">
 <field name="source"
 type="textarea"
 rows="5"
 required="true"
 class="input-xxlarge"
 filter="raw" />
 </fieldset>
 </fields>
</form>

 The only requirement is that the fieldset name matches the name of your rule, in this case foo.

Running your code

The runRule() function is the heart of your rule, without it, nothing is going to happen. Here are some pointers to help you understand what is going on in runRule(). The function takes 4 arguments:

  1. $plugin
  2. $settings
  3. $field
  4. $fields

$plugin

This is the ID of the plugin being called. So you need to check if it is your name being called, if not, do not run your code.

$settings

This is an object with data saved by the user from the form provided by your rule.

$field

The current field being processed.

$fields

An instance of CsviHelperFields. This is the class to use to manipulate the fields because it contains all the fields.

There are 2 ways in which you can modify a field that is being imported:

  • $fields->updateField()
    This function is the same for both import and export
  • $fields->set()
    This function takes different arguments depending on whether it is an import or export. The updateField() is the preferred method of modifying a field.

Identifying a field

Fields are always identified by the value in the xml_node variable. This variable contains the unique identifier for that field. One word of caution, when dealing with XML files that have duplicate nodes, this field may contain a value that is the same for multiple fields.

Installation XML

To be able to install a plugin in Joomla, an XML file is required. This is a regular Joomla XML file, just make sure the group is set to csvirules as shown here:

<extension version="3.3" type="plugin" group="csvirules" method="upgrade">

Language files

In case you want to make your rule plugin multi-lingual you can include language files as per the Joomla standard.

Examples

If you want to check out some examples, have a look at the rule plugins that come with CSV Improved, they contain all kinds of ways of handling the fields.