The theme system

In order to successfully build extensions that visually manifest themselves to the user either on the backend or frontend, we need to get familiar with the theme system. The theme system is comprised of two distributed parts: one found under the app/design folder and the other under the root skin folder. Files found under the app/design folder are PHP template files and XML layout configuration files. Within the PHP template files you can find the mix of HTML, PHP, and some JavaScript.

The structure of the app/design folder is shown in the following diagram:

app/
├── design
│   ├── adminhtml
│   ├── frontend
│   │   ├── base
│   │   │   └── default
│   │   │       ├── etc
│   │   │       ├── layout
│   │   │       └── template
│   │   └── default
│   │       ├── blank
│   │       ├── default
│   │       ├── iphone
│   │       └── modern
│   └── install

There are three main subfolders here as follows:

Once you step into one of them you should see a list of so called packages.

For example, stepping into the frontend shows two packages available, base and default. Drilling down into individual packages, come themes. For example, the package default has four themes in it: blank, default, iphone, and modern. By default, once you install the Magento package the initial active theme is default within the default package.

You will often hear about the frontend developer using a shorthand when talking about theme; for example, if they say default/hello, it would mean the default package with the theme named hello.

There is one important thing to know about Magento themes; they have a fallback mechanism; for example, if someone in the administration interface sets the configuration to use a theme called hello from the default package; and if the theme is missing, for example, the app/design/frontend/default/hello/template/catalog/product/view.phtml file in its structure, Magento will use app/design/frontend/default/default/template/catalog/product/view.phtml from the default theme; and if that file is missing as well, Magento will fall back to the base package for the app/design/frontend/base/default/template/catalog/product/view.phtml file.

We won't get into the details of Magento design packages and themes. There is plenty to be said about this topic that could fit into a new book. For the purpose of this book, there are a few things that you need to know as a Magento extension developer in terms of writing unobtrusive extensions.

Firstly, all your layout and view files should go under the /app/design/frontend/defaultdefault/default directory.

Secondly, you should never overwrite the existing .xml layout or template .phtml file from within the /app/design/frontend/default/default directory, rather create your own. For example, imagine you are doing some product image switcher extension, and you conclude that you need to do some modifications to the app/design/frontend/default/default/template/catalog/product/view/media.phtml file. A more valid approach would be to create a proper XML layout update file with handles rewriting the media.phtml usage to, let's say, media_product_image_switcher.phtml.

This might not make much sense for you now; but once you get your head around layout updates, the idea will be pretty clear. We will now temporarily conclude our trip to the app/design folder structure and move on to the root skin folder. The structure of the skin folder is similar to that of app/design, as shown in the following diagram:

skin/
├── adminhtml
├── frontend
│   ├── base
│   │   └── default
│   │       ├── css
│   │       ├── favicon.ico
│   │       ├── images
│   │       ├── js
│   │       └── lib
│   │           └── prototype
│   └── default
│       ├── blank
│       ├── blue
│       ├── default
│       │   ├── css
│       │   ├── favicon.ico
│       │   └── images
│       ├── french
│       ├── german
│       ├── iphone
│       └── modern
└── install

There is not much to say about the skin folder. It's a placeholder for all your theme-specific CSS, JavaScript, and image files. If you are developing community-distributed extensions, it makes sense to reduce the usage of CSS to absolute minimum, if any, in your extension. The reason is that you cannot know which theme the user will use and how your extension visual components design will impact its theme.

The same thing cannot be said for JavaScript, as you will most likely notice yourself if you keep developing a lot of community extensions. Adding your custom JavaScript code to a skin/frontend/default/default/js folder is a nice, clean, and unobtrusive way of doing it. As the skin folder has the same fallback functionality as the app/design folder, you do not need to know upfront the theme that the user will use.

Later on, as you sharpen your Magento developer skills you might ask yourself, "Why not use the root js folder to add your JavaScript code?" Technically, you could, and it would be perfectly valid; no tricks or hacks in that approach. However, the root js folder should be looked upon as a third-party JavaScript library container, while the skin/frontend/default/default/js folder should be looked upon as your custom JavaScript extension-related code container. For example, it makes no sense to place your product image switcher extension JavaScript into the root js folder if it's a JavaScript code that works only with your extension and is not intended for general re-use.

With this we can conclude the relevant Magento folder structure that you as a Magento extension developer should be familiar with. In general, these five locations should be all to build fully functional, clean, and unobtrusive extensions:

Depending on the complexity and the functionality your extension tries to fulfill, you might end up using just a few or all of these directory locations within a single extension.