Inserting blocks into custom places in Magento2

Inserting blocks into custom places in Magento2

August 29, 2026 · Illustrated author avatarBy Stefan Bogdanescu
Inserting blocks into custom places in Magento2

Inserting Blocks into Custom Places in Magento2

In Magento 1, customizing the layout was straightforward—you could simply edit the local.xml file to add blocks or modify existing ones. However, with the migration to Magento 2, the process has changed significantly due to the adoption of XML layouts instead of layout handles. Let’s explore how to achieve similar functionality in Magento 2.

Understanding Magento 2 XML Layouts

In Magento 2, the layout system uses XML files stored under app/design/frontend/<Vendor>/<Theme>/Magento_Theme/layout. These files define the structure and content of your pages through various block references. The main file is typically called default.xml.

Adding a Custom Block to an Existing Page Structure

To insert a custom block into a specific location, you’ll need to modify one of these XML layout files. Let’s say we want to add a new banner above the main content area on all pages.

  1. Create your template file: First, design and save your banner template as app/design/frontend/<Vendor>/<Theme>/Magento_Theme/templates/banner.phtml.

  2. Add the block to the XML layout: Open or create the default.xml file under your theme’s layout folder. Add the following code within the <reference name="root"> tag:

<block class="Magento\Framework\View\Element\Template" name="above_main" template="Magento_Theme::banner.phtml"/>

This creates a new block named above_main, which references your custom template file.

  1. Insert the block into the page structure: Next, you need to insert this new block at the desired position in the existing layout. Find the <reference name="main.content"> container within your theme’s XML layout files.

  2. Add the reference for the new block: Add the following line just before the </reference> closing tag:

<block name="above_main" template="$block->getNameInLayout()" as="above_main"/>

The $block->getNameInLayout() function ensures that the correct template is used.

Modifying an Existing Template

If you want to insert a block into an existing template file, you’ll need to override the original file in your theme. Here’s how:

  1. Find the original template: Locate the page/html/body.phtml file within Magento 2 core at vendor/magento/module-theme/view/frontend/templates/page/html/body.phtml.

  2. Create an override: Copy this file to app/design/frontend/<Vendor>/<Theme>/Magento_Theme/templates/page/html/body.phtml. This creates a local copy that Magento will use instead of the original.

  3. Add the block insertion: Find the line where you want to insert your new block within the overridden template file. Let’s say we want to add our banner above the main container.

<div class="main-container col2-left-layout">
    <?php echo $this->getChildHtml('breadcrumbs') ?>
  1. Insert the new block reference: Just before this line, add:
<?php echo $this->getChildHtml('above_main') ?>
  1. Update the XML layout: Finally, make sure your above_main block is referenced in one of your theme’s XML files as described earlier.

Conclusion

While Magento 2 has made some significant changes to its layout system compared to Magento 1, the process of inserting blocks into custom positions remains achievable with careful attention to XML layouts. By understanding and leveraging these new systems effectively, developers can maintain a high level of flexibility in page design and structure within their Magento 2 implementations.

For more detailed information on working with themes and layouts in Magento 2, I highly recommend checking out the Laravel Company guide on theme development. This comprehensive resource provides step-by-step instructions and best practices for creating and managing themes in Magento 2.

Remember, the key to successful layout customization lies in a deep understanding of XML layouts, block references, and the overall page structure. With practice, you’ll find that Magento 2 offers powerful tools for tailoring the user experience across your store’s pages.

Magento 2 Magento 1 Themes Configuration

Our network