Personnalisation du constructeur de mise en page. Créer une mise en page personnalisée dans Drupal

Après avoir ajouté le modèle, nous devrions être en mesure d'ajouter facilement notre section :

Définition du plugin Layout

Du point de vue de l'utilisateur final, nous n'avons rien fait jusqu'à présent, car l'éditeur de contenu ne verra que le nouveau titre de la section avec le grand préfixe [CUSTOM]. Cela est dû au fait que la section que nous avons ajoutée fonctionne de manière identique à la section par défaut, fournie avec le module Layout Builder (avec une petite exception : notre implémentation n'ajoute pas de classes). Pour changer son comportement, nous devons implémenter un nouveau plugin de mise en page.

Cadre de la classe de base

La classe doit se trouver dans le dossier src/Plugin/Layout. Elle sera suffisamment générique pour pouvoir être utilisée pour tout nombre de régions. La classe Drupal\Core\Layout\LayoutDefault contient de nombreuses méthodes de base et implémente les interfaces nécessaires. Pour ne pas réinventer la roue, nous pouvons l'étendre dans notre classe.

# nom du fichier : CustomLayoutClassBase.php

<?php

namespace Drupal\custom_layout_builder\Plugin\Layout;

use Drupal\Core\Layout\LayoutDefault;

/**
 * Classe de base de nos mises en page personnalisées avec des classes HTML configurables.
 *
 * @internal
 *   Les classes de plugins sont internes.
 */
class CustomLayoutClassBase extends LayoutDefault {

}

Ajout d'options de configuration à une classe de base

L'une des exigences est la possibilité de sélectionner une classe pour la balise enveloppant les régions de la section. Pour y parvenir, nous devons d'abord remplacer la méthode defaultConfiguration et y ajouter une nouvelle option de configuration.

/**
 * {@inheritdoc}
 */
public function defaultConfiguration() {
  $configuration = parent::defaultConfiguration();

  return $configuration + [
    'wrapper_classes' => '',
  ];
}

Ensuite, nous devrions ajouter la possibilité de spécifier une valeur pour cette option de configuration. Nous pouvons le faire en remplaçant les méthodes buildConfigurationForm et submitConfigurationForm.

/**
 * {@inheritdoc}
 */
public function buildConfigurationForm(array $form, FormStateInterface $form_state) {
  $form['wrapper_classes'] = [
    '#type' => 'textfield',
    '#title' => $this->t('Classes supplémentaires de l'enveloppe'),
    '#default_value' => $this->configuration['wrapper_classes'],
    '#description' => $this->t('Classes supplémentaires pour l'enveloppe. Tapez autant que vous le souhaitez, mais n'oubliez pas de les séparer par un espace.´),
  ];

  return parent::buildConfigurationForm($form, $form_state);
}

/**
 * {@inheritdoc}
 */
public function submitConfigurationForm(array &$form, FormStateInterface $form_state) {
  parent::submitConfigurationForm($form, $form_state);

  $this->configuration['wrapper_classes'] = $form_state->getValue('wrapper_classes');
}

S'il y a besoin d'ajouter une validation de formulaire, cela peut être fait en remplaçant la méthode validateConfigurationForm. Nous recommandons d'implémenter une validation pour ce champ, car les classes doivent être conformes à la norme de la communauté Drupal. La méthode Html::getClass() pourrait être utile dans ce cas.

Utilisation de la configuration pour construire des sections

Le tableau de rendu est créé dans la méthode build, c'est ce que nous allons maintenant remplacer. Si vous vous souvenez du contenu du modèle que nous avons ajouté, vous savez probablement déjà que nous ajoutons des classes à l'objet attributes.

/**
 * {@inheritdoc}
 */
public function build(array $regions): array {
  $build = parent::build($regions);
  $wrapper_classes = explode(' ', (string) $this->configuration['wrapper_classes']);
  $build['#attributes']['class'] = [...$wrapper_classes];

  return $build;
}

Utilisation de la base pour créer un plugin Layout

Notre classe est prête, il est temps de l'utiliser dans une section. Pour ce faire, revenons au fichier *.layouts.yml pour déclarer un nouveau plugin. Cela se fait en spécifiant l'intégralité du namespace de la classe sous la clé class.

# nom du fichier : custom_layout_builder.layouts.yml

layout_custom_one_column:
  label: '[CUSTOM] Une colonne'
  category: 'Mises en page personnalisées'
  path: layouts/custom_onecol_section
  template: layout--custom-onecol-section
  class: '\Drupal\custom_layout_builder\Plugin\Layout\CustomOneColLayout'
  default_region: first
  icon_map:
    - [first]
  regions:
    first:
      label: Première

Après avoir apporté les modifications ci-dessus, vous pouvez remarquer que le formulaire de la section dispose d'un nouveau champ et que les classes saisies dans ce champ sont au bon endroit dans le HTML.

Ajout de l'option pour sélectionner des classes pour les régions

Nous pouvons déjà définir une liste de classes pour l'élément enveloppeur dans notre section. Il est temps de réfléchir à la manière de créer la logique responsable de l'ajout de classes aux sections individuelles de notre mise en page. Nous devons prendre en considération l'extensibilité de notre classe de base. C'est pourquoi nous recommandons de baser la logique de détermination et d'accès aux régions sur la méthode getRegionNames() de la classe LayoutDefinition.

1. Tout d'abord, nous ajoutons un champ à notre formulaire pour chaque région :

/**
 * {@inheritdoc}
 */
public function buildConfigurationForm(array $form, FormStateInterface $form_state) {
  $form['wrapper_classes'] = [
    '#type' => 'textfield',
    '#title' => $this->t('Classes supplémentaires de l'enveloppe'),
    '#default_value' => $this->configuration['wrapper_classes'],
    '#description' => $this->t('Classes supplémentaires pour l'enveloppe. Tapez autant que vous le souhaitez, mais n'oubliez pas de les séparer par un espace.´),
  ];

  foreach ($this->getPluginDefinition()->getRegionNames() as $region_name) {
    $form['region_classes'][$region_name] = [
      '#type' => 'textfield',
      '#title' => $this->t('Classes supplémentaires pour la région @region_name', [
        '@region_name' => $region_name,
      ]),
      '#default_value' => $this->configuration['region_classes'][$region_name],
      '#description' => $this->t('Classes supplémentaires pour l'enveloppe de la région @region_name. Tapez autant que vous le souhaitez, mais n'oubliez pas de les séparer par un espace.´, [
        '@region_name' => $region_name,
      ]),
    ];
  }

  return parent::buildConfigurationForm($form, $form_state);
}

2. Nous utilisons une boucle similaire pour écrire la valeur :

/**
 * {@inheritdoc}
 */
public function submitConfigurationForm(array &$form, FormStateInterface $form_state) {
  parent::submitConfigurationForm($form, $form_state);

  $this->configuration['wrapper_classes'] = $form_state->getValue('wrapper_classes');

  foreach ($this->getPluginDefinition()->getRegionNames() as $region_name) {
    $this->configuration['region_classes'][$region_name] = $form_state->getValue(['region_classes', 
$region_name], '');
      }
}

3. La dernière étape consistera à remplacer la méthode build et à intégrer nos classes dans l'objet de la classe Attributes approprié.

/**
 * {@inheritdoc}
 */
public function build(array $regions): array {
  $build = parent::build($regions);
  $wrapper_classes = explode(' ', (string) $this->configuration['wrapper_classes']);
  $build['#attributes']['class'] = [...$wrapper_classes];

  foreach (array_keys($regions) as $region_name) {
    $region_classes = explode(' ', (string) $this->configuration['region_classes'][$region_name]);
    $build[$region_name]['#attributes']['class'] = [...$region_classes];
  }

  return $build;
}

Après nos dernières modifications, nous devrions voir un nouveau champ Classes supplémentaires pour la première région où nous pouvons fournir une liste de classes que nous voulons utiliser.

Gardez à l'esprit que la région ne s'affichera que si elle n'est pas vide. C'est pourquoi nous avons ajouté un bloc test contenant le titre du nœud. Voyons si les classes sont visibles dans le HTML.

Création de différentes variantes de sections

Le code a été écrit de manière si générique que l'ajout d'une section avec un nombre différent de régions nécessite uniquement de définir la région et le modèle de notre part. Ajoutons alors une nouvelle section contenant deux régions.

Tout d'abord, nous ajoutons la définition :

# nom du fichier : custom_layout_builder.layouts.yml

layout_custom_one_column:
  label: '[CUSTOM] Une colonne'
  category: 'Mises en page personnalisées'
  path: layouts/custom_onecol_section
  template: layout--custom-onecol-section
  class: '\Drupal\custom_layout_builder\Plugin\Layout\CustomLayoutClassBase'
  default_region: first
  icon_map:
    - [first]
  regions:
    first:
      label: Première
layout_custom_two_columns:
  label: '[CUSTOM] Deux colonnes'
  category: 'Mises en page personnalisées'
  path: layouts/custom_twocol_section
  template: layout--custom-twocol-section
  class: '\Drupal\custom_layout_builder\Plugin\Layout\CustomLayoutClassBase'
  default_region: first
  icon_map:
    - [first, second]
  regions:
    first:
      label: Première
    second:
      label: Deuxième

Ensuite, nous préparons le modèle :

# nom du fichier : layout--custom-twocol-section.html.twig

{#
/**
 * @file
 * Implémentation par défaut pour une section de mise en page personnalisée à une colonne.
 *
 * Variables disponibles :
 * - content : Le contenu pour cette mise en page.
 * - attributes : Attributs HTML pour la disposition <div>.
 * - region_attributes : Attributs HTML pour la région <div>.
 * - settings : Un tableau de paramètres configurés pour la disposition.
 *
 * @ingroup themeable
 */
#}
{% if content %}
  <div{{ attributes }}>

    {% if content.first %}
      <div {{ region_attributes.first }}>
        {{ content.first }}
      </div>
    {% endif %}

    {% if content.second %}
      <div {{ region_attributes.second }}>
        {{ content.second }}
      </div>
    {% endif %}

  </div>
{% endif %}