block.module

<?php

/**
 * @file
 * Controls the boxes that are displayed around the main content.
 */

/**
 * Denotes that a block is not enabled in any region and should not
 * be shown.
 */
define('BLOCK_REGION_NONE', -1);

/**
 * Constants defining cache granularity for blocks.
 *
 * Modules specify the caching patterns for their blocks using binary
 * combinations of these constants in their hook_block(op 'list'):
 *   $block[delta]['cache'] = BLOCK_CACHE_PER_ROLE | BLOCK_CACHE_PER_PAGE;
 * BLOCK_CACHE_PER_ROLE is used as a default when no caching pattern is
 * specified.
 *
 * The block cache is cleared in cache_clear_all(), and uses the same clearing
 * policy than page cache (node, comment, user, taxonomy added or updated...).
 * Blocks requiring more fine-grained clearing might consider disabling the
 * built-in block cache (BLOCK_NO_CACHE) and roll their own.
 *
 * Note that user 1 is excluded from block caching.
 */

/**
 * The block should not get cached. This setting should be used:
 * - for simple blocks (notably those that do not perform any db query),
 * where querying the db cache would be more expensive than directly generating
 * the content.
 * - for blocks that change too frequently.
 */
define('BLOCK_NO_CACHE', -1);

/**
 * The block can change depending on the roles the user viewing the page belongs to.
 * This is the default setting, used when the block does not specify anything.
 */
define('BLOCK_CACHE_PER_ROLE', 0x1);

/**
 * The block can change depending on the user viewing the page.
 * This setting can be resource-consuming for sites with large number of users,
 * and thus should only be used when BLOCK_CACHE_PER_ROLE is not sufficient.
 */
define('BLOCK_CACHE_PER_USER', 0x2);

/**
 * The block can change depending on the page being viewed.
 */
define('BLOCK_CACHE_PER_PAGE', 0x4);

/**
 * The block is the same for every user on every page where it is visible.
 */
define('BLOCK_CACHE_GLOBAL', 0x8);

/**
 * Implementation of hook_help().
 */
function block_help($path, $arg) {
  switch ($path) {
    case 'admin/help#block':
      $output = '<p>' . t('Blocks are boxes of content rendered into an area, or region, of a web page. The default theme Garland, for example, implements the regions "left sidebar", "right sidebar", "content", "header", and "footer", and a block may appear in any one of these areas. The <a href="@blocks">blocks administration page</a> provides a drag-and-drop interface for assigning a block to a region, and for controlling the order of blocks within regions.', array(
        '@blocks' => url('admin/build/block'),
      )) . '</p>';
      $output .= '<p>' . t('Although blocks are usually generated automatically by modules (like the <em>User login</em> block, for example), administrators can also define custom blocks. Custom blocks have a title, description, and body. The body of the block can be as long as necessary, and can contain content supported by any available <a href="@input-format">input format</a>.', array(
        '@input-format' => url('admin/settings/filters'),
      )) . '</p>';
      $output .= '<p>' . t('When working with blocks, remember that:') . '</p>';
      $output .= '<ul><li>' . t('since not all themes implement the same regions, or display regions in the same way, blocks are positioned on a per-theme basis.') . '</li>';
      $output .= '<li>' . t('disabled blocks, or blocks not in a region, are never shown.') . '</li>';
      $output .= '<li>' . t('when throttle module is enabled, throttled blocks (blocks with the <em>Throttle</em> checkbox selected) are hidden during high server loads.') . '</li>';
      $output .= '<li>' . t('blocks can be configured to be visible only on certain pages.') . '</li>';
      $output .= '<li>' . t('blocks can be configured to be visible only when specific conditions are true.') . '</li>';
      $output .= '<li>' . t('blocks can be configured to be visible only for certain user roles.') . '</li>';
      $output .= '<li>' . t('when allowed by an administrator, specific blocks may be enabled or disabled on a per-user basis using the <em>My account</em> page.') . '</li>';
      $output .= '<li>' . t('some dynamic blocks, such as those generated by modules, will be displayed only on certain pages.') . '</li></ul>';
      $output .= '<p>' . t('For more information, see the online handbook entry for <a href="@block">Block module</a>.', array(
        '@block' => 'http://drupal.org/handbook/modules/block/',
      )) . '</p>';
      return $output;
    case 'admin/build/block':
      $throttle = module_exists('throttle');
      $output = '<p>' . t('This page provides a drag-and-drop interface for assigning a block to a region, and for controlling the order of blocks within regions. To change the region or order of a block, grab a drag-and-drop handle under the <em>Block</em> column and drag the block to a new location in the list. (Grab a handle by clicking and holding the mouse while hovering over a handle icon.) Since not all themes implement the same regions, or display regions in the same way, blocks are positioned on a per-theme basis. Remember that your changes will not be saved until you click the <em>Save blocks</em> button at the bottom of the page.') . '</p>';
      if ($throttle) {
        $output .= '<p>' . t('To reduce CPU usage, database traffic or bandwidth, blocks may be automatically disabled during high server loads by selecting their <em>Throttle</em> checkbox. Adjust throttle thresholds on the <a href="@throttleconfig">throttle configuration page</a>.', array(
          '@throttleconfig' => url('admin/settings/throttle'),
        )) . '</p>';
      }
      $output .= '<p>' . t('Click the <em>configure</em> link next to each block to configure its specific title and visibility settings. Use the <a href="@add-block">add block page</a> to create a custom block.', array(
        '@add-block' => url('admin/build/block/add'),
      )) . '</p>';
      return $output;
    case 'admin/build/block/add':
      return '<p>' . t('Use this page to create a new custom block. New blocks are disabled by default, and must be moved to a region on the <a href="@blocks">blocks administration page</a> to be visible.', array(
        '@blocks' => url('admin/build/block'),
      )) . '</p>';
  }
}

