Get Free Audit

Module Layout Handles in Magento 2

Sep 6, 2018

18269 Andrey Litvin

Module Layout Handles in Magento 2

When writing modules, there might be a need to make edits to some pages. This can be adding, modifying or editing any elements on the page. Changes are made in Layout handles xml files.


The name of the layout
Layout customization tasks
Where layout handles are stored
Extend & override layouts
Extend module layout
Override module layout
Override theme layout
View the result of an xml layout on a page

The name of the layout xml file

The Xml file has a name based on the routing. For example, product URL look like this: /catalog/product/view/… Thus, the layout of the handle for this page will be catalog_product_view.xml. If the changes should be made on all pages, the file will be named default.xml.

Layout customization tasks

Let’s take a quick look at how you can customize layouts.

Set the page layout

Page layout is specified in the root <page> node.

Default theme has the following page layouts:

  • 1column
  • 2columns-left
  • 2columns-right
  • 3columns

which are located at: /vendor/magento/module-theme/view/frontend/page_layout.

Let’s take a look at the example of assigning the 1column layout for a product page:
module-catalog/view/frontend/layout/catalog_product_view.xml

Include or remove static resources (JavaScript, CSS, fonts) in <head>

JavaScript, CSS and other static assets are added in the <head> node. Let’s look at the example of using it in the layout:
module-theme/view/frontend/layout/default_head_blocks.xml


When adding external resources, you must specify an attribute src_type=”url.

To add Google fonts, you need to add the attributes rel=stylesheet and type=text/css“.

To add JavaScript, you can use  <link src=”js/sample.js”/> or <script src=”js/sample.js”/> instructions.

The example of using the external resource:

Adding conditional comments

Conditional comments are meant for special instructions for Internet Explorer.

In layout files they are used in the following way:


You can take a look at its usage in *.phtml file at: magento2-base/setup/view/layout/layout.phtml

Create a container or block

A typical block has a class and a phtml file containing html and data from the methods of the class. Container does not have classes and phtml. Container is similar to the html markup to which you can attach the blocks with the “as” attribute. Also, the container has htmlTag and htmlClass attributes.

Let’s look at the example of creating a container and a block in the layout:
module-theme/view/frontend/layout/default.xml

Reference a container or a block

To update a block or container, referenceBlock and referenceContainer instructions are used.

Let’s look at the reference container and the block in the layout:
module-theme/view/frontend/layout/default.xml

Set the template used by a block

There are 2 ways to assign a block to a template:

  • Using template attribute

<referenceBlock name=”customer_form_register” template=”Magento_Checkout::cart/item/configure/updatecart.phtml”/>

  • Using <argument> instruction


The templates specified as an attribute have a higher priority than the templates specified as an argument.

Modify block arguments

To modify block arguments, use the <referenceBlock> instruction.

Let’s look at the layout:
module-wishlist/view/frontend/layout/customer_account.xml

It has a block:


Extending layout will be:

Use block object methods to set block properties

There are 2 ways to do this:

  • using the <argument> instruction for <block> or <referenceBlock>.

Let’s look at the example of using it in the layout:
module-catalog/view/frontend/layout/catalog_product_view.xml


CSS class is set and an attribute is added for the product page.

using the <action> instruction. Use this method only when you can not use the previous one.

Let’s look at an example of using it in the layout:
module-customer/view/frontend/layout/customer_account_index.xml

Igor Dragun
Partner With Us Let's discuss how to grow your business. Get a Free Quote.
Talk to Igor

Rearrange elements

There are 2 ways to change the order of elements on a page:

  • Using the <move> construction;
  • Specifying before and after attributes.

Let’s take a look at using the <move> instruction in the layout:
module-theme/view/frontend/layout/print.xml


In the value of the before / after attribute, we can specify the name of the element, before or after which we need to insert a block. If the block should be the first or the last, as in the example, the value “-” is used.

Let’s take a look at using before and after attributes:
module-sales/view/frontend/layout/sales_order_view.xml

Remove elements

The remove attribute is used for removing elements in <referenceBlock> and <referenceContainer>.

Let’s look at the example in the layout:
module-theme/view/frontend/layout/print.xml

Replace elements

There is no mechanism to replace an element, but you can delete it and add a new one.

Where layout handles are stored

app/code/<Vendor>/<Module>/view/frontend/layout/ – front end;

app/code/<Vendor>/<Module>/view/adminhtml/layout/ – back end.

Extend & override layouts

To change layouts, you can use extend & override.

Extend means that you do not need to copy the entire file, but only specify changes from the parent layout. Using override, you can copy the layout and work with it, in this case the data from the parent layout will not be taken into account. It is worth noting that layout override is not recommended.

Extend module layout

The path to the files:
app/design/[StoreSide]/[Vendor]/[theme]/[Vendor_Module]/layout/

For example, if you need module’s extend layout:
app/code/Belvg/Example/view/frontend/layout/layout.xml

The path to it will be:
app/design/frontend/Vendor/theme/Belvg_Example/layout/layout.xml

magento_ico_1.9_layered_navigation

Layered Navigation

Take your online store to the new level together with BelVG's extensions

Download here

Override module layout

The path to the files:
app/design/[StoreSide]/[Vendor]/[theme]/[Vendor_Module]/layout/override/base/

For example, if you need to override module’s layout:
app/code/Belvg/Example/view/frontend/layout/layout.xml

The path to it will be:
app/design/frontend/Vendor/theme/Belvg_Example/layout/override/base/layout.xml

Note: The base folder is intended for overriding module layouts. If we wanted to overload the theme layout, the folder would be called theme and the path to it would be:
app/design/[StoreSide]/[Vendor]/[theme]/[Vendor_Module]/layout/override/theme/[Vendor2]/[theme2]/

Override theme layout

For example, if you need to override theme layout:
app/design/frontend/Magento/Luma/Magento_Theme/layout/default.xml

The path to it will be:
app/design/frontend/[Vendor]/[theme]/Magento_Theme/layout/override/theme/Magento/blank/default.xml

View the result of an xml layout on a page

When we visit a page, the xml layout is built for it. Let’s look at the result using the Observer.

1. Create module.xml:
app/code/Belvg/LayoutLogger/etc/module.xml


2. Create registeration.php:
app/code/Belvg/LayoutLogger/registration.php


3. Create events.xml and declare the observer:
app/code/Belvg/LayoutLogger/etc/frontend/events.xml


4. Create an observer that will write all layout pages into a separate xml file:
app/code/Belvg/LayoutLogger/Module/Layout.php


As a result, we will get the xml layout files of the visited pages:

XML layout of the visited pages

This is how you can look at the layout xml of the page we are interested in and see all the instructions contained.

catalog_category_view for 2.2.3 sd:

catalog category view for 2.2.3 sd

Hope this information was clear and useful to you. Please leave your questions in the comment section below and I will get in touch with you as soon as possible.

Igor Dragun
Partner With Us Looking for a partner to grow your business? We are the right company to bring your webstore to success. Talk to Igor

2 Comments

  1. Hi, Mudasser! Thanks for your comment!
    There was a mistake in the code, but now we fixed it. We are grateful that you noticed it and informed us.

  2. After following the given steps to perform i found this exception.
    “Warning: fopen(/var/www/html/Magento-CE-2.3.2/var/log/layouts/cms_index_index 2019-07-12 03:19:54.xml): failed to open stream: No such file or directory”.

    Can you please guide me to ix this exception.

    Thanks in advance sir.

Post a new comment

BelVG Newsletter
Subscribe to our mailing list and get interesting stuff and updates to your email inbox.
Email *