Magebase

Quick Tip: Disable all Local Modules at Once

Robert Popovic — Mon, 13 Feb 2012 05:00:14 +0000

While going through the study guide for the Magento Developer Exam, I’ve been learning a few interesting details that are squirreled away in the Magento code, but can be useful in day to day Magento development.

For example, while going through the section on Module loading, it is revealed that we can easily disable all modules living in the local (app/code/local) namespace by editing app/etc/local.xml and setting the disable_local_modules node to true:


    
        ...
        true
        ...
    
    ...

Of course, if you have cache enable, clear or disable it to see the effects.

This will immediately prevent Magento from loading any code from your local code pool. You could use this to troubleshoot issues with custom modules or local Mage overrides. Of course, to find the exact culprit would require disabling individual modules one by one but at least you can narrow down your area of search quickly this way.

Note that this will not affect the community modules.

Quick Tip: Easy pop-ups with window.js in the front end with Magento

Robert Popovic — Sat, 05 Nov 2011 05:33:51 +0000

Magento comes with a lot of files, utilities and libraries, one of which is window.js. It is a Prototype based library implementing some classes that allow you to add windows to a web page. This can be simple pop-ups and modal windows and dialogs. They can be dragged, minimized, resized and closed. You can open multiple windows if you wanted to. You can load content from a link, an HTML container on the page or via Ajax. This library is seriously versatile. The Magento admin already uses window.js for various pop-up functions such as the widget options and image management. Well if the back end can do it, then the front end can too.

How to use it

The library is located under [magento_root]/js/prototype/window.js. Additionally, window.js comes with a bunch of CSS themes found under: /js/prototype/windows/themes/*. To load the library in the front end we will make or add an entry to our design theme’s local.xml:


    
        
        js_cssprototype/windows/themes/default.css
        js_cssprototype/windows/themes/magento.css

The bare minimum necessary to make the windows look right is default.css. In our example above, we are also loading a supplied window.js theme: magento.css. This is the theme that the back-end loads. Now, that we have the library and styles loaded, what can we do with this? For example, we can load the compare items page in a nice pop-up instead of opening a new window. Make an override of the template/catalog/product/compare/sidebar.phtml in your local design theme and add the following to the end:

Also modify the line that says:

to:

Add some items to compare and click on the “Compare” button and, voila, your compare page loads in a nice pop-up. I know, the Magento window theme isn’t exactly the most exciting one, but you can copy a theme CSS file to your local skin CSS folder and customize to your heart’s content.

Now, we might notice that the button actions in the compare window don’t quite work as expected. This is due to some of the links like Add to Cart and Add to Wishlist use setPLocation to set the target page URL. This won’t work in our pop-up since window.js loads the page into an iframe. So the remedy is to override the product/compare/list.phtml and add:

Then replace all setPLocation calls with setILocation.

The close button won’t work either but you don’t really need that as the window provides its own close button so you can simply remove it from the template.

Conclusion

In our example we saw how to open the compare page in a window.js pop-up. You can use this approach to create size guide pop-ups for example. However this is a powerful library and can do much more that just pop-up windows. To get a good overview of its power, visit the window.js homepage at prototype-window.xilinus.com. You will find the documentation and a few examples there.

Magento Sort By Newest Products Made Easy

Robert Popovic — Thu, 27 Oct 2011 09:13:04 +0000

The Situation

Recently, I had the pleasure of working on an existing site we took over. The site had been upgraded from Magento CE to EE before it came to me. One of the tasks was to make a new enterprise theme and clean up any unused or incompatible extensions.

I will just focus on one extension here that was added to allow the catalog to be sorted by newest products. This is the EWTechnologies_SortByNewest. It came to my attention after debugging the toolbar for not showing the pagination links where there is more than one page of products. So I looked into it and to my horror realized that it was overriding the default Mage_Catalog_Block_Product_List_Toolbar class but extending from Mage_Page_Block_Html_Pager. If that wasn’t bad enough, it was also completely overriding the Mage_Eav_Model_Config class. This one has been substantially changed in later versions of Magento so the override implements very old code. I decided that this is too risky to keep even though there were no other visible adverse effects. It certainly isn’t best practice to run outdated code in any case.

I thought this feature shouldn’t require overriding so much core code so I investigated and, to my delight, found that the solution was very simple and quite elegant and didn’t involve overriding any core code as such.

The Approach

The Product Entity in Magento has a ‘created_at’ attribute which stores the date when the product was created. Logically, it lends itself to be used for the sort by newest feature as it is set only once by the system, when the product was created.

A look into the eav_attribute table gives us the attribute_id and an inspection of the catalog_eav_attribute table shows that the attribute is set to not be used in the sort by drop-down. So, the obvious course of action was to set the attribute’s used_in_sort_by field to 1 and then the only other thing left was to update the frontend_label in eav_attribute to read “Newest”. That’s all, folks!

The Extension

I’ve whipped up a quick extensions that will perform those updates and makes it easy to install on any site that needs this feature.

Note: This should work fine for Magento CE 1.4.x and up, PE, EE 1.8.0 and up. There is no guarantee and I don’t provide support for this extension. Use at your own risk and ALWAYS backup your database before installing.

Download it here.

Conclusion

This approach should be upgrade safe and works on any Magento CE version over 1.4 as well as PE and EE versions. The only issue would be if a future Magento upgrade was updating the created_at attribute but then it’s easy enough to reapply the database edits to restore functionality – easier than troubleshoot issues with core code overrides.

Update: If you want to set the default sort direction for the toolbar, you can do this via the layout XML. Best in your local.xml but you can edit catalog.xml if your theme has overridden that:


    /* other layout nodes */
    
        desc
    



    /* other layout nodes */
    
        desc

