Jak stworzyć niestandardowy layout? Dostosowanie Layout Buildera w Drupalu

Po dodaniu szablonu powinniśmy móc bez przeszkód dodać swoją sekcję:

Definiowanie wtyczki Layoutu

Patrząc od strony użytkownika końcowego, można powiedzieć, że do tej pory nie zrobiliśmy nic, bo redaktor treści zobaczy jedynie nowy tytuł sekcji z wielkim prefixem [CUSTOM]. Jest tak dlatego, że sekcja którą dodaliśmy działa identycznie, co domyślna, dostarczona wraz z modułem Layout Builder (z małym wyjątkiem - nasza implementacja nie dodaje żadnych klas). Aby zmienić jej zachowanie, należy zaimplementować nowy layout plugin.

Szkielet klasy bazowej

Klasa powinna znaleźć się w folderze src/Plugin/Layout. Będzie na tyle generyczna, że może zostać wykorzystana dla dowolnej liczby regionów. Klasa Drupal\Core\Layout\LayoutDefault zawiera wiele bazowych metod i implementuje potrzebne interfejsy. Aby nie wymyślać koła na nowo, rozszerz ją w swojej klasie.

# nazwa pliku: CustomLayoutClassBase.php

<?php

namespace Drupal\custom_layout_builder\Plugin\Layout;

use Drupal\Core\Layout\LayoutDefault;

/**
 * Base class of our custom layouts with configurable HTML classes.
 *
 * @internal
 *   Plugin classes are internal.
 */
class CustomLayoutClassBase extends LayoutDefault {

}

Dodanie opcji konfiguracyjnych do klasy bazowej

Jednym z wymagań jest możliwość wybrania klasy dla taga wrapującego regiony sekcji. Aby to osiągnąć, należy w pierwszej kolejności nadpisać metodę defaultConfiguration i dodać do niej nową opcję konfiguracyjną.

/**
 * {@inheritdoc}
 */
public function defaultConfiguration() {
  $configuration = parent::defaultConfiguration();
  return $configuration + [
    'wrapper_classes' => '',
  ];
}

Następnie należy też dać możliwość podania wartości dla tej opcji konfiguracyjnej. Możemy to zrobić nadpisując metody buildConfigurationForm oraz submitConfigurationForm.

/**
 * {@inheritdoc}
 */
public function buildConfigurationForm(array $form, FormStateInterface $form_state) {
  $form['wrapper_classes'] = [
    '#type' => 'textfield',
    '#title' => $this->t('Wrapper extra classes'),
    '#default_value' => $this->configuration['wrapper_classes'],
    '#description' => $this->t('Extra wrapper classes. Type as many as you want but remember to separate them by using a single space character.'),
  ];
  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');
}

Jeśli zaistnieje potrzeba dopisania walidacji formularza, można to zrobić nadpisując metodę validateConfigurationForm. Rekomendujemy implementację walidacji dla tego pola, gdyż klasy powinny być zgodne ze standardem określonym przez Community Drupala. Może się przydać w tym przypadku metoda Html::getClass().

Wykorzystanie konfiguracji do budowania sekcji

Tablica renderowania jest budowana w metodzie build i to właśnie jej nadpisaniem teraz się zajmiemy. Jeśli pamiętasz zawartość szablonu, który dodaliśmy, to pewnie wiesz już, że klasy dodajemy do obiektu 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;
}

Użycie bazy do stworzenia Layout Pluginu

Nasza klasa jest już gotowa, pora na użycie jej w sekcji. W tym celu należy wrócić do pliku *.layouts.yml, żeby zadeklarować nowy plugin. Robi się to podając pełny namespace klasy pod kluczem class.

# nazwa pliku: custom_layout_builder.layouts.yml

layout_custom_one_column:
  label: '[CUSTOM] One column'
  category: 'Custom layouts'
  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: First

Po wprowadzeniu powyższych zmian możesz zauważyć, że formularz sekcji posiada nowe pole oraz że klasy wpisane w to pole znajdują się w odpowiednim miejscu w HTML-u.

Dodanie opcji wyboru klas dla regionów

Możemy już definiować listę klas dla elementu wrapującego w swojej sekcji. Pora zastanowić się, jak stworzyć logikę, odpowiadającą za dodanie klas do poszczególnych sekcji naszego layoutu. Należy wziąć pod uwagę rozszerzalność naszej klasy bazowej. Z tego powodu rekomendujemy oparcie logiki określania i dostępu do regionów na podstawie metody getRegionNames() z klasy LayoutDefinition.

1. Najpierw dodajemy po jednym polu do naszego formularza dla każdego regionu:

/**
 * {@inheritdoc}
 */
public function buildConfigurationForm(array $form, FormStateInterface $form_state) {
  $form['wrapper_classes'] = [
    '#type' => 'textfield',
    '#title' => $this->t('Wrapper extra classes'),
    '#default_value' => $this->configuration['wrapper_classes'],
    '#description' => $this->t('Extra wrapper classes. Type as many as you want but remember to separate them by using a single space character.'),
  ];

  foreach ($this->getPluginDefinition()->getRegionNames() as $region_name) {
    $form['region_classes'][$region_name] = [
      '#type' => 'textfield',
      '#title' => $this->t('Extra classes for @region_name region', [
        '@region_name' => $region_name,
      ]),
      '#default_value' => $this->configuration['region_classes'][$region_name],
      '#description' => $this->t('Extra classes for the @region_name region wrapper. Type as many as you want but remember to separate them by using a single space character.', [
        '@region_name' => $region_name,
      ]),
    ];
  }

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

2. Używamy analogicznej pętli do zapisu wartości:

/**
 * {@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. Ostatnim krokiem będzie nadpisanie metody build i osadzenie naszych klas w odpowiednim obiekcie klasy 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];

  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;
}

Po naszych najnowszych zmianach powinniśmy ujrzeć nowe pole Extra classes for first region, w którym możemy podać listę klas, które chcemy użyć.

Należy pamiętać, że region pojawi się wyłącznie w przypadku, w którym nie będzie pusty. Z tego powodu dodaliśmy testowo blok zawierający tytuł node’a. Zobaczmy, czy klasy są widoczne w HTML-u.

Tworzenie różnych wariantów sekcji

Kod został napisany w na tyle generyczny sposób, że dodanie sekcji z inną liczbą regionów wymaga od nas wyłącznie definicji regionu oraz szablonu. Dodajmy więc nową sekcję zawierającą dwa regiony.

Najpierw dodajemy definicję:

# nazwa pliku: custom_layout_builder.layouts.yml

layout_custom_one_column:
  label: '[CUSTOM] One column'
  category: 'Custom layouts'
  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: First
layout_custom_two_columns:
  label: '[CUSTOM] Two columns'
  category: 'Custom layouts'
  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: First
    second:
      label: Second

A następnie przygotowujemy szablon:

# nazwa pliku: layout--custom-twocol-section.html.twig

{#
/**
 * @file
 * Default implementation for a custom layout onecol section.
 *
 * Available variables:
 * - content: The content for this layout.
 * - attributes: HTML attributes for the layout <div>.
 * - region_attributes: HTML attributes for the region <div>.
 * - settings: An array of configured settings for the layout.
 *
 * @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 %}

Sekcja powinna być już dostępna.

Formularz konfiguracji powinien dopasować się automatycznie do liczby regionów.

Po konfiguracji formularza, a także dodaniu testowych danych, możemy zobaczyć wynik naszej operacji w HTML-u.