/**
 * Implementation of hook_theme()
 */
function block_theme() {
  return array(
    'block_admin_display_form' => array(
      'template' => 'block-admin-display-form',
      'file' => 'block.admin.inc',
      'arguments' => array(
        'form' => NULL,
      ),
    ),
  );
}

/**
 * Implementation of hook_perm().
 */
function block_perm() {
  return array(
    'administer blocks',
    'use PHP for block visibility',
  );
}

/**
 * Implementation of hook_menu().
 */
function block_menu() {
  $items['admin/build/block'] = array(
    'title' => 'Blocks',
    'description' => 'Configure what block content appears in your site\'s sidebars and other regions.',
    'page callback' => 'block_admin_display',
    'access arguments' => array(
      'administer blocks',
    ),
    'file' => 'block.admin.inc',
  );
  $items['admin/build/block/list'] = array(
    'title' => 'List',
    'type' => MENU_DEFAULT_LOCAL_TASK,
    'weight' => -10,
  );
  $items['admin/build/block/list/js'] = array(
    'title' => 'JavaScript List Form',
    'page callback' => 'block_admin_display_js',
    'access arguments' => array(
      'administer blocks',
    ),
    'type' => MENU_CALLBACK,
    'file' => 'block.admin.inc',
  );
  $items['admin/build/block/configure'] = array(
    'title' => 'Configure block',
    'page callback' => 'drupal_get_form',
    'page arguments' => array(
      'block_admin_configure',
    ),
    'access arguments' => array(
      'administer blocks',
    ),
    'type' => MENU_CALLBACK,
    'file' => 'block.admin.inc',
  );
  $items['admin/build/block/delete'] = array(
    'title' => 'Delete block',
    'page callback' => 'drupal_get_form',
    'page arguments' => array(
      'block_box_delete',
    ),
    'access arguments' => array(
      'administer blocks',
    ),
    'type' => MENU_CALLBACK,
    'file' => 'block.admin.inc',
  );
  $items['admin/build/block/add'] = array(
    'title' => 'Add block',
    'page callback' => 'drupal_get_form',
    'page arguments' => array(
      'block_add_block_form',
    ),
    'access arguments' => array(
      'administer blocks',
    ),
    'type' => MENU_LOCAL_TASK,
    'file' => 'block.admin.inc',
  );
  $default = variable_get('theme_default', 'garland');
  foreach (list_themes() as $key => $theme) {
    $items['admin/build/block/list/' . $key] = array(
      'title' => check_plain($theme->info['name']),
      'page arguments' => array(
        $key,
      ),
      'type' => $key == $default ? MENU_DEFAULT_LOCAL_TASK : MENU_LOCAL_TASK,
      'weight' => $key == $default ? -10 : 0,
      'file' => 'block.admin.inc',
      'access callback' => '_block_themes_access',
      'access arguments' => array(
        $theme,
      ),
    );
  }
  return $items;
}

