Get Started
Magento 2 Layout: Containers, Blocks, and Custom Files

Magento 2 Layout: Containers, Blocks, and Custom Files

Magento Hosting

The Magento 2 layout enables users to create various UI layouts for your store. It ranges from simple and minimalistic designs to more complex and intricate ones. It empowers merchants to establish unique and personalized Magento storefronts.


Interested in setting up page design within Magento 2? This guide covers key components such as layouts, containers, and blocks. These components are essential for customizing your web pages to create a distinct online presence for your business.

Best Magento Hosting now

Key Takeaways

  • Understand the role of Magento 2 layouts as XML files for defining page structure.

  • Learn to create custom layout files for unique web page designs.

  • Discover Layout Handles for flexible page configurations.

  • Learn how to use containers to organize and position page content effectively.

  • Discover the role of blocks in rendering UI elements and how to customize them.

  • Understand the similarities between blocks and containers in page layout.

What are Magento 2 Layouts?

Overview of Magento 2 layout system

In Magento 2, layouts are XML files that define the structure and content of different website pages. Each page in Magento 2 has its corresponding layout file. This file specifies the page's blocks, containers, and other elements.

It offers five default frontend page layouts:

  1. empty
  2. 1column
  3. 2columns-left
  4. 2columns-right
  5. 3columns

For the backend or admin section, Magento 2 provides three-page layouts:

  1. Admin-empty
  2. admin-1column
  3. admin-2columns-left.

The admin panel offers the flexibility to choose a specific layout for each page. This level of customization allows for a diverse range of page structures without needing technical expertise.

Basic Layouts

The basic view of all storefront pages is found in two-page configuration layout files located in the Magento_Theme module:

  • To define the page layout:

<Magento_Theme_module_dir>/view/frontend/layout/default.xml

  • To define the scripts, images, and metadata included in pages' <head> section:

<Magento_Theme_module_dir>/view/frontend/layout/default_head_blocks.xml

These basic page configuration layouts are extended in other Magento themes. You can also extend or override these files in your custom theme.

Layout Handles

A layout handle is a unique identifier representing a set of layout instructions. It serves as the name of a layout file. There are three distinct types of Layout Handles:

  1. Page-type Layout Handles: These handles are synonyms for page-type identifiers and correspond to the full action names of controller actions. E.g., catalog_product_view.

  2. Page Layout Handles: These identifiers are specific to particular pages. It is associated with controller actions that include parameters identifying those specific pages.

  3. Arbitrary Handles: These handles don't correspond to any specific page type. Other handles can incorporate these handles for various purposes.

Layout File Types and Conventions

1. Layout file types: By role

When defining the layout of a webpage, two key components come into play: the page layout file and the page configuration file. Following are the definitions of each layout file type:

1. Page Layout

  • The page layout file is an XML document designed to declare the fundamental wireframe of a web page.

  • It is primarily responsible for defining the arrangement of elements within the <body> section of the HTML page markup.

  • It can specify a two-column page layout or other similar arrangements that determine how content is presented to users.

2. Page Configuration

  • The page configuration file is also an XML document, but its role is more elaborate.

  • This file not only outlines the structural elements but also delves into specific details such as the content and meta-information of a web page.

  • It encompasses the entire HTML structure, including the <html>, <head>, and <body> sections, providing a holistic view of the page.

3. Generic Layout

  • The generic layout file is an XML document.

  • It focuses on defining the detailed structure and content within the <body> section of the HTML markup.

  • It is especially valuable for pages generated in response to AJAX requests, emails, and HTML snippets. In these situations, a full-page layout may not be necessary.

2. Module and theme layout files

Module and theme layout files are categorized using specific terms. Various application components use these terms to distinguish between layouts. These include:


1. Base layouts

These layout files are provided by modules and are conventionally located in the following directory:

  • Page configuration and generic layout files: <module_dir>/view/frontend/layout
  • Page layout files: <module_dir>/view/frontend/page_layout

2. Theme layouts

Theme layouts are essential to website design and organization. These layout files play a pivotal role in shaping a website's overall appearance and structure.

They are typically provided by themes, which are collections of design elements and templates that determine the look and feel of a website. Themes are conventionally located in the following directory:

  • Page configuration and generic layout files: <theme_dir>/<Namespace>_<Module>/layout
  • Page layout files: <theme_dir>/<Namespace>_<Module>/page_layout

Key Elements of Layout

1. ReferenceContainer

The referenceContainer refers to any pre-existing container within your layout file. You can easily incorporate existing containers into your layout by referencing their names enclosed within <referenceContainer /> tags. For instance, suppose you wish to introduce content into the primary section of your webpage. In that case, you can achieve this by employing the following structure:

xml
<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" layout="1column" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
      <body>
            <referenceContainer name="content">
                  <container name="new.container" htmlTag="div" htmlClass="new-container" htmlId="custom-container">
                        <block class="Magento\Framework\View\Element\Template" name="custom.block" template="Vendor_Module::newtemplate.phtml" cacheable="false" />
                  </container>
            </referenceContainer>
      </body>
</page>

2. ReferenceBlock

You can use the referenceBlock to reference any pre-existing block within the layout file. It facilitates the utilization of existing blocks in your layout by specifying their names within tags.


These tags are instrumental in directing your layout to the precise location and attributes of the blocks you wish to utilize. For example, you want to eliminate the product SKU from the product detail page. In that case, you can achieve this with the following code snippet:

<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" layout="1column" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
      <body>
            <referenceBlock name="product.info.sku" remove="true"/>
      </body>
</page>

What are Containers?

Containers in Magento 2 layout for structuring web pages

