Magento Understanding of System XML

The Main part of Magento is that it run through XML.As Magento had lot of XML file for there flexibilty.
ALL Magento modules have own configurations described in system.xml file.
Generally System XMl sperated into four parts
Tabs, Sections, Groups, Fields.

Tabs contains sections,
sections contains groups (i.e. fieldsets),
groups contains fields.

Every Module of Magento have these four parts which are in system.xml.
let's take an Example of Newcustom Module in which system.xml will look like this 


<?xml version="1.0" ?>

<config>
    <tabs>
        <newcustom_tab module="[module_name]" translate="label">
            <label>My Configuration Tab</label>
            <sort_order>100</sort_order>
        </newcustom_tab>
    </tabs>
    <sections>
        <newcustom_section module="[module_name]" translate="label">
            <label>New Custom Section</label>
            <sort_order>200</sort_order>
            <show_in_default>1</show_in_default>
            <show_in_website>1</show_in_website>
            <show_in_store>1</show_in_store>
            <tab>newcustom_tab</tab>
            <groups>
                <newcustom_group translate="label">
                    <label>New Custom Group</label>
                    <comment>Some comment about my group</comment>
                    <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>
                    <fields>
                        <newcustom_field translate="label tooltip comment">
                            <label>New Custom Field</label>
                            <comment>Some comment about field</comment>
                            <tooltip>Field ToolTip</tooltip>
                            <show_in_default>1</show_in_default>
                            <show_in_website>1</show_in_website>
                            <show_in_store>1</show_in_store>
                            <frontend_type>text</frontend_type>
                        </newcustom_field>
                    </fields>
                </newcustom_group>
            </groups>
        </newcustom_section>
    </sections>
</config>

So step by step look at the following parts

1) Tabs
<tabs>
    <newcustom_tab module="[module_name]" translate="label">
        <label>My Configuration Tab</label>
        <sort_order>100</sort_order>
    </newcustom_tab>
</tabs>

Where,
node name is used as the unique identifier (newcustom_tab in this case) of a tab
module attribute used to specify what module will be used for translations and
translate attribute is used for specifying which nodes to translate (multiple values are separated by space or comma).

This node may contain such children:
label – it is label text that is used for tab rendering
sort_order – identifies the tab position between the other tabs
class - it is CSS class name that is used for the tab

2) Sections 
<sections>
      <newcustom_section module="[module_name]" translate="label">
            <label>NewCustom Section</label>
            <class>custom class</class>
            <header_css>custom css</header_css>
            <tab>mycustom_tab</tab>
            <frontend_model>newcustom/adminhtml_system_config_fieldset_yourfile</frontend_model>
            <sort_order>200</sort_order>
            <show_in_default>1</show_in_default>
            <show_in_website>1</show_in_website>
            <show_in_store>1</show_in_store>
      <newcustom_section>
<sections>

Where,
node name is used as the unique identifier (newcustom_tab in this case) of a tab
module attribute used to specify what module will be used for translations and
translate attribute is used for specifying which nodes to translate (multiple values are separated by space or comma).

This node may contain such children:
label it is label of the section displayed on the left side under the tab and on the right side as the page heading
sort_order   tell us that the section position inside of the tab between the other sections
class   CSS class for section label in the tabs block (In PayPal module used for displaying of image instead of text)
header_css  CSS class used on section edit form (the page after clicking on the section label)
use_in_default   tell us that  this section will be showed when “Default Values” is selected in “Current Configuration Scope”
use_in_website  tell us that  this section will be showed when a website is selected in “Current Configuration Scope”
use_in_store    tell us that this section will be showed when a store view is selected in “Current Configuration Scope”
frontend_model  block class that is used as the section form render, by default used adminhtml/system_config_form

3) Group


<groups>
 <newcustom_group translate="label"> 
     <label>New Custom Group</label> 
     <comment>Some comment about my group</comment> 
     <sort_order>10</sort_order> 
     <frontend_type>select</frontend_type> 
     <frontend_model>adminhtml/system_config_form_fieldset</frontend_model> 
     <show_in_default>1</show_in_default> 
     <show_in_website>1</show_in_website> 
     <show_in_store>1</show_in_store> 
 </newcustom_group> 
</groups>

Where,
node name is used as the unique identifier (newcustom_tab in this case) of a tab
module attribute used to specify what module will be used for translations and
translate attribute is used for specifying which nodes to translate (multiple values are separated by space or comma).

label     tell us that the configuration group that is displayed as fieldset legend on the section edit page
sort_order  identifies the configuration group position inside of the section between the other groups
use_in_default    tell us that this group will be showed when “Default Values” is selected in “Current Configuration Scope”
use_in_website    tell us that this group will be showed when a website is selected in “Current Configuration Scope”
use_in_store   tell us that this group will be showed when a store view is selected in “Current Configuration Scope”
frontend_model   tell us that block class that is used as the configuration group fieldset render, by default used adminhtml/system_config_form_fieldset
comment text that will be displayed before all the items in form
expanded  displays this group as expanded, until admin user collapse it manually. By default all the groups are collapsed
sort_fields   tell us that this node is used to define sorting mechanism inside of configuration group if you don’t want to arrange items by sort_order. The structure of this node is simple and may contain the following children:
by – the child node name of the field node for which will be used as sort value
direction_desc – if it is set to 1, then the sorting will be in the reverse order
clone_fields and clone_model   tell us that these both nodes are used to create configuration fields duplicates with some specific prefixes. For example it is used to change placeholder images for different product image attributes. clone_fields is a boolean and can be 0 or 1, clone_model contains model class that should be used for retriving of prefixes. This model should contain getPrefixes() method that will return an array of associative arrays that contains label and field for specifying of field name prefix and field label prefixes. For example it should looks like the following:


