Besides being a utility method container, the Helper classes play an indispensable role for extensions that provide Magento-style configuration options for users. For example, if you were building a payment extension, you would most certainly need a configuration area in order to set up the access data for it. Magento comes with its own built-in configuration area, located under System | Configuration. This entire section is built from the XML elements found under the extension etc/system.xml.

Here is where things get a little complicated. In order for the Magento admin user to have access to your extension configuration interface defined through system.xml, it needs permissions for that. These permissions are defined in another configuration file located in the same folder called adminhtml.xml.

Let us demonstrate this with a simple example. We will create a configuration options section for our extension within system.xml, define permissions to it via adminhtml.xml, and then use the data helper class to fetch that configuration value from within our controller.

First, we need to create the app/code/community/Foggyline/HappyHour/etc/system.xml configuration file with the following content:

<?xml version="1.0"?>
<config>
   <tabs>
      <foggyline module="foggyline_happyhour">">
         <label>Foggyline</label>
        <sort_order>10</sort_order>
      </foggyline>
   </tabs>
   <sections>
      <foggyline_happyhour module="foggyline_happyhour">
         <label>FoggylineHappyHour</label>
         <tab>foggyline</tab>
         <sort_order>10</sort_order>
         <show_in_default>1</show_in_default>
         <groups>
            <settings>
               <label>FoggylineHappyHour Settings</label>
               <sort_order>10</sort_order>
               <show_in_default>1</show_in_default>
               <fields>
                  <custom_message>
                     <label>Custom Message</label>
                     <frontend_type>text</frontend_type>
                     <sort_order>20</sort_order>
                     <show_in_default>1</show_in_default>
                  </custom_message>
               </fields>
            </settings>
         </groups>
      </foggyline_happyhour>
   </sections>
</config>

The first thing that we did was add a custom tab called Foggyline to the system configuration. Tabs are the navigation headers down the left-hand side of the Magento administration are a under System | Configuration. The default tabs are General, Catalog, Customers, Sales, Services, and Advanced. Adding a new tab is as simple as defining your own element under Configuration | Tabs. In our example, we have defined the foggyline element, where foggyline is a freely given element name. The attribute module="foggyline_happyhour" simply tells Magento what helper to use for this part of functionality while referencing helpers internally. The string foggyline_happyhour points to the helper group defined under config.xml. The label element specifies the label for this tab to be shown under the navigation sidebar. The sort_order element specifies the order in the sidebar with regards to other elements; a larger number pushes the item in the sidebar to the bottom after other elements.

Once we have defined the actual tab, we need to add one or more sections to it. In our example, we have defined one section through the foggyline_happyhour element.

The foggyline_happyhour element is an arbitrary name that's used to identify your new section.

The label element defines the display value used in the HTML interface for your new section.

The tab element identifies which tab your new section should be grouped under. We want our section to show up under our new Foggyline tab. The name foggyline comes from the tag used to create the Foggyline tab.

The sort_order element determines where this section shows up vertically compared to other sections in the tab.

The show_in_default element is a Boolean configuration option with a valid value of 1 or 0. They determine the level of configuration scope this section has.

The groups element determines the logical grouping of configuration options, sort of like the fieldset element in HTML forms.

The settings element within groups is an arbitrary name that's used to identify this group.

The elements label, sort_order, and show_in_default are analogous to those previously explained for this section.

The fields element is a container for one or more elements that will be visually manifested into HTML form elements later. Within the fields element, again we have label, sort_order, show_in_default, and this time one new element called frontend_type. The frontend_type element determines what HTML element will be used for rendering in the browser.

At this point if you try to log in to Magento and navigate to System | Configuration, you will be able to see the FoggylineHappyHour menu in the left sidebar. However, accessing the menu item would give you a 404 Error Page not found error.

This might be a good time to explain what ACL actually is. ACL, short for Access Control Lists, is a functionality that allows a store owner to create fine-grained roles for each and every user in their system. A default Magento installation comes with one role, Administrators. Magento ACL implementation allows you to add new roles to the system via System | Permissions | Roles. A role is essentially a collection of resources, while a resource is basically an action such as "delete user".

