Often you have call-to-action images that you want to display in several locations on your Magento site. Perhaps you are pushing a certain line of merchandise, offering a promotion, etc. These types of call-to-action images are referred to in Magento as callouts.

There are three ways to display a callout image in Magento:

  1. Calling it directly in a PHTML template file
  2. Selecting a CMS block in Magento’s category manager
  3. Updating Magento’s layout XML

The first option is perhaps the easiest — you figure out which template your image needs to be placed in, and drop the image code in the template PHTML file. The problem with this approach is that it’s neither modular nor flexible. Template files are used across different pages as defined by Magento’s layout XML. Perhaps you want to place a banner image above product listings on category pages, but not have the banner show when the product listings template is called on the search results page. Or, more specifically, you want to display the banner above the product listings on a specific category. In either case you would be writing code that is completely unnecessary to accomplish your design objectives.

The second option is much better than the first. Creating a static block in Magento’s CMS allows you to specify what category pages the image should display on. This way, you can manage what pages callout images are displayed on a selective basis. The problem with this approach is that selecting a CMS block from a dropdown in the Magento admin interface is limited to Category pages and further restricted depending on if the layout or template used to render a given category page calls the CMS block. Lastly, CMS blocks cannot be selected the admin for product pages.

Screenshot of a CMS Block being assigned to a category in the Magento admin
Category CMS Block Dropdown

The third option is the best. Using Magento’s XML layout engine provides the most flexibility. You can either create callout images inside a Magento CMS static block, or create them directly via XML. On category and product pages, you can call the XML within the Magento admin. Furthermore, category pages allow you to inherit layout definitions among subcategories. This means that you can define a callout image once and display on any/all descendant categories. If you require callout images on other types of pages (ie: the search results page, or customer dashboard), you can do so in your theme’s layout files using the proper XML layout syntax.

Screenshot of the Custom Layout Update field in the Magento category manager
Category Manager Layout Update
Screenshot of the Use Parent Category Settings dropdown in the Magento Admin
Use Parent Category Settings

Magento CMS + Admin Approach to Callout Blocks

Below are the steps to display a callout image on multiple category pages by creating a CMS static block, and calling it in the Magento admin.

Always perform the types of operations listed below in a development environment.

  1. Login to the Magento admin and navigate to CMS > Static Blocks.
  2. Click the Add New Block button in the top right.
  3. Provide a title, identifier and HTML for the static block, then click Save Block.

    Screenshot of a new CMS Block in the Magento admin
    Create New CMS Block
  4. Navigate to the Custom Design tab for the category that the static block should be displayed on.
  5. Add the proper XML in the Custom Layout Update field and click Save Category.

    Screenshot of a CMS Block being called on a Magento category in the Custom Layout Update field
    Update Category Layout

    The before="-" attribute instructs the Magento layout engine to place the CMS block before any other block within the <reference> block.

  6. Confirm the callout image is present in the category page(s) on the frontend.

    Screenshot of a cat banner shown on a Magento website
    Magento Callout on Frontend

Magento Theme Approach to Callout Blocks

Below are the steps to display a callout image in the customer account dashboaord by updating a Magento XML layout file in your theme.

  1. Login to the Magento admin and navigate to System > Configuration > Developer (the developer link is under the Advanced heading at the bottom of the page).
  2. Select the Current Configuration Scope in the top left of the page.
  3. Click the Debug heading and set Template Path Hints to Yes.

    Screenshot of the Template Path Hints dropdown in the Magento Admin
    Template Path Hints Configuration
  4. Open up the frontend of the site and login to a customer account.
  5. Take note of the template path that is in the location you want your callout image to appear.

    Screenshot of Magento template path hints displayed in the customer dashboard
    Template Path Hints
  6. Open the XML layout file in in your theme that is in charge of loading the template file from the previous step.
  7. Find the XML block inside the layout file that is responsible for loading the template file identified in step 5.
  8. Add the proper XML to display your callout block.

    Screenshot of a Magento CMS block being called in the customer.xml layout file
    Customer XML Layout

    While this is a perfectly valid way to update your theme’s XML layout files, a better approach to layout updates is accomplished by creating a local.xml file for your theme. While that is outside the scope of this post, there is a good reference on the local.xml approach on Inchoo’s blog.

  9. Save the XML layout file and confirm the callout image is present in the customer dashboard on the frontend.

    Screenshot of a cat banner shown in the customer dashboard of a Magento website
    Magento Callout on Frontend

Magento “Callout” Approach to Callout Blocks ~ bonus

Magento is flexible enough that you can create callouts entirely in XML (no CMS block required). The nice thing about a pure XML approach is that you don’t have to clutter your CMS with static blocks that perform the very simple task of displaying callout images. The downside of this approach is that changes to the callout are more reliant on developers than the previous options. So, if your team manages content more efficiently/effectively in the Magento CMS, this probably is not the best approach. Onward…

Inside the default theme of Magento’s base package, there is a directory named callouts. That directory contains two template files named left_col.phtml and right_col.phtml. These files are responsible for rendering callouts on the frontend. The former is intended for callouts displayed in the left sidebar, the latter is for the right sidebar. Instead of using a <block type="cms/block"> in your XML layout, you will use a <block type="core/template">. Below, I’ll show you how to create a new callout template to display the cat banner in your customers’ dashboard.

  1. Copy the template files from /app/design/frontend/base/default/template/callouts to the callouts directory in your theme. Since I am using Magento’s rwd package, I’ll copy the files to the callouts directory of the default theme located at /app/design/frontend/rwd/default/template/callouts.

    If you don’t have a callouts directory in your theme, you’ll need to create it.

    Screenshot of Magento callouts directory being copied to another theme
    Magento Callouts Directory
  2. Inside your theme’s callouts directory, copy the left_col.phtml to a new template file named main_col.phtml.
  3. Open main_col.phtml and adjust the code as needed. I’ll echo some “Hello World” text for the example.

    Screenshot of a text being added to a Magento callout template file
    New Callout Template
  4. Add the proper XML to display your callout block using the new main_col.phtml template file to render it.

    Screenshot of a Magento callout block being called in the customer.xml layout file
    Customer XML Layout

    Above we use a few new <action> methods. There is a good overview of Magento’s action methods on StackOverflow. Again, a better way to modify your theme’s XML is to use the local.xml approach explained on Inchoo’s blog.

  5. Save the XML layout file and confirm the callout image is present in the customer dashboard on the frontend, along with the “Hello World” text.

    Screenshot of a cat banner shown in the customer dashboard of a Magento website
    Magento Callout on Frontend
Posted by: John Dugan

Comments