Personalizzazione di IonicUI

In quest’ultimo paragrafo vedremo quali tecniche sono previste per personalizzare la resa grafica delle applicazioni sviluppate con il framework IonicUI.

Il tema #

Il tema è un oggetto JavaScript condiviso tra la sessione di lavoro e il codice del browser che gestisce l’interfaccia dell’applicazione. Le proprietà del tema permettono di personalizzare l’aspetto e i comportamenti del framework IonicUI.

Le proprietà specifiche riconosciute dal tema IonicUI sono presenti nella classe IonTheme contenuta nella libreria IonicFramework e sono le seguenti:

1. ionPlatform: rappresenta la grafica di base dell’applicazione e può valere “md” per Material Design oppure “ios” per dispositivi Apple. Il valore predefinito viene calcolato automaticamente in base al dispositivo utilizzato, ma può essere modificato nell’evento onStart dell’applicazione, prima dell’apertura della prima videata.
2. primary: colore primario dell’applicazione. 
3. secondary: colore secondario dell’applicazione.
4. danger: colore utilizzato per messaggio di errore o azioni distruttive.
5. light: sfumatura di colore utilizzata per visualizzare elementi chiari.
6. dark: sfumatura di colore utilizzata per visualizzare elementi scuri.
7. bright: colore utilizzato per visualizzare elementi ad alto impatto visivo.
8. vibrant: colore alternativo utilizzato per visualizzare elementi ad alto impatto visivo.
9. focus: colore della sottolineatura di elementi che hanno il fuoco (usato se ionPlatform=”md”).
10. ionIcons: versione del set di icone da utilizzare. I possibili valori sono 4 e 5. Si consiglia di usare il valore 4.
11. iconSet: determina quale set di icone deve essere attivato. I possibili valori sono “md” e “ios” e il default è uguale ad ionPlatform.
12. tippy: parametri da passare al sistema di gestione dei tooltip tippy.js in formato oggetto JavaScript.
13. darkMode: attiva o meno il darkMode per la sessione. I possibili valori sono “true”, “false” e “auto”. Il default è “auto”.
14. darkPercent: percentuale di diminuzione della luminosità dei colori del tema quando si attiva il tema scuro. Default 0.30.
15. gmapKey: comunica al browser il valore della chiave gmap da utilizzare per visualizzare le mappe. Deve essere impostato prima di caricare una mappa per la prima volta e deve iniziare con “key=”. Ad esempio: “key=aIsalz3fg4…”.

È possibile modificare i parametri del tema sia a design time che da codice. Per modificare i parametri di tema a design time si deve procedere come segue:

1. Creare all’interno di una libreria una classe di tipo Tema che estende IonicFramework.IonTheme.
2. Inserire nella classe le proprietà con il nome corrispondente ai parametri del tema da modificare. Impostare quindi il valore iniziale di ogni proprietà al valore da assegnare alla corrispondente proprietà di tema.
3. Selezionando l’oggetto applicazione, impostare come proprietà Tema la classe tema appena creata.

A questo punto le proprietà del tema verranno applicate anche alle videate in anteprima nell’editor delle videate. Dopo aver modificato il valore di una proprietà del tema, può essere richiesto l’aggiornamento manuale dell’anteprima dell’editor delle videate.

La modifica di una proprietà di tema da codice è molto semplice. Se tale modifica avviene nell’evento onStart dell’applicazione è necessario solamente modificare l’oggetto app.theme. Ad esempio per modificare un colore del tema è possibile scrivere:

app.theme.secondary = “#51d677”;

In questo caso la modifica non sarà visibile nell’anteprima dell’editor delle videate ma solo quando l’applicazione viene lanciata dall’IDE o in produzione.

Se la modifica al tema avviene dopo l’apertura della prima videata, sarà necessario chiamare il metodo app.updateTheme() per renderla effettiva. È possibile passare le proprietà da aggiornare direttamente a tale metodo, ad esempio:

app.updateTheme({secondary: “#51d677”, ...});

Editing del CSS #

La modalità più completa per ottenere qualunque effetto grafico di interesse è quella di personalizzare il CSS del framework IonicUI. Questa modalità è estremamente potente, ma richiede la conoscenza degli inspector web dei browser e del linguaggio di configurazione dello stile degli elementi (CSS).

Per ottenere questo risultato è sufficiente aggiungere un foglio CSS alla propria applicazione e poi inserire le regole aggiornate.

Per testare quali selettori specificare e quali regole aggiornare, si consiglia di ispezionare il DOM della pagina browser in cui sono presenti gli elementi da modificare e poi testare al volo le modifiche necessarie. Dopo aver trovato la configurazione richiesta, si può procedere a definire il contenuto del proprio foglio CSS.

Il metodo setAttribute #

Alcuni elementi visuali del framework IonicUI vengono visualizzati creando diversi oggetti nel DOM del browser. La modifica di uno stile inline di un elemento visuale a design time o tramite codice agisce solo sull’oggetto DOM principale, solitamente quello che contiene tutti gli altri. 

In alcuni casi, per modificare lo stile degli oggetti interni potrebbe quindi essere necessaria la creazione di una classe CSS apposita che possa arrivare agli oggetti interni attivando i selettori opportuni. 

Una soluzione alternativa può essere quella di utilizzare il metodo setAttribute dell’elemento che, oltre a poter impostare gli attributi dell’elemento, è in grado di operare anche sugli oggetti interni. 

Se ad esempio si volesse modificare il colore di sfondo di una navbar senza usare i colori del tema, potremmo scrivere il codice seguente:

$navbar.setAttribute("toolbar-background style",
                     "background-color:yellow");

Questa riga di codice fa sì che l’attributo style non venga modificato sull’oggetto DOM principale della navbar, ma su un suo sotto-oggetto che ha come classe toolbar-background, e che è quello che visualizza lo sfondo.
Per maggiori informazioni sulle varie configurazioni ammesse dal metodo setAttribute, si consiglia di leggere la documentazione in linea.