Shipper Plugins¶

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

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

Here's a short overview of the events:

• When a shopper selects a shipper, plgOnSelectShipper() is fired. It displays the shipper and can be used for collecting extra - shipper specific - info.
• After selecting, plgVmShipperSelected() can be used to store extra shipper info in the cart. The selected shipper ID will be stored in the cart by the checkout process before this method is fired.
• plgOnConfirmShipper() is fired when the order is confirmed and stored to the database. It is called before the rest of the order or stored, when reimplemented, it must include a call to parent::plgOnConfirmShipper() (or execute the same steps to put all data in the cart)

When a stored order is displayed in the backend, the following events are used:

• plgVmOnShowOrderShipperBE() displays specific data about (a) shipment(s) (NOTE: this plugin is OUTSIDE any form!)
• plgVmOnShowOrderLineShipperBE()) can be used to show information about a single orderline, e.g. display a package code at line level when more packages are shipped.
• *plgVmOnEditOrderLineShipperBE() can be used add a package code for an order line when more packages are shipped.
• plgVmOnUpdateOrderShipperBE() is fired inside a form. It can be used to add shipper data, like package code.
• plgVmOnSaveOrderShipperBE() is fired from the backend after the order has been saved. If one of the show methods above have to option to add or edit info, this method must be used to save the data.
• plgVmOnUpdateOrderLine() is fired from the backend after an order line has been saved. This method must be reimplemented if plgVmOnEditOrderLineShipperBE() is used.
• plgVmOnShipperSelectedCalculatePrice() is fired before the order is saved, and used to calculate the cart prices.
• plgVmOnConfirmedOrderStoreShipperData() This event is fired after the order has been stored; it gets the shipping method specific data.

The frontend 1 show method:

• plgVmOnShowOrderShipperFE() collects and displays specific data about (a) shipment(s)

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

• plgVmOnSelectShipper() - This event is fired during the checkout process. It allows the shopper to select one of the available shippers.
  It should display a radio button (name: shipper_id) to select the shipper. In the description, the shipping cost can also be displayed, based on the total order weight and the shipto country (this wil be calculated again during order confirmation)
  Return:
  HTML code to display the form
  Parameters:
1. (VirtueMartCart object) Cart object
2. (integer, default 0) ID of the currently shipper selected

• plgVmOnShipperSelected() - This event is fired after the shipping method has been selected. It can be used to store additional shipper info in the cart.
  Return:
  True on succes, false on failures, null when this plugin was not selected.
  On errors, JError::raiseWarning (or JError::raiseError) must be used to set a message.
  Parameters:
1. (VirtueMartCart object) Cart object
2. (integer, default 0) ID of the shipper selected

• plgVmOnShipperSelectedCalculatePrice() - This event is fired before the order is saved, and used to calculate the cart prices.
  Return:
  True on success, false on failures, null when this plugin was not selected.
  On errors, JError::raiseWarning (or JError::raiseError) must be used to set a message.
  Parameters:
1. (VirtueMartCart object) Cart object
2. (array ) Shipping array containing: shipping_name, shipping_value, shipping_rate_vat_id

• plgVmOnConfirmShipper() - This event is fired after the payment has been processed; it selects the actual shipping rate and/or order weight, and optionally writes extra info to the database (in which case this method must be reimplemented).
  Reimplementation is not required, but when done, the following check MUST be made:
  

  if (!$this->selectedThisShipper($this->_selement, $_cart->shipper_id)) {
      return null;
  }

  
  Return:
  The shipping rate ID
  Do not return parent::plgVmOnConfirmShipper($_cart); it is valid but will produce extra overhead!
  Parameters:
1. (VirtueMartCart object) Cart object

• plgVmOnConfirmedOrderStoreShipperData() This event is fired after the order has been stored; it gets the shipping method specific data.
  +Return:+mixed Null when this method was not selected, otherwise true
  #(integer) The order_id being processed
  #(object) the cart
  #array Price information for this order

• plgVmOnShowOrderShipperBE() - This method is fired when showing the order details in the backend. It displays the shipper-specific data.
  NOTE, this plugin should NOT be used to display form fields, since it's called outside a form! Use *plgVmOnUpdateOrderBE()( instead!
  Return:
  Null for shippers that aren't active, text (HTML) otherwise
  Parameters:
