Quick and Smart Drupal Module Configuration

This is a copy of the blog post located here.

As a Drupal module developer, you may have spent some time coding mundane submit handlers for configuration forms. That can end after you read this post. There is a saviour out there. A saviour waiting to rescue you from the depths of coding boredom, waiting to take you to that place we all love and enjoy: PHP heaven!. That saviour comes in the form of the system_settings_form() function.

Using this function, a developer may define a module configuration form without a corresponding submit handler, and the form data would automatically be stored as variables upon submit. To demonstrate how the function is used, we will implement a small Drupal module sys_settings.

We will begin by creating the module folder sys_settings in the sites/all/modules directory. Within that directory, create the sys_settings.info file and add the following text. This ensures the module can be detected by Drupal.

name = "System Settings Form Demo"
description = "A demonstration of how to use the system_settings_form() function."
core = 6.x

Now we move on to the sys_settings.module file, where all the operational code will be held. Let us take a look at the menu hook.

/**
 * Implementation of hook_menu().
 */
function sys_settings_menu() {
  $items['admin/settings/sys-settings'] = array(
    'title' => 'System Settings Form Demo',
    'description' => 'Change the demo settings',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('sys_settings_admin_form'),
    'access arguments' => array('administer site configuration'),
  );
  $items['view-settings'] = array(
    'title' => 'View Configured Settings',
    'page callback' => 'sys_settings_view_conf',
    'access arguments' => array('administer site configuration'),
    'type' => MENU_NORMAL_ITEM,
  );
  return $items;
}

The first item creates a menu path to the configuration page. It supplies the callback function (drupal_get_form) and the parameter to be passed to that function (which is itself a function that builds the configuration form using the Form API). The second item creates a menu path for the page we will use to view the module configurations.

Moving on to the reason for this post, the function that builds the configuration form. It is defined as follows.

/**
 * Form builder.
 *
 *@ingroup forms
 *@see system_settings_form()
 */
function sys_settings_admin_form() {
  $form['sys_settings_text'] = array(
    '#type' => 'textfield',
    '#title' => t('Demo Textfield'),
    '#default_value' => variable_get('sys_settings_text', 'not set'),
    '#description' => t('Enter a value in the textfield'),    
  );
  $form['sys_settings_radios'] = array(
    '#type' => 'radios',
    '#title' => t('Demo Radios'),
    '#options' => array(t('Zero'), t('One'), t('Two')),
    '#default_value' =>  variable_get('sys_settings_radios', 0),
  );
  return system_settings_form($form);
}

I would like to draw your attention to the two peculiarities of this form definition.

A submit button was not defined.
Instead of returning the $form array, the result of the call to system_settings_form() is returned.

The second point is the one to focus on. The call to system_settings_form() ensures that submit and reset buttons are appended to the form, and the appropriate handlers are identified to store the form data as variables. The variables that are stored inherit the names of their corresponding form array indexes. In this case, we will have two variables, sys_settings_text and sys_settings_radios. Given that the data are stored to variables, it is sensible to retrieve the default values for the form elements from these variables (returning default data if they are not set as yet), as is seen on lines 11 and 18.

That leaves us with the function that handles displaying the settings. It is defined as follows.

/**
 * Display Config.
 */
function sys_settings_view_conf() {
  $output = '';
  $output .= 'Textfield entry: ' . 
                variable_get('sys_settings_text', 'not set') . '<br />';
  $output .= 'Radio selection: ' . 
                variable_get('sys_settings_radios', 0);
  return $output;
}

After doing this we can create an install file (sys_settings.install) and define an uninstall routine to clean up the variables after we are done testing the module. Enter the following code in that file.


/**
 * Implementation of hook_uninstall().
 */
function sys_settings_uninstall() {
  variable_del('sys_settings_text');
  variable_del('sys_settings_radios');
}

And that gives us a fully functional module. You may proceed to admin/build/modules to enable the module for testing. After enabling, go to view-settings or click on View Configured Settings in the navigation menu. You should see something like this:

view settings

It shows that no text has been placed in our textfield as yet and the radios default to the first one as is expected. Going to the configuration page at admin/settings/sys-settings the admin interface is presented:

configuration interface

Change these values and go back to the viewing page and you will notice the changes there.

And that wraps it up. The quick and smart way to configure your Drupal module. Note that this method may not work for complex modules in which database interaction is required. It is, however, a nice fit for modules with relatively small amounts of configuration parameters that can be stored as variables.

I hope this was an informative post and I can assure you that there is more to come. Happy coding!