Block-API

Overzicht

Blokken in Drupal 8 bestaan eigenlijk uit twee afzonderlijke API-structuren om een gebruikersinterface te creëren die vergelijkbaar is met die van eerdere Drupal-versies. Deze twee API’s zijn de Block Plugin API, die een zelfstandige en herbruikbare API is, en de Block Entity API, die specifiek is voor Drupal 8 om blokken te plaatsen en hun zichtbaarheid te beheren.

Blokken maken met de Block Plugin API

Het maken van blokken die in de code van je module worden gedefinieerd, vereist kennis en begrip van de Plugin API en in het bijzonder het gebruik van annotatie-gebaseerde plugins, het mechanisme dat Drupal 8 gebruikt om de code te vinden die je blok definieert.

Het maken van een aangepast blok in je module omvat de volgende stappen:

• Maak een block plugin met annotaties
• Breid de klasse Drupal\Core\Block\BlockBase uit
• Implementeer de methodes uit de interface Drupal\Core\Block\BlockPluginInterface die nodig zijn voor jouw use case

Zorg dat je blok zichtbaar is voor Drupal en je gebruikers

Drupal gebruikt de PSR-4-standaard voor detectie. Stel dat je module fax heet, dan moet de code voor je blok(ken) worden geplaatst in fax/src/Plugin/Block/. Elk bestand in deze map moet worden genoemd naar de klasse die het bevat. Als we bijvoorbeeld een klasse FaxBlock definiëren, moet die in fax/src/Plugin/Block/FaxBlock.php staan, met de volgende inhoud:

namespace Drupal\fax\Plugin\Block;

use Drupal\Core\Block\BlockBase;

/**
 * Provides a 'Fax' block.
 *
 * @Block(
 *   id = "fax_block",
 *   admin_label = @Translation("Fax block"),
 * )
 */
class FaxBlock extends BlockBase {
  // Override BlockPluginInterface methods here.
}

De eigenschap id in de annotatie bepaalt de unieke machine-readable ID van je blok en de naam die zichtbaar is in andere code. De annotatie admin_label bepaalt de leesbare naam van het blok in de admin-interface. Alle beschikbare eigenschappen staan beschreven in \Drupal\Core\Block\Annotation\Block.

Twee veelgebruikte methodes om te overschrijven zijn:

• BlockPluginInterface::build() – moet een render array teruggeven die de inhoud van het blok bepaalt
• BlockBase::access() – bepaalt de zichtbaarheid van het blok en geeft een AccessResult-object terug

Voeg aangepaste configuratieopties toe aan je blok

Je kunt ook extra configuratievelden toevoegen door de methodes BlockPluginInterface::blockForm() en BlockPluginInterface::blockSubmit() te overschrijven en met BlockBase::setConfigurationValue() en BlockBase::getConfiguration() te werken.

In het onderstaande voorbeeld voegen we een tekstveld toe in blockForm() en slaan we de waarde op in blockSubmit():

use Drupal\Core\Block\BlockBase;
use Drupal\Core\Block\BlockPluginInterface;
use Drupal\Core\Form\FormStateInterface;

/**
 * Provides a 'Fax' block.
 *
 * @Block(
 *   id = "fax_block",
 *   admin_label = @Translation("Fax block"),
 * )
 */
class FaxBlock extends BlockBase implements BlockPluginInterface {

  public function build() {
    $config = $this->getConfiguration();
    $fax_number = isset($config['fax_number']) ? $config['fax_number'] : '';
    return [
      '#markup' => $this->t('The fax number is @number!', ['@number' => $fax_number]),
    ];  
  }

  public function blockForm($form, FormStateInterface $form_state) {
    $form = parent::blockForm($form, $form_state);

    $config = $this->getConfiguration();
    $form['fax_number'] = [
      '#type' => 'textfield',
      '#title' => t('Fax number'),
      '#default_value' => isset($config['fax_number']) ? $config['fax_number'] : '',
    ];
    return $form;
  }

  public function blockSubmit($form, FormStateInterface $form_state) {
    $this->setConfigurationValue('fax_number', $form_state->getValue('fax_number'));
  }

  public function blockValidate($form, FormStateInterface $form_state) {
    $fax_number = $form_state->getValue('fax_number');
    if (!is_numeric($fax_number)) {
      $form_state->setErrorByName('fax_number', t('Needs to be an integer'));
    }
  }
}

Je kunt BlockBase::getConfiguration() gebruiken in de build()-methode om configuratiewaarden weer te geven. Ook de access()-methode kan complexere logica bevatten om te bepalen of een blok zichtbaar moet zijn.

Voorbeeld access-methode

/**
 * {@inheritdoc}
 */
public function access(AccountInterface $account, $return_as_object = FALSE) {
  return \Drupal\Core\Access\AccessResult::allowedIf($account->isAuthenticated());
}

Voorbeeld met cache-tags

/**
 * {@inheritdoc}
 */
public function getCacheTags() {
  return \Drupal\Core\Cache\Cache::mergeTags(parent::getCacheTags(), ['node_list']);
}

Als je de maximale cacheduur van een blok wilt uitschakelen (op 0 zetten):

public function getCacheMaxAge() {
  return 0;
}