Conversione dinamica

Nel wordpress Gpci framework è presente in varie zone un sistema per convertire un contenuto da statico a dinamico. Il funzionamento è molto semplice e consiste fondamentalmente in 2 campi gutenberg o personalizzati: uno ospita una stringa statica mentre l'altro la converte verso il tipo scelto. Nel backend il selettore e il controllo associato che generano una conversione dinamica sono segnalati da un contenitore con sfondo grigio e bordo laterale per poter essere subito visibili durante la configurazione del blocco. Infine, nel frontend, la conversione viene eseguita tramite php. Questa conversione verrà espansa con il tempo in base alle esigenze del framework.

Conversione da javascript a php

Per convertire da tipo a contenuto è sufficiente selezionarne il tipo tramite il selettore tipo di valore e, nel controllo sottostante, si inserisce il contenuto. Vediamo per esempio un'immagine dal gruppo di controlli attributi:

Il selettore tipo di valore è associato in questo caso alla textarea. Questo significa che il valore della textarea cambierà dinamicamente nel frontend in base al selettore. Nello specifico di questo caso:

• Se selezionata stringa: il valore sarà convertito a stringa
• Se selezionato campo wordpress: nel valore si inserisce il nome di un campo wordpress
• Se selezionato campo personalizzato: nel valore si inserisce il nome di un campo personalizzato
• e così via...

La conversione nel frontend viene eseguita automaticamente verso il tipo di valore scelto.

Argomenti aggiuntivi

Sotto alla coppia tipo/valore è visibile (solo se amministratori) una textarea in cui poter scrivere argomenti opzionali, alcuni sono comuni a tutte le conversioni altri in base al tipo scelto. Gli argomenti possono essere inseriti in formato json ( con o senza delimitatori {} )oppure json semplificato in quanto convertiti dalla funzione JsonAction. E' possibile utilizzare shortcodes nei valori per renderli dinamici. Gli argomenti functions, nesting, json e readable saranno processati nell'ordine di inserimento per permettere combinazioni e risultati liberi. Esempio di definizione argomenti:

database:sitoesterno
delete_cache_end:false
nesting:chiave
readable:true

La lista degli argomenti aggiuntivi è:

origin

Utilizzato internamente per capire il chiamante della conversione dinamica.

maybe_convert

- booleano - se provare ad eseguire una conversione dinamica ed utilizzare il valore originale come fallback - default: false

Questo argomento serve a fare ritornare il valore originale nel caso che la conversione non sia possibile o malformata (normalmente ritornerebbe null), esempio: tipo non esistente o coppia tipo/valore non determinata. Serve soprattutto nelle stringhe che potrebbero essere conversioni dinamiche ma anche stringhe normali. Esempi (solo valori):

//sarà eseguita la conversione:
wp,title

//non sarà eseguita la conversione
wpa,title

disable_error_messages

booleano - se disabilitare i messaggi di errore dalla conversione dinamica - default: false

Questo argomento serve a disabilitare i messaggi di errore nella conversione dinamica. Ha senso utilizzarlo quando vengono utilizzate 2 conversioni dinamiche e la seconda è un fallback della prima come nel caso della funzione php GetField. Esempio:

disable_error_messages:true

database

stringa - id del database da utilizzare per il recupero del valore - default:''

Utilizzando questo argomento, per i campi di tipo wordpress o metabox, è possibile ottenere il valore da un database esterno. Notare che il database va aggiunto prima tramite php utilizzando la funzione DatabaseAction (azione add). L'ideale, quando si ottiene un valore da un database esterno, è eliminare le caches relative al valore utilizzando gli argomenti delete_cache_start e delete_cache_end settandoli su true (serve a evitare che wordpress restituisca il valore in cache che probabilmente sarà diverso da quello che si sta cercando invece di cercarlo nel database secondario). Se invece il valore deve essere riutilizzato più volte nella pagina ha senso invece svuotare la cache prima di ottenerlo la prima volta e dopo averlo ottenuto l'ultima volta. Esempi:

//passa al database secondario
database:id_database_secondario

//passa al database secondario eliminando le caches relative sia prima che dopo aver ottenuto il valore
delete_cache_start:true
database:id_database_secondario
delete_cache_end:true

delete_cache_start

