Skip to content

Latest commit

 

History

History
374 lines (359 loc) · 13.1 KB

xml-schema-layout.md

File metadata and controls

374 lines (359 loc) · 13.1 KB
layout group subgroup title menu_title menu_order version github_link redirect_from
default
View library
XML layouts and schemas
XML layouts and schemas
2.0
architecture/view/xml-schema-layout.md
/guides/v1.0/architecture/view/xml-schema-layout.html

Overview {#m2devgde-xml-layout-intro}

In the Magento system, you define application page layouts in XML files, also known as layouts.

The system uses the Magento XML schemas to validate these layouts.

XML schemas {#xml-schemas}

The Magento system uses the following XML schemas to validate these layouts:

Reviewer: The original topic mentioned 3 XSD files, two of which do not exist or have been renamed: layout_single.xsd, layouts.xsd, and layout_merged.xsd. I guessed that layout_single = layout_generic but I do not know the correct reference for layouts.xsd. Please provide this information.

Schema Validates
layout_generic.xsd Individual layouts
layouts.xsd Individual layouts.
layout_merged.xsd Merged layouts.

These layout-specific XML schemas might use additional universal XML schemas.

XML layout elements and structure {#layout-elements}

The following table lists the allowable XML layout elements. The table reflects the correct structure for these elements.

Description Attributes Children
<layout>

Mandatory root element.
  • xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
  • xs:include schemaLocation="urn:magento:framework:View/Layout/etc/elements.xsd
  • <block>
  • <container>
  • <remove>
  • <move>
  • <update>
  • <referenceBlock>
  • <referenceContainer>
<block>

A unit of a page output, which generates content. Each block corresponds to a Magento PHP class. Instantiate each block one time only.

If the cacheable attribute is set to false for one block on the page, each request generates the whole page.

  • class="{block_class}" (required)
  • name="{arbitrary_name}" (unique)
  • as="{alias}"
  • before="{name_of_sibling}"
  • after=" {name_of_sibling}"
  • template="{block_template}"
  • group="{group_name}"
  • output="1|0"
  • acl="{resource_name}" (the block is generated and its output is added to the rendered page if a user has permission for the resource)
  • ifconfig="{сonfig_path}" (the element is rendered just in case the corresponding configuration flag is set for the current scope)
  • cacheable="true|false"
  • ttl="block_lifetime_for_Varnish_ESI_cache"
  • <block>
  • <container>
  • <action>
  • <arguments>
  • <referenceBlock>
<container>

A placeholder for blocks and other containers.
  • name="{arbitrary_name}" (unique)
  • as="{alias}"
  • before="{name_of_sibling}"
  • after="{name_of_sibling}"
  • group="{group_name}"
  • output="1|0"
  • htmlTag="{tag_to_wrap_in}"
  • htmlId="{id_of_wrapping_tag}"
  • htmlClass="{class_of_wrapping_tag}"
  • label="label_displayed_for_user}"
  • <block>
  • <container>
  • <remove>
  • <move>
  • <referenceBlock>
  • <referenceContainer>
<update>

The specified handle is "included" and executed recursively.
  • handle="{name_of_handle_to_include}"
<move>

Sets the declared element as a child to another element in the specified order.
  • element="{name.of.an.element}" (required)
  • destination="{name.of.destination.element}" (required)
  • as="{new_alias}"
  • after="{name.of.element.after}"
  • before="{name.of.element.before}"
<remove>

Removes the specified element.
  • name="{name.of.an.element}" (required)
<action>

Invokes block method Will become obsolete eventually. It is being gradually replaced with non-imperative layout instructions.

  • method="{block_class_method}" (required)
  • ifconfig="{config_path}" (The element is rendered just in case the corresponding configuration flag is set by specified path for current scope.)
  • <argument>
<referenceBlock>

Wraps layout instructions, that is they will be executed in the context of the specified block.
  • name="{block_name}" (required)
  • <block>
  • <container>
  • <remove>
  • <move>
  • <update>
  • <referenceBlock>
  • <referenceContainer>
  • <action>
  • <arguments>
<referenceContainer>

Wraps layout instructions, that is they will be executed in the context of the specified container.
  • name="{container_name}" (required)
  • htmlTag="{wrapping_tag}"
  • htmlClass="{class_of_wrapping_tag}"
  • htmlId="{id_of_wrapping_tag}"
  • label="{lable_to_be_displayed_for_admin_user}"
  • <block>
  • <container>
  • <remove>
  • <move>
  • <update>
  • <referenceBlock>
  • <referenceContainer>
<arguments>

A wrapper for arguments.
  • <argument>
<argument>

Handles parameters that are injected into the parent block constructor during instantiation. 

        </p>
     </td>
     <td>
        <ul>
           <li><code>name ="{ argument_name}"</code> (required, unique)</li>
           <li><code>xsi:type =" string|boolean|object|number|null|array"</code></li>
           <li><code>translate="true|false"</code></li>
        </ul>
     </td>
     <td>
        <ul>
           <li><code>&lt;item></code></li>
        </ul>
     </td>
  </tr>
  <tr style="background-color: lightgray">
     <th colspan="3"><code>&lt;item&gt;</code></th>
  </tr>
  <tr>
     <td>
        <p>Handles array items for array arguments type.</p>
     </td>
     <td>
        <ul>
           <li><code>name ="{ argument_name}"</code> (required, unique)</li>
           <li><code>xsi:type =" string|boolean|object|number|null|array"</code></li>
           <li><code>translate="true|false"</code></li>
        </ul>
     </td>
     <td>
        <ul>
           <li><code>&lt;item></code></li>
        </ul>
     </td>
  </tr>
  <tr style="background-color: lightgray">
     <th colspan="3"><code>&lt;updater&gt;</code></th>
  </tr>
  <tr>
     <td>
        <p>Changes argument value.</p>
     </td>
     <td/>
     <td/>
  </tr>

Validate XML layouts {#xml-validation}

Use the following tests to validate new or changed layouts:

Test Validates
HandlesTest.php Layouts
LayoutFilesTest.php Argument values correspond to required data types