adding a template to cms page in magento

adding a template to cms page in magento

July 30, 2026 · Illustrated author avatarBy Stefan Bogdanescu
adding a template to cms page in magento

Adding a Custom Template to CMS Pages in Magento

As a developer working with Magento, you might find yourself needing to add custom templates for your CMS pages. While Magento allows this, the process can sometimes be confusing or seem counterintuitive if you’re new to the platform’s architecture.

Understanding the Problem

You’ve followed the official Magento tutorial on adding CMS layout templates. However, your custom template isn’t appearing in the list of available layouts when creating a new CMS page.

The issue likely lies in how Magento handles module configuration. Your current approach is correct from a theoretical perspective, but Magento requires specific details to recognize and register your custom layout files correctly.

Step-by-Step Solution

Let’s break down the process into clear steps to ensure your custom template appears as an option for CMS pages:

  1. Configure Your Module XML File

Your config.xml file is correctly structured with the necessary parameters. However, the layout_handle attribute should match exactly what you’ll use in your layout handle later.

<global>
   <page>
      <layouts>
        <home translate="label">
           <label>Home Page</label>
           <template>page/home.phtml</template>
           <layout_handle>custom_homepage</layout_handle>
        </home>
      </layouts>
    </page>
  </global>
  1. Update Your Module Dependency

Your mycustom_template.xml file is also correctly configured, but let’s ensure the dependencies are properly set.

<config>
  <modules>
    <mycustom_template>
      <active>true</active>
      <codePool>local</codePool>
      <depends>
        <Mage_Page />
      </depends>
    </mycustom_template>
  </modules>
</config>
  1. Check Your Template Location and Naming

Ensure your home.phtml file is located at the correct path: app/design/frontend/{your_package}/{your_theme}/template/page/home.phtml.

The naming must match exactly with what you’ve specified in your layout handle (custom_homepage).

  1. Refresh Magento’s Configuration Cache

After making changes to configuration files, always clear and reindex Magento’s cache.

  1. Check Your Layout XML File

Finally, ensure that the custom layout file references this new template correctly. In app/design/frontend/{your_package}/{your_theme}/layout/page.xml, you should have something like:

<layout>
    <custom_homepage translate="label">
        <label>Home Page</label>
        <reference name="root">
            <action method="setTemplate"><template>home.phtml</template></action>
        </reference>
    </custom_homepage>
</layout>

Conclusion

Adding a custom template to Magento CMS pages requires careful configuration of the module XML files and accurate matching of layout handles and template file locations.

Always ensure your naming conventions are consistent across all related files. If you still encounter issues, double-check that no typos or inconsistent capitalization exists in your file paths and names.

Remember, Magento is a robust platform with many moving parts, so patience and careful attention to detail are key when working with its configuration files.

For more advanced customizations like this, consider exploring Laravel Company’s Magento development services for expert guidance.

Extensions Themes Configuration Errors

Our network