Plugin system¶

Since VirtueMart v2, the Joomla! plugin system is used form payment and shipper plugins.

Installing plugins¶

During development the the VM2 branch, the plugins are not available as Joomla install packages, so for test environments, they must be installed manually.

Payment plugins¶

At the time of writing, only 2 of the former payment plugins have been converted to the new plugin system. Others should follow soon, all help is appreciated!!

Use the SQL query below to add the plugins to your database (assuming the table prefix is "jos_"):

INSERT INTO `jos_plugins` (`id`, `name`, `element`, `folder`, `access`, `ordering`
  , `published`, `iscore`, `client_id`, `checked_out`, `checked_out_time`, `params`)
VALUES
 (NULL, 'VMPayment - Authorize', 'authorize', 'vmpayment', 0, 0, 1, 0, 0, 0, '0000-00-00 00:00:00', '')
,(NULL, 'VMPayment - Cash on delivery', 'cashondel', 'vmpayment', 0, 0, 1, 0, 0, 0, '0000-00-00 00:00:00','')
;

Next, copy the plugin files (authorize.php, authorize.xml, cashondel.php and cashondel.xml), located in the folder /plugins/vmpayment in the SVN checkout, to the Joomla plugin directory. If that doesn't exist, it must be created first:

mkdir <document_root>/plugins/vmpayment

Now, in the store maintenance, you can add payment methods based on one of these plugins. Note at this moment it is required to select a vendor!

Shipper plugins¶

This is very similar to the payment plugins. Only 1 plugin has been created (again: all help is appreciated!); 'standard', which provides a basic shipping option for postal services.
Note: Installing the sample data does NOT provide shipping rates anymore!

Use the SQL query below to add the plugins to your database (assuming the table prefix is "jos_"):

INSERT INTO `jos_plugins` (`id`, `name`, `element`, `folder`, `access`, `ordering`
  , `published`, `iscore`, `client_id`, `checked_out`, `checked_out_time`, `params`)
VALUES
 (NULL, 'VMShipper - Standard', 'standard', 'vmshipper', 0, 0, 1, 0, 0, 0, '0000-00-00 00:00:00', '')
;

Next, copy the plugin files (standard.php and standard.xml), located in the folder /plugins/vmshipper in the SVN checkout, to the Joomla plugin directory. If that doesn't exist, it must be created first:

mkdir <document_root>/plugins/vmshipper

Now use the 'Shipping' menu item in the backend to add 1 or more carriers based on this plugin. All you need to do here is give the shipper a name and select a vendor (this is optional; when no vendor is selected, this carrier is valid for all vendors).
Finally you can add the shipping rates for the created vendor. Make sure a there's always a valid shipping rate: customers select the carrier only and the plugin must be able to find a mathcing rate based on the total order weight and the shipto address!

Plugin Development¶

All plugins for VirtueMart should be developed confirming the Joomla! plugin development methods. Refer to http://docs.joomla.org/Tutorial:Plugins for developers documentation for Joomla! plugins.

Payment Plugins¶

Payment plugins are used both in the front-end and the backend. They must be created as classes deriving from the base class vmPaymentPlugin:

class plgVmPayment<myPlugin> extends vmPaymentPlugin {
    function plgVmPayment<myPlugin>(&$subject, $config) {
        $this->_pelement = basename(__FILE__, '.php');    // Required!
        $this->_createTable();                // Required, see below
        parent::__construct($subject, $config);
    }
}

Below is the list with events and a description on what moment they are fired.

• plgVmOnSelectPayment() - This event is fired during the checkout process. It allows the shopper to select one of the available payment methods.
  It should display a radio button (name: paym_id) to select the payment method. Other information (like credit card info) might be selected as well, depending on the plugin.
  Return:
  It must return the HTML code for displaying the form (radio button and optional extra selections).
  Parameters:
1. (VirtueMartCart object) The cart object
2. (integer, default 0) ID of an already selected payment method ID, if any

• plgVmOnPaymentSelectCheck() - This event is fired after the payment method has been selected. It can be used to store
  additional payment info in the cart.
  Return:
  Plugins that were not selected must return null, otherwise True of False must be returned indicating Success or Failure.
  Parameters:
