Création de réglages avancés pour le thème

Dans la section d’administration de Drupal, chaque thème possède sa propre page de réglages accessible à l’adresse admin/Appearance/Settings/themeName. Cette page contient un formulaire avec des réglages standards, tels que « Réglages de l’image du logo » et « Réglages de l’icône du favicon ».

Dans Drupal 8, les thèmes peuvent modifier l’ensemble du formulaire de réglages du thème en ajoutant une fonction PHP soit dans le fichier THEMENAME.theme, soit dans le fichier theme-settings.php. Dans l’un de ces fichiers, le thème doit utiliser la fonction d’extension THEMENAME_form_system_theme_settings_alter(&$form, $form_state). Voir la « Documentation API des formulaires dans Drupal 8 » ainsi que la liste complète des éléments Form et Render, et la documentation hook_form_FORM_ID_alter() pour découvrir la flexibilité complète de l’API des formulaires.

Voici un exemple : si votre thème s’appelle « foo » et que vous souhaitez ajouter un champ texte avec une valeur par défaut « blue bikeshed », ajoutez ce qui suit dans le fichier foo/foo.theme ou dans foo/theme-settings.php :

function foo_form_system_theme_settings_alter(&$form, \Drupal\Core\Form\FormStateInterface $form_state, $form_id = NULL) {
  // Contournement d’un bug du core affectant les thèmes admin. Voir l’issue #943212.
  if (isset($form_id)) {
    return;
  }

  $form['foo_example'] = array(
    '#type'          => 'textfield',
    '#title'         => t('Widget'),
    '#default_value' => theme_get_setting('foo_example'),
    '#description'   => t("Place this text in the widget spot on your site."),
  );
}

Pour définir la valeur par défaut d’un élément ajouté au formulaire, vous devez ajouter dans le fichier config/install/THEME.settings.yml une ligne simple : SETTING_NAME: DEFAULT_VALUE. Pour notre thème foo, éditez foo/config/install/foo.settings.yml et ajoutez la ligne suivante :

foo_example: blue bikeshed

Dans n’importe quel fichier PHP de votre thème, vous pouvez récupérer la valeur définie par l’utilisateur en appelant :

$foo_example = theme_get_setting('foo_example');

Notez que les auteurs de thèmes peuvent créer des formulaires dynamiques complexes en utilisant l’API avancée des formulaires (autocomplétion, groupes de champs pliables, etc.).

Récupérer les valeurs des réglages dans les fichiers de votre thème

Pour utiliser un paramètre dans un fichier Twig, vous devez ajouter une nouvelle variable Twig en la passant via une fonction de prétraitement dans le fichier THEMENAME.theme.

$variables['varname'] = theme_get_setting('varname')

Par exemple, pour ajouter notre paramètre foo_example dans le fichier node.html.twig, ajoutez ce code dans foo.theme :

<?php
function foo_preprocess_node(&$variables) {
  $variables['foo_example'] = theme_get_setting('foo_example');
}

Puis dans node.html.twig, vous pouvez accéder à foo_example comme toute variable Twig classique :

{{ foo_example }}

Plus d’informations

Voir les notes de mise à jour pour Drupal 8 : https://www.drupal.org/node/2382645