/**
 * Menu item access callback - only admin or enabled themes can be accessed
 */
function _block_themes_access($theme) {
  return user_access('administer blocks') && ($theme->status || $theme->name == variable_get('admin_theme', '0'));
}

/**
 * Implementation of hook_block().
 *
 * Generates the administrator-defined blocks for display.
 */
function block_block($op = 'list', $delta = 0, $edit = array()) {
  switch ($op) {
    case 'list':
      $blocks = array();
      $result = db_query('SELECT bid, info FROM {boxes} ORDER BY info');
      while ($block = db_fetch_object($result)) {
        $blocks[$block->bid]['info'] = $block->info;

        // Not worth caching.
        $blocks[$block->bid]['cache'] = BLOCK_NO_CACHE;
      }
      return $blocks;
    case 'configure':
      $box = array(
        'format' => FILTER_FORMAT_DEFAULT,
      );
      if ($delta) {
        $box = block_box_get($delta);
      }
      if (filter_access($box['format'])) {
        return block_box_form($box);
      }
      break;
    case 'save':
      block_box_save($edit, $delta);
      break;
    case 'view':
      $block = db_fetch_object(db_query('SELECT body, format FROM {boxes} WHERE bid = %d', $delta));
      $data['content'] = check_markup($block->body, $block->format, FALSE);
      return $data;
  }
}

/**
 * Update the 'blocks' DB table with the blocks currently exported by modules.
 *
 * @param $theme
 *   The theme to rehash blocks for. If not provided, defaults to the currently
 *   used theme.
 *
 * @return
 *   Blocks currently exported by modules.
 */
function _block_rehash($theme = NULL) {
  global $theme_key;
  init_theme();
  if (!isset($theme)) {
    $theme = $theme_key;
  }
  $result = db_query("SELECT * FROM {blocks} WHERE theme = '%s'", $theme);
  $old_blocks = array();
  while ($old_block = db_fetch_array($result)) {
    $old_blocks[$old_block['module']][$old_block['delta']] = $old_block;
  }
  $blocks = array();

  // Valid region names for the theme.
  $regions = system_region_list($theme);
  foreach (module_list() as $module) {
    $module_blocks = module_invoke($module, 'block', 'list');
    if ($module_blocks) {
      foreach ($module_blocks as $delta => $block) {
        if (empty($old_blocks[$module][$delta])) {

          // If it's a new block, add identifiers.
          $block['module'] = $module;
          $block['delta'] = $delta;
          $block['theme'] = $theme;
          if (!isset($block['pages'])) {

            // {block}.pages is type 'text', so it cannot have a
            // default value, and not null, so we need to provide
            // value if the module did not.
            $block['pages'] = '';
          }

          // Add defaults and save it into the database.
          drupal_write_record('blocks', $block);

          // Set region to none if not enabled.
          $block['region'] = $block['status'] ? $block['region'] : BLOCK_REGION_NONE;

          // Add to the list of blocks we return.
          $blocks[] = $block;
        }
        else {

          // If it's an existing block, database settings should overwrite
          // the code. The only exceptions are 'cache' which is only definable
          // and updatable in the code, and 'info' which is not stored in
          // the database.
          // Update the cache mode only; the other values don't need to change.
          if (isset($block['cache']) && $block['cache'] != $old_blocks[$module][$delta]['cache']) {
            db_query("UPDATE {blocks} SET cache = %d WHERE bid = %d", $block['cache'], $old_blocks[$module][$delta]['bid']);
          }

          // Add 'info' to this block.
          $old_blocks[$module][$delta]['info'] = $block['info'];

          // If the region name does not exist, disable the block and assign it to none.
          if (!empty($old_blocks[$module][$delta]['region']) && !isset($regions[$old_blocks[$module][$delta]['region']])) {
            drupal_set_message(t('The block %info was assigned to the invalid region %region and has been disabled.', array(
              '%info' => $old_blocks[$module][$delta]['info'],
              '%region' => $old_blocks[$module][$delta]['region'],
            )), 'warning');
            $old_blocks[$module][$delta]['status'] = 0;
            $old_blocks[$module][$delta]['region'] = BLOCK_REGION_NONE;
          }
          else {
            $old_blocks[$module][$delta]['region'] = $old_blocks[$module][$delta]['status'] ? $old_blocks[$module][$delta]['region'] : BLOCK_REGION_NONE;
          }

          // Add this block to the list of blocks we return.
          $blocks[] = $old_blocks[$module][$delta];

          // Remove this block from the list of blocks to be deleted.
          unset($old_blocks[$module][$delta]);
        }
      }
    }
  }

  // Remove blocks that are no longer defined by the code from the database.
  foreach ($old_blocks as $module => $old_module_blocks) {

    // This cleanup does not apply to disabled modules, to avoid configuration
    // being lost when modules are disabled.
    if (module_exists($module)) {
      foreach ($old_module_blocks as $delta => $block) {
        db_query("DELETE FROM {blocks} WHERE module = '%s' AND delta = '%s' AND theme = '%s'", $module, $delta, $theme);
      }
    }
  }
  return $blocks;
}

