Our Objective

If you need to make adjustments to the adminhtml theme files (template, layout, or skin), you have two options for accomplishing this. Here’s an example of what we would want to accomplish: Files in /app/design/adminhtml/default/custom_admin_theme/ need to override files in: /app/design/adminhtml/default/default/ Likewise, files in /skin/adminhtml/default/custom_admin_theme/ need to override files in: /skin/adminhtml/default/default/ The following two options accomplish this functionality:

Option 1 – “Admin Theme” module

Here is a screenshot of this module in action:

Option 2 – Add XML to your module’s config file

If you don’t want to install a module just to enable this functionality, you can add the following XML code inside the tag inside the config.xml file of any of your active modules. Alternatively, you can add this XML to your /app/etc/local.xml file. I prefer this option, due to its simplicity and the fact that the store administrator will have no need to update the adminhtml theme from the admin panel.

<config>
...
    <stores>
        <admin>
            <!-- custom admin theme -->
            <design>
                <theme>
                    <default>custom_admin_theme</default>
                </theme>
            </design>
        </admin>
    </stores>	
...
</config>

The code above overrides the XML from the /app/code/core/Mage/Adminhtml/etc/config.xml lines 410-422

<stores>
        <admin>
            <!-- default admin design package and theme -->
            <design>
                <package>
                    <name>default</name>
                </package>
                <theme>
                    <default>default</default>
                </theme>
            </design>
        </admin>
    </stores>

Anyone that has developed a theme in Magento knows how helpful template/block hints are. They help quickly identify which files are being loaded for a specific page.

Magento’s admin panel uses the exact same design pattern as the front end (layouts + blocks + templates). If you’ve ever done any modifications to the Magento admin panel, you’ve probably tried to turn on template/block hints for the admin panel. The only problem is, Magento doesn’t have built-in support for this. I did some digging around and found out how to enable this feature in the admin panel.

Step 1 – Connect to database

Using your favorite database administration tool, connect to your Magento database. These are tools I’ve used and recommend: Navicat ($129), MySQL Query Browser (Free), Sequel Pro (Mac Only – Free), or phpMyAdmin (free).

Step 2 – Enter values into ‘core_config_data’ table

Run the following query on the Magento database:

INSERT INTO core_config_data (scope, scope_id, path, value)
VALUES ('default', 0, 'dev/debug/template_hints', 1),
('default', 0, 'dev/debug/template_hints_blocks', 1);

Step 3 – Test in admin panel

Once you make this addition to the core_config_data database, template/block hints should show up in the admin panel.

Disabling Hints

When you’ve finished development want to turn off template hints in the admin panel, open the core_config_data table and change the ‘value’ column of the two row you inserted to “0”.

Why does this work?

For those of you who are like me and want to know the “why” as well as the “how”, I’m going to go over why this works. Here is the Magento code that checks to see if template/blocks hints are enabled:

File: /app/code/core/Mage/Core/Block/Template.php (Magento 1.3.2)

public function getShowTemplateHints()
{
    if (is_null(self::$_showTemplateHints)) {
        self::$_showTemplateHints = Mage::getStoreConfig('dev/debug/template_hints')
            && Mage::helper('core')->isDevAllowed();
        self::$_showTemplateHintsBlocks = Mage::getStoreConfig('dev/debug/template_hints_blocks')
            && Mage::helper('core')->isDevAllowed();
    }
    return self::$_showTemplateHints;
}

The “Mage::getStoreConfig” method checks for config values that are set in the current scope (ie, default, website, store, store view). In the admin panel, only values set in the “Default Scope” are loaded.

Magento only allows you to turn on hints when you’re in the configuration scope of a Website or Store View. This means that when the code above tries to load the configuration, it returns “null” because that config value isn’t set in the “Default Config” scope. Running the MySQL query above adds the hint config values to the “Default Config” scope.

Conclusion

I hope this helps you in your development of Magento modules that integrate with the admin panel. I considered writing a module to enable the hints to be turned on in the “Default Scope”, but decided against it, due to the simplicity of the method outlined in this post.