XML for Admin Configurations

Last modified by MattStephens on Tue, June 26, 2012 06:44
Source|Old Revisions  

This is an old revision of the document!


This document describes how to define fields for your module’s use in the Configuration section. The following examples assume an extension called Company_Module.

Creating a new section

The configuration sections are listed down the left-hand side of the Configuration page. To add a new section create a file Company/Module/etc/system.xml.

<?xml version="1.0"?>
<config>
  <sections>
    <EXAMPLE translate="label">
      <label>An Example Section</label>
      <tab>general</tab>
      <frontend_type>text</frontend_type>
      <sort_order>1000</sort_order>
      <show_in_default>1</show_in_default>
      <show_in_website>1</show_in_website>
      <show_in_store>1</show_in_store>
    </EXAMPLE>
  </sections>
</config>

Some tag names are used throughout system.xml, these can be used in section, group and field definitions:

  • EXAMPLE is given a unique name so it will not overwrite any other section. In reality an all-lowercase name is preferred.
  • label is the visible name of the section.
  • tab is the name of any existing heading in the list of sections.
  • frontend_type is always text here but get used to using it lots.
  • sort_order places this new section in the tab. If omitted the new section is merely appended instead.
  • show_in_default, show_in_website & show_in_store show or hide (1 or 0) this section for different scopes as chosen by the ‘Current Configuration Scope’ drop-down in the top left corner of the page. Omitting one of these is the same as setting it to 0.
  • comment you can add your own comment to a field or group.

Group specific tag names used in system.xml:

  • expanded whether the group is expanded by default when viewing that particular tab section.

If you try to view this new section now it will give an ‘Access Denied’ error. This is because it is a new page and pages in admin need permissions. Next create the file Company/Module/etc/adminhtml.xml.

<?xml version="1.0"?>
<config>
  <acl>
    <resources>
      <all>
        <title>Allow Everything</title>
      </all>
      <admin>
        <children>
          <system>
            <children>
              <config>
                <children>
                  <example translate="title">
                    <title>An Example Section</title>
                    <sort_order>100</sort_order>
                  </example>
                </children>
              </config>
            </children>
          </system>
        </children>
      </admin>
    </resources>
  </acl>
</config>

Note the admin, system and config are already defined by core modules so there is no need to define a title for these.

Adding to an existing section

If you want your module’s configuration to appear in an existing section then use it’s name and do not redefine it’s label, sort_order or any other tag. The existing section already has permissions granted to it.

<?xml version="1.0"?>
<config>
  <sections>
    <general>
      <!-- Your additions go here -->
    </general>
  </sections>
</config>

Creating a new group

Groups are the expandable fieldsets within a section page, they are always the children of a section. Edit your Company/Module/etc/system.xml file:

<?xml version="1.0"?>
<config>
  <sections>
    <EXAMPLE translate="label">
      <label>An Example Section</label>
      <tab>General</tab>
      <frontend_type>text</frontend_type>
      <sort_order>1000</sort_order>
      <show_in_default>1</show_in_default>
      <show_in_website>1</show_in_website>
      <show_in_store>1</show_in_store>
      <groups>
        <!-- New groups go here -->
        <SAMPLE translate="label">
          <label>A Sample Group</label>
          <frontend_type>text</frontend_type>
          <sort_order>100</sort_order>
          <show_in_default>1</show_in_default>
          <show_in_website>1</show_in_website>
          <show_in_store>1</show_in_store>
        </SAMPLE>
      </groups>
    </EXAMPLE>
  </sections>
</config>

Creating a new field

Fields are children of groups the same way that groups are the children of sections.

<?xml version="1.0"?>
<config>
  <sections>
    <EXAMPLE translate="">
      <label>An Example Section</label>
      <tab>General</tab>
      <frontend_type>text</frontend_type>
      <sort_order>1000</sort_order>
      <show_in_default>1</show_in_default>
      <show_in_website>1</show_in_website>
      <show_in_store>1</show_in_store>
      <groups>
        <SAMPLE translate="label">
          <label>A Sample Group</label>
          <frontend_type>text</frontend_type>
          <sort_order>100</sort_order>
          <show_in_default>1</show_in_default>
          <show_in_website>1</show_in_website>
          <show_in_store>1</show_in_store>
          <fields>
            <!-- New fields go here -->
            <ENABLED translate="label comment">
              <label>Enabled</label>
              <comment>
                <![CDATA[This text appears just beneath the field with a small arrow. 
                <span class="notice">It can contain HTML formatting too!</span>]]>
              </comment>
              <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>1</show_in_store>
            </ENABLED>
          </fields>
        </SAMPLE>
      </groups>
    </EXAMPLE>
  </sections>
