How the Magento control flow works when creating a module

Wed, 03/23/2011 - 09:02

Submitted by markoshust Wed, 03/23/2011 - 09:02
Tags: 

I would like to start some short segments on how Magento works. There seems to be very little correct information on the web, and given I just came back from Magento U, I figure I can start spreading all of the good news.

Magento makes extensive use of XML. I'm sure all of you developers are fully aware of that by now, and some are completely loss in the mess of XML. In actuality, it's not a mess at all, but a very well designed architecture that believe it or not, you will learn to love after you get involved in module development. The purpose of the XML layer is to provide a much easier ability to override and extend the default Magento classes, and provide some structure to the thousands of files that exist in a default Magento install.

Some things you should know from the get-go: Magento combines ALL of the xml files, everywhere, into one giant XML file. Theoretically, any XML directive can go in any file, as long as it follows the same naming conventions inside the XML. This gives great freedom to the developer, but there are certain 'standards' you should follow so your code is easy to understand and maintain by the great many other Magento developers.

All code you will be working with is located within app/code, within a certain subdirectory (core = Magento, community = community modules, local = your site-specific modules). The first step to take when creating a module is setup your namespace (ex. make it easy on yourself: the name of your company or yourself), and then your module name (ex. Helloworld) so you wind up with the following directory structure:

app/code/community/Company/Helloworld

When you have that set, create some extra subdirectories within the module folder:

app/code/community/Company/Helloworld/controllers
app/code/community/Company/Helloworld/etc

Controller files will obviously go in the 'controllers' folder, and your xml file(s) will go in the 'etc' folder. Make more things easy on yourself: spell it all right. If you don't, you will eventually find yourself hating Magento, and yourself.

First, you need to make Magento aware of your new module; just creating the files doesn't do that. Create a file with the following:

<?xml version="1.0" encoding="UTF-8"?>
<config>
    <modules>
        <Company_Helloworld> <!-- your namespace and module name. spell/case it right. -->
            <active>true</active> <!-- this is always true unless you want to explicitly disable this module to diagnose issues -->
            <codePool>community</codePool> <!-- where the module lives in app/etc - either local, community or core -->
        </Company_Helloworld>
    </modules>
</config>

This file alone makes Magento aware of your module and adds it to the active list of modules. You can verify this by going System > Configuration > Advanced > Advanced in the Magento Admin, and seeing the module listed under the Disabled Modules Output list.

Now, create your module config xml file. Remember: this config.xml file will eventually be merged with all of the other xml files, so it has to follow a specific structure format. Set something up like this:

<?xml version="1.0" encoding="UTF-8"?>
<config>
    <modules>
        <Company_Helloworld> <!-- your namespace and module name. spell/case it right. -->
            <version>0.1</version> <!-- the version of your module, unimportant unless dealing with custom sql -->
        </Company_Helloworld>
    </modules>
    <frontend>
        <routers>
            <helloworld> <!-- name of router. for consistency sake, match this to frontName -->
                <use>standard</use> <!-- this is a standard router -->
                <args>
                    <module>Company_Helloworld</module> <!-- what module we should look at for the 'helloworld' router -->
                    <frontName>helloworld</frontName> <!-- for consistency sake, match this to router name -->
                </args>
            </helloworld>
        </routers>
    </frontend>
</config>

Looks like a ridiculous amount of code for adding in a custom router, but in actuality is quite condensed. We do have to explicitly declare everything with the correct naming conventions because again, everything is merged into one giant xml file, then parsed. So, essentially you can put the Company_Helloworld.xml file xml contents (active and codePool params) into your config.xml file. But we keep it separate to make sure those other Magento developers know where to go to find certain params. You'll get used to the naming and formatting pretty quick because it's really simple to follow as there is no 'coding' involved, just xml naming conventions.

What happens when we now to go http://magentoinstall.localhost/helloworld is that it is going to check the xml file for a 'helloworld' router. Given the above, it'll find it! The config is telling the helloworld router to look for the controller in Company/Helloworld/controllers and execute it. Well, I guess we need a file there. Throw something up like this:

<?php
class Company_Helloworld_IndexController extends Mage_Core_Controller_Front_Action
{
    public function indexAction()
    {
        echo 'Hello... world!';
    }
}

