Paginación ¶

Cuando hay muchos datos a mostrar en una sola página, una estrategia común es mostrarlos en varias páginas y en cada una de ellas mostrar sólo una pequeña porción de datos. Esta estrategia es conocida como paginación.

Yii utiliza el objeto yii\data\Pagination para representar la información acerca del esquema de paginación. En particular,

• cuenta total especifica el número total de ítems de datos. Ten en cuenta que este es normalmente un número mucho mayor que el número de ítems necesarios a mostrar en una simple página.
• tamaño de página especifica cuántos ítems de datos contiene cada página. El valor por defecto es 20.
• página actual da el número de la página actual (comenzando desde 0). El valor por defecto es 0, lo que sería la primera página.

Con un objeto yii\data\Pagination totalmente especificado, puedes obtener y mostrar datos en partes. Por ejemplo, si estás recuperando datos de una base de datos, puedes especificar las cláusulas OFFSET y LIMIT de la consulta a la BD correspondientes a los valores provistos por la paginación. A continuación hay un ejemplo,

use yii\data\Pagination;

// construye una consulta a la BD para obtener todos los artículos con status = 1
$query = Article::find()->where(['status' => 1]);

// obtiene el número total de artículos (pero no recupera los datos de los artículos todavía)
$count = $query->count();

// crea un objeto paginación con dicho total
$pagination = new Pagination(['totalCount' => $count]);

// limita la consulta utilizando la paginación y recupera los artículos
$articles = $query->offset($pagination->offset)
    ->limit($pagination->limit)
    ->all();

¿Qué página de artículos devolverá el ejemplo de arriba? Depende de si se le es pasado un parámetro llamado page. Por defecto, la paginación intentará definir la página actual con el valor del parámetro page. Si el parámetro no es provisto, entonces tomará por defecto el valor 0.

Para facilitar la construcción de elementos UI que soporten paginación, Yii provee el widget yii\widgets\LinkPager, que muestra una lista de botones de navegación que el usuario puede presionar para indicar qué página de datos debería mostrarse. El widget toma un objeto de paginación y tal manera conoce cuál es la página actual y cuántos botones debe mostrar. Por ejemplo,

use yii\widgets\LinkPager;

echo LinkPager::widget([
    'pagination' => $pagination,
]);

Si quieres construir los elementos de UI manualmente, puedes utilizar yii\data\Pagination::createUrl() para generar URLs que dirigirán a las distintas páginas. El método requiere un parámetro de página y generará una URL apropiadamente formada contieniendo el parámetro de página. Por ejemplo,

// especifica la ruta que la URL generada debería utilizar
// Si no lo especificas, se utilizará la ruta de la petición actual
$pagination->route = 'article/index';

// muestra: /index.php?r=article%2Findex&page=100
echo $pagination->createUrl(100);

// muestra: /index.php?r=article%2Findex&page=101
echo $pagination->createUrl(101);

Consejo: puedes personalizar el parámetro page de la consulta configurando la propiedad pageParam al crear el objeto de la paginación.