Magento theme customization

Please note that Magento theme customization is far beyond the scope of this user guide. This chapter is only for informational purposes, you should treat it as a starting point. Before you start to customize the theme you need to be sure that you know what you’re doing.

Magento is based on a theming concept referred to as parent/child theming – changes in the theme can be implemented without modifying the original. Magento’s “base” theme serves as a parent theme for any custom theme.

The correct way to customize the theme in Magento is to create your own sub-theme of the default theme in the design package. You should never edit original design package files. Files that need to be changed can be copied from the default theme of the design package to your custom sub-theme inside that package.

This way you can override any file of the design package. And you can be sure that when something goes wrong you can simply delete your custom sub-theme without breaking the original files.

How to modify the theme

Customize images

The easiest way to customize the theme is to modify or replace default images.

Custom content images

All images which are used in this theme (such as page backgrounds, patterns, icons, banners inside blocks etc.) are stored in media/wysiwyg/magenthemes/mtvela/ directory:

  • patterns – patterns which can be applied for the main sections of the page in System > Configuration > MT Abc> Theme Design. (**Abc** is the name of Magento theme)

To add custom pattern, rename one of the files which name starts with default., for example: default.custom1.png → custom1.png

(by removing the first part of the name: default. – the dot also has to be removed). Then, replace that file with your custom image. Custom image will be available in the admin panel as custom pattern.

  • _backgrounds – images which can be used as page background and other images for static blocks. You can create subdirectories here for custom images.
  • brands – the logo which can be used in Brand Slider.
  • slideshow – images for the home page slideshow.

Interface images

All interface images and icons are stored in skin/frontend/mtquartz/default/images/ directory. You can replace those files with custom files. You can also use PSD files included with this theme to create your own versions of images.

Modify template files

Magento consists of dozens of template files, each one is used to render a block of content in the frontend of the store. When you want to customize a theme, you can display the names of template file of every block in the frontend by enabling Magento’s Template Path Hints.

Note: to enable Magento’s Template Path Hints go to System > Configuration > Developer. Select your current website under Current Configuration Scope in the top left corner of the admin panel, otherwise Template Path Hints settings will not be visible.

This way you can easily check which template files you need to edit to customize specific sections of Magento.

Create custom sub-theme

The correct way to customize the theme in Magento is to create your own sub-theme. You should never edit the original files. Files that need to be modified can be copied to your custom sub-theme.

Note: to check which template file you need to edit to customize specific section of Magento you can enable Magento’s Template Path Hints. Refer to chapter Modify template files for more details.
If the file which you selected with Template Path Hints doesn’t exist in MT A package (a theme doesn’t need to override all template files from Magento’s “base” theme), you can copy that file from Magento’s “base” theme to your custom sub-theme inside MT Yoming package.

By creating custom sub-theme:

  • You can override any file.
  • You can create upgrade-proof modifications.
  • You can be sure that when something goes wrong you can simply delete your sub-theme without breaking the original files.

For more infomation about how to switch to your custom sub theme, please go to chapter How to switch to your custom sub theme

Magento theme customization

Design packages

Themes in Magento are grouped together into design packages (in earlier versions called interfaces). By default Magento Community Edition has two packages named “base” and “default”.

Note: do not edit files in the “base” package and do not create custom sub-themes inside the “base” package.

Every design package in Magento comes with a default theme named “default” which is the main theme in the design package. When administrator assigns a package to the store, Magento automatically looks for the theme named “default” in that package.

Design package can also contain variations of the “default” theme. This variations are often called sub-themes because they inherit all the files from the “default” theme (from the same package) and from the “base” package. Inside the sub-theme you can override any file of the “default” theme. Sub-theme can even consists of a single file – other files will be inherited from the “default” theme from the package. This is called a fallback mechanism because Magento always falls back to the next theme in the hierarchy to find the requested file. Fallback is described later in this chapter.

Theme structure

Magento themes consists of many files like HTML templates, CSS stylesheets, images etc. All files are split between two directories:

  • app/design/frontend/package_name/theme_name/

Templates directory – contains the layout files, HTML templates and translations

  • skin/frontend/package_name/theme_name/

Skin directory – contains CSS stylesheets, images and theme-specific JavaScript
files

where package_name indicates the package name and theme_name indicates the theme name.

Template files are organized as follows:

  • layout – directory contains XML files which define page structure
  • template – directory contains template files (.phtml), a mix of HTML and PHP
  • locale – directory contains CSV files with translation strings

Skin files are organized as follows:

  • css – directory contains CSS files
  • images – directory contains images
  • js – directory contains theme-specific JavaScript files

Fallback mechanism

Understanding fallback mechanism is very important when you want to customize the theme, so let’s see a simple example.

Let’s say we have a design package named “helloworld” with custom sub-theme named “new”. Package files are organized as follows:

  • app/design/frontend/helloworld/new/
  • skin/frontend/helloworld/new/

Let’s also assume that your custom sub-theme contains a CSS file called “menu.css” located in skin/frontend/helloworld/new/css/menu.css

If your custom theme requests “menu.css” but Magento can’t find it in your custom sub-theme in skin/frontend/helloworld/new/css/menu.css, Magento will try to find that file in the next theme in the hierarchy. Next theme in the hierarchy is the “default” theme in “helloworld” package so Magento will search in skin/frontend/helloworld/default/css/menu.css.

