Drupal 8 Blocks

By Appnovation Co-op Erica Scott. 

Drupal 8 is changing the way Drupal developers can build custom blocks within the code.

The Drupal 7 Way

Let's look at how we would define a block in Drupal 7. We would input code like this into the .module file of a custom module such as /sites/all/modules/custom/blog_example/blog_example.module

<?php
/**
 * @file
 * Module file for blog_example module.
 */

/**
 * Implements hook_block_info().
 */
function blog_example_block_info() {
  $blocks = array();
  $blocks['blog_example_block'] = array(
    'info' => t('Blog Example'),
  );
  return $blocks;
}

/**
 * Implements hook_block_view().
 */
function blog_example_block_view($delta = '') {
  $block = array();
  switch($delta) {
    case 'blog_example_block':
      $block['content'] = '<h1>Hello, World!</h1><p>This is a test block!</p>';
      break;
  }
  return $block;
}

First, we would need to declare the info for the block using hook_block_info which uses an ID for the block (blog_example_block) and the title for the block that we will see on configuration pages (Blog Example). Then, we would need to define what we see when we display the block using hook_block_view (there are other ways to do this as well, and other things to do with the block, but this is a simple way to just show a basic block). In this hook, we see that when we encounter the block ID we defined in the previous hook, we set the content of that block.

With this definition, we can now see the block if we navigate to /admin/structure/block, we should be able to see the new block and set it under the Content region of our site (or anywhere else we would like it displayed).

The Drupal 8 Way

Drupal 8 does this same thing by defining a class that declares the block. Once a developer becomes more accustomed to using Drupal 8 (and working with a object oriented code) we can see that this block declaration is simpler than the way it was declared in Drupal 7. The following is how you would define the exact same block in Drupal 8. This code would exist in a file such as /modules/custom/blog_example/src/Plugin/Block/BlogExample.php

<?php
/**
 * @file
 * Contains BlogExample Block.
 */

namespace Drupal\blog_example\Plugin\Block;

use Drupal\Core\Block\BlockBase;

/**
 * Provides BlogExample Block.
 *
 * @Block(
 *   id = "blog_example_block",
 *   admin_label = @Translation("Blog Example"),
 *   category = @Translation("Blocks")
 * )
 */
class BlogExample extends BlockBase {

  /**
   * {@inheritdoc}
   */
  public function build() {
    $build = [];
    $build[] = array(
      '#type' => 'markup',
      '#markup' => '<h1>Hello, World!</h1><p>This is a test block!</p>',
    );
    return $build;
  }
}

There is a lot going on here. Let's talk about each section:

First, we need to declare the block file, which first means defining a namespace for the file (which is commonly used throughout Drupal 8, please read this article for more information on namespaces). In this instance, we have placed the file in the custom module in src/Plugin/Block and so the namespace for this will need to look something like Drupal\{CUSTOM MODULE}\Plugin\Block.

<?php
/**
 * @file
 * Contains BlogExample Block.
 */

namespace Drupal\blog_example\Plugin\Block;

Also, in order to extend the BlockBase Drupal class, we need to include the core files as such.

use Drupal\Core\Block\BlockBase;

Next, we need to declare the block in a comment, which, unlike Drupal 7, is necessary to have Drupal recognize the block. The block declaration is expecting an ID and an Admin Label, and can be passed other optional parameters such as a Category. Please note the use of @Translation() here, which works the same as t() does in Drupal 7.

/**
 * Provides BlogExample Block.
 *
 * @Block(
 *   id = "blog_example_block",
 *   admin_label = @Translation("Blog Example"),
 *   category = @Translation("Blocks")
 * )
 */

 Then, when defining the class we simply need to ensure that the class name (here, it is BlogExample) matches the name of the file (which is why we named the file BlogExample.php) and that it extends the proper class for blocks (BlockBase).

class BlogExample extends BlockBase {

Finally, we get to actually assigning content to the block. Everything up to this point simply describes the block, and lets Drupal know about it. We can see here that the code to build the block is quite similar to what we normally would have done in Drupal 7. The most important difference is the use of the method build(), but we also display information using the Form API process.

public function build() {
  $build = [];
  $build = array(
    '#type' => 'markup',
    '#markup' => '<h1>Hello, World!</h1><p>This is a test block!</p>',
  );
  return $build;
}

Then, just like in Drupal 7 we can navigate to /admin/structure/block and add this block into any region we wish.

Summary

This is a quick introduction to Drupal 8's procedure for creating custom blocks within the code. For more information check out the documentation page at drupal.org.