Developing a custom magento module

It’s been some time since I wrote my last post as I have been busy working on numerous projects. Today I am going to discuss and step by step explain how to develop a custom magento module. Most of the tutorials, blog posts & articles that I found online explaining a custom magento module development were the “Hello World” examples, that may show you the basics but aren’t that helpful really. In this step by step tutorial we are going to cover the following points and actually develop a custom magento module that integrates SMSGupShup sms gateway to send sms text messages to the customers depending on different events.

At the end of this tutorial we will be able to:

  • Send SMS messages to our customers on the following events using SMSGupShup Gateway
    • Welcome SMS on customer registration
    • Thankyou SMS on placing an order
    • Shipment ID & Information on shipment sent
  • Enable / Disable the module from the configuration
  • Enable / Disable sending SMS for any of the aforementioned events
  • Use custom SMS templates for the aforementioned events
  • Use variables in SMS templates
  • Have all of the above configurable via a configuration menu in the admin

As this tutorial is going to be pretty extensive, Let’s Break it down into 2 parts:

  1. Implement Customization Options
  2. Using Customization Options

So without any further ado, let’s get our hands dirty

Custom Magento Module Development: Part 1: Implementing Customization Options

In magento, There are 3 code-pools that you can put your code into:

  1. Core – Used for magento’s core modules
  2. Community – Used for community modules that are available to us via Magento Connect.
  3. Local – Used for locally developed modules, that do not fall into the above categories.

We are going to develop our custom magento module in the local codepool as it is neither a core magento module nor are we going to provide it via magento connect (as of now). Now let’s go to our magento root directory.

Once you have reached your magento directory, cd in to app/code/local, This is where our custom module code will reside.

Magento Custom Module Development

So let’s start with creating a folder named after our company (you can use your own blog/company name). so we type in mkdir Beyondroid (Beyondroid is our company name) and then cd into it using cd Beyondroid.This folder is root of all the custom modules that we’ll develop for this magento installation.

Magento Custom Module Development

Now we create our custom magento module directory named Sms. So we do mkdir Sms and then cd into it cd Sms. Notice the capital letters in our directory names S in Sms and B in Beyondroid. This is because of naming conventions of magento.

Now we create a etc folder in our module directory. This etc folder is going to contain our modules configuration files. Once you have created the etc folder go ahead and create a file named config.xml inside the etc folder.

Custom magento module development

Now let’s add the following code to our config.xml file

Let’s see what we have defined in our config.xml file.

  1. The <config></config> tags contain your module information. So all the other blocks go inside the config tag.
  2. The <modules></modules> tag define the information like location of the module, version of the module. Do note the <Beyondroid_Sms> tag within the modules tag. This tag defines the location of the module i.e. Beyondroid/Sms directory in our code pool. So In case your Folders are named Myextensions and Awesomemodule the tag that you’d be using in your <modules> tag should be <Myextensions_Awesomemodule>. Within this tag there is a version that defines the version of this module.
  3. Then we define our Model and Helper class location inside the <global> tag. The global tag defines the scope. You can also use <frontend> or <adminhtml> tags if that is where you will be using your model and helper classes. I just feel comfortable using the global scope.
  4. Inside the <models> tag, we define where our models reside. So in this case Beyondroid_Sms_Model and similarly for the <helpers> tag we have Beyondroid_Sms_Helper. As of now we have not created these directories and classes. So we’ll do that now.

Let’s create the Model and the Helper directory inside our Sms module directory. So now it looks like this:

Custom magento module development

Next thing is to let magento know about our custom module. In order to do so we need to add a xml file named Beyondroid_Sms.xml (according to the magento naming conventions) at the location /magento-root-directory/app/etc/modules/. So we go to our magento root directory and do vim app/etc/modules/Beyondroid_Sms.xml

Magento custom module development

and put the following code into it.


In the above code the <active> tag defines whether the module is enabled or not. The <codePool> tag defines which code pool our module resides in.

Once you have saved the above file, you should be able to see your custom module appear under Disable Modules Output if you go to System > Configuration > Advanced in your magento admin panel.

Magento custom module development


See it ? Good Enough now let’s get to the planning part.

Now, we need a way to provide customization options to the users in the admin panel. In order to acheive so we need to plan what customization options we will provide and how many sections are we going to divide into. For this custom magento module we are going to create 3 customization sections:


