' . 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 blocks administration page 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'))) . '

'; $output .= '

' . t('Although blocks are usually generated automatically by modules (like the User login 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 input format.', array('@input-format' => url('admin/settings/filters'))) . '

'; $output .= '

' . t('When working with blocks, remember that:') . '

'; $output .= ''; $output .= '

' . t('For more information, see the online handbook entry for Block module.', array('@block' => 'http://drupal.org/handbook/modules/block/')) . '

'; return $output; case 'admin/build/block': $output = '

' . 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 Block 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 Save blocks button at the bottom of the page.') . '

'; $output .= '

' . t('Click the configure link next to each block to configure its specific title and visibility settings. Use the add block page to create a custom block.', array('@add-block' => url('admin/build/block/add'))) . '

'; return $output; case 'admin/build/block/add': return '

' . 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 blocks administration page to be visible.', array('@blocks' => url('admin/build/block'))) . '

'; } } /** * 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' => 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.'))), ), ); } /** * 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); } if (filter_access($box['format'])) { 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; } /** * 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 block overview page.', 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.'), '#weight' => -17, ); return $form; } function block_box_save($edit, $delta) { if (!filter_access($edit['body_format'])) { $edit['body_format'] = FILTER_FORMAT_DEFAULT; } 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; } /** * 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_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) { 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); } 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; } 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 == '' ? '' : 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); } }