booleano - se eliminare la cache prima di ottenere il valore (da usare solo con database esterno) - default:false

//esempio
delete_cache_start:true

delete_cache_end

booleano - se eliminare la cache dopo aver ottenuto il valore (da usare solo con database esterno) - default:false

//esempio
delete_cache_end:true

nesting

Stringa di chiavi separate da una virgola - Permette di poter ottenere il valore interno di un array o un oggetto avanzando tra le sue chiavi interne. default:-1

//esempio
nesting:0

json

booleano - Se il valore deve essere convertito a stringa json. Default:false

//esempio
json:true

readable

booleano - Se il valore deve essere convertito a stringa json formattata (delimitata da tag pre), serve agli amministratori (solo loro vedranno il risultato) per capire dove si trova il valore che si vuole ottenere in array e oggetti. Default:false

//esempio
readable:true

functions

Stringhe separate da una virgole - Questo argomento serve a manipolare il valore di ritorno subito prima di generarlo. Si inserisce il nome di una o più funzioni separate da una virgola, se le funzioni esistono e sono in whitelist (ricordarsi di aggiungerle!) il valore verrà processato da ogni funzione nell'ordine inserito prima di essere generato. Le funzioni possono prendere in ingresso fino a 1 un parametro come il valore in ingresso (probabilmente stringa o numero) e ritornarlo alla fine dopo le modifiche. Se le funzioni non esistono o non sono in whitelist la conversione genererà un messaggio di errore senza modificare il valore (ricordarsi che le funzioni vengono processate una per volta quindi potrebbero esserne ad esempio eseguite 2 e la terza potrebbe generare l'errore).

//esempio
functions:funzionepersonalizzata1,funzionepersonalizzata2

falsy_to_null

booleano - se true i valori falsy (come false, 0 e valori vuori) saranno automaticamente convertiti a null. Questo parametro può servire nelle conversioni dinamiche multiple con fallbacks o per semplificare i controlli in campi che possono restituire valori falsy - default: false

//esempio
falsy_to_null:true

Argomenti aggiuntivi riservati a determinate opzioni

I seguenti argomenti aggiuntivi sono applicabili solo a determinate opzioni:

custom

Questo argomento serve per passare argomenti personalizzati calcolati da php alle conversione (per ora è usato solo in valore javascript, azione ajax e funzione php). I valori di questi argomenti saranno soggetti alla conversione dinamica (con parametro maybe_convert => true). Questi sotto argomenti saranno solitamente accessibili in base al tipo di conversione (solitamente inserendo custom come argomento nel valore). Esempi:

"custom":{
  "chiave1":"valore1",
  "postid":"[render_data data="id"]"
}
//stessa cosa di
custom:{
  chiave1:valore1
  postid:[render_data data="id"]
}
//stessa cosa di
custom:{
  chiave1:valore1
  postid:wp,id
}

custom_javascript

Questo argomento è simile all'argomento custom visto sopra ma serve a passare sotto argomenti (funzioni o oggetti del window) tramite javascript invece che php. Per ora è usato solo in valore javascript e azione ajax e, tramite la funzione javascript ResolveWindowProperty, risolve i valori dei sotto argomenti. Esempi:

custom_javascript:{
  lingua:navigator.language
  Proprieta1:FunzioneSenzaArgomenti
  Proprieta2:FunzioneConArgomenti,argomento1,argomento2
}

fields

Questo argomento è applicato per ora solo all'azione ajax e serve a inviare i valori di uno o piu campi compilabili dagli utenti come in un form per potere essere usati dalla funzione php. Il suo valore è un array o una stringa, ossia uno più selettori css (il/i contenitore/i dei campi): tutti i valori dei campi supportati al suo interno saranno ottenuti dalla funzione javascript ElementAction (azione get_fields) e inviati al server. Anche in questo caso, per supportare le queries o situazioni particolati i valori saranno soggetti alla conversione dinamica (con parametro maybe_convert => true). Esempi:

fields:#contenitore_campo_campi_id_div

//oppure in una query
fields:#contenitore_campo_campi_id_[render_data data="id"]-div

method

Questo argomento è applicato solo all'azione ajax e serve a forzare il metodo della richiesta. Esempi:

method:POST

file