Quick Tip: Using a Frontend Model For Your Module Configuration Parameter

Robert Popovic — Mon, 05 Sep 2011 05:00:44 +0000

If you’re a fastidious Magento module developer, you will try to make sure that your module options only reveal the necessary and configured fields to the admin user and hide all the irrelevant stuff. Specifically, I’m referring to Yes/No options that allow the administrator to enable and configure a subsequent option. For example, you have an extension that can show additional field content if an option is enabled and allows for entering the field contents:

Standard options configuration

As we can see, the initial state is ‘No’ for the ‘Enable Additional Text’ option, and the textarea is blank. It would be really nice if the whole ‘Additional Text’ row was hidden in this scenario.

We can achieve that by utilizing a front end model for our Yes/No option. Magento provides this mechanism for creating options that depend on certain settings or other dependencies. Some of the built in options are the ‘Allowed Countries’, Enable Flat Catalog Products/Categories and the Tax Destination Calculation ‘State’ option.

We are going to use the front end model to add some logic to enable/disable the textarea and some JavaScript to enable the toggle functionality when the Yes/No drop-down is changed. Note that this is just one, albeit trivial, example of using this technique. Especially since Magento provides the node for this specific purpose (see the update below).

Using the same tutorial module from our Explain Your Module Configuration Options With Tooltips quick tip, we’ll change our system.xml to read:



    
        
            Magebase
            700
        
    
    
        
            magebase
            Magebase Tutorial Options
            text
            10
            1
            1
            1
            
                
                    Conditional Toggle Options
                    text
                    10
                    1
                    1
                    1
                    
                        
                            Enable Additional Text
                            select
                            adminhtml/system_config_source_yesno
                            custom/adminhtml_system_config_form_field_customopt1toggle
                            10
                            1
                            1
                            0
                            Select whether to show a text block in the front end.
                        
                        
                            Additional Text
                            textarea
                            20
                            1
                            1
                            0
                            Enter the content for the text block.
                            Note that the content will be erased if you disable it above, and save.

The key to our quick tip is in:

custom/adminhtml_system_config_form_field_customopt1toggle

So, now, we’re going to create the front end model class. Incidentally, even though it’s named a ‘model’ class we are going to create it as a Magento Block class since this is how the other built in front end model classes are implemented. Effectively, it is used for template output so it’s appropriate to create a block class for this.

Create Customopt1toggle.php under .../Magebase/Custom/Block/Adminhtml/System/Config/Form/Field/ with the following content:

class Magebase_Custom_Block_Adminhtml_System_Config_Form_Field_Customopt1toggle extends Mage_Adminhtml_Block_System_Config_Form_Field
{

    /**
     * Get element ID of the dependent field to toggle
     *
     * @param object $element
     * @return String
     */
    protected function _getToggleElementId($element)
    {
        return substr($element->getId(), 0, strrpos($element->getId(), 'mbcustomopt1')) . 'mbcustomopt2';
    }
    /**
     * Get element ID of the dependent field's parent row
     *
     * @param object $element
     * @return String
     */
    protected function _getToggleRowElementId($element)
    {
        return 'row_'.$this->_getToggleElementId($element);
    }
    /**
     * Override method to output our custom HTML with JavaScript
     *
     * @param Varien_Data_Form_Element_Abstract $element
     * @return String
     */
    protected function _getElementHtml(Varien_Data_Form_Element_Abstract $element)
    {
        // If our Yes/No toggle is 'No' then disable the text value field
        if(!$element->getValue() || $element->getValue()!=1) {
            $_frm = $element->getForm();
            $_elm = $_frm->getElement($this->_getToggleElementId($element));
            $_elm->setDisabled('disabled')->setValue('');
        }
        // Get the default HTML for this option
        $html = parent::_getElementHtml($element);
        // Set up additional JavaScript for our toggle action. Note we are using the two helper methods above
        // to get the correct field ID's. They are hard-coded and depend on your option names in system.xml
        $javaScript = "
            ";

        $html .= $javaScript;
        return $html;
    }
}

The Varien_Data_Form_Element_Abstract class implements the _getElementHtml() method responsible for generating the HTML for each option element. This is where we can add out override and ‘inject’ some custom code to control the other element as well as the JavaScript to implement the dynamic toggle functionality. The code is self-explanatory.

