Wiring Up a Custom Select Control Options List for the Magento Admin Interface

Yesterday, while building the admin interface for a Magento module, I wanted to populate a select control (a.k.a. combobox or drop-down list) with a custom list of options. Inserting the select control was simple. Building the custom options class also was easy. However, figuring out how to wire in the custom options list took a little bit of time.

Quick Review

A module’s admin interface is defined in the file system.xml found in the module’s etc directory. If my company name is BenGribaudo and my module name is CustomizablePDFs, by convention this file will be located at app/code/local/BenGribaudo/CustomizablePDFs/etc/system.xml.

Here’s an example system.xml (below) which defines a single field named store_info_font. This field will show up in the admin interface as a select box containing two options: yes and no. The field type is specified by the <frontend_type> tag. The select control’s options are configured by the <source_model> tag. In this case, the Magento-defined adminhtml/system_config_source_yesno is being used as source_model‘s value.

<?xml version="1.0"?>
    <config>
        <sections>
            <sales_pdf>
                <groups>
                    <bengribaudo_customizableinvoice translate="label">
                        <label>Ben Gribaudo's Customizable Invoice</label>
                            <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>
                            <fields>
                                <store_info_font translate="label">
                                    <label>Store Information Font</label>
                                    <frontend_type>select</frontend_type>
                                    <source_model>adminhtml/system_config_source_yesno</source_model>
                                    <sort_order>40</sort_order>
                                    <show_in_default>1</show_in_default>
                                    <show_in_website>1</show_in_website>
                                    <show_in_store>1</show_in_store>
                                </store_info_font>
                            </fields>
                    </bengribaudo_customizableinvoice>
                </groups>
            </sales_pdf>
        </sections>
    </config>

Custom Options Class

Instead of having this drop-down list yes and no as options, I wanted it to display a list of font names. Magento’s wiki describes how to define a class with an instance method named toOptionsArray which returns the custom list of options. Fairly simple to do:

<?php
class BenGribaudo_CustomizablePDFs_FontList
{
    public function toOptionArray()
    {
        return array(
	        array('value' => 'Courier', 'label'=>Mage::helper('adminhtml')->__('Courier')),
	        array('value' => 'Courier-Bold', 'label'=>Mage::helper('adminhtml')->__('Courier-Bold')),
	        array('value' => 'Courier-Oblique', 'label'=>Mage::helper('adminhtml')->__('Courier-Oblique')),
	        array('value' => 'Courier-BoldOblique', 'label'=>Mage::helper('adminhtml')->__('Courier-BoldOblique'))
        );
    }
}

Wiring It Into <source_model>

The challenge was figuring out how to wire this custom options class into system.xml. The afore-mentioned Magento wiki article said to “specify it in the typical module/path_to_file format.” I thought that this meant some kind of module name then slash character then path-to-file syntax. Nope! It’s simpler that that!

I needed to set <source_model> to the name of my class  (note the absence of slashes in the value): 

<source_model>BenGribaudo_CustomizablePDFs_FontList</source_model>

Magento then used its built-in conventions to figure out where to find the definition (the PHP code) for this class. I just needed to be sure that I had saved the class’s PHP file in the location where Magento expected it to be. In the case of a class named BenGribaudo_CustomizablePDFs_FontList, that location is app/code/local/BenGribaudo/CustomizeablePDFs/FontList.php.