drupal/core/modules/block/block.module

644 lines
23 KiB
Plaintext

<?php
/**
* @file
* Controls the visual building blocks a page is constructed with.
*/
use Drupal\Component\Plugin\Exception\PluginException;
use Drupal\Component\Utility\NestedArray;
/**
* Denotes that a block is not enabled in any region and should not be shown.
*/
const BLOCK_REGION_NONE = -1;
/**
* Shows this block on every page except the listed pages.
*/
const BLOCK_VISIBILITY_NOTLISTED = 0;
/**
* Shows this block on only the listed pages.
*/
const BLOCK_VISIBILITY_LISTED = 1;
/**
* Shows this block if the associated PHP code returns TRUE.
*/
const BLOCK_VISIBILITY_PHP = 2;
/**
* Implements hook_help().
*/
function block_help($path, $arg) {
switch ($path) {
case 'admin/help#block':
$output = '';
$output .= '<h3>' . t('About') . '</h3>';
$output .= '<p>' . t('The Block module allows you to create boxes of content, which are rendered into an area, or region, of one or more pages of a website. The core Seven administration theme, for example, implements the regions "Content" and "Help", and a block may appear in either of these regions. 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. For more information, see the online handbook entry for <a href="@block">Block module</a>.', array('@block' => 'http://drupal.org/documentation/modules/block', '@blocks' => url('admin/structure/block'))) . '</p>';
$output .= '<h3>' . t('Uses') . '</h3>';
$output .= '<dl>';
$output .= '<dt>' . t('Positioning content') . '</dt>';
$output .= '<dd>' . t('When working with blocks, remember that all themes do <em>not</em> implement the same regions, or display regions in the same way. Blocks are positioned on a per-theme basis. Users with the <em>Administer blocks</em> permission can disable blocks. Disabled blocks are listed on the <a href="@blocks">Blocks administration page</a>, but are not displayed in any region.', array('@block' => 'http://drupal.org/documentation/modules/block', '@blocks' => url('admin/structure/block'))) . '</dd>';
$output .= '<dt>' . t('Controlling visibility') . '</dt>';
$output .= '<dd>' . t('Blocks can be configured to be visible only on certain pages, only to users of certain roles, or only on pages displaying certain <a href="@content-type">content types</a>. Some dynamic blocks, such as those generated by modules, will be displayed only on certain pages.', array('@content-type' => url('admin/structure/types'), '@user' => url('user'))) . '</dd>';
if (module_exists('custom_block')) {
$output .= '<dt>' . t('Creating custom blocks') . '</dt>';
$output .= '<dd>' . t('Users with the <em>Administer blocks</em> permission can add custom blocks, which are then listed on the <a href="@blocks">Blocks administration page</a>. Once created, custom blocks behave just like default and module-generated blocks.', array('@blocks' => url('admin/structure/block'))) . '</dd>';
}
$output .= '</dl>';
return $output;
}
if ($arg[0] == 'admin' && $arg[1] == 'structure' && $arg['2'] == 'block' && (empty($arg[3]) || $arg[3] == 'list') && empty($arg[5])) {
if (!empty($arg[4])) {
$demo_theme = $arg[4];
}
else {
$demo_theme = Drupal::config('system.theme')->get('default');
}
$themes = list_themes();
$output = '<p>' . t('This page provides a drag-and-drop interface for adding a block to a region, and for controlling the order of blocks within regions. To add a block to a region, or to configure its specific title and visibility settings, click the block title under <em>Place blocks</em>. 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>' . l(t('Demonstrate block regions (@theme)', array('@theme' => $themes[$demo_theme]->info['name'])), 'admin/structure/block/demo/' . $demo_theme) . '</p>';
return $output;
}
}
/**
* Implements hook_theme().
*/
function block_theme() {
return array(
'block' => array(
'render element' => 'elements',
'template' => 'block',
),
'block_list' => array(
'render element' => 'form',
'template' => 'block-list',
),
);
}
/**
* Implements hook_permission().
*/
function block_permission() {
return array(
'administer blocks' => array(
'title' => t('Administer blocks'),
),
);
}
/**
* Implements hook_menu().
*
* @todo Clarify the documentation for the per-plugin block admin links.
*/
function block_menu() {
$default_theme = Drupal::config('system.theme')->get('default');
$items['admin/structure/block'] = array(
'title' => 'Block layout',
'description' => 'Configure what block content appears in your site\'s sidebars and other regions.',
'route_name' => 'block_admin_display',
);
$items['admin/structure/block/list'] = array(
'title' => 'Block layout',
'type' => MENU_DEFAULT_LOCAL_TASK,
);
$items['admin/structure/block/manage/%block'] = array(
'title' => 'Configure block',
'route_name' => 'block_admin_edit',
);
$items['admin/structure/block/manage/%block/configure'] = array(
'title' => 'Configure block',
'type' => MENU_DEFAULT_LOCAL_TASK,
'context' => MENU_CONTEXT_INLINE,
);
$items['admin/structure/block/manage/%block/delete'] = array(
'title' => 'Delete block',
'type' => MENU_LOCAL_TASK,
'context' => MENU_CONTEXT_NONE,
'route_name' => 'block_admin_block_delete',
);
$items['admin/structure/block/add/%/%'] = array(
'title' => 'Place block',
'type' => MENU_VISIBLE_IN_BREADCRUMB,
'route_name' => 'block_admin_add',
);
// Block administration is tied to the theme and plugin definition so
// that the plugin can appropriately attach to this URL structure.
// @todo D8: Use dynamic % arguments instead of static, hard-coded theme names
// and plugin IDs to decouple the routes from these dependencies and allow
// hook_menu_local_tasks() to check for the untranslated tab_parent path.
// @see http://drupal.org/node/1067408
foreach (list_themes() as $key => $theme) {
$items["admin/structure/block/list/$key"] = array(
'title' => check_plain($theme->info['name']),
'type' => $key == $default_theme ? MENU_DEFAULT_LOCAL_TASK : MENU_LOCAL_TASK,
'route_name' => "block_admin_display.$key",
);
$items["admin/structure/block/demo/$key"] = array(
'title' => check_plain($theme->info['name']),
'page callback' => 'block_admin_demo',
'page arguments' => array($key),
'type' => MENU_CALLBACK,
'access callback' => '_block_themes_access',
'access arguments' => array($key),
'theme callback' => '_block_custom_theme',
'theme arguments' => array($key),
'file' => 'block.admin.inc',
);
}
return $items;
}
/**
* Access callback: Only enabled themes can be accessed.
*
* Path:
* - admin/structure/block/list/% (for each theme)
* - admin/structure/block/demo/% (for each theme)
*
* @param $theme
* Either the name of a theme or a full theme object.
*
* @see block_menu()
*/
function _block_themes_access($theme) {
return user_access('administer blocks') && drupal_theme_access($theme);
}
/**
* Theme callback: Uses the theme specified in the parameter.
*
* @param $theme
* The theme whose blocks are being configured. If not set, the default theme
* is assumed.
*
* @return
* The theme that should be used for the block configuration page, or NULL
* to indicate that the default theme should be used.
*
* @see block_menu()
*/
function _block_custom_theme($theme = NULL) {
// We return exactly what was passed in, to guarantee that the page will
// always be displayed using the theme whose blocks are being configured.
return $theme;
}
/**
* Implements hook_page_build().
*
* Renders blocks into their regions.
*/
function block_page_build(&$page) {
global $theme;
// The theme system might not yet be initialized. We need $theme.
drupal_theme_initialize();
// Fetch a list of regions for the current theme.
$all_regions = system_region_list($theme);
$item = menu_get_item();
if ($item['path'] != 'admin/structure/block/demo/' . $theme) {
// Load all region content assigned via blocks.
foreach (array_keys($all_regions) as $region) {
// Assign blocks to region.
if ($blocks = block_get_blocks_by_region($region)) {
$page[$region] = $blocks;
}
}
// Once we've finished attaching all blocks to the page, clear the static
// cache to allow modules to alter the block list differently in different
// contexts. For example, any code that triggers hook_page_build() more
// than once in the same page request may need to alter the block list
// differently each time, so that only certain parts of the page are
// actually built. We do not clear the cache any earlier than this, though,
// because it is used each time block_get_blocks_by_region() gets called
// above.
drupal_static_reset('block_list');
}
else {
// Append region description if we are rendering the regions demo page.
$visible_regions = array_keys(system_region_list($theme, REGIONS_VISIBLE));
foreach ($visible_regions as $region) {
$description = '<div class="block-region">' . $all_regions[$region] . '</div>';
$page[$region]['block_description'] = array(
'#markup' => $description,
'#weight' => 15,
);
}
$page['page_top']['backlink'] = array(
'#type' => 'link',
'#title' => t('Exit block region demonstration'),
'#href' => 'admin/structure/block' . (Drupal::config('system.theme')->get('default') == $theme ? '' : '/list/' . $theme),
// Add the "overlay-restore" class to indicate this link should restore
// the context in which the region demonstration page was opened.
'#options' => array('attributes' => array('class' => array('block-demo-backlink', 'overlay-restore'))),
'#weight' => -10,
);
}
}
/**
* Gets a renderable array of a region containing all enabled blocks.
*
* @param $region
* The requested region.
*
* @return
* A renderable array of a region containing all enabled blocks.
*/
function block_get_blocks_by_region($region) {
$build = array();
if ($list = block_list($region)) {
$build = _block_get_renderable_region($list);
}
return $build;
}
/**
* Gets an array of blocks suitable for drupal_render().
*
* @param $list
* A list of blocks such as that returned by block_list().
*
* @return
* A renderable array.
*/
function _block_get_renderable_region($list = array()) {
$build = array();
// 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'). 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.
$not_cacheable = Drupal::currentUser()->id() == 1 ||
count(Drupal::moduleHandler()->getImplementations('node_grants')) ||
!Drupal::request()->isMethodSafe();
foreach ($list as $key => $block) {
$settings = $block->get('settings');
if ($not_cacheable || in_array($settings['cache'], array(DRUPAL_NO_CACHE, DRUPAL_CACHE_CUSTOM))) {
// Non-cached blocks get built immediately.
if ($block->access()) {
$build[$key] = entity_view($block, 'block');
}
}
else {
$key_components = explode('.', $key);
$id = array_pop($key_components);
$build[$key] = array(
'#block' => $block,
'#weight' => $block->get('weight'),
'#pre_render' => array('_block_get_renderable_block'),
'#cache' => array(
'keys' => array($id, $settings['module']),
'granularity' => $settings['cache'],
'bin' => 'block',
'tags' => array('content' => TRUE),
),
);
}
// Add contextual links for this block; skip the main content block, since
// contextual links are basically output as tabs/local tasks already. Also
// skip the help block, since we assume that most users do not need or want
// to perform contextual actions on the help block, and the links needlessly
// draw attention on it.
if (isset($build[$key]) && !in_array($block->get('plugin'), array('system_help_block', 'system_main_block'))) {
$build[$key]['#contextual_links']['block'] = array('admin/structure/block/manage', array($key));
// If there are any nested contextual links, move them to the top level.
if (isset($build[$key]['content']['#contextual_links'])) {
$build[$key]['#contextual_links'] += $build[$key]['content']['#contextual_links'];
unset($build[$key]['content']['#contextual_links']);
}
}
}
return $build;
}
/**
* Returns an array of block class instances by theme.
*
* @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) {
$theme = $theme ? $theme : Drupal::config('system.theme')->get('default');
$regions = system_region_list($theme);
$blocks = entity_load_multiple_by_properties('block', array('theme' => $theme));
foreach ($blocks as $block_id => $block) {
$region = $block->get('region');
$status = $block->status();
// Disable blocks in invalid regions.
if (!empty($region) && $region != BLOCK_REGION_NONE && !isset($regions[$region]) && $status) {
drupal_set_message(t('The block %info was assigned to the invalid region %region and has been disabled.', array('%info' => $block_id, '%region' => $region)), 'warning');
// Disabled modules are moved into the BLOCK_REGION_NONE later so no
// need to move the block to another region.
$block->disable()->save();
}
// Set region to none if not enabled.
if (!$status) {
$block->set('region', BLOCK_REGION_NONE);
$block->save();
}
}
return $blocks;
}
/**
* Initializes blocks for enabled themes.
*
* @param $theme_list
* An array of theme names.
*/
function block_themes_enabled($theme_list) {
foreach ($theme_list as $theme) {
block_theme_initialize($theme);
}
}
/**
* Assigns 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_theme_initialize($theme) {
// Initialize theme's blocks if none already registered.
$has_blocks = entity_load_multiple_by_properties('block', array('theme' => $theme));
if (!$has_blocks) {
$default_theme = Drupal::config('system.theme')->get('default');
// Apply only to new theme's visible regions.
$regions = system_region_list($theme, REGIONS_VISIBLE);
$default_theme_blocks = entity_load_multiple_by_properties('block', array('theme' => $default_theme));
foreach ($default_theme_blocks as $default_theme_block_id => $default_theme_block) {
list(, $machine_name) = explode('.', $default_theme_block_id);
$block = $default_theme_block->createDuplicate();
$block->set('id', $theme . '.' . $machine_name);
// If the region isn't supported by the theme, assign the block to the
// theme's default region.
if (!isset($regions[$block->get('region')])) {
$block->set('region', system_default_region($theme));
}
$block->save();
}
}
}
/**
* Returns 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 the configuration object name
* that represents the configuration. 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.
*/
function block_list($region) {
$blocks = &drupal_static(__FUNCTION__);
if (!isset($blocks)) {
global $theme;
$blocks = array();
foreach (entity_load_multiple_by_properties('block', array('theme' => $theme)) as $block_id => $block) {
$blocks[$block->get('region')][$block_id] = $block;
}
}
// Create an empty array if there are no entries.
if (!isset($blocks[$region])) {
$blocks[$region] = array();
}
uasort($blocks[$region], function($first, $second) {
return $first->weight === $second->weight ? 0 : ($first->weight < $second->weight ? -1 : 1);
});
return $blocks[$region];
}
/**
* Loads a block instance.
*
* This should only be used when entity_load() cannot be used directly.
*
* @param string $entity_id
* The block ID.
*
* @return \Drupal\block\Entity\Block
* The loaded block object.
*/
function block_load($entity_id) {
return entity_load('block', $entity_id);
}
/**
* Builds the content and label for a block.
*
* For cacheable blocks, this is called during #pre_render.
*
* @param $element
* A renderable array.
*
* @return
* A renderable array.
*/
function _block_get_renderable_block($element) {
$block = $element['#block'];
// Don't bother to build blocks that aren't accessible.
if ($element['#access'] = $block->access()) {
$element += entity_view($block, 'block');
}
return $element;
}
/**
* Implements hook_rebuild().
*/
function block_rebuild() {
foreach (list_themes() as $name => $data) {
if ($data->status) {
_block_rehash($name);
}
}
}
/**
* Prepares variables for block templates.
*
* Default template: block.html.twig.
*
* Prepares 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.html.twig is used.
*
* Most themes use their own copy of block.html.twig. The default is located
* inside "core/modules/block/templates/block.html.twig". Look in there for the
* full list of available variables.
*
* @param array $variables
* An associative array containing:
* - elements: An associative array containing the properties of the element.
* Properties used: #block, #configuration, #children, #plugin_id.
*/
function template_preprocess_block(&$variables) {
$block_counter = &drupal_static(__FUNCTION__, array());
$variables['configuration'] = $variables['elements']['#configuration'];
$variables['plugin_id'] = $variables['elements']['#plugin_id'];
$variables['label'] = !empty($variables['configuration']['label_display']) ? $variables['configuration']['label'] : '';
$variables['content'] = $variables['elements']['content'];
$variables['attributes']['class'][] = 'block';
$variables['attributes']['class'][] = drupal_html_class('block-' . $variables['configuration']['module']);
// The block template provides a wrapping element for the content. Render the
// #attributes of the content on this wrapping element rather than passing
// them through to the content's #theme function/template. This allows the
// content to not require a function/template at all, or if it does use one,
// to not require it to output an extra wrapping element.
if (isset($variables['content']['#attributes'])) {
$variables['content_attributes'] = NestedArray::mergeDeep($variables['content_attributes'], $variables['content']['#attributes']);
unset($variables['content']['#attributes']);
}
// Add default class for block content.
$variables['content_attributes']['class'][] = 'content';
$variables['theme_hook_suggestions'][] = 'block__' . $variables['configuration']['module'];
// Hyphens (-) and underscores (_) play a special role in theme suggestions.
// Theme suggestions should only contain underscores, because within
// drupal_find_theme_templates(), underscores are converted to hyphens to
// match template file names, and then converted back to underscores to match
// pre-processing and other function names. So if your theme suggestion
// contains a hyphen, it will end up as an underscore after this conversion,
// and your function names won't be recognized. So, we need to convert
// hyphens to underscores in block deltas for the theme suggestions.
// We can safely explode on : because we know the Block plugin type manager
// enforces that delimiter for all derivatives.
$parts = explode(':', $variables['plugin_id']);
$suggestion = 'block';
while ($part = array_shift($parts)) {
$variables['theme_hook_suggestions'][] = $suggestion .= '__' . strtr($part, '-', '_');
}
// Create a valid HTML ID and make sure it is unique.
if ($id = $variables['elements']['#block']->id()) {
$config_id = explode('.', $id);
$machine_name = array_pop($config_id);
$variables['attributes']['id'] = drupal_html_id('block-' . $machine_name);
$variables['theme_hook_suggestions'][] = 'block__' . $machine_name;
}
}
/**
* Implements hook_user_role_delete().
*
* Removes deleted role from blocks that use it.
*/
function block_user_role_delete($role) {
foreach (entity_load_multiple('block') as $block) {
$visibility = $block->get('visibility');
if (isset($visibility['roles']['roles'][$role->id()])) {
unset($visibility['roles']['roles'][$role->id()]);
$block->set('visibility', $visibility);
$block->save();
}
}
}
/**
* Implements hook_menu_delete().
*/
function block_menu_delete($menu) {
foreach (entity_load_multiple('block') as $block) {
if ($block->get('plugin') == 'system_menu_block:' . $menu->id()) {
$block->delete();
}
}
}
/**
* Implements hook_admin_paths().
*/
function block_admin_paths() {
$paths = array(
// Exclude the block demonstration page from admin (overlay) treatment.
// This allows us to present this page in its true form, full page.
'admin/structure/block/demo/*' => FALSE,
);
return $paths;
}
/**
* Implements hook_language_delete().
*
* Delete the potential block visibility settings of the deleted language.
*/
function block_language_delete($language) {
// Remove the block visibility settings for the deleted language.
foreach (entity_load_multiple('block') as $block) {
$visibility = $block->get('visibility');
if (isset($visibility['language']['langcodes'][$language->id])) {
unset($visibility['language']['langcodes'][$language->id]);
$block->set('visibility', $visibility);
$block->save();
}
}
}
/**
* Implements hook_library_info().
*/
function block_library_info() {
$libraries['drupal.block'] = array(
'title' => 'Block',
'version' => Drupal::VERSION,
'js' => array(
drupal_get_path('module', 'block') . '/block.js' => array(),
),
'dependencies' => array(
array('system', 'jquery'),
array('system', 'drupal'),
),
);
$libraries['drupal.block.admin'] = array(
'title' => 'Block admin',
'version' => Drupal::VERSION,
'js' => array(
drupal_get_path('module', 'block') . '/js/block.admin.js' => array(),
),
'css' => array(
drupal_get_path('module', 'block') . '/css/block.admin.css' => array(),
),
'dependencies' => array(
array('system', 'jquery'),
array('system', 'drupal'),
),
);
return $libraries;
}