Block API
Same name in other branches
- 9 core/modules/block/block.api.php \block_api
- 8.9.x core/modules/block/block.api.php \block_api
- 10 core/modules/block/block.api.php \block_api
Information about the classes and interfaces that make up the Block API.
Overview
Blocks are a combination of a configuration entity and a plugin. The configuration entity stores placement information (theme, region, weight) and any other configuration that is specific to the block. The block plugin does the work of rendering the block's content for display.
Basic requirements
To define a block in a module you need to:
- Define a Block plugin by creating a new class that implements the \Drupal\Core\Block\BlockPluginInterface, in namespace Plugin\Block under your module namespace. For more information about creating plugins, see the Plugin API topic.
- Usually you will want to extend the \Drupal\Core\Block\BlockBase class, which provides a common configuration form and utility methods for getting and setting configuration in the block configuration entity.
- Block plugins use the annotations defined by \Drupal\Core\Block\Annotation\Block. See the Annotations topic for more information about annotations.
This is an example of a basic block plugin class:
namespace Drupal\my_module\Plugin\Block;
use Drupal\Core\Block\BlockBase;
class MyBlock extends BlockBase {
public function build() {
return [
'#type' => '#markup',
'#markup' => 'Example block',
];
}
}
More examples are available at the links below.
Extending blocks with conditions and hooks
The Block API also makes use of Condition plugins, for conditional block placement. Condition plugins have interface \Drupal\Core\Condition\ConditionInterface, base class \Drupal\Core\Condition\ConditionPluginBase, and go in plugin namespace Plugin\Condition. Again, see the Plugin API and Annotations topics for details of how to create a plugin class and annotate it.
There are also several block-related hooks, which allow you to affect the content and access permissions for blocks:
Further information
- \Drupal\system\Plugin\Block\SystemPoweredByBlock provides a simple example of defining a block.
- \Drupal\user\Plugin\Condition\UserRole is a straightforward example of a block placement condition plugin.
- \Drupal\system\Plugin\Block\SystemMenuBlock is an example of a block with a custom configuration form.
- For a more in-depth discussion of the Block API, see https://www.drupal.org/docs/drupal-apis/block-api/block-api-overview.
- The Examples for Developers project also provides a Block example in https://www.drupal.org/project/examples.
File
-
core/
modules/ block/ block.api.php, line 13
Functions
Title Sort descending | File name | Summary |
---|---|---|
hook_block_access | core/ |
Control access to a block instance. |
hook_block_alter | core/ |
Allow modules to alter the block plugin definitions. |
hook_block_build_alter | core/ |
Alter the result of \Drupal\Core\Block\BlockBase::build(). |
hook_block_build_BASE_BLOCK_ID_alter | core/ |
Provide a block plugin specific block_build alteration. |
hook_block_view_alter | core/ |
Alter the result of \Drupal\Core\Block\BlockBase::build(). |
hook_block_view_BASE_BLOCK_ID_alter | core/ |
Provide a block plugin specific block_view alteration. |
Classes
Title Sort descending | File name | Summary |
---|---|---|
Block | core/ |
Defines a Block annotation object. |
BlockBase | core/ |
Defines a base block implementation that most blocks plugins will extend. |
Interfaces
Title Sort descending | File name | Summary |
---|---|---|
BlockPluginInterface | core/ |
Defines the required interface for all block plugins. |
MainContentBlockPluginInterface | core/ |
The interface for "main page content" blocks. |
MessagesBlockPluginInterface | core/ |
The interface for "messages" (#type => status_messages) blocks. |
TitleBlockPluginInterface | core/ |
The interface for "title" blocks. |
Traits
Title Sort descending | File name | Summary |
---|---|---|
BlockPluginTrait | core/ |
Provides the base implementation of a block plugin. |
Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.