block_example.module

<?php
/**
 * @file
 * Hook implementations for the Block Example module.
 */

/**
 * @defgroup block_example Example: Block
 * @ingroup examples
 * @{
 * This example demonstrates how blocks are created.
 *
 * This is an example outlining how a module can define blocks that can be
 * displayed on various pages and how modules can alter blocks provided by a
 * module.
 */

/**
 * 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 layout admin page</a>.', array('@url' => url('/admin/structure/layouts/'))),
  );
  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'),
    'description' => 'This block is configurable.',
  );

  // This sample shows how to provide a block which extends Block class. The
  // configuration and display of this block are defined in a separate class
  // file which is loaded by hook_autoload_info().
  $blocks['example_subclass'] = array(
    'info' => t('Example: subclass block'),
    'description' => 'This block is defined by extending Block class.',
    'class' => 'BlockExample',
  );

  $blocks['example_uppercase'] = array(
    // info: The name of the block.
    'info' => t('Example: uppercase this please'),
    'description' => 'This block\'s title will be uppercase.',
  );

  // This sample shows how to make a block that is only available when required
  // information is provided. This block will only be available when it is
  // placed in a layout that has a node context. That is, the layout's path
  // is node/% or any other path where the wildcard is a node ID.
  $blocks['example_node_context'] = array(
    'info' => t('Example: Node Context'),
    'description' => t('This block is only available when a node context is available. It will pull out information about the node and display it in the block.'),
    // The key of this array is the name of the context and the value is the
    // type of context. This allows you to require multiple contexts of the same
    // type. e.g. array('node1' => 'node', 'node2' => 'node').
    'required contexts' => array('node' => 'node'),
  );

  return $blocks;
}

/**
 * Implements hook_block_configure().
 *
 * This hook declares configuration options for blocks provided by this module.
 */
function block_example_block_configure($delta = '', $settings = array()) {
  $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') {
    // Add in default values to the settings array.
    $settings += array(
      'example_string' => '',
      'uppercase' => '',
    );
    // All we need to provide is the specific configuration options for our
    // block. Backdrop will take care of the standard block configuration options
    // (block title, page visibility, etc.) and the save button.
    $form['example_string'] = array(
      '#type' => 'textfield',
      '#title' => t('Block contents'),
      '#size' => 60,
      '#description' => t('This text will appear in the example block.'),
      '#default_value' => $settings['example_string'],
    );
    $form['uppercase'] = array(
      '#type' => 'checkbox',
      '#title' => t('Uppercase the block contents'),
      '#default_value' => $settings['uppercase'],
    );
  }

  return $form;
}

/**
 * Implements hook_block_save().
 *
 * This hook declares how the configured options for a block provided by this
 * module are saved. This hook is optional if we do not wish to modify the
 * way values are saved. Values are saved into the layout configuration file
 * that contains this block.
 */
function block_example_block_save($delta = '', &$edit = array()) {
  // We need to check $delta to make sure we are saving the right block.
  if ($delta == 'example_configurable_text') {
    // Cast the checkbox option to a boolean value before saving.
    $edit['uppercase'] = (bool) $edit['uppercase'];
  }
}

/**
 * Implements hook_block_view().
 *
 * This hook generates the contents of the blocks themselves.
 */
function block_example_block_view($delta = '', $settings = array(), $contexts = array()) {
  // 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 Backdrop UI supersedes 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($settings);
      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;

    case 'example_node_context':
      // Pull out the contextual information (a node in this case) from the
      // contexts array.
      $node = $contexts['node'];
      $author = user_load($node->uid);
      $block['subject'] = t('Block with node context');
      $block['content'] = t('The title of the node on this page is "@title" and was created by !author.', array('@title' => $node->title, '!author' => theme('username', array('account' => $author))));
  }
  return $block;
}

/**
 * A module-defined block content function.
 */
function block_example_contents($settings) {
  // Modules would typically perform some database queries to fetch the
  // content for their blocks. Here, we'll just use the config 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.
  $string = $settings['example_string'];
  if ($settings['uppercase']) {
    $string = backdrop_strtoupper($string);
  }
  $result = array(
    '#markup' => check_plain($string),
  );
  return $result;
}


/**
 * 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']) ? backdrop_strtoupper($data['subject']) : '';
    // This will uppercase a title set in the UI.
    $block->title = isset($block->title) ? backdrop_strtoupper($block->title) : '';
  }
}

/**
 * Implements hook_autoload_info().
 */
function block_example_autoload_info() {
  return array(
    'BlockExample' => 'block_example.inc',
  );
}

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