If the file is not there, Magento will continue until it locates the file. Next theme in the hierarchy is the “default” theme in “base” package: skin/frontend/base/default/css/menu.css. The “default” theme in the “base” package is the final fallback point in the hierarchy.

Let’s take a look again at the entire fallback hierarchy:

  1. Look for the requested file in custom sub-theme: skin/frontend/helloworld/new/
  2. If not found, look for the file in the “default” theme in the design package: skin/frontend/helloworld/default/
  3. If not found, look for the file in the “default” theme in “base” design pack skin/frontend/base/default/

The first theme in hierarchy is the theme that you assign through the admin panel (in System > Configuration > Design). The last theme in hierarchy is the “default” theme in “base” design package.

Thanks to the fallback mechanism there is no need to copy all the default theme files to your custom sub-theme when you want to make some changes in your theme. You only copy over the files that you want to edit. Other files will be inherited from the “default” theme in the package and from the “base” package.

The most important advantages of the fallback mechanism:

  • selected functionality can be shared between many themes
  • less code to maintain
  • custom themes are update-proof: you don’t edit original files, so your changes are not overwritten after theme updated

Examples of custom sub-theme

Let’s see some examples.

Example 1:

You have just installed a custom design package named helloworld with the default theme (named “default”) inside. Let’s say that you want to change the font color of the product name on product page.
Package files are organized as follows:

  • app/design/frontend/helloworld/default/
  • skin/frontend/helloworld/default/

The correct way to customize the “default” theme is to create your own sub-theme in which you will override selected elements of the default theme.

1.Let’s call the new theme my_world. Create the following folder inside the helloworld package: skin/frontend/helloworld/my_world/

The name of that folder is the name by which Magento will recognize your theme.

2.Create a copy of the CSS file skin/frontend/helloworld/default/css/styles.css

And paste it into your sub-theme directory: skin/frontend/helloworld/my_world/css/styles.css

Note that the directory structure inside the sub-theme must replicate the directory structure of the default theme:

  • skin/frontend/helloworld/default/css/styles.css
  • skin/frontend/helloworld/my_world/css/styles.css

3.Open skin/frontend/helloworld/my_world/css/styles.css style sheet and add these lines at the end of the file to override the default color of the product name:

Go to: ↑ Table of Contents 59
.product-view .product-shop .product-name h1 { color:#f00; }

4.Enable the new sub-theme in the admin panel. Go to System > Configuration > Design > Themes and enter my_world (the sub-theme name) in the default field:

enable-sub-theme

Finally, refresh Magento cache. From now on your customization will override the default styling of the helloworld package.

Example 2

In the previous example we created custom sub-theme named my_world in the helloworld design package to override one of the skin files of the default theme. But you can also override template files located in app/design/frontend, not only skin files.

Continuing with the previous example, let’s override the contact form template to add simple image banner above the form.

  1. Create the following folder for the “my_world” template files in the “helloworld” package:

app/design/frontend/helloworld/my_world/

The name of the folder has to be the same as the name of the folder which you created for the skin files (skin/frontend/helloworld/my_world/)

  • Go to: ↑ Table of Contents 60
  • The file which is responsible for the contact form is located here: app/design/frontend/helloworld/default/template/contacts/form.phtml

Create a copy of that file and paste it into your sub-theme directory (remember that the directory structure inside the sub-theme must replicate the directory structure of the default theme): app/design/frontend/helloworld/my_world/template/contacts/form.phtml

Note that if the form.phtml file doesn’t exist in the helloworld package, you can copy it from the base package (keeping the directory structure intact). base package contains all the files that control Magento’s default behavior. If the requested file is not found in your custom sub-theme, Magento will try to find that file in the “default” theme from the package. If the file is not found, Magento will call the file from the “base” package.

Thanks to the fallback mechanism, in our example Magento will try to find the file in the following order:

  1. app/design/frontend/helloworld/my_world/template/contacts/form.phtml
  2. app/design/frontend/helloworld/default/template/contacts/form.phtml
  3. app/design/frontend/base/default/template/contacts/form.phtml
  4. Open app/design/frontend/helloworld/my_world/template/contacts/form.phtml file and insert image banner before the beginning of the contact form.
  5. If you didn’t enable the new sub-theme in the previous example, you need to do it now. Go to System > Configuration > Design > Themes and enter my_world (the sub-theme name) in the default field. Finally, refresh Magento cache to display changes you have made.
  6. Go to: ↑ Table of Contents 6

Summary

  • Themes in Magento are grouped together into design packages.
  • By default Magento comes with the package named “base” which contains all the files that control Magento’s default behavior.
  • Every design package in Magento comes with a default theme named “default” which is the main theme of the design package.
  • Design package can contain variations (sub-themes) of the “default” theme. They inherit all the files from the “default” theme (from the same package) and from the “base” package.
  • The correct way to customize the theme in Magento is to create your own sub- theme. You should never edit original design package files. Files that need to be changed can be copied to your custom sub-theme.
  • This way you can override any file of any design package. And you can be sure that when something goes wrong you can simply delete your custom sub-theme without breaking the original files.
  • Magento use fallback mechanism to make custom themes easier to maintain and upgrade-proof.
  • The first theme in the fallback hierarchy is the theme that you assign through the admin panel (in System > Configuration > Design). The last theme in hierarchy is the “default” theme in “base” design package.
  • If the requested file is not found in your custom sub-theme, Magento will try to find that file in the “default” theme from the package. If the file is not found, Magento will call the file from the “base” package.
  • The directory structure inside the sub-theme must replicate the directory structure of the default theme.