Definizione e utilizzo della propria configurazione in Drupal 8
Tema principale: definizione della propria configurazione
Puoi includere configurazioni predefinite nel tuo modulo, basandoti sulla funzionalità di altri moduli (tipi di nodo, viste, campi, formati di testo, ecc.).
Ad esempio, il modulo Node fornisce la configurazione di un tipo di nodo, quindi nel tuo modulo puoi impostare un tipo di nodo predefinito che sarà distribuito con il tuo modulo.
Potresti voler definire una configurazione per i tuoi plugin, entità e impostazioni, che a loro volta possono essere usati da altri moduli, così come tu puoi utilizzare la configurazione dei tipi di contenuto del modulo Node. Drupal 8 semplifica la definizione della tua parte di configurazione.
File di configurazione
I file di configurazione per il tuo modulo si trovano nella sottocartella config/install del tuo modulo. Ad esempio, /modules/example/config/install/example.settings.yml, se il tuo modulo si trova in /modules/example. Puoi posizionare qui i file di configurazione del tuo modulo usando il formato YAML.
example.settings.yml per le impostazioni di configurazione, ad esempio. Non chiamare il file settings.yml o system.settings.yml, poiché questo può andare in conflitto con altri file di configurazione. Se non segui questa convenzione, comandi Drush come drush config:import potrebbero confondersi.
Questo ti consente anche di fornire configurazioni per altri componenti, ad esempio un tipo di nodo di esempio, includendo configurazioni predefinite nel tuo modulo, dove il file di configurazione sarà node.type.example_mytype.yml, identificato come configurazione di un tipo di nodo dal modulo Node.
Il nome del file di configurazione (esclusa l’estensione .yml) è chiamato anche nome della configurazione nel sistema, ed è così che puoi fare riferimento alla tua configurazione tramite le API PHP.
Struttura del file di configurazione
Il file di configurazione deve usare il formato YAML. Puoi strutturarlo come desideri, senza limitazioni oltre al formato YAML stesso. Ad esempio, se ti serve un parametro per mostrare qualcosa di specifico dal tuo controller di pagina, il file può contenere una chiave message con un valore testuale:
message: 'Hello' langcode: 'en'
Si consiglia di includere il codice lingua sotto la chiave langcode. Questo viene usato dal sistema delle lingue per proporre il testo traducibile. La chiave langcode è riservata a questo scopo e non deve essere usata per altro al livello principale del file.
Per tradurre la configurazione, deve essere abilitato il modulo Config Translation.
Per rendere la configurazione traducibile, occorre aggiungere altri due file:
- /modules/example/config/schema/example.schema.yml
- /modules/example/example.config_translation.yml
Il primo definisce lo schema della configurazione personalizzata. Definiamo example.settings come un config_object che contiene più campi. Ogni campo ha un tipo: la definizione del tipo base determina se il campo sarà traducibile o meno (vedi core.data_types.schema.yml). Ad esempio, path, che contiene un percorso interno di Drupal, non è traducibile, mentre text lo è.
# /modules/example/config/schema/example.schema.yml
example.settings:
type: config_object
label: 'Example config'
mapping:
message:
type: text
label: 'Message'
Il secondo aggiunge un collegamento a /admin/config/regional/config-translation nel relativo form di traduzione:
# /modules/example/example.config_translation.yml
example.admin.config:
title: 'Example module'
base_route_name: example.admin.config
names:
- example.settings
Per convenzione, la chiave corrisponde al nome della route di base: example.admin.config è il nome della route del form di configurazione admin del tuo modulo. names elenca tutte le chiavi di configurazione modificate dal form, in questo caso la configurazione personalizzata definita nello schema sopra.
Il file può includere liste più complesse e coppie chiave/valore strutturate ad albero. Vedi, ad esempio, il file views.view.content.yml come esempio di configurazione più articolata.
La traduzione della configurazione aggiunge automaticamente la scheda “Traduzione modulo” al form di configurazione del modulo, tuttavia potrebbe non apparire se questa è l’unica scheda disponibile. Per aggiungere la scheda “Predefinito” al form di configurazione, dobbiamo aggiungere un altro file example.links.task.yml. (Vedi Local tasks definiti dai moduli.)
# example.links.task.yml example.admin.config: route_name: example.admin.config title: Settings base_route: example.admin.config
Utilizzo della configurazione
Drupal 8 fornisce una PHP API per leggere e scrivere questa configurazione. Il modo più semplice per utilizzarla è il metodo statico Drupal::config():
$config = \Drupal::config('example.settings');
// Stampa 'Hello'.
print $config->get('message');
// Stampa 'en'.
print $config->get('langcode');
Se vuoi modificare la configurazione e aggiornarla con un nuovo valore, puoi usare il metodo \Drupal::service('config.factory')->getEditable():
$config = \Drupal::service('config.factory')->getEditable('example.settings');
// Imposta e salva un nuovo valore per message.
$config->set('message', 'Hi')->save();
// Ora stamperà 'Hi'.
print $config->get('message');