<

Javascript

Nel wordpress Gpci framework sono automaticamente inserite nel frontend variabili e funzioni necessarie al corretto funzionamento dei pattern e blocchi gutenberg. Al momento non è consentito scegliere una selezioni di cosa includere e cosa no in quanto il file js-head.js è di dimensioni molto ridotte. in futuro, se il file diventerà troppo grande o pesante da caricare, verrà introdotto un metodo di selezione.

Variabili

Le variabili javascript sono la base delle funzioni e dei vari script nel framework, da cui dipende tutto il resto. Sono sempre disponibili e liberamente usabili in quanto sono automaticamente inserite nel file js-head.js durante l'inizializzazione del tema.

ajaxurl

Tipo: stringa

Url del file admin-ajax.php, serve a far funzionare i form via via javascript e altre funzioni grazie agli hook di wordpress wp_ajax_priv e wp_ajax_nopriv.

ScreenWidth

Tipo: numero

Larghezza in pixel dello schermo dell'utente, dopo l'applicazione del pixel ratio. Esempio: se la risoluzione del monitor è 3840x2160 e il ridimensionamento è 200% la variabile ScreenWidth sarà di 1920. La variabile è calcolata solo durante il caricamento della

ScreenWidthWithZoom

Tipo: numero

Larghezza in pixel della finestra dell'utente, dopo l'applicazione del pixel ratio. Esempio: se la risoluzione del monitor è 3840x2160, il ridimensionamento è 200% e la finestra è ristretta al 50% la variabile ScreenWidth sarà 960.

La variabile viene calcolata solo una volta durante il caricamento della pagina, quindi se la finestra è ridimensionata successivamente non cambia il valore. A volte può essere utile eseguire operazioni con la variabile in continuo aggiornamento, per fare questo utilizzare un listener javascript nel blocco o tramite il modulo aggiunte di codice con:

window.addEventListener( 'resize', function(){
  ScreenWidthWithZoom = document.documentElement.clientWidth;
} );

PinnedElements

Tipo: array

Inizializza i PinnedElement e nella stragrande maggioranza dei casi è utilizzata dalle funzioni relative.

DynamicVars

Tipo: oggetto

Inizializza le DynamicVars (vedi sotto)

Funzioni base

Le funzioni base possono essere utili nella scrittura di semplici script e sono utilizzate da alcune funzionalità del framework e funzioni più avanzate.

GetCurrentBlockFromCurrentScript

Questa funzione ottiene il blocco corrente come elemento javascript partendo dallo script corrente. Data la struttura costante degli script e dei blocchi nel framework questa funzione sarà quasi sempre usata nel codice javascript nel blocco gutenberg/avanzate. Questo è molto utile nei pattern e per avere elementi adiacenti con una sola riga di codice.

Parametri

Nessuno

Return

La funzione ritorna il blocco corrente come elemento javascript.

Esempio

//Questa funzione aggiunge un paragrafo dopo il blocco corrente, e sotto c'e' il risultato
GetCurrentBlockFromCurrentScript().insertAdjacentHTML( 'afterend', '<p class="elemento-aggiunto">Sono stato aggiunto!</p>');

IsPhone

Questa funzione si basa sulla variabile ScreenWidth e controlla se il dispositivo è uno smartphone. Su questa funzione si basa l'opzione di non generare il blocco gutenberg su telefono.

Parametri

Nessuno

Return

La funzione ritorna true se la risoluzione è minore di 782 pixel, false in caso contrario.

Esempio

//Controlla se smartphone e aggiunge la risposta al paragrafo sotto
let ForsePhone = IsPhone() ? 'SI' : 'NO';
GetCurrentBlockFromCurrentScript().innerHTML += '<span class="elemento-aggiunto">'+ForsePhone+'</span>';

Stai usando uno smartphone?

IsTablet

Questa funzione si basa sulla variabile ScreenWidth e controlla se il dispositivo è un tablet. Su questa funzione si basa l'opzione di non generare il blocco gutenberg su tablet.

Parametri

Nessuno

Return

La funzione ritorna true se la risoluzione è maggiore di 781 pixel e minore di 1280 pixel, false in caso contrario.

Esempio

