<?php
/**
* @file
* Module file for block_example.
*//**
* @defgroup block_example Example: Block
* @ingroup examples
* @{
* Demonstrates code creation of blocks.
*
* This is an example outlining how a module can define blocks that can be
* displayed on various pages of a site, or how to alter blocks provided by
* other modules.
*//**
* Implements hook_menu().
*
* Provides a default page to explain what this module does.
*/functionblock_example_menu() {
$items['examples/block_example'] = array(
'page callback' => 'block_example_page',
'access callback' => TRUE,
'title' => 'Block Example',
);
return$items;
}
/**
* Simple page function to explain what the block example is about.
*/functionblock_example_page() {
$page = array(
'#type' => 'markup',
'#markup' => t('The Block Example provides two sample blocks which demonstrate the various block APIs. To experiment with the blocks, enable and configure them on <a href="@url">the block admin page</a>.', array('@url' => url('admin/structure/block'))),
);
return$page;
}
/**
* Implements hook_block_info().
*
* This hook declares what blocks are provided by the module.
*/functionblock_example_block_info() {
// 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.
// Many options are defined in hook_block_info():
$blocks['example_configurable_text'] = array(
// info: The name of the block.
'info' => t('Example: configurable text string'),
// Block caching options (per role, per user, etc.)
'cache' => DRUPAL_CACHE_PER_ROLE, // default
);
// This sample shows how to provide default settings. In this case we'll
// enable the block in the first sidebar and make it visible only on
// 'node/*' pages. See the hook_block_info() documentation for these.
$blocks['example_empty'] = array(
'info' => t('Example: empty block'),
'status' => TRUE,
'region' => 'sidebar_first', // Not usually provided.
'visibility' => BLOCK_VISIBILITY_LISTED, // Not usually provided.
'pages' => 'node/*', // Not usually provided here.
);
return$blocks;
}
/**
* Implements hook_block_configure().
*
* This hook declares configuration options for blocks provided by this module.
*/functionblock_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 == 'example_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;
}
/**
* Implements hook_block_save().
*
* This hook declares how the configured options for a block
* provided by this module are saved.
*/functionblock_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 == 'example_configurable_text') {
// Have Drupal save the string to the database.
variable_set('block_example_string', $edit['block_example_string']);
}
return;
}
/**
* Implements hook_block_view().
*
* This hook generates the contents of the blocks themselves.
*/functionblock_example_block_view($delta = '') {
//The $delta parameter tells us which block is being requested.
switch ($delta) {
case'example_configurable_text':
// The subject is displayed at the top of the block. Note that it
// should be passed through t() for translation. The title configured
// for the block using Drupal UI supercedes this one.
$block['subject'] = t('Title of first block (example_configurable_text)');
// The content of the block is typically generated by calling a custom
// function.
$block['content'] = block_example_contents($delta);
break;
case'example_empty':
$block['subject'] = t('Title of second block (example_empty)');
$block['content'] = block_example_contents($delta);
break;
}
return$block;
}
/**
* A module-defined block content function.
*/functionblock_example_contents($which_block) {
switch ($which_block) {
case'example_configurable_text':
// 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.
// Block content can be returned in two formats: renderable arrays
// (as here) are preferred though a simple string will work as well.
returnarray('#markup' => variable_get('block_example_string', t('A default value. This block was created at %time', array('%time' => date('c')))));
case'example_empty':
// It is possible that a block not have any content, since it is
// probably dynamically constructed. In this case, Drupal will not display
// the block at all. This block will not be displayed.
return;
}
}
/*
* The following hooks can be used to alter blocks
* provided by your own or other modules.
*//**
* Implements hook_block_list_alter().
*
* This hook allows you to add, remove or modify blocks in the block list. The
* block list contains the block definitions. This example requires
* search module and the search block enabled
* to see how this hook implementation works.
*
* You may also be interested in hook_block_info_alter(), which allows changes
* to the behavior of blocks.
*/functionblock_example_block_list_alter(&$blocks) {
// We are going to make the search block sticky on bottom of regions. For
// this example, we will modify the block list and append the search block at
// the end of the list, so even if the administrator configures the block to
// be on the top of the region, it will demote to bottom again.
foreach ($blocksas$bid => $block) {
if (($block->module == 'search') && ($block->delta == 'form')) {
// Remove the block from the list and append to the end.
unset($blocks[$bid]);
$blocks[$bid] = $block;
break;
}
}
}
/**
* Implements hook_block_view_alter().
*
* This hook allows you to modify the output of any block in the system.
*
* In addition, instead of hook_block_view_alter(), which is called for all
* blocks, you can also use hook_block_view_MODULE_DELTA_alter() to alter a
* specific block.
*
* We are going to uppercase the title of any block if the string "magic string"
* is encountered in the content. If we were changing only our block using
* hook_block_view_MODULE_DELTA_alter to do this, we would have used the
* function:
* block_example_block_view_block_example_example_configurable_text_alter()
*
* To demonstrate the effect of this hook, you can use the
* 'configurable_text_string' block created by this module and add the
* text 'magic string' into the configuration.
*/functionblock_example_block_view_alter(&$data, $block) {
// Verify the we have raw text content
if (!isset($data['content']) || !is_string($data['content'])) {
return;
}
// If the content contains the string: 'magic string', uppercase the title.
if (strstr($data['content'], 'magic string')) {
$data['subject'] = isset($data['subject']) ? drupal_strtoupper($data['subject']) : '';
}
}
/**
* @} End of "defgroup block_example".
*/