Writing a custom module in Magento

I wrote a newer article on how to write a module, one with more details. Check it out here .

   Time to move on to some more serious stuff concerning Magento. My last few posts were about understanding a way to use Magento functions. Functions like getModel, getData, getSingleton and so on. Most important it was a way of showing you how to find the available functions ascreend how to extract the data from objects. Not sure if I fully seceded in that but hopefully I helped a bit.

   Before I start with the explanation on how to actually write a module let’s take a deeper look at the module philosophy. You can look at the module as your application (that’s the way I look at it) within the main application (Magento). Just for the consistency let’s stick to the module terminology. Each module is comprised of various parts working together for the common goal. If your module is named, let’s say, SomeCoolPaymentServiceModule then the common goal of the module parts is to achieve full integration (inner workings) of Magento system with the SomeCoolPaymentService service.

So what are the parts that make the module ? In MVC architecture even the bare bone application is (mostly) written across three separate files. Model, View and Controller. Ideal case is the one where Model manages all of the database connections and queries, then passes the information to controller. Controller then reorders, maps, filters, does some logic on the data and passes it to the View. View is the thing we see. View is the file served to our browsers. In Magento case View is called Block. The same block whose name we see when we turn on System > Current Configuration Scope > Developer > Add Block Names to Hints to Enabled.

Magento is built on top of Zend framework. Since Zend is pure MVC framework so is Magento’s architecture MVC based. Open you Magento installation directory and drill down into the app/code/core/Mage/Catalog/ folder. Notice the word Catalog in this path? Well, the Catalog is one of the modules inside the Magento. And the app/code/core/Mage/ path is the path to all the Magento modules , the building blocks of Magento. Now that we know where to find modules, let’s look at the content of a module. This is the content of the Catalog module:

Block /
controller/
etc /
Helper /
Model /
sql /
Exception.php

  As you might notice, there are more than three type of files here. By types I think of Model, View (Block), Controller. Magento’s structure is therefore more divided. We can see the Helper and sql folders as well. Although not every Model contains the same sub folder structure like this one you need to understand that this is somewhat of a blueprint of how Magento modules are built.

  So how does one write a custom module ? Presumption is that you already know how to create a custom theme. Across this walktrough I will be using paths showing mycustom as the name of my theme folder. Remember this so you don’t get confused. My module will be called ActiveCodeline (wonder why ).

  Folder /app/code/core/Mage/ is used to store default Magento modules NOT the custom created ones. User (custom) modules are to be stored inside the app/code/local/ folder. The thing with PHP is that it lacks the support for namespaces. However, this did not stop Magento guys and girls for creating them. In the default Magento module folder /app/code/core/Mage/ word (folder) Mage is actually a namespace. Why is this important? Well, as I sad I’ll create a module named ActiveCodeline. Creating a directory app/code/local/ActiveCodeline/ simply means I created a new namespace named ActiveCodeline inside the user module folder. Therefore you should look at the ActiveCodeline folder as the namespace name not the module name for now.

   Under the /app/code/local/ActiveCodeline/ folder (or shall I say under the namespace ActiveCodeline) create a folder (module) named Example like

    app/code/local/ActiveCodeline/Example/

   Now if we were to look at the newly created folder we should look at it the same way we look at the app/code/core/Mage/Catalog/ folder. Example (in our case) and Catalog (in Magento default case) are both modules. Now we can say Example is our custom module. This however is a bit contradictory since we are most likely to say that ActiveCodeline is the name of our module . What’s important is that you know the difference and avoid getting confused by the naming.

Now, let’s go into the /app/code/local/ActiveCodeline/Example/ folder (module) and create two subfolders there, Block and etc. Our folder structure should now look like

/app/code/local/ActiveCodeline/Example/
Block/
etc/

  So far, we haven’t done anything that would make Magento see our new module. In order to get our module seen by Magento we need to register it. How do we register our module in Magento? drill down into the newly created

/app/code/local/ActiveCodeline/Example/etc/

folder and create config.xml file.

  What do we write into this file? If you open up the app/code/core/Mage/Catalog/etc/config.xml file and have a look inside, you’ll see the stuff it contains. For our bare bone module we need to write the following into the config.xml file:

<?xml version=”1.0″ encoding=”UTF-8″?>

<config>

<modules>
<ActiveCodeline_Example>
<version>0.1.0</version>
</ActiveCodeline_Example>
</modules>

<global>
<blocks>
<ActiveCodeline_Example>
<class>ActiveCodeline_Example_Block</class>
</ActiveCodeline_Example>
</blocks>
</global>

</config>

  After we save our config.xml file we can go to Magento admin, go to System > Configuration > Advanced . There you should see the ActiveCodeline_Example on the list among other modules.

Now we need to add some logic to our module. To keep things simple, I’ll make my module simply echo some stuff to the browser. Now lets create second file that we need to make our module work. Open up the app/code/local/ActiveCodeline/Example/Block/ folder and create a View.phtml file.

Place the following content into it:

class ActiveCodeline_Example_Block_View extends Mage_Core_Block_Template {

public function doSomeAction(){
$message = ‘<p>Hello from ActiveCodeline sample module…</p>’;
return $message;
}
}

Finaly, we go to our theme folder. As I told you at the beginning of this article, my theme folder is called mycustom . Therefore, inside the app/design/frontend/default/mycustom/template/ folder you need to create the example folder like

app/design/frontend/default/mycustom/template/example/

Now you create a file called view.phtml with the following content

<?php
/*
$this is now instance of ActiveCodeline_Example_Block_View
*/
?>
<div>This is the output of the activecodeline example:</div>
<?php
echo ‘Class name: <strong>’. get_class($this) .’</strong>’;
echo $this->doSomeAction();
?>

Basically these three files conclude the creation of your bare bone module . To test if the module is working, go to Magento admin > CMS > Manage Pages > Home page then write the following somewhere on the page

<h1>Sample activecodeline message…</h1>
{{block type=”ActiveCodeline_Example/view” template=”example/view.phtml”}}

Notice the type=”ActiveCodeline_Example/view” . If you were to write it like type=”activecodeline_example/view” it wont work. Watch for the capital letters.

Now if you refresh the home page of Magento shop, you would see the result message of the new module.

As I said at the beginning, this is a bare bone module , dummy module or whatever you like to call it. My intention was show you how simple it is to create a basis for module. I haven’t mentioned sql folder here or helpers folder. I leave some things for you to do. Most of the tutorials out there on creating a custom module jump right into the fire going over trough stuff I intentionally left out but they leave the basis unmentioned. Then you end up with the tutorial on how to create something cool but you are missing few steps and you go crazy trying to figure out what’s missing.

If you truly understood this walktrough and my previous articles on Magento then you are ready to connect the dots and start making more serious modules.

Hope this was helpful. All the best…

19-01-2009
p.s. Article has missed one step. I missed adding the xml to app/etc/modules/ as descibed in comments below by Coconuts-GrG .

Comments are now closed for this article…