Extending Magento Widget Layout within a Theme
Adding custom functionality to default Magento widgets is a common requirement for many projects. In this post, we’ll explore how to extend the Catalog Products List widget layout file found in vendor/magento/module-catalog/widget/etc/widget.xml.
The Challenge: Overriding the Default Widget XML File
The developer wants to add an additional template option (“Alternate Products Grid Template”) to the products_list widget. They have created a theme located at app/design/frontend/Vendor/theme, and placed their own version of the widget.xml file in app/design/frontend/Vendor/theme/Magento_CatalogWidget/widget.xml.
However, despite following best practices for theme configuration, the custom widget.xml file is not overriding the original one. This leads to the existing issue:
$ cat app/design/frontend/Vendor/theme/Magento_CatalogWidget/widget.xml
Understanding Magento Widget Structure
Before we dive into the solution, let’s understand how Magento widget layouts are structured.
The default widget.xml file in the magento-catalog-widget module defines a set of parameters for the products_list widget. These include options like “Title”, “Number of Products per Page”, and most importantly for our use case, the “Template” parameter:
<widget id="products_list"...>
...
<parameter name="template" xsi:type="select" required="true" visible="true">
...
<option name="default" value="product/widget/content/grid.phtml" selected="true">Products Grid Template</option>
...
</parameter>
...
</widget>
The Solution: Correct Theme Configuration
The key to successfully overriding the default widget layout is proper theme configuration. It’s not enough to simply place the widget.xml file in your theme directory.
To extend the Magento widget layout, you must follow these steps:
- Create the Widget Layout XML File
Create a new XML file (let’s call it catalog_widget.xml) in your theme’s layout directory: app/design/frontend/Vendor/theme/Magento_CatalogWidget/layout/catalog_widget.xml.
- Define Your Extensions
Open this new file and define your extensions for the products_list widget:
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
<body>
<referenceContainer name="catalog_widget_products_list">
<block class="Magento\CatalogWidget\Block\Product\ProductsList"
template="Magento_CatalogWidget::product/widget/content/alternate-grid.phtml" />
</referenceContainer>
</body>
</page>
- Update the Theme’s etc/view.xml File
Open your theme’s etc/view.xml file and add a new XML node to include your custom layout:
<view xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Theme:etc/view.xsd">
...
<media>
...
</media>
<ui_component>
...
</ui_component>
<layout>
<update handle="catalog_widget"/>
</layout>
</view>
- Clear Cache
Finally, clear your Magento cache to ensure the changes take effect.
Conclusion
By following these steps and properly configuring your theme’s layout files, you should be able to successfully extend the widget.xml file for any built-in widget in Magento without touching the core framework.
This approach allows for a clean separation of concerns between your theme and the base system, ensuring that updates to the core do not overwrite your customizations. It also promotes better maintainability and easier theme upgrades or migrations.
Remember, always ensure you have proper version control in place when working with Magento themes. This helps prevent loss of work and facilitates easy collaboration if needed.
For more detailed information on Magento 2 theme development, check out our comprehensive guide at Laravel Company’s Magento 2 Theme Development Tutorial.