Skip to content

Latest commit

 

History

History
381 lines (273 loc) · 15.9 KB

xml-manage.md

File metadata and controls

381 lines (273 loc) · 15.9 KB
layout group subgroup title menu_title menu_order version github_link
default
fedg
B_Layouts
Common layout customization tasks
Common layout customization tasks
6
2.2
frontend-dev-guide/layouts/xml-manage.md

What's in this topic

This article describes the following typical layout customization tasks:

To ensure stability and secure your customizations from being deleted during upgrade, do not change out-of-the-box Magento module and theme layouts. To customize layout, create extending and overriding layout files in your custom theme.

Set the page layout

The type of page layout to be used for a certain page is defined in the page configuration file, in the layout attribute of the root <page> node.

Example: Change the layout of Advanced Search page from default "1-column" to "2-column with left bar". To do this, extend catalogsearch_advanced_index.xml in your theme by adding the following layout:

app/design/frontend/<Vendor>/<theme>/Magento_CatalogSearch/layout/catalogsearch_advanced_index.xml

{%highlight xml%} ... {%endhighlight xml%}

Include static resources (JavaScript, CSS, fonts)

JavaScript, CSS and other static assets are added in the <head> section of a page configuration file. The default look of a Magento store page <head> is defined by app/code/Magento/Theme/view/frontend/layout/default_head_blocks.xml. The recommended way to add CSS and JavaScript is to extend this file in your custom theme, and add the assets there. The following file is a sample of a file you must add:

<theme_dir>/Magento_Theme/layout/default_head_blocks.xml

{%highlight xml%} 

    <!-- The following two ways to add local JavaScript files are equal -->
    <script src="Magento_Catalog::js/sample1.js"/>
    <link src="js/sample.js"/>
	
	<!-- Add external resources -->
    <css src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/css/bootstrap-theme.min.css" src_type="url" />
    <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js" src_type="url" />
    <link src="http://fonts.googleapis.com/css?family=Montserrat" src_type="url" /> 
</head>
{%endhighlight xml%}

When adding external resources, specifying the src_type="url" argument value is a must.

You can use either <link src="js/sample.js"/> or <script src="js/sample.js"/> instruction to add a locally stored JavaScript file to your theme.

The path to assets is specified relatively to one the following locations:

  • <theme_dir>/web
  • <theme_dir>/<Namespace>_<Module>/web

Adding conditional comments

Conditional comments are meant to give special instructions for Internet Explorer. In the terms of adding assets, you can add CSS files to be included for a specific version of Internet Explorer. A sample follows:

{%highlight xml%} {%endhighlight xml%}

This adds an IE conditional comment in the generated HTML, like in the following example:

{%highlight html%}

{%endhighlight html%}

In this example, orange is a custom theme created by the OrangeCo vendor.

Remove static resources (JavaScript, CSS, fonts)

To remove the static resources, linked in a page <head>, make a change similar to the following in a theme extending file:

app/design/frontend/<Vendor>/<theme>/Magento_Theme/layout/default_head_blocks.xml

{%highlight xml%} 

<!-- Remove external resources -->
    <remove src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/css/bootstrap-theme.min.css"/>
    <remove src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js"/>
    <remove src="http://fonts.googleapis.com/css?family=Montserrat" />
{%endhighlight xml%}

Note, that if a static asset is added with a module path (for example Magento_Catalog::js/sample.js) in the initial layout, you need to specify the module path as well when removing the asset.

Create a container

Use the following sample to create (declare) a container:

{%highlight xml%} {%endhighlight xml%}

Reference a container

To update a container use the <referenceContainer> instruction.

Example: add links to the page header panel.

{%highlight xml%} header links {%endhighlight xml%}

Create a block

Blocks are created (declared) using the <block> instruction.

Example: add a block with a product SKU information.

{%highlight xml%} getSku sku sku {%endhighlight xml%}

Reference a block

To update a block use the <referenceBlock> instruction.

Example: pass the image to the logo block.

{%highlight xml%} images/logo.png {%endhighlight xml%}

Set the template used by a block {#set_template}

There are two ways to set the template for a block:

  • using the template attribute
  • using the <argument> instruction

Both approaches are demonstrated in the following examples of changing the template of the page title block.

Example 1:

{%highlight xml%} {%endhighlight%}

Example 2:

{%highlight xml%} %Namespace_Module::new_template.phtml% {%endhighlight%}

In both example, the template is specified according to the following:

  • Namespace_Module: defines the module the template belongs to. For example, Magento_Catalog.
  • new_template.phtml: the path to the template relatively to the templates directory. It might be <module_dir>/view/<area>/templates or <theme_dir>/<Namespace_Module>/templates.

Template values specified as attributes have higher priority during layout generation, than the ones specified using <argument>. It means, that if for a certain block, a template is set as attribute, it will override the value you specify in <argument> for the same block.

Modify block arguments

To modify block arguments, use the <referenceBlock> instruction.

Example: change the value of the existing block argument and add a new argument.

Initial block declaration:

{%highlight xml%} ... Block Label ... {%endhighlight xml%}

Extending layout:

{%highlight xml%} ... New Block Label <!- Newly added block argument --> Custom Block Label ... {%endhighlight xml%}

Use block object methods to set block properties

There are two ways to access block object methods:

  • using the <argument> instruction for <block> or <referenceBlock>
  • using the <action> instruction. This way is not recommended, but can be used for calling those methods, which are not refactored yet to be accessed through <argument>.

Example 1: Set a CSS class and add an attribute for the product page using <argument>.

Extending layout:

{%highlight xml%} product itemprop="name" {%endhighlight xml%}

Example 2: Set a page title using <action>.

Do not use <action>, if the method implementation allows calling it using <argument> for <block> or <referenceBlock>.

Extending layout:

{%highlight xml%} ... Catalog Advanced Search ... {%endhighlight xml%}

Rearrange elements

In layout files you can change the elements order on a page. This can be done using one of the following:

Example of `` usage: put the stock availability and SKU blocks next to the product price on a product page.

In the Magento Blank theme these elements are located as follows:

Let's place the stock availability and SKU blocks after product price block on a product page, and move the review block out of the product-info-price container. To do this, add the extending catalog_product_view.xml in the app/design/frontend/OrangeCo/orange/Magento_Catalog/layout/ directory:

{%highlight xml%}

{%endhighlight xml%}

This would make the product page look like following:

To learn how to locate the layout file you need to customize, see Locate templates, layouts, and styles.

Remove elements

Elements are removed using the remove attribute for the <referenceBlock> and <referenceContainer>.

Example: remove the Compare Products sidebar block from all store pages.

This block is declared in app/code/Magento/Catalog/view/frontend/layout/default.xml:

{%highlight xml%} ... ... {%endhighlight xml%}

To remove the block, add the extending default.xml in your theme: <theme_dir>/Magento_Catalog/layout/default.xml

In this file, reference the element having added the remove attribute:

{%highlight xml%}

... ...

{%endhighlight xml%}

Replace elements

To replace an element, remove it and add a new one.

Related topics: