Quick Tip: Explain Your Module Configuration Options With Tooltips

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 <comment></comment> 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:

<?xml version="1.0" encoding="UTF-8"?>
<config>
    <tabs>
        <magebase>
            <label>Magebase</label>
            <sort_order>700</sort_order>
        </magebase>
    </tabs>
    <sections>
        <mbcustom>
            <tab>magebase</tab>
            <label>Demo Options</label>
            <frontend_type>text</frontend_type>
            <sort_order>10</sort_order>
            <show_in_default>1</show_in_default>
            <show_in_website>1</show_in_website>
            <show_in_store>1</show_in_store>
            <groups>
                <default>
                    <label>Demo Defaults</label>
                    <frontend_type>text</frontend_type>
                    <sort_order>10</sort_order>
                    <show_in_default>1</show_in_default>
                    <show_in_website>1</show_in_website>
                    <show_in_store>1</show_in_store>
                    <fields>
                        <mbcustomopt1>
                            <label>Option 1</label>
                            <frontend_type>select</frontend_type>
                            <source_model>adminhtml/system_config_source_yesno</source_model>
                            <sort_order>10</sort_order>
                            <show_in_default>1</show_in_default>
                            <show_in_website>1</show_in_website>
                            <show_in_store>0</show_in_store>
                            <comment>Option 1 comment</comment>
                        </mbcustomopt1>
                    </fields>
                </default>
            </groups>
        </mbcustom>
    </sections>
</config>

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

...
                        <mbcustomopt1>
                            <label>Option 1</label>
                            <frontend_type>select</frontend_type>
                            <source_model>adminhtml/system_config_source_yesno</source_model>
                            <sort_order>10</sort_order>
                            <show_in_default>1</show_in_default>
                            <show_in_website>1</show_in_website>
                            <show_in_store>0</show_in_store>
                            <comment>Option 1 comment</comment>
                            <tooltip>Option 1 tooltip</tooltip>
                        </mbcustomopt1>
...

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:

                        <mbcustomopt2>
                            <label>Option 2</label>
                            <frontend_type>text</frontend_type>
                            <sort_order>20</sort_order>
                            <show_in_default>1</show_in_default>
                            <show_in_website>1</show_in_website>
                            <show_in_store>0</show_in_store>
                            <comment><![CDATA[Using CDATA to give us more formatting options:<br/><strong>Bold text</strong><br/><em>Emphasis</em><br/><a href="http://google.com">Hyperlinks</a>]]></comment>
                            <tooltip><![CDATA[<div style="border-radius:6px;background-color:#fcc;padding:10px;margin-left:10px;width:230px;">Also using CDATA
 to create richly formatted tooltips like an image:<br />
<img src="http://magento15.dev.lero9.com/skin/frontend/default/modern/images/logo.gif" alt="Logo" style="margin:15px 15px 15px 0;"/>
<p>Some paragraph text.</p></div>]]></tooltip>
                        </mbcustomopt2>

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 <tooltip> 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.

Originally published on magebase.com. Copyright © 2011 Magebase - All Rights Reserved.