//Controlla se tablet e aggiunge la risposta al paragrafo sotto
let ForseTablet = IsTablet() ? 'SI' : 'NO';
GetCurrentBlockFromCurrentScript().innerHTML += '<span class="elemento-aggiunto">'+ForseTablet+'</span>';

Stai usando un tablet?

IsDesktop

Questa funzione si basa sulla variabile ScreenWidth e controlla se il dispositivo è un tablet. Su questa funzione si basa l'opzione di non generare il blocco gutenberg su desktop.

Parametri

Nessuno

Return

La funzione ritorna true se la risoluzione è maggiore di 1279 pixel, false in caso contrario.

Esempio

//Controlla se desktop e aggiunge la risposta al paragrafo sotto
let ForseDesktop = IsDesktop() ? 'SI' : 'NO';
GetCurrentBlockFromCurrentScript().innerHTML += '<span class="elemento-aggiunto">'+ForseDesktop+'</span>';

Stai usando un desktop?

GetCookie

Questa funzione ottiene il valore di un cookie partendo dal nome, è utilizzata nel pattern del consenso dei cookie.

Parametri

  1. cookieName - stringa - obbligatorio
    Nome del cookie da ottenere

Return

La funzione ritorna il valore del cookie oppure null.

Esempio

//Settiamo un cookie per 15 secondi, lo leggiamo e lo scriviamo nella pagina. Il risultato è sotto
document.cookie = "gpci-saluto=Ciao!; max-age=15";
let  ValoreCookie = GetCookie('gpci-saluto');
GetCurrentBlockFromCurrentScript().innerHTML += '<span class="elemento-aggiunto">'+ValoreCookie+'</span>';

Cosa ho inserito nel tuo browser?:

Ma tra 15 secondi il CookieSaluto sparirà dal tuo computer...

Manipolare attributi

La maggior parte dei pattern fa uso di attributi per nascondere o visualizzare contenuti. Ad esempio: modal e accordion usano pulsanti e icone per visualizzare e nascondere il contenuto con un click; flipbox, slidebox e tooltip nascondono o visualizzano il contenuto in base alla presenza del puntatore su un contenitore o icona. Questi effetti sono facilmente ottenibili grazie all'uso degli attributi onclick e onhover e codice javascript. Nel caso di pattern più complessi da animare(come slideshow, carousel e slider) è richiesto invece aggiornare costantemente gli elementi contenitori che contengono gli indici degli elementi correnti ed elementi totali. Per questo ho incluso nel frontend 2 funzioni principali che si interfacciano con gli attributi per creare tutti questi effetti con il minor numero di linee di codice possibile. Va detto anche che benchè queste funzioni siano pensate e usate nei pattern non si limitano ad essi ma possono essere liberamente usate per altri casi d'uso e saranno aggiornate nel tempo per ampliarne le possibilità.

Funzione AttributeHandle

Questa funzione ha lo scopo di manipolare gli attributi su un elemento, le azioni attualmente disponibili sono:

  • remove (rimuove un attributo da un elemento)
  • set (imposta un attributo a un elemento)
  • alternate (alterna un attributo a un elemento in base alla sua esistenza corrente)

La maggior parte delle volte sarà applicata a pulsanti, icone o contenitori usando attributi come onclick e onhover, quindi l'elemento di partenza dal quale saranno ricavabili semplicemente gli altri sarà this. Esempi d'uso potrebbero essere essere: this.parentNode(per ottenere l'elemento padre di un'icona o pulsante), this.parentNode.nextElementSibling(per ottenere l'elemento successivo all'elemento padre) e così via. Vedere gli esempi per casi d'uso più specifici.

Parametri

  1. handle - stringa - obbligatorio
    I valori possibili sono: remove, set, alternate
  2. element - elemento - obbligatorio
    Elemento il cui attributo sarà manipolato
  3. name - stringa - obbligatorio
    Nome dell'attributo che sarà rimosso o impostato
  4. value - stringa - opzionale - default:name
    Valore dell'attributo nel caso di settaggio(se non specificato sarà uguale al nome dell'attributo), nel caso di rimozione invece sarà ignorato

Return

La funzione ritorna true nel caso di azione, false in caso contrario.

Esempi