A container serves as a wrapper. It can encompass one or more child blocks of other containers or simple content blocks. Containers empower developers to organize a page's layout and govern the positioning and presentation of its content.


In the page structure, we encounter various sections: the header, footer, left column, and main content area. It functions as a container, capable of housing multiple elements. For instance:

  • The header (container) can accommodate elements such as a Magento logo, navigation links, and a mini-cart.

  • The footer (container) can contain copyright information, social media icons, and additional links.

  • The left column (container) can host a sidebar menu, advertisements, or supplementary navigation.

  • The main content area (container) focuses on accommodating the central content of the page, including articles, images, and interactive features.

Key Elements of Container

1. Name

This serves as a unique identifier for the container within the layout of a web page. Each container must have a distinct name.


2. HTML tag

This feature specifies the HTML tag used to enclose the container's output. Options include aside, dd, div, dl, fieldset, main, nav, header, footer, ol, p, section, table, tfoot, and ul.


3. HTML class

This feature specifies the CSS class(es) applied to the wrapper HTML tag.


4. HTML ID

This feature defines an HTML ID for the container's wrapper tag. For example:


5. Label

This feature describes the purpose or content of the container.


6. As

It provides an alias name, acting as an identifier within the scope of the parent element.


7. Output

It determines whether the output should include the root element. If specified, the element will be added to the output list. If not specified, the parent element is responsible for rendering its children.


Sample of a structure within a layout:

xml
<container name="custom.container" htmlTag="div" htmlClass="custom-container" htmlId="custom-container">
    <!-- Your code goes here... -->
</container>

What are Blocks?

Blocks for rendering UI elements in Magento 2 layout

Blocks play a crucial role in rendering UI elements on the page. It achieves this by utilizing block tags within a layout XML file. It employs templates to generate HTML inserted into its parent structural block. Some common examples of blocks include category lists, mini carts, product tags, and product listings.


Information can be passed from the layout XML to the block using . For instance, elements like the logo, header links, category filter, and compare list are all considered blocks. The header, footer, main, etc., encapsulate these blocks within their respective containers.

Key Elements of Block

1. Name

The name serves as a unique identifier for the block within the layout.


2.Class

It represents the code that renders the block's output. It also specifies the name of the class that handles this rendering.


3. Template

This element defines the path to the template file used for rendering the block. The path notation typically includes the vendor, module, and template file names.


4. Cacheable

The default setting for this property is true, indicating that the block's output is cacheable. However, setting it to false will prevent the entire page from caching with a Full Page Cache.


5. Ifconfig

It allows the block's visibility to depend on a specific system configuration field. For instance, <block ifconfig="contact/contact/enabled" />.


6. Display

The display attribute determines if the block should display. It accepts true or false as its value.


7. As

This attribute gives the block an alias name that can serve as an identifier within the parent element.

Here is a sample that defines a block in the layout:

<block class="Vendor\Module\Block\Class"
       name="custom.block"
       cacheable="false"
       ifconfig="contact/contact/enabled"
       template="Vendor_Module::template.phtml" />

Similarities between Blocks and Containers

  1. Placement -You can position Blocks and Containers before or after another element based on identifying the element's name.

  2. Removal - They also share the functionality to remove elements from the rendering process in the frontend. The removal feature is on default, set to false.

  3. Element Movement - Blocks and Containers can relocate elements within a layout, enabling element movement.

How to Create Custom Layout File?

To create a new layout file, follow these steps:

  1. Begin by naming your new layout file as new_layout_index.xml. In this name:

    • "new" represents the front name of a module.
    • "Layout" is the name of the controller.
    • "index" is the name of the controller class.

  2. Within the "new_layout_index.xml" file, construct the structure of the web page as follows:

<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" layout="1column" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <container name="new.container" htmlTag="div" htmlClass="new-container" htmlId="custom-container">
            <block class="Magento\Framework\View\Element\Template" name="custom.block" template="Vendor_Module::newtemplate.phtml" cacheable="false" />
        </container>
    </body>
</page>
  1. The output of the above layout on a web browser will appear as follows:
<div class="new-container" id="custom-container">
      Content of block goes here...
</div>

FAQs

1. What is a Magento 2 layout overview?

A Magento 2 layout overview provides insights into creating layouts, containers, and blocks within your Magento module. A dedicated page XML file is used to achieve this.


2. What are the differences between default.xml and a specific page xml file?

The difference lies in the usage: default.xml makes universal changes like custom headers and footers across all pages. Specific page xml files, e.g., cms_index_index.xml, are for altering the layout of individual pages on a website.


3. How do I validate my Magento layout files?

To validate your layout files:

  1. Confirm the proper structure of your Layout XML file, ensuring the correct placement of tags.

  2. Validate that the actual rendering of block output matches your intended design.


4. Can I change the number of columns in my site’s pages?

You can adjust the number of columns on your website's pages. You'll need to work with the page layouts specified in the page configuration file to do this. These layouts are defined using the "layout" attribute within the <page> element.


For instance, let's consider the default category page, which typically has a layout of 2-left columns. If you want to change this to 3 columns, aligning with your design preferences, you must extend the layout file named "catalog_category_view.xml" within your theme.

Summary

Magento 2 layout defines the structure and content of web pages through XML files, offering flexibility in creating diverse page layouts for your Magento 2 store. We looked at the key components for customizing webpage designs, such as layouts, containers, and blocks in Magento 2.


Want more performance out of your Magento store? Explore Magento hosting to optimize your ecommerce website.

Maria Ajnawala
Maria Ajnawala
Technical Writer

Maria has over five years of expertise in content marketing, specialising in Magento insights and industry trends. She excels in creating engaging content that resonates within the Magento community.

Get the fastest Magento Hosting! Get Started