</config>

comment is useful for providing extra descriptions or information. Wrap it’s text in a CDATA tag if you want to use HTML, any HTML is allowed but the most common use is to create highlight spans with a “notice” or “warning” class.

''frontend_type'' types

The frontend_type can be any class in the /lib/Varien/Data/Form/Element/ directory. Here are just some:

  • Button
  • Checkboxes
  • Checkbox
  • Date
  • File
  • Hidden
  • Imagefile
  • Image
  • Label
  • Link
  • Multiline
  • Multiselect
  • Note
  • Obscure
  • Password
  • Radio
  • Radios
  • Reset
  • Select
  • Submit
  • Textarea
  • Text
  • Time

''frontend_model'' types

Instead of a frontend_type you may also specify a block name in the typical module/path_to_file format. This block will have _getElementHtml() method called, use this to return the HTML for the field’s control. Even though it is called frontend_model it really is a block.

''source_model''

For all list types of field the possible options are supplied by a model class you specify. Mage/Adminhtml/Model/System/Config/Source directory contains lots of useful sources already defined like “Yes/No” or “Enable/Disable” or lists of countries, currencies or languages.

You can also create your own source model and specify it in the typical module/path_to_file format. Return a nested array like this:

<?php
class Company_Module_Model_Source
{
  public function toOptionArray()
  {
    return array(
      array('value' => 0, 'label' => Mage::helper()->__('First item')),
      array('value' => 1, 'label' => Mage::helper()->__('Second item')),
      array('value' => 2, 'label' => Mage::helper()->__('third item')),
     // and so on...
    );
  }
}

The saved value from such a field will contain the selected values as a string like ‘1,2,3’.

''backend_model''

A field’s config data is normally stored in a core/config_data model but you can also define your own. It’s _afterLoad() method is called before the field is shown, and the _beforeSave() & _afterSave() methods are called when a user clicks the ‘Save Config’ button. Use these events to perform extra checks on the data, possibly throwing an exception in _beforeSave() or updating local files in _afterSave().

''validate''

The validate tag has it’s contents added as a class to the eventual input element. Here are the standard tests that come with Magento’s form validation.

  • validate-admin-password
  • validate-ajax
  • validate-alpha
  • validate-alphanum
  • validate-cc-cvn
  • validate-cc-exp
  • validate-cc-number
  • validate-cc-type
  • validate-cc-type-select
  • validate-clean-url
  • validate-code
  • validate-cpassword
  • validate-css-length
  • validate-currency-dollar
  • validate-data
  • validate-date
  • validate-date-au
  • validate-digits
  • validate-email
  • validate-fax
  • validate-greater-than-zero
  • validate-identifier
  • validate-length
  • validate-new-password
  • validate-not-negative-number
  • validate-number
  • validate-one-required
  • validate-one-required-by-name
  • validate-password
  • validate-percents
  • validate-phone
  • validate-select
  • validate-ssn
  • validate-state
  • validate-street
  • validate-url
  • validate-xml-identifier
  • validate-zero-or-greater
  • validate-zip
  • validate-zip-international

Defining default values

This is very simply done in Company/Module/etc/config.xml:

<?xml version="1.0"?>
<config>
  <default>
    <EXAMPLE>
      <SAMPLE>
        <ENABLED>1</ENABLED>
      </SAMPLE>
    </EXAMPLE>
  </default>
</config>

Here the ENABLED field has been using a adminhtml/system_config_source_yesno source model which defines ‘0’ as ‘No’ and ‘1’ as ‘Yes’. Setting the default to ‘1’ means the ‘Enabled’ field will be ‘Yes’ until a user changes it.

Accessing your configuration

The quickest way to access the saved value of a field is like this:

Mage::getStoreConfig('EXAMPLE/SAMPLE/ENABLED');

The path is always in the section/group/field format. getStoreConfig() takes into account the default value and website or store scope.




 

Magento 2 GitHub Repository

Magento Job Board - Some sort of tag line goes here

Latest Posts| View all Jobs