OCMLABS/MODULE-WORDPRESS · LAYOUT HANDLES

Layout Handles

  • Magento
  • Adobe Commerce
  • Hyvä

The Observer/LayoutLoadBefore.php observer dynamically adds a layout handle to every blog page request. These handles allow targeted layout customization per page type.

Layout Handles

HandlePageLayout File
ocmlabs_blog_indexBlog post listingview/frontend/layout/ocmlabs_blog_index.xml
ocmlabs_post_viewSingle post pageview/frontend/layout/ocmlabs_post_view.xml
ocmlabs_category_viewCategory archiveview/frontend/layout/ocmlabs_category_view.xml
ocmlabs_tag_viewTag archiveview/frontend/layout/ocmlabs_tag_view.xml
ocmlabs_author_viewAuthor archiveview/frontend/layout/ocmlabs_author_view.xml
ocmlabs_search_resultsSearch resultsview/frontend/layout/ocmlabs_search_results.xml

Additional Handles

HandleAdded whenLayout File
ocmlabs_sidebar_menuIncluded by the blog home, post, category, tag and search handles. Adds the WordPress menu block to sidebar.mainview/frontend/layout/ocmlabs_sidebar_menu.xml
ocmlabs_blog_index_front_pageBlog home, first page only, when Blog Home Page Content is a Front Page option and a front page is set in WordPress. Adds the wp.blog.front.page blockview/frontend/layout/ocmlabs_blog_index_front_page.xml
ocmlabs_blog_index_front_page_onlyAs above, with WordPress Front Page Only. Removes the wp.blog.post.list blockview/frontend/layout/ocmlabs_blog_index_front_page_only.xml

These were added in 2.1.0. The blog controller adds the front page handles before the layout loads.

Page Layout

Since 2.1.0, the page layout (2columns-left, 2columns-right or 1column) comes from the Page Layout settings. The observer sets it on the page config, which takes precedence over the layout attribute in the module’s layout files and in your theme’s.

How Handles Are Added

The handle name is constructed as ocmlabs_{controller}_{action}:

  • Controller name: the request controller name (set by the Router based on the URL pattern matched)
  • Action: the controller action name (index, view, results)

For the post view controller, the handle is ocmlabs_post_view. For the blog index controller, it is ocmlabs_blog_index.

Since 2.0.5, Magento also adds its own default handle for each blog page, built from the wordpress route name, for example wordpress_blog_index and wordpress_post_view. The module ships no layout files for these. Use the ocmlabs_* handles for your customizations.

Using Layout Handles in Your Theme

To add content to the blog listing page sidebar in your theme:

File: app/design/frontend/Your/Theme/OCMLabs_WordPressIntegration/layout/ocmlabs_blog_index.xml

XML LAYOUT
<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceContainer name="sidebar.main">
            <block class="OCMLabs\WordPressIntegration\Block\Sidebar\Categories"
                   name="blog.sidebar.categories"
                   template="OCMLabs_WordPressIntegration::sidebar/categories.phtml"
                   after="-"/>
        </referenceContainer>
    </body>
</page>

To apply changes to all blog page types at once, use a layout update that references all six handles.

See also

Related pages

In this module