Adding Magento 2 Module Layout Updates

18th October 2016

A common task within Magento is to add layout updates to a custom module. These layout updates extend existing Magento layout configuration and can add additional template files to your storefront. This article will demonstrate adding Magento 2 module layout updates.

To start with, register a custom module that will hold your layout updates.

Create a module.xml file.

// app/code/Siphor/Custom/etc/module.xml
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="Siphor_Custom" setup_version="1.0.0" />
</config>

Then add the module’s registration.php file.

// app/code/Siphor/Custom/registration.php
<?php
\Magento\Framework\Component\ComponentRegistrar::register(
    \Magento\Framework\Component\ComponentRegistrar::MODULE,
    'Siphor_Custom',
    __DIR__
);

Then, run the following commands to enable your module.

$ /path/to/your/php bin/magento module:enable --clear-static-content Siphor_Custom
$ /path/to/your/php bin/magento setup:upgrade

As a simple example, this module will add a custom template to the homepage that will contain some text.

Create the following directories within your module’s directory structure. The directories should be within the following location.

app/code/Siphor/Custom/view/frontend/layout
app/code/Siphor/Custom/view/frontend/templates

To extend layout updates specific to the homepage, you can add a cms_index_index.xml file within the layout directory.

This file will contain the following layout updates.

// app/code/Siphor/Custom/view/frontend/layout/cms_index_index.xml
<?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">
    <body>
        <referenceContainer name="content">
            <block class="Magento\Framework\View\Element\Template" name="siphor.custom.block" as="customBlock" template="Siphor_Custom::custom.phtml" />
        </referenceContainer>
    </body>
</page>

As you can see, a block node is added within the ‘content’ referenceContainer node. The block class, ‘Magento\Framework\View\Element\Template’, is similar to Magento 1’s ‘core/template’ block type.

The ‘name’ and ‘as’ attributes also make a return in Magento 2, so we set these attribute values that will relate to our block we’re trying to add.

The ‘template’ attribute of the block node contains our template name. This template will be added within the templates directory that was made.

For simplicity, the template file will contain the following.

// app/code/Siphor/Custom/view/frontend/templates/custom.phtml
<h1>We are here!</h1>

If you then clear your cache and refresh any pre-generated static files that Magento creates, you should see the template appear on the homepage.

Adding Magento 2 Module Layout Updates

Note: This article is based on Magento CE version 2.1.