Le funzioni in Sass

Dopo aver spiegato cosa sono, come creare e utilizzare un mixin, vediamo ora come definire e invocare una funzione in Sass. Mostreremo poi alcune delle funzioni predefinite più utili. Le funzioni costituiscono infatti un altro metodo per non ripetere più volte lo stesso frammento di codice, evitando così di perdere tempo a riscrivere più volte la stessa istruzione e diminuendo allo stesso tempo la possibilità di commettere errori o introdurre nuovi bug. La principale differenza fra i mixin e le funzioni è che i primi permettono di inserire dei blocchi di dichiarazioni in una regola mentre le seconde consentono di eseguire delle istruzioni e restituire un valore.

Come definire una funzione in Sass con la direttiva @function

Per definire una funzione in Sass useremo la direttiva @function seguita dal nome della funzione e da una coppia di parentesi graffe all’interno delle quali inseriremo la direttiva @return che consente di restituire un valore il cui tipo può essere uno degli otto tipi di dato supportati in Sass. Per evitare possibili conflitti con le funzioni predefinite o fornite da librerie di terze parti è opportuno usare un prefisso da anteporre al nome della funzione da noi definita. Inoltre, come per le variabili e i mixin, i caratteri ‘_’ e ‘-‘, usati all’interno di un nome di funzione, sono intercambiabili per cui ‘simple-function()’ e ‘simple_function()’ si riferiscono alla stessa funzione e non sono quindi due funzioni distinte.

/* file style.scss */
@function my-identity($x: 0) {
  @return $x;
}

Nell’esempio mostrato sopra la funzione my-identity() può ricevere un argomento il cui valore predefinito è 0. Il valore ricevuto come argomento viene quindi restituito grazie alla direttiva @return.

Può essere a volte utile creare una funzione che può ricevere un numero non definito di argomenti. In queste situazioni risulta estremamente utile usare l’operatore ‘…’ (variable arguments) in fase di definizione di una funzione. Vediamo anche in questo caso un esempio.

/* file style.scss */
@function mr-webmaster-min($numbers...) {
  // ottiene il numero di elementi presenti nella lista
  $length: length($numbers);

  // recupera il primo elemento della lista
  $min: nth($numbers, 1);

  @for $i from 2 through $length {

    $current-value: nth($numbers, $i);

    @if $current-value < $min {
      $min: $current-value;
    }

  }
  // scrive un messaggio nello standard error
  // Line 20 - DEBUG: Il valore minimo è 1.5
  @debug "Il valore minimo è #{$min}";

  @return $min;
}

p {
  font-size: 1em;
  font-family: Arial, Helvetica, sans-serif;
  line-height: mr-webmaster-min(2.5, 3, 2, 4, 12, 1.5, 8 , 6, 1.8); // 1.5
}

La funzione mr-webmaster-min() può ricevere un numero indefinito di argomenti che vengono inseriti all’interno della lista $numbers. Con la funzione predefinita length() otteniamo il numero di elementi presenti nella lista. Con l’altra funzione predefinita nth($lista, $indice) vengono recuperati i valori presenti nella lista in posizione $indice. Al termine del ciclo for la variabile $min contiene il minimo valore presente in $numbers che viene alla fine restituito dalla funzione. Abbiamo anche usato la direttiva @debug per scrivere un messaggio nello standard error. All’interno del terminale verrà stampata la seguente stringa.

/Users/claudio/sass-example/scss/style.scss:20 DEBUG: Il valore minimo è 1.5

Come invocare una funzione in Sass

Una volta definita una funzione, possiamo invocarla come abbiamo già fatto nell’esempio precedente.

p {
  font-size: 1em;
  font-family: Arial, Helvetica, sans-serif;

  // invochiamo la funzione mr-webmaster-min()
  line-height: mr-webmaster-min(2.5, 3, 2, 4, 12, 1.5, 8 , 6, 1.8); // 1.5
}

Anche per le funzioni è possibile usare l’operatore ‘…’ in fase di invocazione per espandere una lista e passare i vari elementi come singoli argomenti.

/* file style.scss */
$values: 2.5, 3, 2, 4, 12, 1.5, 8 , 6, 1.8;

p {
  line-height: mr-webmaster-min($values...); // 1.5
}

Un’altra funzionalità utile è costituita dai keyword arguments attraverso i quali si possono passare gli argomenti a una funzione di qualsiasi ordine. La sintassi è quella mostrata nell’esempio sottostante.

/* file style.scss */

$red: 62;

p {
  color: rgb($green: 103, $blue: 179, $red: $red);
}

