Thursday, July 31, 2008

Writing your first Drupal custom module

How to write a drupal module to meet your custom requirements?
here is a simple guide. This assumes that you already have a working installation of drupal 6.x.

There are lot of tutorials available out there. I do not want to add one more. I just want to provide the developer a jump start by omitting most of the advanced stuff.

Let us write a module which does nothing but print the famous "Hello World" in the content area (not in the side bar) and call it "helloworld" module.

Now for directories and conventions. In the drupal installation directory, you will find "modules" directory. This is the directory which contains modules officially packaged with drupal. Don't mess this directory. You will also find a "sites" directory where installation specific modules need to be put. Under this directory, you will find "all" directory. The modules under this directory will be available for all sites catered by that particular installation (drupal can cater to multiple sites using one installation). Let us use this "all" directory. Create a directory "modules" under this. The "modules" directory will hold the custom modules. Create a directory "helloworld" under "modules". This will be the directory for our module files.

For our module to work, we need two files under this directory. info file and module file. info file contains information (such as id, version, etc) about your module and module file contains the code.

Let us create info file first. Create a file called "helloworld.info" under helloworld directory. Then write the below lines into that file.

; $Id$ Helloworld
name = Hello World
description = A simple module which prints Hello World on the screen.
core = 6.x
Now a little bit of explanation. First line is the identifier for your module. You can add date, version etc to it. Let us keep it simple for the time being. Second line is a name which appears in the title of the content for your module. Third line is a small description which appears in admin section. Fourth line tells that our module is compatible with drupal 6.x.

Now for the module file. Create a file called helloworld.module in the same directory. This file contains php code. The coding convention is to open the file with no end tag. That is right, no end tag.

The content for the module files goes here.

function helloworld_perm()
{
return array('access helloworld content');
}
The above function tells drupal to create permission control in admin section for our module for accessing content. Without this, users (except admin) will not be able to access the contents of the module.

function helloworld_content()
{
$content="Hello, World!";
return $content;
}
The above function returns the content of the module. In our case, it is a simple string "Hello, World!".

function helloworld_menu()
{
$items = array();
$items['helloworld'] = array( 'title' => 'Hello World', 'page callback' => 'helloworld_content', 'access arguments' => array('access helloworld content'), 'type' => MENU_CALLBACK );

return $items;
}
This is the last function in the module file. This will add a callback which enables us to access our module contents using url like /index.php?q=helloworld or /helloworld.

Put all these 3 functions in the module file after
Now, login to drupal as admin. Go to modules under site building. At the end of the modules list, you should find your module. Enable the module by checking the checkbox and clicking "save configuration" button.

Now go to permissions under "User management". You should find a section "helloworld module". Check "authenticated user" checkbox against "access helloworld content". Configuration for our module is ready.

Logoff admin and login as a regular user. Access the URL /helloworld or /index.php?q=helloworld (depending on whether you have enabled smart url or not). You should see "Hello, World!" in the content pane.

1 comment:

brian.final said...
This comment has been removed by the author.