Basically, we have a couple of helper methods to return our HTML field and row ID’s depending on the names we gave our options in config.xml. The _getElementHtml() method just sets the disabled state of the textarea field if the option is ‘No’ and adds the Prototype JavaScript to add our toggle functionality. The JavaScript code will execute on page load and completely hide the text field if the option is ‘No’ and install an event observer on the Yes/No drop-down to show/hide the text option.

The result of our work would look like this initially:

Toggle options - Text Hidden

Selecting ‘Yes’, wil toggle the next field into its visible state:

Toggle options - text revealed

Conclusion

We’ve seen how to create a nice little usability enhancement to busy module option pages. You can take this paradigm and enhance it for your own specific purposes. You can study the other examples of the built in Magento options using a frontend_model class for more inspiration and ideas.

One note, the above solution will erase a text option once its saved when the toggle is set to ‘No’. If you’d like to preserve the option, just remove the PHP code setting the text field as disabled as well as the $('{$this->_getToggleElementId($element)}').disabled = (!enabled || enabled!=1); JavaScript line. That should allow the hidden option to be saved.

Update:

The same result as above can be achieved by utilizing the node in the system.xml as Damián pointed out:


    
        Enable Additional Text
        select
        adminhtml/system_config_source_yesno
        10
        1
        1
        0
        Select whether to show a text block in the front end.
    
    
        Additional Text
        textarea
        20
        1
        1
        0
        1
        Enter the content for the text block.

However, this article illustrates how you can potentially add custom option processing using the front end model option. This is more relevant for example if you have an option where you need to check more complex conditions or link several options together.

Quick Tip: Conditional Loading of JavaScript and CSS Using Your Module Configuration

Robert Popovic — Tue, 09 Aug 2011 21:26:26 +0000

I don’t know about you but I often find myself removing third party module’s CSS and sometimes even JS files from loading in my custom themes because I need to change most of the styling and don’t want to add bulk to my site.

Traditionally, I do it using my local.xml as outlined in my previous article. However, it would be good practice if module developers would provide the option right from their module configuration.

This is actually really easy to do, watch this:

1. Create configuration options in system.xml:

...

    
    Advanced
    text
    100
    1
    1
    0
    
        
            Load Stylesheet
            select
            adminhtml/system_config_source_yesno
            10
            1
            1
            0
            Set to No if the supplied stylesheet file should not be loaded.
        
        
            Load Javascript
            select
            adminhtml/system_config_source_yesno
            20
            1
            1
            0
            Set to No if the supplied javascript file should not be loaded.
        
    
    

...

Here, I’m only showing the relevant part for brevity. Essentially, I have an Advanced section with two Yes/No drop downs which allow the admin to configure the desired options.

2. Add your conditional includes to your module’s layout XML:

        
            css/my_module/my_module.css
            skin_jsjs/my_module/my_module.js

And there you have it. Your css and js will only be included if the configuration allows it.

Improving the File Cache Backend

Vinai Kopp — Mon, 01 Aug 2011 21:00:44 +0000

The purpose of this post is to spread knowledge about the bolts and gears of the Magento cache system among developers, and to share one method of overcoming some limitations of the file cache storage class.

This article basically started with the site of a client who was having performance issues: when the cache reached about 38000 records, he was actually forced to clear the cache to keep the site responsive enough.

How strange is that? Shouldn’t a full cache give a better performance then an empty cache?

The number of records stored in the Magento cache depends on many factors, amongst others the number of store views, if a full page cache is used or not, and the size of the catalog. Many Sites don’t go above 1000 or 2000 cache records, but for large instances much higher values are common.

The performance issues of my client only occurred on specific pages, one of the most noticeable being the add-to cart action. Dropping a product to the cart took up to 4 seconds!
Using some profiling, we could pin the issue down on part of the (full page) cache being cleared, more precisely, when the mini-cart in the page header had to be rebuilt.

Lets have a look at how the Magento caching (which uses the Zend_Cache library) works.
Each cache entry consists of the following information

the cached data
a cache key (or ID), that uniquely identifies this entry and is used to retrieve the data from the cache
a cache lifetime, after which the cache entry expires
zero or more cache tags

Most of these are obvious, but what is the purpose of cache tags? Cache tags are used to segment the cache for partial deletion. For example, you could clear all entries of the configuration cache, without touching the any entries of the HTML block cache.

On the cache management page most of the cache tags used by Magento are listed. Depending on the modules and extensions installed there could be more or less tags, e.g. CONFIG, LAYOUT_GENERAL_CACHE_TAG, BLOCK_HTML, TRANSLATIONS, FULL_PAGE_CACHE, …

Listed Cache Tags

All the information associated with the cache record is saved in the cache storage every time the method Mage::app()->saveCache() is called. And to read cache records the Method Mage::app()->loadCache() is used.
Magento offers several different options what to use as a cache storage, and each of these storage systems is used by means of a PHP class called “cache backend”.

By default, cache data is stored in files (located in the directory var/cache/). Another option is the database, which is slower then the files option mostly because the database is a heavily used resource for Magento instances anyway. Then there are storage schemes that use RAM (which are much faster), e.g. APC (shared memory) or memcached (a networked caching server).

So, lets use RAM as our cache storage, right?

