Drupal 7: Creating a module (Part – 3)

In our previous article, we have created a simple module which displays a Welcome! message whenever the user log-in into their 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 lot of things. We have seen a simple part of it.

Usually modules will comes 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. Lets extend our module; to display the Welcome! message to the selected user roles. 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 log-in into the site.

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

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

We have to register paths. What paths we have to register? See, paths are used to navigate between the nodes. To access Drupal based website’s configuration page; we use ‘admin/config’ path. Like that we have to register the paths to access our Example node and its settings through 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 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 access particular node or path.
  • Access Arguments – Restrict the 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 ‘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;
}

Lets walk through the code:

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

  • We are telling to Drupal to call ‘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 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! message is going to display when the user log-in into 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 ‘page arguments’ property.
  • Here also we are restricting access to only administrators through ‘access arguments’.
  • We have to define our form generation code under ‘example_admin_settings’ function. And we are telling Drupal to check this function in ‘example.admin.inc’ file. Why we are adding another file? Why can’t we place this code in ‘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 ‘type’ property.

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

  • Log in into Drupal based website as an administrator and open the Configuration page.
  • On Cofiguration 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/.

    Drupal 7 - Configuration page with Example node

    Drupal 7 – Configuration page with Example node

  • Wait! Wait! don’t click on ‘Example node settings’ link. We are 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 you web-browser. Drupal will display ‘Example node’ in separate page.

    Drupal 7 - Example node on separate page

    Drupal 7 – Example node on separate page

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

**

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

Leave a Reply