Introduction
Magento is an excellent piece of open-source software providing developers with an e-commerce platform that’s extremely extensible and flexible…once you know the system.
Of all the open-source shopping cart systems available, Magento is widely considered one of the most difficult to learn. This is in large part due to the somewhat lacking availability of detailed technical documentation.
In this two part series I hope to introduce some of the basic concepts of how Magento is built and how to customize it by following its modular standards. This ensures that future updates of the Magento core system will not affect your customizations and allow you to extend the platform to suit your needs.
In part one we’ll cover the basics of Magento’s architecture to become familiar with the structure of the platform itself. Then, in part 2 we’ll build a simple “Hello World” custom module for Magento in order to understand how some of the concepts we’ll cover are put into place.
Structure
Magento follows very strict development standards that rely on knowing exactly where to place files and folders. While this can make it a little bit difficult to learn, this is actually one of the primary benefits of the platform. Following these standards provides the flexibility to create your own solutions on top of the platform and build anything you and your clients need.
One of the most important things you can learn about customizing Magento is simply “what goes where?” To get a basic understanding of this, let’s start by reviewing all of the files and folders included in default Magento installation.
- /app
- /downloader
- /errors
- /js
- /lib
- /media
- /pkginfo
- /skin
- /var
- .htaccess
- cron.php
- cron.sh
- favicon.ico
- get.php
- index.php
- install.php
Each of these directories and files has a specific purpose. We’ll cover each in more detail in order to understand what’s happening within all of this, which will be helpful in the future when building custom modules and knowing where things should go.
| /app | This is the directory we’ll be primarily working in when developing custom Magento modules. This is where all code for modules, design themes, configuration files, and translation files are stored. |
| /downloader | This is where the built in installer for Magento exists. It allows you to upgrade or install Magento quickly when SSH is unavailable. |
| /errors | This directory houses code for handling errors and reporting like 404 and 503 server responses. |
| /js | This is the core directory for JavaScript code included with a clean install of Magento. All pre-compiled JavaScript libraries reside here. |
| /lib | This directory houses all of the PHP libraries used to build Magento including the Zend Framework. |
| /media | This folder is used for media storage, primarily images. All generated thumbnails and product images will be placed in this directory by default. Also, when importing products into Magento you will place all uploaded product images here. |
| /pkginfo | This directory contains simple txt files that help to notify users when modules are upgraded in any way. |
| /skin | All theme assets are located here. We can generally find images, JavaScript, CSS, Flash, etc. related to the themes that are currently installed. It also contains template files for the installation and administration of template files. |
| /var | This directory is where the majority of cached data, exported data, database backups, and error reports are found. |
| .htaccess | This is a standard control file for the Apache web server and handles URL rewrites for SEO purposes. It also sets configuration variables to help Magento perform as well as possible. |
| cron.php | This PHP script is provided to help ensure that Magento’s caching system does not affect server performance. It should be run every few minutes on the server via a cron job. |
| cron.sh | This is a shell script version of the PHP cron job script and can be used outside of the PHP cron job. |
| favicon.ico | Magento’s default favicon, which is a small icon that will be seen in the user’s web browser title bar. |
| get.php | This file receives request data from client devices and routes the request to the correct controller or error page accordingly. |
| index.php | This is the main loader file for Magento that will initialize everything for the Magento platform. |
| install.php | As the name indicates, this file is responsible for checking the current PHP version and loading the installer for Magento accordingly. |
Template System
The template system in Magento is broken down into three sections: two for theme development and one to store assets.
- /app/design/frontend/default/<template_name>/
- /layout – This is where XML configuration files are stored to distinguish which functions should be tied to which modules and template files.
- /template – This is where template files are stored which process the output passed from the layout configuration files.
- /skin/frontend/default/<template_name>/ – This is where all assets related to your template, images, JavaScript files, CSS files, Flash, etc.
Structural and Content Blocks
Each theme in Magento will contain both structural and content blocks. The structural blocks will create the overall layout of a particular page, while the content blocks will house actual design and data to be displayed on screen.
Let’s take a look at an example of how structural blocks are used to lay out a page. Consider a three column page layout with a header and footer as depicted by the following image.
You can see how the highlighted sections of the graphic simply provide separate containers for each portion of the page. If you’re familiar with CSS design you’ll feel right at home with this concept.
The content blocks will then reside within each structure block to present information (content) to the user on screen. For example, the “right” structural block on our layout contains the following content blocks.
- Product Comparison
- Mini Cart
- Newsletter Subscription
- Community Poll
As you can see, the theme essentially consists of a bunch of CSS blocks that are stacked and aligned accordingly on the page to generate the anticipated outcome. Each time a user requests a page from the Magento system the following sequence of events takes place.
- Magento loads all structural portions of the page.
- Magento will then gather all content blocks associated with each structural block and process the output based on the template layout configuration files.
- The final output is presented to the user on screen.
XML Layout Configuration Files
Values and content are assigned to blocks using XML configuration files within the theme’s structure. The XML file is loaded based on the URL requested by the client. It notifies the system of all modules that need to be loaded in each structural portion of the page. One of your XML configuration files should be named page.xml and will be the default loader for all pages on the site.
Let’s take a look at the basic structure of an XML layout configuration file.
<default> <reference name="header"> <block type="page/html_header" name="header" as="header"> <block type="page/template_links" name="top.links" as="topLinks"/> <block type="page/switch" name="store_language" as="store_language" template="page/switch/languages.phtml"/> <block type="core/text_list" name="top.menu" as="topMenu"/> </block> </reference> </default>
Now we can break this down and take a closer look at what’s happening.
<default> – This element specifies the URL handler.
<reference> – This element specifies the structural block that you’ll be referencing. Here we are referencing the header block in our theme structure.
<block> – This element specifies a content block, what type of block it will be, and which template file should be loaded and displayed to the end user.
Magento also uses <action> elements within the XML configuration files for functions that need to process data passed in to them. For example, styling with CSS.
<block type="page/html_head" name="head" as="head"> <action method="addCss"> <stylesheet>css/menu.css</stylesheet> </action> <action method="addCss"> <stylesheet>css/clears.css</stylesheet> </action> <action method="addItem"> <type>js</type> <name>varien/iehover-fix.js</name> <params>media="print"<params/> <if>lt IE 7</if> </action> <action method="addCss"> <stylesheet>css/print.css</stylesheet> <params>media="print"</params> </action> <action method="addCss"> <stylesheet>css/print.css</stylesheet> <params>media="print"</params> </action> </block>
Once again, the content block is specified and then action tags are used to load stylesheets for that particular block.
Layouts and templates are explained in more detail in Magento’s Designer’s Guide. I highly recommend you read through this guide in order to fully understand everything we’ve covered here.
Hierarchical File Processing
One very nice aspect of the Magento’s design structure is that we do not have to worry about copying or creating every single file necessary to replicate or build a new theme from scratch. If you have your own theme installed, Magento will load any content available within your theme, but will fall to the default theme any time required files are not found within your theme and will still load accordingly.
For example, let’s say we simply want to update the logo on our currently active theme. We don’t want to modify the theme’s core files, though. As such, we’d create a new theme, my_new_theme, that will reside along with our original default_theme.
Assume our pages are calling images, logo.gif and image.gif, and that both of these images are included in /skin/frontend/default/default_theme/images directory. Let’s also assume that a different logo.gif file resides in our /skin/frontend/default/my_new_theme/images directory. We can visualize this as follows.
| default_theme | my_new_theme |
| logo.gif | logo.gif |
| image.gif |
When our pages load with my_new_theme active, logo.gif will be pulled from the my_new_theme directory, however, image.gif (and everything else for that matter) will be pulled from the default_theme directory.
This hierarchical file processing applies to all files within Magento themes, including templates, XML layout files, and any content within the skin folders.
While this was a quick overview of the details behind the Magento architecture, I hope it’s allowed you to become a little bit more comfortable with the underlying structure of the platform.
Stay tuned. In part 2 of this series, we’ll focus more on the details of how modules are built within Magento, and we’ll walk through the development of a class “Hello World” custom module.