Sounds good, except for one problem: APC and memcached only support storing simple key-value pairs, so the cache tags are lost! This renders the whole caching rather useless, because every time we need to clear only one part of the cache, EVERY cache entry is cleared.

But, do not despair! The Zend Framework contains a solution to this problem. There is a special cache backend called Twolevels. The Twolevels backend uses a fast cache backend (i.e. APC or memcached) for the cache data, and a slow backend (i.e. files or database) for the lifetime and the cache tag information. This way we can have the best of both worlds!

According to the excellent performance whitepaper (login required) Magento has released, it is recommended to use APC for the fast backend and files for the slow backend for single webserver setups. If you use a cluster of webservers, you should use memcached for the fast backend and the database for the slow backend. The latter has more overhead then the APC/files combo, but having all servers share one cache pool makes up for that.

Magento makes it easy to configure all this by the way – have a look at the file app/etc/local.xml.additional for further information. I will not go deeper into the setup here because we have already written about this.

Now, back to the problem at hand – why is a nice, full, cache slower then an empty one?
The site in question was using APC as the fast backend and files as the slow backend.

So, lets have a look at what is happening.
Every time a product is added to the cart, the following method is called:

Mage::app()->getCache()->clean(
    Zend_Cache::CLEANING_MODE_MATCHING_ANY_TAG,
    array($cacheTag)
);

$cacheTag is an MD5 hash built from several parameters identifying the active customers mini-cart block cache.
So, how do the twolevel and the file cache backends handle this?

In the method Zend_Cache_Backend_TwoLevels::clean() each request with the cleaning mode CLEANING_MODE_MATCHING_ANY_TAG fetches all cache IDs matching the given tags from the slow backend using the method getIdsMatchingAnyTags(), and then removes one cache entry after the other in a loop.

case Zend_Cache::CLEANING_MODE_MATCHING_ANY_TAG:
    $ids = $this->_slowBackend->getIdsMatchingAnyTags($tags);
    $res = true;
    foreach ($ids as $id) {
        $bool = $this->remove($id);
        $res = $res && $bool;
    }
    return $res;
    break;

Lets dive in a little bit deeper and find out how the Zend_Cache_Backend_File backend finds those cache IDs.
The interesting part happens in the method _get(). Here we can see a list of all cache entries is built, and then it loops over each one, reads in the corresponding meta data file (using file_get_contents() and unserialize()) and then checks if the cache entry is associated with a matching cache tag.

This following code is slightly simplified for educational purposes:

$result = array();
$glob = @glob($cacheDir . $prefix . '--*');
if ($glob !== false) {
    foreach ($glob as $file) {
        $fileName = basename($file);
        $id = $this->_fileNameToId($fileName);
        $metadatas = $this->_getMetadatas($id);
        …
       switch ($mode) {
           …
           case 'matchingAny':
               $matching = false;
               foreach ($tags as $tag) {
                   if (in_array($tag, $metadatas['tags'])) {
                       $result[] = $id;
                       break;
                   }
               }
               break;
           …
       }
    }
}

This code is probably fine for a couple of hundred cache entries, but after not even a day my clients Magento instance reached 40k records. Opening and unserializing thousands of files takes some time, even on a strong machine.

It turns out the file backend doesn’t scale well.

The remedy to this is obviously some kind of index, mapping the tags to the matching cache IDs.
Instead of writing that information into a file that would have to be parsed and updated, I decided to use the filesystem itself as the index utilizing directories and symlinks.

In the modified file cache backend developed for the client, every time a cache entry is written, a directory with the name of each tag is created and a symlink to the metadata file is placed into it. This gives a little more overhead during the write operation. There is no difference reading cache entries. But every operation matching some tags is a lot faster. And since Magento makes heavy use of cache tags, the effect is quite noticeable, depending on the number of records in the cache. For example, adding a product to the cart now takes less then a second on the original instance. And I’m happy to say the reports of the friends who have been nice enough to test the extension have been positive for smaller sites also.

Benchmarks!

Inspired by Marc Jakubowski’s comment below, I added a little benchmark script. Here are some results to give a more detailed idea.
UPDATE: Thanks to Collin Mollenhour’s comment below, I also added benchmarks for Redis using his Zend Cache Backend Class – it’s incredibly fast, so if you have the possibility to use Redis 2.4 or newer, go for it! For this test I used the default Redis configuration, with the server running on the same machine I was running the tests. Before using it in production I would like to write some unit tests for this new backend, but it seems to work okay.

Records	Tags	Avg. Records / Tag	Cache Backend	Avg. Time for getIdsMatchingTags()
50000	250	~700	File	20.71s
50000	250	~700	Symlink	2.28s
50000	250	~1500	Redis	0.01s
6000	120	~175	File	2.41s
6000	120	~175	Symlink	0.23s
6000	120	~370	Redis	0.002s
2000	80	~88	File	0.78s
2000	80	~88	Symlink	0.08s
2000	80	~180	Redis	0.001s

