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:
adminhtml
: This folder contains the XML layouts and PHTML view files used for rendering the Magento administration area, the area that the admin user seesfrontend
: This folder contains the XML layouts and PHTML view files used for rendering the Magento frontend area, the area that the customers see.install
: This folder contains the XML layouts and PHTML view files used for rendering the Magento installation process
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 sk
in 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:
app/etc/modules/
– requiredapp/locale/
– optionalapp/code/community/YourNamespace/YourModuleName/
– required/app/design/frontend/default/default/
(or/app/design/adminhtml/default/default/ for backend area
) – optionalskin/frontend/default/default/
(orskin/adminhtml/default/default/
) – optional
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.