block_example.module in Examples for Developers 7

Module file for block_example.

File

block_example/block_example.module

<?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.
 */
function block_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.
 */
function block_example_page() {
  $page = array(
    '#type' => 'markup',
    '#markup' => t('The Block Example provides three 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.
 */
function block_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.)
    // DRUPAL_CACHE_PER_ROLE is the default.
    'cache' => DRUPAL_CACHE_PER_ROLE,
  );

  // 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',
    'visibility' => BLOCK_VISIBILITY_LISTED,
    'pages' => 'node/*',
  );
  $blocks['example_uppercase'] = array(
    // info: The name of the block.
    'info' => t('Example: uppercase this please'),
    'status' => TRUE,
    'region' => 'sidebar_first',
  );
  return $blocks;
}

/**
 * Implements hook_block_configure().
 *
 * This hook declares configuration options for blocks provided by this module.
 */
function block_example_block_configure($delta = '') {
  $form = array();

  // 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.
  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.
 */
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 == 'example_configurable_text') {

    // Have Drupal save the string to the database.
    variable_set('block_example_string', $edit['block_example_string']);
  }
}

/**
 * Implements 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 '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;
    case 'example_uppercase':
      $block['subject'] = t("uppercase this please");
      $block['content'] = t("This block's title will be changed to uppercase. Any other block with 'uppercase' in the subject or title will also be altered. If you change this block's title through the UI to omit the word 'uppercase', it will still be altered to uppercase as the subject key has not been changed.");
      break;
  }
  return $block;
}

/**
 * A module-defined block content function.
 */
function block_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.
      // Block content created through the UI defaults to a string.
      $result = array(
        '#markup' => variable_get('block_example_string', t('A default value. This block was created at %time', array(
          '%time' => date('c'),
        ))),
      );
      return $result;
    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.
 */
function block_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 ($blocks as $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. To change only our block using
 * hook_block_view_MODULE_DELTA_alter, we would use the function:
 * block_example_block_view_block_example_example_configurable_text_alter()
 *
 * We are going to uppercase the subject (the title of the block as shown to the
 * user) of any block if the string "uppercase" appears in the block title or
 * subject. Default block titles are set programmatically in the subject key;
 * titles created through the UI are saved in the title key. This module creates
 * an example block to demonstrate this effect (default title set
 * programmatically as subject).  You can also demonstrate the effect of this
 * hook by creating a new block whose title has the string 'uppercase' in it
 * (set as title through the UI).
 */
function block_example_block_view_alter(&$data, $block) {

  // We'll search for the string 'uppercase'.
  if (!empty($block->title) && stristr($block->title, 'uppercase') || !empty($data['subject']) && stristr($data['subject'], 'uppercase')) {

    // This will uppercase the default title.
    $data['subject'] = isset($data['subject']) ? drupal_strtoupper($data['subject']) : '';

    // This will uppercase a title set in the UI.
    $block->title = isset($block->title) ? drupal_strtoupper($block->title) : '';
  }
}

/**
 * @} End of "defgroup block_example".
 */

Functions

Name	Description
block_example_block_configure	Implements hook_block_configure().
block_example_block_info	Implements hook_block_info().
block_example_block_list_alter	Implements hook_block_list_alter().
block_example_block_save	Implements hook_block_save().
block_example_block_view	Implements hook_block_view().
block_example_block_view_alter	Implements hook_block_view_alter().
block_example_contents	A module-defined block content function.
block_example_menu	Implements hook_menu().
block_example_page	Simple page function to explain what the block example is about.