The numbers for the records and tags where chosen because they roughly correspond the average cache pool size and tags on several live Magento instances of different sizes. These benchmarks where run on my laptop, and obviously the results may be different depending on the drive, file system, system memory etc. Please go ahead and test on your system.
One interesting thing about the Redis backend is that the average number of ID’s per tag is much higher then with the other backends. I’m not sure why, my guess is that it has something to do with the way Redis manages the tag hash tables. I don’t have time to check it out at the moment, but maybe Collin already knows why.

By the way, according to the PHP reference, the symlink function is no longer limited to Unix systems, but since PHP 5.3 it is also available under Windows (Vista, Server 2008 or greater). I haven’t tested this, though.

This module is provided with no warranty, you use it at your own risk. I know it is being used successfully on several sites, both as a primary cache backend and as a slow backend in combination with APC or memcached.
I invite you to have a look at it and try it out, but please start with a test instance and not your live store. You can download the module from Magento Connect or from github.
If you find bugs or have improvements, please send them in.

After installing the extension clear the config and block_html cache and visit System > Tools > Symlink Cache.

There you can see sample XML that you will have to add to your app/code/local.xml file for both variants, to use it on its own or to use it as a slow backend.
Then, after you have updated the local.xml file, clear the config cache, go to the Symlink Cache page and hit the “Initialize Tag Symlinks” button.
And that is all, your system is set up and uses the tag symlinks. Enjoy!
I would be happy to hear about other methods, ideas and experiences about improving cache performance.

Downloads

Magento Connect

Github

Google Optimizer on Magento: Where to start for maximum gain

Mark Hammersley — Mon, 01 Aug 2011 02:23:05 +0000

Magento has Google Optimizer tools built in and so it makes sense to use them. Google Optimizer allows you to present different content options to your prospective customers and then tracks which version converts more. On top of this Google Optimizer has built in probability formulae that understand when a result is a ‘confident result’ rather than a random occurrence.

To get a confident result you need to either have a test that is really obviously better or a decent number of transactions. But as a rule of thumb if you are getting more than 10 transactions a day then you can benefit from using Google Optimizer.

Where to start?

If you have a lower number of transactions it makes sense to start optimizing on the pages that most people see. This tends to be the home and checkout pages of the site. However we need not guess the best place to start when we have good data available to tell us exactly.

We can find the best place to start by looking at Google Analytics. Google Analytics should be setup using Ecommerce mode and to be tracking conversions, which is a standard part of Magento as long as you have entered the Google ID in the Google API area of Magento’s configuration settings.

In Google Analytics go to ‘content’

Then top content

Then set the time line for Google Analytics to show a decent length of time. I am using 6 months in my example – just use as much data as you have since the site has been stable and not changed.

On the top content screen find the right most column called $ index – the $ index is the average value for a page that a user visited before completing an Ecommerce transaction. Ordering by the $ index will give you the most valuable pages on your site. However you also need to click on ‘weighted sort’ to give you not only the most valuable pages but the most relevant valuable pages. Without weighted sort you are only going to see the pages that randomly got high values because an odd buyer used them to make a big purchase. By using weighted sort we can filter out these anomalies.

On the site I am looking at for this example this gives me the following pages

As you can see these are all checkout pages which are NOT part of the inbuilt Google Optimizer set of tools that Magento supplies. Whilst I have personally run split tests here, its tricky and not something I can easily show you. However you can optimise these pages by creating a ‘goal’ funnel and looking at the profile, but I want to cover that in another blog post.

So what I am going to do is to scroll through the list until I find one of the following pages that is built into Magento to Google Optimizer test

Product page
CMS page – (this could be a Google Adwords landing page and in many of my sites these are the best pages to test as they drive a significant proportion of my revenue)
Category page
Home page

In my example site the first page I find is not the home page as I would have expected but instead a product page. It just goes to show how important it is to look at the stats before deciding where to test.

The product I can use to test is worth $102 and thus a decent sale for the site and must have a fair number of transactions to rank this highly. So this is where I would start.

I am not going to go through how to actually setup the experiment as there are plenty of good blog tutorials available – just Google “Google Optimizer for Magento” – but I wanted to show you where to test first as this will actually allow you to make the most important changes to your site first.

Creating Custom Layout Handles

Paryank Kansara — Mon, 11 Jul 2011 09:33:10 +0000

As discussed in previous articles about Magento’s Layout XML, Layout Handles in Magento’s layout XML are XML nodes which contain the definition of updates in page layouts. There are some built in Layout Handles which are called implicitly in Magento. For example, default handle is called for every page, PRODUCT_TYPE_configurable is called for the configurable product detail page, customer_logged_in is called if a customer is logged in, etc.

But what if we want to add a custom set of layout updates for our own condition? For example, if we wanted our product pages to be different depending on its attribute set. Magento already provides layout handles for each product type. It also provides a layout handle PRODUCT_[product_id] where [product_id] is replaced by the product’s ID in the database. Using this layout handle, we can easily define a layout update for a specific product. But in our case, we want to define a layout handle for all products with a particular attribute set. In this case, it is not practical to define PRODUCT_[product_id] handles for each product in that attribute set, because new products added in that attribute set will not have the same design update and we would have to keep adding additional handles.

