www.aleph1.co.uk Git - yaffs-website/blob - web/core/modules/block/block.api.php

   1 <?php
   2
   3 /**
   4  * @file
   5  * Hooks provided by the Block module.
   6  */
   7
   8 use Drupal\Core\Access\AccessResult;
   9
  10 /**
  11  * @defgroup block_api Block API
  12  * @{
  13  * Information about the classes and interfaces that make up the Block API.
  14  *
  15  * Blocks are a combination of a configuration entity and a plugin. The
  16  * configuration entity stores placement information (theme, region, weight) and
  17  * any other configuration that is specific to the block. The block plugin does
  18  * the work of rendering the block's content for display.
  19  *
  20  * To define a block in a module you need to:
  21  * - Define a Block plugin by creating a new class that implements the
  22  *   \Drupal\Core\Block\BlockPluginInterface, in namespace Plugin\Block under your
  23  *   module namespace. For more information about creating plugins, see the
  24  *   @link plugin_api Plugin API topic. @endlink
  25  * - Usually you will want to extend the \Drupal\Core\Block\BlockBase class, which
  26  *   provides a common configuration form and utility methods for getting and
  27  *   setting configuration in the block configuration entity.
  28  * - Block plugins use the annotations defined by
  29  *   \Drupal\Core\Block\Annotation\Block. See the
  30  *   @link annotation Annotations topic @endlink for more information about
  31  *   annotations.
  32  *
  33  * The Block API also makes use of Condition plugins, for conditional block
  34  * placement. Condition plugins have interface
  35  * \Drupal\Core\Condition\ConditionInterface, base class
  36  * \Drupal\Core\Condition\ConditionPluginBase, and go in plugin namespace
  37  * Plugin\Condition. Again, see the Plugin API and Annotations topics for
  38  * details of how to create a plugin class and annotate it.
  39  *
  40  * There are also several block-related hooks, which allow you to affect
  41  * the content and access permissions for blocks:
  42  * - hook_block_view_alter()
  43  * - hook_block_view_BASE_BLOCK_ID_alter()
  44  * - hook_block_access()
  45  *
  46  * Further information and examples:
  47  * - \Drupal\system\Plugin\Block\SystemPoweredByBlock provides a simple example
  48  *   of defining a block.
  49  * - \Drupal\user\Plugin\Condition\UserRole is a straightforward example of a
  50  *   block placement condition plugin.
  51  * - \Drupal\book\Plugin\Block\BookNavigationBlock is an example of a block with
  52  *   a custom configuration form.
  53  * - For a more in-depth discussion of the Block API, see
  54  *   https://www.drupal.org/developing/api/8/block_api.
  55  * - The Examples for Developers project also provides a Block example in
  56  *   https://www.drupal.org/project/examples.
  57  * @}
  58  */
  59
  60 /**
  61  * @addtogroup hooks
  62  * @{
  63  */
  64
  65 /**
  66  * Alter the result of \Drupal\Core\Block\BlockBase::build().
  67  *
  68  * This hook is called after the content has been assembled in a structured
  69  * array and may be used for doing processing which requires that the complete
  70  * block content structure has been built.
  71  *
  72  * If the module wishes to act on the rendered HTML of the block rather than
  73  * the structured content array, it may use this hook to add a #post_render
  74  * callback. Alternatively, it could also implement hook_preprocess_HOOK() for
  75  * block.html.twig. See drupal_render() documentation or the
  76  * @link themeable Default theme implementations topic @endlink for details.
  77  *
  78  * In addition to hook_block_view_alter(), which is called for all blocks, there
  79  * is hook_block_view_BASE_BLOCK_ID_alter(), which can be used to target a
  80  * specific block or set of similar blocks.
  81  *
  82  * @param array &$build
  83  *   A renderable array of data, as returned from the build() implementation of
  84  *   the plugin that defined the block:
  85  *   - #title: The default localized title of the block.
  86  * @param \Drupal\Core\Block\BlockPluginInterface $block
  87  *   The block plugin instance.
  88  *
  89  * @see hook_block_view_BASE_BLOCK_ID_alter()
  90  * @see entity_crud
  91  *
  92  * @ingroup block_api
  93  */
  94 function hook_block_view_alter(array &$build, \Drupal\Core\Block\BlockPluginInterface $block) {
  95   // Remove the contextual links on all blocks that provide them.
  96   if (isset($build['#contextual_links'])) {
  97     unset($build['#contextual_links']);
  98   }
  99 }
 100
 101 /**
 102  * Provide a block plugin specific block_view alteration.
 103  *
 104  * In this hook name, BASE_BLOCK_ID refers to the block implementation's plugin
 105  * id, regardless of whether the plugin supports derivatives. For example, for
 106  * the \Drupal\system\Plugin\Block\SystemPoweredByBlock block, this would be
 107  * 'system_powered_by_block' as per that class's annotation. And for the
 108  * \Drupal\system\Plugin\Block\SystemMenuBlock block, it would be
 109  * 'system_menu_block' as per that class's annotation, regardless of which menu
 110  * the derived block is for.
 111  *
 112  * @param array $build
 113  *   A renderable array of data, as returned from the build() implementation of
 114  *   the plugin that defined the block:
 115  *   - #title: The default localized title of the block.
 116  * @param \Drupal\Core\Block\BlockPluginInterface $block
 117  *   The block plugin instance.
 118  *
 119  * @see hook_block_view_alter()
 120  * @see entity_crud
 121  *
 122  * @ingroup block_api
 123  */
 124 function hook_block_view_BASE_BLOCK_ID_alter(array &$build, \Drupal\Core\Block\BlockPluginInterface $block) {
 125   // Change the title of the specific block.
 126   $build['#title'] = t('New title of the block');
 127 }
 128
 129 /**
 130  * Alter the result of \Drupal\Core\Block\BlockBase::build().
 131  *
 132  * Unlike hook_block_view_alter(), this hook is called very early, before the
 133  * block is being assembled. Therefore, it is early enough to alter the
 134  * cacheability metadata (change #cache), or to explicitly placeholder the block
 135  * (set #create_placeholder).
 136  *
 137  * In addition to hook_block_build_alter(), which is called for all blocks,
 138  * there is hook_block_build_BASE_BLOCK_ID_alter(), which can be used to target
 139  * a specific block or set of similar blocks.
 140  *
 141  * @param array &$build
 142  *   A renderable array of data, only containing #cache.
 143  * @param \Drupal\Core\Block\BlockPluginInterface $block
 144  *   The block plugin instance.
 145  *
 146  * @see hook_block_build_BASE_BLOCK_ID_alter()
 147  * @see entity_crud
 148  *
 149  * @ingroup block_api
 150  */
 151 function hook_block_build_alter(array &$build, \Drupal\Core\Block\BlockPluginInterface $block) {
 152   // Add the 'user' cache context to some blocks.
 153   if ($block->label() === 'some condition') {
 154     $build['#cache']['contexts'][] = 'user';
 155   }
 156 }
 157
 158 /**
 159  * Provide a block plugin specific block_build alteration.
 160  *
 161  * In this hook name, BASE_BLOCK_ID refers to the block implementation's plugin
 162  * id, regardless of whether the plugin supports derivatives. For example, for
 163  * the \Drupal\system\Plugin\Block\SystemPoweredByBlock block, this would be
 164  * 'system_powered_by_block' as per that class's annotation. And for the
 165  * \Drupal\system\Plugin\Block\SystemMenuBlock block, it would be
 166  * 'system_menu_block' as per that class's annotation, regardless of which menu
 167  * the derived block is for.
 168  *
 169  * @param array $build
 170  *   A renderable array of data, only containing #cache.
 171  * @param \Drupal\Core\Block\BlockPluginInterface $block
 172  *   The block plugin instance.
 173  *
 174  * @see hook_block_build_alter()
 175  * @see entity_crud
 176  *
 177  * @ingroup block_api
 178  */
 179 function hook_block_build_BASE_BLOCK_ID_alter(array &$build, \Drupal\Core\Block\BlockPluginInterface $block) {
 180   // Explicitly enable placeholdering of the specific block.
 181   $build['#create_placeholder'] = TRUE;
 182 }
 183
 184 /**
 185  * Control access to a block instance.
 186  *
 187  * Modules may implement this hook if they want to have a say in whether or not
 188  * a given user has access to perform a given operation on a block instance.
 189  *
 190  * @param \Drupal\block\Entity\Block $block
 191  *   The block instance.
 192  * @param string $operation
 193  *   The operation to be performed; for instance, 'view', 'create', 'delete', or
 194  *   'update'.
 195  * @param \Drupal\Core\Session\AccountInterface $account
 196  *   The user object to perform the access check operation on.
 197  *
 198  * @return \Drupal\Core\Access\AccessResultInterface
 199  *   The access result. If all implementations of this hook return
 200  *   AccessResultInterface objects whose value is !isAllowed() and
 201  *   !isForbidden(), then default access rules from
 202  *   \Drupal\block\BlockAccessControlHandler::checkAccess() are used.
 203  *
 204  * @see \Drupal\Core\Entity\EntityAccessControlHandler::access()
 205  * @see \Drupal\block\BlockAccessControlHandler::checkAccess()
 206  * @ingroup block_api
 207  */
 208 function hook_block_access(\Drupal\block\Entity\Block $block, $operation, \Drupal\Core\Session\AccountInterface $account) {
 209   // Example code that would prevent displaying the 'Powered by Drupal' block in
 210   // a region different than the footer.
 211   if ($operation == 'view' && $block->getPluginId() == 'system_powered_by_block') {
 212     return AccessResult::forbiddenIf($block->getRegion() != 'footer')->addCacheableDependency($block);
 213   }
 214
 215   // No opinion.
 216   return AccessResult::neutral();
 217 }
 218
 219 /**
 220  * @} End of "addtogroup hooks".
 221  */