Chris@0: <?php
Chris@0: 
Chris@0: /**
Chris@0:  * @file
Chris@0:  * Hooks provided by the Block module.
Chris@0:  */
Chris@0: 
Chris@0: use Drupal\Core\Access\AccessResult;
Chris@0: 
Chris@0: /**
Chris@0:  * @defgroup block_api Block API
Chris@0:  * @{
Chris@0:  * Information about the classes and interfaces that make up the Block API.
Chris@0:  *
Chris@0:  * Blocks are a combination of a configuration entity and a plugin. The
Chris@0:  * configuration entity stores placement information (theme, region, weight) and
Chris@0:  * any other configuration that is specific to the block. The block plugin does
Chris@0:  * the work of rendering the block's content for display.
Chris@0:  *
Chris@0:  * To define a block in a module you need to:
Chris@0:  * - Define a Block plugin by creating a new class that implements the
Chris@0:  *   \Drupal\Core\Block\BlockPluginInterface, in namespace Plugin\Block under your
Chris@0:  *   module namespace. For more information about creating plugins, see the
Chris@0:  *   @link plugin_api Plugin API topic. @endlink
Chris@0:  * - Usually you will want to extend the \Drupal\Core\Block\BlockBase class, which
Chris@0:  *   provides a common configuration form and utility methods for getting and
Chris@0:  *   setting configuration in the block configuration entity.
Chris@0:  * - Block plugins use the annotations defined by
Chris@0:  *   \Drupal\Core\Block\Annotation\Block. See the
Chris@0:  *   @link annotation Annotations topic @endlink for more information about
Chris@0:  *   annotations.
Chris@0:  *
Chris@0:  * The Block API also makes use of Condition plugins, for conditional block
Chris@0:  * placement. Condition plugins have interface
Chris@0:  * \Drupal\Core\Condition\ConditionInterface, base class
Chris@0:  * \Drupal\Core\Condition\ConditionPluginBase, and go in plugin namespace
Chris@0:  * Plugin\Condition. Again, see the Plugin API and Annotations topics for
Chris@0:  * details of how to create a plugin class and annotate it.
Chris@0:  *
Chris@0:  * There are also several block-related hooks, which allow you to affect
Chris@0:  * the content and access permissions for blocks:
Chris@0:  * - hook_block_view_alter()
Chris@0:  * - hook_block_view_BASE_BLOCK_ID_alter()
Chris@0:  * - hook_block_access()
Chris@0:  *
Chris@0:  * Further information and examples:
Chris@0:  * - \Drupal\system\Plugin\Block\SystemPoweredByBlock provides a simple example
Chris@0:  *   of defining a block.
Chris@0:  * - \Drupal\user\Plugin\Condition\UserRole is a straightforward example of a
Chris@0:  *   block placement condition plugin.
Chris@0:  * - \Drupal\book\Plugin\Block\BookNavigationBlock is an example of a block with
Chris@0:  *   a custom configuration form.
Chris@0:  * - For a more in-depth discussion of the Block API, see
Chris@0:  *   https://www.drupal.org/developing/api/8/block_api.
Chris@0:  * - The Examples for Developers project also provides a Block example in
Chris@0:  *   https://www.drupal.org/project/examples.
Chris@0:  * @}
Chris@0:  */
Chris@0: 
Chris@0: /**
Chris@0:  * @addtogroup hooks
Chris@0:  * @{
Chris@0:  */
Chris@0: 
Chris@0: /**
Chris@0:  * Alter the result of \Drupal\Core\Block\BlockBase::build().
Chris@0:  *
Chris@0:  * This hook is called after the content has been assembled in a structured
Chris@0:  * array and may be used for doing processing which requires that the complete
Chris@0:  * block content structure has been built.
Chris@0:  *
Chris@0:  * If the module wishes to act on the rendered HTML of the block rather than
Chris@0:  * the structured content array, it may use this hook to add a #post_render
Chris@0:  * callback. Alternatively, it could also implement hook_preprocess_HOOK() for
Chris@0:  * block.html.twig. See drupal_render() documentation or the
Chris@0:  * @link themeable Default theme implementations topic @endlink for details.
Chris@0:  *
Chris@0:  * In addition to hook_block_view_alter(), which is called for all blocks, there
Chris@0:  * is hook_block_view_BASE_BLOCK_ID_alter(), which can be used to target a
Chris@0:  * specific block or set of similar blocks.
Chris@0:  *
Chris@0:  * @param array &$build
Chris@0:  *   A renderable array of data, as returned from the build() implementation of
Chris@0:  *   the plugin that defined the block:
Chris@0:  *   - #title: The default localized title of the block.
Chris@0:  * @param \Drupal\Core\Block\BlockPluginInterface $block
Chris@0:  *   The block plugin instance.
Chris@0:  *
Chris@0:  * @see hook_block_view_BASE_BLOCK_ID_alter()
Chris@0:  * @see entity_crud
Chris@0:  *
Chris@0:  * @ingroup block_api
Chris@0:  */
Chris@0: function hook_block_view_alter(array &$build, \Drupal\Core\Block\BlockPluginInterface $block) {
Chris@0:   // Remove the contextual links on all blocks that provide them.
Chris@0:   if (isset($build['#contextual_links'])) {
Chris@0:     unset($build['#contextual_links']);
Chris@0:   }
Chris@0: }
Chris@0: 
Chris@0: /**
Chris@0:  * Provide a block plugin specific block_view alteration.
Chris@0:  *
Chris@0:  * In this hook name, BASE_BLOCK_ID refers to the block implementation's plugin
Chris@0:  * id, regardless of whether the plugin supports derivatives. For example, for
Chris@0:  * the \Drupal\system\Plugin\Block\SystemPoweredByBlock block, this would be
Chris@0:  * 'system_powered_by_block' as per that class's annotation. And for the
Chris@0:  * \Drupal\system\Plugin\Block\SystemMenuBlock block, it would be
Chris@0:  * 'system_menu_block' as per that class's annotation, regardless of which menu
Chris@0:  * the derived block is for.
Chris@0:  *
Chris@0:  * @param array $build
Chris@0:  *   A renderable array of data, as returned from the build() implementation of
Chris@0:  *   the plugin that defined the block:
Chris@0:  *   - #title: The default localized title of the block.
Chris@0:  * @param \Drupal\Core\Block\BlockPluginInterface $block
Chris@0:  *   The block plugin instance.
Chris@0:  *
Chris@0:  * @see hook_block_view_alter()
Chris@0:  * @see entity_crud
Chris@0:  *
Chris@0:  * @ingroup block_api
Chris@0:  */
Chris@0: function hook_block_view_BASE_BLOCK_ID_alter(array &$build, \Drupal\Core\Block\BlockPluginInterface $block) {
Chris@0:   // Change the title of the specific block.
Chris@0:   $build['#title'] = t('New title of the block');
Chris@0: }
Chris@0: 
Chris@0: /**
Chris@0:  * Alter the result of \Drupal\Core\Block\BlockBase::build().
Chris@0:  *
Chris@0:  * Unlike hook_block_view_alter(), this hook is called very early, before the
Chris@0:  * block is being assembled. Therefore, it is early enough to alter the
Chris@0:  * cacheability metadata (change #cache), or to explicitly placeholder the block
Chris@0:  * (set #create_placeholder).
Chris@0:  *
Chris@0:  * In addition to hook_block_build_alter(), which is called for all blocks,
Chris@0:  * there is hook_block_build_BASE_BLOCK_ID_alter(), which can be used to target
Chris@0:  * a specific block or set of similar blocks.
Chris@0:  *
Chris@0:  * @param array &$build
Chris@0:  *   A renderable array of data, only containing #cache.
Chris@0:  * @param \Drupal\Core\Block\BlockPluginInterface $block
Chris@0:  *   The block plugin instance.
Chris@0:  *
Chris@0:  * @see hook_block_build_BASE_BLOCK_ID_alter()
Chris@0:  * @see entity_crud
Chris@0:  *
Chris@0:  * @ingroup block_api
Chris@0:  */
Chris@0: function hook_block_build_alter(array &$build, \Drupal\Core\Block\BlockPluginInterface $block) {
Chris@0:   // Add the 'user' cache context to some blocks.
Chris@16:   if ($block->label() === 'some condition') {
Chris@0:     $build['#cache']['contexts'][] = 'user';
Chris@0:   }
Chris@0: }
Chris@0: 
Chris@0: /**
Chris@0:  * Provide a block plugin specific block_build alteration.
Chris@0:  *
Chris@0:  * In this hook name, BASE_BLOCK_ID refers to the block implementation's plugin
Chris@0:  * id, regardless of whether the plugin supports derivatives. For example, for
Chris@0:  * the \Drupal\system\Plugin\Block\SystemPoweredByBlock block, this would be
Chris@0:  * 'system_powered_by_block' as per that class's annotation. And for the
Chris@0:  * \Drupal\system\Plugin\Block\SystemMenuBlock block, it would be
Chris@0:  * 'system_menu_block' as per that class's annotation, regardless of which menu
Chris@0:  * the derived block is for.
Chris@0:  *
Chris@0:  * @param array $build
Chris@0:  *   A renderable array of data, only containing #cache.
Chris@0:  * @param \Drupal\Core\Block\BlockPluginInterface $block
Chris@0:  *   The block plugin instance.
Chris@0:  *
Chris@0:  * @see hook_block_build_alter()
Chris@0:  * @see entity_crud
Chris@0:  *
Chris@0:  * @ingroup block_api
Chris@0:  */
Chris@0: function hook_block_build_BASE_BLOCK_ID_alter(array &$build, \Drupal\Core\Block\BlockPluginInterface $block) {
Chris@0:   // Explicitly enable placeholdering of the specific block.
Chris@0:   $build['#create_placeholder'] = TRUE;
Chris@0: }
Chris@0: 
Chris@0: /**
Chris@0:  * Control access to a block instance.
Chris@0:  *
Chris@0:  * Modules may implement this hook if they want to have a say in whether or not
Chris@0:  * a given user has access to perform a given operation on a block instance.
Chris@0:  *
Chris@0:  * @param \Drupal\block\Entity\Block $block
Chris@0:  *   The block instance.
Chris@0:  * @param string $operation
Chris@0:  *   The operation to be performed; for instance, 'view', 'create', 'delete', or
Chris@0:  *   'update'.
Chris@0:  * @param \Drupal\Core\Session\AccountInterface $account
Chris@0:  *   The user object to perform the access check operation on.
Chris@0:  *
Chris@0:  * @return \Drupal\Core\Access\AccessResultInterface
Chris@0:  *   The access result. If all implementations of this hook return
Chris@0:  *   AccessResultInterface objects whose value is !isAllowed() and
Chris@0:  *   !isForbidden(), then default access rules from
Chris@0:  *   \Drupal\block\BlockAccessControlHandler::checkAccess() are used.
Chris@0:  *
Chris@0:  * @see \Drupal\Core\Entity\EntityAccessControlHandler::access()
Chris@0:  * @see \Drupal\block\BlockAccessControlHandler::checkAccess()
Chris@0:  * @ingroup block_api
Chris@0:  */
Chris@0: function hook_block_access(\Drupal\block\Entity\Block $block, $operation, \Drupal\Core\Session\AccountInterface $account) {
Chris@0:   // Example code that would prevent displaying the 'Powered by Drupal' block in
Chris@0:   // a region different than the footer.
Chris@0:   if ($operation == 'view' && $block->getPluginId() == 'system_powered_by_block') {
Chris@0:     return AccessResult::forbiddenIf($block->getRegion() != 'footer')->addCacheableDependency($block);
Chris@0:   }
Chris@0: 
Chris@0:   // No opinion.
Chris@0:   return AccessResult::neutral();
Chris@0: }
Chris@0: 
Chris@0: /**
Chris@0:  * @} End of "addtogroup hooks".
Chris@0:  */