This is my first tutorial written for the Drupal site. It took me over a day to do, but it was a good learning experience. I can't say it's perfect, but at least fewer people will have to suffer through my pain after this gets through the moderation queue on the site. And, frustratingly enough, it looks like crap on my site. Argh.
Introduction
This tutorial describes how to create a module for Drupal-CVS
(i.e. Drupal version > 4.3.1). A module is a collection of functions
that link into Drupal, providing additional functionality to your Drupal
installation. After reading this tutorial, you will be able to create a
basic block module and use it as a template for more advanced modules
and node modules.
This tutorial will not necessarily prepare you to write modules for
release into the wild. It does not cover caching, nor does it elaborate
on permissions or security issues. Use this tutorial as a starting
point, and review other modules and the Drupal
handbook and Coding standards for more information.
This tutorial assumes the following about you:
- Basic PHP knowledge, including syntax and the concept of PHP objects
- Basic understanding of database tables, fields, records and SQL statements
- A working Drupal installation
- Drupal administration access and webserver access
This tutorial does not assume you have any knowledge about the inner
workings of a Drupal module. This tutorial will not help you write
modules for Drupal 4.3.1 or before.
Getting Started
To focus this tutorial, we'll start by creating a block module that
lists links to content such as blog entries or forum discussions that
were created one week ago. The full tutorial will teach us how to
create block content, write links, and retrieve information from Drupal
nodes.
Start your module by creating a PHP file and save it as
'onthisdate.module'.
<?php
?>
As per the Coding standards, use the longhand <?php tag,
and not <? to enclose your PHP code.
All functions in your module are named {modulename)_{hook}, where
"hook" is a well defined function name. Drupal will call these
functions to get specific data, so having these well defined names means
Drupal knows where to look.
Telling Drupal about your module
The first function we'll write will tell Drupal information about your
module: its name and description. The hook name for this function is
'help', so start with the onthisdate_help function:
function onthisdate_help($section) {
}
The $section variable provides context for the help: where in Drupal or
the module are we looking for help. The recommended way to process this
variable is with a switch statement. You'll see this code pattern in
other modules.
/* Commented out until bug fixed */
/*
function onthisdate_help($section) {
switch($section) {
case "admin/system/modules#name":
return "onthisdate";
break;
case "admin/system/modules#description":
return t("Display a list of nodes that were created a week ago.");
break;
}
}
*/
You will eventually want to add other cases to this switch statement to
provide real help messages to the user. In particular, output for
"admin/help#onthisdate" will display on the main help page accessed by
the admin/help URL for this module (/admin/help or ?q=admin/help).
The t() function in the second case is used to provide
localized content to the user. Any string that presents information to
the user should be enclosed in at t() call so that it can
be later translated.
Note:This function is commented out in the above code. This is
on purpose, as the current version of Drupal CVS won't display the
module name, and won't enable it properly when installed. Until this
bug is fixed, comment out your help function, or your module may not
work.
Telling Drupal who can use your module
The next function to write is the permissions function. Here, you can
tell Drupal who can access your module. At this point, give permission
to anyone who can access site content or administrate the module.
function onthisdate_perm() {
return array("administer onthisdate");
}
If you are going to write a module that needs to have finer control over
the permissions, and you're going to do permission control, you may want
to define a new permission set. You can do this by adding strings to
the array that is returned:
function onthisdate_perm() {
return array("access onthisdate", "administer onthisdate");
}
You'll need to adjust who has permission to view your module on the
administer » accounts » permissions page. We'll use the
user_access() function to check access permissions later.
Be sure your permission strings must be unique to your module. If they
are not, the permissions page will list the same permission multiple
times.
Announce we have block content
There are several types of modules: block modules and node modules are
two. Block modules create abbreviated content that is typically (but
not always, and not required to be) displayed along the left or right
side of a page. Node modules generate full page content (such as blog,
forum, or book pages).
We'll create a block content to start, and later discuss node content.
A module can generate content for blocks and also for a full page (the
blogs module is a good example of this). The hook for a block module is
appropriately called "block", so let's start our next function:
function onthisdate_block($op='list', $delta=0) {
}
The block function takes two parameters: the operation and the offset,
or delta. We'll just worry about the operation at this point. In
particular, we care about the specific case where the block is being
listed in the blocks page. In all other situations, we'll display the
block content.
function onthisdate_block($op='list', $delta=0) {
// listing of blocks, such as on the admin/system/block page
if ($op == "list") {
$block[0]["info"] = t("On This Date");
return $block;
} else {
// our block content
}
}
Generate content for a block
Now, we need to generate the 'onthisdate' content for the block. In
here, we'll demonstrate a basic way to access the database.
Our goal is to get a list of content (stored as "nodes" in the database)
created a week ago. Specifically, we want the content created between
midnight and 11:59pm on the day one week ago. When a node is first
created, the time of creation is stored in the database. We'll use this
database field to find our data.
First, we need to calculate the time (in seconds since epoch start, see
http://www.php.net/manual/en/function.time.php for more information on
time format) for midnight a week ago, and 11:59pm a week ago. This part
of the code is Drupal independent, see the PHP website (http://php.net/)
for more details.
function onthisdate_block($op='list', $delta=0) {
// listing of blocks, such as on the admin/system/block page
if ($op == "list") {
$block[0]["info"] = t("On This Date");
return $block;
} else {
// our block content
// Get today's date
$today = getdate();
// calculate midnight one week ago
$start_time = mktime(0, 0, 0,
$today['mon'], ($today['mday'] - 7), $today['year']);
// we want items that occur only on the day in question, so calculate 1 day
$end_time = $start_time + 86400; // 60 * 60 * 24 = 86400 seconds in a day
...
}
}
The next step is the SQL statement that will retrieve the content we'd
like to display from the database. We're selecting content from the
node table, which is the central table for Drupal content. We'll get
all sorts of content type with this query: blog entries, forum posts,
etc. For this tutorial, this is okay. For a real module, you would
adjust the SQL statement to select specific types of content (by adding
the 'type' column and a WHERE clause checking the 'type' column).
Note: the table name is enclosed in curly braces: {node}.
This is necessary so that your module will support database table name
prefixes. You can find more information on the Drupal website by
reading the Table Prefix (and sharing tables
across instances) page in the Drupal handbook.
$query = "SELECT nid, title, created FROM {node} WHERE created >= %d AND created <= %d", $start_time, $end_time);
Drupal uses database helper functions to perform database queries. This
means that, for the most part, you can write your database SQL statement
and not worry about the backend connections.
We'll use db_query() to get the records (i.e. the database rows) that
match our SQL query, and db_fetch_object() to look at the individual
records:
// get the links
$queryResult = db_query($query);
// content variable that will be returned for display
$block_content = '';
while ($links = db_fetch_object($queryResult)) {
$block_content .= '<a href="' . url('node/view/' . $links->nid ) . '">' .
$links->title . '</a><br />';
}
// check to see if there was any content before setting up the block
if ($block_content == '') {
/* No content from a week ago. If we return nothing, the block
* doesn't show, which is what we want. */
return;
}
// set up the block
$block['subject'] = 'On This Date';
$block['content'] = $block_content;
return $block;
}
Notice the actual URL is enclosed in the url() function. This adjusts
the URL to the installations URL configuration of either clean URLS:
http://sitename/node/view/2 or http://sitename/?q=node/view/2
Also, we return an array that has 'subject' and 'content' elements.
This is what Drupal expects from a block function. If you do not
include both of these, the block will not render properly.
You may also notice the bad coding practice of combining content with
layout. If you are writing a module for others to use, you will want to
provide an easy way for others (in particular, non-programmers) to
adjust the content's layout. An easy way to do this is to include a
class attribute in your link, and not necessarily include the <br
/> at the end of the link. Let's ignore this for now, but be aware
of this issue when writing modules that others will use.
Putting it all together, our block function looks like this:
function onthisdate_block($op='list', $delta=0) {
// listing of blocks, such as on the admin/system/block page
if ($op == "list") {
$block[0]["info"] = t("On This Date");
return $block;
} else {
// our block content
// content variable that will be returned for display
$block_content = '';
// Get today's date
$today = getdate();
// calculate midnight one week ago
$start_time = mktime(0, 0, 0,
$today['mon'], ($today['mday'] - 7), $today['year']);
// we want items that occur only on the day in question, so calculate 1 day
$end_time = $start_time + 86400; // 60 * 60 * 24 = 86400 seconds in a day
$query = "SELECT nid, title, created FROM {node} WHERE created >= %d AND created <= %d", $start_time, $end_time);
// get the links
$queryResult = db_query($query);
while ($links = db_fetch_object($queryResult)) {
$block_content .= '<a href="'.url('node/view/'.$links->nid).'">'.
$links->title . '</a><br />';
}
// check to see if there was any content before setting up the block
if ($block_content == '') {
// no content from a week ago, return nothing.
return;
}
// set up the block
$block['subject'] = 'On This Date';
$block['content'] = $block_content;
return $block;
}
}
Installing, enabling and testing the module
At this point, you can install your module and it'll work. Let's do
that, and see where we need to improve the module.
To install the module, you'll need to copy your onthisdate.module file
to the modules directory of your Drupal installation. The file must be
installed in this directory or a subdirectory of the modules directory,
and must have the .module name extension.
Log in as your site administrator, and navigate to the modules
administration page to get an alphabetical list of modules. In the
menus: administer » configuration » modules, or via URL:
http://.../admin/system/modules or
http://.../?q=admin/system/modules
Note: You'll see one of three things for the 'onthisdate' module at this point:
- You'll see the 'onthisdate' module name and no description
- You'll see no module name, but the 'onthisdate' description
- You'll see both the module name and the description
Which of these three choices you see is dependent on the state of the
CVS tree, your installation and the help function in your module. If
you have a description and no module name, and this bothers you, comment
out the help function for the moment. You'll then have the module name,
but no description. For this tutorial, either is okay, as you will just
enable the module, and won't use the help system.
Enable the module by selecting the checkbox and save your configuration.
Because the module is a blocks module, we'll need to also enable it in
the blocks administration menu and specify a location for it to display.
Navigate to the blocks administration page: admin/system/block or
administer » configuration » blocks in the menus.
Enable the module by selecting the enabled checkbox for the 'On This
Date' block and save your blocks. Be sure to adjust the location
(left/right) if you are using a theme that limits where blocks are
displayed.
Now, head to another page, say select the module. In some themes, the
blocks are displayed after the page has rendered the content, and you
won't see the change until you go to new page.
If you have content that was created a week ago, the block will display
with links to the content. If you don't have content, you'll need to
fake some data. You can do this by creating a blog, forum topic or book
page, and adjust the "Authored on:" date to be a week ago.
Alternately, if your site has been around for a while, you may have a
lot of content created on the day one week ago, and you'll see a large
number of links in the block.
Create a module configuration (settings) page
Now that we have a working module, we'd like to make it better. If we
have a site that has been around for a while, content from a week ago
might not be as interesting as content from a year ago. Similarly, if
we have a busy site, we might not want to display all the links to
content created last week. So, let's create a configuration page for
the administrator to adjust this information.
The configuration page uses the 'settings' hook. We would like only
administrators to be able to access this page, so we'll do our first
permissions check of the module here:
function onthisdate_settings() {
// only administrators can access this module
if (!user_access("admin onthisdate")) {
return message_access();
}
}
If you want to tie your modules permissions to the permissions of
another module, you can use that module's permission string. The
"access content" permission is a good one to check if the user can view
the content on your site:
...
// check the user has content access
if (!user_access("access content")) {
return message_access();
}
...
We'd like to configure how many links display in the block, so we'll
create a form for the administrator to set the number of links:
function onthisdate_settings() {
// only administrators can access this module
if (!user_access("admin onthisdate")) {
return message_access();
}
$output .= form_textfield(t("Maximum number of links"), "onthisdate_maxdisp",
variable_get("onthisdate_maxdisp", "3"), 2, 2,
t("The maximum number of links to display in the block."));
return $output;
}
This function uses several powerful Drupal form handling features. We
don't need to worry about creating an HTML text field or the form, as
Drupal will do so for us. We use variable_get to retrieve
the value of the system configuration variable "onthisdate_maxdisp",
which has a default value of 3. We use the form_textfield function to
create the form and a text box of size 2, accepting a maximum length of
2 characters. We also use the translate function of t(). There are
other form functions that will automatically create the HTML form
elements for use. For now, we'll just use the form_textfield function.
Of course, we'll need to use the configuration value in our SQL SELECT.
Because different databases have slightly different ways of limiting the
amount of data returned, Drupal provides a database independent function
to query the database: db_query_range. Get the saved
maximum number and use db_query_range():
$limitnum = variable_get("onthisdate_maxdisp", 3);
$query = "SELECT nid, title, created FROM {node} WHERE created >= %d AND created <= %d", $start_time, $end_time);
// get the links, limited to just the maxium number:
$queryResult = db_query($query, 0, $limitnum);
You can test the settings page by editing the number of links displayed
and noticing the block content adjusts accordingly.
Navigate to the settings page: admin/system/modules/onthisdate or
administer » configuration » modules » onthisdate. Adjust the number
of links and save the configuration. Notice the number of links in the
block adjusts accordingly.
Note:We don't have any validation with this input. If you enter
"c" in the maximum number of links, you'll break the block.
Adding menu links and creating page content
So far we have our working block and a settings page. The block
displays a maximum number of links. However, there may be more links
than the maximum we show. So, let's create a page that lists all the
content that was created a week ago.
function onthisdate_all() {
}
We're going to use much of the code from the block function. We'll
write this ExtremeProgramming style, and duplicate the code. If we need
to use it in a third place, we'll refactor it into a separate function.
For now, copy the code to the new function onthisdate_all(). Contrary
to all our other functions, 'all', in this case, is not a Drupal hook.
We'll discuss below.
function onthisdate_all() {
// content variable that will be returned for display
$page_content = '';
// Get today's date
$today = getdate();
// calculate midnight one week ago
$start_time = mktime(0, 0, 0,
$today['mon'], ($today['mday'] - 7), $today['year']);
// we want items that occur only on the day in question, so calculate 1 day
$end_time = $start_time + 86400; // 60 * 60 * 24 = 86400 seconds in a day
// NOTE! No LIMIT clause here! We want to show all the code
$query = "SELECT nid, title, created FROM " .
"{node} WHERE created >= '" . $start_time .
"' AND created <= '". $end_time . "'";
// get the links
$queryResult = db_query($query);
while ($links = db_fetch_object($queryResult)) {
$page_content .= '<a href="'.url('node/view/'.$links->nid).'">'.
$links->title . '</a><br />';
}
...
}
We have the page content at this point, but we want to do a little more
with it than just return it. When creating pages, we need to send the
page content to the theme for proper rendering. We use this with the
theme() function. Themes control the look of a site. As noted above,
we're including layout in the code. This is bad, and should be
avoided. It is, however, the topic of another tutorial, so for now,
we'll include the formatting in our content:
print theme("page", $content_string);
The rest of our function checks to see if there is content and lets the
user know. This is preferable to showing an empty or blank page, which
may confuse the user.
Note that we are responsible for outputting the page content with the
'print theme()' syntax. This is a change from previous 4.3.x themes.
function onthisdate_all() {
...
// check to see if there was any content before setting up the block
if ($page_content == '') {
// no content from a week ago, let the user know
print theme("page",
"No events occurred on this site on this date in history.");
return;
}
print theme("page", $page_content);
}
Letting Drupal know about the new function
As mentioned above, the function we just wrote isn't a 'hook': it's not
a Drupal recognized name. We need to tell Drupal how to access the
function when displaying a page. We do this with the _link hook and
the menu() function:
function onthisdate_link($type, $node=0) {
}
There are many different types, but we're going to use only 'system' in
this tutorial.
function onthisdate_link($type, $node=0) {
if (($type == "system")) {
// URL, page title, func called for page content, arg, 1 = don't disp menu
menu("onthisdate", t("On This Date"), "onthisdate_all", 1, 1);
}
}
Basically, we're saying if the user goes to "onthisdate" (either via
?q=onthisdate or http://.../onthisdate), the content generated by
onthisdate_all will be displayed. The title of the page will be "On
This Date". The final "1" in the arguments tells Drupal to not display
the link in the user's menu. Make this "0" if you want the user to see
the link in the side navigation block.
Navigate to /onthisdate (or ?q=onthisdate) and see what you get.
Adding a more link and showing all entries
Because we have our function that creates a page with all the content
created a week ago, we can link to it from the block with a "more" link.
Add these lines just before that $block['subject'] line, adding this to
the $block_content variable before saving it to the $block['content']
variable:
// add a more link to our page that displays all the links
$block_content .= "<div class=\"more-link\">". l(t("more"), "onthisdate", array("title" => t("More events on this day."))) ."</div>";
This will add the more link.
And we're done!
We now have a working module. It created a block and a page. You
should now have enough to get started writing your own modules. We
recommend you start with a block module of your own and move onto a node
module. Alternately, you can write a filter or theme.
Please see the Drupal Handbook for more information.
Further Notes
As is, this tutorial's module isn't very useful. However, with a few
enhancements, it can be entertaining. Try modifying the select query
statement to select only nodes of type 'blog' and see what you get.
Alternately, you could get only a particular user's content for a
specific week. Instead of using the block function, consider expanding
the menu and page functions, adding menus to specific entries or dates,
or using the menu callback arguments to adjust what year you look at the
content from.
If you start writing modules for others to use, you'll want to provide
more details in your code. Comments in the code are incredibly valuable
for other developers and users in understanding what's going on in your
module. You'll also want to expand the help function, providing better
help for the user. Follow the Drupal Coding standards, especially if
you're going to add your module to the project.
Two topics very important in module development are writing themeable
pages and writing translatable content. We touched briefly on both of
these topics with the theme() and t() calls in
various parts of the module. Please check the Drupal Handbook for more details on these two
subject.
