What's the Deal with the "Hint" Tag in system.xml?

Question

I've found opaque reference to a <hint/> tag in system.xml files. What's the deal with this tag? Is its use documented anywhere?

Answer 1

I'm not sure about EE, but in CE this is a vestigial tag from a never completed help system. The intent appears to have been to give each form field in the System configuration section a small "hint", or help text.

The help text is added when the field element is created

#File: app/code/core/Mage/Adminhtml/Block/System/Config/Form.php
$hint  = (string)$element->hint ? Mage::helper($helperName)->__((string)$element->hint) : '';

//...

$field = $fieldset->addField($id, $fieldType, array(
    'name'                  => $name,
    'label'                 => $label,
    'comment'               => $comment,
    'tooltip'               => $tooltip,
    'hint'                  => $hint,
    'value'                 => $data,
    'inherit'               => $inherit,
    'class'                 => $element->frontend_class . $sharedClass . $requiresClass,
    'field_config'          => $element,
    'scope'                 => $this->getScope(),
    'scope_id'              => $this->getScopeId(),
    'scope_label'           => $this->getScopeLabel($element),
    'can_use_default_value' => $this->canUseDefaultValue((int)$element->show_in_default),
    'can_use_website_value' => $this->canUseWebsiteValue((int)$element->show_in_website),
));

That first line reads the value of a <hint/> in system.xml.

Next, when Magento renders the field as HTML, the last thing it does is add the hint in a nested div.

#File: app/code/core/Mage/Adminhtml/Block/System/Config/Form/Field.php
$html.= '<td class="">';
if ($element->getHint()) {
    $html.= '<div class="hint" >';
    $html.= '<div style="display: none;">' . $element->getHint() . '</div>';
    $html.= '</div>';
}
$html.= '</td>';

Finally, there's a small bit of javascript that's called on an admin page load.

#File: app/design/adminhtml/default/default/template/system/config/js.phtml
function showHint() {    
    $$('.hint').each(function(element){
        Event.observe(element, 'mouseover', function(){            
            element.down().show()
        });
        Event.observe(element, 'mouseout', function(){
            element.down().hide()
        });
    });
}

This javascript sets up event handlers such that mousing in or out of the help text will make it appear. The intent being this "hint" would help users understand what each field does.

The problem? The HTML/CSS on the backend makes the hint td a single pixel wide. This prevents anyone mousing over the hint to view it. Try adding a hint to your field configuration and then running the following from your browser's javascript console

$$('.hint').each(function(el){
    el.down().show();
});

You'll see something like this.

(the This is a hint text).

I've always chalked this up as one of those "Best Laid Plans" thing that got dropped once Magento launched.