Magento: Custom configuration fields

Dream. Dare. Do – that is Suyati’s work principle in a nutshell.

Aug
30
2013
  • Author:
  • Arun Balakrishnan
  • Category:

Magento, simply is an open-source ecommerce web application. It is a feature-rich eCommerce platform built on open-source technology.

During the development we have a lot of things those are needed for configuration by an admin user. In Magento we can easily create sections under “System -> Configuration” via system.xml. Here in this article we are going to see how to create configuration fields.

Almost all of the Magento modules have own configurations setup in system.xml file. The configuration scheme separated into four parts Tabs, Sections, Groups, Fields. Tabs contains sections, sections contains groups , groups contains fields. All of them defined in system.xml file that is placed in etc folder of a Magento module.

Let’s create our custom module, go to app/code in your magento installation and cretae folder local if not exists. Inside local create a folder with your namsppace( it should be a unique name for ex: Companyname) inside this folder create module folder say MyModule

Now let’s write our system.xml file

[Module_Folder]/etc/system.xml



    
        
            
            100
        
    
    
        
            
            200
            1
            1
            1
            mycustom_tab
            
                
                    
                    Some comment about my group
                    10
                    1
                    1
                    1
                    
                        
                            
                            Some comment about my field
                            Field ToolTip
                            1
                            1
                            1
                            text
                        
                    
                
            
        
    

We can discuss each node in this xml one by one

1. The <tabs> node

The node name is used as the unique identifier (mycustom_tab in our 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 allowed and are separated by space or comma).

This node may contain these 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. The <sections> node

Here the node name is used as the unique identifier (mycustom_section in our case) of a section, 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 allowed and are separated by space or comma).

This node may contain these 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 – identifies 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 – indicates that this section will be showed when “Default Values” is selected in “Current Configuration Scope”
  • use_in_website – indicates that this section will be showed when a website is selected in “Current Configuration Scope”
  • use_in_store – indicates 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
  • groups – contains definitions of groups those are described below

3.The <groups> node

Here the node name is used as the unique identifier (mycustom_group in our case) of a custom section, 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). module may be omitted, then value from the configuration section will be used.

This node may contain these children:

  • label – it is label of 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 – indicates that this group will be showed when “Default Values” is selected in “Current Configuration Scope”
  • use_in_website – indicates that this group will be showed when a website is selected in “Current Configuration Scope”
  • use_in_store – indicates that this group will be showed when a store view is selected in “Current Configuration Scope”
  • frontend_model – 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, may contain some notice about configuration group or whatever you want
  • expanded – displays this group as expanded, until admin user collapse it manually. By default all the groups are collapsed
  • sort_fields – 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 – 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.
  • fields – contains definitions of groups.

4.The <fields> node

Where the node name is used as the unique identifier (mycustom_field in this case) of a custom section, module attribute used to specify what module will be used for translations and translateattribute is used for specifying which nodes to translate (multiple values are separated by space or comma). module may be omitted, then value from the configuration group will be used.

This node may contain such children:

  • label – it is label of the configuration field
  • sort_order – identifies the field position inside of the configuration group if custom sort mechanism is not set
  • config_path – identifies 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 mycustom_section/mycustom_group/mycustom_field node.
  • frontend_model – block class that is used as the field render, by default used adminhtml/system_config_form_field
  • frontend_type– 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 – indicates that multiselect field can contain no values selected, otherwise empty selection will not be saved
  • source_model – specifies 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
  • backend_model – specifies custom model for saving of configration value data. If you want to implement such custom logic, you should extend your backend model from Mage_Core_Model_Config_Data
  • use_in_default – indicates that this field will be showed when “Default Values” is selected in “Current Configuration Scope”
  • use_in_website – indicates that this field will be showed when a website is selected in “Current Configuration Scope”
  • use_in_store – indicates that this field will be showed when a store view is selected in “Current Configuration Scope”
  • tooltip – 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 – 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.
  • 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.
  • depends – this node contains list of dependencies of the current field to other fields.

Note: Your custom configuration section should be included into acl resources list (admin/system/config) to make it available for view by an admin used. For example, let’s create the xml file for adminhtml configuration.

[Module_Folder]/etc/adminhtml.xml



    
        
            
                
                    
                        
                            
                                
                                    
                                        My Custom Section
                                        100
                                    
                                
                            
                        
                    
                 
            
        
    


We are Done! If you replace “[module_name]” in file contents with your module helper namespace definition, then you will have a view similar in “System -> Configuration -> My Custom Section” to this screencast:

custom

Leave a Comment

Your email address will not be published. Required fields are marked *