4) Fields

<fields>
 <newcustom_field translate="label tooltip comment">
    <label>My Custom Field</label> 
    <comment>Some comment about my field</comment> 
    <tooltip>Field ToolTip</tooltip> 
    <frontend_model>adminhtml/system_config_form_field</frontend_model> 
    <source_model>module_name/system_config_source_yesno</source_model> 
    <backend_model>paypal/system_config_backend_dependsonyourmodule</backend_model>
    <tooltip>Simply enter your email address.</tooltip>
    <config_path>newcustom_section/newcustom_group/newcustom_field</config_path> 
    <show_in_default>1</show_in_default> 
    <show_in_website>1</show_in_website> 
    <show_in_store>1</show_in_store> 
    <frontend_type>text</frontend_type> 
 </newcustom_field> 
</fields>

label   tell us that the label of the configuration field
sort_order   tell us that the field position inside of the configuration group if custom sort mechanism is not set
config_path   tell us  to what configuration node the field value should be saved. If this field is not specified, configration field path will be used ([section_name]/[group_name]/[field_name]). In this example field value will be saved into newcustom_section/newcustom_group/newcustom_field node.
frontend_model  block class that is used as the field render, by default used adminhtml/system_config_form_field
frontend_type  tell us that the field input type for displaying of the form item. Possible values are:

  • text  Text input field
  • textarea   Textarea field
  • select   Dropdown field. Options for this field are retrieved from source_model
  • multiselect   Multiselect field. Options for this field are retrieved from source_model
  • import  File input field for importing of the data
  • export   File export button that is used for exporting of the data
  • allowspecific  Dropdown field that displays “Allow Specific Countries” and “All Countries” as its options
  • image File input field for uploading of an image

and all the fields presented as Varien_Data_Form_Element_* …
If value is not specified, text input type will be used
can_be_empty    tell us that multiselect field can contain no values selected, otherwise empty selection will not be saved
source_model   tell us source model that returns option list for select and multiselect fields types. Value contains model class name or model callback. If you specify only class name your module should implement toOptionArray($isMultiselect) method, that will return a list of prepared option array for form element. If you specify model callback, your source model should just return only associative array of value-label pairs.

Example of model callback: module_name/model_name::methodName
List of mostly used source models:

adminhtml/system_config_source_admin_page:  returns list of all the items in Magento Admin menu
adminhtml/system_config_source_cms_page : returns list of CMS Pages
adminhtml/system_config_source_customer_group : returns list of customer groups
adminhtml/system_config_source_date_short : returns list of available short date formats
adminhtml/system_config_source_email_identity : returns list of email sending identities (General Contact, Sales Representative, etc)
adminhtml/system_config_source_email_template : returns list of transactional email templates
adminhtml/system_config_source_locale_country : returns list of localized country names
adminhtml/system_config_source_locale_currency : returns list of localized currency names
adminhtml/system_config_source_locale_timezone : returns list of localized timezone names
adminhtml/system_config_source_locale_weekdays : returns list of localized weekday names
adminhtml/system_config_source_order_status : returns list of available order statuses except pending payment
adminhtml/system_config_source_payment_allmethods : returns list of all payment methods
adminhtml/system_config_source_shipping_allmethods : returns list of all shipping methods
adminhtml/system_config_source_country : returns list of all countries from directory module
adminhtml/system_config_source_allregion : returns list of all country regions grouped by country
adminhtml/system_config_source_enabledisable : return list of two options (“Enable” and “Disable”)
adminhtml/system_config_source_notoptreq : return list of three options for customer widget mandatory indetificator (“Not”, “Optional”, “Required”).
adminhtml/system_config_source_yesno : return boolean options (“Yes”, “No”)


use_in_website  tell us  that this field will be showed when a website is selected in “Current Configuration Scope”
use_in_store  tell us  that this field will be showed when a store view is selected in “Current Configuration Scope”
tooltip  tell us  tooltip text for field. This text is displayed when the mouse is over the field. If you want to specify custom html block for text in tooltip, you should use tooltip_block
tooltip_block tell us block class name that will be used as tooltip for this field instead of tooltip text
validate- CSS class name that will be applied to form field. Used for validation of the field input. Some usual values:

  • required-entry – validates field value as non empty
  • validate-number – validates field value as numeric
  • validate-email – validates field value as valid email address

All the possible validation rules can be found at js/prototype/validation.js
comment- text that will be displayed before all the items in form, may contain some notice about field value format group or whatever you want. Also this field can use a comment generator model. In these case you need specify the following children for it:
depends – this node contains list of dependencies of the current field to other fields. The structure of this node is very simple. The child node name is name of field on what this one depends, and the node value is value for make this field visible. For example such configuration:

<depends>
     <field_name>1</field_name>
</depends>

Hope this will help you!

3 comments:

  1. Thank you! This is exactly wat I was looking for!
    I have a question.
    Is possible to add custom html above or undes a field?
    I know that you can add a block "title" but is possibble to add a "content block" where you can add a code html ?
    Thank you

    ReplyDelete
  2. @andrea Just like you means to say description block as we have in product,category ?

    ReplyDelete

Thankyou for your Comments

LinkWithin

Blog has moved, searching new blog...