Block API

Same name in other branches
  1. 9 core/modules/block/block.api.php \block_api
  2. 8.9.x core/modules/block/block.api.php \block_api
  3. 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:

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

File

core/modules/block/block.api.php, line 13

Functions

Title Sort descending File name Summary
hook_block_access core/modules/block/block.api.php Control access to a block instance.
hook_block_alter core/modules/block/block.api.php Allow modules to alter the block plugin definitions.
hook_block_build_alter core/modules/block/block.api.php Alter the result of \Drupal\Core\Block\BlockBase::build().
hook_block_build_BASE_BLOCK_ID_alter core/modules/block/block.api.php Provide a block plugin specific block_build alteration.
hook_block_view_alter core/modules/block/block.api.php Alter the result of \Drupal\Core\Block\BlockBase::build().
hook_block_view_BASE_BLOCK_ID_alter core/modules/block/block.api.php Provide a block plugin specific block_view alteration.

Classes

Title Sort descending File name Summary
Block core/lib/Drupal/Core/Block/Annotation/Block.php Defines a Block annotation object.
BlockBase core/lib/Drupal/Core/Block/BlockBase.php Defines a base block implementation that most blocks plugins will extend.

Interfaces

Title Sort descending File name Summary
BlockPluginInterface core/lib/Drupal/Core/Block/BlockPluginInterface.php Defines the required interface for all block plugins.
MainContentBlockPluginInterface core/lib/Drupal/Core/Block/MainContentBlockPluginInterface.php The interface for "main page content" blocks.
MessagesBlockPluginInterface core/lib/Drupal/Core/Block/MessagesBlockPluginInterface.php The interface for "messages" (#type => status_messages) blocks.
TitleBlockPluginInterface core/lib/Drupal/Core/Block/TitleBlockPluginInterface.php The interface for "title" blocks.

Traits

Title Sort descending File name Summary
BlockPluginTrait core/lib/Drupal/Core/Block/BlockPluginTrait.php 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.