Javascript, HTML, CSS e... !
0 commenti

Codice più snello e più facile da mantenere

Centralizzare le funzioni in una Libreria in Google Apps Script

Una libreria è un progetto di Google Apps Script creato con lo scopo di centralizzare funzioni utili al fine di poterle richiamare da altri script.

VANTAGGI
L'evidente vantaggio di non dover scrivere, o inserire, ogni volta le stesse funzioni in ogni script in cui se ne ha bisogno è quello di rendere il codice più snello, più facilmente manutenibile e velocizzare la realizzazione delle proprie applicazioni.

SVANTAGGI
Come indicato nella documentazione ufficiale, uno degli accorgimenti per migliorare le prestazioni degli script è proprio quello di evitare l'uso delle librerie in quanto partecipano negativamente alla velocità di esecuzione degli script. In particolar modo sono sconsigliate laddove la velocità è un elemento fondamentale, come nelle Add-on.

Per poter includere una libreria all'interno di un progetto Apps Script è essenziale:

- Avere accesso almeno in lettura alla libreria (altrimenti si riceverà un errore di permessi nel momento in cui si tenta di aggiungerla al progetto);
- Conoscere l'ID script della libreria (disponibile in File -> Proprietà del progetto).

L'utilizzo di una libreria è relativamente semplice, con i dovuti accorgimenti nel creare funzioni adeguatamente parametrizzate e con pochi passaggi di implementazione è possibile crearsi una collezione di entità di base pronte per l'uso.

Ci sono alcune best practices che conviene prendere in considerazione quando si scrive una libreria:

- Scegliere un nome rappresentativo per il progetto in quanto verrà utilizzato come identificativo predefinito, questa prassi è molto utile nel caso la libreria venga resa pubblica per l'utilizzo da parte di altri sviluppatori;
- Se vogliamo rendere private alcune funzioni all'interno della libreria, ovvero non accessibili da script esterni, basterà terminare il nome della funzione con un underscore, ad esempio: myFunction_();
- Se vogliamo attivare il completamento automatico dell'editor di script quando si richiamano le funzioni della libreria è necessario dotare ciascuna funzione di descrizione ed informazione sui vari parametri che si traduce in una parte di codice commentata da inserire al di sopra delle funzioni stessi. Di seguito un esempio di questa notazione stile JSDoc (dove solo i parametri @param e @return sono supportati in Apps Script), un altro esempio si trova invece nell'articolo 'Funzioni personalizzate in Google Sheets con Google Apps Script':

/**
 * Restituisce la regione
 *
 * @param {country} il paese nel formato standard ISO 3166-1 alpha-2
 * @param {zip} il codice di aviamento postale
 * @return {string} the result of the exponential calculation
 */
function getRegionByZip(country, zip) {
  var res = getGeolocByZip_(country, zip);
  return res.places[0].state;
}

Vediamo con un caso pratico come utilizzare una libreria di funzioni Apps Script.
Nel caso specifico l'intenzione è quella di creare una libreria contenente una serie di funzioni che mi permettano di georeferenziare un codice di aviamento postale per ottenere in risposta l'informazione puntuale di latitudine e longitudine, regione, ecc... Allo scopo mi sono avvalso di un'API gratuita per il recupero di tali dati, descritta nell'articolo 'Georeferenziare un CAP con una chiamata in GET in Google Apps Script'.

Come detto ad inizio articolo, una libreria è un progetto Apps Script pertanto come primo passo è necessario creare un nuovo progetto che chiamerò, per seguire i consigli delle best practices, 'GeoZipLibrary' all'interno del quale ho inserito una funzione privata (getGeolocByZip_) che effettua la chiamata all'API e che può essere interrogata solo dall'interno della libreria da parte delle funzioni ad uso esterno chiamate getLngLatByZipgetRegionByZip, Fig. 1:



funzioni all'interno della libreria organizzate come da best practices

Fig. 1 - Esempio di una Libreria in Apps Script gestita come da best practices


