Same filename and directory in other branches
This is an example outlining how a module can be define blocks to be displayed on each page.
File
developer/examples/block_example.moduleView source
<?php
/**
* @file
* This is an example outlining how a module can be define blocks to be
* displayed on each page.
*/
/**
* Implementation of hook_help().
*
* Throughout Drupal, hook_help() is used to display help text at the top of
* pages. Some other parts of Drupal pages get explanatory text from these hooks
* as well. We use it here to provide a description of the module on the
* module administration page.
*/
function block_example_help($section) {
switch ($section) {
case 'admin/modules#description':
// This description is shown in the listing at admin/modules.
return t('An example module showing how to define a block.');
}
}
/**
* Implementation of hook_block().
*
* This hook both declares to Drupal what blocks are provided by the module, and
* generates the contents of the blocks themselves.
*/
function block_example_block($op = 'list', $delta = 0, $edit = array()) {
// The $op parameter determines what piece of information is being requested.
switch ($op) {
case 'list':
// If $op is "list", we just need to return a list of block descriptions.
// This is used to provide a list of possible blocks to the administrator,
// end users will not see these descriptions.
$blocks[0]['info'] = t('Example: configurable text string');
$blocks[1]['info'] = t('Example: empty block');
return $blocks;
case 'configure':
// If $op is "configure", we need to provide the administrator with a
// configuration form. The $delta parameter tells us which block is being
// configured. In this example, we'll allow the administrator to customize
// the text of the first block.
$form = array();
if ($delta == 0) {
// All we need to provide is a text field, Drupal will take care of
// the other block configuration options and the save button.
$form['block_example_string'] = array(
'#type' => 'textfield',
'#title' => t('Block contents'),
'#size' => 60,
'#description' => t('This string will appear in the example block.'),
'#default_value' => variable_get('block_example_string', t('Some example content.')),
);
}
return $form;
case 'save':
// If $op is "save", we need to save settings from the configuration form.
// Since the first block is the only one that allows configuration, we
// need to check $delta to make sure we only save it.
if ($delta == 0) {
// Have Drupal save the string to the database.
variable_set('block_example_string', $edit['block_example_string']);
}
return;
case 'view':
default:
// If $op is "view", then we need to generate the block for display
// purposes. The $delta parameter tells us which block is being requested.
switch ($delta) {
case 0:
// 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);
// These next three settings are be registered when the block is first
// loaded at admin/block, and from there can be changed manually via
// block administration.
$block['weight'] = -6;
$block['enabled'] = 0;
// Note that if you set a region that isn't available in a given
// theme, the block will be registered instead to that theme's
// default region (the first item in the _regions array).
$block['region'] = 'right';
break;
case 1:
// This time we'll use the more concise array declaration style.
$block = array(
'subject' => t('Title of block #2'),
'content' => block_example_contents(2),
'weight' => -7,
'enabled' => 1,
'region' => 'footer',
);
break;
}
return $block;
}
}
/**
* A block content function.
*/
function block_example_contents($which_block) {
if ($which_block == 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.'));
}
if ($which_block == 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;
}
}
Functions
Name | Description |
---|---|
block_example_block | Implementation of hook_block(). |
block_example_contents | A block content function. |
block_example_help | Implementation of hook_help(). |