Magento Module Development Series – Part8- Module – system.xml

Part-8-MM
In this blog will learn about system.xml and how to use it
System.xml is a configuration file similar to config.xml. It’s placed inside etc folder of the modules.

System.xml file is used to create configuration fields in System->Configuration in magento admin.
This might be useful in number of cases in your module. For example:

  1. Your module is doing some kind of API integration like facebook api. So you would like to store facebook api key somewhere in system -> configuration.
  2. Your module has some settings which user needs to set. These settings can be done from System->Configuration.

Here is first and explanation of the System Configuration in magento. This page is divided logically in few parts namely, Tabs, Sections, Groups, Fields.
Please understand the this image See Screenshot carefully, as its critical for understanding system.xml

Fields

So let’s start from the basic here. First we will simply, create new fields inside Customer Configuration -> Create New Account Options.

<?xml version="1.0"?>
<config>    <!-- Primary Tag is required -->
	<sections> <!-- Sections Tag -->
		<customer translate="label" module="test"> <!-- Section Name In which we want to put in the fields -->
			<groups>  <!-- Groups Tag -->
				<create_account translate="label">  <!-- Group Name where we want to put the fields -->
					<fields>  <!-- Fields Tag -->
						<patient translate="label">  <!-- Field Name or Identifier -->
                            		         <label>Sign In Gate Email Template</label>  <!-- Label of field as seen in admin -->                   				  

<frontend_type>select</frontend_type> <!-- Input type of field i.e text or select box or something else? -->                                                                                                            

<source_model>adminhtml/system_config_source_email_template</source_model>  <!-- In case of select box, specific from where the drop down values come from. This is path of a model class -->                                                                                                               

<sort_order>3</sort_order>  <!-- Sort Order Or Position of the field in the group -->                                                                                                              

<show_in_default>1</show_in_default>  <!-- Should this field be shown default store scope -->                                                                                                             

<show_in_website>1</show_in_website> <!-- Should this field be show in website scope --> 				 	                             

<show_in_store>1</show_in_store> <!-- Should this field be show in store scope -->
                               </patient>
					</fields>
					<fields>  <!-- Another  Field -->
						<slider translate="label">
                            <label>Show Slider In Sign In Gate</label>
                            <frontend_type>text</frontend_type>   <!-- This time field type is text field -->
                            <sort_order>99</sort_order>
                            <show_in_default>1</show_in_default>
                            <show_in_website>1</show_in_website>
                            <show_in_store>1</show_in_store>
                           </slider>
					</fields>					
				</create_account>
	            </groups>
	        </customer>
    </sections>
</config>

We can see the result below for the same.

Magento Admin Section View

Magento Admin Section View

Now if you want to get the value entered by admin in these fields, in your module. Use this
Mage::getStoreConfig(‘section_key/group_key/field_key’,Mage::app()->getStore());
In our case
Mage::getStoreConfig(‘customer/create_account/email_domain’,Mage::app()->getStore());

These fields get automatically saved in magento. The magento controller for system configuration, save these fields in a key value pair based format in core_config_data table. If you see this table structure it has scope, path and value column.
Path column stores the path of our field and value column stores the value selected.

Important things to note here are.
1. The name of the section and group, was known. This is the most important thing to know, when creating a field. Question is how to know this. Here are 2 ways.
a. Need to look at existing system.xml files for the modules. Like in case of customer module look at Customer/etc/system.xml to see section name and group. Same for other modules.
b. Second method, is that we can use firebug or any inspect element tool to find out section and group name. See screenshot.

2. The Frontend type to use e.g text,select etc. for this, the only option is to see other magento system.xml and learn from them.

Group

In this part, we will see how to create a new Group. Below the system.xml for it