If you are familiar with Zend Framework and MVC, it will come into play here (if not, please go ahead right now and read up on Zend Framework & MVC). Long story short, you have the url address something like /helloworld/controller/action, with controller = index and action = index by default. So, rendering /helloworld, /helloworld/index, and /helloworld/index/index all go to the same place (IndexController->indexAction, as you can see above).

Now visit http://magentoinstall.localhost/helloworld, and you should see your Hello... world! display. Hopefully this clarifies some of the beginning routing questions available and gives you a brief overview of the xml naming and structuring process.

Related Screencast

I created a related screencast that is available on Vimeo, Creating a Helloworld Module in Magento.

Comments

Dude, great explanations. I'm an experienced PHP Developer, and familiar to OOP and MVC developing. Not very familiar with the ZF though, but to others frameworks.
It would be very helpfull to me if you could throw me a line about where [A link, a book] to learn the XML naming nodes conventions for Magento.
Of course I've been around the Magento site, wiki, Alan Storm's blog, and been reading a few books, like Magento Developers Guide and the Architect's Guide to Programming with Magento, but still can't make a clear and enlighted idea of Magento's XML config files. Let me confess that it's been two weaks since I ever knew Magento ... Help would be appreciated. Drop me some lines to ele_hache@hotmail.com
Thanks in advance

SUPER. KEEP IT UP

Hi Mark,
I have read these article. thanks a lot.
I have done the adding custom module with the above process but didn't getting the output with the given url : http://magentoinstall.localhost/helloworld. Is that because i have already installed the magento??
Will please help me out??

Regards,
Rajesh

Thanks so much Mark it'z working now ,can you please write an article on block in magento ,how it really works. it will be very helpful for newbies like me in magento

Regards
Param

Hi Mark, can i know how to run the code in wamp server, right now i am trying using this http://localhost/magento/magento/index.php/helloworld/index/index and it is giving 404 error page.

FYI... this code is verified as working. If it's not working.... you are doing something wrong :) Just check over the url's, naming, and etc. until it is fixed -- that is programming!

Thanx for such an quick reply, but i have my magento modules installed in C:\wamp\www\magento\magento\app so i think the url is right which i have given, could u plz let me know the some site or documentation which show how to run the magento module in local..

just few days before i have started learning Magento and have installed it, added different type of products, analyses the code but while applying a theme i found a problem, every thing require to change the theme i have done but by default in fronted it is just taking the theme from base/default path only and not from the new package to sort out this i again installed the magento and applied the theme and this time the theme get applied...........what would be the problem please let me know?

I don't quite understand your post, but after setting the package and theme in admin>config, and creating your folders in app/design/frontend/packagename/themename and skin/frontend/packagename/themename, it should look in those directories for everything. What it doesn't find, it will fall back to the base package and default theme.

Hi mark,
I have followed your steps to create new module.
I have created it successfully.
I can see that module in System->Configuration->advanced.
Please tell me how can i access that module in user front.

Hi Mark,
I started learning magento just few days before.In magento we have facility to check paths in user front by setting System->Configuration->Developer->Debug->Template Path Hints="Yes" and Add Block Names to Hints="Yes". Do we have same functionality for admin side for checking path hints?

It's all the same framework and codebase, so yes, but you will need to most likely override that core functionality to apply it to adminhtml.

Hi,
I have read your article. thanks for it. but i need to know how i can make a module in which we are able to write some text in back end(admin) and it will display in front end. so i can take the data "abc" from admin and process it(some calculation) and then display in front end. please replay me . i understand your all above points and now i am very enthusiastic to learn next.

thanks

I want to know the flow of data in magento while any event occur, like when product is added or customer is edited.
I want to know where the query's are building for these.
Could you please guide me/ share link.

Hi Yash,

Please refer to event observers wiki page at http://www.magentocommerce.com/wiki/5_-_modules_and_development/0_-_module_development_in_magento/customizing_magento_using_event-observer_method

This is most likely what you are looking for.

Thanks,
Mark

The screencast about "Creating a Helloworld Module in Magento" is great!

Hopefully you will create more screencasts in the future.

WHen i have ran by following url
http://localhost/magento_theme/index.php/helloworld/index/index

or
http://localhost/magento_theme/index.php/helloworld/

i am getting 404 error...

Please help me....

Double-check your spelling... the tutorial above has been all confirmed working. With frameworks... if something isn't working, there are good chances you are doing something incorrectly (or have a typo someplace). My advice is to start over and go step by step. Good luck!

Thanks Mark...

Now its working...

Sorry for inconvenience....

Thanks
Pankaj