<?php
// $Id: block_example.module,v 1.8 2010-12-12 07:04:41 rfay Exp $

/**
 * @file
 * 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 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.
 */
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.)
    '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' => 1,  // 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.
 */
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 == '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']);
  }
  return;
}

/**
 * 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;
  }
  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.
      return array('#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.
 */
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.
 *
 * 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.
 */
function block_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']) : '';
  }
}