Attenzione a tutti gli sviluppatori di moduli! Nell' ultima release di Envolution, v1.1.0, ci è stato rilasciato un nuovo set di funzioni sotto forma di estensione API envRender. Queste funzioni ci permettono di creare templates per l'output dei nostri moduli. Molta gente non a conoscenza della loro esistenza, non fanno uso delle loro grandi potenzialità per la creazione del layout dei moduli. Questo  articolo, in due parti, spiegherà il nuovo set di funzioni e ci mostrerà le sue caratteristiche implemenandole, tramite un tutorial, in un processo di design di un modulo. Nella prima parte, verranno illustrate le nuove funzioni e si spiegherà cosa esse fanno senza addentrarci all'interno del codice. Questa è intanto la lista delle funzioni disponibili, di seguito c'è una più approfondita spiegazione di cosa ognuno di esse fa e come lavora.

envTplStart ();
envTplEnd ();
envTplAssign ();
envTplAppend ();
envTplUnassign ();
envTplRegFunc ();
envTplUnRegFunc ();
envTplRender ();
envTplFetch ();
envTplLoadEngine ();
envTplGetPath ();
envTplImagePath ();
envTplCheckPath ();

L' Inizio e la Fine:

envTplStart

Questa funzione dà inizio all'utilizzo del nuovo sistema di template dei moduli. Ad essa vengono passati tre argomenti, due dei quali obbligatori e uno opzionale. Il primo di questi argomenti definisce il nome del modulo; esse deve essere uguale al nome come è mostrato nel pannello d'amministrazione dei moduli ed è case sensitive. Il secondo definisce il nome file del template principale da essere utilizzato senza l'estensione (.tpl) alla fine. Infine il terzo argomento controlla la visibilità a destra e a sinistra dei blocchi

 1. ->questa impostazione disabilita i blocchi di destra
 2. ->questa impostazione abilita i blocchi di destra
 3. -> questa impostazione disabilita i blocchi di sinistra e di destra cos' come l' header ed il footer (i.e.: Frontpage Module)

Questo è un esempio di come una funzione envTplStart potrebbe apparire:

envTplStart (‘TestMod’, ‘testmodmain’, 1);

Lo scopo principale di questa funzione è di:

1.) Far partire il motore del tema.
2.) Controllare e caricare i file template (più avanti in questo capitolo).
3.) Caricare l'intestazione (header) se necessario.

La funzione envTplStart ritorna true quando ha terminato.

envTplEnd

Questa funzione è piuttosto semplice ed il suo unico scopo e quello di includere il file di piedi pagina (footer), terminando così il layoutfooter.Non le vengono passati argomenti e ritorna true quando ha terminato.

envTplEnd();

Le Variabili sono mie Amiche

envTplAssign

Questa è una delle più potenti funzioni del gruppo. Quelli che hanno familiarità con il tema Envolution avranno già visto le variabili cha appaiono come [-$VARIABLE-]. Questa funzione permette agli sviluppatori di impostare le loro proprie variabili del tema.

La funzione envTplAssign ha 2 argomenti, il primo è il nome della variabile ed il secondo è il valore della variabile. Questa funzione ritornerà true quando terminato.

envTplAssign (‘TESTVAR’, ‘Questo è il valore di TESTVAR’);

Fino ad ora, la convenzione dei nomi per le variabili dei temi è stata quella di utilizzare tutto maiuscolo. Questa convenzione dovrebbe essere seguita da tutti gli sviluppatori di moduli per motivi di conformità agli standards.

envTplAppend

Questa funzione è usata insieme alla funzione envTplAssign. Essa abilita lo sviluppatore del modulo ad aggiungere ulteriori informazioni ad una variabile già impostata. Essa accetta lo stesso tipo di argomenti di envTplAssign e ritorna true quando terminato.

envTplAppend (‘TESTVAR’, ‘Aggiunta di più informazioni a TESTVAR’);

envTplUnassign

Una funzione di assegnazione non sarebbe completa senza una funzione di (dis)assegnazione per cancellare il suo lavoro e questo è ciò che esattamente fa envTplUnassign. Essa cancella il valore della variabile specificata. Il solo argomento passato a questa funzione è il nome della variabile cancellata e quindi ritorna vero quando terminato.

envTplUnassign (‘TESTVAR’);

Congiunzione Giunzione fa un tema Funzione

envTplRegFunc

Questa ti permette di chiamare una specifica funzione all'interno di un template. Gli argomenti per questa funzione sono il nome del  place holder (es. [-$MIAFUNZ-])ed il nome della funzione. Una volta che una funzione è assegnata ed un place holder, potrai usarlo dentro un tema allo stesso modo di una varabile. Ritorna true quando terminato.

envTplRegFunc(‘TESTFUNC’, ‘testfunc’);

envTplUnRegFunc

Puoi indovinare, questa particolare funzione ha il solo scopo di cancellare il placeholder impostato da envTplRegFunc. L'argomento per questa è il nome del placeholder da cancellare. Ritorna true quando terminato.

envTplUnRegFunc (‘TESTFUNC’);

Dove Oh Dove Sono I Miei Templates?

envTplRender

Una volta che tutte le variabili e tutti i placeholder delle funzioni sono stati impostati è tempo di mstrare le tue informazioni; questo è fatto attraverso la funzione envTplRender. Il suo lavoro è quello di prendere che gli è stato assegnato ed i suoi argomenti ed elaborarlo per l'output. L'argomento passato saranno il nome del template desiderato senza l'estensione (.tpl).

Ritorna true quando terminato.

envTplRender (‘testmodmain’);

envTplFetch

L'abilità di usare più di un template o di includere  files template all'interno di altri diventa possibile con questa funzione. Essa ti permette tirar dentro un particolare file template, però non elabora subito il file. Esso ti permette di assegnare variabili e funzioni per questo specifico template prima di elaborarlo per l'output. Questo avrà più senso dopo nel tutorial. L'argomento per questa funzione è il nome del template che vuoi  includere senza l'estensione (.tpl). Ritorna true quando terminato.

envTplFetch(‘testmodsubtpl’);

Shhh… Uno Sguardo dietro le Scene

Le quattro ultime funzioni non sono direttamente accessibili dallo sviluppatore del modulo ma da altre funzioni mostrate sopra. Sono qui presentate per il solo scopo di una completa spiegazione delle API di rendering.

envTplLoadEngine

Questa funzone controlla se il sistema smarty template  è già inizializzato, se no, include le classi di smarty e ritorna true. Se c'è già una istanza di smarty attiva questa funzione ritorna false.

envTplGetPath

Questa funzione controlla se c'è definito un file template personalizzato e ritorna il suo path se esiste.

envTplImagePath

Questa funzione controlla se c'è una directory di immagini personalizzata e ritorna il suo path se esiste.

envTplCheckPath

Controlla se c'è un template personalizzato per il modulo specificato e ritorna il suo path se esiste.

Bene, questo è tutto per questa parte.Nella prossima lezione presenterò veri esempi di codice di come implementare queste funzioni nel tuo design e ti mostrerò come approcciare differenti problemi con differenti soluzioni.

Buona programmazione!

ApathyBoy