block.module

<?php
// $Id$

/**
 * @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_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', 0x0001);

/**
 * 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', 0x0002);

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

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

/**
 * 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="@text-format">text format</a>.', array('@text-format' => url('admin/settings/filter'))) . '</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('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':
      $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>';
      $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' => array(
      'arguments' => array('block' => NULL),
      'template' => 'block',
    ),
    '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' => array(
      'title' => t('Administer blocks'),
      'description' => t('Select which blocks are displayed, and arrange them on the page.'),
    ),
  );
}

/**
 * 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'),
  );
  $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,
  );
  $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,
  );
  $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,
  );
  $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,
  );
  $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,
      '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_list().
 */
function block_block_list() {
  $blocks = array();

  $result = db_query('SELECT bid, info FROM {box} 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;
}

/**
 * Implementation of hook_block_configure().
 */
function block_block_configure($delta = 0, $edit = array()) {
  $box = array('format' => FILTER_FORMAT_DEFAULT);
  if ($delta) {
    $box = block_box_get($delta);
  }
  return block_box_form($box);
}

/**
 * Implementation of hook_block_save().
 */
function block_block_save($delta = 0, $edit = array()) {
  block_box_save($edit, $delta);
}

/**
 * Implementation of hook_block_view().
 *
 * Generates the administrator-defined blocks for display.
 */
function block_block_view($delta = 0, $edit = array()) {
  $block = db_fetch_object(db_query('SELECT body, format FROM {box} WHERE bid = %d', $delta));
  $data['content'] = check_markup($block->body, $block->format, '', FALSE);
  return $data;
}

/**
 * Implementation of hook_page_alter().
 *
 * Render blocks into their regions.
 */
function block_page_alter($page) {
  global $theme;

  // The theme system might not yet be initialized. We need $theme.
  init_theme();

  // Populate all block regions
  $regions = system_region_list($theme);

  // Load all region content assigned via blocks.
  foreach (array_keys($regions) as $region) {
    // Prevent left and right regions from rendering blocks when 'show_blocks' == FALSE.
    if (!empty($page['#show_blocks']) || ($region != 'left' && $region != 'right')) {
      // Assign blocks to region.
      if ($blocks = block_get_blocks_by_region($region)) {
        $page[$region]['blocks'] = $blocks;
      }

      // Append region description if we are rendering the block admin page.
      $item = menu_get_item();
      if ($item['path'] == 'admin/build/block') {
        $description = '<div class="block-region">' . $regions[$region] . '</div>';
        $page[$region]['blocks']['block_description'] = array('#markup' => $description);
      }
    }
  }
}

/**
 * Get a renderable array of a region containing all enabled blocks.
 *
 * @param $region
 *   The requested region.
 */
function block_get_blocks_by_region($region) {
  $weight = 0;
  $build = array();
  if ($list = block_list($region)) {
    foreach ($list as $key => $block) {
      $build[$key] = array(
        '#theme' => 'block',
        '#block' => $block,
        '#weight' => ++$weight,
      );
    }
    $build['#sorted'] = TRUE;
  }
  return $build;
}

/**
 * Update the 'block' DB table with the blocks currently exported by modules.
 *
 * @return
 *   Blocks currently exported by modules.
 */
function _block_rehash() {
  global $theme_key;

  init_theme();

  $result = db_query("SELECT * FROM {block} WHERE theme = '%s'", $theme_key);
  $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_key);

  foreach (module_implements('block_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_key;
          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('block', $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. But aside from 'info' everything that's definable in
          // code is stored in the database and we do not store 'info', so we
          // do not need to update the database here.
          // 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) {
    foreach ($old_module_blocks as $delta => $block) {
      db_query("DELETE FROM {block} WHERE module = '%s' AND delta = '%s' AND theme = '%s'", $module, $delta, $theme_key);
    }
  }
  return $blocks;
}

function block_box_get($bid) {
  return db_fetch_array(db_query("SELECT * FROM {box} 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'],
    '#text_format' => isset($edit['format']) ? $edit['format'] : FILTER_FORMAT_DEFAULT,
    '#rows' => 15,
    '#description' => t('The content of the block as shown to the user.'),
    '#required' => TRUE,
    '#weight' => -17,
    '#access' => filter_access($edit['format']),
  );

  return $form;
}

function block_box_save($edit, $delta) {
  db_query("UPDATE {box} SET body = '%s', info = '%s', format = %d WHERE bid = %d", $edit['body'], $edit['info'], $edit['body_format'], $delta);

  return TRUE;
}

/**
 * Implementation of hook_user_form().
 */
function block_user_form(&$edit, &$account, $category = NULL) {
  if ($category == 'account') {
    $rids = array_keys($account->roles);
    $result = db_query("SELECT DISTINCT b.* FROM {block} b LEFT JOIN {block_role} r ON b.module = r.module AND b.delta = r.delta WHERE b.status = 1 AND b.custom <> 0 AND (r.rid IN (:rids) OR r.rid IS NULL) ORDER BY b.weight, b.module", array(':rids' => $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;
    }
  }
}

/**
 * Implementation of hook_user_validate().
 */
function block_user_validate(&$edit, &$account, $category = NULL) {
  if (empty($edit['block'])) {
    $edit['block'] = array();
  }
  return $edit;
}

/**
 * Implementation of hook_form_FORM_ID_alter().
 */
function block_form_system_performance_settings_alter(&$form, &$form_state) {

  // Add the block cache fieldset on the performance settings page.
  $form['block_cache'] = array(
    '#type' => 'fieldset',
    '#title' => t('Block cache'),
    '#description' => t('Enabling the block cache can offer a performance increase for all users by preventing blocks from being reconstructed on each page load. If the page cache is also enabled, performance increases from enabling the block cache will mainly benefit authenticated users.'),
    '#weight' => 0,
  );

  $form['block_cache']['block_cache'] = array(
    '#type' => 'radios',
    '#title' => t('Block cache'),
    '#default_value' => variable_get('block_cache', CACHE_DISABLED),
    '#options' => array(CACHE_DISABLED => t('Disabled'), CACHE_NORMAL => t('Enabled (recommended)')),
    '#disabled' => count(module_implements('node_grants')),
    '#description' => t('Note that block caching is inactive when modules defining content access restrictions are enabled.'),
  );

  // Check if the "Who's online" block is enabled.
  $online_block_enabled = db_select('block')
    ->condition('module', 'user')
    ->condition('delta', 'online')
    ->condition('status', 1)
    ->countQuery()
    ->execute()
    ->fetchField();

  // If the "Who's online" block is enabled, append some descriptive text to
  // the end of the form description.
  if ($online_block_enabled) {
    $form['page_cache']['cache']['#description'] .=  '<p>' . t('When caching is enabled, anonymous user sessions are only saved to the database when needed, so the "Who\'s online" block does not display the number of anonymous users.') . '</p>';
  }

}

/**
 * Implementation of hook_form_FORM_ID_alter().
 */
function block_form_system_themes_form_alter(&$form, &$form_state) {
  $form['#submit'][] = 'block_system_themes_form_submit';
}

/**
 * Initialize blocks for enabled themes.
 */
function block_system_themes_form_submit(&$form, &$form_state) {
  if ($form_state['values']['op'] == t('Save configuration')) {
    if (is_array($form_state['values']['status'])) {
      foreach ($form_state['values']['status'] as $key => $choice) {
        if ($choice || $form_state['values']['theme_default'] == $key) {
          block_initialize_theme_blocks($key);
        }
      }
    }
    if ($form_state['values']['admin_theme'] && $form_state['values']['admin_theme'] != variable_get('admin_theme', 0)) {
      // If we're changing themes, make sure the theme has its blocks initialized.
      $has_blocks = (bool) db_query_range('SELECT 1 FROM {block} WHERE theme = :theme', array(':theme' => $form_state['values']['admin_theme']), 0, 1)->fetchField();
      if (!$has_blocks) {
        block_initialize_theme_blocks($form_state['values']['admin_theme']);
      }
    }
  }
}

/**
 * Assign an initial, default set of blocks for a theme.
 *
 * This function is called the first time a new theme is enabled. The new theme
 * gets a copy of the default theme's blocks, with the difference that if a
 * particular region isn't available in the new theme, the block is assigned
 * to the new theme's default region.
 *
 * @param $theme
 *   The name of a theme.
 */
function block_initialize_theme_blocks($theme) {
  // Initialize theme's blocks if none already registered.
  $has_blocks = (bool) db_query_range('SELECT 1 FROM {block} WHERE theme = :theme', array(':theme' => $theme), 0, 1)->fetchField();
  if (!$has_blocks) {
    $default_theme = variable_get('theme_default', 'garland');
    $regions = system_region_list($theme);
    $result = db_query("SELECT * FROM {block} WHERE theme = '%s'", $default_theme);
    while ($block = db_fetch_array($result)) {
      // If the region isn't supported by the theme, assign the block to the theme's default region.
      if (!array_key_exists($block['region'], $regions)) {
        $block['region'] = system_default_region($theme);
      }
      db_query("INSERT INTO {block} (module, delta, theme, status, weight, region, visibility, pages, custom, cache) VALUES ('%s', '%s', '%s', %d, %d, '%s', %d, '%s', %d, %d)",
          $block['module'], $block['delta'], $theme, $block['status'], $block['weight'], $block['region'], $block['visibility'], $block['pages'], $block['custom'], $block['cache']);
    }
  }
}

/**
 * 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 <i>module</i>_<i>delta</i>.
 *   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 <i>module</i>_<i>delta</i>.
 */
function block_list($region) {
  static $blocks = array();

  if (!count($blocks)) {
    $blocks = _block_load_blocks();
  }

  // Create an empty array if there were no entries.
  if (!isset($blocks[$region])) {
    $blocks[$region] = array();
  }

  $blocks[$region] = _block_render_blocks($blocks[$region]);

  return $blocks[$region];
}

/**
 * Load blocks information from the database.
 */
function _block_load_blocks() {
  global $user, $theme_key;

  $blocks = array();
  $rids = array_keys($user->roles);
  $result = db_query(db_rewrite_sql("SELECT DISTINCT b.* FROM {block} b LEFT JOIN {block_role} 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);
      }
      elseif (module_exists('php')) {
        $page_match = php_eval($block->pages);
      }
      else {
        $page_match = FALSE;
      }
    }
    else {
      $page_match = TRUE;
    }
    $block->enabled = $enabled;
    $block->page_match = $page_match;
    $blocks[$block->region]["{$block->module}_{$block->delta}"] = $block;
  }

  return $blocks;
}

/**
 * Render the content and subject for a set of blocks.
 *
 * @param $region_blocks
 *   An array of block objects such as returned for one region by _block_load_blocks().
 *
 * @return
 *   An array of visible blocks with subject and content rendered.
 */
function _block_render_blocks($region_blocks) {
  foreach ($region_blocks 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($region_blocks[$key]);
      if ($block->enabled && $block->page_match) {
        // 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' (or 'HEAD').
        if (!count(module_implements('node_grants')) && ($_SERVER['REQUEST_METHOD'] == 'GET' || $_SERVER['REQUEST_METHOD'] == 'HEAD') && ($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 = '';
          }
          $region_blocks["{$block->module}_{$block->delta}"] = $block;
        }
      }
    }
  }
  return $region_blocks;
}

/**
 * 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 differentiated.
 *
 * @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);
  }
}

/**
 * Implementation of hook_flush_caches().
 */
function block_flush_caches() {
  return array('cache_block');
}

/**
 * Process variables for block.tpl.php
 *
 * Prepare the values passed to the theme_block function to be passed
 * into a pluggable template engine. Uses block properties to generate a
 * series of template file suggestions. If none are found, the default
 * block.tpl.php is used.
 *
 * Most themes utilize their own copy of block.tpl.php. The default is located
 * inside "modules/block/block.tpl.php". Look in there for the full list of
 * variables.
 *
 * The $variables array contains the following arguments:
 * - $block
 *
 * @see block.tpl.php
 */
function template_preprocess_block(&$variables) {
  static $block_counter = array();
  $variables['block'] = $variables['block']['#block'];
  // All blocks get an independent counter for each region.
  if (!isset($block_counter[$variables['block']->region])) {
    $block_counter[$variables['block']->region] = 1;
  }
  // Same with zebra striping.
  $variables['block_zebra'] = ($block_counter[$variables['block']->region] % 2) ? 'odd' : 'even';
  $variables['block_id'] = $block_counter[$variables['block']->region]++;

  if (is_array($variables['block']->content)) {
    // Render the block contents if it is not already rendered.
    $variables['block']->content = drupal_render($variables['block']->content);
  }

  $variables['template_files'][] = 'block-' . $variables['block']->region;
  $variables['template_files'][] = 'block-' . $variables['block']->module;
  $variables['template_files'][] = 'block-' . $variables['block']->module . '-' . $variables['block']->delta;
}