EasyScript: libreria Commons

Sviluppando script, accade spesso di trovarsi in situazioni in cui, in codici differenti, occorre eseguire gli stessi tipi di controlli, ad esempio su forum o utenti, oppure si necessitano gli stessi elementi HTML, come modal o toast. Ciò in genere si traduce in un macchinoso copia-incolla delle stesse funzioni, il quale rende sufficientemente complicato apportare aggiornamenti generali alle funzioni comuni.
Fin dall'introduzione di EasyScript, è stata predisposta una particolare libreria condivisa da tutti gli script e disponibile in tutti i forum che avessero attivato il plugin. Tale libreria è finalmente stata aggiornata e formalizzata in questa guida.
La libreria viene importata automaticamente in ogni forum che ha attivo EasyScript, ossia ha installato almeno uno script oppure ha inserito il flag all'opzione "Abilita EasyScript" presente in Amministrazione > Funzioni aggiuntive > Script e codici, ed è raggiungibile anche dai vari box in Amministrazione > Grafica > Codice HTML tramite window.Commons. Si tratta di un pacchetto scritto in Vanilla JS, JQuery free e senza dipendenze da altre librerie, basato su una logica di lazy getter, al fine di pesare il meno possibile e garantire buone prestazioni.
La libreria è suddivisa in otto aree tematiche, sulla base della logica dei metodi contenuti, a ciascuna delle quali corrisponde una proprietà dell'oggetto window.Commons: location, forum, user, device, utilities, animations, modal e toast.

Location

L'oggetto location, raggiungibile da window.Commons.location, contiene informazione sul "luogo", ossia sulla pagina in cui si trova l'utente. Le sue proprietà sono le seguenti:

1. isArticle: boolean: true se la pagina corrente è un topic in formato articolo;
2. isArticleList: boolean: true se la pagina corrente è una sezione in formato blog, ossia con l'elenco dei primi post dei vari articoli;
3. isBlog: boolean: true se la pagina corrente è una sezione in formato blog o la prima pagina di un articolo;
4. isFullEditor: boolean: true se la pagina corrente è la risposta "estesa" (ad esempio la pagina a cui si viene indirizzati cliccando sui pulsanti "citazione" o "rispondi" nei topic);
5. isHome: boolean: true se la pagina corrente è la homepage del forum;
6. isProfile: boolean: true se la pagina corrente è il profilo di un utente;
7. isSection: boolean: true se la pagina corrente è una sezione;
8. isTopic: boolean: true se la pagina corrente è un topic;
9. profile: object: si tratta di un oggetto che racchiude informazioni sul profilo che si sta eventualmente visitando. Le sue proprietà sono:
   • avatar: string | null: l'avatar del profilo. Null nel caso in cui non sia disponibile (ad esempio ci si trova in homepage);
   • group: {id: number | string; name: string | null;}: informazioni sul gruppo a cui appartiene l'utente che si sta visitando. In caso non siano disponibili, l'id restituito è -1 e il name è null;
   • id: number: l'id del profilo. Zero in caso non sia disponibile;
   • nickname: string | null: il nickname del profilo. Null nel caso in cui non sia disponibile.
10. posts: object[]: si tratta di un array di oggetti ciascuno dei quali contiene informazioni sui posts della pagina che si sta visualizzando. Nel caso in cui la pagina corrente non sia un topic, ritorna un array vuoi. Le proprietà degli oggetti contenuti sono:
    • author: {id: number; group: {id: number | string; name: string | null}; nickname: string | null;}: informazioni sull'autore del post;
    • content: string: il contenuto del post con eventualmente i tag html inseriti;
    • nativeElement: l'elemento HTML che rappresenta il post;
    • id: number: l'id del post;
    • time: number: il timestamp della data in cui è stato inviato il post, adatto per essere passato come parametro alla classe Date.
11. section: object: si tratta di un oggetto che racchiude informazioni su una sezione. Le sue proprietà sono:
    • id: number: l'id della sezione. Zero in caso non sia disponibile (ad esempio ci si trova in homepage);
    • title: string | null: il nome della sezione. Null nel caso in cui non sia disponibile.
12. topic: object: si tratta di un oggetto che racchiude informazioni su un topic. Le sue proprietà sono:
    • id: number: l'id del topic. Zero in caso non sia disponibile (ad esempio ci si trova in una sezione);
    • title: string | null: il titolo del topic. Null nel caso in cui non sia disponibile.

Forum

L'oggetto forum, raggiungibile da window.Commons.forum, contiene informazione sul forum in cui ci si trova. Le sue proprietà sono le seguenti:

