I'm currently working through my first Magento 2 website and I'm having some trouble understanding how to create custom page templates.

I've read the answer provided here but still have some questions.

Do I need to structure the template in xml? Or can I use html and save the file as a .phtml? Where do I declare which template belongs to which page? In the the layouts.xml?


I have tried to go into more details about how to display a template on to a page, if I've missed anything out please let me know.

Find out the module name (where you want to add the block)

You need to declare the block and tell it which template to use, to find out where to declare the block you need to think where you want it to display (eg on every page or just the category page).

You then need to find out the module name for the page/section you want to place the block on, you can find the default ones listed in magento2/app/design/frontend/Magento/blank for example:

  • Magento_Cms
  • Magento_Checkout
  • Magento_Wishlist

Create the directories

Once you have the module name you can create the directory, so if you was editing a CMS page you would create magento2/app/design/frontend/**PackageName**/**themeName**/Magento_Cms

Then within the directory above you create a directory named layout, and this is where you place the XML files (if you're extending XML that is, overwriting XML is a slightly different story).

Adding the XML

In my example I will add a block only to the product page and declare which template to use.

As I only want the block to display on product pages I need to create catalog_product_view.xml within the layout directory we created, you can usually find out the layout handle by looking at the class added to the body tag.

If you aren't too sure about layout handles I recommend reading through the layout docs

Declare the block/template

This is the markup you need to position a block:

  • The xml tag
  • The page tag
  • The container (or block) you want to add your block to (referenceContainer). You can find the name of blocks/container by looking at a parent's XML
  • The block itself (block)

    <?xml version="1.0" ?>
    <page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
        <referenceContainer name="product.info.main">
            <block class="Magento\Framework\View\Element\Template" name="example_name" template="Magento_Catalog::template-example.phtml" />

This will add a block with the following:

  • It will display within the product.info.main container
  • It uses the default template block class allowing us to assign a template to the block
  • It has the name example_name so we can manipulate it elsewhere
  • It uses the template Magento_Catalog::template-example.phtml which is located in magento2/app/design/frontend/**PackageName**/**themeName**/Magento_Catalog/templates/template-example.phtml
  • In the above point it's important to note the Magento_Catalog:: part before the actual template, as this tells Magento the template is found within the Magento_Catalog module. Another example would be Magento_Cms if it was a CMS page.

This will render the block out at the bottom of the product info section like so (it's the lorem ipsum text I added), forgive me for the red BG I was testing something out before I read this question.

template test

phtml vs html

You will need to use .phtml (a mixture of PHP and HTML), I believe .html can only be used with Knockout JS templates. I'm not 100% sure on that but that has been my results when attempting to use .html.

  • Amazing, thank you! Does the same apply to replacing the homepage as a whole? – evilscary Apr 8 '16 at 8:21
  • As in adding a template to the homepage or replace the CMS content with a template? – Ben Crook Apr 8 '16 at 8:22
  • Replacing the CMS with a template – evilscary Apr 8 '16 at 8:36
  • 1
    There's a few methods for this, the question is answered here - stackoverflow.com/questions/34288366/… - The easiest way would be to reference the block in the CMS content, then you (or a client) can easily remove the template without making any codebase changes. If you know this will never be removed then I'd use the XML method. – Ben Crook Apr 8 '16 at 9:07

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.