Building a custom block using the Block Plugin APIfor Drupal 8 , 9 , 10 , and 11

Blocks in Drupal are a powerful feature that lets developers add reusable content throughout their sites. Using the Block Plugin API, you can create custom blocks that offer dynamic content, advanced configuration, and personalized user interactions. This lesson walks you through creating a custom Drupal block from the ground up.

Understanding the Block Plugin API

The Block Plugin API is an integral part of Drupal that allows developers to create blocks as plugins. These blocks can be configured and placed in various regions provided by your theme. Compared to static content, custom blocks are more flexible and interactive, responding to user inputs and displaying dynamic data.

Setting up Your Custom Block

To create a custom block, you'll implement a new plugin by defining a block class and a block annotation. Let’s get started by setting up our custom block plugin.

Step 1: Create the Block Class

First, create a directory for your block plugin within your module, for example, src/Plugin/Block. Next, create the block class file, say CustomGreetingBlock.php.

namespace Drupal\your_module\Plugin\Block;

use Drupal\Core\Block\BlockBase;
use Drupal\Core\Block\BlockPluginInterface;

/**
 * Provides a 'Custom Greeting' block.
 *
 * @Block(
 *   id = "custom_greeting_block",
 *   admin_label = @Translation("Custom Greeting"),
 *   category = @Translation("Custom")
 * )
 */
class CustomGreetingBlock extends BlockBase implements BlockPluginInterface {

    /**
     * {@inheritdoc}
     */
    public function build() {
        return [
            '#markup' => $this->t('Hello, welcome to our site!'),
        ];
    }

}

In our example, the block displays a simple greeting message. This class extends BlockBase and implements BlockPluginInterface, representing a typical custom block structure.

Step 2: Annotate Your Block

The annotation properties like id, admin_label, and category describe how your block will appear in the admin interface and how it's categorized. This metadata is crucial for managing and configuring the block through the Drupal UI.

Configuring the Block Experience

While our block is now visible in the admin UI under the Custom Blocks section, you can enhance its functionality by adding custom settings or logic to its behavior. Let’s learn how you can do this.

Implementing Settings

To allow configuration directly from the UI, override the blockForm and blockSubmit methods. This is often used to provide adjustable parameters for your blocks.

/**
 * {@inheritdoc}
 */
public function blockForm($form, \Drupal\Core\Form\FormStateInterface $form_state) {
    $form['custom_text'] = [
        '#type' => 'textfield',
        '#title' => $this->t('Custom Text'),
        '#default_value' => $this->configuration['custom_text'] ?? $this->t('Hello, welcome to our site!'),
    ];
    return $form;
}

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

/**
 * {@inheritdoc}
 */
public function build() {
    return [
        '#markup' => $this->configuration['custom_text'],
    ];
}

By incorporating these methods, you give users the flexibility to change the greeting message via the block configuration form.

Adding Cache Tags

To ensure the block remains efficient while interacting dynamically with your site, incorporate caching strategies. Here’s an example of integrating cache tags:

/**
 * {@inheritdoc}
 */
public function getCacheMaxAge() {
    return 0;
}

By setting the cache max age to 0, the block is always fresh, meaning it recalculates on each request.

Conclusion

Congratulations, you've successfully created a custom block using Drupal's Block Plugin API. This block serves as a template for more advanced custom blocks that access databases, render forms, or interact with users in complex ways.

In our next lesson, we'll explore "Defining a Custom Field Type," where you’ll learn how to create specialized fields. These fields empower content creators, expanding the ways you can gather and display data across your Drupal-based site. Keep building your Drupal expertise, one component at a time!