Questo argomento è applicato al file e serve a specificare il percorso/url del file quando non è possibile inserirlo direttamente nel valore (molto raro). Esempi:

file:percorso_oppure_url_file

Selettore tipo di valore

Il selettore tipo di valore ha varie opzioni, ma non tutte sono disponibili in tutti i casi in quanto ho deciso quali inserire caso per caso in base all'utilità del contesto (comunque ci saranno sicuramente variazioni e/o aggiunte). Ad esempio nel gruppo di controlli attributi le opzioni disponibili sono quelle viste nell'immagine sopra, mentre nel gruppo di controlli condizioni di rendering le opzioni disponibili nel selettore tipo di valore sono quelle viste sopra con aggiunta di:

• array di stringhe
• numero intero
• array di numeri interi
• booleano

Va specificato che alcune opzioni sono disponibili soltanto agli amministratori e, nel caso di un blocco gutenberg, se il post è successivamente modificato da un utente non amministratore il blocco stesso non sarà modificabile dall'utente senza i permessi sufficienti. Per altre informazioni leggere la parte sugli AdminOnlySettings. E' importante specificare anche che nei casi in cui l'informazione ritorna un oggetto sarà convertito ad array (vedi sotto).

Opzioni disponibili

Le opzioni, che siano in un gruppo di controlli o in un altro, si comportano sempre nello stesso modo; le opzioni selezionabili sono (tra parentesi è indicato il valore):

Non usare (none)

Il valore non verrà utilizzato. In questo e unico caso il valore diventerà null.

Valore originale (original)

Il valore resterà quello originale senza manipolazioni php nè possibilità di shortcodes. La stragrande maggioranza delle volte sarà una stringa ma in certi cari potrebbe essere ad esempio un numero o booleano.

Stringa (string)

Selezionando questa opzione il valore verrà convertito a stringa in grado di processare shortcodes. Inserire una stringa. Esempio:

Il nome di questo documento è: [render_data data="title"]

Risultato: Il nome di questo documento è: Conversione dinamica

Array di stringhe (arraystrings)

Il valore verrà convertito a un array di stringhe, inserire stringhe separate da una virgola. Questo valore supporta shortcodes. Esempio:

prima stringa,seconda stringa

//oppure
[render_data data="title"],[render_data data="permalink"]

Numero intero (integer)

Selezionando questa opzione il valore verrà convertito a numero intero, inserire un numero intero. Questo valore supporta shortcodes.

Array di numeri interi (arrayintegers)

Il valore verrà convertito in un array di numeri interi, inserire numeri interi separati da una virgola. Questo valore supporta shortcodes. Esempio:

10,20

//oppure
[render_data data="id,id"],[render_data data="id,500"]

Booleano (boolean)

Il valore verrà convertito in booleano, inserire true o false (anche in maiuscolo). Notare che il valore inserito è diverso da true diventerà sempre false. Questo valore supporta shortcodes.

title

title,id

title,3453

id

last_id

permalink

content,4259

content,4259,testo_link_more,true

content,4259,null,false,false

excerpt

author

post_field,id,post_title

post_type

post_type_object,id,name

post_type_object,id,label

post_type_object,id

date

date,id,l - F j - Y

date,id,l, F j, Y

modified_date

post_timestamp,id,modified

post_thumbnail_url,7011,full

post_thumbnail_url,7011,345w

queried_object

readable:true

queried_object,slug

attachment_image_src,7011,thumbnail

//Ottiene l'immagine di anteprima del post corrente
attachment_image_src,post_thumbnail_id

comments_number,id

bloginfo

bloginfo,description

theme_mod,custom_logo

//imposta anche un valore default
theme_mod,custom_logo,50

//controlla se l'utente correte è amministratore
current_user_can,administrator

userdata

userdata,id,user_email

userdata,id,user_login

userdata,id,ID

userdata,id,roles

userdata,id,allcaps

userdata,id,user_can,edit_files

userdata,id,user_can,upload_files

[render_data data="block_content"]

post
//oppure
post,null

single_additions_css

single_additions_css,id

esempio-file,3453,limit:1

esempio-file,3453,limit:1,0,url

campo-utente,id,object_type:user

esempio,opzionisito,object_type:setting

campo_data,id,format:d-m-y

functions:localize date

