Amitav Roy

Blog on web and travel

Drupa 7 module development: Making settings form in drupal using forms api

Posted on 14 Sept 2011 by Amitav Roy

I have this block on my site where I display a featured article. Nothing fancy, its just an article which I would like people to have a look and more importantly the article should have a link on the home page so that Google can crawl it quickly.

But, somehow it is not quite the Drupal way of doing things. So, I decided to have a very simple interface (a Drupal setting page) to set the node id which will be displayed as the featured article. The node-id will be stored in the database and when the page is viewed, the node load will happen with the node id stored in the dB.

Cool, so what are the things that we are going to do:

Create a module (in my case, it is amitav_settings)
Implement hook_menu() for the settings page
Form for the settings page
Store the variables in the variables table in Drupal DB
Use watchdog method to add error messages to the watchdog table.
Use drupal_set_message to show messages to the end user.

NOTE: If you are new to Drupal module development, then I suggest you get the basics right at first. You can get that here: Writing Drupal .info file. Once done you can always refer to this tutorial.

Here is the first part of the code. Here is am implementing drupal hook_menu()

/**
 * Implementing hook_menu().
 */

function amitav_settings_menu() {
    $items['admin/config/amitavroy'] = array(
        'title' => "Amitav Roy Site settings",
        'description' => t("This is the page for various settings for the site."),
        'position' => 'right',
        'weight' => -5,
        'access arguments' => array('administer site configuration'),
        'page callback' => 'system_admin_menu_block_page',
        'file' => 'system.admin.inc',
        'file path' => drupal_get_path('module', 'system'),
    );

    $items['admin/config/amitavroy/featured'] = array(
        'title' => 'Featured article',
        'description' => t('Set the featured article of the site in justread section.'),
        'page callback' => 'drupal_get_form',
        'page arguments' => array('featured_articles'),
        'file' => 'includes/amitav_settings.featured.inc',
        'access arguments' => array('administer site configuration'),
    );

    return $items;
}

There are two items, one admin/config/amitavroy which is like the landing page for all the settings page. All other settings will be listed inside this. And that is the reason I have implemented system_admin_menu_block_page function in page callback.

The second item is the actual menu item where the form will be generated. In this page, I am using drupal_get_form to generate the form. And the whole form will be passed as an array in the form of argument from the function featured_articles which will return the form element. [This is the typical way of implementing Drupal hook_menu and generate form.]

The function featured_articles() will be searched for in the file “includes/amitav_settings.featured.inc” as per line number 20.

So, now let’s look at the function featured_articles and the other functions which are supporting it.

/**
 * This form generates the setting for the featured article setting.
 */
function featured_articles() {
 $def_node_id = _form_default_value();
 $form['featured_article'] = array(
    '#type' => 'textfield',
    '#size' => 10,
    '#maxlength' => 10,
    '#required' => TRUE,
    '#default_value' => $def_node_id['featured'],
    '#title' => t('Featured article node ID'),
    '#description' => t('Enter the node id of the article that you want to feature on the website.'),
 );
 
 $form['#submit'][] = 'submit_setting_for_site'; //Submit button call back.
 return system_settings_form($form);
}
/**
 * This function gets the default values for different settings in this form.
 * @return type array of default values for the settings form.
 */
function _form_default_value() {
    $def_values['featured'] = variable_get('feat_article');
    return $def_values;
}
 
/**
 *
 * This function handels the submit of the settings form.
 */
function submit_setting_for_site($form, $form_state) {
 $featured_nid = $form_state['input']['featured_article'];
 $var_name = 'feat_article';
// Setting the variable with the function.
 _featured_node_set($featured_nid,$var_name);
}
/**
 * Inner function for checking and setting the variable.
 */
function _featured_node_set($featured_nid,$var_name) {
    // Checks before setting the variable.
    if (variable_get($var_name) && $featured_nid != 0) {
        variable_set($var_name, $featured_nid);
        watchdog('site settings', "Featured article value now {$featured_nid}.");
        
        $message = "Featured article nid changed to {$featured_nid}.";
        drupal_set_message($message);
    }
    
    // No featured article is set for now.
    else {
    // Setting a default value.
    variable_set($var_name, $featured_nid);
    
    // Setting the drupal message for default value.
    $message = "The value was not set. Currently set to 1. <br>Please set it to a proper node ID.";
    drupal_set_message($message);
    }
}

The function uses a def_node_id variable to store the already set featured article node id. This is important so that when you change the setting, you know what the current setting is.

You will see _form_default_value() function is called which uses variable_get() function to get the current feature article node id.

Then it’s just a simple form element ‘textfield’. Default value of the text field is $def_node_id[‘featured’] which we got using the variable_get() method.

Then we come to the submit_setting_for_site($form, $form_state) function. It calls a function which does bulk of the checking and error reporting jobs. I have used the watchdog function to add a record that the featured article value was changed.

[NOTE: I have used the watchdog only when we get a successful event. You can use it for failure too. But, I have just set an error message when the thing goes wrong.]

The variable set message stores the value and the variable name in the variable table of Drupal which is a huge advantage for us.