The Interspire Shopping Cart Modules Documentation is an introduction to Interspire Shopping Cart modules, their structure and how they work. This guide, and module development requires knowledge of PHP.

Interspire Shopping Cart 3.5 Required
This documentation has been written for the upcoming release of Interspire Shopping Cart 3.5. There are numerous changes between Interspire Shopping Cart 3.5 and earlier releases for modules.

Contents

  1. Introduction
  2. Types of Modules
  3. Module Structure
  4. Module Creation

Introduction

Interspire Shopping Cart contains a modular structure that allows you to interface with new payment providers and gateways, build in new shipping methods, add support for additional analytics, order notification methods and currency exchange rate services as well as provide extra functionality in the control panel via a built in addons system.

This guide serves as a primer and an introduction in creating modules for Interspire Shopping Cart.

Types of Modules

The different types of modules that can be written for Interspire Shopping Cart are as follows:

  • Checkout Modules (Documentation)
    Checkout modules allow additional payment methods and gateways to be integrated in to Interspire Shopping Cart.
  • Shipping Modules (Documentation)
    Shipping modules allow support for additional shipping methods to be integrated in to Interspire Shopping Cart.
  • Analytics Modules (Documentation)
    Analytics modules allow integration with third party analytics and visitor tracking packages. Analytics modules output tracking code throughout the store.
  • Notification Modules (Documentation)
    Notification modules allow real-time notifications of new orders to be sent to the store administrator.
  • Currency Exchange Rate Modules (Documentation)
    Currency exchange rate modules allow for additional services that provide currency exchange rate updates to be tied in to the currency system.
  • Addon Modules (Documentation)
    Addon modules allow extra functionality and pages to be implemented in to the Interspire Shopping Cart control panel.

Documentation on each of the specific types of Interspire Shopping Cart modules can also be found on the Interspire Developer Network.

Module Structure

Interspire Shopping Cart modules are located within the /modules/ directory of your store. Inside this directory are several subdirectories relating to the type of modules that are contained within them:

  • checkout – Checkout modules
  • shipping – Shipping modules
  • analytics – Analytics modules
  • notification – Notification modules
  • currency – Currency exchange rate modules

Addon modules are the only exception and are located in the /addons/ directory of your store.

Within each of the module types directories exists a directory for each of the modules for that specific type. The name of the directory must match the module ID as outlined below.

  • images – Contains any images specific to this module (logos, etc)
  • lang – Contains language files that this module supports
    • en – Contains the English language files for this module
      • language.ini – Contains the master English language file for this module
  • templates – (Used only by shipping quotes) Any templates that this module makes use of
  • module.[id].php – The primary file for this module. [id] must match the name of the directory and the ID of the module within this file

Module Creation

Module Class

Each module contains a primary PHP class that performs all of the main actions for this particular module. The class is also the primary entry point for modules in to existing Interspire Shopping Cart features.

The module class must have a file name of module.[id].php. Where [id], is the name of the directory that the module exists in and a unique identifier for this module. This module ID is also referenced in the class name of the module.

The basic definition of a module class is as follows:

class [MODULE TYPE]_[MODULE ID]
{

	public function __construct()
	{
		parent::__construct();
	…
	}
}

Module Information

Each module also has it’s own set of information properties such as the ID, the module name, description, image and help text. These properties should be set for each module in a __construct method. (as documented below)

Module Name
The name of a module is the name that will be displayed throughout Interspire Shopping Cart when this module is being enabled/disabled or configured.

To set the name of a module, $this->SetName() should be called as follows:

$this->SetName('Example Checkout Provider');

Module Description
The description of a module is a brief overview of the functionality this module provides or is a list of instructions that need to be manually performed (such as configuring a PayPal account for usage with Interspire Shopping Cart) that is shown when changing the settings of a module in the control panel.

To set the description of a module, $this->SetDescription() should be called as follows:

$this->SetDescription('To integrate the example checkout provider in to your store follow the simple steps below: ….');

Module Help Text (Addons Only)
If an addon has a text/html based overview of the functionality that provides, that should be shown when changing the settings for the addon in the control panel, it should be set using this method. The help text will be shown with a highlighted background with a small icon to the left of it.

To set the help text of a module, $this->SetHepText() should be called as follows:

$this->SetHelpText('The Google AdWords addon can automatically generate a list of Google AdWords ads for every product in your store.');

Module Image
If a module has a logo or icon that should represent it (and in the case of addons, shown on the addon listing page) this module should specify the path to the image (relative to the directory that the module is in) that should be shown. Module images are shown when changing the settings of a particular module.

