Common Magento theming issues

In this post I would like to discuss two common "gotchas" which often arise when implementing a new theme in Magento that might save others some time. The first outlines a situation where page titles will stop working, and the second issue can cause the checkout progress to stop updating. Here's how to avoid these pitfalls.

Breadcrumbs and page titles

Removing the breadcrumbs block should not be very difficult since it is just one line in the /layout/page.xml file. However, if you were to remove breadcrumbs by changing the /layout/page.xml file it will adversely affect page titles, which may not be what you expect.

The underlying issue is related to Magento's built-in flexibility that allows breadcrumbs to be used with page titles. The breadcrumbs block needs to be part of the page in order for page titles to be processed correctly. Removing the breadcrumbs block will result in products and categories to show the default store title, unless a title is explicitly defined in the backend. Since the aim is to only remove breadcrumbs from the design, the safest option is to modify the breadcrumbs template file:

 template/page/html/breadcrumbs.phtml

Replace the entire content of that file with:

<?php 
?>

This ensures that page titles work as expected, and yet no breadcrumbs appear on the page. Of course you could always use the more lazy method of using CSS to simply hide the relevant <div> as an alternative.

Custom onepage checkout layout

The default Magento checkout uses the "2column-right" layout, where the checkout progress block appears in the right column. As you progress through the checkout, the progress block is updated using javascript. However, the javascript in question relies on a hardcoded CSS class name, which is specifically related to the 2column-right layout. The javascript code, which can be found in

 skin/frontend/default/default/js/opcheckout.js

looks for the .col-right CSS class. When you decide to use a different layout, this CSS class will not be created and hence the progress block will stop updating.

To avoid this issue you need to copy the javascript file into your own template directory and change .col-right to match the class of the div that encloses <div class="one-page-checkout-progress">.

Have another common trap that has caught you more than once when developing a custom Magento design? Tell us how you avoid it in the comments.