What shipping modules do

Shipping modules are used to define the handling of the order, before it goes through the payment method section of the order process. They take the order itself and decide how to go about charging and delivering it to the customer. Magento takes the order through each shipping module that is installed and active in the system. Each shipping module is then able to process the order currently in the cart and present any available options to the user, from what it sees in the order.

For example: we have a shipping module in our system that provides free delivery to people located within the UK and ordering over £40. Let’s presume that we are ordering £50 worth of goods and are located within the UK. When the order is sent through this module, it checks whether or not the user is in the UK and the order total is over £40. If these conditions are met, (which our order does), then we are presented with a free delivery option, among others, to choose during our order process.

This is a very simple version of what a shipping module can do. The full range of what can be done using shipping modules can be grasped by looking at Shipping Modules on Magento Connect and finding what it has on offer. Here’s a small range of what has been made public:

• Royal Mail UK, EU, and Worldwide Shipping module — For calculation and handling of all of Royal Mail’s shipping methods using weight and distance. This module sends key product information to Royal Mail via their API, authenticating with information that the Magento store administrator has input, and outputs pricing for various shipping options on the current order.
• Regional Free Shipping module — Gives the Magento administrator the option to allow free shipping by region, instead of by country. This provides a choice to the store administrator of breaking down free shipping further than country. For example, this would be good for someone who runs a store based in Nottingham that wants to reward local customers in the East Midlands, as opposed to simply giving free shipping to the entire United Kingdom.
• Basic Store Pickup Shipping module — Enables customers to choose between picking up the item themselves and having it delivered to them. This is advantageous for companies which use Magento and have a physical store presence with stock held.

Magento Connect can be accessed at the following URL:http://www.magentocommerce.com/magento-connect.

The three core types of shipping module can be summarized in the following:

• Third-party API and/or web service integration. For integration with existing couriers that have web-based APIs or web services that offer the same for organization of your shipping. Many existing services make an API available to us for integrating into Magento. We should check Magento Connect for any existing modules that others have created.
• Using customer data to provide unique calculations and opportunities to certain users. Anything that the customer puts in it while checking out can be used for this type of module.
• Shipping methods that involve a physical store or location for additional options that compliment others. We could theoretically build up a set of stores under the Magento store company’s business. We could then link them up with local computers at the locations and use the shipping module to check for stocks at each location. We should do that before suggesting the store as a location for the user to be able to pick up the item.

How to begin with a shipping module

• Here we’ll be learning about how to begin with a shipping module. This is the skeletal structure of a shipping module that we can use as a template for any shipping module which we create. We will also be using it to create a very basic shipping module at the end of this article.
• For the purpose of following this tutorial, we will be creating all files in /app/code/local/MagentoBook/ShippingModule/ , which will be the base directory for all files created (from this point onwards). We must make sure that this directory and sub-directory are set up before continuing onwards. This means that if the file is declared to be /hello/world.php, we place this on the end of our initial base address and it becomes /app/code/local/MagentoBook/ShippingModule/hello/world.php
• Please start by creating the directory MagentoBook in /app/code/local/ and a sub-directory within that called ShippingModule, creating the directory structure /MagentoBook/ShippingModule/.

The configuration files

We create /app/code/local/MagentoBook/ShippingModule/etc/config.xml in our module’s folder. Here, we’ll place the following code which will declare our new module for use, make it depend on Mage_Shipping being enabled, set it at version 0.1.0 and allow it to use the existing global database connection which is set up for our store.

<?xml version="1.0"?>
<config>
 <modules>
 <MagentoBook_ShippingModule>
 <version>0.1.0</version>
 <depends>
 <Mage_Shipping />
 </depends>
 </MagentoBook_ShippingModule> 
 </modules>

 <global>
 <models>
 <shippingmodule>
 <class>MagentoBook_ShippingModule_Model</class>
 </shippingmodule>
 </models>
 
 <resources>
 <shippingmodule_setup>
 <setup>
 <module>MagentoBook_ShippingModule</module>
 </setup>
 <connection>
 <use>core_setup</use>
 </connection>
 </shippingmodule_setup>
 </resources>
 </global>
 <default>
 <carriers>
 <shippingmodule>
 <model>MagentoBook/carrier_ShippingModule</model>
 </shippingmodule>
 </carriers>
 </default>
