Adding a block to magento category page using local.xml

Adding a block to magento category page using local.xml

August 18, 2026 · Illustrated author avatarBy Stefan Bogdanescu
Adding a block to magento category page using local.xml

Adding a Block to Magento Category Page Using local.xml

Hello developers,

Let’s dive into a common challenge faced by many Magento users: adding a custom block to the category page using the local.xml layout update file. I understand that you have already explored several resources, but let me provide a step-by-step guide to help you overcome this issue successfully.

Understanding the Current Setup

Firstly, let’s clarify what you’ve done so far:

  1. You created a new template file named image.phtml under the path mytheme/template/catalog/category/.

    • The correct location should be mytheme/app/design/frontend/<your_package>/<your_theme>/template/catalog/category/image.phtml.
  2. You added some test text “I am here” to this phtml file.

    • Ensure that you have rendered the text using a PHP echo statement, e.g., echo 'I am here';
  3. You included the following XML code in your local.xml under the catalog_category_default layout:

<reference name="content">
    <block type="catalog/category_view" name="category.image" template="catalog/category/image.phtml"/>
</reference>

The Issue and Solution

The problem lies in how you defined the block type. In Magento 2, the catalog/category_view is not a valid block type for displaying category-specific content.

To resolve this issue, you should use the core Magento_Catalog module’s category.image block instead:

  1. Update your local.xml code as follows:
<reference name="content">
    <block class="Magento\Catalog\Block\Category\View" name="category.image" template="catalog/category/image.phtml"/>
</reference>
  1. Ensure that you have correctly referenced the image.phtml file in your theme’s folder structure.

    • The layout updates will look for the template file in the specified location relative to the app/design/frontend path.
  2. Flush Magento cache:

    • Navigate to System > Cache Management
    • Select all cache types and click “Flush Cache”
  3. Verify that your category page is displaying the text “I am here” at the top of the content area, above the left navigation menu.

Displaying Category Image

Now that you have successfully created a working block for testing purposes, let’s move on to displaying the category image:

  1. Replace the test text in image.phtml with the following code:
<?php if ($block->getImage()): ?>
    <img src="<?= $block->escapeHtmlAttr($block->getImage()->getFile()) ?>" width="200" height="200">
<?php endif; ?>
  1. Update your local.xml to include the category image block:
<reference name="content">
    <block class="Magento\Catalog\Block\Category\View" name="category.image" template="catalog/category/image.phtml"/>
</reference>
<reference name="page.wrapper">
    <reference name="header.container">
        <block class="Magento\Theme\Block\Html\Header" template="Magento_Theme::html/header.phtml">
            <arguments>
                <argument name="is_stack" trans_replace="true">false</argument>
            </arguments>
        </block>
    </reference>
</reference>
  1. Flush the Magento cache again.

Conclusion

Adding a block to the category page using local.xml might seem complex initially, but it becomes straightforward once you understand the correct approach. Remember to use the Magento\Catalog\Block\Category\View class for the category image-specific content and ensure that your template file is located in the appropriate theme folder.

If you’re looking for more advanced layout customizations or Magento 2 development services, feel free to explore our offerings at Laravel Company. We specialize in delivering high-quality, optimized solutions tailored to meet your e-commerce needs.

Happy coding!

Magento 2 Catalog Extensions Themes

Our network