<

Javascript

Ultima modifica: 10 Agosto 2026

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 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.

AjaxPublicUrl

Tipo: stringa

Url del file ajax-public.php, serve a eseguire azioni ajax (come form via javascript o azioni personalizzate).

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

Nel tuo caso, ScreenWidth è:

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.

Nel tuo caso, ScreenWidthWithZoom è:

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;
} );

Nel tuo caso, ScreenWidthWithZoom in continuo aggiornamento è:

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...

ElementAction

Questa funzione esegue un'azione su uno più elementi del DOM esistente, segue indicativamente la stessa logica della funzione php HtmlAction. In un secondo momento, se utile, aggiungerò la possibilità di manipolare un dom esterno o simulato. Per ora le selezioni saranno sempre riferite al document corrente. Questa funzione sostituirà o ingloberà varie funzioni precedenti.

Parametri

  1. action - stringa - azione da eseguire - default:''
  2. element - stringa/oggetto - stringa html/selettore_css/oggetto. Elemento/i bersaglio dell'azione, che devono essere esistenti. Possono essere elementi multipli solo se in formato css - default: ''
  3. args - oggetto - argomento aggiuntivi da applicare - default:{}

Note

La funzione cercherà il primo elemento esistente come da parametro element. Nel caso che esistano vari elementi simili (probabile caso di selettore css) cercare di essere il più specifici possibile.

Return

In base all'azione. In caso di errori sarà stampato un messaggio in console sviluppatori. Se l'elemento è in formato css ed è una query di elementi multipli (quindi separati da una virgola) ritornerà un array di valori in base all'azione.

Azioni/args

Argomenti comuni

Gli argomenti comuni a tutte le azioni sono:

  • event - stringa/false - nome dell'evento da aspettare prima di eseguire la funzione - default:false
  • event_target - stringa html/selettore_css/oggetto - elemento bersaglio collegato all'evento(se applicabile), rispetta le stesse regole del parametro element - default:false
  • event_repeat - booleano - se ripetere l'evento oppure rimuovere il listener appena eseguita la funzione. In un secondo momento sarà aggiunta la possibilità di specificare anche un numero di ripetizioni massime - default:true
- get_type

Questa azione ottiene il tipo di elemento bersaglio. Ritorna una stringa rappresentante il primo tipo trovato come da seguente lista:

  1. object - se oggetto rappresentante un elemento
  2. css - un selettore css
  3. html - se stringa html. Può essere molto utile per identificare l'elemento copiando il suo codice html dalla console sviluppatori. Se un elemento è piuttosto complicato sarà più semplice utilizzare il backtick ` al posto di ' o ".
  4. false se l'elemento non esiste o se non rispetta i punti precedenti

E' utilizzata soprattutto internamente per capire il tipo di input.

$args: Nessuno.

Esempi
//css
let type = ElementAction( action='get_type', element='#footer-primary' );

//html
let type = ElementAction( action='get_type', element=`<header>Contenuto...</header>` );

//object
let h1 = document.createElement('h1');
h1.classList.add('wp-block-post-title');
h1.textContent = 'Titolo post';
let type = ElementAction( action='get_type', element=h1 );

//ottiene i tipi di vari elementi
let types = ElementAction( action='get_type', elements='#header-primary, #footer-primary' ] );
types.forEach( (t)=>{
  console.log( t );
} );
- get

Ottiene l'elemento bersaglio nel formato richiesto. Se l'input non è nel formato richiesto sarà convertito automaticamente tramite l'azione convert_to. Se non è possibile ottenere l'elemento ritorna false.

args:

  • format - stringa - formato da ottenere - default: 'object'
Esempi
//Stampiamo in console la header del sito:
console.log( ElementAction( action='get', element='header' ) );

//otteniamo l'elemento con id footer-primary
let element = ElementAction( action='get', element='#footer-primary' );

