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. Layout refers to the visual and structural composition of the page. Layout update refers to a specific set of XML instructions that can override or customize how the page is constructed.
The XML layout of your Commerce store is a hierarchical structure of containers and blocks. Some elements appear on every page, and others appear only on specific pages. To learn more about layout, containers, and blocks, see the Layouts overview in the Frontend Developer Guide.
The Widget tool is an easy way to add an existing content block to the default layout of a page. For more advanced updates, you must save the XML layout update code on the server, and then reference the file as a custom layout update from the Admin. For an overview of the process, see Use Layout Updates.
In the following diagram, the names that refer to containers are black and the block types, or block class paths, are blue.
page/html
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. There can be only one block of this type per page.page/html_head
head
and it is a child of the root block. There can be only one block of this type per page and it must not be removed.page/html_notices
global_notices
and it is a child of the root block. If this block is removed from the layout, the global notices do not appear on the page. There can be only one block of this type per page.page/html_header
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. There can be only one block of this type per page and it must not be removed.page/html_wrapper
page/html_breadcrumbs
breadcrumbs
and it is a child of the header block. This block displays breadcrumbs for the current page. There can be only one block of this type per page.page/html_footer
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. There can be only one block of this type per page and it must not be removed.page/template_links
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.Note: It is possible to manipulate the template links, as shown in the examples.
page/switch
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.global_messages
block displays global messages. The messages
block is used to display all other messages. If you remove these blocks, the customer does not see any messages.core/text_list
core/profiler
Place a block using layout updates
Layout updates make it possible to customize the layout of a page. Layout updates offer more flexibility than a widget, but require access to the server and a basic knowledge of XML.
The following steps show how to use a layout update to place a block on a page. For specific examples and help with syntax, see Common layout customization tasks in the Frontend Developer Guide.
Step 1: Create the block
-
Create the block that you want to place.
-
Take note of the
block_id
, because it is used in the layout update instructions.
Step 2: Compose the layout update in XML
-
Compose the layout instructions in XML to Reference a CMS Block.
-
Save the layout instructions on the server in the layout folder where XML files are saved for the theme.
For example:
<theme_dir>/<Namespace>_<Module>/layout
The layout handle is the filename that begins with
cms_page_view_selectable_
, followed by the URL key of the CMS page, the layout update option, and thexml
file suffix. In the following example,customer-service
is the URL key of the page, andChatTool
is the option that you select to apply the layout update to the page.cms_page_view_selectable_
<customer-service
>_
<ChatTool
>.xml
table 0-row-2 1-row-2 2-row-2 layout-auto Element Description CMS Page Identifier The URL key of the page with any forward slash ( /
) replaced by an underscore (_
).Layout Update Name The option that appears for Custom Layout Update.
Step 3: Reference the layout update from the page
-
On the Admin sidebar, go to Content > Elements > Pages.
-
Find the page where you want to place the block and open it in edit mode.
-
Scroll down and expand the Design section.
-
To display all available layout updates that are associated with the page, click the Custom Layout Update menu.
img-md w-400 modal-image -
Select the layout update that you want to apply to the page.
Step 4: Save and refresh the cache
-
When complete, click Save & Close.
-
In the message at the top of the workspace, click Cache Management and refresh all the invalid cache items.