Clase Paginado - class.paginado.php

Descripción

Esta clase, permite al usuario realizar consultas a una base de datos, y devolver los resultados en forma de "páginas", junto a los métodos necesarios para realizar una navegación entre éstas. La implementación de la misma es muy sencilla y los métodos prácticamente intuitivos.

La idea detrás de esta clase, es proveer a los usuarios, un medio sencillo de utilizar, para realizar paginación de resultados, utilizando medio eficientes y produciendo, de esta manera, una programación más clara y entendible.

Se ha elegido hacer el desarrollo como una clase, y su funcionalidad como métodos de la misma, para utilizar los beneficios de la programación orientada a objetos, como pueden ser la extensibilidad y la modularización.

Modo de Uso

Los pasos para utilizar la clase son los siguientes:

Código fuente

Clase Paginado

Ejemplo de Uso

<?
// Conectamos a la Base de Datos
$Conn mysql_connect("localhost""usuario""password");
mysql_select_db("base_de_datos");

// Obtenemos la página actual, por el método que más nos guste
// Por defecto, la página se propaga por la variable $pagina
$pagina $HTTP_GET_VARS["pagina"];

// Incluimos la Clase Paginado
include("class.paginado.php");
$rs = new paginado($Conn); // instanciamos un objeto
$rs->pagina($pagina); // Le indicamos en que página estamos - 1 por defecto
$rs->porPagina(10); // Le decimos cuantos registros por página queremos - 20 por defecto $rs->propagar("forum"); // Le decimos las variables que queremos propagar en los links
if(!$rs->query("SELECT * FROM clientes")) // Y ejecutamos nuestra consulta.
{
    die( 
$rs->error() ); // Si Query devolvió falso, hubo un error y lo mostramos.
}
echo 
"Mostrando ".$rs->desde()." - ".$rs->hasta()." de un total de ".$rs->total()."<br>";
// Recorremos todos los resultados y los mostramos. while($row $rs->obtenerArray())
{
    echo 
$row["apellido"].", ".$row["nombre"]."<br>";
    echo 
"Email : ".$row["email"];
    echo 
"<hr>";
// while // Finalmente mostramos los medios para la navegación entre los resultados.
echo $rs->anterior()." - ".$rs->nroPaginas()." - ".$rs->siguiente();
?>

Métodos básicos de la Clase

Constructor del Objeto( $ResourceLink )

El método Constructor del objeto, es el método que se llama automáticamente cuando se ejecuta una instanciación de la clase. Este método, que se llama igual que la clase, debe recibir como parámetro un link de recurso, hacia una conexión establecida con la Base de Datos, ya habiendo sido seleccionada una base de datos. Ej:

<?
$Conn 
mysql_connect("localhost""usuario""password");
mysql_select_db("base_de_datos");
$obj = new paginado($Conn);
?>

pagina ( $NroPagina )

El método pagina() le indica al objeto a cuál página de los resultados queremos acceder. En caso de querer acceder a un número de página inexistente en los resultados, el objeto aborta su ejecución, y setea un mensaje interno de error informando el motivo del error.

De no indicarse a que página se quiere acceder, el objeto toma por defecto, el valor 1. Este método también puede ser invocado sin parámetros, en ese caso, retorna el valor de la página actual.

porPágina ( $NroDeResultados )

Este método nos permite indicarle al objeto, cuántos resultados debe obtener por cada una de las páginas. De no indicarse, el objeto posee un valor por defecto de 20 resultados por página.

Al igual que el método anterior, puede ser llamado sin parámetros, devolviendo de esa manera el valor seteado en el objeto actualmente.

query ( $SentenciaSql )

A este método, se le debe pasar una sentencia SQL válida, debiéndo esta ser un SELECT que no utilice la directiva LIMIT (caso contrario se producirá un error de sintaxis luego y el objeto cancelará su ejecución, devolviendo FALSE).

El método primero hará una llamada a la base, para averiguar la cantidad total de resultados que genera la consulta. Con éste número, define si la página solicitada está dentro del número posible de páginas y finalmente, realiza la consulta, retornando una cantidad de resultados igual a la definida con el método porPagina().

Los resultados de la consulta quedan guardados dentro del objeto y quedan listos para ser utilizados.

obtenerArray ( )

Método análogo al nativo de PHP mysql_fetch_array(). Este método permite recuperar un registro de los resultados, en forma de array asociativo. En caso de no haber más resultados, entonces retorna FALSE, por lo cual es posible recorrer los resultados secuencialmente hasta su finalización. Ej:

while ($fila $obj->obtenerArray())
{
    echo $fila["apellido"].", ".fila["nombre"]."<br>";
    echo "Email: ".$fila["email"];
}

Este método no recibe ningún parámetro, ya que trabaja con el link de resultados interno del objeto.

siguiente ( [$CódigoHTML] )

Si la consulta devolviera más de una página de resultados, al invocar este método, retorna el código HTML de un link hacia la siguiente página, siempre y cuando no estemos mostrando la última de las páginas, en este caso, no retorna nada.

Por defecto, el método retorna solo un texto ("Siguiente >"), convertido en link hacia la siguiente página, pero esto puede modificarse si, en cambio, invocamos al método pasándole como parámetro, el código HTML de la frase o lo que sea que queramos aparezca como link. Los siguientes son dos ejemplos, uno cambiando el texto y el otro reemplazándolo por una imagen:

// Esto cambiará el texto por defecto.
$obj->siguiente("Más resultados ->"); // Ahora, con esto, reemplazamos el texto anterio // por una imagen, que será utilizada dentro de un
// link (Tag <A>).
$obj->siguiente("<img src=\"/icons/forward.gif\" border=\"0\">");

anterior ( [$CódigoHTML] )

Método análogo al anterior en funcionamiento, solo que en vez de retornar el código hacia la siguiente página, lo hace para la página anterior de los resultados, solo si no estamos actualmente posicionados en la primera página. También es similar el comportamiento que permite cambiar el texto por defecto ("< Anterior"), por otro o por una imagen, haciendo al ejemplo anterior completamente válido para este método también.

nroPaginas ( )

Este método devuelve una lista separada por pipes de todos los números de páginas generadas por la consulta, en código HTML. Cada uno de estos números es un link hacia la página correspondiente, excepto el número de la página actual, que es resaltado en negrita. Ej:

// Suponiento que la consulta retorna 50 resultados
// y que se muestran 10 resultados por página.
$obj->pagina(3);
$obj->porPagina(10);
...
$obj->nroPaginas();
Esto devolvería :
1 | 2 | 3 | 4 | 5

Otros Métodos de la Clase

Luego de realizada la consulta, el objeto posee ciertos atributos que pueden ser de utilidad al usuario de la clase para ofrecer más información sobre la consulta realizada y sobre los resultados de la misma.

error ( )

Devuelve una descripción textual del último error generado dentro del objeto, ante una mal función del objeto o errores en la sintaxis de la consulta que se intentó ejecutar contra la Base de Datos.

total ( )

Devuelve la cantidad total de registros que retorna la consulta ejecutada.

totalPaginas ( )

Devuelve la cantidad total de páginas que retorna la consulta ejecutada.

registros ( )

Devuelve la cantidad de registros que contiene la página actual de la consulta.

desde ( )

Devuelve el índice dentro del total de resultados, del primer elemento de la página actual.

hasta ( )

Devuelve el índice dentor del total de resultados, del último elemento de la página actual.

propagar ( )

Este método recibe como parámetros los nombres de las variables que deseamos propagar desde los links generados por nroPaginas(), siguiente() y anterior(). Estas variables deben pertenecer al entorno global del Script, ya que de otra manera no serán reconocidas.

Versión y Licencia

Esta versión de la Clase actualmente es la 0.1, del 27 de Febrero de 2002 12:43. Cualquier comentario sobre la documentación o sobre la clase, así como cualquier contribución hacia el código de la misma, puede ser enviado a pablo.rigazzi@gmail.com.

Esta clase es Open Source (Código Libre). Esto significa que cualquier la puede utilizar y modificar, sin pagar un centavo por ello. Esta clase utiliza la licencia GPL (GNU General Public License) que pueden ver en http://www.gnu.org/licenses/, para informarse que es lo que pueden o no hacer con un software que está bajo esta licencia.

Ver también