Magento : Dynamic comment loading for admin system config field (Part 1/2)

May 12th, 2014 by in Backend, Development, Magento 0
Magento : Dynamic comment loading for admin system config field (Part 2/2)

There is a little known option available to Magento developers that can help you provide better UX in Magento system configuration admin area. We are talking about an actual built-in method for loading dynamic comment contents for a configuration field in your Magento module. Sounds cool? That’s because it is.

 

We’re going to start with a bit of history. According to the release notes, this feature has been around since Magento CE version 1.4.x-devel-64038 and Magento EE version 1.8.0.0-rc1. It hasn’t been marked as deprecated but it also haven’t been much used by Magento’s core. In fact community edition does not use it at all and enterprise edition is using it only once. This is why I said it’s little known feature.

 

Background

Let’s first get some perspective on how dynamic comment loading is made possible by Magento core. If you take a look at app\code\core\Mage\Adminhtml\Block\System\Config\Form.php you will notice a function called _prepareFieldComment that should be somewhere on line 509 (Magento CE 1.8.1.0):

 

    /**
     * Support models "getCommentText" method for field note generation
     *
     * @param Mage_Core_Model_Config_Element $element
     * @param string $helper
     * @return string
     */
    protected function _prepareFieldComment($element, $helper, $currentValue)
    {
        $comment = '';
        if ($element->comment) {
            $commentInfo = $element->comment->asArray();
            if (is_array($commentInfo)) {
                if (isset($commentInfo['model'])) {
                    $model = Mage::getModel($commentInfo['model']);
                    if (method_exists($model, 'getCommentText')) {
                        $comment = $model->getCommentText($element, $currentValue);
                    }
                }
            } else {
                $comment = Mage::helper($helper)->__($commentInfo);
            }
        }
        return $comment;
    }

It looks simple, but we should dig a bit into it in order to understand how it actually works.

 

As you can see $element is an object of Mage_Core_Model_Config_Element and represents the XML markup of your system config field element defined in etc/system.xml file of your module. So, by defining $commentInfo as on the line #12 in the code above, Magento is basically accessing the <comment> XML tag of your field. This means that you can define a model for your comment rendering and Magento will automatically call getCommentText method of your model.

 

Example

Let’s say that you have a configuration field defined in the etc/system.xml file of your module that looks something like this:

<testfield translate="label">
    <label>Test Field</label>
    <frontend_type>select</frontend_type>
    <source_model>adminhtml/system_config_source_yesno</source_model>
    <comment><model>modulename/adminhtml_system_config_source_testfield_comment</model></comment>
    <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>
</testfield>

It’s a classic Yes/No dropdown select, but with one exception – we have defined a model for rendering of our comment. Of course, you can enter any model name, but I like to name my classes by the location of where they are used (way more simple during debugging).

 

The next step is to define our model and getCommentText method:

/* File location: Namespace/Modulename/Model/Adminhtml/System/Config/Source/Testfield/Comment.php */
<?php
class Namespace_Modulename_Model_Adminhtml_System_Config_Source_Testfield_Comment extends Mage_Core_Model_Config_Data
{
    public function getCommentText(Mage_Core_Model_Config_Element $element, $currentValue)
    {
        $array = $element->asArray();
        $result = "";
            foreach ($array as $item)
            {
                $result .= $item . "<br />";
            }
        $result .= $currentValue;
        return $result;
    }
}

If you open the admin page where your field is located, you should see something like this:

Test field preview Yes

You’ll notice that we have rendered contents of XML nodes from our test field. The last displayed value in the preview image above is the current value of our test field pulled from Magento’s database. If we change the selection of our test field and save the configuration changes, we will get something like this when the page reloads:

 

Test field preview No

 

The current value of the field is pulled automatically in our model’s method from the $currentValue parameter. This means that you can display a custom comment for any of your system configuration fields in Magento admin depending on the actual saved value of your field. This can be pretty useful when you want to improve user experience of your module.

 

But we will not stop here. I will let you play with this for a while and in the next post I will show you how you can change the contents of your field’s comment the moment you pick a value from the dropdown. And we’ll do it in pure JavaScript without using AJAX or making additional calls to the server.

Written by Nikola Stojiljkovic

Nikola is a Certified Magento Backend Developer with a passion for high quality code that follows standards and best practices. He also leads our Magento development teams so you can expect excellent Magento articles from him.


See all articles from this author »

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>