//otteniamo un elemento dal suo html
let element = ElementAction( action='get', element='<h3 class="wp-block-heading" id="AjaxAction">AjaxAction</h3>' );
//stessa cosa con il backtick
let element = ElementAction( action='get', element=`<h3 class="wp-block-heading" id="AjaxAction">AjaxAction</h3>` );

//otteniamo la header del sito in formato html
let element = ElementAction( action='get', element='header', args={ format:'html' } );

//otteniamo, in un array, la header e il footer del sito in formato html
let array = ElementAction( action='get', elements='header, footer' ] );
array.forEach( (el)=>{
  console.log( el );
} );
- get_fields

Ottiene i campi compilabili e li ritorna come oggetto. Per ora i campi ottenibili sono di tipo input, textarea e select. Se un campo non passa il controllo checkValidity al posto del suo valore sarà memorizzato false, questo consente di fermare azioni ajax se il controllo non passa.

args: nessuno.

Esempi
//Ottiene i campi compilabili da un contenitore
let fields = ElementAction( action='get_fields', element='#id_contenitore' );
- convert_to

Converte l'elemento bersaglio da un tipo a un altro, se necessario. Serve per poterlo selezionare o utilizzare in in un contesto differente. Ritorna l'oggetto convertito (oppure l'originale se il tipo è come il to), false in caso di fallimento.

$args:

  • to - stringa - tipo di elemento verso cui convertire, è possibile utilizzare i tipi riconosciuti, ossia: css, html o object - default:'html'
Esempi
//convertiamo la prima header della pagina in html
let el = ElementAction( action='convert_to', element='header' );
//stessa cosa di
let el = ElementAction( action='convert_to', element='header', args={ to:'html' } );
//stessa cosa di
let el = ElementAction( action='convert_to', element='#header-primary', args={ to:'html' } );

//convertiamola ora in oggetto
let el = ElementAction( action='convert_to', element='header', args={ to:'object' } );

//convertiamo il titolo del post in selettore css
//il risultato sarà qualcosa come: h1.wp-block-post-title
let el = ElementAction( action='convert_to', element=`<h1 class="wp-block-post-title">Javascript</h1>`, args={ to:'css' } );

//ora convertiamolo in oggetto
let el = ElementAction( action='convert_to', element=`<h1 class="wp-block-post-title">Javascript</h1>`, args={ to:'object' } );

//convertiamo un oggetto che rappresenta il titolo del post in html
let  h1 = document.createElement('h1');
h1.classList.add('wp-block-post-title');
h1.textContent = 'Javascript';
let el = ElementAction( action='convert_to', element=h1, args={ to:'html' } );
//stessa cosa ma a selettore css
let el = ElementAction( action='convert_to', element=h1, args={ to:'css' } );
- remove

Rimuove l'elemento bersaglio dal DOM. Non ritorna nulla.

$args: nessuno.

Esempi
//eliminiamo il titolo del post dal suo selettore css
ElementAction( action='remove', element='h1.wp-block-post-title' );

//eliminiamo il titolo del post dal suo codice html
ElementAction( action='remove', element=`<h1 class="wp-block-post-title">Javascript</h1>` );
- add_element

Aggiunge un elemento o una stringa html alla posizione specificata rispetto all'elemento bersaglio. Non ritorna nulla.

$args:

  • element - oggetto/stringa html - elemento da aggiungere, se vuoto non sarà eseguito nulla - default:''
  • position - stringa - posizione rispetto all'elemento bersaglio come da funzioni insertAdjacentElement e insertAdjacentHTML. Può quindi essere:
    - beforebegin
    - afterbegin
    - beforeend
    - afterend (default)
Esempi
//aggiungiamo un paragrafo dopo il titolo del post (in questo caso potrei omettere position)
ElementAction( action='add_element', element='h1.wp-block-post-title', args={ element:`<p style="background:red;">testo</p>`, position:'afterend' } );
//stessa cosa ma prima del titolo del post
ElementAction( action='add_element', element='h1.wp-block-post-title', args={ element:`<p style="background:red;">testo</p>`, position:'beforebegin' } );

//aggiungiamo un li a una lista, all'inizio
ElementAction( action='add_element', element='ul', args={ element:'<li>testo</li>', position:'afterbegin' } );

//aggiungiamo un li a una lista, alla fine
ElementAction( action='add_element', element='ul', args={ element:'<li>testo</li>', position:'beforeend' } );
//stessa cosa ma con selettore css E solo a caricamento DOM
ElementAction( action='add_element', element='ul', args={ element:'<li>testo</li>', position:'beforeend', event:'DOMContentLoaded' } );
//stessa cosa ma ogni volta che si clicca su un pulsante con un certo id
ElementAction( action='add_element', element='ul', args={ element:'<li>testo</li>', position:'beforeend', event:'click', event_target:'#id_bersaglio' } );
//stessa cosa ma solo la prima volta che si clicca su un pulsante con un certo id
ElementAction( action='add_element', element='ul', args={ element:'<li>testo</li>', position:'beforeend', event:'click', event_target:'#id_bersaglio', event_repeat:false} );

//stessa cosa ma con selettore css E solo a caricamento DOM E con un'ulteriore attesa di 5 secondi
//ElementAction( action='add_element', element=`#AjaxAction`, args={ event:'DOMContentLoaded', delay:5000 } );
- replace_with_element

Sostituisce il bersaglio con un elemento o una stringa html. Non ritorna nulla.

$args:

  • element - oggetto/stringa html - elemento da aggiungere, se vuoto non sarà eseguito nulla - default:''
Esempi
//sostituisce il titolo del post con un paragrafo
ElementAction( action='replace_with_element', element='h1.wp-block-post-title', args={ element:`<p style="background:red;">testo</p>` } );

//sostituisce lo script corrente con un testo
ElementAction( action='replace_with_element', element=document.currentScript, args={ element:'testo' } );
- add_event_listener

Aggiunge un evento filtrabile al document. Non ritorna nulla. Questa azione non utilizza element (dato che un target dell'evento è opzionale) che può quindi essere settato a false.

$args:

  • event_target - stringa html/selettore_css/oggetto - elemento bersaglio collegato all'evento(se applicabile), rispetta le stesse regole del parametro element - default:false
  • event_repeat - booleano - se ripetere l'evento oppure rimuovere il listener appena eseguita la funzione. In un secondo momento sarà aggiunta la possibilità di specificare anche un numero di ripetizioni massime - default:true
  • function_name - stringa - nome della funzione da eseguire appena si verifica l'evento - default:false
  • function_args - stringa - eventuali argomenti inerenti la funzione da eseguire appena si verifica l'evento, sotto fprma di array - default:[]
Esempi
//eseguiamo una funzione personalizzata al caricamento del DOM
function funzione_personalizzata(){ 
  console.log( 'Funzione eseguita!' );
}
ElementAction( action='add_event_listener', element=false, { event:'DOMContentLoaded', function_name:'funzione_personalizzata' } );
//stessa cosa ma ogni volta che si esegue un click
ElementAction( action='add_event_listener', element=false, { event:'click', function_name:'funzione_personalizzata' } );
//stessa cosa ma ogni volta che si esegue un click su un determinato elemento
ElementAction( action='add_event_listener', element=false, { event:'click', event_target:'#id_bersaglio, function_name:'funzione_personalizzata' } );
//stessa cosa ma la prima volta che si esegue un click su un determinato elemento
ElementAction( action='add_event_listener', element=false, { event:'click', event_target:'#id_bersaglio, event_repeat:false, function_name:'funzione_personalizzata' } );

//eseguiamo una funzione personalizzata al caricamento del DOM con 1 argomento, inoltre la ritardiamo di 3 secondi
function funzione_personalizzata( argomento1 ){
  setTimeout( function(){ console.log( argomento1 ); }, 3000 );
}
ElementAction( action='add_event_listener', element=false, { event:'DOMContentLoaded', function_name:'funzione_personalizzata', function_args:['Valore argomento 1!'] } );

ResolveWindowProperty

Questa funzione risolve una proprietà window partendo da una stringa in questo modo:

  • se array la sua risoluzione sarà: value[0] è nome di una funzione globale, gli elementi successivi i suoi argomenti, args non è utilizzato
  • se oggetto chiave/valore: risolve tutti i valori di tipo stringa/array (non ricorsivamente) eliminando dall'oggetto le chiavi con valore undefined, args non è utilizzato
  • se stringa la sua risoluzione sarà: value è un oggetto globale o il nome di una funzione, args eventuali argomenti della funzione
  • negli altri casi ritornerà undefined

Parametri

  1. value - stringa/array/oggetto - valore da risolvere - default:''
  2. args - array/oggetto - argomento aggiuntivi da applicare - default:{}

Return

Il valore risolto, undefined per casi non previsti.

Esempi

//Ritorna la lingua predefinita del browser corrente
content = ResolveWindowProperty( value='navigator.language' );

//Ritorna il risultato della funzione globale FunzioneSenzaArgomenti
content = ResolveWindowProperty( value='FunzioneSenzaArgomenti' );

//Ritorna il risultato della funzione globale FunzioneConArgomenti
content = ResolveWindowProperty( value='FunzioneConArgomenti', args=[ 'argomento1', 'argomento2' ] );

//Ritorna l'oggetto con i valori risolti
content = ResolveWindowProperty( value={ "lingua":"navigator.language", "Proprieta1":"FunzioneSenzaArgomenti", "Proprieta2":["FunzioneConArgomenti", "argomento1", "argomento2"] } );

GetNestedValue

Questa funzione ottiene un valore interno a un oggetto come la funzione php GetNestedValue ma applicata a un oggetto javascript.

Parametri

  1. value - oggetto - valore da risolvere
  2. nesting - stringa - nesting separati da punti

Return

Valore nested, null se la una proprietà o il percorso indicato non esistono. Valore originale se non è un oggetto.

Esempi

let obj = { nome:'luigi', cognome:'gaudino', indirizzi:{ indirizzo_1:'Via bologna 1', indirizzo_2:'Via Milano 2' } };

//otteniamo tutti gli indirizzi
let sedi = GetNestedValue( obj , 'indirizzi' );

//otteniamo solo il secondo indirizzo
let indirizzo_2 = GetNestedValue( obj , 'indirizzi.indirizzo_2' );

RemoteRequest

Questa è la versione javascript della funzione php RemoteRequest . Ci sono alcune diffeerenze ma l'dea è renderle il più intercambiabili possibile.

Parametri

  1. url - stringa/oggetto
  2. request_args - oggetto
  3. payload - oggetto
  4. extra_args - oggetto

Return

Promise.

Esempi

RemoteRequest(
  url='https://pokeapi.co/api/v2/pokemon/',
  request_args={ 'method':'GET' },
  payload={},
  extra_args={ 'return':'normal', 'response_target':'promise' }
).then( function(response){ console.log( response.body.count ); } );
//equivalente di
RemoteRequest(
  url='https://pokeapi.co/api/v2/pokemon/',
  request_args={ 'method':'GET' },
  payload={},
  extra_args={ 'return':'normal.body.count', 'response_target':'promise' }
).then( function(response){ console.log( response ); } );

//sostituiamo un pulsante (id="pulsante") con il nome del primo pokemon
RemoteRequest( url='https://pokeapi.co/api/v2/pokemon/', request_args={ 'method':'GET' }, payload={ limit:5 }, extra_args={ 'return':'normal.body.results.0.name', 'response_target':'#pulsante' } );

//stampiamo in console un array contenente i nomi dei primi 5 pokemon
RemoteRequest( url='https://pokeapi.co/api/v2/pokemon/', request_args={ 'method':'GET' }, payload={ limit:5 }, extra_args={ 'return':'normal.body.results.*.name', 'response_target':'console.log' } );
//stessa cosa ma solo previa conferma e con messaggio personalizzato
RemoteRequest( url='https://pokeapi.co/api/v2/pokemon/', request_args={ 'method':'GET' }, payload={ limit:5 }, extra_args={ 'return':'normal.body.results.*.name', 'response_target':'console.log', 'confirm':true, confirm_text:'Sei sicuro di continuare?' } );

//stampiamo in console una lista numerata dei nomi dei primi 5 pokemon
RemoteRequest(
  url='https://pokeapi.co/api/v2/pokemon/',
  request_args={ 'method':'GET' },
  payload={ limit:5 },
  extra_args={ 'return':'normal.body.results.*.name' }
).then( function(response){ response.forEach( (v,i)=>{ console.log( i+'. '+v ); } ); } );

//richiesta rest di ricette su un blog di cucina, visualizziamo gli endpoint e gli argomenti
RemoteRequest(
  url={ 'url':'https://www.sito_cucina.com/blog/', 'endpoint':'wp_rest' },
  request_args={ 'method':'GET' },
  payload={},
  extra_args={ 'return':'normal.body', 'response_target':'console.log' }
);

//ora otteniamo i links di 5 ricette, saltando le prime 2
RemoteRequest(
  url={ 'url':'https://www.sito_cucina.com/blog/', 'endpoint':'wp_rest' },
  request_args={ 'method':'GET' },
  payload={ 'post_type':'ricetta', 'per_page':5, 'offset':2 },
  extra_args={ 'return':'normal.body.*.link', 'response_target':'console.log' }
);

//ora eseguiamo un'azione ajax tramite hook wordpress
RemoteRequest(
  url={ 'url':'https://sito.it', 'endpoint':'wp_admin_ajax' },
  request_args={ 'method':'GET' }, 
  payload={ 'action':'mia_azione' },
  extra_args={ 'return':'normal.body', 'response_target':'console.log' }
);

//ora creiamo un post tramite rest
//al post di slug_post_type è possibile anche utilizzare post, page o media; la funzione proverà a configurare tutto automaticamente
RemoteRequest(
  url={ 'url':'https://sito.it', 'endpoint':'wp_rest' },
  request_args={ 'method':'POST', 'user_login':'nome_utente', 'application_password':'generare_password_app_da_schermata_utenti' }, 
  payload={ 'post_type':'slug_post_type', 'title':'Titolo', 'content':'Contenuto', 'status':'draft' },
  extra_args={ 'return':'normal', 'response_target':'#id_bersaglio'}
);

//carichiamo un media su un blog tramite rest, è possibile anche aggiungere campi con name=title, alt o altri campi documentati
RemoteRequest(
  url={ 'url':'https://sito.it', 'endpoint':'wp_rest' },
  request_args={ 'method':'POST', 'user_login':'nome_utente', 'application_password':'generare_password_app_da_schermata_utenti' }, 
  payload={ 'post_type':'media', 'title':'Titolo media', 'file':document.getElementById('file').files[0], 'fields':['#contenitore_altri_campi'] },
  extra_args={ 'return':'normal', 'response_target':this, 'normalize_response':true }
);
//stessa cosa ma il file sarà ottenuto automaticamente dal contenitore senza bisogno di essere inserito manualmente
//è importante che il campo del file da caricare abbia l'attributo name=file
//notare che i campi dinamici da campi del form avranno la predecenza sui campi statici
RemoteRequest(
  url={ 'url':'https://sito.it', 'endpoint':'wp_rest' },
  request_args={ 'method':'POST', 'user_login':'nome_utente', 'application_password':'generare_password_app_da_schermata_utenti' }, 
  payload={ 'post_type':'media', 'title':'Titolo media', 'fields':['#contenitore_campo_file'] },
  extra_args={ 'return':'normal', 'response_target':this, 'normalize_response':true }
);

Documentazione rilevante

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)

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 poi 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.