As we said in the previous chapter, to start a new Magento module, you have to create a module code folder under an appropriate code pool. We are going to use the local code pool for our module here.
We can use the same namespace used for the Widget module, BookStore, and create the module inside that folder. We are going to name it ThemeOptions. Let’s start creating the basic module. The following is the folder structure:
app
-
- code
- local
- BookStore
- ThemeOptions
- etc
- Helper
- Model
- etc
- ThemeOptions
- BookStore
- local
- code
1. Activating the module
To activate the module, we need to do the following three simple operations:
- Create the xml file in app/etc/modules/with the following code to activate the module:
<?xml version= “1.0”?>
<config>
<modules>
<BookStore_ThemeOptions>
<active>true</active>
<codePool>local</codePool>
<depends>
<Mage_Cms/>
</depends>
</BookStore_ThemeOptions>
</modules>
</config>
- Then, Disable or Refresh the To do this, go to admin and open System | Cache Management. Remember that once you create a theme, a module, and so on with Magento and you find some visualization issues or 404 errors, first check if the cache is disabled; if so, refresh and delete all the cache.
- Then, in the admin panel, go to the System | Configuration | Advanced tab on the left-hand side and check if the module is present and enabled as shown in the following screenshot:
2. Creating the module helper
To make the module work correctly, you need to create the module helper file. This file is needed to make the system of translations work correctly. In fact, if you don’t create this file, you will get an error on the screen. So, let’s create the Data.php file in app/code/local/BookStore/ThemeOptions/Helper/ with the following code:
<?php
/**
* BookStore Theme Options
*/
class BookStore_Themeoptions_Helper_Data extends Mage_Core_Helper_ Abstract
{
}
3. Creating the configuration file config.xml
The configuration file is very important for a Magento module, and in our case, it will show the tab in System | Configuration. In order to use Magento’s configuration section, you need to define models’ and helpers’ locations by performing the following steps:
- Let’s create the xml file in app/code/local/BookStore/ ThemeOptions/etc/ with the following basic code structure:
<?xml version= “1.0” encoding= “UTF-8”?>
<config>
</config>
- Then, inside <config>, you need to define models and helpers locations as follows:
<global>
<models>
<themeoptions>
<class>BookStore_ThemeOptions_Model</class>
</themeoptions>
</models>
<helpers>
<themeoptions>
<class>BookStore_ThemeOptions_Helper</class>
</themeoptions>
</helpers>
</global>
- Finally, in order to avoid the “permission denied” problem, you need to always add the following code inside the <config>and </config> tags:
<adminhtml>
<acl>
<resources>
<all>
<title>Allow Everything</title>
</all>
<admin>
<children>
<system>
<children>
<config>
<children>
<bookstore>
<title>Bookstore – All</title>
</bookstore>
</children>
</config>
</children>
</system>
</children>
</admin>
</resources>
</acl>
</adminhtml>
The following is the full code of the config.xml file:
<?xml version= “1.0” encoding= “UTF-8”?>
<config>
<modules>
<BookStore_ThemeOptions>
<version>0.0.1</version>
</BookStore_ThemeOptions>
</modules>
<!– define models and helpers –>
<global>
<models>
<themeoptions>
<class>BookStore_ThemeOptions_Model</class>
</themeoptions>
</models>
<helpers>
<themeoptions>
<class>BookStore_ThemeOptions_Helper</class>
</themeoptions>
</helpers>
</global>
<!– in order to avoid “404 and Permission Denied –>
<adminhtml>
<acl>
<resources>
<all>
<title>Allow Everything</title>
</all>
<admin>
<children>
<system>
<children>
<config>
<children>
<bookstore>
<title>Bookstore – All</title>
</bookstore>
</children>
</config>
</children>
</system>
</children>
</admin>
</resources>
</acl>
</adminhtml>
</config>
4. Creating the options file system.xml
Now we need to create a file that will manage all the options of our theme by performing the following steps:
- Create the file xml in app/code/local/BookStore/ThemeOptions/ etc/ with the following basic code:
<config>
<tabs>
. . .
</tabs>
<sections>
. . .
</sections>
</config>
- Inside the <tabs></tabs> tags, you need to define the tab that will be displayed on the left in system configuration. In our case, we create the Bookstore tab and place it at the very top of the left sidebar with <sort_order>000</sort_order> as follows:
<bookstore translate=”label”>
<label>BookStore Theme</label>
<sort_order>000</sort_order>
</bookstore>
- And now the fun part! Let’s create the Inside the <sections></section> tags, insert the following code that will define the section of our module’s tab:
<bookstore translate=”label”>
<label>Theme Options</label>
<tab>bookstore</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>
. . .
</groups>
</bookstore>
- Now, to make the module appear in the admin, we need to insert at least one All the options are located inside the <groups></groups> tags that we defined in the previous step. Here, all the options must be organized in subgroups that you can name as you prefer. In this case, we are going to create a test field inside the group general with the following code:
<general translate=”label” module=”themeoptions”>
<label>Test Group</label>
<frontend_type>text</frontend_type>
<sort_order>01</sort_order>
<show_in_default>1</show_in_default>
<show_in_website>1</show_in_website>
<show_in_store>1</show_in_store>
<fields>
<text_field translate=”label”>
<label>Input Text Field</label>
<frontend_type>text</frontend_type>
<sort_order>00</sort_order>
<show_in_default>1</show_in_default>
<show_in_website>1</show_in_website>
<show_in_store>1</show_in_store>
</text_field>
</fields>
</general>
- Now, go to System | Configuration in admin, and you should see the new BOOKSTORE THEME tab in the left-hand side column, as shown in the following screenshot:
As you can see, we chose the bookstore tab to instruct Magento to place this section inside the brand new tab defined in the previous step.
If you want to add the section inside one of the present tabs, you need to indicate the tab inside the <tab></tab> tag.
Let’s suppose that you want to add a section Theme Options inside the General settings tab. To display the new section there, you need to define the general tab in the following way:
<tab>general</tab>
The output will be like what is shown in the following screenshot:
Only for your reference, the following is the full code of the system.xml file that we have created:
<config>
<tabs>
<bookstore translate= “label”>
<label>BookStore Theme</label>
<sort_order>000</sort_order>
</bookstore>
</tabs>
<sections>
<bookstore translate= “label”>
<label>Theme Options</label>
<tab>bookstore</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>
<general translate= “label” module= “themeoptions”>
<label>Test Group</label>
<frontend_type>text</frontend_type>
<sort_order>01</sort_order>
<show_in_default>1</show_in_default>
<show_in_website>1</show_in_website>
<show_in_store>1</show_in_store>
<fields>
<text_field translate= “label”>
<label>Input Text Field</label>
<frontend_type>text</frontend_type>
<sort_order>00</sort_order>
<show_in_default>1</show_in_default>
<show_in_website>1</show_in_website>
<show_in_store>1</show_in_store>
</text_field>
</fields>
</general>
</groups>
</bookstore>
</sections>
</config>
5. Getting started with options fields
Now that we created the left tab, the section button, and the default group with a test option field, we are going to explore how to create a custom options panel with groups and options.
Before starting, let’s take a look at the following screenshot that shows you the module we created with Tabs, Sections, Groups, and Fields:
As we have seen, we need to set the groups and fields inside the <groups></ groups> tags, and also set the real options of the module / theme options panel.
A group can contain several fields, as you can see in the example shown in the following code, where we create two fields, an input field, and a drop-down select Yes/No field:
<groups>
<mygroup translate= “label” module= “themeoptions”>
<label>My test group title</label>
<frontend_type>text</frontend_type>
<sort_order>01</sort_order>
<show_in_default>1</show_in_default>
<show_in_website>1</show_in_website>
<show_in_store>1</show_in_store>
<fields>
<my_input_field translate= “label”>
<label>My Input Field: </label>
<comment>This is a comment</comment>
<frontend_type>text</frontend_type>
<sort_order>20</sort_order>
<show_in_default>1</show_in_default>
<show_in_website>1</show_in_website>
<show_in_store>1</show_in_store>
</my_input_field>
<my_select_field translate= “label”>
<label>My Dropdown: </label>
<comment>Source model provider Magento’s default Yes/No values</comment>
<frontend_type>select</frontend_type>
<sort_order>90</sort_order>
<show_in_default>1</show_in_default>
<show_in_website>1</show_in_website>
<show_in_store>1</show_in_store>
<source_model>adminhtml/ system_config_source_yesno</source_model>
</my_select_field>
</fields>
</mygroup>
</groups>
The result of this new group with two fields is the following:
Sometimes, if you are already logged in and you click on the Theme Options tab, the 404 Error can appear as shown in the following screenshot. This happens as a result of caching problems. To solve this, simply log out and log in again, and then refresh the cache.
Source: Sacca Andrea (2014), Mastering Magento theme design, Packt Publishing; Illustrated edition.