Backend Development - Block Plugins

Blocks are one of the most visible features in Drupal, but behind the scenes they are powered by a plugin system. Understanding block plugins is a major step in backend Drupal development because it introduces you to plugin architecture, annotations, and reusable backend components.

In this topic, we move beyond configuration-only blocks and learn how to create custom block plugins using code. We continue the learning-by-building approach by extending the same weeklydrupal_demo module.

By the end of this article, you will understand:

• What block plugins are
• How Drupal’s plugin system works at a high level
• How to create a custom block using code
• How configuration and logic are separated in blocks
• When block plugins are the right solution

1. What Is a Block Plugin

A block plugin is a reusable backend component that:

• Provides content or functionality
• Can be placed in any region
• Can be configured per placement
• Is discovered automatically by Drupal

In simple terms:

A block plugin is backend logic packaged as a pluggable UI component.

2. Blocks vs Block Plugins

It is important to separate these concepts:

• Block – A placed instance in the UI
• Block plugin – The PHP class that defines behavior

One block plugin can have many block instances, each with different configuration.

3. Why Blocks Are Plugins

Drupal uses plugins so that:

• New functionality can be discovered automatically
• Components can be swapped or extended
• Configuration and logic remain separate

Block plugins are one of the clearest examples of Drupal’s plugin-based architecture.

4. Where Block Plugins Live

Block plugins live under the Plugin namespace.

Path:

weeklydrupal_demo/src/Plugin/Block/

Drupal scans this directory to discover block plugins.

5. Creating a Basic Block Plugin

File path

weeklydrupal_demo/src/Plugin/Block/DemoBlock.php

Block plugin code

<?php

namespace Drupal\weeklydrupal_demo\Plugin\Block;

use Drupal\Core\Block\BlockBase;

/**
 * Provides a WeeklyDrupal demo block.
 *
 * @Block(
 *   id = "weeklydrupal_demo_block",
 *   admin_label = @Translation("WeeklyDrupal Demo Block"),
 *   category = @Translation("WeeklyDrupal")
 * )
 */
class DemoBlock extends BlockBase {

  public function build() {
    return [
      '#markup' => $this->t('Hello from a custom block plugin'),
    ];
  }

}

6. Understanding the Block Annotation

The @Block annotation tells Drupal how to discover this plugin.

Key parts:

• id – Unique machine name for the block plugin
• admin_label – Display name in the block UI
• category – Grouping in the admin interface

Drupal reads this metadata during cache rebuilds.

7. How Drupal Discovers Block Plugins

When caches are rebuilt:

1. Drupal scans src/Plugin/Block
2. Reads plugin annotations
3. Registers the block plugin
4. Makes it available in the Block Layout UI

No manual registration is required.

8. The build() Method

public function build() {
  return [
    '#markup' => $this->t('Hello from a custom block plugin'),
  ];
}

Important rules:

• Must return a render array
• Should not contain heavy logic
• Should delegate logic to services when needed

9. Adding Configuration to a Block

Blocks can be configurable per placement.

Default configuration

public function defaultConfiguration() {
  return [
    'message' => 'Default block message',
  ];
}

Block configuration form

public function blockForm($form, \Drupal\Core\Form\FormStateInterface $form_state) {
  $form['message'] = [
    '#type' => 'textfield',
    '#title' => $this->t('Block message'),
    '#default_value' => $this->configuration['message'],
  ];

  return $form;
}

Save configuration

public function blockSubmit($form, \Drupal\Core\Form\FormStateInterface $form_state) {
  $this->configuration['message'] = $form_state->getValue('message');
}

10. Using Configuration in build()

public function build() {
  return [
    '#markup' => $this->t('@message', [
      '@message' => $this->configuration['message'],
    ]),
  ];
}

Each block placement can now display different content.

11. When to Use Block Plugins

Use block plugins when:

• Content must appear in regions
• Logic should be reusable
• Editors need placement control
• Configuration varies by placement

Avoid block plugins for:

• Full pages
• Form-heavy workflows
• One-off logic

12. Common Mistakes to Avoid

• Hardcoding HTML
• Putting heavy logic in build()
• Skipping cache considerations
• Treating blocks as pages

Blocks should stay lightweight and reusable.

13. Learning by Building: weeklydrupal_demo

At this stage, our module includes:

• Routes and controllers
• Forms and AJAX
• Form alters
• Custom block plugins

This reflects real backend Drupal architecture.

14. Why Block Plugins Matter

Block plugins teach you:

• Plugin-based thinking
• Annotation-driven discovery
• Separation of logic and configuration

These concepts appear across Drupal in fields, views, and actions.