block.module

<?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;

/**
 * Users cannot control whether or not they see this block.
 */
const BLOCK_CUSTOM_FIXED = 0;

/**
 *  Shows this block by default, but lets individual users hide it.
 */
const BLOCK_CUSTOM_ENABLED = 1;

/**
 * Hides this block by default but lets individual users show it.
 */
const BLOCK_CUSTOM_DISABLED = 2;

/**
 * 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;

/**
 * Indicates the block label (title) should be displayed to end users.
 */
const BLOCK_LABEL_VISIBLE = 'visible';

/**
 * 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 <a href="@block-add">add custom blocks</a>, 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'),
          '@block-add' => url('admin/structure/block/list/block_plugin_ui:' . config('system.theme')
            ->get('default') . '/add/custom_blocks'),
        )) . '</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])) {
      list(, $demo_theme) = explode(':', $arg[4]);
    }
    else {
      $demo_theme = config('system.theme')
        ->get('default');
    }
    $themes = list_themes();
    $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. 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. Click the <em>configure</em> link next to each block to configure its specific title and visibility settings.') . '</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',
    ),
  );
}

/**
 * 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 = config('system.theme')
    ->get('default');
  $items['admin/structure/block'] = array(
    'title' => 'Blocks',
    'description' => 'Configure what block content appears in your site\'s sidebars and other regions.',
    'page callback' => 'block_admin_display',
    'page arguments' => array(
      $default_theme,
    ),
    'access arguments' => array(
      'administer blocks',
    ),
    'file' => 'block.admin.inc',
  );
  $items['admin/structure/block/add/%/%'] = array(
    'title' => 'Configure block',
    'page callback' => 'block_admin_add',
    'page arguments' => array(
      4,
      5,
    ),
    'access arguments' => array(
      'administer blocks',
    ),
    'file' => 'block.admin.inc',
  );
  $items['admin/structure/block/manage/%block'] = array(
    'title' => 'Configure block',
    'page callback' => 'block_admin_edit',
    'page arguments' => array(
      4,
    ),
    'access arguments' => array(
      'administer blocks',
    ),
    'file' => 'block.admin.inc',
  );
  $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',
  );

  // 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
  $themes = list_themes();
  foreach (drupal_container()
    ->get('plugin.manager.system.plugin_ui')
    ->getDefinitions() as $plugin_id => $plugin) {
    list($plugin_base, $key) = explode(':', $plugin_id);
    if ($plugin_base == 'block_plugin_ui') {
      $theme = $themes[$key];
      $items['admin/structure/block/list/' . $plugin_id] = array(
        'title' => check_plain($theme->info['name']),
        'page arguments' => array(
          $key,
        ),
        'type' => $key == $default_theme ? MENU_DEFAULT_LOCAL_TASK : MENU_LOCAL_TASK,
        'access callback' => '_block_themes_access',
        'access arguments' => array(
          $key,
        ),
        'file' => 'block.admin.inc',
      );
      $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.
    $item = menu_get_item();
    if ($item['path'] == 'admin/structure/block/demo/' . $theme) {
      $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' . (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 = $GLOBALS['user']->uid == 1 || count(module_implements('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 : 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 = 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();
  }
  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\Plugin\Core\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_id => $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_id => $block) {
    if ($block
      ->get('plugin') == 'menu_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_id => $block) {
    $visibility = $block
      ->get('visibility');
    if (isset($visibility['language']['langcodes'][$language->langcode])) {
      unset($visibility['language']['langcodes'][$language->langcode]);
      $block
        ->set('visibility', $visibility);
      $block
        ->save();
    }
  }
}

/**
 * Implements hook_library_info().
 */
function block_library_info() {
  $libraries['drupal.block'] = array(
    'title' => 'Block',
    'version' => VERSION,
    'js' => array(
      drupal_get_path('module', 'block') . '/block.js' => array(),
    ),
    'dependencies' => array(
      array(
        'system',
        'jquery',
      ),
      array(
        'system',
        'drupal',
      ),
    ),
  );
  return $libraries;
}