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 page 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.
• Arrange the element position.

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.

The class attribute is no longer required in versions 2.2.1 and above, as it will default to Magento\Framework\View\Element\Template. In version 2.2.0, the class attribute is still required.

We recommend always adding a name to blocks. Otherwise, it is given a random name.

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

Sample usage in the product listing page layout:

1
<block class="Magento\Catalog\Block\Product\ListProduct" name="category.products.list" as="product_list" template="Magento_Catalog::product/list.phtml"/>

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. If the <container> is empty, and there is no child <block> available, it will not be displayed in the frontend source code.

We recommend always adding a name to containers. Otherwise, it is given a random name.

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.

Controlling children visibility

The output attribute controls the visibility of the container’s children elements. Set this value to 1 to render children content or 0 to disable the output of the entire container.

Use this feature to make temporary changes to a store, such as disabling a section of the page for a sales event and re-enabling it after the event ends.

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 a as positioned element.

Examples

action

The <action> instruction is deprecated. If the method implementation allows, use the <argument> for <block> or <referenceBlock> to access the 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.

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></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 are targeting the block <block name="right">.

To pass parameters to a block use the <argument></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.

  1
  <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.

  1
  <referenceContainer name="container.name" display="false" />
  

move

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

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 <referenceBlock> and <referenceContainer>.

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.

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 name="item1" xsi:type="string">Custom string</argument>
   <argument name="item2" xsi:type="boolean">true</argument>
   ...
</arguments>

Arguments values set in a layout file can be accessed in templates using the getData('{ArgumentName}') and hasData('{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 getData('some_string').

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() : '';

Argument types examples

As was described above the argument attribute can be added with different types. There are examples of all argument types.

• The string type:

  1
  <argument name="some_string" xsi:type="string" >Some String</argument>
  

• The boolean type:

  1
  <argument name="is_active" xsi:type="boolean" >true</argument>
  

• The object type:

  1
  <argument name="viewModel" xsi:type="object" >Vendor\CustomModule\ViewModel\Class</argument>
  

  The Vendor\CustomModule\ViewModel\Class class should implement the \Magento\Framework\View\Element\Block\ArgumentInterface interface.

• The number type:

  1
  <argument name="some_number" xsi:type="number" >100</argument>
  

• The null type:

  1
  <argument name="null_value" xsi:type="null" />
  

• The array type:

  1
  2
  3
  4
  5
  <argument name="custom_array" xsi:type="array">
     <item name="array_key_one" xsi:type="string">First Item</item>
     <item name="array_key_two" xsi:type="string">Second Item</item>
  ...
  </argument>
  

• The options type:

  1
  <argument name="options" xsi:type="options" >Vendor\CustomModule\Source\Options\Class</argument>
  

  The Vendor\CustomModule\Source\Options\Class class should implement the \Magento\Framework\Data\OptionSourceInterface interface.

• The url type:

  1
  <argument name="shopping_cart_url" xsi:type="url" path="checkout/cart/index" />
  

• The helper type:

  1
  2
  3
  4
  5
  <argument name="helper_method_result" xsi:type="helper" helper="Vendor\CustomModule\Helper\Class::someMethod" >
    <param name="firstParam">firstValue</param>
    <param name="secondParam">secondValue</param>
   ...
  </argument>
  

The helper can only use public methods. In this example the someMethod() method should be public. The argument with helper type can contain param items which can be passed as a helper method parameters.

Obtain arguments in template examples

These argument examples are taken in the template by the getData method. Another way to take these arguments is using the magic method get followed by the name of argument in CamelCase format. Here is an example to retrieve the arguments from above example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
<?php
/** @var \Magento\Framework\View\Element\Template $block */

/** @var string $someString */
$someString = $block->getData('some_string'); //or $block->getSomeString()

/** @var bool $isActive */
$isActive = $block->getData('is_active'); //or $block->getIsActive()

/** @var Vendor\CustomModule\ViewModel\Class|\Magento\Framework\View\Element\Block\ArgumentInterface $viewModel */
$viewModel = $block->getData('viewModel'); //or $block->getViewModel()

/** @var string|int|float $someNumber */
$someNumber = $block->getData('some_number'); //or $block->getSomeNumber()

/** @var null $nullValue */
$nullValue = $block->getData('null_value'); //or $block->getNullValue()

/** @var array $customArray */
$customArray = $block->getData('custom_array'); //or $block->getCustomArray()

/** @var array $options */
$options = $block->getData('options'); //or $block->getoptions()

/** @var string $shoppingCartUrl */
$shoppingCartUrl = $block->getData('shopping_cart_url'); //or $block->getShoppingCartUrl()

/** @var mixed $helperMethodResult */
$helperMethodResult = $block->getData('helper_method_result'); // or $block->getHelperMethodResult()

arguments

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

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

Common arguments for blocks

The following are common arguments for block instructions:

• cache_key: key for saving/retrieving cached information. This is helpful if the block needs to be cached: example.

• template: sets the template for the block.

  1
  2
  3
  4
  5
  <referenceBlock name="page.main.title">
     <arguments>
        <argument name="template" xsi:type="string">%Namespace_Module::new_template.phtml%</argument>
     </arguments>
  </referenceBlock>
  

• translate_inline: `true’ = enable translation for this block.

  1
  <argument xsi:type="string" translate="true">{strValue}</argument>
  

• module_name: sets the module for the block. Usually this is determined automatically.

  1
  2
  3
  4
  5
  <block class="Namespace_Module_Block_Type" name="block.example">
     <arguments>
        <argument name="label" xsi:type="string">Block Label</argument>
     </arguments>
  </block>