Magento Theme Development

7 min read

In this article by Fernando J. Miguel, author of the book Magento 2 Development Essentials, we will learn the basics of theme development. Magento can be customized as per your needs because it is based on the Zend framework, adopting the Model-View-Controller (MVC) architecture as a software design pattern. When planning to create your own theme, the Magento theme process flow becomes a subject that needs to be carefully studied. Let’s focus on the concepts that help you create your own theme.

(For more resources related to this topic, see here.)

The Magento base theme

The Magento Community Edition (CE) version 1.9 comes with a new theme named rwd that implements the Responsive Web Design (RWD) practices.

Magento CE’s responsive theme uses a number of new technologies as follows:

  • Sass/Compass: This is a CSS precompiler that provides a reusable CSS that can even be organized well.
  • jQuery: This is used for customization of JavaScript in the responsive theme. jQuery operates in the noConflict() mode, so it doesn’t conflict with Magento’s existing JavaScript library.

Basically, the folders that contain this theme are as follows:

  • app/design/frontend/rwd
  • skin/frontend/rwd

The following image represents the folder structure:

As you can see, all the files of the rwd theme are included in the app/design/frontend and skin/frontend folders:

  • app/design/frontend: This folder stores all the .phtml visual files and .xml configurations files of all the themes.
  • skin/frontend: This folder stores all JavaScript, CSS, and image files from their respective app/design/frontend themes folders.

Inside these folders, you can see another important folder called base.

The rwd theme uses some base theme features to be functional. How is it possible? Logically, Magento has distinct folders for every theme, but Magento is very smart to reuse code. Magento takes advantage of fall-back system. Let’s check how it works.

The fall-back system

The frontend of Magento allows the designers to create new themes based on the basic theme, reusing the main code without changing its structure. The fall-back system allows us to create only the files that are necessary for the customization.

To create the customization files, we have the following options:

  • Create a new theme directory and write the entire new code
  • Copy the files from the base theme and edit them as you wish

The second option could be more productive for study purposes. You will learn basic structure by exercising the code edit.

For example, let’s say you want to change the header.phtml file. You can copy the header.html file from the app/design/frontend/base/default/template/page/html path to the app/design/frontend/custom_package/custom_theme/template/page/html path.

In this example, if you activate your custom_theme on Magento admin panel, your custom_theme inherits all the structure from base theme, and applies your custom header.phtml on the theme.

Magento packages and design themes

Magento has the option to create design packages and themes as you saw on the previous example of custom_theme. This is a smart functionality because on same packages you can create more than one theme.

Now, let’s take a deep look at the main folders that manage the theme structure in Magento.

The app/design structure

In the app/design structure, we have the following folders:

The folder details are as follows:

  • adminhtml: In this folder, Magento keeps all the layout configuration files and .phtml structure of admin area.
  • frontend: In this folder, Magento keeps all the theme’s folders and their respective .phtml structure of site frontend.
  • install: This folder stores all the files of installation Magento screen.

The layout folder

Let’s take a look at the rwd theme folder:

As you can see, the rwd is a theme folder and has a template folder called default. In Magento, you can create as many template folders as you wish. The layout folders allow you to define the structure of the Magento pages through the XML files. The layout XML files has the power to manage the behavior of your .phtml file: you can incorporate CSS or JavaScript to be loaded on specific pages.

Every page on Magento is defined by a handle. A handle is a reference name that Magento uses to refer to a particular page. For example, the <cms_page> handle is used to control the layout of the pages in your Magento.

In Magento, we have two main type of handles:

  • Default handles: These manage the whole site
  • Non-default handles: These manage specific parts of the site

In the rwd theme, the .xml files are located in app/design/frontend/rwd/default/layout. Let’s take a look at an .xml layout file example:

This piece of code belongs to the page.xml layout file. We can see the <default> handle defining the .css and .js files that will be loaded on the page.

The page.xml file has the same name as its respective folder in app/design/frontend/rwd/default/template/page. This is an internal Magento control. Please keep this in mind: Magento works with a predefined naming file pattern. Keeping this in your mind can avoid unnecessary errors.

The template folder

The template folder, taking rwd as a reference, is located at app/design/frontend/rwd/default/template. Every subdirectory of template controls a specific page of Magento. The template files are the .phtml files, a mix of HTML and PHP, and they are the layout structure files. Let’s take a look at a page/1column.phtml example:

The locale folder

The locale folder has all the specific translation of the theme. Let’s imagine that you want to create a specific translation file for the rwd theme. You can create a locale file at app/design/frontend/rwd/locale/en_US/translate.csv.

The locale folder structure basically has a folder of the language (en_US), and always has the translate.csv filename.

The app/locale folder in Magento is the main translation folder. You can take a look at it to better understand. But the locale folder inside the theme folder has priority in Magento loading.

For example, if you want to create a Brazilian version of the theme, you have to duplicate the translate.csv file from app/design/frontend/rwd/locale/en_US/ to app/design/frontend/rwd/locale/pt_BR/.

This will be very useful to those who use the theme and will have to translate it in the future.

Creating new entries in translate

If you want to create a new entry in your translate.csv, first of all put this code in your PHTML file:

<?php echo $this->__('Translate test'); ?>

In CSV file, you can put the translation in this format: ‘Translate test’, ‘Translate test’.

The SKIN structure

The skin folder basically has the css and js files and images of the theme, and is located in skin/frontend/rwd/default.

Remember that Magento has a filename/folder naming pattern. The skin folder named rwd will work with rwd theme folder. If Magento has rwd as a main theme and is looking for an image that is not in the skin folder, Magento will search this image in skin/base folder. Remember also that Magento has a fall-back system. It is keeping its search in the main themes folder to find the correct file. Take advantage of this!

CMS blocks and pages

Magento has a flexible theme system. Beyond Magento code customization, the admin can create blocks and content on Magento admin panel. CMS (Content Management System) pages and blocks on Magento give you the power to embed HTML code in your page.


In this article, we covered the basic concepts of Magento theme. These may be used to change the display of the website or its functionality. These themes are interchangeable with Magento installations.

Resources for Article:

Further resources on this subject:


Please enter your comment!
Please enter your name here