Layout XML Deep Dive

Block Element Complete Reference

<block class="Magento\Catalog\Block\Product\ListProduct"
       name="product.list"
       template="product/list.phtml"
       as="productList"
       after="-"
       before="-"
       output="1"
       cacheable="1"
       ttl="3600"
       css_class="product-list"
       html_tag="div"
       html_id="product-list-wrapper"
       group_id="">
    <arguments>
        <argument name="title" xsi:type="string">Products</argument>
    </arguments>
</block>

Block Attributes Reference

Container Element

<container name="content.container"
           htmlTag="div"
           htmlClass="page-main"
           htmlId="maincontent"
           label="Main Content Container"
           output="1">
    <block .../>
</container>

Container Attributes

ReferenceBlock Operations

<!-- Add child blocks -->
<referenceBlock name="product.info">
    <block class="Vendor\Module\Block\Extra"
           name="extra.info"
           template="extra.phtml"
           after="product.info.price"/>
</referenceBlock>

<!-- Change block class -->
<referenceBlock name="product.info" class="Vendor\Module\Block\CustomProduct"/>

<!-- Change template -->
<referenceBlock name="product.info" template="Vendor_Module::custom.phtml"/>

<!-- Remove block -->
<referenceBlock name="product.info.review" remove="true"/>

<!-- Remove with args -->
<referenceBlock name="product.info.review" remove="true"/>

ReferenceContainer Operations

<!-- Add to container -->
<referenceContainer name="content">
    <container name="custom.section" htmlTag="div" htmlClass="custom">
        <block .../>
    </container>
</referenceContainer>

<!-- Wrap container -->
<referenceContainer name="content" htmlTag="div" htmlClass="content-wrapper"/>

<!-- Remove container -->
<referenceContainer name="sidebar.main" remove="true"/>

Sort Order with after/before

<block name="block.a" .../>
<block name="block.b" after="block.a" .../>
<block name="block.c" before="block.a" .../>
<block name="block.d" after="-" .../>  <!-- Last -->
<block name="block.e" before="-" .../>  <!-- First -->

Action Tag for Method Calls

<block class="Vendor\Module\Block\Custom" name="custom.block">
    <!-- Call method with parameters -->
    <action method="setTitle">
        <argument name="title" xsi:type="string">Custom Title</argument>
    </action>
    
    <!-- Call method with multiple params -->
    <action method="addItem">
        <argument name="type" xsi:type="string">product</argument>
        <argument name="item" xsi:type="array">
            <item name="label" xsi:type="string">Product Name</item>
            <item name="url" xsi:type="string">http://example.com</item>
        </argument>
    </action>
    
    <!-- Call method without arguments -->
    <action method="setCanShowPrice">
        <argument name="canShowPrice" xsi:type="boolean">true</argument>
    </action>
</block>

Common Action Methods

<!-- Set block data -->
<action method="setData">
    <argument name="key" xsi:type="string">value</argument>
</action>

<!-- Add CSS class -->
<action method="addCss">
    <argument name="css" xsi:type="string">Vendor_Module::css/custom.css</argument>
</action>

<!-- Add JS -->
<action method="addJs">
    <argument name="js" xsi:type="string">Vendor_Module::js/custom.js</argument>
</action>

<!-- Set template -->
<action method="setTemplate">
    <argument name="template" xsi:type="string">custom.phtml</argument>
</action>

Action vs Direct Attributes

<!-- Direct attribute (preferred) -->
<block class="..." template="custom.phtml"/>

<!-- Action method (for complex operations) -->
<action method="setTemplate">
    <argument name="template" xsi:type="string">custom.phtml</argument>
</action>

Use direct attributes when possible; action for methods not available as attributes.

Move Element

<!-- Move block from one container to another -->
<move element="product.info.addto"
      destination="product.info.bottom"
      after="product.info.price"
      before="-"/>

<!-- Move to different parent -->
<move element="newsletter"
      destination="footer"
      after="-"/>

Move Attributes

Remove Element

<!-- Remove a block -->
<referenceBlock name="product.info.review" remove="true"/>

<!-- Remove a container -->
<referenceContainer name="sidebar.main" remove="true"/>

<!-- Conditional remove (with args) -->
<referenceBlock name="product.info" remove="true"/>

Remove vs Hide

<!-- Remove completely from DOM -->
<referenceBlock name="block.name" remove="true"/>

<!-- Hide with CSS (alternative) -->
<referenceBlock name="block.name" cssClass="hidden"/>

Complete Example

<?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>
        <!-- Remove sidebar -->
        <referenceContainer name="sidebar.main" remove="true"/>
        
        <!-- Move addto buttons -->
        <move element="product.info.addto"
              destination="product.info.bottom"
              after="product.info.price"/>
        
        <!-- Add custom block -->
        <referenceContainer name="content">
            <block class="Vendor\Module\Block\Widget"
                   name="custom.widget"
                   template="widget.phtml"/>
        </referenceContainer>
    </body>
</page>