Per poter essere inclusa in un altro script, una libreria, deve contenere una versione salvata (che rappresenta un'istantanea del progetto) pertanto, una volta inserite in essa le opportune funzioni è necessario, nel relativo editor di script, recarsi alla voce di menu 'File -> Gestisci versioni...' e nella finestra che si aprirà inserire una descrizione (opzionale) come nota di cosa è stato modificato/aggiunto rispetto ad una eventuale versione precedente e cliccare su 'Salva una nuova versione', Fig. 2:



versioni salvate del progetto

Fig. 2 - Versioni salvata del progetto utilizzabili in altri script come libreria


Una nota sulle versioni in quanto, come è facile intuire, tramite l'icona della 'x' è possibile eliminare una versione dall'elenco ma è bene sapere che una versione eliminata non può più essere recuperata.

A questo punto prendere nota dell'identificativo del progetto ovvero, l'ID script dalla voce di menu 'File -> Proprietà del progetto' (Fig. 3) per utilizzarlo nel progetto nel quale vogliamo includere la relativa libreria:



id script - identificativo del progetto

Fig. 3 - ID script, identificativo del progetto


In precedenza la stringa che identificava il progetto era il 'Codice del progetto' (come ho descritto nell'articolo 'Parsing HTML con una Libreria pronta in Google Apps Script') ma ad oggi è diventato obsoleto e sostituito appunto dall'ID script, che non è altro che la stringa di caratteri associata allo script presente anche nel suo URL.

Nel progetto Apps Script dove vogliamo includere la libreria selezionare la voce di menu 'Risorse -> Librerie...' e nella finestra che si aprirà inserire l'ID script nel campo di testo 'Aggiungi una libreria' e premere su 'Aggiungi', Fig. 4:



aggiunta di una libreria ad un progetto apps script

Fig. 4 - Aggiunta di una libreria ad un progetto Apps Script tramite il relativo ID script


Una volta aggiunta la libreria è possibile notare la presenza del relativo 'Identificatore', quella stringa (che di default è pari al nome del progetto correlato privo di spazi e di altri caratteri non alfanumerici ma che può essere personalizzata a piacimento) sarà il riferimento da utilizzare per richiamare le funzioni della libreria (nota sull'identificatore: se utilizzi un nome di un identificatore già esistente legato ad un servizio già presente o di una libreria aggiunta in precedenza, la libreria inserita più di recente sovrascriverà quelle precedenti).

A questo punto è la volta di selezionare la versione che si intende collegare tramite l'opportuno combobox, Fig. 5, e salvare di conseguenza:



selezione della versione della libreria da collegare al progetto

Fig. 5 - Selezione della versione della Libreria da collegare al progetto


Dallo script sarà ora possibile richiamare le funzioni della libreria per utilizzarle a piacimento (Fig. 6, notare l'uso dell'identificatore):



script che richiama una funzione da una libreria aggiunta al progetto

Fig. 6 - Script che richiama una funzione da una libreria aggiunta al progetto


Per completezza di informazione, se provassimo a richiamare la funzione privata getGeolocByZip_ otterremo il seguente messaggio di errore (Fig. 7):



errore restituito dallo script in caso di chiamata di una funzione privata

Fig. 7 - Errore restituito dall'editor di script in caso di chiamata di una funzione privata


Per ulteriori informazioni sulle Librerie in Apps Script rimando alla documentazione ufficiale.

Tags

Michele Pisani

Michele Pisani

Sviluppatore Javascript ed esperto in Digital Analytics

L'esperienza nel settore Digital Analytics unita ad anni di sviluppo in Javascript ha trovato la massima espressione in Google Apps Script che mi ha permesso, con estrema facilità e poche righe di codice, di realizzare potenti applicazioni interattive e processi automatizzati integrati con i prodotti della G Suite.

Come contattarmi
scrivi un commento

0 Commenti

Non ci sono commenti

Nessuno ha ancora commentato questo articolo, fallo tu per primo!

scrivi un commento

Scrivi un commento

Il tuo indirizzo email non sarà pubblicato.I campi contrassegnati da un * sono obbligatori
Puoi utilizzare i seguenti tag nei commenti:
[bold]testo[/bold] se vuoi evidenziare un testo con il grassetto[code]function helloworld() { }[/code] se vuoi pubblicare una porzione di codice[url]http://www.appsscript.it[/url] se devi riferirti ad un indirizzo web