Dato che come libreria di appoggio è stata scelta scrollmagic.js, che traduce le dimensioni in pixel dei componenti web in durata di animazioni di scrollytelling, ScrollAStory.js lavora sia con la localizzazione degli elementi HTML che compongono la pagina, sia con le loro dimensioni.
Internamente, ScrollAStory.js memorizza informazioni riguardanti la pagina nella sua interezza, la struttura delle sezioni, e le componenti delle singole sezioni, così che la libreria stessa conosce in qualsiasi momento il posizionamento delle singole sezioni, dei loro componenti e la loro effettiva dimensione in pixel.
Il funzionamento generale della libreria si basa sull’invocazione del metodo
Create_Scroll_A_Story_Page() che, una volta che il document è caricato nella sua
interezza, a partire dal contenitore globale della pagina implementata con ScrollAStory.js (quindi quello classificato come scroll_a_story_container), registra l’identificatore univoco, il titolo, il pixel dell’asse y dello schermo corrispondente al punto di inizio della sezione e il pixel dell’asse y corrispondente al punto di fine della sezione, per tutte le sezioni che compongono la pagina.
Per poter far sì che questo accada, è necessario assegnare ad ogni div inserito all’interno del contenitore della sezione la giusta classe, prestando grande attenzione
all’ordinamento dei sotto blocchi58. Dato che lo script di ScrollAStory.js seleziona i
nodi figli di determinati elementi HTML che dispongono di particolari classi, se non viene rispettata la gerarchia riportata per ogni tipo di sezione (ibidem 4.2.1) verrà a mancare il corretto funzionamento della libreria.
La creazione della pagina dinamica avviene in maniera gerarchica: una volta creata la struttura generale, ciascuna sezione viene tradotta dalla struttura HTML statica della pagina caricata a quella dinamica scrollytelling.
Per ogni tipologia di sezione, sono stati quindi implementati dei metodi “creatori” che vengono invocati automaticamente all’interno del metodo
Create_Scroll_A_Story_Page() in base ai valori inseriti nell’attributo class del
contenitore di sezione, prendendo come parametri di input l’identificativo univoco e i parametri aggiuntivi inseriti a seguito della classe associata alla sezione scelta dal creatore di contenuti.
Una volta invocati, i metodi che implementano la creazione delle diverse sezioni isolano a loro volta i figli del contenitore più interno corrispondente alla sezione e, in base ai parametri aggiuntivi, realizzano il layout richiesto. Nel caso in cui il creatore di contenuti non inserisca nessun parametro, lo script assegna dei valori di default: ad esempio, per la sezione con elemento fisso, la posizione e la dimensione di default sono left e 50; per la sezione a comparsa animata, l’allineamento di default è left; per la sezione con vari elementi fissi, la posizione e la dimensione di default sono left e
50; per la sezione con elementi HTML su immagini di sfondo, il posizionamento di
default è left; per la sezione con elemento fisso animabile tramite step discreti, la posizione e la dimensione di default sono left e 50; per la sezione con elemento fisso animabile in maniera continua, la posizione e la dimensione di default sono left e 50.
L’ultima istruzione di ogni “creatore” di sezione è l’invocazione di un ulteriore metodo che si occupa della realizzazione della cosiddetta scena di scrollmagic, in base alla sezione che deve essere realizzata.
La creazione della pagina dinamica è quindi completamente automatica: il comportamento degli elementi dinamici è determinato dalle classi, e le dimensioni, la posizione degli elementi dinamici e i vari punti di trigger delle animazioni vengono calcolati in base alla dimensione di contenuti. L’utente perciò lavora con blocchi ad alto livello, senza preoccuparsi dei dettagli implementativi a basso livello.
Quando la pagina viene ridimensionata, avviene un nuovo riposizionamento degli elementi all’interno del DOM, azione che permette a ScrollAStory.js di calcolare nuovamente le posizioni degli elementi della pagina, rendendola quindi estremamente adattiva.
4.4.1
Dati interni di ScrollAStory.js
Come scritto in precedenza, ScrollAStory.js salva all’interno di una struttura dati una serie di informazioni rappresentate da booleani, stringhe e oggetti che permettono alla libreria di tenere traccia di tutto ciò che riguarda la porzione di pagina web implementata tramite la stessa:
● anchored_sections: array delle sezioni che si vogliono rendere visibili nei punti di ancoraggio. Ogni elemento dell’array corrisponde ad un blocco div HTML che tra i valori inseriti nell’attributo class ha la keyword anchored;
● controller: oggetto necessario per il funzionamento di scrollmagic;
● fixed_backgrounds: oggetto costituito da oggetti per quante sono le sezioni classificate come text_on_fixed_backgrounds. Ogni elemento del dizionario segue la seguente sintassi:
○ [section_id], corrispondente all'identificativo univoco della sezione che funge da chiave dell’oggetto;
○ oggetto in cui sono riportate le specifiche della sezione in questione, costituito da:
■ start: coordinata Y dello schermo in cui inizia la sezione; ■ end: coordinata Y dello schermo in cui finisce la sezione; ■ components: array di oggetti in cui vengono riportate le
informazioni riguardo gli sfondi e quando devono essere visualizzati, costituito da:
● background, in cui è riportato il percorso dell'immagine da utilizzare come sfondo;
● start, dove è riportata la coordinata Y dello schermo coincidente all’inizio di quella particolare porzione di viewport in cui applicare lo sfondo;
● end, coordinata Y dello schermo che segna la fine della porzione di viewport con quel tipo di sfondo;
● heigh, che riporta l’altezza del blocco;
● id, ovvero l’identificatore univoco della porzione associata a quell’immagine di sfondo.
● is_ready: flag [true | false] che fornisce indicazioni riguardo allo stato della pagina creata;
● sections_info: array di oggetti in cui sono riportate le informazioni di tutte le sezioni implementate, sia classificate come anchored che non. Ogni elemento dell’array è costituito dalle seguenti chiavi:
○ id: identificativo univoco della sezione; ○ title: titolo assegnato alla sezione;
○ end: coordinata Y dello schermo coincidente al punto di fine della sezione.
● show_anchor_points: flag [true | false] che fornisce indicazioni riguardo all’utilizzo della funzionalità aggiuntiva dei punti di ancoraggio;
● steps_continuous_pinnings_elements: dizionario delle informazioni riguardanti le sezioni con elemento animato in maniera continua, realizzate tramite la classe continuous_pinning_element. La sua struttura è simile a quella di fixed_backgrounds, in quanto l’identificativo della sezione costituisce la chiave di accesso all’ulteriore dizionario in cui sono riportati:
○ pinned_element: l’elemento HTML che verrà animato;
○ section_start: coordinata Y dello schermo in cui inizia la sezione; ○ section_height: altezza in pixel della sezione;
○ section_end: coordinata Y dello schermo in cui finisce la sezione; ● steps_discreete_pinnings_elements: dizionario riguardante le sezioni
classificate come discreete_pinning_element. La struttura del dizionario segue quella del precedente; l’identificativo della sezione permette di accedere al dizionario più interno in cui sono riportate informazioni rigurado alla sezione d’interesse:
○ pinned_element: elemento HTML che verrà animato;
○ section_start: coordinata Y dello schermo in cui inizia la sezione; ○ section_end: coordinata Y dello schermo in cui finisce la sezione; ○ triggs: ulteriore dizionario le cui chiavi di accesso sono costituite dagli
identificatori associati ai vari punti di trigger dello script JavaScript da aggiungere per far animare l’elemento sopracitato. Questo dizionario è costituito da:
■ start, il cui valore riporta la coordinata Y dello schermo in cui inizia il blocco associato ad una particolare animazione dell’elemento;
■ end, il cui valore riporta la coordinata Y dello schermo in cui finisce il blocco;
■ value, il cui valore corrisponde a ciò che la funzione passata all’attributo onsasscroll (aggiunto al contenitore della sezione) prenderà come parametro di input.
● steps_pinning_elements: dizionario in cui sono salvate le informazioni relative ai componenti delle sezioni classificate come variable_pinning_elements. L’identificativo della sezione, di nuovo, funge da chiave di accesso ad un ulteriore dizionario in cui vengono salvati:
○ section_start: coordinata Y dello schermo coincidente al pixel d’inizio della sezione;
○ section_end: coordinata Y dello schermo coincidente al pixel di fine della sezione;
○ section_steps: array in cui vengono memorizzate le informazioni riguardo:
■ pin_id: identificativo univoco dell’elemento che rimarrà fisso durante lo scroll dell’utente;
■ trigg_id: identificativo univoco dell’elemento che continuerà a reagire agli scroll dell’utente sulla pagina;
■ triggs_info: dizionario in cui vengono riportati i pixel che stabiliscono l'inizio e la fine di quella particolare animazione:
● start; ● end.
● total_sections: array che contiene tutti i TAG HTML delle sezioni;
4.4.2
Metodi di ScrollAStroy.js
Oltre al già accennato metodo Create_Scroll_A_Story_Page(), sono stati implementati metodi che permettono di realizzare i layout di ogni tipologia di sezione, metodi che popolano e aggiornano le proprietà della libreria, e quelli riguardanti la funzionalità aggiuntiva dei punti di ancoraggio.
CreateScene( trigger_id, duration, pin_id) Il metodo in questione prende in input:
● punto di trigger, ovvero il tag HTML classificato come section_trigger_point che coincide con il punto di avvio dell’animazione di scrollmagic;
● durata in pixel della scena che verrà realizzata;
● il tag HTML classificato come section_pinning_element, ovvero l’elemento che reagirà in maniera non standard allo scroll dell’utente.
Al suo interno viene richiamata la classe ScrollMagic.Scene()59 che, appunto, realizzerà la scena in base ai parametri passati. Una volta assegnati questi parametri, la scena realizzata viene aggiunta (tramite il metodo della libreria .addTo()) al controller globale di scrollmagic, memorizzato nella proprietà controller di ScrollAStroy.js
CreateRevealingScene( trigger_id, pin_id )
A differenza del precedente, questo metodo permette di realizzare scene di scrollmagic con comparsa animata, prendendo in input:
59 scrollmagic.js, a differenza di ScrollAStory.js, lavora con delle componenti dette “scene”, sezioni
della pagina web che utilizzano il codice implementativo di scrollmagic.js per attivare le animazioni di scrollytelling. Quindi una scena è una porzione di viewport che si anima una volta che viene “toccato” il punto di trigger (inserito in ScrollAStory.js come contenitore section_trigger_point) che dura un numero ben preciso di pixel (che in ScrollAStory.js è calcolato come la distanza tra il punto di inizio e fine di una sezione che si vuol far animare secondo il paradigma dello scrollytelling).
● il punto di trigger coincidente all’avvio dell’animazione; ● il tag HTML che verrà animato.
Una volta settati i parametri di ScrollMagic.Scene(), anche questa viene aggiunta al controller globale.
Insert_Pinning_Element( section_id, position, pins_width)
Il metodo in questione implementa il corretto layout per la realizzazione della sezione con elemento fisso e viene richiamato nel caso in cui all’interno dell’attributo class sia inserita la keyword pinning_element_section.
I parametri di input sono di tipo stringa e corrispondono a: ● identificativo univoco della sezione;
● posizionamento dell’elemento fisso; ● dimensione dell’elemento fisso.
Una volta selezionato il contenitore della sezione, grazie all’identificativo passato tra i parametri, vengono selezionati e memorizzati i tre figli:
● contenitore classificato come section_trigger_point, coincidente con il punto di avvio dell’animazione di scrollytelling;
● contenitore classificato come section_content, al cui interno sarà riportata la parte di sezione che risponderà in maniera naturale allo scroll dell’utente; ● contenitore classificato come section_pinning_element, al cui interno verrà
Una volta memorizzate queste sotto componenti HTML, il contenitore di sezione viene diviso in due colonne, tramite l’utilizzo delle proprietà float60 e width61 dei tag HTML. La proprietà float permette di specificare la posizione del tag all’interno della viewport, mentre width di assegnare i pixel o la percentuale di spazio che quella porzione di viewport dovrà occupare.
Una volta assegnate queste nuove caratteristiche agli elementi, vengono chiamate due ulteriori proprietà dei nodi HTML: offsetHeight e clientHeight. La proprietà
offsetHeight restituisce l’altezza in pixel di un elemento HTML, includendo il suo
padding62 e escludendo i suoi margini, mentre clientHeight restituisce l’altezza in pixel
dell’elemento HTML includendo il padding, ma escludendo margini e bordi. Queste permettono di calcolare automaticamente la durata in pixel dell’animazione di scrollytelling, utilizzata dalla libreria scrollmagic per le sue scene e, il risultato dato dalla sottrazione tra offsetHeight della componente section_contet e clientHeight del
section_pinning_element, viene memorizzato come scene_duration, la durata in pixel
della scena di scrollmagic, che verrà passata come uno dei parametri al metodo
CreateScene() per l’attivazione della componente di scrollmagic. Questa operazione
permette di evitare il calcolo di durata di ogni diversa sezione, in quanto non si conoscono a priori le dimensioni delle componenti che dovranno essere realizzate: così facendo le informazioni vengono recuperate dagli stessi componenti dopo la loro renderizzazione nel document, garantendo la corretta misurazione di ognuno di loro.
Insert_Variable_Pinnings_Elements( section_id, position, pins_width )
Il funzionamento del seguente metodo è pressoché similare a quello di
Insert_Pinning_Element(), salvo per il fatto che questa particolare sezione dispone di
più nodi figli, tanti quanti sono gli elementi fissi che si vuol far susseguire durante
60 Proprietà CSS che permette di far “fluttuare” un elemento HTML all’interno della pagina,
posizionandolo a sinistra o a destra (left o right), a seconda del valore assegnato (w3schools.com, 2019).
61 Proprietà CSS che permette di assegnare una larghezza ad un elemento HTML (w3schools.com,
2019).
l’animazione.
Nuovamente viene selezionato il tag HTML in base al suo identificativo, per ogni suo nodo figlio vengono memorizzati i tre componenti classificati come
section_trigger_id, section_content e section_pinning_element e, successivamente,
vengono realizzate due strutture dati in cui verranno memorizzate le informazioni riguardanti i diversi elementi fissi e le loro controparti a interazione standard. Per ogni elemento all’interno della componente classificata come section_content, si memorizza la sua posizione Y sullo schermo coincidente al punto di inizio, e la posizione Y sullo schermo coincidente alla coordinata che segna la fine dell’elemento. Queste informazioni vengono memorizzate in un array in cui, per ogni cosiddetto “step” (ovvero punto di cambio di animazione), si registra:
● l’identificativo della sotto componente in questione;
● l’identificativo dell’elemento fisso da far visualizzare una volta che il focus dell’utente comprende la porzione di viewport racchiusa tra i pixel di inizio e di fine sopra citati;
● le informazioni riguardo, appunto, i punti di inizio e fine della sotto componente.
Questa struttura dati, viene successivamente memorizzata all’interno della proprietà
steps_pinnings_elements alla chiave identificativo della sezione generale (quindi steps_pinnings_elements[section_id]), come valore della chiave section_steps. Nella
proprietà vengono memorizzate anche la coordinata Y, ottenuta grazie alla proprietà
offsetTop della componente section_content, coincidente col punto di inizio della
sezione, come valore della chiave section_start, e la coordinata Y che segna la fine della sezione, ottenuta dalla somma di offsetTop e offsetHeight di section_content. Una volta memorizzate queste informazioni, vengono posizionati i componenti della sezione, utilizzando nuovamente le proprietà float e width.
Insert_Discreete_Pinning_Element( section_id, position, width )
Questo metodo permette l’implementazione della sezione classificata come
discreete_pinning_element, seguendo il pattern di istruzioni del precedente, salvo la
postazione di memorizzazione delle informazioni, in quanto viene inserito un nuovo elemento all’interno della proprietà steps_discreete_pinnings_elements.
L’ultima istruzione è la chiamata di CreateScene(), alla quale vengono passati i parametri necessari calcolati in precedenza.
Insert_Continuous_Pinning_Element( section_id, position, pins_width )
Questo metodo permette l’implementazione della sezione classificata come
continuous_pinning_element, seguendo il canonico pattern di istruzioni delle sezioni
che presentano un elemento fisso. La postazione di memorizzazione delle informazioni è all’interno della proprietà steps_continuous_pinnings_elements. Una volta memorizzate le informazioni e collocati gli elementi secondo il giusto layout, viene chiamata la CreateScene() che si occuperà della realizzazione della scena scrollmagic.
Insert_Revealing_Component( section_id, position )
Dato che la tipologia di sezione classificata come revealing_element_section non presenta nessun elemento fisso, tra i parametri di input manca la dimensione di quest’ultimo. Il metodo seleziona i nodi figlio della sezione, rilevata all’interno del document tramite il costrutto getElementById()63 e li memorizza in variabili
temporanee.
Al figlio classificato come section_revealing, ovvero il corpo della sezione che avrà la comparsa animata, viene assegnata un’ulteriore classe section_revealing_pin, necessaria per l’animazione CSS utilizzata.
Fatto ciò, vengono selezionati gli eventuali nodi figli e, in caso siano presenti e siano classificati come una delle sezioni implementabili, vengono richiamati gli altri metodi- costruttori per realizzare il corretto layout.
63 Metodo del DOM che restituisce un particolare elemento in base al suo identificativo (proprietà id)
A differenza dei metodi precedenti, l’ultima istruzione è la chiamata del metodo
CreateRevealingScene(), metodo adibito alla realizzazione di scene scrollmagic a
comparsa animata.
Insert_Pinning_Background( section_id, position )
Il metodo in questione realizza il layout delle sezioni di tipo
text_on_fixed_background. Come per i metodi precedenti, anche qua vengono
selezionati i nodi figlio della sezione e, per quanto riguarda di componente classificato come section_description, vengono salvati i suoi figli in due variabili temporanee. Questo processo permette di risalire all’immagine di sfondo di ogni parte della sezione in questione, alla quale vengono settate delle proprietà stilistiche fondamentali per la corretta resa grafica:
● backgroundAttachment, che permette di assegnare alla parte uno sfondo con particolari caratteristiche stilistiche;
● paddingTop, che aggiunge dello spazio vuoto tra il punto di inizio della parte e l’effettiva foglia riportata;
● zIndex, che modifica il livello della parte rispetto all’asse z della pagina, mettendo “sopra” o “sotto” altri elementi il componente.
Fatto questo, le informazioni riguardanti le parti della sezione, quali identificativo della parte, percorso dell’immagine di sfondo, punto di inizio, punto di fine e altezza, sono salvate entro un oggetto che verrà poi memorizzato alla chiave components della proprietà fixed_backgrounds.
L’ultima istruzione eseguita dal metodo è, di nuovo, la chiamata di CreateSene().
Get_Total_Section()
Restituisce l’array memorizzato nella proprietà total_sections, ovvero tutti i blocchi HTML che si trovano racchiusi dentro il blocco classificato come
Get_Anchored_Sections()
Restituisce l’array memorizzato nella proprietà anchored_sections, ovvero tutti i blocchi HTML delle sezioni che sono visibili nei punti di ancoraggio.
Get_Sections_Info()
Restituisce l’array di oggetti memorizzato nella proprietà sections_info, in cui sono memorizzati identificatore, titolo, pixel di inizio e pixel di fine di ogni sezione.
Get_Fixed_Backgrounds()
Restituisce l’oggetto assegnato alla proprietà fixed_backgrounds, in cui, per ogni sezione di tipo text_on_fiexed_background, vengono memorizzate le informazioni riguardo la sezione d’interesse (per maggiori dettagli, ibidem 4.2.3).
Get_Steps_Pinnings_Elements()
Restituisce l’oggetto assegnato alla proprietà steps_pinnings_elements, in cui, per ogni sezione di tipo discreete_pinning_element, vengono memorizzate le informazioni riguardo la sezione d’interesse (per maggiori dettagli, ibidem 4.2.3).
Set_Total_Sections()
Memorizza nella proprietà total_sections tutti i tag HTML della pagina web che hanno come classe anche il valore di sas_section.
Set_Anchored_Sections()
Memorizza nella proprietà anchored_sections tutti i tag HTML della pagina web che hanno come classe anche il valore di anchored.
Set_Sections_Info()
Per ogni sezione inserita nel contenitore scroll_a_story_container, viene realizzato un oggetto in cui sono memorizzati il valore dell’identificativo univoco alla chiave id, il titolo alla chiave title, la coordinata Y dello schermo coincidente al punto di inizio della sezione, grazie alla proprietà offsetTop, alla chiave start, la coordinata Y dello schermo che segna la fine della sezione, grazie alla somma del valore ottenuto tramite
la proprietà offsetHeight e il valore di height di tutta la sezione, alla chiave end, successivamente aggiunto all’array della proprietà sections_info.
Set_Fixed_Background()
Questo metodo permette di assegnare le corrette misurazioni salvate come punti di inizio, fine e altezza per ogni parte di ogni sezione di tipo text_on_fixed_background, ed è richiamata all’interno della Init() della libreria, in quanto prima che la pagina sia effettivamente renderizzata dal browser, non sono conosciute le effettive dimensioni e