Impostazioni tema
Panoramica
Le Impostazioni tema permettono al designer di definire alcuni settaggi specifici del tema che l'utente può modificare nella sezione omonima del pannello. Nella pagina, definita all'interno della vista settings.html, sarà presente un form i cui campi verranno salvati in theme.settings
alla validazione.
Le impostazioni tema possono essere differenti per ogni lingua, inoltre sono l'unica vista che il designer può mostrare all'interno del pannello, per questo viene utilizzato un differente file per le etichette, admin.php, ed è consigliabile creare un differente file CSS admin.css.
Implementazione
Creazione di una pagina settings.html
Il file settings.html non si integra direttamente a nessun'altra vista del tema, esso infatti utilizza blocchi, etichette e stili CSS a parte. Per questo motivo l'intestazione del file presenterà l'estensione del blocco cms::admin.themes.settings
e il blocco admin_styles
per includere lo stile del pannello ed, eventualmente, un file CSS aggiuntivo definito dal designer.
{% extends 'cms::admin.themes.settings' %} {% block admin_styles %} {{ parent() }} {{ theme.style('css/admin.css') }} {# Eventuale file CSS aggiuntivo #} {% endblock %}
Il pannello di SelfComposer utilizza di base Bootstrap 3 ed è quindi possibile fare uso dei suoi componenti. Inoltre si consiglia di utilizzare uno stile consono con il resto del pannello per evitare confusione da parte di chi lo utilizza.
Il contenuto della pagina va inserito nel blocco settings_body
in cui andremo a creare un form con il tag form_model
in questo modo:
{{ form_model(theme.settings) }} ... {# contenuto del form #} {{ form_save() }} {# pulsante di "submit" per salvare le impostazioni #} {{ form_close() }}
All'interno del form possiamo creare i campi attraverso le funzioni previste nel pannello. Con form_group()
possiamo generare l'HTML di un campo con la sua label, i suoi parametri sono:
Nome | Tipo | Descrizione |
---|---|---|
label | string | Etichetta per il campo in lingua, può fare riferimento a quelle definite in admin.php |
field | oggetto field | Il campo, o la funzione per generarlo (descritta successivamente) |
params | array | Array di parametri |
I campi (field
) possono essere di diverso tipo e vengono generati con queste funzioni:
form_page()
per far selezionare una pagina all'utente ed estrarne l'idform_fileManager()
per selezionare il file (ritorna la path)form_picture()
per selezionare un'immagine (ritorna la path)form_gallery()
per selezionare una serie di immagini (ritorna un array con la path dei file)form_date()
per selezionare una dataform_time()
per selezionare un orarioform_datetime()
per selezionare data e oraform_color()
per selezionare un colore (in formato #FFFFFF)form_code()
per mostrare un campo editor di codiceform_wysi()
per mostrare un editor di testo WYSIWYG come quello della descrizioneform_wysiSimple()
per un editor WYSIWYG semplificato con meno opzioni
Tutte queste funzioni hanno gli stessi parametri:
Nome | Tipo | Descrizione |
---|---|---|
name | string | Nome del campo (che sarà il nome del parametro di theme.settings da estrarre) |
value | (dipende dal campo) | Valore del campo (può essere riempito per inserire un valore di default) |
attributes | array | Attributi aggiuntivi del campo |
Un esempio di campo con etichetta può quindi essere generato così:
{{ form_group('theme::admin.fields.logo', form_picture('logo')) }}
I valori dei campi all'interno del form verranno salvati con il loro nome nell'oggetto theme.settings.NOMECAMPO
che può essere estratto in tutte le view del tema.
È possibile anche creare un form i cui valori siano diversi per ogni lingua, come mostrato nel paragrafo successivo.
Creare impostazioni del tema con valori diversi per lingua
Attenzione: questo metodo funziona solo dalla versione di Selfcomposer 3.2.12
Se si ha la necessità di avere impostazioni diverse per ogni lingua del tema attiva, basterà aggiungere il tag {{ form_language(null, { name: 'lang_code' }) }}
all'interno del form, che farà comparire il selettore della lingua. Finché il form non viene salvato, le impostazioni tema rimangono multilingua, poi modificando una lingua, le impostazioni tema si modificheranno solo per essa, e quindi verranno estratte in modo differente in base alla lingua scelta da chi naviga il sito.
{{ form_model(theme.settings) }} {{ form_language(null, { name: 'lang_code' }) }} {# ... contenuti del form ... #} {{ form_close() }}
Utilizzo delle impostazioni in front-end
Il valore di ogni campo del form di settings.html può essere richiamato all'interno di qualsiasi vista del tema utilizzando theme.settings('NOME CAMPO')
.
È possibile anche specificare un valore di default che verrà utilizzato se al campo non ne è associato uno, in questo modo: theme.settings('NOME CAMPO', 'VAL DI DEFAULT')
.
Infine, se si è utilizzato un form con valori diversi per ogni lingua nelle impostazioni tema, il valore dei campi viene richiamato con l'utilizzo del terzo parametro, ovvero il codice lingua delle impostazioni da richiamare. Si può quindi utilizzare lang.code
per estrarre le impostazioni della lingua attualmente attiva, o un codice lingua in particolare.
{{ theme.settings('NOME CAMPO', 'VAL DI DEFAULT', lang.code) }}
Esempio
Creazione di un form immagine per l'inserimento di un logo nel tema
In questo esempio verrà creato un file di impostazioni tema con un campo che permette la scelta da parte dell'utente di un'immagine dalla gestione file e di mostrarlo all'interno del tema.
Inizializziamo settings.html con il blocco degli stili admin_styles
e quello dei contenuti settings_body
.
{% extends 'cms::admin.themes.settings' %} {% block admin_styles %} {{ parent() }} {{ theme.style('css/admin.css') }} {% endblock %} {% block settings_body %}
All'interno di settings_body
andiamo a definire una struttura base. Per questo esempio utilizzeremo alcune classi del pannello che abbiamo importato in precedenza (di base SelfComposer utilizza Bootstrap 3), in modo da allinearci alla grafica del pannello. Inseriamo quindi il titolo del tema all'interno di un blocco, dentro inizializziamo il form:
{% block settings_body %} <div class="row"> <div class="col-md-8 col-md-offset-2"> <div class="page-header"> <h3 class="text-center">{{ theme.info.name }}</h3> {# Titolo del tema #} </div> {{ form_model(theme.settings, { class: 'form-horizontal' }) }} {# Inizializzazione form #}
Nel form appena aperto inseriamo un campo immagine, con la funzione form_picture()
, attraverso il quale l'utente potrà scegliere un file dalla Gestione File. Aggiungiamo poi un <div>
con parametro data-field
che ha per valore il nome del campo, qui comparirà l'immagine selezionata dall'utente. Aggiungiamo alla struttura un'etichetta per il titolo del pannello, oltre a quella del campo immagine (che abbiamo chiamato logo
).
{{ form_model(theme.settings, { class: 'form-horizontal' }) }} <div class="panel panel-default"> <div class="panel-heading"> <h3 class="panel-title">{{ lang_get('theme::admin.appearance') }}</h3> {# Titolo del pannello #} </div> <div class="panel-body"> {{ form_group('theme::admin.fields.logo', form_picture('logo')) }} {# Form immagine 'logo' con etichetta relativa #} <div class="row"> <div class="col-md-10 col-md-offset-3 col-lg-offset-2"> <div class="picture-preview" data-field="logo"></div> {# Campo con data-field per l'anteprima dell'immagine scelta nel campo 'logo' #} </div> </div> </div> </div>
A questo punto possiamo chiudere il form, inserendo però prima il pulsante di submit con la funzione form_save()
.
{{ form_save() }} {{ form_close() }} </div> </div> {% endblock %}
Andiamo quindi a impostare in admin.php il valore delle due etichette che abbiamo utilizzato. La prima sarà theme::admin.appearance
, seguita da theme::admin.fields.logo
che fa parte di fields
.
<?php return [ 'appearance' => 'Aspetto', 'fields' => [ 'logo' => 'Logo', ], ];
Una volta scelta l'immagine potremmo richiamare il suo URL all'interno del tema con theme.settings('logo')
.