Developing custom PHP (PHTML) template files for a Magento package or theme offers more flexibility and greater latitude than simply updating existing files.
But sometimes traversing the popular platform's more than 10,000 files and 3,300 folders can be a little challenging. So in this tutorial, I will describe one way to add a custom PHTML template to the Magento layout menu found in the CMS section of the administration panel. From this menu, one can assign the new PHTML template, for example, to the home page, about pages, or other unique sections of the site.
For this article, I used version 1.4.1.1 of Magento's Community edition.
No. 1: Add The New Template File
The first step in this process is to create the new PHTML template file. You don't need to develop the template yet. Just create an empty placeholder or copy and rename an existing file.
The important thing is to save your new PHTML template file to app > design > frontend > default > modern > template > page, wherein "default" is the name of the package and "modern" is the name of the template. If your package was named "Fred" and your theme was called "Astaire," the path would be app > design > frontend > Fred > Astaire > template > page.
No. 2: Mirror the Core File Structure in Local
From a development standpoint, one of Magento's best features is its ability to mirror core files. In this way, you can make changes to what are clearly core functions or files without worrying about future updates erasing those changes or breaking your site.
Navigate to app > code > local. Create a new folder called "Mage." Inside of the "Mage" folder, create a new folder named "Page." Open "Page" and create a folder called "etc." In this way, you will have mimicked the folder structure of one portion of the Magento core.
No. 3: Get a Copy of config.xml
Now head to app > code > core > Mage > Page > etc, where you will find a file named config.xml. Copy this file and save it to the folder you created in step two above.
No. 4: Add Your Template to the XML
Open config.xml in your favorite code editor and head to about line 47. In context, the code should look like the following.
<page>
<layouts>
<empty module="page" translate="label">
<label>Empty</label>
<template>page/one-column.phtml</template>
<layout_handle>page_empty</layout_handle>
</empty>
<one_column module="page" translate="label">
<label>1 column</label>
<template>page/1column.phtml</template>
<layout_handle>page_one_column</layout_handle>
<is_default>1</is_default>
</one_column>
<two_columns_left module="page" translate="label">
<label>2 columns with left bar</label>
<template>page/2columns-left.phtml</template>
<layout_handle>page_two_columns_left</layout_handle>
</two_columns_left>
<two_columns_right module="page" translate="label">
<label>2 columns with right bar</label>
<template>page/2columns-right.phtml</template>
<layout_handle>page_two_columns_right</layout_handle>
</two_columns_right>
<three_columns module="page" translate="label">
<label>3 columns</label>
<template>page/3columns.phtml</template>
<layout_handle>page_three_columns</layout_handle>
</three_columns>
</layouts>
</page>
</global>
Specifically, you want to find the <layouts> tag and the entry that immediately follows it.
<layouts>
<empty module="page" translate="label">
<label>Empty</label>
<template>page/one-column.phtml</template>
<layout_handle>page_empty</layout_handle>
</empty>
The code that starts with the tag <empty> describes one PHTML template option. If you looked in the Magento administration panel at CMS > Pages > Home page > Design, you would see that "Empty" is one of the layout template options that can be assigned to a page.
In config.xml, I am going to create a similar entry for my custom PHTML that I have named 12columns.phtml. I start this process by creating a semantic XML tag, assigning it the same module as the other templates listed in this XML file.
<twelve_columns module="page" translate="label">
Experience tells me that using the number "12" rather than the word "twelve" would have caused an error.
Defining a "label" for my template comes next. This label will appear on the layouts drop-down menu on the Magento administration panel, so make it descriptive.
<label>12 columns</label>
The template tag describes where Magento can find my PHTML template.
<template>page/12columns.phtml</template>
Next, I provide a layout handle and close the entry.
<layout_handle>page_12_columns</layout_handle> </twelve_columns>
The completed code looks like this:
<twelve_columns module="page" translate="label">
<label>12 columns</label>
<template>page/12columns.phtml</template>
<layout_handle>page_12_columns</layout_handle>
</twelve_columns>
Don't forget to save config.xml.
No. 5: Update Mage_All.xml
I need to update MageAll.xml_, which can be found at app > etc > modules.
In this file, I need to locate the "Mage_Page" module. It will look like the following code.
<Mage_Page>
<active>true</active>
<codePool>core</codePool>
<depends>
<Mage_Core/>
</depends>
</Mage_Page>
Between the "codePool" tags, I need to change "core" to "local."
<Mage_Page>
<active>true</active>
<codePool>local</codePool>
<depends>
<Mage_Core/>
</depends>
</Mage_Page>
No. 6: Flush Your Cache
In order to see these changes take on site, I need to make sure that Magento has not cached the configuration pages. In the administration panel, I go to System > Cache Management. Here I click "Flush Magento Cache."
No. 7: Admire Your Handy Work
If I go to CMS > Pages > Home page > Design in the Magento administration panel, I find that my 12-columns template can now be assigned to a page.
Using these simple steps, it is fairly easy to assign custom templates to pages in Magento. Of course, I still have to develop my 12-column page template, but at least I will be able to see it on page as I go through the development process.