1. (VirtueMartCart object) The cart object

• plgVmOnCheckoutCheckPaymentData() - This event is fired during the checkout process. It can be used to validate the payment data as entered by the user.
  Return:
  Plugins that were not selected must return null, otherwise True of False must be returned indicating Success or Failure.
  Parameters:
  None

• plgVmOnConfirmedOrderStorePaymentData() - This event is fired after the payment has been processed; it stores the payment method-specific data.
  All plugins must reimplement this method.
  Return:
  If the plugin is NOT actually executed (not the selected payment method), this method must return NULL
  If this plugin IS executed, it MUST return the order status code that the order should get. This triggers the stock updates if required
  Parameters:
1. (integer) The ordernumber being processed
2. (object) Data from the cart
3. (array) Price information for this order

• plgVmOnShowOrderPaymentBE() - This method is fired when showing the order details in the backend. It displays the the payment method-specific data.
  All plugins must reimplement this method.
  Return:
  Null when for payment methods that were not selected, text (HTML) otherwise
  Parameters:
1. (integer) The order ID
2. (integer) Payment method used for this order

• plgVmOnCancelPayment() - This event is fired each time the status of an order is changed to Cancelled. It can be used to refund payments, void authorization etc.
  When reimplementing this methis, the body must start with this code:
  

  $_paymethodID = $this->getPaymentMethodForOrder($_orderID);
  if (!$this->selectedThisMethod($this->_pelement, $_paymethodID)) {
      return;
  }

  
  Parameters:
  (integer The order ID
  (char) Previous order status
  (char) New order status

• plgVmOnShipOrderPayment() - This event is fired when the status of an order is changed to Shipped. It can be used to confirm or capture payments
  When reimplementing this methis, the body must start with this code:
  

  $_paymethodID = $this->getPaymentMethodForOrder($_orderID);
  if (!$this->selectedThisMethod($this->_pelement, $_paymethodID)) {
      return;
  }

  
  Return:
  True on success, False on failure, Null if this plugin was not activated
  Parameters:
1. (integer) Order ID

Other helper functions inherited from the base class:

• createTable() - This method is used to create and maintain the plugin specific database table(s).
  It _must be reimplemented by all plugins.
  Example:
  

  $_scheme = DbScheme::get_instance();
  $_scheme->create_scheme('#__vm_order_payment_'.$this->_pelement);
  $_schemeCols = array(
       'id' => array (
               'type' => 'int'
              ,'length' => 11
              ,'auto_inc' => true
              ,'null' => false
      )
      ,'order_id' => array (
               'type' => 'int'
              ,'length' => 11
              ,'null' => false
      )
      ,'payment_method_id' => array (
               'type' => 'text'
              ,'null' => false
      )
  );
  $_schemeIdx = array(
       'idx_order_payment' => array(
               'columns' => array ('order_id')
              ,'primary' => false
              ,'unique' => false
              ,'type' => null
      )
  );
  $_scheme->define_scheme($_schemeCols);
  $_scheme->define_index($_schemeIdx);
  if (!$_scheme->scheme()) {
      JError::raiseWarning(500, $_scheme->get_db_error());
  }
  $_scheme->reset();
  

• getPaymentMethodForOrder() - Get the order payment ID for a given order number
  Return:
  The payment method ID, or -1 when not found
  Parameters:
1. (integer) The order ID

• getThisMethodName() - Get the name of the payment method.
  This method can not be reimplemented
  Return:
  Paymenent method name
  Parameters:
1. (integer) The payment method ID

• selectedThisMethod() - This method checks if the selected payment method matches the current plugin
  Return:
  True if the calling plugin has the given payment ID, False otherwise.
  Parameters:
1. (string) Element name, taken from the plugin filename
2. (integer) The payment method ID

• writePaymentData() - This method writes all payment plugin specific data to the plugin's table
  Return:
  True if the calling plugin has the given payment ID, False otherwise.
  Parameters:
1. (array) Indexed array in the format 'column_name' => 'value'
2. (string) Table name