So ideally, we need a way to define a layout handle for attribute sets. Something like the following:

Fortunately, Magento’s layout engine is flexible enough to provide a way to define our own layout handles and call them explicitly through custom extensions. In the example of the case we discussed above, we will see how to create our own layout handles.

As described in our previous tutorials on Layout XML, after the layout XML is loaded, Magento applies the default handle, store handle, theme handle and then action handle. At the very end, layout updates from the database are applied.

For the product page, two additional layout handles: PRODUCT_TYPE_[type_id] and PRODUCT_[product_id] are applied after the action handle and before the layout updates from the database. In our case, we need to create and apply one more additional handle so that we can target our attribute set, namely: PRODUCT_ATTRIBUTE_SET_[attribute_set].

To accomplish this, we will use the event observer approach. This will keep our customization clean and not interfere with other extension.

Magento fires an event controller_action_layout_load_before before applying layout updates from the database. We can add a method observing this event in our extension which will add our attribute specific layout handle.

So, we have to follow the steps described below:

Create an extension which observes the event: controller_action_layout_load_before and calls a method to add our custom layout handle.
In the observer method, we will check if it is a product page and if not stop the execution or go to step 3.
We’ll fetch the current product’s attribute set name.
For the attribute set name, Magento allows characters like space, comma, period, etc. which are not valid as XML tag names. Since the layout handle is also an XML tag, we need to convert it to a XML tag compatible name. In short we need to remove all invalid characters from the attribute set name and replace them with underscores (‘_’).
Finally, we add the new layout handle PRODUCT_ATTRIBUTE_SET_[attribute_set_nicename] where [attribute_set_nicename] is the attribute set name which is converted to a XML tag compatible format.

We will give our extension the name: Magebase_AttributeSetHandle. First, we will create app/etc/modules/Magebase_AttributeSetHandle.xml

And, app/code/local/Magebase/AttributeSetHandle/etc/config.xml



    
        
            0.1.0
        
    
    
        
            
                
                    
                        Magebase_AttributeSetHandle_Model_Observer
                        addAttributeSetHandle

Here, in config.xml we declare an observer method for the controller_action_layout_load_before event as Magebase_AttributeSetHandle_Model_Observer::addAttributeSetHandle().

Now, we will create a class: Magebase_AttributeSetHandle_Model_Observer and a method: addAttributeSetHandle() in app/code/local/Magebse/AttributeSetHandle/Model/Observer.php.

 after
     * PRODUCT_TYPE_ handle
     *
     * Event: controller_action_layout_load_before
     *
     * @param Varien_Event_Observer $observer
     */
    public function addAttributeSetHandle(Varien_Event_Observer $observer)
    {
        $product = Mage::registry('current_product');

        /**
         * Return if it is not product page
         */
        if (!($product instanceof Mage_Catalog_Model_Product)) {
            return;
        }

        $attributeSet = Mage::getModel('eav/entity_attribute_set')->load($product->getAttributeSetId());
        /**
         * Convert attribute set name to alphanumeric + underscore string
         */
        $niceName = str_replace('-', '_', $product->formatUrlKey($attributeSet->getAttributeSetName()));

        /* @var $update Mage_Core_Model_Layout_Update */
        $update = $observer->getEvent()->getLayout()->getUpdate();
        $update->addHandle('PRODUCT_ATTRIBUTE_SET_' . $niceName);
    }
}

Here, to convert the attribute set name to a XML tag compatible name, we have called:

$niceName = str_replace('-', '_', $product->formatUrlKey($attributeSet->getAttributeSetName()));

This is because, formatUrlKey() in the product class, replaces all non-alphanumeric characters to ‘-’. But ‘-’ is not valid in XML tag name, so we are replacing it with ‘_’.

After that we add our handle for the attribute set. However, there is one shortfall to our observer approach.

On the product page, after the action handle is applied, the product type and product id handles are applied immediately before the controller_action_layout_load_before event is fired. This means that our attribute set handle is applied after the product id handle, which is not ideal.

The reason is that if we use both the product id handle and product attribute set handle in our custom layout modifications, then the attribute set handle will override the product id handle updates. This is not a practical because the product id handle should always be applied after the attribute set handle since it is specific to a product. Our handle hierarchy should be:

PRODUCT_TYPE_[type] => PRODUCT_ATTRIBUTE_SET_[attribute_set_nicename] => PRODUCT_ID_[id]

Unfortunately, there is no event fired between the handles applied for product type and product id so, we have to rearrange the layout handles in our observer method. So our method would be as below:

 after
     * PRODUCT_TYPE_ handle
     *
     * Event: controller_action_layout_load_before
     *
     * @param Varien_Event_Observer $observer
     */
    public function addAttributeSetHandle(Varien_Event_Observer $observer)
    {
        $product = Mage::registry('current_product');

        /**
         * Return if it is not product page
         */
        if (!($product instanceof Mage_Catalog_Model_Product)) {
            return;
        }

        $attributeSet = Mage::getModel('eav/entity_attribute_set')->load($product->getAttributeSetId());
        /**
         * Convert attribute set name to alphanumeric + underscore string
         */
        $niceName = str_replace('-', '_', $product->formatUrlKey($attributeSet->getAttributeSetName()));

        /* @var $update Mage_Core_Model_Layout_Update */
        $update = $observer->getEvent()->getLayout()->getUpdate();
        $handles = $update->getHandles(); // Store all handles in a variable
        $update->resetHandles(); // Remove all handles

        /**
         * Rearrange layout handles to ensure PRODUCT_
         * handle is added last
         */
        foreach ($handles as $handle) {
            $update->addHandle($handle);
            if ($handle == 'PRODUCT_TYPE_' . $product->getTypeId()) {
                $update->addHandle('PRODUCT_ATTRIBUTE_SET_' . $niceName);
            }
        }
    }
}

