Since we at Bricks & Mortar Creative are such big fans of Magento for our e-commerce projects, we wanted to start a weekly Blog series called "Magento Mondays" where we will cover various Magento topics as well as give away free Magento extensions that we've built. For today's inaugural post, I wanted to focus on something that tends to trip up a lot of beginning Magento developers, creating a custom template for your custom Magento themes.
Unlike registering a new page template in a CMS like Wordpress, Magento actually has you register the template or templates as a local extension. Now while this process is very simple to run through, a lot of developers who are just starting out will here "Custom Magento Extension" and run in the direction as quickly as possible. Hopefully this post will alleviate some of those fears and pull back some of the mystery that is Magento. So without further ado...
Step 1. Setting Up Your Extension Structure
The first thing you'll want to do is start setting up your extension files. This extension will live in your app/code/local directory, so the first thing you'll want to do is navigate to that directory and create a new directory for your extension, ours will be called "Bricks". Make sure to capitalize the first letter as this is important for name spacing. Now within your extension directory, you will want to create two new directories, "Templates" and "etc", where each directory is within the one before it. The directory entire path should look like this: "app > code > local > Bricks > Templates > etc".
Step 2. Setting Up Your Extension Config File
Next, we'll want to create a new file called 'config.xml' within the 'etc' directory you just created. This file is where almost all of the magic is going to happen, so it's important that this file is formatted properly. Once you've created the new file you'll want to paste in the following code:
[xml]
<?xml version="1.0"?>
<config>
<modules>
<Bricks_Templates>
<version>0.1.0</version>
</Bricks_Templates>
</modules>
<global>
<page>
<layouts>
<homepage translate="label">
<label>Home</label>
<template>page/home.phtml</template>
<layout_handle>home_page</layout_handle>
</homepage>
<!-- add more layouts here -->
</layouts>
</page>
</global>
</config>
[/xml]
There are a couple of important areas to point out in this code block. First, you'll notice that under the "modules" section, the module name is capitalized and also matches our directory name spacing. Second, you'll notice that the custom "homepage" layout is stored within our global page layouts, so can be accessed just as the standard 1 column or 2 column templates can be accessed. Now that you have this file created and saved it's time to turn the extension on.
Step 3. Enabling Your Custom Magento Extension
Now that you've setup the bulk of your extension, you'll need to let Magento know that it exists and that you'd like to turn it on. You do this by creating another xml file within your modules directory, or app > etc > modules. This new file will need to be named after your extension name space, so ours will be called "Bricks_Templates.xml" and the full file path will be app > etc > modules > Bricks_Templates.xml. Once you have this file created, open it up and enter in the following code:
[xml]
<?xml version="1.0"?>
<config>
<modules>
<Bricks_Templates>
<active>true</active>
<codePool>local</codePool>
<depends>
<Mage_Page/>
</depends>
</Bricks_Templates>
</modules>
</config>
[/xml]
You will see that we're telling Magento to look in the "Local" code pool for an extension called "Bricks_Templates" and that it is active because it's status is set to true. If you wanted to disable the extension while leaving all of it's files in place, you could do that by setting it's active status to "false". Now that you've turned on your extension, all that's left is to create your custom page template.
Step 4. Create Your Custom Page Template
In our config.xml file, we told Magento that our custom home page template would be found at 'page/home.phtml', so we'll need to create a home.phtml file within the 'page' directory of our template files. In this case I will use the 'base' theme for my example, so the file would be included at 'app > design > frontend > base > template > page'. You can add whatever code you would like in to this new page template, whether it be static HTML, a CMS block, or other custom Magento code of your choosing. Once you've finished the setup of this page template, your custom page template extension is ready to be used on the store of your choosing.
Step 5. Creating Additional Custom Page Templates
Let's assume that now that you've added your custom Home Page template, you now want to add in a custom About Page template as well. To do this, all you will need to do is open up your extension config file and put your cursor on the line directly after you close your home page layout. You will then register another page here in exactly the same fashion, so it would look something like this:
[xml]
<?xml version="1.0"?>
<config>
<modules>
<Bricks_Templates>
<version>0.1.0</version>
</Bricks_Templates>
</modules>
<global>
<page>
<layouts>
<homepage translate="label">
<label>Home</label>
<template>page/home.phtml</template>
<layout_handle>home_page</layout_handle>
</homepage>
<!-- add more layouts here -->
<about_page>
<label>About Page</label>
<template>page/about.phtml</template>
</about_page>
</layouts>
</page>
</global>
</config>
[/xml]
As you can see, we've registered a new page template that points to a brand new template file, about.phtml. All you would need to do at this point is make sure to include the about.phtml template within your Theme's template directory along with your custom home page template. Now that all of your page templates are created, you'll want to put them in to use on Magento.
Step 5. Using Your Custom Page Templates in Magento
Now that the page templates are created and ready to be used, you'll want to include them on the necessary pages. To do this, open up your Magento admin dashboard and navigate to "CMS > Pages". Once on this page, go ahead and open the "Home Page" you've created and click on the "Design" tab in the left hand navigation options. At the very top of the Design view, you should see a dropdown option with the label "Layout". Click on this dropdown and you should see your newly created custom template available to be used. Simply select the template, save the page, refresh your cache and you should be all good to go.
We've also made our files available for you to download, use, and fork as needed, feel free to use however you would like.
[ed_download_file id ="1063" title="yes" show_content="yes"]