La funzione rgb($red, $green, $blue) è una funzione predefinita che presenta tre parametri denominati $red, $green e $blue. Quando chiamiamo la funzione rgb() (non in fase di definizione) possiamo passare come argomenti delle coppie ‘chiave: valore’ purché la chiave abbia lo stesso nome di uno dei parametri della funzione. In questo modo gli argomenti possono essere passati in qualsiasi ordine. Notate che nell’esempio precedente come valore di $red abbiamo usato l’omonima variabile.

Funzioni predefinite utili

Dopo aver visto come creare e invocare una funzione vediamo alcuni esempi di funzioni predefinite che Sass mette a disposizione.

La funzione unique-id()

La funzione unique-id() restituisce una stringa casuale che possiamo per esempio usare per generare dei nomi di classe o id random come mostrato sotto.

/* file style.scss */
.box-#{unique-id()} {
  font-size: 1em;
  font-family: Arial, Helvetica, sans-serif;
}

Lanciando il comando node-sass otteniamo il seguente risultato.

/* file style.css */
.box-ub45d26ea {
  font-size: 1em;
  font-family: Arial, Helvetica, sans-serif;
}

Le funzioni get-function() e call()

La funzione get-function() restituisce un riferimento alla funzione il cui nome è passato come argomento. Tale riferimento può quindi essere passato alla funzione call($riferimento-a-una-funzione, $args…) che invoca la funzione ricevuta come primo argomento passandole gli altri argomenti ricevuti.

/* file style.scss */
$ref-to-function: get-function(mr-webmaster-min);

.box-#{unique-id()} {
  line-height: call($ref-to-function, 1, 2, 3); // 1
}

Se compiliamo il frammento di codice mostrato sopra, otteniamo il risultato riportato sotto.

/* file style.css */
.box-u92e19f91 {
  line-height: 1;
}

Funzioni per le stringhe

Sass dispone di alcune funzioni per lavorare sulle stringhe che sono simili a quelle di molti linguaggi di programmazione. Un esempio è la funzione to-upper-case($stringa) che converte la stringa passata come argomento in modo che tutti i caratteri siano delle lettere maiuscole. La funzione opposta è to-lower-case($stringa). Altre funzioni utili sono le seguenti:

• str-length($string): restituisce il numero di caratteri di una stringa
• str-index($string, $substring): restituisce l’indice della prima occorrenza di $substring in $string.
• str-slice($string, $start-at[, $end-at]): estrae una sottostringa dalla stringa che viene passata come primo argomento. $start-at indica a partire da quale carattere bisogna estrarre la nuova stringa. L’ultimo argomento è invece opzionale, se non è fornito viene estratta una sottostringa a partire da $start-at fino all’ultimo carattere di $string.
• le due funzioni quote($string) e unquote($string) aggiungono e rimuovono rispettivamente le virgolette dalla stringa passata come argomento.

Funzioni per valori numerici

Sass fornisce anche un insieme di funzioni di base per la manipolazione dei valori numerici. Per esempio esistono due funzioni predefinite min($numbers…) e max($numbers…) che restituiscono rispettivamente il valore minimo e massimo di una serie di numeri. Altre funzioni che possono tornare utili sono le seguenti:

• percentage() converte valori numerici senza unità di misura in percentuali. Per esempio: percentage(320px/1280px) restituisce 25%.
• le funzioni ceil($num) e floor($num) arrotondano invece per eccesso o per difetto al numero intero superiore (ceil) o inferiore (floor). Mentre ceil($num) arrotonda sempre per eccesso e floor($num) sempre per difetto, la funzione round($num) arrotonda un numero all’intero più vicino.
• la funzione abs($num) restituisce il valore assoluto di un numero
• random([$limit]) restituisce un valore pseudo-casuale fra 0 e 1 se non viene passato nessun argomento. In caso venga passato un intero $limit come argomento, allora viene restituito un valore compreso fra 1 e $limit. (estremi inclusi)

Funzioni per i colori

In sass esistono numerose funzioni che permettono di creare un colore in base a dei parametri in ingresso o di modificare e mescolare diversi colori per generarne uno nuovo. Quelle che seguono sono solo alcune delle funzioni disponibili.

Funzioni per creare un colore

Elenchiamo di seguito alcune delle funzioni più utili e interessanti per creare un colore:

