Adding CMS Layout Templates

Last modified by lektro on Fri, July 13, 2012 06:41
Source|Old Revisions  

You may find that you want to add additional layout template options to the CMS section that can be chosen when creating or editing a page in the admin interface.

Step 1: Create New Template

Create a new template file in the following directory (you may want to simply copy an existing template, such as 1column.phtml) and name it with an appropriate name (ie: home.phtml if that template will be used for your home page).


whereas YOUR_INTERFACE typically remains “default” and YOUR_THEME can also be “default” (please see Design-Guide about proper naming of themes and interfaces)

Step 2: Create a new module

In order to customize the configuration of Magento without hacking into existing files we need to create a new module. This is very simple. The module will only contain a configuration file that updates the section that lists the available templates for the CMS.

We’ll call the module Banana (just a example) and its package name Fruit (also just an example).

Note: You may (and probably should) choose a different module/package name, just be consistent throughout the process.

We need to tell Magento about our new module, so create a new file:


with the following content:

  1. <?xml version="1.0"?>
  2. <config>
  3.   <modules>
  4.     <Fruit_Banana>
  5.       <active>true</active>
  6.       <codePool>local</codePool>
  7.       <depends>
  8.         <Mage_Page />
  9.       </depends>
  10.     </Fruit_Banana>
  11.   </modules>
  12. </config>

Now we need to actually create the module itself. Create the following file (and the neccessary folder structure):


with the following content:

  1. <?xml version="1.0"?>
  2. <config>
  3.   <modules>
  4.     <Fruit_Banana>
  5.       <version>0.1.0</version>
  6.     </Fruit_Banana>
  7.   </modules>
  8.   <global>
  9.     <page>
  10.       <layouts>
  11.         <INTERNAL_NAME_FOR_YOUR_NEW_LAYOUT translate="label">
  12.           <label>LAYOUT_NAME</label>
  13.           <template>page/LAYOUT_FILE_NAME.phtml</template>
  14.           <layout_handle>LAYOUT_HANDLE</layout_handle>
  16.         <!-- add more layouts here -->
  17.       </layouts>
  18.     </page>
  19.   </global>
  20. </config>

The capitalized parts need to be filled in by you.

Any new layouts you want to add should to be in the following format:

  1. <layout_description translate="label">
  2.     <label>Layout Name</label>
  3.     <template>page/template_name.phtml</template>
  4.     <!-- defining the layout handle is optional -->
  5. </layout_description>

Using the same steps, and modifying them for each template, you can create new layout templates for use on any CMS page.

You're done!

Also, take a look at the config.xml of the Page module in the Mage package; it defines the layouts that come with Magento:


On line ~47(version find:

  1. <page>
  2.     <layouts>
  3.         <empty module="page" translate="label">
  4.             <label>Empty</label>
  5.             <template>page/empty.phtml</template>
  6.             <layout_handle>page_empty</layout_handle>
  7.         </empty>
  8.         <one_column module="page" translate="label">
  9.             <label>1 column</label>
  10.             <template>page/1column.phtml</template>
  11.             <layout_handle>page_one_column</layout_handle>
  12.             <is_default>1</is_default>
  13.         </one_column>
  14.         <two_columns_left module="page" translate="label">
  15.             <label>2 columns with left bar</label>
  16.             <template>page/2columns-left.phtml</template>
  17.             <layout_handle>page_two_columns_left</layout_handle>
  18.         </two_columns_left>
  19.         <two_columns_right module="page" translate="label">
  20.             <label>2 columns with right bar</label>
  21.             <template>page/2columns-right.phtml</template>
  22.             <layout_handle>page_two_columns_right</layout_handle>
  23.         </two_columns_right>
  24.         <three_columns module="page" translate="label">
  25.             <label>3 columns</label>
  26.             <template>page/3columns.phtml</template>
  27.             <layout_handle>page_three_columns</layout_handle>
  28.         </three_columns>
  29.     </layouts>
  30. </page>

If you don’t care for updating Magento and love hacking core files (something you generally shouldn’t do, unless you know what you’re doing) you can also just update this file (app/code/core/Mage/Page/etc/config.xml). Beware though that Magento updates can override the changes you’ve made.