block_example.module
<?php
// $Id: block_example.module,v 1.12 2009/10/01 18:40:14 jhodgdon Exp $
/**
* @file
* This is an example outlining how a module can define blocks that can be
* displayed on various pages of a site.
*/
/**
* Implementation of hook_block_list().
*
* This hook declares to Drupal what blocks are provided by the module.
*/
function block_example_block_list() {
// This hook returns an array, each component of which is an array of block
// information. The array keys are the 'delta' values used in other block
// hooks.
// The required block information is a block description, which is shown
// to the site administrator in the list of possible blocks. You can also
// provide initial settings for block weight, status, etc.
// This sample only provides a description string.
$blocks['configurable-text'] = array(
'info' => t('Example: configurable text string'),
);
// This sample shows how to provide default settings. In this case we'll
// enable the block and make it visible only on 'node/*' pages.
$blocks['empty'] = array(
'info' => t('Example: empty block'),
'status' => TRUE,
'weight' => 0,
'visibility' => 1,
'pages' => 'node/*',
);
return $blocks;
}
/**
* Implementation of hook_block_configure().
*
* This hook declares configuration options for blocks provided by this module.
*/
function block_example_block_configure($delta = '') {
// The $delta parameter tells us which block is being configured.
// In this example, we'll allow the administrator to customize
// the text of the 'configurable text string' block defined in this module.
$form = array();
if ($delta == 'configurable-text') {
// All we need to provide is the specific configuration options for our
// block. Drupal will take care of the standard block configuration options
// (block title, page visibility, etc.) and the save button.
$form['block_example_string'] = array(
'#type' => 'textfield',
'#title' => t('Block contents'),
'#size' => 60,
'#description' => t('This text will appear in the example block.'),
'#default_value' => variable_get('block_example_string', t('Some example content.')),
);
}
return $form;
}
/**
* Implementation of hook_block_save().
*
* This hook declares how the configured options for a block
* provided by this module are saved.
*/
function block_example_block_save($delta = '', $edit = array()) {
// We need to save settings from the configuration form.
// We need to check $delta to make sure we are saving the right block.
if ($delta == 'configurable-text') {
// Have Drupal save the string to the database.
variable_set('block_example_string', $edit['block_example_string']);
}
return;
}
/**
* Implementation of hook_block_view().
*
* This hook generates the contents of the blocks themselves.
*/
function block_example_block_view($delta = '') {
//The $delta parameter tells us which block is being requested.
switch ($delta) {
case 'configurable-text':
// The subject is displayed at the top of the block. Note that it
// should be passed through t() for translation.
$block['subject'] = t('Title of block #1');
// The content of the block is typically generated by calling a custom
// function.
$block['content'] = block_example_contents(1);
break;
case 'empty':
$block['subject'] = t('Title of block #2');
$block['content'] = block_example_contents(2);
break;
}
return $block;
}
/**
* A module-defined block content function.
*/
function block_example_contents($which_block) {
switch ($which_block) {
case 1:
// Modules would typically perform some database queries to fetch the
// content for their blocks. Here, we'll just use the variable set in the
// block configuration or, if none has set, a default value.
return variable_get('block_example_string', t('A default value.'));
case 2:
// It is possible that your block will not have any content, since it is
// probably dynamically constructed. In this case, Drupal will not display
// the block at all.
return;
}
}