Layout instructions

What’s in this topic

There are two possible ways to customize page layout in Magento:

• Changing layout files
• Altering templates

To change the page wireframe, modify the page layout files; all other customizations are performed in the page configuration or generic layout files.

Manage layouts

To make layout changes available on every page, modify the default.xml file. For example, layout changes added to app/code/Vendor/Module/view/frontend/layout/default.xml are loaded on all pages. To add layout changes to a specific page, use a layout file that corresponds to the page’s path. For example, changes to the app/code/Vendor/Module/view/frontend/layout/catalog_product_view.xml file are loaded on the product details page.

Use these layout instructions to:

• Move a page element to another parent element.
• Add content.
• Remove a page element.

The basic set of instructions is the same for all types of layout files. This topic describes these basic instructions. For details about how they are used in a particular layout file type, please refer to the Layout file types topic.

Common layout instructions

Use the following layout instructions to customize your layout:

• <block>
• <container>
• before and after attributes
• <action>
• <referenceBlock> and <referenceContainer>
• <move>
• <remove>
• <update>
• <argument>
• <block vs. container>

block

Defines a block.

Details: A block is a unit of page output that renders some distinctive content (anything visually tangible for the end-user), such as a piece of information or a user interface element.

Blocks are a foundational building unit for layouts in Magento. They are the link between a PHP block class (which contains logic) and a template (which renders content). Blocks can have children and grandchildren (and so on). Information can be passed from layout XML files to blocks using the <arguments/> child node.

Blocks employ templates to generate HTML. Examples of blocks include a category list, a mini cart, product tags, and product listing.</p>

To pass parameters use the <argument></argument> instruction.

container

A structure without content that holds other layout elements such as blocks and containers. Details: A container renders child elements during view output generation. It can be empty or it can contain an arbitrary set of <container> and <block> elements.

Sample of usage in layout:

1
2
3
<container name="div.sidebar.additional" htmlTag="div" htmlClass="sidebar sidebar-additional" after="div.sidebar.main">
    <container name="sidebar.additional" as="sidebar_additional" label="Sidebar Additional"/>
</container>

This would add a new column to the page layout.

block vs. container

• Blocks represents the end of the chain in rendering HTML for Magento.
• Containers contain blocks and can wrap them in an HTML tag.
• Containers do not render any output if there are no children assigned to them.

before and after attributes

To help you to position elements in a specific order suitable for design, SEO, usability, or other requirements, Magento software provides the before and after layout attributes.

These optional attributes can be used in layout XML files to control the order of elements in their common parent.

The following tables give a detailed description of the results you can get using the before and after attributes. The first table uses a block as a positioned element.

Examples

action

The <action> instruction is deprecated. If the method implementation allows, use the <argument> for <block> or <referenceBlock> to access block public API.

Calls public methods on the block API.

Details: Used to set up the execution of a certain method of the block during block generation; the <action> node must be located in the scope of the <block> node.

Example:

1
2
3
4
5
6
7
8
<block class="Magento\Module\Block\Class" name="block">
    <action method="setText">
        <argument name="text" translate="true" xsi:type="string">Text</argument>
    </action>
    <action method="setEnabled">
        <argument name="enabled" xsi:type="boolean">true</argument>
    </action>
</block>

<action> child nodes are translated into block method arguments. Child nodes names are arbitrary. If there are two or more nodes with the same name under <action>, they are passed as one array.

To pass parameters, use the </argument> instruction.

referenceBlock and referenceContainer

Updates in <referenceBlock> and <referenceContainer> are applied to the corresponding <block> or <container>. For example, if you make a reference by <referenceBlock name="right">, you’re targeting the block <block name="right">.

To pass parameters to a block use the </argument> instruction.

• The remove attribute is optional and its default value is false.

  This implementation allows you to remove a block or container in your layout by setting the remove attribute value to true, or to cancel the removal of a block or container by setting the value to false.

  Example: <referenceBlock name="block.name" remove="true" />

• The display attribute is optional and its default value is true.

  You are always able to overwrite this value in your layout. In situation when remove value is true, the display attribute is ignored.

  Example: <referenceContainer name="container.name" display="false" />

move

Sets the declared block or container element as a child of another element in the specified order. Example:

1
<move element="name.of.an.element" destination="name.of.destination.element" as="new_alias" after="name.of.element.after" before="name.of.element.before"/>

• <move> is skipped if the element to be moved is not defined.
• If the as attribute is not defined, the current value of the element alias is used. If that is not possible, the value of the name attribute is used instead.
• During layout generation, the <move> instruction is processed before the removal (set using the remove attribute). This means if any elements are moved to the element scheduled for removal, they will be removed as well.

remove

<remove> is used only to remove the static resources linked in a page <head> section. For removing blocks or containers, use the remove attribute for [` and ``](#fedg_layout_xml-instruc_ex_ref).

Example of usage:

1
2
3
4
5
6
7
8
9
10
11
12
13
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
   <head>
        <!-- Remove local resources -->
        <remove src="css/styles-m.css" />
        <remove src="my-js.js"/>
        <remove src="Magento_Catalog::js/compare.js" />
								
        <!-- Remove external resources -->
        <remove src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/css/bootstrap-theme.min.css"/>
        <remove src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js"/>
        <remove src="http://fonts.googleapis.com/css?family=Montserrat" /> 
   </head>
</page>

update

Includes a certain layout file.

Used as follows:

1
<update handle="{name_of_handle_to_include}"/>

The specified handle is “included” and executed recursively.

argument

Used to pass an argument. Must be always enclosed in <arguments>.

To pass multiple arguments use the following construction:

1
2
3
4
5
<arguments>
   <argument></argument>
   <argument></argument>
   ...
</arguments>

To pass an argument that is an array use the following construction:

1
2
3
4
5
<argument>
   <item></item>
   <item></item>
   ...
</argument>

Arguments values set in a layout file can be accessed in templates using the get{ArgumentName}() and has{ArgumentName}() methods. The latter returns a boolean defining whether there’s any value set.

{ArgumentName} is obtained from the name attribute the following way: for getting the value of <argument name="some_string"> the method name is getSomeString().

Example: Setting a value of css_class in the app/code/Magento/Theme/view/frontend/layout/default.xml layout file:

1
2
3
<arguments>
    <argument name="css_class" xsi:type="string">header links</argument>
</arguments>

Using the value of css_class in app/code/Magento/Theme/view/frontend/templates/html/title.phtml

1
$cssClass = $this->hasCssClass() ? ' ' . $this->getCssClass() : '';

arguments

<arguments> is a required container for <argument>. It does not have its own attributes.

Example:

1
2
3
<arguments>
    <argument name="css_class" xsi:type="string">header links</argument>
</arguments>