The purpose of this exercise is to demonstrate the basics of creating our very own custom module to change the way Webform does things. Later on, when we get to creating our own custom components and so forth, we will build on knowledge gained in this relatively simple project.
What we'll be doing here is changing the default Results tab view from the Submissions overview to the full submission Table view. As we noticed in the preceding exercises, the Submissions overview is not very helpful when the majority of submissions received are from anonymous users. Our intention is to save our data administrators a click or two by having Webform show the full submission data listing when they click on the Results tab.
While we're busy, we will also be re-arranging the sub-tabs on the result page so that the more frequently used items are towards the right and we'll be changing the Table sub-tab to read Database instead.
Non-coders may happily skip the remainder of this section if they so wish.
Those of us who will be following along here should note that this is not a definitive guide to creating Drupal modules. It is a simplistic and introductory venture into the world of custom coding for Drupal 7 modules using a standard API (Application Programming Interface) hook, hook_menu_alter. Some knowledge of the PHP programming language syntax is assumed.
All we need to create our custom module is a text editor and some method of copying files to the server hosting our Drupal website.
Drupal modules each reside in their very own folder and the folder is given the same name as the module.
- Let's create a folder named
webform_customto house our custom module files. - Within this new folder we'll be creating two files for our custom module to be properly recognized by the Drupal system.
- Using our favorite text editor, let us open a new empty file, enter the following code, and save the file as
webform_custom.info.name = Webform Custom description = Customize Webform Results page. core = 7.x package = Webform dependencies[] = webform
Tip
Downloading the example code
You can download the example code fles for all Packt books you have purchased from your account at http://www.PacktPub.com. If you purchased this book elsewhere, you can visit http://www.PacktPub.com/support and register to have the fles e-mailed directly to you.
- The info file introduces our module to the Drupal system. The name and description we have given previously will be displayed on the Modules page when we go to enable our custom module. The line commencing with
corestipulates that this module may only be enabled on a Drupal 7 website. - The last two lines tell Drupal that this module is an extension of the Webform module and Webform must already be enabled before this module may be enabled. Should we wish to disable Webform at a later point in time, then this custom module of ours will need to be disabled first, because Drupal will not allow us to disable a module on which other modules depend.
- Now for the bit that does the actual work. Let's open a new empty file in our text editor and save the following code as a file named
webform_custom.module.<?php // Make changes to the Results menu sub-tabs. function webform_custom_menu_alter(&$items) { // Set Results Table sub-tab as new default sub-tab. $items['node/%webform_menu/webform-results']['page callback'] = 'webform_results_table'; $items['node/%webform_menu/webform-results']['page arguments'] = array(1, '50'), $items['node/%webform_menu/webform-results/table']['type'] = MENU_DEFAULT_LOCAL_TASK; $items['node/%webform_menu/webform-results/submissions']['type'] = MENU_LOCAL_TASK; // Rename Results Table sub-tab to Database. $items['node/%webform_menu/webform-results/table']['title'] = 'Database'; // Change the order of the sub-tabs. $items['node/%webform_menu/webform-results/table']['weight'] = 4; $items['node/%webform_menu/webform-results/download']['weight'] = 5; $items['node/%webform_menu/webform-results/analysis']['weight'] = 6; $items['node/%webform_menu/webform-results/submissions']['weight'] = 7; } - Internally, the Drupal menu system is driven by an associative array called
$items. All we're doing here is changing a few of the menu items that apply to the Webform Results page. - In the first four lines of code we're substituting the full data listing for the submissions overview page as the default display when the Results tab is clicked.
- The next line of code causes the sub-tab Table to be renamed as Database.
A standard within Drupal is that items are sequenced according to their weight—a lower weight floats towards the top and a heavier weight floats towards the bottom. In the last four lines, then, we are changing the display sequence of the sub-tabs on the Results page.
- Just as we did when we installed the Webform module, we need to copy our module folder (with the two files we just created) into our Drupal installations folder
/sites/all/modules. - To enable our module, we must navigate to the Modules page on our menu bar, scroll down until we find our module, check the box to enable it, and then click on the Save configuration button.
The Drupal system scans through the /sites/all/modules folders looking for the .info files with corresponding .module files. These are then listed on the Modules page. Thanks to the pluggable modular design, Drupal allows us to make changes to various behavioral and display aspects via the hook system.
We have used hook_menu_alter to effect a change in the way that the Webform Results page behaves.
Where the Results page menu used to look like similar to the following screenshot:
It now looks similar to the following screenshot:
The concepts we have covered in this simple example will be reinforced when we encounter the Webform API, which exposes a set of hooks all of its own that we may use to manipulate Webform behaviors.