Repository 32bit  Forum
Repository 64bit  Wiki

PHP HOWTO - Forms Framework: ffTemplate

Da Slacky.eu.
Versione delle 03:12, 20 gen 2008, autore: Nuitari (Discussione | contributi)

(diff) ← Versione meno recente | Versione attuale (diff) | Versione più recente → (diff)

Indice

Introduzione

Questo articolo fa parte di una serie di HOW-TO sui componenti di Forms, un framework Open Source sviluppato da Samuele "Nuitari" Diella, un programmatore con esperienza decennale nel ramo dello sviluppo web.

Nella fattispecie, cFormsTemplate è la classe preposta alla gestione dei template, largamente utilizzata in tutto il framework ma utilizzabile separatamente in qualsiasi progetto.

Si tratta di una classe che l'autore ha trovato parecchi anni fa ( almeno 8 ) su web e che nel tempo ha modificato/riadattato/espanso/migliorato. Se qualcuno dovesse riconoscerla, può segnalarlo all'autore in modo che i dovuti credits siano inclusi nel codice.

Come Ottenerla

E' possibile scaricare la classe da questo indirizzo: http://www.formsframework.org/cFormsTemplate.php.gz. Per utilizzarla è sufficiente scompattare il file e posizionarlo in un qualsiasi punto del sito, a patto che sia raggiungibile con una direttiva di php "require" od "include"

Sinossi

