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:

/**
 * Implementation of hook_block().
 * @param string $op one of "list", "view", "save" and "configure"
 * @param integer $delta code to identify the block
 * @param array $edit only for "save" operation
*/
function onthisdate_block($op = 'list', $delta = 0, $edit = array()) {  

  // YOUR BLOCK GENERATION CODE GOES HERE

} // function onthisdate_block

The block function takes three parameters:

• $op (or operation): hook_block() functions get called to perform 4 different operations, which are "list", "view", "save", and "configure". This parameter tells your function which operation is called for. We'll discuss the "list" operation below and the "view" operation on the next tutorial page. The "configure" and "save" operations allow your block to have a settings form and save the settings -- we won't be using them in this tutorial.
• $delta: Your module can define more than one block in its "list" operation. Each block has a defined "delta" code, which is normally a number, and for the other operations, Drupal will pass in the "delta" value so you can identify which of a module's blocks to perform the operation on. This example module will only have one block. The core Drupal user module is an example of a module that has multiple blocks: user login block, who's new block and who's online block.
• $edit: used only with the "save" operation and not discussed in this tutorial.

The first operation is the "list" operation, which lists the blocks the module supplies, and defines how they will be seen on the Administer >> Site Building >> Blocks page (the Blocks module will call this function with $op='list' when it is building the list of blocks for the blocks administration page).

Here are the details of the onthisdate_block() function (the next tutorial page has more):

/**
 * Implementation of hook_block().
 * @param string $op one of "list", "view", "save" and "configure"
 * @param integer $delta code to identify the block
 * @param array $edit only for "save" operation
*/
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":
      // Generate listing of blocks from this module, for the admin/block page
      $block[0]["info"] = t('On This Date');
      break;
    
    case "view":
      break;

    case "save":
      break;

    case "configure":
      break;
  }

  return $block;
} // function onthisdate_block

(Note for beginners: the opening <?php will only appear once in your module file, at the beginning, and the closing ?> will not appear in your file at all.)

OK, so let's talk about that code....

$block - $block is just a variable used to store the necessary data, before returning it. A module can define more than one block (e.g. a block which shows detailed information, and a different block which shows just summary information). Therefore the block variable is an array, and each item in the array represents one block that your module supplies.
$block[0] - our example module only supplies one block, which is stored in array element 0 (the first element of the array). The "0" array index is passed to the onthisdate_block function via the $delta value parameter that will be used in later operations. If we were defining multiple blocks, we would need to have a $block[0], $block[1], $block[2], etc.; we would also have to check the $delta value passed into the function for later operations.
$block[0]["info"] Each element (0, 1, 2) representing a block is also an array of key = value pairs. Some of the keys are "info", "cache", "weight", "status". That's a bit much for an intro lesson, so we are only going to consider "info", which is the human-readable name of your block that shows up on the block administration page. So, inside hook_block() our block is known as $delta = 0, but on the admin page it is known as On This Date.

The next tutorial page will cover generating the block content, by implementing the 'view' operation.

See Also

• hook_block
• block_example.module