//Mostra il contenuto del modal cliccando sul pulsante "apri modal", usata con attributo onclick
AttributeHandle( handle='remove', element=this.parentNode.nextElementSibling, name='hidden' );
//Nasconde il contenuto del modal cliccando sull'icona di chiusura, usata con attributo onclick
AttributeHandle( handle='set', element=this.parentNode.parentNode, name='hidden' );
//Il risultato delle due funzioni è equivalente: alternano l'attributo hidden con valore hidden all'elemento successivo all'elemento padre.
AttributeHandle( handle='alternate', element=this.parentNode.nextElementSibling, name='hidden' );
AttributeHandle( handle='alternate', element=this.parentNode.nextElementSibling, name='hidden', value='hidden' );

Un metodo semplice per capire l'elemento necessario in base alla struttura della pagina è utilizzare la vista elenco di gutenberg. Ad esempio: se vogliamo alternare l'attributo data-test al contenitore di un'icona possiamo, in gutenberg, visualizzarne la struttura per arrivare all'elemento da manipolare.

Funzione GetElementFromAttribute

Questa funzione serve a ottenere il primo elemento con un certo attributo e, opzionalmente, controlla il valore dell'attributo. La funzione va avanti fino a che la condizione sia rispettata o non ci siano più elementi validi nella direzione specificata. Questa funzione salta automaticamente i tag SCRIPT e STYLE (dato che molte volte sono usati nei pattern di default).

Parametri

  1. element - elemento - obbligatorio
    Elemento di partenza dal quale iniziare a cercare l'attributo
  2. name - stringa - obbligatorio
    Nome dell'attributo da cercare
  3. value - stringa - opzionale - default:name
    Valore dell'attributo nel caso che si voglia verificarne il valore, altrimenti sarà ignorato
  4. direction - stringa rappresentante una proprietà di un elemento js - opzionale
    Se impostato definisce la direzione di ricerca. E' anche possibile usarlo per una leggibilità migliore dell'elemento di partenza
  5. compare - stringa rappresentante un operatore di confronto - opzionale
    Operatore di confronto da usare se si vuole verificare il valore dell'attributo prima di restituire l'elemento, altrimenti continuerà la ricerca verso la direzione specificata. I Valori possibili sono: hasAttribute, ==, startsWith e i controlli equivalgono agli operatori/funzioni javascript omonimi.

Return

La funzione ritorna un elemento se la condizione è rispettata, false in caso contrario.

Esempi

//Memorizza in variabile il primo elemento che ha l'attributo data-animate-total partendo dal precedente e continuando a cercare nei precedenti, usato con attributo onclick su icona nello slideshow
AnimationContainer = GetElementFromAttribute( element=this.previousElementSibling, name='data-animate-total', value=name, direction='previousElementSibling', compare='hasAttribute' );

Monitorare la posizione di un elemento

E' possibile utilizzare le funzioni preinserite nel frontend del framework per monitorare la posizione di un elemento a ogni evento scroll. Al momento ho sviluppato solo la possibilità di monitorare la visibilità in percentuale di un elemento rispetto al viewport.

Funzione GetElementPosition

Ottiene la posizione di un elemento in una certa unità di misura rispetto al viewport o altro. Al momento ho sviluppato solo a possibilità di confrontare la visibilità in percentuale dell'elemento rispetto al viewport. Probabilmente questa funzione verrà modificata in quanto al momento non tiene conto di alcun listener javascript.

Parametri

  • element - elemento js - obbligatorio
    elemento di cui verrà calcolata la posizione
  • compare - stringa - opzionale - default:'viewport'
    elemento di confronto(al momento solo viewport)
  • ValueType - stringa - opzionale - default:'percentage'
    unità di misura utilizzata per il calcolo(al momento solo percentage)

Return

Percentuale di visibilità rispetto al viewport

Esempi

Al momento uno dei pochi usi indipendenti di questa funzione che ho trovato potrebbe essere l'animazione di un elemento a cui si arriva da un link con ancora:

//Ricarica la pagina da qui per vedere questo blocco comparire in 3 secondi
var CurrentElement = GetCurrentBlockFromCurrentScript();
CurrentElement.style.opacity = 0;
window.addEventListener('load', function(){	
	if( GetElementPosition( CurrentElement ) >= 50 ){
		CurrentElement.style.transition = '3s';  	
	}	
	CurrentElement.style.opacity = 1;
} );

Funzione MonitorElementPosition

Monitora la posizione di un elemento rispetto al viewport

