Download from Wow! eBook <www.wowebook.com>
CHAPTER 10 ■ WORKING WITH BLOCKS
hook_block_info(): This defines all blocks provided by a module.
hook_block_configure($delta = ''): The configuration form for a block. The $delta parameter is the ID of the block to return. You can use an integer or a string value for $delta. This same parameter is used in the hook_block_save and hook_block_view hooks.
hook_block_save($delta = '', $edit = array()): This saves the configuration options for a block. The $edit parameter contains the submitted form data from the block configuration form.
hook_block_view($delta = ''): This processes the block when enabled in a region in order to view its contents
Building a Block
For this example, you’ll create two blocks that make content moderation easier to manage. First, you’ll create a block to list comments being held pending approval, and then you’ll create a block to list unpublished nodes. Both blocks will also provide links to the edit form for each piece of moderated content.
Let’s create a new module named approval.module to hold our block code. Create a new folder named approval within sites/all/modules/custom (you might need to create the modules and custom folders if they don’t exist).
Next, add approval.info to the folder:
name = Approval
description = Blocks for facilitating pending content workflow. package = Pro Drupal Development
core = 7.x version = VERSION
files[] = approval.module
Then, add approval.module as well:
<?php
/**
*@file
*Implements various blocks to improve pending content workflow.
*/
Once you’ve created these files, enable the module via the Modules page. You’ll continue to work within approval.module, so keep your text editor open.
Let’s add our hook_block_info so our block appears in the list of blocks on the block administration page (see Figure 10-4). I’ll define the title that appears for the block through the info attribute, the status set to True so that it is automatically enabled, region set to sidebar_first, weight set to 0, and visibility set to 1 (visible).
230
CHAPTER 10 ■ WORKING WITH BLOCKS
/**
* Implements hook_block_info(). */
function approval_block_info() {
$blocks['pending_comments'] = array(
'info' |
=> t('Pending Comments'), |
'status' |
=> TRUE, |
'region' |
=> 'sidebar_first', |
'weight' |
=> 0, |
'visibility' => 1,
);
return $blocks;
}
Figure 10-4. “Pending comments” is now a block listed on the block overview page under the Sidebar First region heading.
Note that the value of info isn’t the title of the block that shows up to users once the block is enabled; rather, info is a description that appears only in the list of blocks the administrator can configure. You’ll implement the actual block title later in hook_block_view. First, though, you’re going to set up additional configuration options. To do this, implement the hook_block_configure function as shown in the following code snippet. You create a new form field that’s visible after clicking the configure link next to the block on the block administration page, shown in Figure 10-5.
/**
* Implements hook_block_configure(). */
function approval_block_configure($delta) {
$form = array();
switch($delta) {
case 'pending_comments':
231
CHAPTER 10 ■ WORKING WITH BLOCKS
$form['pending_comment_count'] = array( '#type' => 'textfield',
'#title' => t('Configure Number of Comments to Display'), '#size' => 6,
'#description' => t('Enter the number of pending comments that will appear in the block.'),
'#default_value' => variable_get('pending_comment_count', 5),
);
break;
}
return $form;
}
Figure 10-5. Block configuration form with the block’s custom fields
When the block configuration form shown in Figure 10-5 is submitted, it will trigger hook_block_save(). You’ll use this next phase to save the value of the form field:
/**
* Implements hook_block_save(). */
function approval_block_save($delta = '', $edit = array()) { switch($delta) {
case 'pending_comments':
variable_set('pending_comment_count', (int)$edit['pending_comment_count']); break;
}
return;
}
232
CHAPTER 10 ■ WORKING WITH BLOCKS
You save the number of pending comments to display using Drupal’s built-in variable system with variable_set(). Note how we typecast the value to an integer as a sanity check. Finally, add the view operation using hook_block_view and a custom function that returns a list of pending comments when the block is viewed:
/**
* Implements hook_block_view(). */
function approval_block_view($delta = '') {
switch ($delta) {
case 'pending_comments':
$block['subject'] = t('Pending Comments'); $block['content'] = approval_block_contents($delta); return $block;
break;
}
}
/**
* A module-defined block content function. */
function approval_block_contents($delta) { switch ($delta) {
case 'pending_comments':
if (user_access('administer comments')) {
$nbr_comments = variable_get('pending_comment_count');
$result = db_query("SELECT cid, subject FROM {comment} WHERE status = 0 limit $nbr_comments");
$items = array();
foreach ($result as $row) {
$items[] = l($row->subject, 'comment/' . $row->cid . '/edit');
}
return array('#markup' => theme('item_list', array('items' => $items)));
}
break;
}
}
Here, we’re querying the database for the comments that need approval and displaying the comment titles as links for each comment, as shown in Figure 10-6.
You also set the title of the block with the following line:
$block['subject'] = t('Pending comments');
233
CHAPTER 10 ■ WORKING WITH BLOCKS
Figure 10-6. The “Pending comments” listing block after it has been enabled; it shows two pending comments.
Now that the “Pending comments” block is finished, let’s define another block within this approval_block_info() function—one that lists all unpublished nodes and provides a link to their edit page:
/**
* Implements hook_block_info(). */
function approval_block_info() { $blocks['pending_comments'] = array(
'info' |
=> |
t('Pending comments'), |
'status' |
=> |
TRUE, |
'region' |
=> |
'sidebar_first', |
'weight' |
=> |
0, |
'visibility' => 1, |
||
); |
|
|
$blocks['unpublished_nodes'] = array( |
||
'info' |
=> t('Unpublished nodes'), |
|
'status' |
=> TRUE, |
|
'region' |
=> 'sidebar_first', |
|
'weight' |
=> 0, |
|
'visibility' => 1,
);
return $blocks;
}
Notice how the blocks are each assigned a key ($blocks['pending_comments'], $blocks['unpublished_nodes'], . . . $blocks['xxxxxx']). The block module will subsequently use these keys as the $delta parameter.
I’ll update the hook_block_configure and hook_block_save functions by adding the form for setting the number of nodes to display and saving the value entered on the form by a site administrator.
/**
* Implements hook_block_configure(). */
function approval_block_configure($delta) {
234
CHAPTER 10 ■ WORKING WITH BLOCKS
$form = array();
switch($delta) {
case 'pending_comments': $form['pending_comment_count'] = array(
'#type' => 'textfield',
'#title' => t('Configure number of comments to display'), '#size' => 6,
'#description' => t('Enter the number of pending comments that will appear in the block.'),
'#default_value' => variable_get('pending_comment_count', 5),
);
break;
case 'unpublished_nodes': $form['unpublished_node_count'] = array(
'#type' => 'textfield',
'#title' => t('Configure Number of Nodes to Display'), '#size' => 6,
'#description' => t('Enter the number of unpublished nodes that will appear in the block.'),
'#default_value' => variable_get('unpublished_node_count', 5),
);
break;
}
return $form;
}
/**
* Implements hook_block_save(). */
function approval_block_save($delta = '', $edit = array()) {
switch($delta) {
case 'pending_comments':
variable_set('pending_comment_count', (int)$edit['pending_comment_count']); break;
case 'unpublished_nodes':
variable_set('unpublished_nodes_count', (int)$edit['unpublished_node_count']); break;
}
return;
}
235
CHAPTER 10 ■ WORKING WITH BLOCKS
I’ll then update the hook_block_view and approval_block_content functions to address displaying unpublished nodes.
/**
* Implements hook_block_view(). */
function approval_block_view($delta = '') {
switch ($delta) {
case 'pending_comments':
$block['subject'] = t('Pending Comments'); $block['content'] = approval_block_contents($delta); return $block;
break;
case 'unpublished_nodes':
$block['subject'] = t('Unpublished Nodes'); $block['content'] = approval_block_contents($delta); return $block;
break;
}
}
/**
* A module-defined block content function. */
function approval_block_contents($delta) { switch ($delta) {
case 'pending_comments':
if (user_access('administer comments')) {
$nbr_comments = variable_get('pending_comment_count', 5);
$result = db_query_range('SELECT cid, subject FROM {comment} WHERE status = 0', 0, $nbr_comments);
$items = array();
foreach ($result as $row) {
$items[] = l($row->subject, 'comment/'.$row->cid.'/edit');
}
return array('#markup' => theme('item_list', array('items' => $items)));
}
break;
case 'unpublished_nodes':
if (user_access('administer nodes')) {
$nbr_nodes = variable_get('unpublished_node_count', 5); $result = db_query_range('SELECT nid, title FROM {node} WHERE status = 0', 0, $nbr_nodes);
$items = array();
foreach ($result as $row) {
$items[] = l($row->title, 'node/'.$row->nid.'/edit');
}
236