Block-API

Übersicht

Blöcke in Drupal 8 bestehen tatsächlich aus zwei separaten API-Strukturen, um eine Benutzeroberfläche zu schaffen, die derjenigen ähnelt, die Drupal in früheren Versionen unterstützte. Diese beiden APIs sind das Block Plugin API, eine eigenständige API für die Wiederverwendung, und das Block Entity API, eine Drupal-8-spezifische Nutzung zur Platzierung von Blöcken und Steuerung der Sichtbarkeit.

Blöcke mit dem Block Plugin API erstellen

Das Erstellen von Blöcken, die im Code Ihres Moduls definiert sind, erfordert ein Verständnis des Plugin-APIs und insbesondere des Systems der annotationsbasierten Plugins, welches Drupal 8 verwendet, um den Code zu finden, der Ihren Block definiert.

Das Erstellen eines benutzerdefinierten Blocks in Ihrem Modul umfasst die folgenden Schritte:

• Erstellen eines Block-Plugins mithilfe von Annotationen
• Erweiterung der Klasse Drupal\Core\Block\BlockBase
• Implementieren der Methoden aus dem Interface Drupal\Core\Block\BlockPluginInterface, die für Ihren Anwendungsfall notwendig sind.

Machen Sie Ihren Block für Drupal und Benutzer sichtbar

Drupal verwendet den PSR-4-Standard für die Entdeckung. Angenommen, Ihr Modul heißt fax, dann muss der Code für Ihren benutzerdefinierten Block in fax/src/Plugin/Block/ liegen. Jede Datei in diesem Verzeichnis muss den Klassennamen tragen, den sie enthält. Wenn Sie z. B. eine Klasse FaxBlock definieren, muss sie in fax/src/Plugin/Block/FaxBlock.php liegen und den folgenden Beispielinhalt enthalten:

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 {
  // Hier können Methoden von BlockPluginInterface überschrieben werden.
}

Die Eigenschaft id in der Annotation definiert die eindeutige maschinenlesbare ID Ihres Blocks und den Blocknamen, der im Code sichtbar ist. Die Annotation admin_label definiert den lesbaren Namen des Blocks, der in der Verwaltungsoberfläche angezeigt wird. Verfügbare Annotationseigenschaften finden Sie in \Drupal\Core\Block\Annotation\Block (öffentliche Eigenschaften).

Die zwei am häufigsten überschriebenen Methoden sind:

• BlockPluginInterface::build() – diese muss ein Render-Array zurückgeben, das den Inhalt definiert, den Ihr Block anzeigen soll.
• BlockBase::access() – diese steuert die Sichtbarkeit des Blocks. Sie sollte ein AccessResult-Objekt zurückgeben.

Benutzerdefinierte Konfigurationsoptionen zu Ihrem Block hinzufügen

Sie können auch benutzerdefinierte Konfigurationsoptionen zur Block-Konfigurationsform hinzufügen, indem Sie die Methoden BlockPluginInterface::blockForm() und BlockPluginInterface::blockSubmit() überschreiben und dann BlockBase::setConfigurationValue() und BlockBase::getConfiguration() verwenden.

Im folgenden Beispiel fügen wir ein neues Textfeld in blockForm() hinzu und speichern die Benutzereingabe in blockSubmit(). Der Code zeigt, wie Werte beim Aufbau des Formulars gelesen, validiert und aktualisiert werden.

use Drupal\Core\Block\BlockBase;
use Drupal\Core\Block\BlockPluginInterface;
use Drupal\Core\Form\FormStateInterface;
use Drupal\Core\Access\AccessResult;
use Drupal\Core\Cache\Cache;

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

  // Zugriffsmethode hier ...

  /**
   * {@inheritdoc}
   */
  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]),
    ];
  }

  /**
   * {@inheritdoc}
   */
  public function blockForm($form, FormStateInterface $form_state) {
    $form = parent::blockForm($form, $form_state);

    // Vorhandene Konfiguration laden.
    $config = $this->getConfiguration();

    // Formularfeld zur Block-Konfiguration hinzufügen.
    $form['fax_number'] = [
      '#type' => 'textfield',
      '#title' => $this->t('Fax number'),
      '#default_value' => isset($config['fax_number']) ? $config['fax_number'] : '',
    ];

    return $form;
  }

  /**
   * {@inheritdoc}
   */
  public function blockSubmit($form, FormStateInterface $form_state) {
    // Speichert die benutzerdefinierte Einstellung bei Formularübermittlung.
    $this->setConfigurationValue('fax_number', $form_state->getValue('fax_number'));
  }

  /**
   * {@inheritdoc}
   */
  public function blockValidate($form, FormStateInterface $form_state) {
    $fax_number = $form_state->getValue('fax_number');

    if (!is_numeric($fax_number)) {
      $form_state->setErrorByName('fax_number', $this->t('Needs to be an integer'));
    }
  }
}

Sie können auch BlockBase::getConfiguration() in build() verwenden, um Konfigurationsdaten zu erhalten und Ihren Nutzern anzuzeigen. Die Methode access() kann auch komplexere Logik enthalten, um zu bestimmen, ob der Block angezeigt werden soll.

Beispiel einer Zugriffsmethode:

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

Sie können auch eigene Cache-Bedingungen definieren.

Beispiel für die Nutzung von Cache-Tags. Mehr zu Cache-Tags erfahren Sie hier.

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

Wenn Sie die maximale Cache-Dauer des Blocks auf 0 setzen möchten. Mehr über max-age:

public function getCacheMaxAge() {
  // Wenn Sie das Caching für diesen Block deaktivieren möchten.
  return 0;
}