Campo personalizzato - value (mb_value)

Come sopra ma il valore verrà convertito utilizzando la funzione rwmb_the_value. Questo serve ad ottenere ad esempio le labels dei campi di tipo select e checkbox e altri tipi di valori (vedere il metabox builder per un aiuto). Notare che il quarto argomento $echo è sempre settato su false.

Richiesta GET (GET)

Selezionando questa opzione è possibile inserire nel campo valore il nome di una query string e ne sarà restituito il valore. E' possibile specificare un valore default se non esiste la richiesta GET specificata separando con una virgola e iniziando una conversione dinamica. Se non specificato un valore predefinito e non esiste la richiesta il valore sarà una stringa vuota. Solitamente questa opzione sarà utilizzata probabilmente nei form php per assegnare automaticamente a un campo il valore inserito dell'utente dopo il ricaricamento della pagina oppure per assegnare dei valori predefiniti a una query. Notare che per ora non funziona correttamente nei form inviati tramite javascript, verrà sistemato in un secondo momento. Esempi:

https://www.gigitopcinformatica.it/docs/gpci-framework/?BlockFormId=ricerca-gpciframework-docs&cercadocpostid=&cercadocs=test

Richiesta GET: cercadocs
Valore restituito: test

https://www.gigitopcinformatica.it/docs/gpci-framework/

Richiesta GET: cercadocs,string,valore_predefinito
Valore restituito: valore_predefinito

https://www.gigitopcinformatica.it/docs/gpci-framework/

//per ottenere come default tutti i risultati in una query:
Richiesta GET: nomerichiesta,none

Globale php controllata (global)

Selezionando questa opzione è possibile inserire nel campo valore il percorso di una globale php controllata: il meccanismo è lo stesso descritto nello shortcode globals ma lo start deve essere sempre specificato, separare con una virgola per ottenere le sottochiavi. Esempi:

$GLOBALS['custom']['stringa'] = 'Stringa fissa';

Valore: custom,stringa

Risultato: Valore stringa fissa

Questo può essere molto utile ad esempio nelle queries dove utilizzando il blocco gutenberg globals e aggiungendo valori, gli stessi possono essere ottenuti esternamente alla query per generare ad esempio dati strutturati o altro.

Funzione php (function)

AdminOnlySettings

Selezionando questa opzione è possibile inserire nel campo valore il nome di una funzione e, opzionalmente, ulteriori argomenti separati da una virgola. Questo valore supporta shortcodes. E' possibile anche andare a capo tra gli argomenti per migliore leggibilità (vedere esempi). Va specificato che se l'argomento è un array deve sempre essere racchiuso tra parentesi graffe e inserito come json, può anche essere inserito come json semplificato. Inserendo come argomenti:

• block_content: sarà convertito al contenuto del blocco gutenberg (utilizzare nei filtri contenuto)
• custom: sarà convertito agli eventuali argomenti personalizzati

Esempi:

get_the_title

Risultato: Conversione dinamica

get_the_title,3385

Risultato: Campo del form

get_option,blogname

Risultato: Gigitopc informatica

Otteniamo l'autore del post corrente tramite shortcode utilizzandolo come terzo argomento della funzione get_the_author_meta

get_the_author_meta,last_name,[render_data data="post_field,id,post_author"]

Risultato: Gaudino

Passiamo array come argomenti:

HtmlAction,remove_tag,[render_data data="block_content"],{"query":"h2"}

//stessa cosa di
HtmlAction,remove_tag,block_content,{"query":"h2"}

//stessa cosa di
HtmlAction,
remove_tag,
[render_data data="block_content"],
{query:h2}

//stessa cosa di
HtmlAction,
remove_tag,
block_content,
{query:h2}

//stessa cosa di
HtmlAction,
remove_tag,
block_content,
custom
//in questo caso occorre specificare nella textarea args:
custom:{
  query:h2
}

//funzione con array di argomenti
funzione,
argomento_stringa,
{
  chiave1:valore1
  chiave2:valore2
}
//oppure
funzione,
argomento_stringa,
custom
//custom sarà da impostare nella textarea

Funzione in whitelist (functionwhitelisted)

