From f8499218a679bb27340bd495b5db0cde298798cb Mon Sep 17 00:00:00 2001 From: Ben Date: Fri, 25 May 2018 17:18:19 +0100 Subject: [PATCH] Update xml-instructions.md Set block class required to no, and included a note with more details. --- .../layouts/xml-instructions.md | 532 +++++++++++++++++- 1 file changed, 531 insertions(+), 1 deletion(-) diff --git a/guides/v2.2/frontend-dev-guide/layouts/xml-instructions.md b/guides/v2.2/frontend-dev-guide/layouts/xml-instructions.md index 8ec963ef5d5..8c284038db3 120000 --- a/guides/v2.2/frontend-dev-guide/layouts/xml-instructions.md +++ b/guides/v2.2/frontend-dev-guide/layouts/xml-instructions.md @@ -1 +1,531 @@ -../../../v2.1/frontend-dev-guide/layouts/xml-instructions.md \ No newline at end of file +--- +group: fedg +title: Layout instructions +version: 2.2 +github_link: frontend-dev-guide/layouts/xml-instructions.md +functional_areas: + - Frontend +--- + +

What's in this topic

+ + +There are two possible ways to customize page layout in Magento: +* Changing {% glossarytooltip 73ab5daa-5857-4039-97df-11269b626134 %}layout{% endglossarytooltip %} 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. + +Use these {% glossarytooltip bcbc9bf8-3251-4b3c-a802-07417770af3b %}layout instructions{% endglossarytooltip %} 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> +* <arguments> + +

<block>

+ +Defines a block. + +

Details: A block is a unit of page output that renders some distinctive content (anything vvisually tangible for the end-user), such as a piece of information or a user interface element. + +Blocks employ templates to generate {% glossarytooltip a2aff425-07dd-4bd6-9671-29b7edefa871 %}HTML{% endglossarytooltip %}. Examples of blocks include a {% glossarytooltip 50e49338-1e6c-4473-8527-9e401d67ea2b %}category{% endglossarytooltip %} list, a mini cart, product tags, and product listing.

+ +
+

The class attribute is no longer required in version `2.2.1` and above as it will default to `Magento\Framework\View\Element\Template`. **In versions lower than `2.2.1` class is still required.**

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionValuesRequired?
className of a class that implements rendering of a particular block. An object of this class is responsible for actual rendering of block output.class nameno
nameName that can be used to address the block to which this attribute is assigned. The name must be unique per generated page. If not specified, an automatic name will be assigned in the format ANONYMOUS_n0-9, A-Z, a-z, underscore (_), period (.), dash (-). Should start with a letter. Case-sensitive.no
before

Used to position the block

before an element under the same parent. The element name or alias name is specified in the value. Use dash (-) to position the block before all other elements of its level of nesting. See before and after attributes for details.		Possible values: element name or dash (-)no
afterUsed to position the block after an element under the same parent. The element name or alias name is specified in the value. Use dash (-) to position the block after all other elements of its level of nesting. See before and after attributes for details.Possible values: element name or dash (-)no
templateA template that represents the functionality of the block to which this attribute is assigned.template file nameno
asAn alias name that serves as identifier in the scope of the parent element.0-9, A-Z, a-z, underscore (_), period (.), dash (-). Case-sensitive.no
cacheableDefines whether a block element is cacheable. This can be used for development purposes and to make needed elements of the page dynamic. true or falseno
+ +To pass parameters use the `` 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionValuesRequired?
nameA name that can be used to address the container in which this attribute is assigned. The name must be unique per generated page.A-Z, a-z, 0-9, underscore (_), period (.), dash (-). Should start with a letter. Case-sensitive.yes
labelAn arbitrary name to display in the web browser.anyno
beforeUsed to position the container before an element under the same parent. The element name or alias name is specified in the value. Use dash (-) to position the block before all other elements of its level of nesting. See before and after attributes for details.Possible values: element name or dash (-).no
afterUsed to position the container after an element under the same parent. The element name or alias name is specified in the value. Use dash (-) to position the block after all other elements of its level of nesting. See before and after attributes for details.Possible values: element name or dash (-).no
asAn alias name that serves as identifier in the scope of the parent element.0-9, A-Z, a-z, underscore (_), period (.), dash (-). Case-sensitive.no
outputDefines whether to output the root element. If specified, the element will be added to output list. (If not specified, the parent element is responsible for rendering its children.)Any value except the obsolete toHtml. Recommended value is 1.no
htmlTagOutput parameter. If specified, the output is wrapped into specified HTML tag.Any valid HTML 5 tag.no
htmlIdOutput parameter. If specified, the value is added to the wrapper element. If there is no wrapper element, this attribute has no effect.Any valid HTML 5 <id> value.no
htmlClassOutput parameter. If specified, the value is added to the wrapper element. If there is no wrapper element, this attribute has no effect.Any valid HTML 5 <class> value.no
+ +Sample of usage in layout: +{%highlight xml%} +... + + + +... +{%endhighlight xml%} + +This would add a new column to the page layout. + + +

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 {% glossarytooltip 8c0645c5-aa6b-4a52-8266-5659a8b9d079 %}XML{% endglossarytooltip %} 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeValueDescription
beforeDash (-)The block displays before all other elements in its parent node.
before[element name]The block displays before the named element.
beforeempty value or [element name] is absentUse the value of after. If that value is empty or absent as well, the element is considered as non-positioned.
afterDash (-)The block displays after all other elements in its parent node.
after[element name]The block displays after the named element.
afterempty value or [element name] is absentUse the value of before. If that value is empty or absent as well, the block is considered as non-positioned.
+