1. domain: "forumfree.it" | "forumcommunity.net" | "blogfree.net": il domain del forum;
2. id: number: l'id del forum;
3. isFFMobile: boolean: true se il layout corrente è FFMobile;
4. isQuirks: boolean: true se il layout corrente è Quirks;
5. isStandard: boolean: true se il layout corrente è Standard;
6. layout: number: valore numerico associato al layout attivo sul forum. Si tratta in genere di una variabile interna della libreria: zero per il layout FFMobile, uno per il Quirks, due per lo Standard;
7. shortdomain: "ff" | "fc" | "bf": il dominio abbreviato del forum;
8. subdomain: string: il sottodominio del forum.

User

L'oggetto user, raggiungibile da window.Commons.user, contiene informazione sull'utente attuale. Le sue proprietà sono le seguenti:

1. avatar: string | null: l'url corrispondente all'avatar dell'utente. Null se è un visitatore;
2. group: number | string: il gruppo a cui appartiene l'utente. Se l'utente è in un gruppo personalizzato, ritorna l'id numerico di quel gruppo. Se l'utente non è in un gruppo personalizzato ed è admin o moderatore, ritorna rispettivamente "admin" o "mod_sez". In tutti gli altri casi ritorna zero;
3. id: number: l'id dell'utente. Zero se è un visitatore;
4. isAdmin: boolean: true se l'utente è un admin del forum;
5. isGlobalMod: boolean: true se l'utente ha poteri di moderazione globale;
6. isGraphicAdmin: boolean: true se l'utente è un admin grafico, ossia ha accesso al pannello grafico nell'amministrazione del forum;
7. isGuest: boolean: true se si tratta di un visitatore non loggato.
8. isMod: boolean: true se l'utente è un moderatore di una o più sezioni;
9. isSectionAdmin: boolean: true se l'utente può amministrare le sezioni, ossia ha accesso, invero parziale, ai pannelli "sito web" e "funzioni aggiuntive" dell'amministrazione del forum;
10. isScriptAdmin: boolean: true se l'utente è un admin degli script;
11. isUserAdmin: boolean: true se l'utente è admin degli utenti, ossia ha accesso al pannello gruppi nell'amministrazione del forum;
12. lang: string: la lingua impostata dall'utente. Default en.;
13. nickname: string | null: il nickname dell'utente. Null se è un visitatore;

Device

L'oggetto device, raggiungibile da window.Commons.device, contiene informazione sul dispositivo utilizzato dall'utente. Le sue proprietà sono le seguenti:

1. isTouch: boolean: true se il dispositivo è touch.

Utilities

L'oggetto utilities, raggiungibile da window.Commons.utilities, contiene varie funzioni di generale utilità. I suoi metodi sono i seguenti:

1. addScriptCredits: (script: {topic: number, name: string}, user: {id: number, name: string}, forum: {id: string, name: string, link: string}) => void: aggiunge i crediti per uno script, seguendo lo standard indicato nell'apposita guida. La libreria "Crediti in fondo al forum" deve essere selezionata per l'importazione tra le impostazioni dello script.
   L'oggetto script contiene due proprietà, topic e name. La prima rappresenta l'ID del topic che contiene la guida e la descrizione dello script, la seconda contiene il nome dello script scelto dall'autore.
   L'oggetto user contiene due proprietà, id e name. La prima rappresenta l'ID dell'account che ha creato lo script, la seconda il nickname dell'account autore dello script. Quest'ultimo può essere anche differente dal nickname effettivamente impostato nel profilo dei circuiti.
   L'oggetto forum contiene tre proprietà, id, name e link. La prima rappresenta un ID unico, scelto e utilizzato da tutti i creatori di script che fanno parte di un medesimo forum, non obbligatoriamente coincidente con l'ID del forum assegnato dai circuiti. È fondamentale che tale id rimanga il medesimo in tutti gli script di uno stesso forum, in caso contrario verranno creati più crediti per script differenti, ma appartenenti alla medesima community, anziché un solo tab. La seconda proprietà rappresenta il nome del forum che sarà visualizzato in fondo alle pagine dei siti che utilizzeranno gli script di quella community. La terza proprietà rappresenta il link al forum a cui appartiene l'utente sviluppatore dello script e verrà usata come base per inserire, insieme all'id del topic specificato nell'oggetto script, il link diretto alla guida dello script.
2. bbcodeParser: () => void: piccola funzione che permette di passare da una stringa in BBCode a una stringa in HTML. I suoi metodi sono:
   • set: (codes: object[], append?: boolean) => void: permette di impostare i vari replacer. codes è un array di oggetti in cui la chiave è una stringa che verrà usata per creare una regexp con new RegExp(), mentre il contenuto è il rimpiazzo in HTML. Un esempio che converte il tag BBCode B nel tag HTML strong è il seguente: myBBCodeParser.set({'\\[b\\](.+?)\\[/b\\]': '$1'}). Se il parametro append è true (di default è false), i nuovi codici passati verranno appesi a quelli eventualmente già impostati, altrimenti verranno sostituiti (e quindi i replace già impostati non saranno più validi).
   • parse: (text: string) => string: esegue i replace sulla stringa passata come input e restituisce la nuova stringa.
