Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 37 ยท Views and Blocks

Blocks and Regions

Place content in Drupal themes with blocks and regions: block layout, custom block types, visibility conditions, plugin blocks, Views blocks and a custom block in code.

A page in Drupal is more than the main content. Around it you find a header, a navigation menu, a search box, a sidebar, a footer. These pieces are blocks, and the areas of the page where they sit are regions. The system lets site builders rearrange the layout without code, and lets developers add new kinds of blocks.

This lesson explains regions, the block layout screen, custom block content, visibility rules, and how to write a block in a module.

Regions belong to themes

A region is a named area defined by the theme. A typical theme defines Header, Primary menu, Highlighted, Content, Sidebar first, Sidebar second and Footer. The regions are listed in the theme's *.info.yml:

YAML
name: My Theme
type: theme
base theme: stable9
core_version_requirement: ^10 || ^11
regions:
  header: 'Header'
  primary_menu: 'Primary menu'
  content: 'Content'
  sidebar_first: 'Sidebar first'
  footer: 'Footer'

Different themes have different regions, and block placements are stored per theme. Switch themes and you need to place blocks again (configuration export helps).

The Block layout page

Go to Structure > Block layout (/admin/structure/block). You see the regions of the default theme with the blocks placed in each. Use Place block to add one:

  1. Pick a block from the list.
  2. Set its title and whether to display the title.
  3. Choose visibility conditions and the region.
  4. Save, then reorder by dragging and click Save blocks.

A block placement is itself a configuration entity (block.block.<id>.yml), connecting a block plugin to a region in a theme.

Kinds of blocks

  • System blocks: Main page content (the route's output), Page title, Messages, Primary admin actions, Tabs, Site branding, Powered by Drupal.
  • Menu blocks: Main navigation, Footer menu, User account menu.
  • Custom blocks (content blocks): blocks you create with fields, in Content > Blocks. They are content entities (block_content), reusable, with their own bundles called custom block types. You can add fields to them, like any bundle.
  • Views blocks: any View display set to Block. See Views Basics.
  • Module blocks: such as Search form, Who's online, or blocks from contributed modules.

Visibility conditions

On the placement form, restrict where and for whom the block shows:

  • Pages: show on listed paths (/events*) or hide on them.
  • Content types: only on Event pages.
  • Roles: only for authenticated users, or only editors.
  • Languages: only for chosen languages.
  • Request path wildcards: * matches anything.

Visibility affects caching: Drupal records cache contexts for the conditions, so the page cache varies correctly.

A block in code

When configuration cannot do the job, write a block plugin. Plugins live in src/Plugin/Block/ and use PHP attributes (Drupal 10.2+ and 11) to declare themselves. Real code, read-only:

PHP
<?php

namespace Drupal\greetings\Plugin\Block;

use Drupal\Core\Block\Attribute\Block;
use Drupal\Core\Block\BlockBase;
use Drupal\Core\StringTranslation\TranslatableMarkup;

#[Block(
  id: 'greetings_welcome',
  admin_label: new TranslatableMarkup('Welcome message'),
)]
class WelcomeBlock extends BlockBase {

  public function build(): array {
    return [
      '#markup' => $this->t('Welcome to our site!'),
      '#cache' => ['max-age' => 3600],
    ];
  }

}

Once the module is enabled, "Welcome message" appears in the Place block list. build() returns a render array. The #cache key controls caching; you will see why that matters in the Performance chapter.

A block with settings adds defaultConfiguration(), blockForm() and blockSubmit() methods, so editors can configure it in the UI.

Blocks and Layout Builder

Placing blocks in global regions suits site-wide elements. When pages need individual layouts, Drupal's Layout Builder lets you place blocks per content type or per node. It is covered in Menus and Layout Builder.

A region and block model

The stand-in below holds regions and placements, applies visibility conditions and prints the resulting page layout. It models the logic of Block layout; real Drupal does it with config entities and plugins.

JS Stand-in: block placement and visibility

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The upcoming_events block shows on /events but not on /about, and admin_tips appears only for editors.

Writing a block's build method

This second stand-in imitates the block plugin lifecycle: a plugin registry, a build() method and caching with a lifetime. It is a pattern sketch, not Drupal's plugin manager.

JS Stand-in: block plugins with caching

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Practical advice

  • Put site-wide elements in blocks, not inside the theme's templates, so editors can move them.
  • Use custom block types with fields instead of one giant body field.
  • Keep visibility simple; many complex conditions are hard to debug.
  • Disable blocks you do not use instead of deleting them while you experiment.
  • Export block placements as configuration like everything else.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where are regions defined?

    Themes declare their regions in the regions key of their *.info.yml.
  2. 2. What is a custom block (content block)?

    Custom blocks are reusable content entities placed into regions.
  3. 3. Which method of a block plugin returns what is shown?

    BlockBase::build() returns a render array for the block.
  4. 4. Why are block placements stored per theme?

    Region names and layout differ between themes, so placements belong to a theme.

Summary

  • Themes define regions; blocks are placed into them from Structure > Block layout.
  • Blocks come from the system, menus, custom content blocks, Views and modules.
  • Visibility conditions control where and for whom a block shows; they influence caching.
  • Custom block plugins implement build() and return render arrays.

Next: Menus and Layout Builder