/**
 * Implementation of hook_flush_caches().
 */
function block_flush_caches() {

  // Rehash blocks for active themes. We don't use list_themes() here,
  // because if MAINTENANCE_MODE is defined it skips reading the database,
  // and we can't tell which themes are active.
  $result = db_query("SELECT name FROM {system} WHERE type = 'theme' AND status = 1");
  while ($theme = db_result($result)) {
    _block_rehash($theme);
  }
}

/**
 * Returns information from database about a user-created (custom) block.
 *
 * @param $bid
 *   ID of the block to get information for.
 * @return
 *   Associative array of information stored in the database for this block.
 *   Array keys:
 *   - bid: Block ID.
 *   - info: Block description.
 *   - body: Block contents.
 *   - format: Filter ID of the filter format for the body.
 */
function block_box_get($bid) {
  return db_fetch_array(db_query("SELECT * FROM {boxes} WHERE bid = %d", $bid));
}

/**
 * Define the custom block form.
 */
function block_box_form($edit = array()) {
  $edit += array(
    'info' => '',
    'body' => '',
  );
  $form['info'] = array(
    '#type' => 'textfield',
    '#title' => t('Block description'),
    '#default_value' => $edit['info'],
    '#maxlength' => 64,
    '#description' => t('A brief description of your block. Used on the <a href="@overview">block overview page</a>.', array(
      '@overview' => url('admin/build/block'),
    )),
    '#required' => TRUE,
    '#weight' => -19,
  );
  $form['body_field']['#weight'] = -17;
  $form['body_field']['body'] = array(
    '#type' => 'textarea',
    '#title' => t('Block body'),
    '#default_value' => $edit['body'],
    '#rows' => 15,
    '#description' => t('The content of the block as shown to the user.'),
    '#weight' => -17,
  );
  if (!isset($edit['format'])) {
    $edit['format'] = FILTER_FORMAT_DEFAULT;
  }
  $form['body_field']['format'] = filter_form($edit['format'], -16);
  return $form;
}

/**
 * Saves a user-created block in the database.
 *
 * @param $edit
 *   Associative array of fields to save. Array keys:
 *   - info: Block description.
 *   - body: Block contents.
 *   - format: Filter ID of the filter format for the body.
 * @param $delta
 *   Block ID of the block to save.
 * @return
 *   Always returns TRUE.
 */