Selezionando questa opzione è possibile, anche per gli utenti normali, inserire il nome di una funzione che deve essere preventivamente essere state inserita in whitelist dall'amministratore. Esempio: wpautop . Notare che se la funzione inserita non è in whitelist ritornerà un messaggio di errore al post del valore.

Costante php (constantphp)

AdminOnlySettings

Selezionando questa opzione è possibile inserire nel campo valore il nome di una costante php. Tenere presente che sia wordpress che questo framework generano molte costanti php. Esempi:

gpci\homeUrl

Risultato: https://www.gigitopcinformatica.it

WP_MAX_MEMORY_LIMIT

Risultato: 1024M

Stringa php

AdminOnlySettings

Selezionando questa opzione è possibile inserire nel campo valore stringhe php (comprese di virgolette singole) concatenate da funzioni e altre variabili php. Il risultato verrà processato utilizzando eval quindi fare attenzione a questa selezione. Esempio:

'Il titolo di questo documento è: '.get_the_title( get_the_ID() )

Risultato: Il titolo di questo documento è: Conversione dinamica

read

File

Selezionando questa opzione il valore sarà convertito a un'informazione relativa a un file (tutte se non specificata l'informazione singola). Il secondo parametro è il file da cui ottenere l'informazione che può essere in uno dei seguenti formati:

• formato percorso (esempio: /public_html/immagine.jpg)
• url locale (esempio: /https://sito.it/immagine.jpg)
• stringa context - sarà ottenuto il percorso del file dal contesto corrente appoggiandosi alla globale php $GLOBALS['gpci']['temps']['gpci_core']['current_file'](solo quando previsto oppure se fatto manualmente). Serve a operare all'interno di hooks come nel modulo media.

Se non utilizzato il secondo parametro il file può essere passato tramite argomento aggiuntivo file. Le informazioni sul file saranno ottenute tramite la funzione php FileAction (get_info). Esempi:

//ottiene l'estensione di un file
extension,percorso_file
//oppure
extension
//in questo caso usare argomento aggiungivo - file:percorso_file

//ottiene il basename di un file
basename,https://www.gigitopcinformatica.it/wp-content/uploads/hard-disk-interno.jpg.webp

//ottiene tutte le informazioni sul file
*,percorso_file
//è possibile ottenere l'informazione singola tramite argomento aggiuntivo nesting:basename

//ottiene il mime del file da un contesto prestabilito
mime,context

Valore javascript

AdminOnlySettings

Selezionando questa opzione sarà ritornato il codice javascript necessario a ottenere un valore da un oggetto o una funzione presente nel window e inserirlo nel contesto corrente. Il valore chiaramente non sarà utilizzabile da php in quanto calcolato nel browser dell'utente e inserito al posto dello script corrente tramite la funzione javascript ElementAction. E' corretto dire quindi che non si ottiene propriamente un valore ma una sostituzione nel DOM. Il tag script per ora sarà sempre aggiunto automaticamente. In futuro, se utile, sarà aggiunta la possibilità di simulare una pagina html con DOM tramite headless browser. E' importante notare che per ora i valori funzionanti saranno solo di tipo stringa e numero, pena una avvertimento in console e contenuto vuoto. Inserendo come argomenti:

• custom: sarà convertito agli eventuali argomenti personalizzati

Esempi:

valore da oggetto:

navigator.language

valore da funzione javascript senza argomenti:

//creare funzione javascript
function ritornaNumero(){ return 15; }

ritornaNumero

valore da funzione javascript con argomento:

//creare funzione javascript
function ritornaNumero( argomento ){ return argomento; }

ritornaNumero,valore_argomento

valore da funzione javascript con argomento e custom:

//creare funzione javascript
function ritornaNumero( argomento, custom ){
  //istruzioni
  return custom.id;
}

ritornaNumero,valore_argomento,custom

valore da funzione javascript con argomento, custom e custom_javascript:

//creare funzione javascript
function ritornaNumero( argomento, custom, custom_javascript ){
  //istruzioni
  return custom_javascript.lingua;
}

ritornaNumero,valore_argomento,custom,custom_javascript 

Tempo

Selezionando questa opzione sarà ritornato il tempo corrente (oppure quello specificato). Può essere manipolato specificando (separare con virgola):

1. tempo di riferimento come da funzione php strtotime - se non specificato sarà impostato a now
2. eventuale fuso orario come stringa timezone - se non specificato sarà impostato a default (ossia il fuso orario del sito)
3. eventuale formato, è possibile utilizzare virgole. (Il formato è processato dalla funzione php DateTimeAction) - se non specificato sarà impostato a quello del sito

Esempi:

now,default,timestamp
now,default,mysql
-2days,America/New_York,Y-m-d H:i:s

Azione ajax

AdminOnlySettings

Selezionando questa opzione sarà generato il codice javascript necessario a contattare il server tramite ajax, è anche possibile contattare altri gpci framework che hanno impostato l'azione ajax specificata. Nel contenuto è sufficiente inserire il nome dell'azione da eseguire, ma è possibile proseguire:

• id_azione
• eventuale sito bersaglio se l'azione è configurata su un altro sito (inserire l'url della root del sito bersaglio)
• eventuali dati inerenti la cifratura se l'azione è configurata su un altro sito, il formato è chiave:valore e l'ordine non importa. E' possibile andare a capo per migliore leggibilità