Examples

+ + + + + + + + + + + + + + + + + + + + + + + +
SituationResult
Both before and after attributes are presentafter takes precedence.
Both before and after attributes are absent or emptyThe element is considered as non-positioned. All other elements are positioned at their specified locations. The missing element displays at a random position that doesn't violate requirements for the positioned elements.
Several elements have before or after set to dash (-)All elements display at the top (or bottom, in case of the after attribute), but the ordering of group of these elements is undefined.
The before or after attribute's value refers to an element that is not located in the parent node of the element being defined.The element displays at a random location that doesn't violate requirements for the correctly positioned elements.
+ +

<action>

+ +
+ +

The <action> instruction is deprecated. If the method implementation allows, use the <argument> for <block> or <referenceBlock> to access block public {% glossarytooltip 786086f2-622b-4007-97fe-2c19e5283035 %}API{% endglossarytooltip %}.

 +
+ +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: + +{%highlight xml%} + + + Text + + + true + + +{%endhighlight xml%} + + +

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

+ + + + + + + + + + + + + + + + +
AttributeDescriptionValuesRequired?
methodName of the public method of the block class this tag is located in that is called during block generation.block method nameyes
+ +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're targeting the block <block name="right">.

+ +To pass parameters to a block use the <argument></argument> instruction. + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionValuesRequired?
removeAllows to remove or cancel the removal of the element. When a container is removed, its child elements are removed as well.true/falseno
displayAllows you to disable rendering of specific block or container with all its children (both set directly and by reference). The block's/container's and its children' respective PHP objects are still generated and available for manipulation.true/falseno
+ + + +

<move>

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

Example:

+ +{%highlight xml%} + +{%endhighlight xml%} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionValuesRequired?
elementName of the element to move.element nameyes
destinationName of the target parent element.element nameyes
asAlias name for the element in the new location.0-9, A-Z, a-z, underscore (_), period (.), dash (-). Case-sensitive.no
after | beforeSpecifies the element's position relative to siblings. Use dash (-) to position the block before or after all other siblings of its level of nesting. If the attribute is omitted, the element is placed after all siblings.element nameno
+ +

<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>. + +Example of usage: + +{%highlight xml%} + + + + + + + + + + + + + +{%endhighlight xml%} + +

<update>

+ +Includes a certain layout file. + +Used as follows: + +{%highlight xml%} + +{%endhighlight xml%} + +The specified handle is "included" and executed recursively. + +

<argument>

+Used to pass an argument. Must be always enclosed in<arguments>. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionValuesRequired?
nameArgument name.uniqueyes
xsi:typeArgument type.string|boolean|object|number|null|arrayyes
translatetrue|falseno
+ +To pass multiple arguments use the following construction: +{%highlight xml%} + + + + ... + +{%endhighlight xml%} + +To pass an argument that is an array use the following construction: + +{%highlight xml%} + + + + ... + +{%endhighlight xml%} + +

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: + +{%highlight xml%} +... + + header links + +... +{%endhighlight xml%} + + +Using the value of css_class in app/code/Magento/Theme/view/frontend/templates/html/title.phtml: + +{%highlight php%} +... +$cssClass = $this->hasCssClass() ? ' ' . $this->getCssClass() : ''; +... +{%endhighlight %} + +

<arguments>

+ +<arguments> is a required container for <argument>. It does not have its own attributes. + +Example: + +{%highlight xml%} +... + + header links + +... +{%endhighlight xml%}