martedì 20 novembre 2007

PHP: Paginazione dei Risultati di una Query

Capita spesso quando si sviluppano applicazioni per il web di dover visualizzare in una tabella grandi quantità di dati provenienti da una query SQL.

In questi casi costringere gli utenti a scorrere una enorme pagina di dati non sarebbe certo una buona idea. Molto meglio adottare una visualizzazione in pagine multiple con link di navigazione che consentano di passare da una pagina all'altra.

Visto che la paginazione dei risultati di una query è un compito che le nostre applicazioni devono svolgere spesso, si tratta del candidato ideale per una classe php. Scrivendo una classe che svolga questa funzione non saremo costretti a riscrivere lo stesso codice tutte le volte.

PDatagrid è una classe che estrae dati da un database MySQL in base ad una determinata query ed impagina i risultati in un formato tabellare (per impostazione predefinita, ma altri tipi di formato sono possibili) con link di navigazione alle singole pagine di dati.

Il pacchetto contiene i seguenti file

  • pdatagrid.class.php - definizione della classe.
  • docs/ - cartella con la documentazione generata con PHP Documentor (in inglese).
  • example1.php, example2.php - semplici file dimostrativi dell'utilizzo della classe.
  • style.css - esempio di foglio di stile per controllare l'aspetto della tabella.
  • dbconfig.php - costanti per la connessione al database usate dal codice di esempio.
  • composers.sql - script sql per ricreare la tabella MySQL utilizzata negli esempi.

Come utilizzare la classe

L'uso della classe è semplice, ecco comunque tutti i passi da seguire per integrarla nelle vostre applicazioni. Il codice che segue è tratto dal file di esempio (example1.php)

1)
require 'pdatagrid.class.php';

Ovviamente il primo passo è includere il file di definizione della classe.

2)
require 'dbconfig.php';
$conn = mysql_connect(DB_HOST, DB_USER, DB_PASSWORD) 
  or die('Connection to database failed: ' . mysql_error());
mysql_select_db(DB_NAME) or die ('select_db failed!');

Si effettua la connessione al database. Il file dbconfig.php è presente nel pacchetto e deve essere modificato con il nome database, nome utente e password necessari per accedere al vostro database.

3)
$grid = new PDatagrid($conn);

Si crea un'istanza della classe PDatagrid e si inizializza con la connessione al database appena creata.

4)
$grid->setSqlCount("Select count(*) from composers");
$grid->setSqlSelect("Select name, 
  date_format(date_birth,'%b %D %Y') db, 
  date_format(date_death,'%b %D %Y') dd from composers");

Si devono impostare due diverse query SQL. La prima per contare il numero di record che si vogliono visualizzare, la seconda per estrarli con SELECT. Da notare che nell'esempio non c'è nessuna condizione WHERE perché vogliamo visualizzare tutti i record della tabella. Se avessimo bisogno di impostare una condizione WHERE la stessa condizione dovrebbe essere presente in entrambe le query o la paginazione non potrebbe funzionare.

5)
$grid->baselink = 'example1.php';
$grid->setMaxNavLinks(4);
$grid->setRowsPerPage(5);
if(isset($_GET['page']))
  $grid->setPage($_GET['page']);

Si impostano nell'ordine:

  • la url base per i link di navigazione
  • il numero massimo dei link di navigazione. Questi sono i link che puntano alle singole pagine. Se le pagine di dati da visualizzare sono molte avere un link ad ogni pagina occuperebbe troppo spazio, in questo caso si imposta il numero massimo di questi link con setMaxNavLinks().
  • il numero di record da visualizzare su una pagina
  • il numero della pagina corrente. Se $_GET['page'] non è impostato allora siamo sulla prima pagina dei risultati, altrimenti la variabile page nella url indica il numero di pagina corrente (vedere nel codice il formato dei link di navigazione)

La parte rimanente del codice è costituite da semplici istruzioni per generare l'html necessario alla visualizzazione della tabella

6)
<table cellspacing="0" cellpadding="0" width="500">
<thead>
<tr>
  <td width="50%">Name</td>
  <td width="25%">Date of Birth</td>
  <td width="25%">Date of Death</td>
</tr>
</thead>

Intestazioni dei campi

7)
<tfoot>
<tr>
  <td colspan="3">
  <span id="navlinks">
    <?php echo $grid->getLinks();?>
  </span>
  </td>
</tr>
</tfoot>

Link di navigazione nel footer

8)
<tbody>
  <?php echo $grid->getRows();?>
</tbody>
</table>

Le righe della tabella nel body

Foglio di stile

L'aspetto della tabella è controllato interamente attraverso fogli di stile. Tra le altre cose agendo sugli opportuni attributi (fare riferimento ai commenti nel file style.css usato dagli esempi) si può impostare un colore di sfondo alternato per le righe in posizione pari e dispari e modificare l'aspetto dei link di navigazione.

Altri esempi

example2.php dimostra come sia possibile visualizzare i record in un formato diverso dalla tipica griglia.

Per fare questo si utilizzano le proprietà rowfmt e fieldfmt che consentono di impostare un formato di visualizzazione di una riga di dati e del singolo campo.

$grid->rowfmt = "<ul%s>%s</ul>\n";
$grid->fieldfmt = "<li>%s</li>";

In questo modo si utilizza un insieme di liste non ordinate per la visualizzazione dei record. Le stringhe di formato usano la stessa sintassi dell'istruzione sprintf.

Il pacchetto (pdatagrid.zip) è scaricabile dal sito. Per provarlo scompattate il tutto in una directory del vostro sito o webserver locale. Per eseguire gli esempi dimostrativi dei diversi tipi di paginazione dei dati che si possono ottenere con la classe, è necessario anche creare un database, modificare dbconfig.php con i dati per l'accesso allo stesso e lanciare lo script composers.sql per creare la tabella di prova.

I commenti al codice e la documentazione completa (che non contiene però molto di più di quanto spiegato in questo articolo) sono in inglese perché ho creato la classe per un sito estero con cui collaboro e non avevo troppa voglia di tradurre il tutto. Chi incontrasse problemi insormontabili di lingua può contattarmi.

Spero la classe vi torni utile, modifiche e futuri sviluppi sono sempre possibili.

Nessun commento:

Posta un commento

Nota. Solo i membri di questo blog possono postare un commento.