"Innovation comes only from readily and seamlessly sharing information rather than hoarding it."- Tom Peters
Development Blog

Building a Simple Module in Drupal - Part One

Building a Drupal module can be a challenging task.  Believe me.  Hopefully this tutorial can help you learn how to do it.  We will be build a very simple module that makes a page with some dummy text.  It will also include permissions and admin configurations.


Overview

Building a Drupal module is actually not as hard as it sounds. You just need to learn what's needed, and how Drupal does things. Once you figure that out, you'll be good to go. There are three files that you need to start off with. Each of these files will have the * replaced by the name of the module. These files are:

  • The *.info file
  • The *.install file
  • The *.module file

The .info file

The .info file contains the information to register the module with Drupal's system. Let's take a look at what is required.

name = TestFoo                  ;The name of the module
description = A sample module   ;The description to be shown on the module page
package = Other                 ;What category the module should be displayed on the module page
version = 6.x-1.dev             ;The module version
core = 6.x                      ;What Drupal core can it work with? 
;dependencies[] =               ;Does it have any dependencies? ( Commented out b/c we have none )
project = testFoo               ;The project name - ( views)

Again, the *.info file is very important. Without it, your module will not show up on the admin module page. It's very similar to the *.info files for themes. Take a look at the .info files for other modules to get a better feel for them.

The .install file

This file contains all the important functions that are performed when a module is either turned on, turned off, or uninstalled. There are typically only two functions that are in this file… being hook_install and hook_uninstall. If you are not familiar with Drupal hooks, check out this site. Basically, you replace “hook” with the name of the module you are building. So, if I was building a module that had a project name of johnny, my install hook function would be johnny_install. It's that simple. Then, put whatever code you need into this section.

Typically, in the install and uninstall functions, the module settings are made. If there are database schema that are required, they are being installed in the install function. Also, any default drupal variables that the module requires are set here (using variable_set() ). In the uninstall function, these database schema and variables are removed.

function testFoo_install() {
      variable_set('testFoo_pageTitle', 'My TestFoo Page');
}

function testFoo_uninstall() {
      variable_del('testFoo_pageTitle');
}

The .module file

This file is where all the action takes place. To make it easier, I will break it down into a few sections… permissions, working with the menus, configuration, building a block (coming later), and building a page.

Permissions

Creating permissions for your module is actually pretty simple. It only takes one Drupal hook to create them. It's this:

function testFoo_perm() {
     return array('access testFoo', 'administer testFoo');
}

You can easily replace the text within the array with whatever you want, and with as many permissions as you want. Pretty simple, huh?

Working with the menus

The menu hook is very important because, without it, you can access your page, or any configuration for your module. Setting it up is pretty easy. Take a look… I will continue working with testFoo.

function testFoo_menu() {
     $items['admin/settings/testFoo'] = array(
          'title' => 'TestFoo Config',
          'page callback' => 'drupal_get_form',
          'page arguments' => array('testFoo_admin'),
          'access arguments' => array('administer testFoo'),
          'type' => MENU_NORMAL_ITEM
     );
     $items['testFoo'] = array(
          'title' => variable_get('testFoo_pageTitle', 'My Page'),
          'page callback' => 'get_testFoo_page_contents',
          'access arguments' => array('access testFoo'),
          'type' => MENU_NORMAL_ITEM

     );
     return $items;
}

Now, I know that looks crazy right now. Let me explain…

  • The content in $items[ HERE ] is the URL for Drupal. For example, the admin page above will be accessed by going to admin/settings/testFoo.
  • Title is the name of the page link, wherever it appears. In the testFoo page, we pull our variable that was initially made on install, but we will be able to configure later.
  • The page callback argument contains the name of the function that will return a string of content for this particular page. For example, the admin page above will call drupal_get_form, while the testFoo page will call get_testFoo_page_contents. Now, drupal_get_form is a Drupal function that is used for creating forms. That's why there's the page arguments. For the testFoo page, you will need to make a get_testFoo_page_contents function that will return a string of data. I'll get to that later.
  • The page arguments is used in this case because the form needs to know what to output. This setting is another function call, but I'll hit that in the Configuration section down below.
  • The access arguments is an array of permissions that need to be set in order for a user to access this page. To access the admin page above, you must have the 'administer testFoo' permission, while to access the testFoo page, you only need 'access testFoo' permission.
  • The type is the type of menu link this is. These are predefined constants that Drupal uses. Click here for more information about that, as well as info about hook_menu.

Configuration

Now that you have the menu set up, and a link going to an admin page, let's make a configuration page. I will continue with my testFoo module in this example. Here is what it might look like. Remember that the name of the function needs to match the page arguments that you listed for this page.

function testFoo_admin() {
  $form['testFoo_pageTitle'] = array(
    '#type' => 'textfield',
    '#title' => t('Page Title'),
    '#default_value' => variable_get('testFoo_pageTitle', 'My Page'),
    '#size' => 60,
    '#maxlength' => 256,
    '#description' => t('The title for the testFoo page')
  );
  return system_settings_form($form);
}

Ok..this code is kinda self-explanatory, but I'll explain.

  • The key for the $form variable needs to be the same as the variable name that you want to save. In this case, it's testFoo_pageTitle.
  • The #type is going to be the form input type.
  • The #title is the label that will be displayed with the element. The t() function translates the text for you, to make the site multi-language.
  • The default value will obviously be whatever the current value is.
  • The description is the little help text that goes along with this particular input.
  • Once returned, the admin page is made! Simple, huh?

Making a page

Making the actual page is fairly simple. You just need to have a function that matches the one you set in the page callback for the menu item. Here is an example:

function get_testFoo_page_contents() {
     return t('<p>Some test of the foo</p>');
}

That's it! You can make it as complicated, or as simple as you want. All that has to happen is a return of text. Generally, it's best to use the t() function for usability.