Learning to Design and Code for Magento Themes

First off, the first reaction I always hear when others are introduced to Magento [including myself] are complaints about how difficult it is. The truth is it is just as easy as what we’re all used to. I’m going to show you that today by drawing comparisons between Magento and some other popular open-source projects we’re more familiar with such as Drupal and WordPress.

This guide is meant to be a quick-start supplement for the official Magento Design Guide, and not a replacement for it. It assumes you are already familiar with and have completed themes for Drupal and/or WordPress.

Introduction: Working with Magento

The first thing you’ll notice about Magento is its size: 15.7MB zipped, and 58.8MB unpacked: 7,231 files across 2,482 folders (as of Magento 1.2.0.1). This may be one of the largest web applications you’ve worked with–and not only you, but your IDE, too. Don’t even think about letting Notepad++, UltraEdit, Textpad, or one of those programs touch this baby. The “Made with Notepad” days are long gone, man. Get yourself a decent IDE. I even had to upgrade my Eclipse IDE to 2.1.0M5 “Galileo” and switch my PHP stack to Zend Core 2.5 just to handle Magento without slowness and crashing.

The second thing you’ll notice is that it’s fully object-oriented with PHP5, and if there seems to be no rhyme or reason to the directory hierarchy, you may also need to take some time to introduce yourself to Zend Framework for PHP. What’s really happening here is Varien is using architectural and design patterns you’ve probably seen before but never fully understood such as Model View Controller (MVC), the Front Controller pattern implemented by Zend_Controller object, the Two Step View pattern, the Application Controller pattern, etc.

Later when you begin writing Magento extensions, you’ll also notice you don’t have to write any SQL anymore because Zend_Db implements the Data Mapper pattern.

So for now bookmark the Zend Framework Reference Guide, Designer’s Guide to Magento, Magento Documentation, and lets get started.

Getting Started: Jump-start with pre-existing Blank Theme

The first thing I would do is download the Blank Theme from Magento Connect; it’s a good blank canvas starting point for theme developers. As I recall, the Drupal community also had one of these–it was called Zen by John Wilkins. In WordPress I suppose it is the equivalent to the Kubrick theme by Michael Heilemann. If you are building your own standards-compliant theme, you will find it much easier to start with Blank Theme than to start with the default Tealo theme packaged with Magento core. This theme is also well commented.

Before we go any further, I want to emphasize that one primary difference you’ll realize with Magento is that there are many many pages you or your client may decide to potentially theme individually. (e.g. front page (2 col), catalog pages (3 col), product pages (2 col), about pages (1 col), my cart, checkout–even the email templates are individually themed) Not only that, but there are over 270 unique XHTML template files as well as the CSS for each content block (e.g. my cart, compare products, newsletter, advertisements, etc.) which come with the stock installation of Magento.

So when quoting you have to take into consideration just how far you’re planning on deviating from the Magento defaults because it could potentially take you a considerable amount of time to customize all these things. In most cases, though, clients only want to pay to have up to five unique pages designed, so it’s no biggie to reuse a lot of the default code on the rest of the pages. By starting with the Blank Theme, we already have all of the base XHTML and CSS we’re going to need, and all we have to do is write the code to override it and only where change is required.

Terminology: Identifying the different LEGO™ pieces

So the Magento Design Guide does a pretty good job of explaining this but I want to draw some comparisons using proportional analogies. (i.e. “A in Magento is to B in Drupal and C in WordPress”)

• A “Theme” in Magento is just like any theme in Drupal or WordPress, with two exceptions. One, the front-end and back-end of Magento are treated as separate themes. And two, for security reasons each theme is split into a public directory (e.g. css, js, images, and index.php front controller) and private directory (e.g. all .php files including XHTML templates which are saved as .phtml files).

• “Structural Blocks” in Magento are known as regions in Drupal, and similar to sidebars in WordPress.

