Last time we talked about Magento’s System Configuration system. If you missed it, you’ll want to go back and catch up. So, we glossed over a lot of the tags you could use within an individual field.

<fields>
    <!-- ... --->
    <fieldname translate="label">
        <label>Field Name</label>
        <frontend_type>text</frontend_type>
        <sort_order>2</sort_order>
        <show_in_default>1</show_in_default>
        <show_in_website>1</show_in_website>
        <show_in_store>0</show_in_store>
    </fieldname>
    <!-- ... --->
</fields>

Consider the rest of this article a thorough de-glossing.

<label/> and <comment/>

These tags allow you to set end-user facing text for your System Configuration field.

A label appears to the left of your form field, while a comment will appear directly under the field.

<show_in_default/>, <show_in_website/>, <show_in_store/>

These are boolean fields with a value of 1 or 0. They indicate if the field will show up when viewing the System Configuration in the default view, the website view, or the store view.

The implicit assumption is that they also control what options are configurable at each level. However, there’s nothing on the backend enforcing this assumption. That is, a field may be configured to with the following

<show_in_store> 0 </show_in_store>

but it will still be possible (although not advisable) to set and retrieve this field’s value at the store level via programatic means.

<sort_order/>

The <sort_order/> is a numerical value that’s used to determine the order of the fields within their group container. The higher the number, the lower the field will sort on the screen.

<frontend_type/>

<frontend_type/> determines the type of field that will be used to collect the configuration value. Values supported in Magento 1.4 Community Edition are

1. allowspecific
2. export
3. image
4. import
5. label
6. multiselect
7. obscure
8. password
9. select
10. text
11. textarea
12. time

The value of this field is used in a Factory style pattern to instantiate a class with a format of

Varien_Data_Form_Element_Type

where “Type” is the value of the <frontend_type/>’s text node. This happens in the addField method of the Varien_Data_Form_Element_Abstract class, as seen below

class Varien_Data_Form_Abstract extends Varien_Object
{
    //...
    public function addField($elementId, $type, $config, $after=false)
    {
        if (isset($this->_types[$type])) {
            $className = $this->_types[$type];
        }
        else {
            $className = 'Varien_Data_Form_Element_'.ucfirst(strtolower($type));
        }

        $element = new $className($config);
        $element->setId($elementId);
        if ($element->getRequired()) {
            $element->addClass('required-entry');
        }
        $this->addElement($element, $after);
        return $element;
    }
}

<frontend_class/>

Don’t be fooled, <frontend_class/> is not a Grouped Class Name. The <frontend_class/> tag can be used to modify the class attribute of the form element tag that’s generated for your field. That is, this config field allows you to add a Cascading Stylesheet Class (i.e. “frontend” class) to the generated form element.

For example, a field configured with the following

<frontend_type>select</frontend_type>
<frontend_class>free-method</frontend_class>

will render as

<select class="free-method">

<validate/>

At first glance, <validate/> is a confusing configuration option. It appears to just add a CSS class to the generated tag. A configuration like this

<validate>validate-email</validate>

will yield a form element like this

<input type="text" class="validate-email" />

As with much of Magento, there’s more going on here. The presence of this CSS class will trigger the system’s client-side validation routines. For example, the above code would cause a javascript email validation to be run against the field. If the field fails the validation test, the end-user won’t be able to submit the configuration form.

You can take a look at the available validation routines in

js/prototype/validation.js

and here’s the above mentioned email validation routine from the same file

