System.xml

The basic structure of system.xml is as follows:

<config>
    <tabs>
      <catalog translate="label" module="catalog">
        <label>Catalog</label>
        <sort_order>100</sort_order>
      </catalog>    
    </tabs>
    <sections>
        <catalog translate="label" module="catalog">		      			 <tab>catalog</tab>
            <sort_order>40</sort_order>
            <class>separator-top</class> <!— any css class —>

            <show_in_website>1</show_in_website>
            <show_in_default>1</show_in_default>
            <show_in_store>1</show_in_store>
            <groups>
		   <general translate="label">
              <label>General</label>
              <show_in_default>1</show_in_default>
              <show_in_website>1</show_in_website>
              <show_in_store>1</show_in_store>

		     <fields>
                   <!— field declarations —>
			   <list_mode translate="label">
                   	<label>List Mode</label>
                   	<frontend_type>select</frontend_type>
			   	<source_model>adminhtml/system_config_source_catalog_listMode</source_model>
                   	<sort_order>1</sort_order>
                   	<show_in_default>1</show_in_default>
                   	<show_in_website>1</show_in_website>
                   	<show_in_store>1</show_in_store>
				<comment>Comment displayed underneath field</comment>
				<backend_model>adminhtml_for_example_only</backend_model>
			   </list_mode>
                </fields>
            </groups>
        </catalog>
    </sections>
</config>
  • Tabs refer to the tabs on the right of the system/configuration page. Tabs are on the same level as sections, but they refer to one another.

  • When a section loads, it gathers all children and orders them by their sort order. So, other modules can add parts to any other module including core, by following the same xpath.

  • Sections, groups and fields can have show_in_default, show_in_store, and show_in_website nodes. If they’re not specified, they default to false. If there are no displayable sections / groups / fields for a tab, then the tab will not show (common gotcha).

  • E.g. Path hints is set to false to show in default (otherwise the admin would look broken).

  • If a tab has no sections defined, then it will not be displayed.

  • Frontend_type is the type of input which will be displayed on the form, not the type which will in any way be displayed on the frontend of the site. Values can be text, textarea, image, select, multiselect (TODO: look at others)

  • source_model is a data provider to give the form element values. E.g. for a select, a class path can be provided of a class which contains a getOptionArray() method, which returns a set of values to be selected. This also works with multiselects.

  • backend_model is a model which is used to do something after the save, such as clear cache or save additional data somewhere else. Should extends Mage_Core_Model_Config_Data, this is because for every form field, if there’s no backend model specified, Magento will instantiate an instance of Mage_Core_Model_Config_Data – this is the model that knows how to save configuration values. This model just extends Mage_Core_Model_Abstract. To add validation, an exception can be thrown from the _beforeSave, or save() method, and a warning or notice can be set on the session object in the _afterSave() method:

public function _afterSave(){
	$helper = Mage::helper('llapgoch_addpcattributes');
	
	if(strpos($this->getValue(), ",") !== false){
		 Mage::getSingleton('core/session')->addNotice($helper->__('Please use spaces to separate your attribute names instead of commas'));
	}
	
	parent::_afterSave();
	
}

Tabs are the left hand titles. Sections refer to the list items which display below them. Groups are the individual panels which display on a section’s page.

Depends

Fields can depend on one another. If a field depends on another field whose value returns false, then the depending field will not show.

<fields>
    <depender translate="label">
        <label>Depender</label>
        <frontend_type>select</frontend_type>
        <show_in_website>1</show_in_website>
        <show_in_default>1</show_in_default>
        <show_in_store>1</show_in_store>
        <sort_order>2</sort_order>
        <source_model>adminhtml/system_config_source_yesno</source_model>
        <depends>
            <twinkie>1</twinkie>
        </depends>
    </depender>
</fields>

In the above example, depender will only show if field twinkie’s value equals 1. Any value can be depended on. The form is updated via javascript in real time to show and hide depended form fields.

Tooltip & Comment

Fields can have tooltip nodes which display the text in a little question mark after the field. A comment node will place a block of text below the field with an upward arrow.