function block_box_save($edit, $delta) {
  if (!filter_access($edit['format'])) {
    $edit['format'] = FILTER_FORMAT_DEFAULT;
  }
  db_query("UPDATE {boxes} SET body = '%s', info = '%s', format = %d WHERE bid = %d", $edit['body'], $edit['info'], $edit['format'], $delta);
  return TRUE;
}

/**
 * Implementation of hook_user().
 *
 * Allow users to decide which custom blocks to display when they visit
 * the site.
 */
function block_user($type, $edit, &$account, $category = NULL) {
  switch ($type) {
    case 'form':
      if ($category == 'account') {
        $rids = array_keys($account->roles);
        $result = db_query("SELECT DISTINCT b.* FROM {blocks} b LEFT JOIN {blocks_roles} r ON b.module = r.module AND b.delta = r.delta WHERE b.status = 1 AND b.custom != 0 AND (r.rid IN (" . db_placeholders($rids) . ") OR r.rid IS NULL) ORDER BY b.weight, b.module", $rids);
        $form['block'] = array(
          '#type' => 'fieldset',
          '#title' => t('Block configuration'),
          '#weight' => 3,
          '#collapsible' => TRUE,
          '#tree' => TRUE,
        );
        while ($block = db_fetch_object($result)) {
          $data = module_invoke($block->module, 'block', 'list');
          if ($data[$block->delta]['info']) {
            $return = TRUE;
            $form['block'][$block->module][$block->delta] = array(
              '#type' => 'checkbox',
              '#title' => check_plain($data[$block->delta]['info']),
              '#default_value' => isset($account->block[$block->module][$block->delta]) ? $account->block[$block->module][$block->delta] : $block->custom == 1,
            );
          }
        }
        if (!empty($return)) {
          return $form;
        }
      }
      break;
    case 'validate':
      if (empty($edit['block'])) {
        $edit['block'] = array();
      }
      return $edit;
  }
}

/**
 * Return all blocks in the specified region for the current user.
 *
 * @param $region
 *   The name of a region.
 *
 * @return
 *   An array of block objects, indexed with module name and block delta
 *   concatenated with an underscore, thus: MODULE_DELTA. If you are displaying
 *   your blocks in one or two sidebars, you may check whether this array is
 *   empty to see how many columns are going to be displayed.
 *
 * @todo
 *   Now that the blocks table has a primary key, we should use that as the
 *   array key instead of MODULE_DELTA.
 */