While adding new system configuration sections, you need to define resources for it so that Magento can use it via its ACL system. So the reason why we might be getting a 404 Error Page not found error is that we are missing the ACL definition.

This is why we need to create the app/code/community/Foggyline/HappyHour/etc/adminhtml.xml file with the following content:

<?xml version="1.0"?>
<config>
   <acl>
      <resources>
         <admin>
            <children>
               <system>
                  <children>
                     <config>
                        <children>
                           <foggyline_happyhour module="foggyline_happyhour">">
                              <title>FoggylineHappyHour</title>
                           </foggyline_happyhour>
                        </children>
                     </config>
                  </children>
               </system>
            </children>
         </admin>
      </resources>
   </acl>
</config>

Once done, you need to log out and then log back in to Magento administration in order for acl (access list) to kick in, otherwise you will still be getting a 404 Error Page not found error when you try to access System | Configuration | Foggyline | FoggylineHappyHour.

Now get back to the adminhtml.xml file. The syntax of the file seems somewhat recursive with all those children elements repeating. We could say that we need to define a resource whose path matches the system configuration option defined under system.xml. So if a base path for the acl resource within adminhtml.xml is config > acl > resources > admin > children > system > children > config > children, we simply need to define a new child within it called foggyline_happyhour like we did in the preceding example. The element name foggyline_happyhour must match the element name of the section from within system.xml.

The title element simply dictates what will show up in the Magento administration panel when the node tree is displayed.

If all went well, you should be able to see your configuration options interface as shown in the following screenshot:

Magento allows each configuration option defined through system.xml to have a default value. For example, let's say we want the default value of our custom_message to be Hello World string. To do so, we turn to our config.xml file as follows:

<?xml version="1.0"?>
<config>
   <!-- … other elements ... -->
   <default>
      <foggyline_happyhour>
         <settings>
            <custom_message><![CDATA[Hello World]]></custom_message>
         </settings>
      </foggyline_happyhour>
   </default>
   <!-- … other elements ... -->
</config>

It might look a bit confusing at first, but notice how the config.xml element paths within the default element path foggyline_happyhour> settings >foggyline_happyhour follow the system.xml element paths within the sections element path foggyline_happyhour> settings > foggyline_happyhour (minus the groups element). Now if you open the System | Configuration | Foggyline | FoggylineHappyHour, you should see, if you haven't previously saved some other value, the text Hello World under the Custom Message option value.

Finally, as shown in the following code snippet, we will use the helper Data class to add utility methods for extracting our configuration option value from the system.xml:

<?php

class Foggyline_HappyHour_Helper_Data extends Mage_Core_Helper_Data
{
   const XML_PATH_CUSTOM_MESSAGE = 'foggyline_happyhour/settings/custom_message';
   
   public function getCustomMessage($storestore = null)
   {
      return Mage::getStoreConfig(self::XML_PATH_CUSTOM_MESSAGE, $store);
   }
}

Looking at the preceding code, it is easy to conclude how the const XML_PATH_CUSTOM_MESSAGE string value follows the same XML elements path as previously mentioned for system.xml and config.xml. Passing that string to Mage::getStoreConfig() will retrieve our custom message.

To confirm everything is working, add the following action to your app/code/community/Foggyline/HappyHour/controllers/HelloController.php class file:

<?php

class Foggyline_HappyHour_HelloController extends Mage_Core_Controller_Front_Action
{   
   public function helperTestAction()
   {
      echo Mage::helper('foggyline_happyhour')->getCustomMessage();
   }
}

Now open the http://magento.loc/index.php/happyhour/hello/helperTest URL in the browser; if all is good, you should be able to see the Hello World message.

Even though we have covered a lot of ground so far, we have barely scratched the surface. The massiveness of the Magento platform hides far more features. These, however, are left for you to discover.

Magento is known for its poor developer documentation regarding certain features. Every now and then you will find yourself tracing the Magento core code trying to understand its inner workings. Hopefully, the preceding introduction will give you a good starting point.