MagenMarket How to create a custom theme in Magento / News, Tutorials and Blog

How to create a custom theme in Magento

A Magento theme is comprised of templating files (layout, template, locale) and/or skin files (CSS, images, theme-specific JavaScript) that create the visual experience of your store. These files reside in two main directories in your Magento file system:

• “App/design” directory – Files that control how the page templates are rendered

• “Skin” directory – Files that control the visual aspects of the theme—CSS, images, etc

The files in the app/design directory only need to be accessible to the app and can be locked down further. Inside of each of these directories, the files in a theme are broken down into further subdirectories by type of file. In this article we will be showing you how to create your own custom theme for Magento 1.8. We will create a theme based on the default theme.

Directory structure for themes in custom design package (CE)

The first part of creating your custom theme is to create your directory structure.

 + design
    + frontend
       + your_new_package_name  (package)
          + your_new_theme_name  (theme in your new package)
             + layout
             + template
             + locale
  + frontend
     + your_new_package_name  (package)
        + your_new_theme_name  (theme in your new package)
           + css
           + images
           + js

Create new files


Finally, add some boiler plate to local.xml, so that custom.css and custom_js.js will get included:

    <?xml version="1.0" encoding="UTF-8"?>


            <!-- Remove callouts and rarely used stuff -->
            <remove name="right.poll"/>
            <remove name="right.permanent.callout"/>
            <remove name="left.permanent.callout"/>
            <remove name="paypal.partner.right.logo"/>

            <!-- add the local stylesheet -->
            <reference name="head">
                <action method="addCss"><stylesheet>css/custom.css</stylesheet></action>
                <action method="addItem"><type>skin_js</type><name>js/custom_js.js</name></action>  


The Javascript files can be added to your theme by adding the following to local.xml: A well coded theme should have the following traits:

  1. A single layout file, named local.xml, where all layout updates are placed.
  2. no layout files with the same name as any layout file in the base theme.
  3. no css files with the same name as any css file in the default skin.
  4. no .phtml template files, except for those that were modified to support the new theme. (Usually this number will be very small.)

Applying your new package and theme to your website

Once you have created the skeleton directory structure to hold your new design package and theme, you will need to apply it to your Magento store so that you can see changes as you work. To see your new theme as you develop it, be sure to apply it to your development website using the Magento Admin Panel. On Admin section, go to  System -> Configuration -> Design tab. In the Package panel, set the Current Package Name to whatever you have named <your_package_name>. In the Themes panel, set the Default theme to default if you are creating a new theme in CE or to whatever you have named <your_theme_name>. Look image below.

Applying your new package and theme to your website Applying your new package and theme to your website

Understanding layout XML files


Using xml instead of other methods (JSON, .ini files, include / require functions) allows us to change many aspects on our page without manually changing the .phtml files. This chapter refers to our default theme so after changing the theme (as we have done above) the paths will also change.

Layout / page structure

The core Layout is defined by page.xml which is located in /app/design/frontend/base/default/layout/page.xml. There are two large tasks layout carries out. First it defines the visual layout for your store. By default Magento uses a 3-column layout, so it defines use of 3columns.phtml (Located in your template/page/ folder):

<block type="page/html" name="root" output="toHtml" template="page/3columns.phtml">

If you wanted to change your store a 2-column layout, for instance, you would reference this section in local.xml, and use an action to change to the .phtml you’d like to use (in this case, 2columns-left.phtml or 2columns-right.phtml).

    <reference name="root">
        <action method="setTemplate"><template>page/2columns-right.phtml</template>
        <!-- Mark root page block that template is applied -->
        <action method="setIsHandle"><applied>1</applied></action>

Reference name values/attributes:

  • root - we will change it mostly to set up another .phtml file as a root template ex. (1column.phtml , 2columns-left.phtml ,2columns-right.phtml etc.).
  • head - as this reffers to our <HEAD> section on page, we will use this reference name to reflect our changes in this section.
  • - defines our content for top menu section.
  • left - defines our content for left column.
  • right - as above but for right column.
  • content - defines blocks placed in main content of our page.
  • footer - defines blocks placed in footer area.

if you wanted to modify category default page, for instance, you add below code in local.xml

<?xml version="1.0" encoding="UTF-8"?>
        Category default layout
                <reference name="root">
            <action method="setTemplate"><template>page/2columns-right.phtml</template></action>

                <reference name="head">


                <reference name="header">


                <reference name="left">


                <reference name="right">
                        <block type="catalog/navigation" name="category.list" before="-" template="catalog/navigation/category_list.phtml"/>

                <reference name="content">


                <reference name="footer">


Same with pages <catalog_product_view>, <cms_page>, etc

Understanding .phtml files


Phtml files are template files that handle the output to browser. They are nothing more than html files with nested php tags. We use them to style our page and the look of our site. Changing .phtml files requires basic knowledge about XHTML, CSS and understanding how to use PHP functions on a page. IMPORTANT: Before changing a .phtml file, it has to be copied from the base (or default) theme, into the new theme. When Magento finds one of these files in your new theme, it will ignore the .phtml file from the base theme, so it is important to ONLY copy over the files that you absolutely need to modify. This will minimize errors when updating Magento. The additional effort required to individually copy the 4-5 files you eventually modify will more than make up for itself the first time Magento needs to be updated.


Hopefully this article will help developers to start creating their own custom themes. If there are any bits of this article that aren't clear, please let me know and I will do my best to clarify.