Here, we have stored all added layout handles in an array variable, then reset the updates. So now layout update instance has no layout handle. Then we iterate over all the handles we have stored and add them one by one again except when we find the product type handle, we add our attribute set handle immediately after that. This way, the attribute set handle is added exactly where we want it.

Conclusion

In this tutorial, we saw how we can add custom layout handles if we need to by observing the controller_action_layout_load_before event. In our example, we added a handle that allows us to create specific layouts for product pages that show products with a specific attribute set. Similarly, we could implement a custom layout handle based on some other attribute value or condition.

Let us know if you discover some more interesting scenarios with your own custom layout handles.

Customizing the Magento Error Report and Maintenance Page

Robert Popovic — Mon, 04 Jul 2011 06:50:17 +0000

In this tutorial, we will expand on the material Kristof already covered a while ago since there are some neat additional options available to us.

If you’ve worked with Magento for any length of time, you will most certainly be familiar with the dreaded “There has been an error processing your request” page. Clearly, the goal is to make sure that this page never appears to our online customers on a live site, but, on occasion it may still show up. For example if you’ve just sent out a newsletter and have an onslaught of visits, if your server runs out of MySQL connections, your visitors will still see this page.

Similarly, Magento provides an easy way to show a maintenance page. All you have to do is create an empty file called maintenance.flag in your Magento document root and your site will be redirected to the built in maintenance page.

This is all well but as part of a professional solution for your clients, we would like to be able to customize these pages so that they are more in line with the design of the site. Luckily, it is very easy to customize these templates. The principle is very similar to customizing a standard Magento skin folders, so, let’s dig into it.

Note that the Magento version used for this tutorial is 1.5.

1. Structure of the Error Pages

The error report and maintenance pages are rendered from template located under [MAGENTO_ROOT]/errors. As you can see from the screenshot, the folder contains some php files and a folder called default that reminds us of the way the normal Magento skin folders are structured. You will notice that the skin folder also contains files with the same name as the error root folder. The difference between them is that the files in the error root are just there to route the specific page processing. They include the processor.php file, instantiate the report class and call the appropriate method which in turn will render the actual page template. For example, the 503.php file has these three lines:

require_once 'processor.php';

$processor = new Error_Processor();
$processor->process503();

The actual page HTML will be in the phtml files under the default skin folder.

So let’s examine the various files of interest here.

In the error folder:

local.xml.sample

The good guys from the Magento dev team have provided us with a sample configuration file that we can use to create our specific configuration to customize our error/maintenance pages. We will look into this file in a moment and create our local.xml file once we decide what we want to achieve.

processor.php

This file is the “engine” that contains all the rendering logic. It implements the Error_Processing class that reads the error template configuration from the local.xml file, loads the configured design and runs the configured design.

404.php, 503.php, report.php

These are the “routing” pages that just invoke the appropriate methods in the Error_Processor class.

The default design folder:

page.phtml

This is the master template file that contains the HTML for all the pages that are handled by the error sub-system. This page will include one of the phtml files listed below. Since this page contains the header and footer you’d clearly want to modify it to implement your own branded design.

404.phtml

This is a 404 Not Found page template. I haven’t seen that one appear on a Magento site since there is already a 404 CMS page built into Magento. However, this page may be useful if you want to change the default 404 handling and direct all 404s to this template. For our purposes, we will ignore this template.

503.phtml

This is the “Temporarily Unavailable” page that also dubs as the maintenance page shown when the site is in maintenance mode. For example, when you are performing upgrades from Magento Connect or manually put the maintenance.flag file up.

We’ll definitely want to customize this page.

report.phtml

This page contains the HTML and PHP code that renders the error report page shown above. It’s certainly another candidate for our customization.

images and css folders

These folders contain the skin CSS and images used by the error/maintenance templates.

2. The local.xml File

Before we dive into customizing the phtml, we should realize that, like with the standard Magento design templates, a similar paradigm is also in effect here. In other words, we don’t want to “hack” the files in the default design, but create our own error design and customize the files there. For this, we will need to create a local.xml file with the appropriate configuration. Opening the supplied sample XML file, we see:



    default
    
        
        print
        
        Store Debug Information
        
        
        
        leave

The comments in the file are pretty clear but we’ll quickly explain the various elements.

– this is the element describing which skin folder the error processor should use. So, to create our own skin, we will change “default” to our own custom skin folder, for example:

