Creazione di impostazioni avanzate del tema

Nella sezione di amministrazione di Drupal ogni tema ha la propria pagina di impostazioni all’indirizzo admin/Appearance/Settings/themeName. Questa pagina contiene un form con impostazioni standard come “Impostazioni dell’immagine del logo” e “Impostazioni dell’icona favicon”.

In Drupal 8 i temi possono modificare l’intero form delle impostazioni del tema aggiungendo una funzione PHP nel file THEMENAME.theme oppure nel file theme-settings.php. In uno di questi file il tema deve utilizzare la funzione di hook THEMENAME_form_system_theme_settings_alter(&$form, $form_state). Vedi “API dei form in Drupal 8” e l’elenco completo degli elementi Form e render, oltre alla documentazione di hook_form_FORM_ID_alter() per comprendere la piena flessibilità delle API dei form.

Ecco un esempio: se hai un tema “foo” e vuoi aggiungere un campo di testo con valore predefinito “blue bikeshed”, aggiungi quanto segue nel file foo/foo.theme oppure in foo/theme-settings.php:

function foo_form_system_theme_settings_alter(&$form, \Drupal\Core\Form\FormStateInterface $form_state, $form_id = NULL) {
  // Soluzione temporanea per un bug core che riguarda i temi di amministrazione. Vedi 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("Inserisci questo testo nello spazio widget del tuo sito."),
  );
}

Per impostare un valore predefinito per qualsiasi elemento di form aggiunto, è necessario aggiungere un file config/install/THEME.settings.yml con una semplice stringa: SETTING_NAME: DEFAULT_VALUE. Per il nostro tema foo, devi modificare il file foo/config/install/foo.settings.yml e aggiungere la seguente riga:

foo_example: blue bikeshed

In qualsiasi file PHP del tuo tema puoi ottenere il valore impostato dall’utente richiamando:

$foo_example = theme_get_setting('foo_example');

Nota che gli autori di temi possono creare form dinamici complessi utilizzando le API dei form avanzate (autocomplete, fieldset collassabili).

Recuperare i valori delle impostazioni nei file del tuo tema

Per utilizzare un’impostazione in un file Twig, è necessario aggiungere una nuova variabile al file Twig, inserendola tramite una funzione di preprocess nel file THEMENAME.theme. 

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

Ad esempio, per aggiungere il nostro parametro foo_example al file node.html.twig, aggiungilo al file foo.theme:

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

Quindi, nel file node.html.twig puoi accedere a foo_example come a qualsiasi normale variabile Twig:

{{foo_example}}

Ulteriori informazioni

Vedi la change record per Drupal 8: https://www.drupal.org/node/2382645