Bloc API

Présentation générale

Les blocs dans Drupal 8 consistent en réalité en deux structures API distinctes, afin de recréer une interface utilisateur similaire à celle des versions précédentes de Drupal. Ces deux API sont : le Block Plugin API, une API autonome pour la réutilisation, et le Block Entity API, spécifique à Drupal 8 pour le placement des blocs et le contrôle de leur visibilité.

Création de blocs avec le Block Plugin API

Pour créer des blocs définis dans le code de votre module, vous devez comprendre l’API des plugins, en particulier la découverte via les plugins basés sur annotations, mécanisme utilisé par Drupal 8 pour détecter les classes définissant vos blocs.

La création d’un bloc personnalisé défini par votre module suit ces étapes :

• Créer un plugin de bloc via des annotations
• Étendre la classe Drupal\Core\Block\BlockBase
• Implémenter les méthodes de l’interface Drupal\Core\Block\BlockPluginInterface nécessaires pour votre usage

Rendre votre bloc visible dans Drupal et pour les utilisateurs

Drupal utilise la norme PSR-4 pour la découverte. Supposons que votre module s’appelle « fax », le code du bloc doit se trouver dans fax/src/Plugin/Block/. Chaque fichier doit porter le nom de la classe contenue. Par exemple, la classe FaxBlock doit être dans fax/src/Plugin/Block/FaxBlock.php :

namespace Drupal\fax\Plugin\Block;

use Drupal\Core\Block\BlockBase;

/**
 * Fournit un bloc 'Fax'.
 *
 * @Block(
 *   id = "fax_block",
 *   admin_label = @Translation("Fax block"),
 * )
 */
class FaxBlock extends BlockBase {
  // Redéfinissez ici les méthodes de BlockPluginInterface.
}

Le champ id dans l’annotation définit l’identifiant machine unique du bloc, visible par le code. L’annotation admin_label définit le nom lisible affiché dans l’interface d’administration. Les propriétés disponibles sont documentées dans \Drupal\Core\Block\Annotation\Block.

Les deux méthodes les plus courantes à redéfinir :

• BlockPluginInterface::build() doit retourner un tableau de rendu définissant le contenu du bloc.
• BlockBase::access() contrôle la visibilité du bloc, et doit retourner un objet AccessResult.

Ajouter des paramètres de configuration personnalisés à votre bloc

Vous pouvez ajouter des paramètres personnalisés dans le formulaire de configuration du bloc en redéfinissant blockForm() et blockSubmit(), puis en utilisant setConfigurationValue() et getConfiguration().

Exemple : ajout d’un champ texte dans blockForm() et sauvegarde dans blockSubmit() :

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

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

  /**
   * {@inheritdoc}
   */
  public function build() {
    $config = $this->getConfiguration();
    $fax_number = isset($config['fax_number']) ? $config['fax_number'] : '';
    return [
      '#markup' => $this->t('Le numéro de fax est @number!', ['@number' => $fax_number]),
    ];  
  }

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

    $config = $this->getConfiguration();

    $form['fax_number'] = [
      '#type' => 'textfield',
      '#title' => $this->t('Numéro de fax'),
      '#default_value' => isset($config['fax_number']) ? $config['fax_number'] : '',
    ];
    
    return $form;
  }

  /**
   * {@inheritdoc}
   */
  public function blockSubmit($form, FormStateInterface $form_state) {
    $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('Doit être un nombre entier'));
    }
  }
}

Vous pouvez utiliser getConfiguration() dans build() pour récupérer les données configurées et les afficher. Le méthode access() peut contenir une logique plus complexe pour déterminer la visibilité du bloc.

Exemple simple de méthode d’accès :

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

Vous pouvez aussi définir vos propres règles de cache.

Exemple d’ajout de tags de cache. Pour en savoir plus, voir les tags de cache.

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

Pour modifier la durée maximale du cache à zéro (désactiver le cache) :

public function getCacheMaxAge() {
  // Désactive le cache pour ce bloc.
  return 0;
}