<?xml version="1.0"?>
<config>
	<sections>
		<customer translate="label" module="test">
			<groups>
				<test translate="label"> <!-- Name/Unique Key of our new group-->
					<label>Test Group</label>  <!-- Display Text -->
                      		<sort_order>10</sort_order> <!-- Store Order/Position -->
                    		<show_in_default>1</show_in_default>
                    		<show_in_website>0</show_in_website>
                    		<show_in_store>0</show_in_store>
					<fields>
						<patient translate="label">
                            <label>Sign In Gate Email Template</label>
                            <frontend_type>select</frontend_type>
                            <source_model>adminhtml/system_config_source_email_template</source_model>
                            <sort_order>3</sort_order>
                            <show_in_default>1</show_in_default>
                            <show_in_website>1</show_in_website>
                            <show_in_store>1</show_in_store>
                        </patient>
					</fields>
					<fields>
						<slider translate="label">
                            <label>Show Slider In Sign In Gate</label>
                            <frontend_type>select</frontend_type>
                            <source_model>adminhtml/system_config_source_yesno</source_model>
                            <sort_order>99</sort_order>
                            <show_in_default>1</show_in_default>
                            <show_in_website>1</show_in_website>
                            <show_in_store>1</show_in_store>
                       </slider>
					</fields>
					
				</test>
	            </groups>
	        </customer>
    </sections>
</config>

Here is the output for the above code.

Magento Admin Custom Fields

Magento Admin Custom Fields

Section

Now we will see how to create a new section. Below the system.xml for the same.

<?xml version="1.0"?>
<config>
	<sections>
		<testsection translate="label" module="test">
		<class>separator-top</class>
            <label>New Test Section</label>
            <tab>customer</tab>
            <sort_order>130</sort_order>
            <show_in_default>1</show_in_default>
            <show_in_website>1</show_in_website>
            <show_in_store>1</show_in_store>
			<groups>
				<test translate="label">
					<label>Test Group</label>
                    <sort_order>10</sort_order>
                    <show_in_default>1</show_in_default>
                    <show_in_website>0</show_in_website>
                    <show_in_store>0</show_in_store>
					<fields>
						<patient translate="label">
                            <label>Sign In Gate Email Template</label>
                            <frontend_type>select</frontend_type>
                            <source_model>adminhtml/system_config_source_email_template</source_model>
                            <sort_order>3</sort_order>
                            <show_in_default>1</show_in_default>
                            <show_in_website>1</show_in_website>
                            <show_in_store>1</show_in_store>
                        </patient>
					</fields>
					<fields>
						<slider translate="label">
                            <label>Show Slider In Sign In Gate</label>
                            <frontend_type>select</frontend_type>
                            <source_model>adminhtml/system_config_source_yesno</source_model>
                            <sort_order>99</sort_order>
                            <show_in_default>1</show_in_default>
                            <show_in_website>1</show_in_website>
                            <show_in_store>1</show_in_store>
                       </slider>
					</fields>
					
				</test>
	            </groups>
	        </testsection>
    </sections>
</config>

After doing the above, you will see a new section called “New Test Section” added inside the Customer tab. But if you click on the New Test Section you will get an error page like thisSee Screenshot

To fix this, we need to make some entries in magento config.xml file. The reason for this is related to ACL configuration (this is advanced stuff, can be explained later). Basically if you see the code at class Mage_Adminhtml_System_ConfigController line no 259 i.e protected function _isSectionAllowed($section); this function checks for permission for the new section created. If permission exists, it shows the new section. So if u want to do some debugging, here is where u do it.
To put the acl setting, in the config.xml of the module, inside the >adminhtml< section. Put the below.

<acl>
			<resources>
				<admin>  <!--This is acl based on URL. If you see URL it would be /admin/system_config/ -->
					<children>
						<system>
							<children>
	                               		 <config>
	                                  			  <children>
											<testsection translate="title" module="fav">  <!-- This is name of the section created by us -->
												<title>Test Section ACL</title>  <!-- Title as shown in User->Roles->Permissions Window -->
												<sort_order>99</sort_order>
											</testsection>
      									</children>
								</config>
							</children>
						</system>
					</children>
				</admin>
			</resources>
		</acl>

After this, you need to logout of admin and then login back again. Then you will see your Section.

