Newer
Older
// $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.
*/
Dries Buytaert
committed
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);
/**
Gábor Hojtsy
committed
* 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);
/**
Gábor Hojtsy
committed
* 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);
/**
Gábor Hojtsy
committed
* 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);
Gábor Hojtsy
committed
function block_help($path, $arg) {
switch ($path) {
$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('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>';
Dries Buytaert
committed
return $output;
Dries Buytaert
committed
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;
Dries Buytaert
committed
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>';
Dries Buytaert
committed
/**
* Implementation of hook_theme().
Dries Buytaert
committed
*/
function block_theme() {
return array(
'block_admin_display_form' => array(
'template' => 'block-admin-display-form',
'file' => 'block.admin.inc',
Dries Buytaert
committed
'arguments' => array('form' => NULL),
),
);
}
return array(
Angie Byron
committed
'administer blocks' => array(
'title' => t('Administer blocks'),
'description' => t('Select which blocks are displayed, and arrange them on the page.'),
),
'use PHP for block visibility' => array(
'title' => t('Use PHP for block visibility'),
'description' => t('Enter PHP code in the field for block visibility settings. %warning', array('%warning' => t('Warning: Give to trusted roles only; this permission has security implications.'))),
),
);
Dries Buytaert
committed
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',
Dries Buytaert
committed
'access arguments' => array('administer blocks'),
);
$items['admin/build/block/list'] = array(
'title' => 'List',
Dries Buytaert
committed
'type' => MENU_DEFAULT_LOCAL_TASK,
'weight' => -10,
);
$items['admin/build/block/list/js'] = array(
'title' => 'JavaScript List Form',
'page callback' => 'block_admin_display_js',
Dries Buytaert
committed
'access arguments' => array('administer blocks'),
'type' => MENU_CALLBACK,
);
Dries Buytaert
committed
$items['admin/build/block/configure'] = array(
'title' => 'Configure block',
'page callback' => 'drupal_get_form',
Dries Buytaert
committed
'page arguments' => array('block_admin_configure'),
Dries Buytaert
committed
'access arguments' => array('administer blocks'),
Dries Buytaert
committed
'type' => MENU_CALLBACK,
);
$items['admin/build/block/delete'] = array(
'title' => 'Delete block',
'page callback' => 'drupal_get_form',
Dries Buytaert
committed
'page arguments' => array('block_box_delete'),
Dries Buytaert
committed
'access arguments' => array('administer blocks'),
Dries Buytaert
committed
'type' => MENU_CALLBACK,
);
$items['admin/build/block/add'] = array(
'title' => 'Add block',
'page callback' => 'drupal_get_form',
Dries Buytaert
committed
'page arguments' => array('block_add_block_form'),
Dries Buytaert
committed
'access arguments' => array('administer blocks'),
Dries Buytaert
committed
'type' => MENU_LOCAL_TASK,
);
$default = variable_get('theme_default', 'garland');
foreach (list_themes() as $key => $theme) {
$items['admin/build/block/list/' . $key] = array(
Gábor Hojtsy
committed
'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),
);
Gábor Hojtsy
committed
/**
* Menu item access callback - only admin or enabled themes can be accessed.
Gábor Hojtsy
committed
*/
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.
Steven Wittens
committed
* Blocks currently exported by modules.
Steven Wittens
committed
function _block_rehash() {
global $theme_key;
Dries Buytaert
committed
init_theme();
$result = db_query("SELECT * FROM {blocks} WHERE theme = '%s'", $theme_key);
Gábor Hojtsy
committed
$old_blocks = array();
while ($old_block = db_fetch_array($result)) {
$old_blocks[$old_block['module']][$old_block['delta']] = $old_block;
Dries Buytaert
committed
$blocks = array();
Gábor Hojtsy
committed
// Valid region names for the theme.
$regions = system_region_list($theme_key);
if ($module_blocks) {
foreach ($module_blocks as $delta => $block) {
Gábor Hojtsy
committed
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'] = '';
}
Gábor Hojtsy
committed
// Add defaults and save it into the database.
drupal_write_record('blocks', $block);
Dries Buytaert
committed
// Set region to none if not enabled.
$block['region'] = $block['status'] ? $block['region'] : BLOCK_REGION_NONE;
// Add to the list of blocks we return.
Gábor Hojtsy
committed
$blocks[] = $block;
Gábor Hojtsy
committed
// 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'];
Gábor Hojtsy
committed
// 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;
}
Dries Buytaert
committed
// Add this block to the list of blocks we return.
Gábor Hojtsy
committed
$blocks[] = $old_blocks[$module][$delta];
// Remove this block from the list of blocks to be deleted.
unset($old_blocks[$module][$delta]);
Gábor Hojtsy
committed
// 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 {blocks} WHERE module = '%s' AND delta = '%s' AND theme = '%s'", $module, $delta, $theme_key);
}
Dries Buytaert
committed
}
function block_box_get($bid) {
Dries Buytaert
committed
return db_fetch_array(db_query("SELECT * FROM {boxes} WHERE bid = %d", $bid));
/**
* Define the custom block form.
*/
function block_box_form($edit = array()) {
Steven Wittens
committed
$edit += array(
'info' => '',
'body' => '',
);
Dries Buytaert
committed
$form['info'] = array(
'#type' => 'textfield',
'#title' => t('Block description'),
'#default_value' => $edit['info'],
Dries Buytaert
committed
'#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'))),
Dries Buytaert
committed
'#required' => TRUE,
'#weight' => -19,
);
$form['body_field']['#weight'] = -17;
$form['body_field']['body'] = array(
Dries Buytaert
committed
'#type' => 'textarea',
'#title' => t('Block body'),
'#default_value' => $edit['body'],
Angie Byron
committed
'#input_format' => isset($edit['format']) ? $edit['format'] : FILTER_FORMAT_DEFAULT,
Dries Buytaert
committed
'#rows' => 15,
'#description' => t('The content of the block as shown to the user.'),
'#weight' => -17,
);
}
function block_box_save($edit, $delta) {
Angie Byron
committed
if (!filter_access($edit['body_format'])) {
$edit['body_format'] = FILTER_FORMAT_DEFAULT;
Angie Byron
committed
db_query("UPDATE {boxes} SET body = '%s', info = '%s', format = %d WHERE bid = %d", $edit['body'], $edit['info'], $edit['body_format'], $delta);
Dries Buytaert
committed
return TRUE;
}
Dries Buytaert
committed
* Implementation of hook_user_form().
Dries Buytaert
committed
function block_user_form(&$edit, &$account, $category = NULL) {
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));
Dries Buytaert
committed
}
Dries Buytaert
committed
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();
Dries Buytaert
committed
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 <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();
Dries Buytaert
committed
if (!count($blocks)) {
Dries Buytaert
committed
$blocks = _block_load_blocks();
}
// Create an empty array if there were no entries.
Dries Buytaert
committed
if (!isset($blocks[$region])) {
$blocks[$region] = array();
}
$blocks[$region] = _block_render_blocks($blocks[$region]);
return $blocks[$region];
}
/**
* Load blocks information from the database.
Dries Buytaert
committed
*/
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 {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));
Dries Buytaert
committed
while ($block = db_fetch_object($result)) {
if (!isset($blocks[$block->region])) {
$blocks[$block->region] = array();
}
// Use the user's block visibility setting, if necessary.
Dries Buytaert
committed
if ($block->custom != 0) {
if ($user->uid && isset($user->block[$block->module][$block->delta])) {
$enabled = $user->block[$block->module][$block->delta];
}
else {
Dries Buytaert
committed
$enabled = ($block->custom == 1);
Steven Wittens
committed
}
Dries Buytaert
committed
}
else {
$enabled = TRUE;
}
Steven Wittens
committed
// Match path if necessary.
Dries Buytaert
committed
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);
Dries Buytaert
committed
}
Dries Buytaert
committed
// 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);
Steven Wittens
committed
}
else {
Dries Buytaert
committed
$page_match = drupal_eval($block->pages);
Steven Wittens
committed
}
Dries Buytaert
committed
}
else {
$page_match = TRUE;
}
$block->enabled = $enabled;
$block->page_match = $page_match;
$blocks[$block->region]["{$block->module}_{$block->delta}"] = $block;
}
Dries Buytaert
committed
return $blocks;
}
Dries Buytaert
committed
Dries Buytaert
committed
/**
* 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().
Dries Buytaert
committed
*
* @return
Dries Buytaert
committed
* An array of visible blocks with subject and content rendered.
Dries Buytaert
committed
*/
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) {
Dries Buytaert
committed
// 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'))) {
Dries Buytaert
committed
$array = $cache->data;
}
else {
$array = module_invoke($block->module, 'block', 'view', $block->delta);
if (isset($cid)) {
cache_set($cid, $array, 'cache_block', CACHE_TEMPORARY);
Dries Buytaert
committed
}
Dries Buytaert
committed
if (isset($array) && is_array($array)) {
foreach ($array as $k => $v) {
$block->$k = $v;
Steven Wittens
committed
}
Dries Buytaert
committed
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);
}
Gábor Hojtsy
committed
if (!isset($block->subject)) {
$block->subject = '';
}
Dries Buytaert
committed
$region_blocks["{$block->module}_{$block->delta}"] = $block;
Dries Buytaert
committed
return $region_blocks;
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
/**
* 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);
}