Drupal 7’s block system has always left something to be desired. Fortunately, Drupal 8 has made huge improvements in this arena. One of these improvements is the concept of reusable blocks that you can store in a library. Today we'll go through how to create and store your own custom reusable block. While reusable blocks can be created via the UI, these examples will be created in code.

First things first, let’s create a bare-bones module to house the reusable block. This is pretty simple. In your modules/custom/ (or sites/all/modules/, if that’s your thing) folder create your my_custom_module folder and inside that the file my_custom_module.info.yml.

type: module

name: My Custom Module

description: 'Custom module to demonstrate custom reusable blocks.'

core: 8.x

Create an empty my_custom_module.module file. For this example the .module file isn’t even necessary. However, it’s good to put in place for further processing of your block or any custom implementation required for your project.

Now we need to create the file that builds your block. From within your custom module, create the following folder: src/Plugin/Block. Next, create the file MyCustomBlock.php within that folder. The opening of the file should declare the namespace to that of your custom block and then import Drupal\Core\Block\BlockBase:

<?php
/**
 * @file
 * Contains \Drupal\my_custom_block\Plugin\Block\MyCustomBlock.
 */
namespace Drupal\my_custom_block\Plugin\Block;
use Drupal\Core\Block\BlockBase;

Next, we need to create a new custom class that extends BlockBase. It is important to pay attention to the naming convention used for your filename. If the class name and filename do not match, your block will not work.

/**
 * Provides an example of a custom reusable block.
 *
 * @Block(
 *   id = "my_custom_block_id",
 *   admin_label = @Translation("My Custom Block")
 * )
 */
class MyCustomBlock extends BlockBase {
  /**
   * {@inheritdoc}
   */
  public function build() {
    return array('#markup' => t('My custom block is ALIVE!'));
  }
}

It’s also important to note the @Block() comment. These annotations define information about your block and are how Drupal discovers your block. Keep in mind that the example given here is incredibly simple. A lot more can be done with custom blocks.

After all that, your custom block is ready to be placed in a region!

A mistake people often make during this next step is to look in the wrong location to find their custom block. I would be lying if I said I didn’t do this myself. You’ll probably find yourself going to /admin/structure/block/block-content, i.e. the Custom block library tab. However, this is only for custom blocks created via the UI - not created programmatically. To add your custom block you need to navigate to /admin/structure/block and click the Place Block button next to the region you want to insert your block into.

And finally, you'll see the fruits of our labor!