• “Content Blocks” in Magento are just called blocks in Drupal, and widgets in WordPress. However, unlike Drupal and WordPress, they cannot yet be positioned on the page using simple JavaScript drag-and-drop techniques. They can’t even be specified with weights like in Drupal 5. They are specified only in .XML layout files, which are part of your theme, and can optionally be assigned an order which is an integer but are otherwise displayed in the order that the .XML files are included. However, unlike Drupal and WordPress where blocks and widgets would normally be relegated to only sidebars and you cannot control the position of the actual content, in Magento, content blocks are used for everything. For example, to render the XHTML for individual products, comparable in Drupal to nodes, or in WordPress to posts and pages.

• “Layouts” in Magento have no equivalent in Drupal or WordPress. It’s a relatively clever concept. There are also some other clever concepts involved like overriding of template files that I won’t go into here but are explained in the design guide. You won’t need to worry about that much, if at all, to complete this theme.

• “Templates” in Magento are the individual XHTML files and they are saved with a .phtml extension inside the ./app/design/frontend/default/YOUR_THEME/template/page/ directory. In Drupal these files end with .tpl.php and are saved in ./sites/all/themes/YOUR_THEME/, and in WordPress these files end with good old .php and are saved in ./wp-content/themes/YOUR_THEME/. These are the files containing XHTML markup for pages, including header, footer, as well as individual content blocks.

Ok, great. Now that you are acclimated to the terminology most people will be using as you read further into the subject, let’s move on.

Touring the Directory Structure: What goes where?

Now I am going to take you on an overview of the Magento directory structure, highlighting only the files you need to be concerned about along the way to complete your first theme. Feel free to find these files and directories in your own Magento installation and follow along with me as I explain what each file is for.

./app/ - private dir
  design/
    frontend/
      default/ - interface (worry about later)
        YOUR_THEME/
          layout/ - .XML here control which content blocks appear and in what order
            page.xml - content blocks that appear on all pages
          template/
            page/
              html/
                head.phtml - DOCTYPE & <HEAD> tag
                header.phtml - page header incl. logo
                footer.phtml - page footer
              1column.phtml - e.g. about page
              2columns-left.phtml
              2columns-right.phtml - e.g. product page
              3columns.phtml - e.g. catalog page

./skin/ - public dir
  frontend/
    default/ - interface (worry about later)
      YOUR_THEME/
        css/
          styles.css - screen styles
          print.css - print styles
          reset.css - CSS reset
          clears.css - .clear { clear:both }
          styles-ie.css - ie-only styles
        images/
        js/
        favicon.ico

I think the way I have presented it to you here, if you have ever completed a theme for WordPress or Drupal before, you will immediately recognize these files and be well on your way. By making changes to these XHTML and CSS files alone you will have drastic control over 90% of the theme.

Enabling Magento Debugging Tools

Of course, there are more files than this that make a theme. Sometimes you will wonder what file controls a specific content block when you want to edit its XHTML template. For that you will want to know about this handy developer tool provided with Magento.

Here it is step-by-step:

1. Login to back-end > System > Configuration
2. Choose your store from the “Current Configuration Scope” drop-down menu on the top-left
3. Continue navigating to Advanced > Developer
4. Open the Debug drawer
5. Uncheck “Use website” for “Template Path Hints” and set its drop-down to “Yes“
6. Uncheck “Use website” for “Add Block Names to Hints” and set its drop-down to “Yes“
7. Click the Save Config button and refresh the front page

This will display the location of the .phtml template at the top of each content block. It does come in handy.

To Be Continued

While there are more advanced subtleties, nuances, and quirks you will undoubtedly encounter as you complete more and more themes for the Magento e-Commerce platform, this is the meat and potatoes. Should you run into any question not answered here, I find that the Magento Forum, Magento Wiki, and #magento on irc.freenode.net, as well as a fair amount of Googling can turn up those answers with relative ease.

Please feel free to drop me a note in the comments if this tutorial saved you some time, or if you’d like to point out anything I may have missed or any necessary corrections to be made. Otherwise, thanks for visiting and good luck on your theme!

Bonus

I recently completed a Magento theme of my own and it took me about 40 hours to do, work which includes the creative time for custom artwork. All-in-all, it turned out excellent and I am very proud. Check it out:

Front page

Product Catalog

Product Page

Also, I have posted an in-depth case study explaining most everything that went into the project, should you be interested in reading further:

Magento case study at Smullin Design

Thanks again!