Drupal 7 – Creating a module (Part – 4)

As of now, we have created a node on the Configuration page to place the link to change the example module’s configuration settings. Now we have to implement the functionality to run when the user clicks on the Example node from the Configuration page. That means, we have to tell Drupal to display the Example module’s configuration settings page when the user clicks on the Example node from the Configuration page.

Is the Example module’s configuration settings page is ready? No. Not yet. We have to set it, through our code. So, Drupal will display the page whenever required.

Do you remember, in our previous article, we have instructed Drupal to call the “example_admin_settings” function when the user clicks on the Example node? And we have clearly mentioned that, look for “example_admin_settings” function in “example.admin.inc” file.

So, we need to create a file “example.admin.inc” and add the function “example_admin_settings”. But what code to add to this function? Don’t worry! We will look at these things step-by-step.

Step 1. Create a file “example.admin.inc”.

Step 2. Now we have to implement the “example_admin_settings” function. The purpose of this function is to create a configuration settings form.

On the form, what controls do we have to place? Good question. Our requirement is, display the “Welcome!” message for the selected role(s) only. So, we need a checkbox for each role and allow the administrator to select or un-select the checkboxes. And important thing is, allow the administrator to save the configuration settings.

Drupal system_settings_form – Creating module’s configuration form

Step 3. We will use Drupal’s API “system_settings_form” to create our form. This API function expects $form as an argument. The syntax of the function looks like below:

function system_settings_form($form);

Here $form is an associative array containing the structure of the form.

Drupal forms are represented as an array of arrays. This structure describes how to represent the form; Drupal’s form rendering engine uses this information and displays the form. This structure contains form properties; each form property is denoted with a pound sign (#).

Step 4. We have to define the form structure to pass it to the “system_settings_form” API function. We already discussed that our form will contain a checkbox for each role. So, based on this we create a form. The form structure would be like this:

   $form['example_user_roles'] = array(
      '#type' => 'checkboxes',
      '#title' => t('Select Role(s)'),
      '#options' => $roles,
      '#default_value' => variable_get('example_user_roles', array(3)),
      '#description' => t('Users will see Welcome! message when they logged into the site.'),
   );

Let us discuss each form property from the above code.

• ‘#type’ tells what type of form element we are using. We are telling to create ‘checkboxes’. That means multiple checkboxes.
• ‘#title’ is the title of the element.
• ‘#options’ are used to build those ‘checkboxes’; based on the values Drupal will generate the checkboxes. We are passing the $roles variable here; this is a keyed array. We are going to populate this with a list of user roles.
• ‘#default_value’ tells what would be the default value. That means, from multiple checkboxes, we have to tell Drupal what check box to select when none of the checkboxes are selected. Observe that, we have used the “variable_get” function here. Drupal provides “variable_get” and “variable_set” functions to store and retrieve variable information from/to the database. We are using variable_get() function to check is there is any value defined for the entry ‘example_user_roles’ in database. If any value exists, it will return the value. Otherwise, we are telling to return ‘administrator’ as a default value. Here we are using “variable_get” to retrieve the variable ‘example_user_roles’ information from the database. If not finds it returns the default value which is passed in its second argument. So, we are instructing to return “array(‘administrator’)” as the default value if ‘example_user_roles’ information is not found in the database.
• ‘#description’ provides description. Observe that we are using the t() function. This is important while using language translations.

We have been instructed to create a form with the key-value ‘example_user_roles’ and define the required form properties.

Step 5. As we have seen in the above step; the code used the $roles variable. And $roles contains a list of user role(s). Now we need to look into how to populate this $roles variable.

Actually, for our requirement, we need a list of user roles created in the Drupal database. Let’s check for Drupal API which returns this information…

Yeah!!! I found one Drupal API which returns a list of user role(s). The API is “user_roles”. If we see the syntax in Drupal API documentation, it would be like below:

function user_roles($membersonly = FALSE, $permission = NULL);

This function takes two optional arguments. One is $membersonly; which is a Boolean type variable that controls what roles to return. If we pass TRUE through these arguments, this function will exclude the ‘anonymous’ role to return.

Another one is $permission; which is a string containing permission to control to return only roles with that permission.

Finally, we will get an associated array with the role id as the key and the role name as value.

So, in our case, we have to call this function like below:

$roles = user_roles(TRUE);

Now our variable $roles are ready with the list of user roles.

If we print this variable; the values look like below:

Array ( [2] => authenticated user [3] => administrator )

Observe that the key value for ‘administrator’ is ‘3’. This is the value we instruct to select when there is no checkbox selected from the form (see Step 4.).

Step 6. Few more things we have to do. We have to instruct Drupal, what to do when the administrator submits the form. We can inform this through or $form structure. So, the code will be like this:

$form['#submit'][] = 'example_admin_settings_submit';

We are instructing Drupal to call the “example_admin_settings_submit” function when the form is submitted.

Step 7. We are almost done. I know you will ask one question. Where do we mention creating a submit button on the form? Good. We are not mentioned. But it will take care of by Drupal through the “system_settings_form” API. So, we no need to add submit button through our $form variable.

Now it’s time to call “system_settings_form” API. The call will be like below:

system_settings_form($form);

It’s so simple, right? Yep.

Step 8. Now we will put it all together. The code looks like below: Remember that we are placing this code into the ‘example.admin.inc’ file.

<?php

/**
 * Implementation of example_admin_settings()
*/
function example_admin_settings()
{
   $roles = user_roles(TRUE);
   
   $form['example_user_roles'] = array(
      '#type' => 'checkboxes',
      '#title' => t('Select Role(s)'),
      '#options' => $roles,
      '#default_value' => variable_get('example_user_roles', array('administrator')),
      '#description' => t('Users will see Welcome! message when they logged into the site.'),
   );

   $form['#submit'][] = 'example_admin_settings_submit';

   return system_settings_form($form);
}

As discussed in the above steps, the purpose of this form is to display a list of user roles on the form. Allows administrators to select which user role(s) to see the “Welcome!” message when they logged into their websites.

Now we are ready to go. Let’s test whether we are getting this form or not.

Click on the “Example node settings” link from “EXAMPLE NODE” from the Configuration page. Hurray!!!! Our form is displayed.

Drupal displays our form and selected the ‘administrator’ checkbox. We already been informed to select the ‘administrator’ checkbox, if none of the checkboxes are selected. Actually, we are not telling to select default value when no checkbox is selected. We are telling to Drupal, select the default value when there is no ‘example_user_roles’ variable entry in the Drupal database.

We will discuss more this in our next article. Keep reading…

**