magebase

– is an element that governs what will happen when an error is reported. The values are:

- blank: This is the default value and means that the error report will not be shown on the page but saved in the report file under var/report/

- print: If you want to show the full exception report on the error page, this is the value to use.

- email: You may want the error report page to display an error report form that your customers can fill out when they encounter an error on your site (perhaps to explain the steps they took before the error). This setting will do just that. Note that error report emails will be sent regardless whether the customer fills out the form or not.

The following two elements allow you to set a default email recipient and subject and are relevant only if you set the action to “email” and are self-explanatory. Note that Magento will append the error report number to the subject line automatically.

is the final element and allows you to specify what you want to happen with the error report files dumped in var/report/. Again, the comments are self-explanatory.

So, we will settle for the following local.xml content:



    magebase
    
        email
        XYZ Store Debug Information
        someone@example.com
        leave

In other words, we’ll create a “magebase” skin, we want our customers to be able to submit error reports to us and also leave the report files on the server. If the customer sends a report, our email will have the subject line: “XYZ Store Debug Information [error-number]” and it will be sent to the specified email address (do change that on your own site).

3. Creating a Custom Skin

That’s easy, just create a new sub-folder under errors/ and copy the files and folders from the errors/default/ skin there. Done!

Of course, if you this won’t show any changes in the design but, the error page would now look like this:

Now, the task is to customize our design.

4. Customizing the Skin

We mentioned above that the main HTML for these pages comes from page.phtml containing the following code:




<?php echo $this->pageTitle?>










    
        
            
                
                    
                
            
            
                
                    
                
            
            
                
                    Magento is a trademark of Magento Inc. Copyright © 2010 Magento Inc.

So, clearly, the first thing we’d want to do is replace the logo image, link title attribute and image alt attribute, as well as the footer text. Then we can move onto the included phtml templates. And work on our CSS. We can also add or replace the images in the images folder if we need some fancy background or other imagery.

We won’t go into details about how to structure your HTML/CSS, we will leave that up to you since it’s standard web development work.

So, after our Magebase error page makeover, our new pages look like this:

Our custom site maintenance page. Note we added contact info so customers can ring.

Our custom error report page allowing customers to send us additional information

Conclusion

We saw how we can easily customize the default Magento maintenance and error pages by configuring the local.xml file, creating a custom skin folder and adjusting the HTML and CSS supplied in the default skin. You can play around with the settings in local.xml to get the configuration you want and add more meaningful content to the pages themselves.

If you want to change the actual default processing that happens in processor.php, then you’d have to extend the Error_Processor class in your own file and include it in the other *.php files. Bear in mind that those changes may be overwritten during an upgrade. Your custom skin, however, would not be affected.

Finally, there doesn’t seem to be an easy way to create language/locale specific error pages but you can create your custom skin templates in your store’s main language.

Quick Tip: Explain Your Module Configuration Options With Tooltips

Robert Popovic — Thu, 23 Jun 2011 11:45:11 +0000

If you are developing end user extensions you would have used the system.xml file to define your extension’s configuration options. You also probably aware that you can add captions that explain the purpose and effect of your options by using the element.

But did you know that you could take this a step further?

Magento provides a built in options tooltip you can use to explain some of your options in more detail. If used, these tooltips appear at the top right of the list of your options section when you hover over an option label or field.

A simple tooltip appears at the top right of your options

To achieve this, let’s start with an example system.xml:



    
        
            Magebase
            700
        
    
    
        
            magebase
            Demo Options
            text
            10
            1
            1
            1
            
                
                    Demo Defaults
                    text
                    10
                    1
                    1
                    1
                    
                        
                            Option 1
                            select
                            adminhtml/system_config_source_yesno
                            10
                            1
                            1
                            0
                            Option 1 comment

This will just give us the simple option caption since we only used the element. To add the tooltip, we will use the element:

...
                        
                            Option 1
                            select
                            adminhtml/system_config_source_yesno
                            10
                            1
                            1
                            0
                            Option 1 comment
                            Option 1 tooltip
                        
...

This will give us the result in the above screenshot.

However, if we want to spruce things up a bit, we can add some HTML to both the caption and the tooltip. For example, to achieve the following:

A more complex HTML formatted caption and tooltip

We need to enclose our element content with <[CDATA[ ... ]> so the new option would look like:

                        
                            Option 2
                            text
                            20
                            1
                            1
                            0
                            Bold text
Emphasis
Hyperlinks]]>
                            Also using CDATA
 to create richly formatted tooltips like an image:


Some paragraph text.
]]>

Keep in mind that Magento’s admin stylesheet specifies the tooltip container with at 180px (class: .system-tooltip-box in boxes.css) but the overflow is not hidden. Also, there is no point in putting any hyperlinks in the tooltip since it disappears when you move your mouse away from the option.

Note that this feature is tested and will work from magento 1.4 onwards.

Conclusion

It’s really easy to add some more verbose explanations to your Magento extension configuration options by using the element in your options definitions. We encourage this especially for more obscure and less intuitive options as well as to have less clutter in the options list since we can avoid lengthy options comments.