block_example.module in Examples for Developers 6

This is an example outlining how a module can define blocks to be displayed on each page.

File

block_example/block_example.module

<?php

/**
 * @file
 * This is an example outlining how a module can define blocks to be
 * displayed on each page.
 */

/**
 * @defgroup block_example Example: Block
 * @ingroup examples
 * @{
 * Block defined by a module. (drupal 6)
 *
 * This example is part of the Examples for Developers Project which you can download
 * and experiment with here: http://drupal.org/project/examples
 */

/**
 * 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 = '', $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['configurable-text'] = array(
        'info' => t('Example: configurable text string'),
      );

      // A block can provide default settings. In this case we'll enable the
      // block and make it visible only on the 'node/*' pages.
      $blocks['empty'] = array(
        'info' => t('Example: empty block'),
        'status' => TRUE,
        'weight' => 0,
        'visibility' => 1,
        'pages' => 'node/*',
      );
      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 == 'configurable-text') {

        // 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 == 'configurable-text') {

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

      // 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 'configurable-text':

          // 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 configurable-text block');

          // The content of the block is typically generated by calling a custom
          // function.
          $block['content'] = block_example_contents(1);
          break;
        case 'empty':
          $block['subject'] = t('Title of block #2');
          $block['content'] = block_example_contents(2);
          break;
      }
      return $block;
  }
}

/**
 * A block content function.
 */
function block_example_contents($which_block) {
  switch ($which_block) {
    case 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.'));
    case 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;
  }
}

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

Functions

Name	Description
block_example_block	Implementation of hook_block().
block_example_contents	A block content function.