Building an Addon Module for Interspire Shopping Cart

Written by Mitchell Harper,  Interspire Product Development Manager
Published on 21st Febuary 2008
 

Introduction
 
As I was looking through our newsletter archive, I realized I hadn't sent a coding related newsletter for quite some time. After thinking about it for a few hours, I decided that this week I would show you step-by-step how to write an addon for Interspire Shopping Cart.
 
In Interspire Shopping Cart, addons can be used through the control panel to add functionality to your store. For example, you can purchase and instantly download the Yahoo Search Marketing addon through your store's control panel, which automatically generates combinations of ads for all products in your store which you can upload through your YSM account to advertise on Yahoo.
 
We're going to build a simple addon that generates an RSS feed containing the last 10 orders in our store. I'll explain the addons framework, including naming conventions, required functions, etc. I'll also assume you have an intermediate level of PHP knowledge too, but if you don't it might still be fun to read on anyway.
 
Getting Started
 
The first thing we need to do is create a folder for our addon. The addons folder in Interspire Shopping Cart is where all addons reside. By default, there are no addons, so we'll start by creating a folder called orderrss in our addons folder:
 

 
As you can see, I've mapped z:\ to my Interspire Shopping Cart folder on one of our in-house development servers because I'm developing locally on our network.
 
Now I'll create a file inside the addons\orderrss folder called addon.orderrss.php. Notice that the filename is in the format of addon.[FOLDER NAME].php. This will be the addon's class. All addons must contain a class named using this format.
 
The addon starts by including the addon base class, which is defined in the includes/classes folder:
 
require_once(dirname(__FILE__) . '/../../includes/classes/class.addon.php');
 
Next we declare our class and its inheritance from the STS_ADDON base class:
 
class ADDON_ORDERRSS extends STS_ADDON {
 
Each class has a constructor which must call a few pre-defined functions:
 
/**
* Constructor
* Setup the addon-specific variables through the addon parent class
*
* @return Void
*/
function __construct() {

   // Call all standard addon functions
   $this->SetId('addon_orderrss');
   $this->SetName('Orders RSS Feed');
   $this->LoadLanguageFile();
   $this->SetPermissionId(10002);
   $this->SetLocation('mnuOrders');
   $this->SetIcon('rss_icon.gif');
   $this->SetImage('');
   $this->SetMenuText(GetLang('OrderRSSMenuText'));
   $this->SetMenuDescription(GetLang('OrderRSSMenuDescription'));
}
 
There's a link to download this sample addon at the end of the newsletter, but what we're doing in the constructor is basically telling Interspire Shopping Cart where to position the addon in the control panel menu, and which icon, link text and description it should use. Because this addon calls SetLocation with mnuOrders, it will appear under the orders menu, like this:
 

 
The addons base class calls the init function of every addon. Here's how the init function looks for our addon:
 
/**
* Init
* Initialize any other addon-specific code that needs to run
*
* @return Void
*/
function init() {
  $this->SetHelpText(GetLang('OrderRSSHelpText'));
  $this->_SetVariables();
  $this->ShowSaveAndCancelButtons(false);
  parent::loadaddonvars();
}
 
I won't go into too much detail, but basically we're assigning help text to the addon which will appear when the addon is enabled from the Settings -> Addon Settings page. We're also specifying that the save and cancel buttons shouldn't be shown when configuring this addon, because it has no variables.
 
Enabling the Addon
 
Now that we have the basic framework in place for our addon, we can enable it from the Settings -> Addon Settings page, like so:
 

Once the addon has been enabled, you'll see a separate tab for it. Because our sample addon doesn't have any configuration variables defined, we simply see the help text that has been specified for the addon:
 

Because the addon has been enabled, it will appear in the control panel's menu (see second screenshot above).  Here's how our simple addon will look when we click the menu option:
 

Each addon must define an EntryPoint function, which is called the first time the addons is run. The form shown above is a simple .TPL file that contains HTML. It hooks into Interspire Shopping Cart's template engine and each language variable is represented by a placeholder, such as:
 

 
Each addons has its own language.ini file where the language variables are defined:
 
; [Orders RSS Addon]
OrderRSSMenuText = "Orders RSS Feed"
OrderRSSMenuDescription = "Export an RSS feed containing your last 10 orders."
OrderRSSHelpText = "Export your last 10 orders to an RSS file."
OrderRSSLatest10Orders = "Latest 10 Orders RSS Feed"
...
 
The form submits to the following URL:
 
index.php?ToDo=runAddon&addon=addon_orderrss&func=BuildRSS
 
The runAddon value tells Interspire Shopping Cart that we're running an addon. The addon attribute specifies the ID of the addon, and the func attribute tells the addons framework which function in the addon to call, which in this case is BuildRSS.
 
The BuildRSS function will get the latest 10 orders from the system. In our example addon we can choose between all orders and only shipped orders. Interspire Shopping Cart runs off a PHP-based API, so it's easy to search and filter the orders we need for our RSS feed, as shown below:
 
/**
* BuildRSS
* Create the RSS feed for our sample addon
*
* @return String The RSS feed's XML
*/
function BuildRSS() {
require_once(dirname(__FILE__) . "/../../admin/includes/classes/class.orders.php");
$orders = new STS_ORDER();
$num = 0;
$xml = "<" . "?xml version=\"1.0\" encoding=\"UTF-8\"" . "?>\n";

// Specify that we only want shipped orders if that option is selected
if($_POST["order_status"] == 1) {
$_GET["orderStatus"] = 2;
}

$order_list = $orders->_GetOrderList(0, "orderid", "asc", $num, true);

while($row = $GLOBALS["STS_CLASS_DB"]->Fetch($order_list)) {
$xml .= "<order>\n";
$xml .= sprintf("\t<orderid>%d</orderid>\n", $row["orderid"]);
$xml .= sprintf("\t<amount>%s</amount>\n", FormatPrice($row["ordtotalamount"]));
$xml .= sprintf("\t<customer>%s</customer>\n", $row["ordbillfullname"]);
$xml .= sprintf("\t<date>%s</date>\n", date("jS F Y h:iA", $row["orddate"]));
$xml .= "</order>\n";
}

ob_end_clean();
header("Content-type: text/xml");
echo $xml;
die();
}
 
As you can see, it only takes a few lines of code to hook into the order system and retrieve the latest orders. We then output them as XML to the browser. Here's how the XML file appears in the browser:
 

You could then of course easily integrate the orders RSS feed into an accounting package, ERP system, etc.

You can download all files for this addon here.
 
Conclusion
 
If you're a developer, this newsletter should've given you a little bit of an insight into the internal workings of Interspire Shopping Cart. We'll be releasing a large amount of code-related documentation before the final release in a few weeks.

You can purchase the Beta version of Interspire Shopping Cart right now for up to 50% of what the final release prices will be when it comes out in a few weeks, or you can learn more about Interspire Shoping Cart.
 
See our blog for more information, or feel free to call us on 1800 939 5570 (US) or +612 9555-5570 (AUS) with any questions you might have.
 
 
Thanks,


... and of course you can read more articles online