1. (integer) The order ID
2. (integer) Vendor ID
3. (object) Object with 2 properties 'carrier' and 'name'

• plgVmOnEditOrderLineShipperBE() - This method is fired when editing the order line details in the backend. It can be used to add line specific package codes
  Return:
  Null for shippers that aren't active, text (HTML) otherwise
  Parameters:
1. (integer) The order ID
2. (integer) The order Line ID

• plgVmOnUpdateOrderShipper() - Save updated order data to the shipper specific table
  Return:
  True on success, false on failures (the rest of the save-process will be skipped!), or null when this shipper is not actived.
  Parameters:
1. (array) Form data

• plgVmOnUpdateOrderLineShipper() - Save updated orderline data to the shipper specific table
  Return:
  True on success, false on failures (the rest of the save-process will be skipped!), or null when this shipper is not actived.
  Parameters:
1. (array) Form data

• plgVmOnShowOrderShipperFE() - This method is fired when showing the order details in the frontend. It displays the shipper-specific data.
  Return:
  Null for shippers that aren't active, text (HTML) otherwise
  Parameters:
1. (integer) The order ID

• plgVmOnShowOrderLineShipperFE() - This method is fired when showing the order details in the frontend, for every orderline. It can be used to display line specific package codes, e.g. with a link to external tracking and tracing systems
  Return:
  Null for shippers that aren't active, text (HTML) otherwise
  Parameters:
1. (integer) The order ID
2. (integer) The order LineID

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_shipper_'.$this->_selement);
  $_schemeCols = array(
       'id' => array (
               'type' => 'int'
              ,'length' => 11
              ,'auto_inc' => true
              ,'null' => false
      )
      ,'order_id' => array (
               'type' => 'int'
              ,'length' => 11
              ,'null' => false
      )
      ,'shipper_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();
  

• getThisShipperName() - Get the name of the shipper
  Return:
  Shipper name
  Parameters:
1. (integer) The Shipper ID
   final protected function ($_sid)

• writeShipperData() - This method writes all shipper plugin specific data to the plugin's table
  Parameters:
1. (array) Indexed array in the format 'column_name' => 'value'
2. (string) Table name

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

• getShippingRate() - Get the total price for a shipping rate
  Return:
  Price in display format
  Parameters:
1. (integer) Shipping rate ID

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

• selectShippingRate() - Select the shipping rate ID, based on the selected shipper in combination with the shipto address (country and zipcode) and the total order weight.
  Return:
  Shipping rate ID, -1 when no match is found. Only 1 selected ID will be returned; if more ID's match, the cheapest will be selected.
  Parameters:
1. (VirtueMartCart object) Cart object
2. (integer, default 0) Shipper ID, by default taken from the cart

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

• getOrderWeight() - Get the total weight for the order, based on which the proper shipping rate can be selected.
  Return:
  Total weight for the order
  Parameters:
1. (VirtueMartCart object) Cart object

• getShippers() - Fill an array with all shippers found with this plugin for the current vendor
  Return:
  True when shipper(s) was (were) found for this vendor, false otherwise
  Parameters:
1. (integer) The vendor ID taken from the cart.

• validateVendor() - Check if this shipper has carriers for the current vendor.
  Return:
  True when a shipper_id was found for this vendor, false otherwise
  Parameters:
1. (integer) The vendor ID taken from the cart.

• getShippingHtml - returns the HTML code to display the form, based on the $shipper_name, $shipper_id, $selectedShipper, $shipper_logo, $shipping_value, $tax_id, $currency_id. To be used by the function plgVmOnSelectShipper().
  Return:
  returns HTML code to display the form
  Parameters:
1. (string) shipper_name
2. (integer) shipper_id
3. (integer) selectedShipper id
4. (string) shipper_logo to be displayed
5. (integer) shipping_value to use to calculate the SalesPriceShipping
6. (integer) tax_id to use to calculate the SalesPriceShipping

• calculateSalesPriceShipping() - Returns the 'salesPriceShipping' for a given shipping value, tax id, and currency id.
  Return:
  returns salesPriceShipping
  Parameters:
1. (integer) shipping_value
2. (integer) tax_id
3. (integer) currency_id

• getShipperLogo() - Returns the shipper logo image html.
  Return:
  returns the html code to display the image
  Parameters:
1. (string) logo image name
2. (string) alt text to the image

Back to Plugin system