After July 2021, the 2.3.x release line will no longer receive quality updates, or user guide updates. PHP 7.3 reaches end of support in December 2021 and Adobe Commerce 2.3.x reaches end of support in September 2022. We strongly recommend planning your upgrade now to Adobe Commerce 2.4.x to help maintain PCI compliance.

Using Layout Updates

The information on this page is intended for Adobe Commerce 2.3 customers who are on an extended support contract. The Adobe Commerce Merchant Documentation for current releases is published on the Adobe Experience League.

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 our Frontend Developer Guide.

Step 1: Create the block

  1. Create the block that you want to place.

  2. Take note of the block_id, because you will need to reference it in the layout update instructions.

Step 2: Compose the layout update in XML

  1. Compose the layout instructions in XML to Reference a CMS Block.

  2. Save the layout instructions on the server in the layout folder where XML files are saved for the theme.

    For example:


    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 the xml file suffix. In the following example, customer-service is the URL key of the page, and ChatTool is the option that you select to apply the layout update to the page.


    CMS Page Identifier The URL key of the page with any forward slash (/) replaced by an underscore (_).
    Layout Update Name The option that appears in the Custom Layout Update list.

Step 3: Reference the layout update from the page

  1. On the Admin sidebar, go to Content > Elements > Pages.

  2. Find the page where you want to place the block and open it in edit mode.

  3. Scroll down and expand the Design section.

  4. Click Custom Layout Update arrow to display all available layout updates that are associated with the page.

    Custom Layout Update list

  5. Select the layout update that you want to apply to the page.

Step 4: Save and refresh cache

  1. When complete, click Save & Close.

  2. In the message at the top of the workspace, click Cache Management and refresh each invalid cache.