La classe non fa altro che caricare un template html da una locazione, quindi lo elabora e costruisce al suo interno una serie di buffer con le parti che lo compongono. Attraverso alcune funzioni è possibile alterarne il contenuto in parte o completamente, per poi effettuare il "parsing" (ossia l'elaborazione). Il risultato del parsing (totale o parziale) può essere immediatamente stampato su stdout oppure restituito come variabile.

I template sono in tutto e per tutto dei file html con l'aggiunta di alcuni costrutti speciali, le "variabili" e le "sezioni".

Le variabili sono elementi di testo racchiusi fra parentesi graffe, ad esempio {data_corrente}. Le sezioni sono blocchi html racchiusi da commenti html che cominciano con e finiscono con

La differenza fra i due è che le variabili possono solo essere sostituite con un contenuto, le sezioni invece possono essere ripetute N volte (un esempio comune è il record di una tabella). Le sezioni a loro volta possono essere usate allo stesso modo delle variabili.

Il primo approccio

Per comprenderne bene il funzionamento, è sufficiente fare un esempio molto banale. Supponiamo ad esempio di voler fetchare gli elementi di un array (magari il risultato di una query) e di voler visualizzare l'output in una tabella.

Innanzitutto realizziamo un semplice template, in un file che chiameremo "grid.html":

<p>Tot Record: {totrec}</p>
<table>
  <tr>
    <td>Campo 1</td>
    <td>Campo 2</td>
  </tr>

  <!--BeginRecord-->
  <tr>
    <td>{field1}</td>
    <td>{field2}</td>
  </tr>
  <!--EndRecord-->

  <!--BeginNoRecords-->
  <tr>
    <td colspan="2">No Records.</td>
  </tr>
  <!--EndNoRecords-->

</table>
<p>Tot Record: {totrec}</p>

Quindi procediamo alla creazione del codice necessario a gestirlo. Innanzitutto includiamo la classe ed istanziamo l'oggetto template. Come parametro l'oggetto richiede la dir che userà come partenza per la ricerca dei template.

require("cFormsTemplate.php");
$tpl = new cFormsTemplate(dirname(__FILE__));

A questo punto, carichiamo il file. Come parametro è necessario passare, oltre al nome del file, il nome di una sezione *fittizia* che l'oggetto usa per includere il template nella sua interezza

$tpl->load_file("grid.html", "main");

Ora non ci resta che creare/valorizzare il nostro array ed eseguire un ciclo sugli elementi.

$records = array(
                            array("1", "pippo")
                          , array("2", "pluto")
                        );

if (count($records))
{
  foreach($records as $key => $value)
  {

Per ogni elemento di record, andremo a mettere il primo valore nella variabile {field1}, il secondo nella variabile {field2} del template. A tal scopo useremo il metodo "set_var", il quale accetta come parametri il nome della variabile ed il contenuto da assegnare.

    $tpl->set_var("field1", htmlentities($value[0]));
    $tpl->set_var("field2", htmlentities($value[1]));

Quindi, una volta valorizzate le variabili, diremo al template di processare la sezione *come appare in quel preciso momento* e di accodarla al buffer. A tal scopo useremo il metodo "parse", il quale accetta come parametri il nome della sezione ed uno switch di gestione del buffer.

    $tpl->parse("Record", true);
  }

se invece di true avremmo usato false, il risultato non sarebbe stato accodato al buffer ma l'avrebbe sostituito. A questo punto eliminamo la sezione "NoRecords", da visualizzare solo se non sono presenti elementi. Per far questo utilizzeremo il metodo set_var, in quanto come detto precedentemente è possibile utilizzare le sezioni come se fossero variabili.

  $tpl->set_var("NoRecords", "");

Nel caso in cui non ci fossero stati record, invece, procediamo al contrario, eliminando la sezione "Record" e visualizzando la sezione "NoRecords"

}
else
{
  $tpl->set_var("Record", "");
  $tpl->parse("NoRecords", false);
}

Infine, impostiamo il valore di {totrec} con il numero totale di record disponibili, anche se 0.

$tpl->set_var("totrec", count($records));

e procediamo a visualizzare il template, usando il metodo pparse (print parse) dando come nome di sezione la sezione fittizia "main" utilizzata all'inizio per indicare il template nella sua interezza. Anche pparse accetta lo switch di gestione del buffer, esattamente come parse.

$tpl->pparse("main", false);

Se avessimo voluto il risultato dell'elaborazione del template in una variabile, invece che in output, avremmo potuto usare il metodo "rpparse"

$out = $tpl->rpparse("main", false);

Vediamo il nostro file php, che chiameremo grid.php, nella sua interezza:

<?php
require("cFormsTemplate.php");
$tpl = new cFormsTemplate(dirname(__FILE__));
$tpl->load_file("grid.html", "main");
$records = array(
                            array("1", "pippo")
                          , array("2", "pluto")
                        );

if (count($records))
{
  foreach($records as $key => $value)
  {
    $tpl->set_var("field1", htmlentities($value[0]));
    $tpl->set_var("field2", htmlentities($value[1]));
    $tpl->parse("Record", true);
  }
  $tpl->set_var("NoRecords", "");
}
else
{
  $tpl->set_var("Record", "");
  $tpl->parse("NoRecords", false);
}
$tpl->set_var("totrec", count($records));
$tpl->pparse("main", false);
?>

Questo è quanto. Si tratta delle basi per poter utilizzare un template engine semplice come questo, ma la potenza e la comodità di un simile strumento dovrebbero apparire evidenti. Come si dovrebbe notare, l'html risulta comunque pulito e leggibile (la struttura non è alterata minimamente e non è presente codice html non standard) e lo stesso vale per il php (la logica di scrittura del codice rispetta la logica funzionale e non quella di visualizzazione).

Conclusioni

Ovviamente la classe contiene altre funzioni ed è possibile fare esempi più complicati d'utilizzo dei template (ad esempio l'utlizzo di sezioni nidificate). In base al gradimento, in seguito è possibile che l'articolo verrà approfondito ulteriormente.

Credits

Tutto il codice presente nell'articolo e nei file collegati è coperto dal licenza GPL v3.

L'autore dell'articolo, di Forms, il framework php e di tutti i file correlati al progetto è Samuele "Nuitari" Diella, mailto: samuele.diella@gmail.com

Ringraziamenti

Conraid, per la simpatia ed il costante supporto/bug-tracking

La comunità di Slacky.eu, la migliore del mondo

Strumenti personali
Namespace

Varianti