Drupal 8 - Creating a custom 'Block' module

3 mins

Here's a very simple and easy to follow guide to add a custom Block module to your Drupal 8 website.

In this example I'll use 'custom_block_module' as the project name, so just replace that with your module name.

You'll only need to create two files:

  1. custom_block_module.info.yml
  2. CustomBlockModule.php

Of course you can change these names to suit your requirements.

Step 1

Let's start by creating the 'custom_block_module.info.yml' file that will let Drupal know about the new block module.

  • In your '/modules/custom' folder create a folder called 'custom_block_module'
    (if you don't have a 'custom' folder simply create one)
  • Inside the 'custom_block_module' folder create a new file called 'custom_block_module.info.yml' and add the following code to it.
    name: Custom Block Module
    description: Enter a description for your Custom Block Module here that will appear in the module list.
    core: 8.x
    package: Custom
    - node
    - block
    type: module

Step 2

Next we create the path structure that will hold the components that define the Block and its content.

In the 'custom_block_module' folder:

  • create a folder called 'src' and then navigate to the folder.
  • create a folder called 'Plugin' and again navigate to that folder.
  • create a folder called 'Block' and then navigate to that folder.

Your module folder structure should look like:

  • custom_block_module
    • src
      • Plugin
        • Block

Step 3

Now we create the PHP file that will define the Block itself.

  • Make sure you are sitting at '/modules/custom/custom_block_module/src/Plugin/Block'
  • Create a new file called 'CustomModuleBlock.php' (adjust filename as required) and edit this file to add the following code:
    			namespace Drupal\custom_block_module\Plugin\Block;
    			use Drupal\Core\Block\BlockBase;
    			 * Provides a 'Custom' Block
    			 * @Block(
    			 *   id = "my_custom_block",
    			 *   admin_label = @Translation("My Custom Block"),
    			 * )
    			class CustomBlockModule extends BlockBase {
    			   * {@inheritdoc}
    			  public function build() {
    			    /* You can put any PHP code here if required */
    			    print ('Hello World - PHP version'); 
    			    return array(
    			      '#markup' => $this->t('Hello World - HTML Version');
    			      /* If you want to bypass Drupal 8's default caching for this block then simply add this, otherwise remove the next three lines */
    			      '#cache' => array(
    			          'max-age' => 0,

Step 4

Now you are ready to enable your new Custom Block Module and assign it to a region.

  • Select the 'Extend' admin menu item.
  • Locate the new module 'My Custom Block' and enable it.
  • Now select the 'Structure' admin menu item, followed by 'Block layout'
  • Scroll to the region you want to add the block contents to and select the 'Place block' button.
  • Enter the block name 'My Custom Block' into the filter and when found select the 'Place block' button.
  • Order the block as required.

All being good you should now see the new custom block content displayed in the region selected.



Date posted:
25 November 2016
Authored by :
Stephen Ollman