Parametri

  • element - elemento js - obbligatorio
    elemento da monitorare
  • MinVisibility - numero intero - obbligatorio - default:50
    percentuale di visibilità dell elemento nel viewport per avviare la funzione OnPositionTrue
  • OnPositionTrue - oggetto con 2 sottoparametri - obbligatorio
    i 2 sottoparametri sono: FunctionName (il nome di una variabile funzione dato come stringa) e FunctionArgs (array di argomenti). Se si verifica la visibilità necessaria verrà chiamata la funzione (definita all'esterno con relativi parametri)
  • OnPositionFalse - oggetto con 2 sottoparametri - opzionale
  • i 2 sottoparametri sono identici a OnPositionTrue e probabilmente conterranno la rimozione di un'animazione con relativo controllo preventivo

Return

Nulla

Esempi

Per questo esempio portati poco più in basso e visualizza tutto lo spazio grigio, si colorerà interamente di rosso in un secondo.

var ColoraGrigio = function ( element ){
	if( element.style.background != 'grey' ){
		element.style.background = 'grey';
	}
}
var ColoraRosso = function( element ){
	element.style.background = 'red';
}
let element=GetCurrentBlockFromCurrentScript();
MonitorElementPosition( element, MinVisibility=100, OnPositionTrue={ FunctionName:ColoraRosso, FunctionArgs:[ element ] }, OnPositionFalse={ FunctionName:ColoraGrigio, FunctionArgs:[ element ] } );

DynamicVars

Le DynamicVars servono principalmente a memorizzare variabili e funzioni con un nome dinamico da associare a un elemento e solitamente sono usate insieme ai PinnedElements. Come questi trovano utilità nei pattern e nei loop di query in quanto non obbligano a specificare un id diverso per ogni elemento pur consentendone una funzione specifica per ognuno. Modo d'uso principale:

  1. la variabile DynamicVars è automaticamente preinizializzata come oggetto vuoto nel frontend nel file js-head.js, verrà poi popolata con la lista delle funzioni/variabili con nomi dinamici
  2. si assegna a una variabile funzione un nome+index del PinnedElement(che sarà quindi univoco all'interno dell'oggetto stesso)
  3. si inserisce la variabile funzione nell'oggetto DynamicVars
  4. si chiama la DynamicVar come funzione oppure si monitora la posizione dell'elemento da animare o gestire

Esempi

Vedi esempi su come è utilizzata in PinnedElements e in AnimateElements(qui sotto)

//Nell'autoforward consente di creare una funzione dal nome dinamico e memorizzarla come DynamicVar, questa funzione verrà eseguita sullo slideshow corrente per continuare l'animazione usando setInterval
DynamicVarInit = 'AnimateElementsInitAutoforward'+PinElement( element );
if( typeof DynamicVars[DynamicVarInit] == 'undefined' ){
  DynamicVars[DynamicVarInit] = function( element ){
    DynamicVarInit = 'AnimateElementsAutoforwardInterval'+GetPinnedElementIndex( element );
    if( typeof DynamicVars[DynamicVarInit] == 'undefined' ){
      DynamicVars[DynamicVarInit] = setInterval( function(){
        active = ( active+ActiveNumber ) % total;
        AnimateElements_UpdateAttrs();
        AnimateElements_Animation( element, type, active, animation, value, unit );
      }, delay );
    }
  }
}

//Qui viene definita la funzione che fermerà, usando clearInterval, l'animazione precedente (sempre collegata all'elemento)
DynamicVarRemove = 'AnimateElementsRemoveAutoforward'+GetPinnedElementIndex( element );
if( typeof DynamicVars[DynamicVarRemove] == 'undefined' ){
  DynamicVars[DynamicVarRemove] = function( element ){
    DynamicVarRemove = 'AnimateElementsAutoforwardInterval'+GetPinnedElementIndex( element );
    if( typeof DynamicVars[DynamicVarRemove] != 'undefined' ){
      clearInterval( DynamicVars[DynamicVarRemove] );
      DynamicVars[DynamicVarRemove] = undefined;
    }
  }
}			

//Qui viene monitorata la posizione dell'elemento e, se visibile o no, viene eseguita la funzione corrispondente
MonitorElementPosition( element, monitor, OnPositionTrue={ FunctionName:DynamicVars[DynamicVarInit], FunctionArgs:[ element ] }, OnPositionFalse={ FunctionName:DynamicVars[DynamicVarRemove], FunctionArgs:[ element ] } );

PinnedElements

I PinnedElements servono a puntare degli elementi in modo dinamico, trovano grande utilità nei loop di query e nei pattern e solitamente sono utilizzati insieme alle DynamicVars. Questo serve a poter usare gli elementi in un secondo momento senza dovere specificare un id per ognuno ma utilizzando 2 funzioni e un attributo di appoggio che verrà settato dalla prima funzione in modo dinamico. Modo d'uso generale:

  1. la variabile PinnedElements è automaticamente inizializzata come array vuoto nel frontend nel file js-head.js, verrà poi popolata con la lista di elementi
  2. l'elemento viene puntato con la funzione: PinElement( elemento ) che setta in un blocco come attributo l'indice dell'elemento puntato
  3. l'elemento viene ottenuto dall'array PinnedElements usando l'attributo settato prima

Funzione PinElement

Memorizza nell'array PinnedElements un elemento ed imposta all'elemento l'indice necessario a trovarlo successivamente come attributo data-pinned-element-index.

Parametri

  • element - elemento js - obbligatorio
    elemento che verrà aggiungo all'array PinnedElements e a cui verrà applicato l'attributo data-pinned-element-index
  • ReturnIndex - booleano - opzionale - default:true
    se true o non specificato: la funzione ritorna l'indice dell'elemento

Return

Se il parametro ReturnIndex è true: ritorna l'indice dell'elemento puntato, altrimenti nulla.

Esempi

Iniziamo dal più facile: questo è un estratto di quello che succede nel blocco codice con syntax highlighting (ho omesso le parti inutili). Puoi verificare in console sviluppatori per maggior riscontro.

//ottengo il blocco corrente
CoreCodeBlock = GetCurrentBlockFromCurrentScript();

//creo una variabile con valore: nome che sarà ripetuto + un numero unico
//il numero è l'indice restituito dalla funzione PinElement
//PinElement flagga anche il blocco con l'attributo data-pinned-element-index
DynamicVar = 'CoreCodeBlockVar'+PinElement( CoreCodeBlock );

//inserisco nell'oggetto DynamicVars la risultante proprietà unica come funzione
//ora possiamo avere tanti listeners quanti sono i blocchi di codice con syntax highlighting 
DynamicVars[DynamicVar] = function( element ){
document.addEventListener( 'DOMContentLoaded', function(){
	CodeMirror( element, {} );
	element.querySelector('code').remove();
} );

//chiamo la funzione unica passando il blocco corrente come parametro
DynamicVars[DynamicVar]( CoreCodeBlock );

Funzione GetPinnedElementIndex

Ottiene l'attributo data-pinned-element-index da un elemento. Al momento è usato negli autoforward delle animazioni.

Parametri

  • element - elemento js - obbligatorio
    elemento che ha l'attributo data-pinned-element-index

Return

Ritorna il valore dell'attributo data-pinned-element-index

Esempi

Estratto della funzione AnimateElements, dove viene creato un autoforward quando è visibile lo slideshow e fermato quando non è visibile.

//element è il contenitore dello slideshow/slider
DynamicVarInit = 'AnimateElementsAutoforwardInterval'+GetPinnedElementIndex( element );
if( typeof DynamicVars[DynamicVarInit] == 'undefined' ){
  //qui viene descritta una funzione che avvia lo slideshow
  /*DynamicVars[DynamicVarInit] = setInterval( function(){
    active = ( active+ActiveNumber ) % total;
    AnimateElements_UpdateAttrs();
    AnimateElements_Animation( element, active, type, animation, value, unit );
  }, delay );*/
}

DynamicVarRemove = 'AnimateElementsAutoforwardInterval'+GetPinnedElementIndex( element );
if( typeof DynamicVars[DynamicVarRemove] != 'undefined' ){
  //qui viene descritta una funzione che ferma lo slideshow
  /*clearInterval( DynamicVars[DynamicVarRemove] );
  DynamicVars[DynamicVarRemove] = undefined;*/
}

Funzioni per animazioni

Sono disponibili anche alcune funzioni per animare elementi e gruppi di elementi in modo semplice e con pochissime linee di codice, sono documentate nella pagina animazioni.