3. dateFormat: (value: number | string, format?: string) => string | null: formatta una data seguendo lo schema passato come format. value deve essere un valore da usare in new Date(). I token disponibili sono i seguenti:
   • Y: anno in quattro cifre (e.g.: 2020);
   • y: anno in due cifre (e.g.: 20);
   • n: mese da 1 a 12;
   • m: mese da 01 a 12;
   • j: giorno del mese da 1 a (massimo) 31;
   • d: giorno del mese da 01 a (massimo) 31;
   • G: ora da 0 a 23;
   • H: ora da 00 a 23;
   • i: minuto da 00 a 59;
   • s: secondo da 00 a 59.
   Ad esempio, volendo una data nel formato "04/12/2020 15:02" è possibile assegnare a format il valore 'd/m/Y H:i'. Il formato di default è Y-m-d H:i:s;
4. getAllCookies: () => object: restituisce un oggetto di key => value contenente tutti i cookie disponibili;
5. getCookie: (name: string) => string | null: ritorna il valore del cookie la cui chiave corrisponde a name. Restituisce null se il cookie cercato non è stato trovato;
6. getUrlParameter: (name: string, url?: string | null) => string | null: cerca nell'url specificato, o nell'url corrente se non viene passato alcun url, il parametro indicato da name. Ritorna il parametro cercato, sempre come stringa, oppure null nel caso in cui ciò che si cerca non viene trovato;
7. removeJsInTags: (text: string) => string: effettua l'escape di tutti i tag contenenti codice javascript inline (ad esempio onclick=) e restituisce la stringa risultante;
8. removeTags: (text: string, tags?: string[]) => string: accetta in input una stringa ed esegue l'escape dei tag specificati dall'array tags. Se non viene passato alcun parametro tags, verrà fatto l'escape dei tag script e style. Restituisce una nuova stringa a seguito dell'escape. Un valore d'esempio per il parametro tags può essere ['script', 'style', 'iframe']: in questo caso verrà effettuato l'escape dei tags script, style e iframe;
9. setCookie: (name: string, value: string, seconds?: number, network?: boolean) => boolean: imposta un cookie seguendo i parametri passati come input. name si riferisce al nome del cookie; value al contenuto; seconds ai secondi dopo cui il biscotto scade. Se non viene passato alcun valore per seconds il cookie scadrà al termine della sessione (ossia non viene settato né expires né max-age). Se network è true (di default è false), il biscotto sarà disponibile su tutti i forum del circuito di riferimento. Il cookie è automaticamente creato con i parametri Secure e SameSite=Lax;
10. uniqueItems: (array: object[], key: string) => object[]: cicla un array di oggetti e ritorna, in un nuovo array, solo gli oggetti che hanno valori distinti nella proprietà specificata dal parametro key;

Animations

L'oggetto animations, raggiungibile da window.Commons.animations, contiene varie animazioni realizzate in puro Javascript. I suoi metodi sono i seguenti:

1. fadeIn: (element: HTMLElement, duration?: number, display?: string, callback?: () => any) => void: esegue il fade in dell'elemento passato come input. Tramite duration è possibile specificare i millisecondi di durata dell'animazione, il valore di default è 300. Tramite display è possibile specificare il valore che verrà assegnato alla proprietà display, ad esempio flex. Il valore di default è block. Il parametro callback rappresenta una possibile funzione che verrà chiamata al termine dell'animazione;
2. fadeOut: (element: HTMLElement, duration?: number, callback?: () => any) => void: esegue il fade out dell'elemento passato come input. Tramite duration è possibile specificare i millisecondi di durata dell'animazione, il valore di default è 300. Il parametro callback rappresenta una possibile funzione che verrà chiamata al termine dell'animazione.

Modal

L'oggetto modal, raggiungibile da window.Commons.modal, permette di settare e gestire i modal.


I suoi metodi sono i seguenti:

