CHAPTER 40: Page Layout Layout Updates
Layout Updates
Before you begin working with custom layout updates, it is important to understand how the pages of your store are constructed, and the difference between the terms layout and layout update. The term layout
1 refers to the visual and structural composition of the page. However, the term layout update
2 refers to a specific set of XML instructions that determines how the page is constructed.
The XML layout of your Magento Community Edition 2.1 store is a hierarchical structure of blocks. Some elements appear on every page, and others appear only on specific pages. You can see how these structural blocks are referenced by examining the layout update code for your home page. To do so, simply open your home page in edit mode, and choose the Design tab to view the Page Layout section. Depending on the theme, it might contain instructions to remove blocks, unset blocks, and add blocks by referencing specific areas of the page layout.
In many cases, the same result can be achieved with the Frontend App tool. To place a block of content as a frontend app, you must identify the page, and the location on the page where you want the block to appear. You can use the Frontend App tool to place a block on most any page in your store, including the home page and all content pages. However, to place a block in the sidebar of a specific page, you must make the change by entering code as a layout update.
1The visual and structural composition of a page.
2A specific set of XML instructions that determines how the page is constructed.
Magento Community Edition 2.1 User Guide 603
Layout Updates CHAPTER 40: Page Layout
Standard Block Layout
In the following diagram, the block names that can be used to refer to a block in the layout are black, and the block types, or block class paths, are blue.
604
Standard Block Layout
Magento Community Edition 2.1 User Guide
CHAPTER 40: Page Layout Layout Updates
Block Descriptions
BLOCK TYPE
page/html
DESCRIPTION
There can be only one block of this type per page. The block name is
"root," and, it is one of the few root blocks in the layout. You can also create your own block and name it "root," which is the standard name for blocks of this type.
page/html_head page/html_notices page/html_header
There can be only one block of this type per page. The block name is
"head," and it is a child of the root block. This block must not be removed from layout.
There can be only one block of this type per page. The block name is
"global_notices," and it is a child of the root block. If this block is removed from the layout, the global notices will not appear on the page.
There can be only one block of that type per page. The block name is
"header," and it is a child of the root block. This block corresponds to the visual header at the top of the page, and contains several standard blocks. This block must not be removed.
page/html_wrapper
Although included in the default layout, this block is deprecated, and only is included to ensure backward compatibility. Do not use blocks of this type.
page/html_breadcrumbs
There can be only one block of this type per page. The name of this block is "breadcrumbs," and it is a child of the header block. This block displays breadcrumbs for the current page.
page/html_footer page/template_links page/switch core/messages
There can be only one block of this type per page. The block name is
"footer," and it is a child of the root block. The footer block corresponds to the visual footer at the bottom of the page, and contains several standard blocks. This block must not be removed.
There are two blocks of this type in the standard layout. The
"top.links" block is a child of the header block, and corresponds to the top navigation menu. The "footer_links" block is a child of the footer block, and corresponds to the bottom navigation menu. It is possible to manipulate the template links, as shown in the examples.
There are two blocks of this type in a standard layout. The "store_ language" block is a child of the header block, and corresponds to the top language switcher. The "store_switcher" block is a child of the footer block, and corresponds to the bottom store switcher.
There are two blocks of this type in a standard layout. The "global_ messages" block displays global messages. The "messages" block is used to display all other messages. If you remove these blocks, the customer won't be able to see any messages.
Magento Community Edition 2.1 User Guide 605
Layout Updates CHAPTER 40: Page Layout
Block Descriptions (cont.)
BLOCK TYPE DESCRIPTION
core/text_list
This type of block is widely used throughout Magento, and is used as a placeholder for rendering children blocks.
core/profiler
There is only one instance of this type of block per page. It is used for the internal Magento profiler, and should not be used for any other purpose.
606 Magento Community Edition 2.1 User Guide
CHAPTER 40: Page Layout Layout Updates
Layout Update Examples
The following blocks types can be manipulated with custom layout instructions. Each action must be specified using the full syntax of the instruction. In the following examples, a simplified notation is used to refer to each action, which corresponds to the full syntax of the instruction.
Full Syntax
?
<!-- Action can be specified inside either a <block> or <reference> instruction. -->
<action method="someActionName">
<arg1>Value 1</arg1>
<arg2>Value 2</arg2>
<!--->
<argN>Value N</argN>
</action>
<!--->
Simplified Syntax
?
someActionName($arg1, $arg2, ..., $argN)
Magento Community Edition 2.1 User Guide 607
Layout Updates CHAPTER 40: Page Layout
page/template_links
Syntax
ACTION DESCRIPTION
addLink($label, $url, $title, $prepare
Adds another link to the end of the list of existing links. Just specify the $label (link caption), $url (link URL) and $title
(link tooltip), and you'll see a new link in the corresponding place. The $prepare parameter must be "true" if you want the
URL to be prepared, or converted to the full URL from the shortened URL. For example, the new page becomes BASE_
URL/newpage if prepared.
removeLinkByUrl($url) Removes a link from the block by its URL. Note that the URL must be properly specified and exactly match corresponding
URL of the link you want to remove.
cms/block
Syntax
ACTION
setBlockId($blockId)
DESCRIPTION
Specifies the ID of a CMS block, so its content can be fetched and displayed when the page is rendered.
?
<!--...-->
<reference name="content">
<block type="cms/block" name="additional.info" as="additionalInfo">
<action method="setBlockId"><id>additional_info</id></action>
</block>
</reference>
<!--->
608 Magento Community Edition 2.1 User Guide
CHAPTER 40: Page Layout Layout Updates
core/text
A core/text block can be used to enter free form text directly into the template.
Syntax
ACTION
addText($textContent)
DESCRIPTION
Specifies text to be rendered as the block's content. After the text is specified, the layout update instructions must continue to be a valid XML statement. If you use HTML tags as part of the text, it is recommended to use:
<![CDATA[...]]>
?
<!--...-->
<reference name="content">
<block type="core/text" name="test.block">
<action method="addText">
<txt><![CDATA[<h2>ATTENTION!</h2><p>Check your options carefully before you submit.</p>]]></txt>
</action>
</block>
</reference>
<!--->
page/html_welcome
This block can be used to duplicate the “Welcome, <USERNAME>!” message that appears in the header block. When the user is not logged in, the welcome message specified in the configuration appears.
Magento Community Edition 2.1 User Guide 609
Layout Updates CHAPTER 40: Page Layout
Layout Update Syntax
Custom layout updates can be applied to product category pages, product pages, and content page to achieve a variety of results, such as:
<block>
<reference>
<action>
<remove>
Create new block.
Update existing content.
Assign actions to blocks.
Remove blocks.
Any change made to the layout is applied when the associated entity—which can be either a product, category, or CMS page—becomes active in the frontend of the store.
Custom layout update instructions consist of well-formed XML tags, without the <?xml ...> declaration and root tag. As with normal XML, every tag must either be empty or properly closed, as shown in the following examples:
<tag attribute="value" />
<tag attribute="value"> ... </tag>
610 Magento Community Edition 2.1 User Guide
CHAPTER 40: Page Layout Layout Updates
<block>
Creates a new block within the current context. Layout block nesting defines the ordering of block initialization location of the blocks on the page.
Syntax
NAME
type
VALUE
*
block class path
An identifier of the block class path that corresponds to the class of the block. See the list of the available block types below.
name before
*
block name identifier
A name that can be used to address the block in which this attribute is assigned. If you create a new block with the name that is the same as one of the existing blocks, your newly created block substitutes the previously existing block. See the list of names of existing blocks below.
block name | '-'
Is used to position the block before a block with the name specified in the value. If "-" value used the block is positioned before all other sibling blocks.
after template as block name | '-'
Is used to position the block after a block with the name specified in the value. If "-" value used the block is positioned after all other sibling blocks.
template filename
A template filename used for the specific block type. As you have no way to see the list of template files, use whatever template value is demanded for every block type listed below.
block alias
An alias name by which a template calls the block in which this attribute is assigned. Sometimes it's necessary to specify the alias for a specific block type.
Magento Community Edition 2.1 User Guide 611
Layout Updates CHAPTER 40: Page Layout
<reference>
Changes the context for all included instructions to a previously defined block. An empty
<reference> tag if of no use, because it affects only the instructions which are children.
Syntax
NAME
name
VALUE
*
block name
A name of a block to reference.
<action>
Used to access block API, in other words, call block's public methods. It is used to set up the execution of a certain method of the block during the block generation. Action child tags are translated into block method arguments. The list of all available methods depends on the block implementation (e.g. public method of the block class).
Syntax
NAME
method
VALUE
*
block method name
A name of the public method of the block class this instruction is located in that is called during the block generation.
<remove>
Removes an existing block from the layout.
Syntax
NAME
name
VALUE
*
block name
The name of the block to be removed.
<extend>
This instruction performs final modifications to blocks which are already part of the layout.
Every attribute in the <block> instruction—except for the block name—is subject for change. In addition, the special attribute parent can be used to change the parent of the block. Simply put the name of the new parent block into the <extend> instruction, and the parent of the block that is referenced will be changed in the layout.
612 Magento Community Edition 2.1 User Guide
CHAPTER 40: Page Layout
Syntax
NAME
name
* parent
Layout Updates
VALUE
*
block name
The name of any block to be extended.
any other
Any other attribute specific for the <block> instruction.
block name
The name of the block that should become a new parent for the referenced block.
*
Indicates a required value
Magento Community Edition 2.1 User Guide 613
Layout Updates CHAPTER 40: Page Layout
Controlling Block Order
Sometimes more than one content element is assigned to the same structural block. For example, there might be several block that appear in a sidebar. You can control the order of blocks by including a “before” or “after” positioning property in the code. To place a block either before, or after a specific block, replace the hyphen with the block identifier, as shown in the following examples: before="-" after="-"
Places the block at the top of the sidebar, before other blocks.
Places the block at the bottom of the sidebar, after other blocks.
Code to Position Content Blocks
<block type="cms/block" before="-" name="left.permanent.callout">
<block type="cms/block" before="some-other-block" name="left.permanent.callout">
<block type="cms/block" after="-" name="left.permanent.callout">
<block type="cms/block" after="some-other-block" name="left.permanent.callout">
614 Magento Community Edition 2.1 User Guide
CHAPTER 40: Page Layout Layout Updates
XML Load Sequence
For developers, it is important to understand that blocks and layout updates must be loaded in the correct order, in keeping with the rules of precedence and load sequence
1 which determine how the page is rendered. Magento supports the following page layout scenarios:
Scenario 1:
Default Layout
The default layout consists of the visual elements that are visible from every page of the store.
Whether it is a menu item, or a shopping cart block, each item has a handle
2 in the default section of the layout definition.
Scenario 2:
Changes to Specific Pages
The second case allows you to create a different layout for a specific page. The XML layout for specific pages is constructed in the same sequence that Magento loads modules, and is determined by the system configuration.
In addition to the instructions in the layout update files which are specific to each module, you can make a custom layout update that applies to a special case in the backend, and is merged each time the special case occurs.
1The order in which scripts are loaded into memory. To work correctly, some scripts must be loaded before others.
2In programming, a name used to reference an object.
Magento Community Edition 2.1 User Guide 615
616 Magento Community Edition 2.1 User Guide
CHAPTER 41:
Themes
A theme is a collection of files that determines the visual presentation of your store. When you first install Magento Community Edition 2.1, the design elements of the store are based on the “Default” Theme. In addition to the initial default theme that comes with your Magento installation, there is a wide variety of themes that are available “off the shelf” on Magento Connect.
Magento themes include layout files, template files, translation files, and skins. A skin is a collection of supporting CSS, images, and JavaScript files that together, create the visual presentation and interactions that your customers experience when they visit your store.
Themes and skins can be modified and customized by a developer or designer who has knowledge of Magento theme design and access to your server. To learn more, see the
Frontend Developer Guide .
Luma Theme
Magento Community Edition 2.1 User Guide 617
