Magento 2 Development Workshop Learn More

Magento 2 for Beginners

10 lessons

Template and Layout Rendering

Template and Layout Rendering

Magento 2 provides a powerful mechanism on extending e-commerce functionality with custom templates. It also allows to provide additional pieces of content by utilizing a declarative approach.

Lesson Overview

In this lesson we are going to learn the following:

  • How to create a template?
  • How to render a template on a custom Magento 2 page?
  • How to add a template via layout configuration file?

Before we begin

Here is the structure of the module, we are going to start with:

Module Structure Template and Layout Rendering

For this tutorial, I've created the MageMastery_FirstLayout module with the registration.php and module.xml files. And the module has been successfully registered with the bin/magento setup:upgrade CLI command.

The registration.php file:


use Magento\Framework\Component\ComponentRegistrar;


The module.xml file:

<?xml version="1.0"?>
<config xmlns:xsi="" 
    <module name="MageMastery_FirstLayout" />

For more information about the module creation and registration, please refer to the previous lesson A Module in Magento 2.

In addition to this, I've added a route.xml file with an Action Controller class. These two files allows to access a custom page that has been declared in the MageMastery_FirstLayout module.

The routes.xml file content is the following:

<?xml version="1.0"?>
<config xmlns:xsi="" 
    <router id="standard">
        <route id="magemastery_firstlayout" frontName="firstlayout">
            <module name="MageMastery_FirstLayout" />

The routes.xml file is located in the MageMastery/FirstLayout/etc/frontend directory. This configuration allows to access a module's controller by using the "firstlayout" URI path of the URL.

And the Action Controller class located in the MageMastery/FirstLayout/Controller/Page/View.php file, the content is:



namespace MageMastery\FirstLayout\Controller\Page;

use Magento\Framework\App\Action\Action;
use Magento\Framework\Controller\ResultFactory;
use Magento\Framework\View\Result\Page;

class View extends Action
    public function execute()
        /** @var Page $resultPage */
        return $this->resultFactory->create(ResultFactory::TYPE_PAGE);

New Page Type Object

From the Create a Page in Magento 2 lesson we've learned how to create a custom page and return a JSON-format data. As you've noticed, there is an instance of the Magento\Framework\View\Result\Page class returned from the execute() method.

return $this->resultFactory->create(ResultFactory::TYPE_PAGE);

The idea behind creating a TYPE_PAGE type of a result object is to trigger the Magento 2 rendering mechanism.


There is a new directory that we've to learn in this lesson. The directory is called view. As we've discussed in the previous tutorial, Magento 2 application uses different configuration areas. It is also applicable for rendering purposes. The frontend and adminhtml are the two areas we can use in order to render a custom content on a Storefront and Admin area accordingly.

Rendering areas of a module in Magento 2

There are other files and directories might be located in the view directories, however, this is outside of the lesson. In the upcoming lessons we will learn about different rendering areas and how it can be used to provide different files for different areas.

In case we want to render something on a Storefront, we have to create a view/frontend directory. Inside this directory, all the files should be added and further to be executed in a frontend area. This happens upon Magento 2 rendering. Inside frontend directory, there are two directories. The layout directory is used to place layout configuration files of the MageMastery_FirstLayout module.

The templates directory, contains PHTML templates that have to be rendered on a Magento 2 Storefront.

The view directory structure

Layout Configuration File

The new magemastery_firstlayout_page_view.xml layout configuration file has to be added to the MageMastery/FirstLayout/view/frontend/layout directory.

<?xml version="1.0"?>
<page xmlns:xsi="" 
        <referenceContainer name="content">
            <block class="Magento\Framework\View\Element\Template"
                   template="MageMastery_FirstLayout::example.phtml" />

The format of the layout file is pretty much similar to all the XML files in Magento 2. The root node <page /> allows to add configuration and templates that have to be rendered on a page.

In order to add a custom example.phtml template from the view/frontend/templates directory, the XML declaration should be created and added to the layout configuration file.

There are 3 pieces of information or node arguments have to be declared as part of the block node. Let's have a look at the block declaration example:

<block class="Magento\Framework\View\Element\Template"
       template="MageMastery_FirstLayout::example.phtml" />

The class argument is responsible for providing a Block class name. The Block class is used to render a PHTML template file. The name of the block is magemastery.first.layout.example. The name has to be unique and can be used to reference to a block from the other layout configuration files and templates. For example, the content name or alias of a block is defined in one of the Magento 2 modules. We use the content block name to reference and add a block for rendering the example.phtml template file.

The path to a template. It usually includes a name of a module joined with "::" template file name. The example.phtml file should be located in the MageMastery/FirstLayout/view/frontend/templates directory. As you may notice, there is no mention in the layout configuration file about the rendering area. However, Magento 2 rendering mechanism knows how to locate the corresponding area of a layout and find a path to the template.

As you may notice, there is also no templates directory specified for the template="MageMastery_FirstLayout::example.phtml". In case we want to add a sub-directory inside the templates directory, let's say a view directory, the configuration of the template should include the sub-directory template="MageMastery_FirstLayout::view/example.phtml".

The example.phtml file is a simple and static template that provides a few HTML tags.

<h1>My First Template</h1>
<p>With Layout support</p>

The content of the example.phtml file is rendered by the Magento\Framework\View\Element\Template class.

Layout File Name

Let's have a look at the layout file name. The magemastery_firstlayout_page_view.xml file name is not an easy-to-guess name. There is some naming convention comes into place.

First of all, a name of the layout file should include the ID of the route. The ID of the route is located in the etc/frontend/routes.xml file. In case of this lesson this is the magemastery_firstlayout ID. The page part of the layout name comes from a name of the controller directory. Finally, the last view path is the name of a controller class, which is View.

Once, we have a custom controller and we want to render a page with the custom layout. The magemastery_firstlayout_page_view name should be provided. Magento 2 will match the the layout configuration file, load the declared list of templates and classes, and render the content of the template on a page.

As the result, we can navigate to the URL and observe a custom page with the custom content rendered on the page.

Layout and Template rendering on a Custom Page


The homework for this lesson.

  1. Create a hello.phtml template under the MageMastery/FirstTemplate/view/frontend/template/view directory.
  2. Add the template into the magemastery_firstlayout_page_view.xml file as an additional block declaration, that should go after the example.phtml block.
  3. Check that the new content of the hello.phtml template is rendered on the page.

Next Steps

Subscribe to the Mage Mastery newsletter to hear first about new lessons and courses.