In general customization options we are going to provide the following settings fields:

  • Base API Url – Just in case if the api’s base url changes in the future, we need to be able to change it through the admin panel instead of hard-coding it in the code.
  • SMS Gupshup Username – This would be the username for our account with the SMS Gateway. This will be used for authentication on the gateway end.
  • SMS Gupshup Password – This is the password for our gateway account and again used with the username for authentication.
  • Production Mode – This would be a boolean (yes/no) dropdown that defines whether our module is working in production mode or not. It’s handy to have this switch while you are in the development phase as you may not want to send a SMS each time while testing.
  • Override DND – This is one of the settings provided by SMSGupShup gateway itself. If this is enabled the SMS messages will be sent to the customer phone even if the customer has a DND service enabled with his service provider. Here we’ll just have a (yes/no) boolean switch and pass this data directly to the gateway API.

SMS Events

Under SMS events section we are going to provide yes/no switches for the events that we would want to send the sms’ on. Currently we will just use 3 basic events as follows:

  • New Customer Registration – This switch will decide whether to send an SMS to customer after he has registered on our website.
  • New Order Placed – This switch enables/disables whether to send an SMS when a new order is placed with our magento store.
  • Order Shipped – This switch enables/disables whether to send a SMS to the customer once his/her shipment has been dispatched.

SMS Template

For each event that we have defined in the above section we need an editable template that contains the content to be sent to the respective :

  • New Customer Registration – This will contain the content for the SMS to be sent on new customer registrations.
  • New Order Placed – This will contain the content for the SMS to be sent when a customer places an order.
  • Order Shipped – This will contain the content for the SMS to be sent when a customer order’s shipment has been dispatched.

So let’s create a configuration menu item and the above mentioned sections. To do this cd in to your modules root directory (in our case it is magento-root-directory/app/code/local/Beyondroid/Sms) and create a system.xml file inside the etc folder and put in the following code.

In the above file within the <config> tag we define our configuration tabs, sections and groups. Let’s look at each one of them

Within the tabs tag we define our company company label. This will have a tab appear in the System > Configuration’s left side menu with the defined label as the tab heading. You can use the sort_order tag to position your tab in the menu.

In the sections tag each entry represents a link under that tab. In the above file we create only one entry under the sections tag i.e. <smspro> tag. The label for this entry represents the text that is displayed as the link under your tab.

Within this section we define a groups tag. Under the groups tag each group would be representing our customization settings sections that we discussed earlier. So we add 3 tags <general>, <smsevents> and <templates>. Within each of these tags we defined the fields that we require for the customization of our module. Under each field use tags like <label>, <comment>, <frontend_type>, <sort_order> <show_in_?> tags. Let’s see what each of these does.

The <label> tag represents the field label that is shown in the customization settings. The <comment> tag represents the comment i.e. shown under the field to help users understand what this particular field does. The <frontend_type> tag specifies what kind of field is to be shown. The <sort_order> defines the position of the field within the group.

There are 3 types of <show_in_?> tags each one uses whether the field is to be displayed in the respective view or not. if <show_in_default> tag is set to 1 the field will be displayed in the default view in admin. Similarly <show_in_website> and <show_in_store> tags work to display the fields in the respective views.

To learn more about fields, tags and configuration in general you should also check out this amazing post by Alan Storm.

Now in order to view the menu in the admin, there is an additional step that we need to take i.e. create the Data.php file in our modules Helper folder and add the following code to it.

Now log-in to your magento admin panel and navigate to System > Configuration. You should be able to see your custom module tab on the left sidebar

Magento Custom Module Development

But when you click on the link, it will give you a 404 error. In order to see our configuration sections and field there are 3 additional steps that we need to take.

1. Create a adminhtml.xml file under our module’s etc folder and put the following code into it.

2. Define default values for our fields. (This is optinal but is a good practice.). we will define the default values for the fields in our modules config.xml file. So open that file and add the following code. The following code snippet show the whole content, make sure you have just added the content in the default tag in your existing config.xml

3. Now logout of your admin panel and log back in. Go to System > Configuration > SMS Pro (gupshup gateway) and you should see your configuration options as follows:

magento custom module development

So now we have our magento custom module’s customization options in place. To make use of these customization options Go To Page 2 :  Custom Magento Module Development: Part 2: Using Customization Options.