function block_list($region) {
  global $user, $theme_key;
  static $blocks = array();
  if (!count($blocks)) {
    $rids = array_keys($user->roles);
    $result = db_query(db_rewrite_sql("SELECT DISTINCT b.* FROM {blocks} b LEFT JOIN {blocks_roles} r ON b.module = r.module AND b.delta = r.delta WHERE b.theme = '%s' AND b.status = 1 AND (r.rid IN (" . db_placeholders($rids) . ") OR r.rid IS NULL) ORDER BY b.region, b.weight, b.module", 'b', 'bid'), array_merge(array(
      $theme_key,
    ), $rids));
    while ($block = db_fetch_object($result)) {
      if (!isset($blocks[$block->region])) {
        $blocks[$block->region] = array();
      }

      // Use the user's block visibility setting, if necessary
      if ($block->custom != 0) {
        if ($user->uid && isset($user->block[$block->module][$block->delta])) {
          $enabled = $user->block[$block->module][$block->delta];
        }
        else {
          $enabled = $block->custom == 1;
        }
      }
      else {
        $enabled = TRUE;
      }

      // Match path if necessary
      if ($block->pages) {
        if ($block->visibility < 2) {
          $path = drupal_get_path_alias($_GET['q']);

          // Compare with the internal and path alias (if any).
          $page_match = drupal_match_path($path, $block->pages);
          if ($path != $_GET['q']) {
            $page_match = $page_match || drupal_match_path($_GET['q'], $block->pages);
          }

          // When $block->visibility has a value of 0, the block is displayed on
          // all pages except those listed in $block->pages. When set to 1, it
          // is displayed only on those pages listed in $block->pages.
          $page_match = !($block->visibility xor $page_match);
        }
        else {
          $page_match = drupal_eval($block->pages);
        }
      }
      else {
        $page_match = TRUE;
      }
      $block->enabled = $enabled;
      $block->page_match = $page_match;
      $blocks[$block->region]["{$block->module}_{$block->delta}"] = $block;
    }
  }

  // Create an empty array if there were no entries
  if (!isset($blocks[$region])) {
    $blocks[$region] = array();
  }
  foreach ($blocks[$region] as $key => $block) {

    // Render the block content if it has not been created already.
    if (!isset($block->content)) {

      // Erase the block from the static array - we'll put it back if it has content.
      unset($blocks[$region][$key]);
      if ($block->enabled && $block->page_match) {

        // Check the current throttle status and see if block should be displayed
        // based on server load.
        if (!($block->throttle && module_invoke('throttle', 'status') > 0)) {

          // Try fetching the block from cache. Block caching is not compatible with
          // node_access modules. We also preserve the submission of forms in blocks,
          // by fetching from cache only if the request method is 'GET'.
          if (!count(module_implements('node_grants')) && $_SERVER['REQUEST_METHOD'] == 'GET' && ($cid = _block_get_cache_id($block)) && ($cache = cache_get($cid, 'cache_block'))) {
            $array = $cache->data;
          }
          else {
            $array = module_invoke($block->module, 'block', 'view', $block->delta);
            if (isset($cid)) {
              cache_set($cid, $array, 'cache_block', CACHE_TEMPORARY);
            }
          }
          if (isset($array) && is_array($array)) {
            foreach ($array as $k => $v) {
              $block->{$k} = $v;
            }
          }
        }
        if (isset($block->content) && $block->content) {

          // Override default block title if a custom display title is present.
          if ($block->title) {

            // Check plain here to allow module generated titles to keep any markup.
            $block->subject = $block->title == '<none>' ? '' : check_plain($block->title);
          }
          if (!isset($block->subject)) {
            $block->subject = '';
          }
          $blocks[$block->region]["{$block->module}_{$block->delta}"] = $block;
        }
      }
    }
  }
  return $blocks[$region];
}

/**
 * Assemble the cache_id to use for a given block.
 *
 * The cache_id string reflects the viewing context for the current block
 * instance, obtained by concatenating the relevant context information
 * (user, page, ...) according to the block's cache settings (BLOCK_CACHE_*
 * constants). Two block instances can use the same cached content when
 * they share the same cache_id.
 *
 * Theme and language contexts are automatically differenciated.
 *
 * @param $block
 * @return
 *   The string used as cache_id for the block.
 */
function _block_get_cache_id($block) {
  global $theme, $base_root, $user;

  // User 1 being out of the regular 'roles define permissions' schema,
  // it brings too many chances of having unwanted output get in the cache
  // and later be served to other users. We therefore exclude user 1 from
  // block caching.
  if (variable_get('block_cache', 0) && $block->cache != BLOCK_NO_CACHE && $user->uid != 1) {
    $cid_parts = array();

    // Start with common sub-patterns: block identification, theme, language.
    $cid_parts[] = $block->module;
    $cid_parts[] = $block->delta;
    $cid_parts[] = $theme;
    if (module_exists('locale')) {
      global $language;
      $cid_parts[] = $language->language;
    }

    // 'PER_ROLE' and 'PER_USER' are mutually exclusive. 'PER_USER' can be a
    // resource drag for sites with many users, so when a module is being
    // equivocal, we favor the less expensive 'PER_ROLE' pattern.
    if ($block->cache & BLOCK_CACHE_PER_ROLE) {
      $cid_parts[] = 'r.' . implode(',', array_keys($user->roles));
    }
    elseif ($block->cache & BLOCK_CACHE_PER_USER) {
      $cid_parts[] = "u.{$user->uid}";
    }
    if ($block->cache & BLOCK_CACHE_PER_PAGE) {
      $cid_parts[] = $base_root . request_uri();
    }
    return implode(':', $cid_parts);
  }
}