Drupal 7: Creating a module (Part – 4)

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

Is 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 “example_admin_settings” function when the user clicks on 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 in 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 “example_admin_settings” function. The purpose of this function is to create a configuration settings form.

On the form, what controls we have to place? Good question. Our requirement is, display the “Welcome!” message for selected role(s) only. So, we need 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.

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 use this information and display the form. This structure contains form properties; each form property denoted with a pound sign (#).

Step 4. We have to define form structure to pass it to “system_settings_form” API function. We already discussed that our form will contain 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 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 $roles variable here; this is a keyed array. We are going to populate this with list of user roles.
  • ‘#default_value’ tells what would be the default value. That means, from multiple checkboxes, we have to tell to Drupal what check box to select when none of the checkboxes are selected. Observe that, we have used “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 not found in the database.
  • ‘#description’ provides description. Observe that we are using t() function. This is important while using language translations.

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

Step 5. As we have seen in above step; the code used $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. Lets 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 controls what roles to return. If we pass TRUE through this arguments, this function will exclude ‘anonymous’ role to return.

Another one is $permission; which is a string containing a 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 is ready with list of user roles.

If we print this variable; the values looks 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 “example_admin_settings_submit” function when the form is submitted.

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

Now its time to call “system_settings_form” API. The call will be like below:

system_settings_form($form);

Its so simple right? Yep.

Step 8. Now we will put all together. The code looks like below: Remember that we are placing this code into ‘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 above steps, the purpose of this form is to display 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. Lets test whether we are getting this form or not.

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

Drupal displays our form and selected ‘administrator’ checkbox. We already informed to select ‘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 default value when there is no ‘example_user_roles’ variable entry in the Drupal database.

Drupal 7 - Configuration - "Example node settings" form

Drupal 7 – Configuration – “Example node settings” form

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

**

1 comment for “Drupal 7: Creating a module (Part – 4)

Leave a Reply