Drupal 7 – Creating a module (Part – 3)

In our previous article, we have created a simple module that displays a “Welcome!” message whenever the user log-in to the Drupal-based website(s). Is that so simple to develop a module in Drupal 7? Yes, it is. But not this simple. Modules will do a lot of things. We have seen a simple part of it.

Usually, modules will come with configuration settings; to allow the administrators to change module-specific configuration settings; if, any. But in our simple module; no configuration settings are required. Let’s extend our module; to display the “Welcome!” message to the selected user roles only. The users whoever part of the user role(s) will see the “Welcome!” message.

So, now we need a configuration page to allow the administrators to select the user roles to display the “Welcome!” message; when they login to the website.

The first step we need to do is, place an entry on the website configuration page to access our Example node settings.

Drupal hook_menu hook

Step 1. Implement the hook function hook_menu to register a path and place a node on the website configuration page. So, the name of our hook function will be example_menu. What code we will put inside here?

We have to register paths. What paths do we have to register? See, paths are used to navigate between the nodes. To access the Drupal-based website’s configuration page; we use the ‘admin/config’ path. Like that we have to register the paths to access our Example node and its settings through the configuration path. So, we need two paths here. One is ‘admin/config/example‘ and ‘admin/config/example/settings‘.

We have to define some properties for these paths. The properties include:

• Title – To display the title of the menu
• Description – Description of the menu
• Page Callback – We have to provide the function here. This function gets called when the user accesses a particular node or path.
• Access Arguments – Restrict access to the page.

Step 2. Include the paths as items in hook_menu and assign the properties to them. We need two paths; so, we need to define two items for them. The code looks like below: Place the below code into the ‘example.module’ file.

/**
 * Implementation of hook_menu()
*/
function example_menu()
{
   $items['admin/config/example'] = array(
       'title' => 'Example node',
       'description' => 'Example node options',
       'page callback' => 'system_admin_menu_block_page',
       'access arguments' => array('administer'),
       'file' => 'system.admin.inc',
       'file path' => drupal_get_path('module', 'system'),
   );
   
   $items['admin/config/example/settings'] = array(
       'title' => 'Example node settings',
       'description' => 'Select the user roles to whom you want to display the Welcome! message.',
       'page callback' => 'drupal_get_form',
       'page arguments' => array('example_admin_settings'),
       'access arguments' => array('administer'),
       'type' => MENU_NORMAL_ITEM,
       'file' => 'example.admin.inc',
   );

   return $items;
}

Let’s walk through the code:

First array defines ‘admin/config/example’ node.

• We are telling to Drupal to call the ‘system_admin_menu_block_page’ callback when the user access this particular node. This Drupal API will display a block page. This API is defined in the System module. So, we need to provide the location where this function resides. Hence ‘file’ and ‘file path’ attributes. drupal_get_path API function we are using to get the System module location.
• We have to provide access to only administrators; hence we added ‘access arguments’ and assigned only ‘administer’.

Second array defines ‘admin/config/example/settings’ node. This is the place where we want to place our controls to allow the administrator to select the user roles to whom Welcome! the message is going to display when the user log-in to their sites.

• When the user access this node; we are telling Drupal to call Drupal API ‘drupal_get_form’. This API function will return the form array for a given form ID. We are passing form ID as ‘example_admin_settings’ through the ‘page arguments’ property.
• Here also we are restricting access to only administrators through ‘access arguments’.
• We have to define our form generation code under the ‘example_admin_settings’ function. And we are telling Drupal to check this function in the ‘example.admin.inc’ file. Why we are adding another file? Why can’t we place this code in the ‘example.module’ file? The trick here is; ‘example.module’ file will load for every page request to check whether is there any hook is implemented. But ‘example_admin_settings’ is required only when the user access ‘admin/config/example/settings’ node. Instead of placing all the code in one place; split the code into different places and access them whenever required. This will improve the site performance.
• And we are telling to create a normal menu item through the ‘type’ property.

Example node settings

Step 3. Let us see now how it looks like when we access these created paths.

• Log in to the Drupal-based website as an administrator and open the Configuration page.
• On the Configuration page, you will find our ‘Example node’ entry displayed. To access this page directly from web-browser use the URL : <your-site-name>/admin/config/.

  

• Wait! Wait! don’t click on the ‘Example node settings’ link. We have not yet implemented the functionality of it; so, definitely Drupal will throw the error message. Type the URL: <your-site-name>/admin/config/example in address bar of your web browser. Drupal will display ‘Example node’ on a separate page.

  

We will implement the rest of the functionality in the next article. Keep reading…

**