Contrib.social

Clarify how to make custom template for block plugin

Open on Drupal.org →
Created on 31 March 2022, almost 3 years ago
Updated 4 September 2024, 4 months ago

Problem/Motivation

I'm trying to follow the documentation for creating a "custom block" via a block plugin here:
https://www.drupal.org/docs/creating-custom-modules/creating-custom-bloc... →

The problem arises when we try to create a custom template for the block:
https://www.drupal.org/docs/creating-custom-modules/creating-custom-bloc... →

I've started a discussion on that page, but it hasn't gone anywhere. Hoping this issue will get more eyes.

The problem is that if you follow that documentation, you end up with unnecessary nested block templates.
Your markup will look something like this:

<div class=block block-id--my-block">
  <h2 class="block__title">My Block</h2>
  <div class="block__content">
    <div class="block">
      <div class="block__content">
        // Content here
      </div>
    </div>
  </div>
</div>

When ideally it would look like this:

<div class=block block-id--my-block">
  <h2 class="block__title">My Block</h2>
  <div class="block__content">
    // Content here
  </div>
</div>

Steps to reproduce

Follow this documentation:
https://www.drupal.org/docs/creating-custom-modules/creating-custom-bloc... →

Proposed resolution

I have an alternative suggestion, but it has its own unwanted side effects.

MyBlock.php

/**
 * @Block(
 *  id = "my_block",
 *  admin_label = @Translation("My Block"),
 * )
 */
class MyBlock extends BlockBase {

  /**
   * {@inheritdoc}
   */
  public function build() {
    return [
      '#theme' => 'block__my_block',
    ];
  }
}

my_module.module

/**
 * Implements hook_theme().
 */
function my_module_theme($existing, $type, $theme, $path) {
  return [
      'block__my_block' => [
      // @todo: If default 'content' variable is provided contextual
      // links will not render in Layout Builder.
      'variables' => [],
      'template' => 'my-block',
      'path' => $path . '/templates/block',
      'base hook' => 'block'
    ],
  ]
}

The problem with this solution is that passing any value for variables['content'] in my_module_theme() causes contextual links to not render when the block is placed via Layout Builder (and I assume when the block is placed via Block Layout).

Remaining tasks

Document a process for creating a custom block via a block plugin and a corresponding template in a module that does not generate unnecessary markup and also allows contextual links to render.

User interface changes

API changes

Data model changes

Release notes snippet

💬 Support request
Status

Postponed: needs info

Version

11.0 🔥

Component
Block  →

Last updated 1 day ago

Created by

🇺🇸United States maskedjellybean Portland, OR

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Comments & Activities

Not all content is available!

It's likely this issue predates Contrib.social: some issue and comment data are missing.

  • Comment over 1 year ago →
    🇺🇸United States smustgrave

    Is your twig template adding the extra div?

  • Comment over 1 year ago →
    🇺🇸United States maskedjellybean Portland, OR

    I'm not sure whether this is a bug or task. I only know it doesn't seem right. Having the additional nested block classes will cause unexpected styling issues.

    This has been a problem on every Drupal 8+ project I've worked on regardless of theme.

  • Comment 4 months ago →
    🇺🇸United States mark_fullmer Tucson

    The problem is that if you follow that documentation, you end up with unnecessary nested block templates.

    I think this depends on what your block.html.twig file is doing. For example, Olivero's template renders the additional divs:

    <div{{ attributes.addClass(classes) }}>
  {{ title_prefix }}
  {% if label %}
    <h2{{ title_attributes.addClass('block__title') }}>{{ label }}</h2>
  {% endif %}
  {{ title_suffix }}
  {% block content %}
    <div{{ content_attributes.addClass('block__content') }}>
      {{ content }}
    </div>
  {% endblock %}
</div>

    ...whereas Stable9, for example, does not:

    <div{{ attributes }}>
  {{ title_prefix }}
  {% if label %}
    <h2{{ title_attributes }}>{{ label }}</h2>
  {% endif %}
  {{ title_suffix }}
  {% block content %}
    {{ content }}
  {% endblock %}
</div>

    If a site is defining a custom block plugin, I think it would be reasonable to "solve" this issue by customizing a block-level template, either site-wide, or for a subset of blocks, which can be done through Twig template suggestions.

    I think this issue is "works as designed."

contrib.social Blog FAQ Discussions
Production build 0.71.5 2024