To set the image for a module, $this->SetImage() should be called as follows:

$this->SetImage('logo.gif'); // logo.gif would then be placed within the directory of this module.

Module Constructor

Each module has it’s own constructor function that is executed whenever that module is loaded. In most circumstances, this function will just set up language variables (calls to GetLang()) for most of the above mentioned module properties but in some circumstances the author may want to perform additional routines when the module is instantiated.

If a module has it’s own constructor (__construct method), it must also call the parent class constructor method (parent::construct()) to ensure proper instantiation of the entire module. An example constructor is shown below.

public function __construct()
{
	parent::__construct();
	$this->_name = GetLang('TestModule');
	$this->_description = GetLang('TestModuleDesc');
}

Configurable Module Settings

Each module can have it’s own set of configuration variables which are user-changeable via the Interspire Shopping Cart control panel in the corresponding location. Examples of configuration variables are the PayPal address used by the PayPal checkout modules that payments should be sent to, and lists of accepted delivery methods for the UPS shipping module.

The list of configurable module settings is defined in a callback function, SetCustomVars in each module class. The module settings are defined as an array within the _variables property of each module. Each item in the array contains another array with the various options for this setting.

For example:

public function SetCustomVars()
{
	$this->_variables['displayname'] = array(
		'name			=> 'Display Name',
		'type'		=> 'textbox',
		'help'		=> 'Enter the display name for this module.',
		'default'		=> $this->GetName(),
		'savedvalue'	=> array(),
		'required'		=> true
);
}

The supported options for each setting is as follows:

  • name
    Defines the display name for this setting to be shown on the properties page.
  • type
    The type of configurable option that this setting is. A list of supported types can be found below.
  • help
    The help text to be shown in the help tip for this setting.
  • default
    The value that this setting should default to if it has not yet been configured.
  • required
    Boolean value. If set to true, this setting requires a choice to be made/value to be entered.
  • options
    If this setting is a select box or radio button list, an array of available options for selection.
  • multiselect
    If this setting is a select box and multiple selections are allowed, this variable should be set to true.
  • size
    If a select box, the size of the select box that should be shown. Defaults to 5 if not specified.
  • callback
    If the type of this setting is set as “custom”, the name of a method in this module class to be called to generate the layout for this setting.
  • javascript
    If the type of this setting is set as “custom”, any custom Javascript validation that should be run for this setting.

Numerous types of settings are supported such as text boxes, check boxes and drop down select boxes. The following is a full list of supported setting types:

  • blank
  • label
    A label (no form control) should be created with the value specified in the “default” setting option.
  • custom
    This setting should be drawn using a custom callback method. For settings of this type, the “callback” item must be supplied for this setting and must be the name of a valid method within the module. The callback should return the HTML necessary to draw the setting.
  • textbox
    A textbox should be created for this setting type. The value specified in “default” will be used if this setting does not have a value, otherwise, the value will be prefilled with what’s been stored for this module.
  • dropdown
    This setting should be a drop down menu (select box). The list of options for the select box should be supplied as the “options” item for this setting. Each option should be in key/value pairs with the key being the text to be displayed and the value being the value to store in the database for this setting. Set “multiselect” to true to allow multiple selections.
  • password
    A password textbox should be created for this setting type. The value specified in “default” will be used if this setting does not have a value, otherwise, the value will be prefilled with what’s been stored for this module.

Accessing Module Variables

To access the value of a module variable from within a module itself, $this->GetValue() should be called. This function takes a single argument , the name of the variable to fetch and will return a mixed data type (string or array depending on the variable type) containing the value. Example:

$emailAddress = $this->GetValue('email');

This would retrieve a variable for this module called 'email' from the module variables data store.

Generic Callbacks

IsSupported

Returns: Boolean. False if this module cannot be enabled because it isn’t supported or true if this module can be enabled.
The IsSupported method checks if a module can be enabled on this server based on the module’s requirements. If this method is not implemented, it is assumed that the module is supported and can be enabled.

This method should return false if a module is not supported based on the supplied requirements. For each of the requirements that are not met, $this->SetError() should be called with an appropriate message as to why this module cannot be enabled. This message will be shown to the user. An example callback is below.

function IsSupported()
{
	if(!function_exists("mcrypt_encrypt")) {
		$this->SetError(GetLang('CCManualErrorNoMCrypt'));
	}
	else if(!GetConfig('UseSSL')) {
		$this->SetError(GetLang('CCManualNoSSLError'));
	}

	if(!$this->HasErrors()) {
		return false;
	}
	else {
		return true;
	}
}