</config>

Let’s walk back through this code and go over what each individual section does.

We start by defining our XML header tag for the file, to ensure that it is accepted as an XML file when read by the XML parsing class in the system.

<?xml version="1.0"?>

We define the <config> tag, to ensure that everything within it is read as configuration variables to be loaded into Magento’s configuration for whatever we define internally within this tag.

<config>

We define the <modules> tag, so that we’re setting configuration variables for modules defined within this tag.

<modules>
 <MagentoBook_ShippingModule>

We set the module’s version number to 0.1.0, to supply Magento with versioning for the module in the future, if we update and need to perform statements within the update portion of the module, so as to execute above a certain version number.

<version>0.1.0</version>

We have to make sure that our module cannot be activated, or possibly run, without the Mage_Shipping core shipping handler and module activated. This is vital because the module being a shipping module is simply going to cause fatal errors without the parent Mage_Shipping module providing the helper functions needed internally.

<depends>
 <Mage_Shipping />
</depends>

Next, we close off our module declaration tag and modules tag.

 </MagentoBook_ShippingModule>
</modules>

We set up our <global> tag to define global assets to Magento.

<global>

Next, we define the <models> tag to define global models to the system and for setting up our module’s default model to be one of those global models which is automatically loaded.

<models>
 <shippingmodule>
 <class>MagentoBook_ShippingModule_Model</class>
 </shippingmodule>
</models>

Next, we define the <resources>tag, so that we can configure the database resources available to the module within the system.

<resources>

Defining the <resources> tag allows us to include a setup file with our module that accesses the database. This helps if we need to load in any variables (such as default table rate rules) for our module, or for loading additional data required locally by the module, when calculating the shipping rates.

<shippingmodule_setup>
 <setup>
 <module>MagentoBook_ShippingModule</module>
 </setup>

Here, we’ll use the core database connection (the default one), and ensure that we do not overwrite the database connection set up for this particular module.

<connection>
 <use>core_setup</use>
 </connection>

We close off all tag pairs, besides <config>, that have been opened at this point.

 </shippingmodule_setup>
 </resources>
</global>

Finally, we end the configuration file with a declaration that our module is a shipping module and should be processed as one, within the system. This will register the module to the system, so that it can actually display shipping methods to the user on checkout. Without this, nothing will be returned to the user from this module.

<default>
 <carriers>
 <shippingmodule>
 <model>MagentoBook/carrier_ShippingModule</model>
 </shippingmodule>
 </carriers>
</default>

We close the <config> tag to end the XML configuration file.

</config>

After we’ve done this, we need to declare our module to Magento by creating a configuration file in /app/etc/modules/MagentoBook_ShippingModule.xml.

Next, we place the following code in our new configuration file, to allow this module to interact with Magento and be turned on/off under the System Configuration menu:

<?xml version="1.0"?>
<config>
 <modules>
 <MagentoBook_ShippingModule>
 <active>true</active>
 <codePool>local</codePool>
 </MagentoBook_ShippingModule>
 </modules>
</config>

We break this file down into the individual lines:

<?xml version="1.0"?>

The <config> wrapper tag defines the XML to be read, as a configuration of something inside Magento.

<config>

The <modules> wrapping tag defines this as a module to Magento.

<modules>

The next tag is used for defining that this is the configuration of a module entitled <MagentoBook_ShippingModule> and for applying the settings inside the tag to the module:

<MagentoBook_ShippingModule>

We make sure that it’s active by default (this will be overwritten when activated/deactivated in the Magento administrative back-end).

<active>true</active>

The <code pool> tag is used for keeping this module in our local module’s directory.

<codePool>local</codePool>

Closing tags are for closing the XML tags that we started the <config> tag with.

 </MagentoBook_ShippingModule>
 </modules>
</config>

Now that we have the configuration set up, to allow the module to be managed within Magento and versioning control to allow for upgrades in the future, we can progress onto the module itself. It also means that we can now turn our module on/off within the administration. To do this, we go to System|Configuration , then to Advanced under the Advanced heading on the left-hand side. Once here, we will be presented Enable/Disable dropdowns for each module installed in the system.

We’ll set the dropdown for our module to Disable until we have completed the adaptor model and administration setup. This will prevent the module from crashing the system, while it is incomplete. We will re-activate the module once we’re ready to see the output.