1. close: (modal?: HTMLElement, callback?: () => any) => void: chiude manualmente un modal. A differenza di toggle, questo metodo accetta come input non l'id del modal, bensì l'elemento stesso. Se non viene passato alcun modal, viene fatto un controllo per verificare se c'è un modal attualmente aperto e, in caso, viene chiuso. Ciò può risultare utile ove si voglia inserire, ad esempio nel footer, un pulsante "chiudi" che, se premuto, chiude il modal: in questo caso, infatti, sarà sufficiente assegnare al pulsante la funzione onclick="window.Commons.modal.close()".
2. open: (modal: HTMLElement, callback?: () => any) => void: apre manualmente un modal. A differenza di toggle, questo metodo accetta come input non l'id del modal, bensì l'elemento stesso;
3. set: (options?: {class?: string | string[], data?: string | string[], title?: string, content?: string, footer?: string}, show?: boolean) => number: il metodo consente di creare un nuovo modal. L'oggetto options contiene le varie caratteristiche del modal:
   • class: una stringa o un array di stringhe contiene le classi personalizzate che si vogliono assegnare al proprio modal;
   • data: una stringa o un array di stringhe che contiene i vari ed eventuali data-attr da assegnare al proprio modal;
   • title: il titolo del modal;
   • content: il contenuto del modal;
   • footer: il footer del modal.
   Se il parametro show è impostato su true (di default è false), il modal oltre ad essegere aggiunto al DOM viene anche mostrato. La funzione restituisce l'id numerico del modal da poter utilizzare nei metodi update e toggle. Sono disponibili alcune classi per aumentare la personalizzazione del modal:
   • cs-modal-dark: la classe permette di utilizzare la versione scura del modal;
   • cs-modal-text-{alignment}: la classe permette di modificare l'allineamento del testo nel corpo del modal e nel footer. Al posto di {alignment} è possibile inserire i token left, center, right;
   • cs-modal-w{number}: la classe permette di gestire la larghezza del modal in schermi con width superiore a 992px. Al posto di {number} è possibile inserire il numero da 20 a 100, di 10 in 10, che indica la percentuale di larghezza del modal. Usando la classe cs-modal-w100 si otterrà un modal largo tutto lo schermo;
   • cs-modal-h{number}: la classe permette di gestire l'altezza del modal. Al posto di {number} è possibile inserire il numero da 40 a 100, di 10 in 10, che indica la percentuale di altezza del modal. Usando la classe cs-modal-h100 si otterrà un modal alto tutto lo schermo.
   Il modal è impostato in modo da rendere scrollabile il contenuto, mantenendo sempre visibile il titolo e il footer;
4. toggle: (id: number, callback?: () => any) => void: esegue il toggle del modal specificato da id, ossia se il modal è visibile, lo nasconde; se è nascosto, lo mostra. Il parametro callback rappresenta una possibile funzione che verrà chiamata al termine dell'animazione;
5. update: (id: number, options?: {title?: string, content?: string, footer?: string}) => void: aggiorna il contenuto del modal specificato da id;

Toast

L'oggetto toast, raggiungibile da window.Commons.toast, permette di settare e gestire i toast.


I suoi metodi sono i seguenti:

1. hide: (id: string) => Promise<string>: nasconde il toast specifica da id. In genere questo metodo non sarà utilizzato in quanto il toast scomparirà dopo il ttl oppure verrà chiuso dall'utente tramite gli appositi comandi.
2. show: (toast?: {id?: string, class?: string | string[], title?: string, content?: string, ttl?: number}) => Promise<string>: crea un toast e lo mostra. L'oggetto toast contiene le varie caratteristiche del toast:
   • id: un id personalizzato da assegnare al proprio toast. Se non viene specificato, ne verrà generato uno casuale. Se viene specificato un id già in uso da un altro toast, prima viene nascosto il toast con quell'id e in seguito viene creato quello nuovo;
   • class: una stringa o un array di stringhe contiene le classi personalizzate che si vogliono assegnare al proprio toast;
   • title: il titolo del toast;
   • content: il contenuto del toast;
   • ttl: time to live. Tempo in millisecondi trascorso il quale il toast scomparirà. Se non specificato, oppure se viene fornito un valore inferiore a 1 secondo, verrà usato il valore di default di 5 secondi.

In particolare, sono disponibili cinque tipologie di toast: notification, success, warning, error, info. A ciascuna di queste corrisponde una classe che deve essere specificata nell'opzione class del metodo set: cs-toast-notification, cs-toast-success, cs-toast-warning, cs-toast-error, cs-toast-info. Se non viene passata alcuna classe, di default verrà lanciato un toast info. Tramite la classe cs-toast-dark è possibile usare la versione scura del toast.

Considerazioni conclusive

Vista la mancanza di diverse informazioni in quel layout, le proprietà che si basano sugli elementi del DOM, ossia gli oggetti user e location, potrebbero non dare i risultati sperati sul layout Quirks.
Attualmente la libreria contiene solo le principali informazioni utili agli script attivi, tuttavia è sempre possibile aggiungere metodi/proprietà o modificare quelli esistenti: se hai una richiesta particolare non esitare a comunicarcelo!