Drupal 6.x

At this point, you can install your module and it'll work. Let's do that, and then see where we need to improve the module.

Install

To install the module, you'll need to copy your onthisdate.module and onthisdate.info files to the right directory on your site, if they are not there already (probably sites/all/modules/onthisdate -- see the first page of this tutorial for more information).

Enable

Log in as your site administrator, and navigate to the modules administration page to get an alphabetical list of modules. In the menus: Administer » Site building » Modules, or via URL:

• http://example.com/admin/build/modules
• http://example.com/?q=admin/build/modules

When you scroll down, you'll see the onthisdate module listed with the description next to it, in the "Other" section. Enable the module by selecting the checkbox and save your configuration.

Configure

The purpose of this module is to display a block, but just enabling the module doesn't make the block display. You need to go to the blocks administration page (Admin >> Site building >> Blocks or paste admin/build/block) and enable it.

The next step in this tutorial is to generate the content of the block. This will involve accessing the Drupal 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.

To tell Drupal what content we want in the block, we use the 'view' operation of hook_block(). So, we'll need to add some code to our previously-defined onthisdate_block() function.

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.

<?php

/**
* Generate HTML for the onthisdate block
* @param op the operation from the URL
* @param delta offset
* @returns block HTML
*/
function onthisdate_block($op='list', $delta=0, $edit = array()) {
// set up an empty array which will contain the block contents
$block = array();

switch ($op) {
case "list":

Modules are created to do all sorts of things: some modules create blocks (abbreviated content that often appears on the right or left side of the page), others create special content types (for full page content - such as the content you are reading right now), others track back-end information, and some do all the above. You may hear the phrases "Block modules" used to describe modules that primarily create block content (such as the menu module) or "Node modules" used to describe modules that primarily generate full page content (such as the blog and forum modules). At this stage, this module is a "block module", because it generates a block.

Later on we will show how to generate page content, which is very similar.

In this page of the tutorial the module will define a block that will eventually (after the next page of the tutorial) display the most recent blog and forum posts. The hook for creating blocks is called hook_block(). To implement any hook in Drupal, replace "hook" in the hook name with your module's short name, and create a function in the .module file with that name. So, we implement this hook by creating a function called onthisdate_block() in the onthisdate.module file.

Here's the basic format:

<?php
/**
* Implementation of hook_block().

Main topic described: Permissions
Drupal hook described: hook_perm

The main module file

The main module file will be called [your_module_name].module. It is important that it has that name, since that is what Drupal will look for. If you just call it something like [your_module_name].php then Drupal will not find it as and treat it as a module. The [your_module_name].module file will contain the heart of your module code, including the permissions code which we describe on the rest of this page. Your module will therefore always begin with the following 2 files:

• [your_module_name].info
• [your_module_name].module

Defining permissions

Main topic described: Let Drupal know the module exists
Drupal hook described: hook_help
In addition to the modulename.module file, all modules must have a modulename.info file, which contains meta information about the module.

The general format is:

name = Module name
description = A description of what your module does.
core = 6.x

For this example, the file would be named "onthisdate.info". Without this file, the module will not show up in the module listing. For this example, it could contain the following:

name = On this date
description = A block module that lists links to content created one week ago.
core = 6.x

Add the source above to a file named to onthisdate.info and save it into the module's directory at sites/all/modules/onthisdate.

Note: If you copy and paste this code block, ensure that the description data does not contain a line break (turn off word-wrap on your text-editor to be sure). Otherwise, the .info file will not parse correctly.

Info File Details

name (Required)

As mentioned in the introduction, in this tutorial we're using the example of a module that lists links to content such as blog entries or forum discussions that were created recently, which we'll currently define as exactly one week ago. This page in the tutorial describes how to create the initial module file and directory.

Name your module

The first step in creating a module is to choose a "short name" for it. This short name will be used in all file and function names in your module, so it must start with a letter and by Drupal convention it must contain only lower-case letters and underscores. For this example, we'll choose "onthisdate" as the short name. Important note: It is not just a convention that the short name is used for both the module's file name and as a function prefix. When you implement Drupal "hooks" (see later portions of tutorial), Drupal will only recognize your hook implementation functions if they have the same function name prefix as the name of the module file.

It's also important to make sure your module does not have the same short name as any theme you will be using on the site.

Create a folder and a module file