Declaring block content

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 of 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.

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 appropriately called "hook_block". To implement this hook create a function called onthisdate_block() in the onthisdate.module file.

Here's the basic format:

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):

(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.
$block[0] - $block is an array variable, and each item in the array represents one block that your module supplies (our example module only supplies one block). The "0" array index is the $delta value 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