I segnaposti dinamici

Utilizzo

I segnaposto dinamici reagiscono male ai filtri. È inutile (almeno fino alla 1.9.2) provare ad applicare un filtro ad un segnaposto dinamico, o utilizzare un segnaposto dinamico come argomento di un filtro.

Approccio

Contesto dell’articolo
Quest’articolo è concepito nella prospettiva di scrivere un plugin per SPIP versione superiore a 1.9.2b.
Quest’articolo non vuole essere esaustivo.
Riassume quanto ho potuto apprendere in occasione della realizzazione di un plugin.

Nella fattispecie mi sono ispirato al segnaposto formulaire_ecrire_auteur

Un segnaposto dinamico

Un segnaposto dinamico è differente da un segnaposto statico.
Il suo impiego è necessario quando bisogna trattare dati, ad esempio quelli inviati da un form.

Se non è necessario eseguire trattamento dati è preferibile definire segnaposti statici.
Se non specificato altrimenti, i path dei file sono relativi alla radice del plugin, cioè, relativamente alla radice del sito SPIP (cartella che contiene il file spip.php), la cartella plugins/nom_plugin.

Un segnaposto dinamico ha un suo nome, spesso lungo. Consideriamo qui un segnaposto chiamato JOHN_DOE. Questo segnaposto deve potere essere chiamato in un modello con la sintassi #JOHN_DOE. La scelta del nome è un aspetto importante che determina anche il nome di almeno due file, che realizzano l’aggiunta del segnaposto propriamente detto. Questi file sono :
-  « balise/john_doe.php »
-  « formulaires/john_doe.html »

Il file « formulaires/john_doe.html »

Ha la stessa sintassi di un modello (squelette).

Il file « balise/john_doe.php »

Comincia con la riga :
if (!defined("_ECRIRE_INC_VERSION")) return; #securite

Quindi vengono definite 3 funzioni la cui forma minimale è la seguente :

function balise_JOHN_DOE($p) {
    return calculer_balise_dynamique($p, 'JOHN_DOE', array());
}
function balise_JOHN_DOE_stat($args, $filtres) {
    return $args;
}
function balise_JOHN_DOE_dyn() {
    return array(
        'formulaires/john_doe', 
        0, 
        array(
        )
    );
}

La prima funzione « balise_JOHN_DOE($p) »

Il ruolo del parametro $p rimane per me ancora da chiarire in modo completo.

$p è il contesto di compilazione della pagina spip di cui ha bisogno tra l’altro la funzione calculer_balise_dynamique per compilare correttamente i valori chiesti dalla tabella della prima funzione, come pure gli eventuali argomenti del segnaposto stesso
(#BALISE_DYN{arg1, arg2...}) che saranno in tal caso aggiunti alla fine della suddetta tabella.

Invece il terzo parametro della funzione calculer_balise_dynamique permette « di recuperare dati del contesto nel quale è chiamato il segnaposto ».

Ad esempio se il vostro segnaposto è destinato a comparire in un circuito ARTICLE e avete bisogno del valore di id_article, allora questo terzo parametro deve essere array('id_article').

Questo array comporta tutti i valori di cui vi occorre recuperare di dati. L’ordine di questi valori è importante per poter ritrovare i dati nelle funzioni seguenti.

La seconda funzione « balise_JOHN_DOE_stat($args, $filtres) » [1]
-  $args è una tabella che contiene i dati recuperati dalla funzione precedente nell’ordine nel quale questi dati sono stati nominati dal terzo parametro della suddetta funzione balise_JOHN_DOE($p).

Qui è possibile effettuare trattamenti su questi dati, ad esempio convalida, lettura del database... l’elenco non è esaustivo.

Se i trattamenti sono soddisfacenti, allora la funzione restituisce $args e l’avventura continua.

Nel caso contrario la funzione può ritornare nul ("return '';)" e l’avventura si ferma. Cioè, il segnaposto #JOHN_DOE non pubblicherà nulla.

In alternativa, in mancanza della tabella dati, la funzione può anche restituire un gruppo di caratteri. Questo causerà la visualizzazione del gruppo di caratteri e l’interruzione del trattamento del segnaposto.

Si noti che la funzione balise_JOHN_DOE_stat($args, $filtres) può aggiungere alla tabella $args altri valori, a patto che siano opportunamente dichiarati come parametri dalla terza funzione balise_JOHN_DOE_dyn().

$filtres è la tabella degli eventuali pseudo-filtri del segnaposto.

La terza funzione « balise_JOHN_DOE_dyn(...) »

Nell’esempio fatto sopra si avrebbe una dichiarazione del tipo function balise_JOHN_DOE_dyn ($id_article) { ... } per utilizzare l’id_article del contesto.

I parametri di questa funzione sembrano dunque corrispondere a un elenco ordinato dei dati recuperati dalla prima funzione balise_JOHN_DOE, che può però essere alterato in tutti i modi possibili dalla seconda funzione balise_JOHN_DOE_stat.

Questa terza funzione consiste di due parti principali :

-  trattamenti di tipo dati da form HTML (« _ request() » sono il vostro amico), produzione di valori destinati a essere pubblicati come risultato di questi trattamenti " - il ritorno della funzione.

L’output della funzione

I dati restituiti dalla funzione sono costituiti da un array di 3 elementi.
-  il riferimento a un modello, nel formato usato da « include_spip () », cioè un nome di file presente in « SPIP_PATH » senza l’estensione del file ;
-  un valore di durata di vita della CACHE per il risultato del segnaposto. Questo valore di solito dovrebbe essere nullo. Infatti il codice HTML prodotto dipende in generale dai valori che appaiono in $_POST : è raro che si possano condividere due chiamate in $_POST, ed è sempre meglio dunque non utilizzare la cache.
-  una tabella associativa, le cui chiavi permettono l’accesso ai relativi valori all’interno del modello (squelette) richiamato, in cui sono richiamati con il segnaposto #ENV{chiave}.

Conclusione

Ora ne sapete ora quanto me.