Tabs

To create a new tab, here is the system.xml

<?xml version="1.0"?>
<config>
	<tabs>
        <newtab translate="label" module="customer">
            <label>New Tab</label>
            <sort_order>1</sort_order>
        </newtab>
    </tabs>
	<sections>
		<testsection translate="label" module="fav">
			<class>separator-top</class>
            <label>New Test Section</label>
            <tab>newtab</tab>
            <sort_order>130</sort_order>
            <show_in_default>1</show_in_default>
            <show_in_website>1</show_in_website>
            <show_in_store>1</show_in_store>
			<groups>
				<test translate="label">
					<label>Test Group</label>
                    <sort_order>10</sort_order>
                    <show_in_default>1</show_in_default>
                    <show_in_website>0</show_in_website>
                    <show_in_store>0</show_in_store>
					<fields>
						<patient translate="label">
                            <label>Sign In Gate Email Template</label>
                            <frontend_type>select</frontend_type>
                            <source_model>adminhtml/system_config_source_email_template</source_model>
                            <sort_order>3</sort_order>
                            <show_in_default>1</show_in_default>
                            <show_in_website>1</show_in_website>
                            <show_in_store>1</show_in_store>
                        </patient>
					</fields>
					<fields>
						<slider translate="label">
                            <label>Show Slider In Sign In Gate</label>
                            <frontend_type>select</frontend_type>
                            <source_model>adminhtml/system_config_source_yesno</source_model>
                            <sort_order>99</sort_order>
                            <show_in_default>1</show_in_default>
                            <show_in_website>1</show_in_website>
                            <show_in_store>1</show_in_store>
                       </slider>
					</fields>
					
				</test>
	            </groups>
	        </testsection>
    </sections>
</config>

Also, ACL setting like before in config.xml are also required for this. And in some cases, it may give a permission error. In that case you need to go System -> Permission ->Roles. Click the role of your user like ‘administrator’ to edit it and then save it again.

Default values for fields created

In system.xml , the fields that we create. We can assign them default values as well, when the module is loaded. For example, suppose, you have a Yes/No drop in configuration. And you want it to have a default value or you have a text field and you want it to have a default value.
The way to do that is in config.xml

<default>  <!-- This needs to be placed direct inside <config> tag -->
        <testsection>  <!-- Name of section -->
        	<test> <!-- Name of group -->
        		<patient>1</patient> <!-- Name of field -->
        		<slider>1</slider>
        	</test>
        </testsection>
    </default>

So this covers our, basics of system.xml . After doing this, you should be able to create a configuration file and use it in our module.

Exercise:
Create a configuration in admin, with 3 fields. 1 text field, 1 drop down and 1 multiple select. Display these values in your module controller.
  • Pingback: Magento Custom Shipping Method Deveolopment()

  • Fadzly Othman

    system.xml should be placed in /app/code/local///etc

  • http://twitter.com/ricomonkeon rico monkeon

    Nice tutorial, though there was one place where I got stuck that I thought I’d post here in case anyone has the same problem. When I set up a new section, I got a file not found error. This seems to be because no Data.php file exists. I added this under Excellence/Helper/Data.php as follows, and that fixes it…

    (OPEN PHP TAG)

    class Excellence_Test_Helper_Data extends Mage_Core_Helper_Abstract
    {

    }

    Also, I think the tabs example should be module=”test” rather than module=”fav” to work.

  • peermydeen sulaiman

    place the system.xml at “app/local/mage/customer/” and too copy the config.xml to same path and update the version number. and also need to set the code pool as local in Mage_all.xml at app/etc/Module

  • Amit

    Thanks for the great explanation on Tabs, Sections, Groups and Fields.

  • http://www.developer.web.tr/ Oğuz Çelikdemir

    There is a typo in line:
    Mage::getStoreConfig(‘customer/create_account/email_domain’,Mage::app->getStore());

    should be:
    Mage::getStoreConfig(‘customer/create_account/patient’,Mage::app->getStore());