5 * Hooks provided by the Block module.
8 use Drupal\Core\Access\AccessResult;
11 * @defgroup block_api Block API
13 * Information about the classes and interfaces that make up the Block API.
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.
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
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.
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()
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.
66 * Alter the result of \Drupal\Core\Block\BlockBase::build().
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.
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.
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.
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.
89 * @see hook_block_view_BASE_BLOCK_ID_alter()
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']);
102 * Provide a block plugin specific block_view alteration.
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.
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.
119 * @see hook_block_view_alter()
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');
130 * Alter the result of \Drupal\Core\Block\BlockBase::build().
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).
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.
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.
146 * @see hook_block_build_BASE_BLOCK_ID_alter()
151 function hook_block_build_alter(array &$build, \Drupal\Core\Block\BlockPluginInterface $block) {
152 // Add the 'user' cache context to some blocks.
153 if ($some_condition) {
154 $build['#cache']['contexts'][] = 'user';
159 * Provide a block plugin specific block_build alteration.
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.
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.
174 * @see hook_block_build_alter()
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;
185 * Control access to a block instance.
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.
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
195 * @param \Drupal\Core\Session\AccountInterface $account
196 * The user object to perform the access check operation on.
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.
204 * @see \Drupal\Core\Entity\EntityAccessControlHandler::access()
205 * @see \Drupal\block\BlockAccessControlHandler::checkAccess()
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);
216 return AccessResult::neutral();
220 * @} End of "addtogroup hooks".