Eventuali argomenti aggiuntivi (esempio per passare argomenti) vanno inseriti nella textarea apposita. Per ora non sarà aggiunto il tag script che, se serve in contesti diversi da un attributo, dovrà essere aggiunto manualmente. Gli argomenti aggiuntivi custom e custom_javascript non vanno richiamati manualmente in quanto sono automaticamente inseriti nei dati cifrati dalla conversione. Esempi:

azione senza argomenti aggiuntivi:

id_azione

azione verso framework non corrente

id_azione,https://www.sito.it,id:id_cifratura_remota

--oppure

id_azione,
https://www.sito.it,
cipher:aes-128-cbc,
secret_key:chiave_16_caratteri,
iv:altra_chiave_16_caratteri

azione con argomenti aggiuntivi:

id_azione

argomenti (textarea args):

custom:{
  postid:[render_data data="id"]
  argomento2:valore2
  campo_personalizzato:mb,campo_personalizzato
}
custom_javascript:{
  lingua:navigator.language
  argomento2:valore2
  campo_personalizzato:mb,campo_personalizzato
}
fields:contenitore1,contenitore2

Opzioni personalizzate

E' possibile infine impostare opzioni personalizzate tramite php che verranno valutate soltanto dopo le altre. Per farlo utilizzare la global php $GLOBALS['gpci']['dynamic_conversion']['options']['custom'] nei seguenti formati di esempio:

//Esempio 1
$GLOBALS['gpci']['dynamic_conversion']['options']['custom']['example'] = [
  'label'     => 'Esempio!',
  'function'  => function(){ return 'test'; }		
];

//Esempio 2
$GLOBALS['gpci']['dynamic_conversion']['options']['custom']['post_author_nickname_current'] = [
  'label'     => 'Nickname autore post corrente',
  'function'  => function( $content ){
    return $content = str_replace( $search='a', $replace='Z', $content );
  }		
];

//Esempio 3
$GLOBALS['gpci']['dynamic_conversion']['options']['custom']['current_user_can'] = [
	'label'		=> 'Capacità utente corrente',
	'helper'	=> "Inserire una capacità come edit_posts o edit_user, verrà controllato se l'utente corrente la possiede",
	'function'	=> function( $content ){
          return $content = current_user_can( $content );
        }
];

La chiave dell'array equivale al valore dell'opzione, la chiave label imposta la label dell'opzione nel backend e la chiave function definisce invece la funzione che sarà eseguita con php nel frontend. Come è possibile vedere nel codice il parametro $content è opzionale. Alcune semplici regole sulle chiavi dell'array:

• non impostare gli stessi valori predefiniti del framework (vedere sotto) altrimenti quelli personalizzati non funzioneranno
• non utilizzare virgole e caratteri speciali
• non ritornare null in quanto in certi casi il framework controllerà, tramite la funzione is_null, se il valore è nullo per saltare tutto il blocco di codice collegato (come nelle queries).

Riepilogo valori

La lista dei valori predefiniti (spiegati sopra) attualmente è:

• wp
• mb
• mb_value
• GET
• function
• functionwhitelisted
• constantphp
• stringphp
• js_value
• ajaxaction
• file
• time

A questa lista si aggiungono eventuali opzioni personalizzate.