• le due funzioni rgb($red, $green, $blue) e rgba($red, $green, $blue, $alpha) restituiscono un valore rappresentante un colore in base ai parametri $red, $green e $blue (e $alpha per l’opacità nel caso della seconda funzione). Gli argomenti $red, $green e $blue possono essere dei valori interi compresi fra 0 e 255 oppure dei valori percentuali compresi fra 0% e 100%. Per quanto riguarda il parametro $alpha della funzione rgba(), deve essere un valore numerico compreso fra 0 e 1. (estremi inclusi)
• le due funzioni hsl($hue, $saturation, $lightness) e hsla($hue, $saturation, $lightness, $alpha) producono lo stesso risultato delle precedenti con la differenza sostanziale che in questo caso vengono forniti come valori in ingresso $hue (tinta) che deve essere compreso fra 0 e 360 (estremi inclusi), $saturation (saturazione) compreso fra 0% e 100% e $lightness compreso sempre fra 0% e 100%. Per la funzione hsla() il valore di $alpha deve essere sempre un valore fra 0 e 1.
• grayscale($color) converte un colore in scala di grigi. È equivalente a invocare la funzione desaturate($color, 100%) che riceve come primo argomento un colore e come secondo un valore percentuale fra 0% e 100% e restituisce un nuovo colore il cui valore di saturazione è stato decrementato in accordo al valore del secondo argomento.
• la funzione complement($color) restituisce il colore complementare a quello passato come argomento

Funzioni per modificare un colore

Fra le funzioni che consentono di modificare o mescolare dei colori riportiamo le seguenti:

• rgba($color, $alpha) permette di modificare l’opacità di un colore di una quantità pari al valore del secondo argomento che deve essere compreso fra 0 e 1 (estremi inclusi). Per esempio rgba(#222, 0.2) restituisce rgba(34, 34, 34, 0.2).
• mix($color1, $color2, [$weight: 50%]) mescola i due colori a seconda della percentuale specificata come ultimo argomento.
• le funzioni lighten($color, $amount) e darken($color, $amount) rendono rispettivamente un colore più chiaro e più scuro in base al valore passato come secondo argomento che deve essere una percentuale compresa fra 0% e 100%.
• la funzione saturate($color, $amount) aumenta la saturazione di un colore in base al valore specificato come secondo argomento il quale deve essere compreso fra 0% e 100%. Si tratta della funzione opposta alla funzione desaturate($color, $amount) di cui abbiamo parlato in precedenza.

Come già accennato, le funzioni per lavorare con i colori sono numerose e consentono di effettuare operazioni disparate. Sass fornisce anche delle funzioni per ottenere componenti di un colore come le funzioni red($color), green($color), blue($color) oppure hue($color), saturation($color), lightness($color)

Funzioni per le liste

Le liste in Sass sono immutabili per cui tutte le funzioni che manipolano le liste restituiscono sempre una nuova lista anziché aggiornare la lista che viene passata come argomento.

• la funzione length($list) restituisce il numero di elementi di una lista;
• la funzione nth($list, $index) restituisce l’elemento della lista di posizione $index mentre la funzione set-nth($list, $index, $value) ‘sostituisce’ l’elemento di posizione $index all’interno della lista $list;
• join($list1, $list2, [$separator, $bracketed]) appende $list2 alla fine di $list1. L’argomento opzionale $separator può contenere come valori comma, space o auto che è il valore predefinito. In quest’ultimo caso la nuova lista generata utilizzerà come separatore quello presente in $list1. L’altro argomento facoltativo è $bracketed che può assumere i valori auto (default), true e false. In questo modo si può specificare se la lista che verrà restituita deve essere racchiusa o meno fra parentesi quadre;
• append($list, $val, [$separator]) aggiunge un singolo valore alla fine della lista $list.

Funzioni per le mappe

Anche le mappe, come le liste, sono immutabili. Tra le funzioni più interessanti per lavorare sulle mappe menzioniamo le seguenti:

• map-get($map, $key) restituisce il valore presente nella mappa $map associato alla chiave ($key) passata come secondo argomento;
• map-has-key($map, $key) restituisce un valore booleano a seconda che la chiave sia presente o meno in $map;
• le funzioni map-keys($map) e map-values($map) restituiscono rispettivamente le chiavi e i valori delle mappe sotto forma di lista;
• map-remove($map, $keys…) restituisce una nuova mappa a partire da $map da cui vengono però rimosse le chiavi passate come argomenti;
• map-merge($map1, $map2) unisce le due mappe passate come argomenti.

Quelle elencate sono ovviamente solo alcune delle funzioni disponibili. Per una lista completa delle funzioni predefinite presenti in Sass è possibile consultare la documentazione ufficiale.

Conclusioni

In questa lezione abbiamo visto come creare e invocare una funzione e abbiamo mostrato alcune delle funzioni disponibili in Sass che consentono di lavorare su colori, stringhe, valori numerici, liste e mappe. Nella prossima e ultima lezione illustreremo superficialmente alcuni utili strumenti e librerie di terze parti che possiamo usare per ottimizzare e velocizzare ulteriormente il flusso di lavoro.