['validate-email', 'Please enter a valid email address. For example johndoe@domain.com.', function (v) {
            return Validation.get('IsEmpty').test(v) || /^[a-z0-9,!#$%&'*+/=?^_`{|}~-]+(.[a-z0-9,!#$%&'*+/=?^_`{|}~-]+)*@[a-z0-9-]+(.[a-z0-9-]+)*.([a-z]{2,})/i.test(v)
        }],

which looks to be a monstrous, but useful, regular expression.

<can_be_empty/>

The <can_be_empty/> tag is used with multiselect fields. The short version is, if you wish to a allow “no selection” to be a valid configuration, use this field.

What happens behind the scenes is if can_be_empty is true, the system renders a hidden field on the System Configuration page

File: lib/Varien/Data/Form/Element/Multiselect.php

if ($this->getCanBeEmpty()) {
    $html .= '<input type="hidden" name="' . parent::getName() . '" value="" />';
}

which ensure the form processing code will accept an empty selection.

<depends/>

<depends/> allows you specify that your configuration field should only be displayed when another confgiruation field in the same group has a specific value.

For example, the Paypal Express System Configuration has the following select defined.

<specificcountry translate="label">
    <label>Countries Payment Applicable From</label>
    <frontend_type>multiselect</frontend_type>
    <sort_order>110</sort_order>
    <source_model>adminhtml/system_config_source_country</source_model>
    <show_in_default>1</show_in_default>
    <show_in_website>1</show_in_website>
    <show_in_store>0</show_in_store>
    <depends><allowspecific>1</allowspecific></depends>
</specificcountry>

You’ll notice the

<depends><allowspecific>1</allowspecific></depends>

This is telling the system that if the <allowspecific> field (defined with the following)

<allowspecific translate="label">
   <label>Payment Applicable From</label>
   <frontend_type>select</frontend_type>
   <sort_order>100</sort_order>    <source_model>adminhtml/system_config_source_payment_allspecificcountries</source_model>
   <show_in_default>1</show_in_default>
   <show_in_website>1</show_in_website>
   <show_in_store>0</show_in_store>
</allowspecific>

has a value of “1”, then the <specificcountry> field should be displayed. This happens instantly via some behind the scenes Javascript.

While it appears to work with any fields that send out on onchange event, the core Magento system only uses this function where the parent field is a select. If you’re paranoid about forward compatibility, I’d apply the same restriction to your own System Configuration fields, as it’s hard to tell where the core Magento team may take this feature in the future.

<source_model/>

The <source_model/> tag specifies a Model class (in URI/Grouped Class Name format) to populate a field’s default options. As of Magento Community Edition 1.4x, it works with selects and multi-selects. In addition to the standard Magento Grouped Class Name, an extended syntax of

module/modelname::methodName

is supported. The system will instantiate a Model with getModel('module/modelname') and call its methodName method to retrieve an array of value/label paris to use for the source. If the method name is left off, the toOptionArray method will be called by default.

<frontend_model/>

By default, Magento Form Elements are rendered with the Block class

Mage_Adminhtml_Block_System_Config_Form_Field

However, if you want to use a custom renderer for your System Configuration field, you can specify a different block class (in URI/Grouped Class Name form) with the <frontend_model/> tag.

For example, the last_update field in the adminnotification group

<last_update translate="label">
    <label>Last update</label>
    <frontend_type>label</frontend_type>
    <frontend_model>adminhtml/system_config_form_field_notification</frontend_model>
    <sort_order>3</sort_order>
    <show_in_default>1</show_in_default>
    <show_in_website>0</show_in_website>
    <show_in_store>0</show_in_store>
</last_update> 

specifies that a field renderer of adminhtml/system_config_form_field_notification should be used. This translates into the following class

File: app/code/core/Mage/Adminhtml/Block/System/Config/Form/Field/Notification.php
class Mage_Adminhtml_Block_System_Config_Form_Field_Notification extends Mage_Adminhtml_Block_System_Config_Form_Field
{
    protected function _getElementHtml(Varien_Data_Form_Element_Abstract $element)
    {
        $element->setValue(Mage::app()->loadCache('admin_notifications_lastcheck'));
        $format = Mage::app()->getLocale()->getDateTimeFormat(Mage_Core_Model_Locale::FORMAT_TYPE_MEDIUM);
        return Mage::app()->getLocale()->date(intval($element->getValue()))->toString($format);
    }
}

The core team is overriding the _getElementHtml method to ensure that any entered date will be displayed with the same format.

<backend_model/>

Once a form is submitted to Magento, its values must be saved. For System Configuration fields, this is normally handeled with the Model class

Mage_Core_Model_Config_Data

However, there may be times where you want your System Configuration to use a different backend model. The <backend_model/> tag allows you to specify a different Model class (using URI/Grouped Class Name format).

Most often this isn’t because you want to save where the data is stored, but rather because you want to perform some additional action when a field is saved. By extending the Mage_Core_Model_Config_Data class with your own model and defining a _beforeSave and/or _afterSave method on your model, you can take additional action anytime a config value is changed.

For example, consider the import field in the tablerate group

<import translate="label">
    <label>Import</label>
    <frontend_type>import</frontend_type>
    <backend_model>adminhtml/system_config_backend_shipping_tablerate</backend_model>
    <sort_order>6</sort_order>
    <show_in_default>0</show_in_default>
    <show_in_website>1</show_in_website>
    <show_in_store>0</show_in_store>
</import>

The Grouped Class Name adminhtml/system_config_backend_shipping_tablerate translates to the following class

class Mage_Adminhtml_Model_System_Config_Backend_Shipping_Tablerate extends Mage_Core_Model_Config_Data
{
    public function _afterSave()
    {
        Mage::getResourceModel('shipping/carrier_tablerate')->uploadAndImport($this);
    }
}

Here the core team is hooking into the _afterSave method (which is called after a model is saved) to update the shipping/carrier_tablerate Model with information from the just uploaded file.

<upload_dir/> and <base_url/>

Both these tags are used with System Configuration fields that use the <frontend_type>image</frontend_type> field with a <backend_model>adminhtml/system_config_backend_image</backend_model> backend model. These determine both

1. Where the image file is uploaded
2. The base URI path used when rendering an <img> tag

First, let’s cover the <upload_dir/> tag

<upload_dir config="system/filesystem/media" scope_info="1">sales/store/logo</upload_dir>

There’s three things being set by the above.

1. The base image upload path
2. The path, from the base, where this specific image field should be uploaded
3. Whether or not the current config scope should be appended to the path

The base image upload path is set with the config attribute (system/filesystem/media above). This specifies a System Configuration path. That is, the base image upload path isn’t system/filesystem/media, but it’s the value of the Magento System Configuration at system/filesystem/media (which resolves to {{root_dir}}/media in a default Community Edition install)

Once the base image upload path is found, we need to append the sub-directory this specific image should be uploaded to. To get this we append the value of the <upload_dir/>'s text node

sales/store/logo

to the value of the base image upload path, which will give us something like this

/path/to/magento/install/media/sales/store/logo

Finally, if the scope attribute is set to “1”, the current Configuration Scope will be transformed into a path. If you were uploading an image with the scope set to default, you’d get a path like

/path/to/magento/install/media/sales/store/logo/default

However, if you were uploading an image with the scope set to a specific store, you’d end up with a path like

/path/to/magento/install/media/sales/store/logo/stores/5

where “5” is the ID of the store scope you’re currently at.

When we upload an image, only the scope and image name portion of the path get saved to the config. This means we need to tell the System what the base URL should be for our image.

<base_url type="media" scope_info="1">sales/store/logo</base_url>

The scope_info and text node function the same as <upload_dir/>’s. Where <base_url/> differs is in setting the base of the image URI (which is going to, naturally, be different than the local base file system path).

As you’ve likely intuited, the base path is set using the type attribute. The configured value will be passed into the getBaseUrl method on the global Mage object to set the base URL for the image. The the above example, that would look something like

Mage::getBaseUrl('media')

You can see the actual code that does this in the Mage_Adminhtml_Block_System_Config_Form_Field_Image class.

class Mage_Adminhtml_Block_System_Config_Form_Field_Image extends Varien_Data_Form_Element_Image
{
    //...

    protected function _getUrl()
    {
        $url = parent::_getUrl();

        $config = $this->getFieldConfig();
        /* @var $config Varien_Simplexml_Element */
        if (!empty($config->base_url)) {
            $el = $config->descend('base_url');
            $urlType = empty($el['type']) ? 'link' : (string)$el['type'];
            $url = Mage::getBaseUrl($urlType) . (string)$config->base_url . '/' . $url;
        }

        return $url;
    }

    //...
}

Finally, it’s important to note that this base URL is not used consistently throughout Magento to create a final URL for a configured image. From what I’ve seen this is only used to create an image preview within the System Configuration admin itself.

Wrapup

As you can see, the Magento System Configuration admin is a powerful system that’s almost an application development environment unto itself. By leveraging the functionality built into the system you can quickly and reliably build out new custom functionality for your, or your client’s stores.