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. Mylast few posts were about understanding a way to use Magento functions.Functions like getModel, getData, getSingleton and so on. Mostimportant it was a way of showing you how to find the availablefunctions ascreend how to extract the data from objects. Not sure if Ifully seceded in that but hopefully I helped a bit.

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

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

Magento is built on top of Zend framework. Since Zend is pure MVCframework so is Magento’s architecture MVC based. Open you Magentoinstallation directory and drill down into theapp/code/core/Mage/Catalog/ folder. Notice the word Catalog in thispath? Well, the Catalog is one of the modules inside the Magento. Andthe 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 theCatalog 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’sstructure is therefore more divided. We can see the Helper and sqlfolders as well. Although not every Model contains the same sub folderstructure like this one you need to understand that this is somewhat ofa 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. Inthe 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 adirectory app/code/local/ActiveCodeline/ simply meansI created a new namespace named ActiveCodeline inside the user modulefolder. 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 isour custom module. This however is a bit contradictory since we aremost 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 newmodule. In order to get our module seen by Magento we need to registerit. How do we register our module in Magento? drill down into the newlycreated

/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.xmlfile and have a look inside, you’ll see the stuff it contains. For ourbare 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 letscreate 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 youhow simple it is to create a basis for module. I haven’t mentioned sqlfolder here or helpers folder. I leave some things for you to do. Mostof the tutorials out there on creating a custom module jump right intothe fire going over trough stuff I intentionally left out but theyleave the basis unmentioned. Then you end up with the tutorial on howto create something cool but you are missing few steps and you go crazytrying to figure out what’s missing.

If you truly understood this walktrough and my previous articles onMagento then you are ready to connect the dots and start making moreserious 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…