Magento category image widget

Widgets can be thought of as small applications embedded on a web page.

I think this definition could also apply to Magento widget which is a small piece of server side and/or client side code that can be added to a CMS page or a static block.

There are many predefined widgets in Magento for popular tasks, however, if there is a need for a functionality that is not already made, a custom widget can be created.

Sometimes there is a need to display image of a certain category inside a static block or a cms page. We might want to show an image of a certain category on a static page.

Let’s see how to do it.

Creating module

We can define a new module for this. First we need to create our module. In config.xml we will define block and helper:



<?xml version="1.0"?>


<?xml version="1.0"?>

Creating widget configuration

Now that we have our module defined we can start creating category image widget. First thing we need is a configuration file – widget.xml where our widget behavior is defined.

There is more than one way to define template path in a widget. We could:

  • – Call setTemplate method in constructor,
  • – Add our own layout file,
  • – Add template path in widget.xml file.

I think that the third approach is the best from usability perspective since in that case user can easily choose between multiple templates if that’s needed. So we’ll define our template in widget.xml.


<?xml version="1.0"?>
    <category_widget_image type="ldusan_category/category_widget_image" translate="name description" module="catalog">
        <name>Catalog Category Image</name>
        <description>Specified Category Image</description>
            <id_path translate="label">
                        <button translate="open">
                            <open>Select Category...</open>
            <template translate="label">

This xml looks a lot like category link widget’s xml file which provides similar functionality. We just borrowed a component that was already built and that is adminhtml/catalog_category_widget_chooser. No need to reinvent the wheel :)

Creating block

Next, we should create a block which is a main part of our widget. It’s important to notice that all widgets must implement Mage_Widget_Block_Interface:


class LDusan_Category_Block_Category_Widget_Image
extends Mage_Core_Block_Template
implements Mage_Widget_Block_Interface
     * Retrieves image path from widget data
     * @return string
    public function getCategoryImageUrl()
        if ($idPath = $this->getData('id_path')) {
            $categoryId = Mage::helper('ldusan_category')->getCategoryIdByIdPath($idPath);
            $category = Mage::getModel('catalog/category')->load($categoryId);
            return $category->getImageUrl();

Besides constructor we need only one method in this class – the one which will get us the path of the category image selected in a widget. Store switcher component gave us “id_path” (that’s how we named it in widget.xml) of the selected category. That value is now property of the widget block and we can easily get it.

Helper for getting category id

Now we need to get category id from id path. After that we can load that category in order to get its image path. Since getting a category id by id_path is a reusable functionality, we can create this method inside a helper class:


class LDusan_Category_Helper_Data extends Mage_Core_Helper_Abstract
    * Retrieves category id for given id path
    * @param string $idPath
    * @return int
    public function getCategoryIdByIdPath($idPath)
        $storeId = Mage::app()->getStore()->getId();
        $rewrite = Mage::getResourceModel('catalog/url')->getRewriteByIdPath($idPath, $storeId);
        $categoryId = $rewrite->getCategoryId();
        return $categoryId;

Id_path is category’s unique path identifier. The resource model of catalog/url has a useful method – getRewriteByIdPath which returns category id by id_path. We will call that method and just return category id.

Note: Actually it does not matter which store we pass since id path is the same for all stores.


Now we just need to create template file that will show the actual category image:


<?php if($categoryImageUrl = $this->getCategoryImageUrl()): ?>
<img src="<?php echo $categoryImageUrl ?>" />;
<?php endif; ?>

I love those conditional assignments :)

Wrap up

So that’s it. Go to any cms page or static block, click on add widget and it should look something like this:

Widget screen in admin panel

Widget screen in admin panel

So hope that helped, let me know if it works for you :)

Would you like to recommend this article to your friends or colleagues?
Feel free to share.

This article was posted in category Magento, PHP.

Article "Magento category image widget" has 4 responses

Leave a Reply to ed Cancel reply

Your email address will not be published. Required fields are marked *