Argumentos WP_Query: Estado, orden y paginación

En esta parte de la serie Dominando WP_Query, aprenderás algunos de los argumentos que puedes usar con la clase WP_Query, a saber, aquellos para:

• estado
• orden
• paginación

Puedes usar estos argumentos para capturar entradas programadas de la base de datos, para consultar adjuntos, para modificar la forma en la que se ordenan las entradas y en base a qué lo hacen, para especificar cuántas entradas se muestran y mucho más

Pero antes de poder hacer esto, debes entender cómo funcionan los argumentos en WP_Query.

Un resumen sobre cómo funcionan los argumentos en WP_Query

Antes de empezar, vamos a hacer un rápido resumen sobre cómo funcionan los argumentos en WP_Query. Cuando escribes código WP_Query en tus temas o plugins, debes incluir cuatro elementos principales:

• los argumentos para la consulta, utilizando parámetros que se tratarán en este tutorial
• la consulta en sí
• el bucle
• finalizar: las etiquetas de cierre if y while y restablecer los datos de entrada

En la práctica esto tendrá un aspecto similar a lo siguiente:

1

<?php

2

3

$args = array(

4

    // Arguments for your query.

5

);

6

7

// Custom query.

8

$query = new WP_Query( $args );

9

10

// Check that we have query results.

11

if ( $query->have_posts() ) {

12

13

    // Start looping over the query results.

14

    while ( $query->have_posts() ) {

15

16

        $query->the_post();

17

18

        // Contents of the queried post results go here.

19

20

    }

21

22

}

23

24

// Restore original post data.

25

wp_reset_postdata();

26

27

?>

Los argumentos son lo que le indica a WordPress qué datos obtener de la base de datos y es de lo que voy a tratar aquí. Así que aquí nos vamos a centrar únicamente en la primera parte del código:

1

$args = array(

2

    // Arguments for your query.

3

);

Como puedes ver, los argumentos están contenidos en una matriz. Aprenderás a codificarlos a medida que avances en este tutorial.

Escribir el código de tus argumentos

Los argumentos de la matriz se codifican de una forma concreta, que es la siguiente:

1

$args = array(

2

    'parameter1' => 'value',

3

    'parameter2' => 'value',

4

    'parameter3' => 'value'

5

);

Debes incluir los parámetros y sus valores entre comillas simples, utilizar => entre ellos y separarlos mediante una coma. Si te equivocas, es posible que WordPress no añada todos tus argumentos a la consulta o que obtengas una pantalla en blanco.

Parámetros de estado

Si alguna vez has convertido el estado de una publicación de Borrador a Publicada, o tal vez la hayas trasladado a la papelera, sabrás que WordPress asigna un estado a cada entrada. Puedes usar el parámetro post_status para consultar entradas con uno o varios estados.

Los argumentos disponibles son:

• publish: Una entrada o página publicada.
• pending: Una entrada que está pendiente de revisión.
• draft: Una entrada en estado de borrador.
• auto-draft: una entrada recién creada, sin contenido.
• future: Una entrada a publicar en el futuro.
• private: Una entrada no visible para los usuarios que no hayan iniciado sesión.
• inherit: Una revisión.
• trash: La entrada está en la papelera.
• any: Recupera cualquier estado excepto aquellos estados de entrada con 'exclude_from_search' establecido en true (es decir, trash y auto-draft).

Si no especificas un estado en los argumentos de consulta, WordPress utilizará por defecto el estado publish; si el usuario actual ha iniciado sesión, también incluirá entradas con el estado private. Si ejecutas una consulta en las páginas de administración, WordPress también incluirá de forma predeterminada los estados protegidos, que son future, draft y pending.

Supongamos que estás administrando un sitio de eventos y que estás usando un tipo de entrada personalizada para los eventos, utilizando la fecha de publicación como la fecha en la que tendrá lugar el evento. Por defecto WordPress no mostrará ningún evento que aún no haya ocurrido: aunque los hayas programado, su fecha programada está por llegar, por lo que el estado de la entrada es future.

Para evitar esto, simplemente utiliza estos argumentos:

1

$args = array(

2

    'post_type' => 'event',

3

    'post_status' => 'future'

4

);

Esto mostrará solo los eventos que aún no hayan tenido lugar, como si tuviesen el estado publish. Pero si también deseas mostrar los eventos que ya hayan tenido lugar, puedes utilizar una matriz de estados de entrada para incluir más de un estado:

1

$args = array(

2

    'post_type' => 'event',

3

    'post_status' => array(

4

        'future',

5

        'publish'

6

    )

7

);

El parámetro post_status es esencial cuando se consultan datos adjuntos. Esto se debe a que tienen un estado inherit, no publish. Por lo tanto, para consultar todos los archivos adjuntos, usarías lo siguiente:

1

$args = array(

2

    'post_type' => 'attachment',

3

    'post_status' => 'inherit'

4

);

Alternativamente, podrías reemplazar inherit con any lo que tendría el mismo efecto.

Parámetros de orden

Existen dos parámetros que se utilizan para ordenar las entradas recuperadas por WP_Query: order y orderby. Como era de esperar, order define el orden en el que se generarán las entradas en el bucle y orderby define en base a qué campo de la base de datos se ordenarán.

Comencemos mirando los argumentos para order.

El parámetro order

Para este solo existen dos argumentos que puedes usar:

• ASC: orden ascendente de valores más bajos a más altos (1, 2, 3; a, b, c).
• DESC: orden descendente de valores, de los más altos a los más bajos (3, 2, 1; c, b, a).

Son bastante auto-explicativos. Si no incluyes un argumento para order, WordPress lo establecerá de forma predeterminada en DESC.

El parámetro orderby

Puedes ordenar tus entradas en base a una serie de campos:

• none: No hay ningún orden (disponible con la versión 2.8).
• ID: Orden por id de la entrada. Presta atención a las mayúsculas.
• author: Orden por autor.
• title: Orden por título.
• name: Orden en base al slug de las publicaciones.
• type: Orden en base al tipo de entrada.
• fecha: Orden por fecha.
• modified: Orden en base a la última fecha de modificación.
• parent: Orden en base al id del padre de la entrada/página.
• rand: Orden aleatorio.
• comment_count: Orden en base al número de comentarios.
• menu_order: Orden en base al orden de página. Se usa con mayor frecuencia para las páginas (utilizando el valor que se añade al metabox en la pantalla Editar página) y para los archivos adjuntos (mediante los campos enteros en el cuadro de diálogo Insertar / Cargar galería multimedia), pero se puede usar para cualquier tipo de entrada con menu_order habilitados.
• meta_value: Ordena en base al valor de una clave meta (o campo personalizado). Esto solo funciona si también incluyes un parámetro meta_key en los argumentos. Los valores meta se ordenan alfabéticamente y no numéricamente (por lo que 34 vendría antes de 4, por ejemplo).
• meta_value_num: Ordena en base a un metavalor numérico. Al igual que con meta_value, también debes incluir un argumento meta_key en la consulta.
• post__in: Conserva el orden del ID de entrada indicado en la matriz post__in.

El valor predeterminado es date, es decir, la fecha en la que se publicó una entrada.

Por ejemplo, si deseas ordenar tus entradas en base a sus títulos en orden ascendente, tendrías que usar estos argumentos:

1

$args = array(

2

    'orderby' => 'title',

3

    'order' => 'ASC'

4

);

Ordenar en base a múltiples campos

No tienes que apegarte a un único campo para ordenar tus entradas. Para ordenar en base a varios campos, utiliza una matriz con el parámetro orderby y (opcionalmente) el parámetro order si quieres ordenar cada campo en un orden diferente.

Supongamos que tienes un campo personalizado de calificaciones que deseas usar para ordenar en un sitio de comercio electrónico. Podrías ordenar en base a la calificación y después en base a los títulos, ambos en orden ascendente, de la siguiente manera:

1

$args = array(

2

    'orderby' => array(

3

        'meta_value_num',

4

        'title'

5

    ),

6

    'order' => 'ASC',

7

    'meta_key' => 'rating'

8

);

Ten en cuenta que he incluido el argumento meta_key para que WordPress sepa qué campo personalizado estoy usando. Esto se hace debido a la forma en la que WordPress almacena los metadatos de las entradas: no en la tabla wp_posts, sino en la tabla wp_postmeta.

Pero, ¿qué pasa si deseas ordenar por calificación en orden descendente y luego en base al título en orden ascendente? Simplemente utilizas otra matriz:

1

$args = array(

2

    'orderby' => array(

3

        'meta_value_num',

4

        'title'

5

    ),

6

    'order' => array(

7

        'DESC',

8

        'ASC'

9

    ),

10

    'meta_key' => 'rating'

11

);

También podrías ordenar en base a varios campos cuando no utilices metadatos de entrada, por ejemplo, para ordenar por tipo de entrada y, a continuación, por fecha:

1

$args = array(

2

    'orderby' => array(

3

        'type',

4

        'date'

5

    ),

6

    'order' => array(

7

        'ASC',

8

        'DESC'

9

    )

10

);

Esto ordenaría por tipo de entrada en orden ascendente y, a continuación, dentro de cada tipo de entrada, por fecha en orden descendente.

Parámetros de paginación

El siguiente conjunto de parámetros a los que llegamos son para la paginación. Estos te ayudan a definir cuántas entradas serán consultadas y cómo funcionará la paginación cuando sean mostradas.

Los parámetros disponibles son:

• nopaging (booleano): Muestra todas las entradas o usa paginación. El valor predeterminado es 'false', es decir, usar paginación.
• posts_per_page (int): Número de entradas que se mostrarán por página.
• posts_per_archive_page (int): Número de entradas que se mostrarán por página, únicamente en las páginas de archivo.
• offset (int): Número de entradas a desplazar o saltar.
• paged (int): La página del archivo desde la que se muestran las entradas.
• page (int): número de páginas para una página principal estática. Muestra las entradas que normalmente se mostrarían en una página X de una página frontal estática.
• ignore_sticky_posts (booleano): Ignora la fijación de las entradas: el valor predeterminado es false.

Echemos un vistazo a algunos ejemplos.

Número de entradas y de entradas desplazadas

Por ejemplo, para mostrar las cinco entradas más recientes:

1

$args = array(

2

    'posts_per_page' => '5'

3

);

O para mostrar las cinco entradas recientes excluyendo la más reciente:

1

$args = array(

2

    'posts_per_page' => '5',

3

    'offset' => '1'

4

);

Ten en cuenta que, aunque estás recuperando entradas a partir de las seis entradas más recientes de la base de datos, continúas utilizando 'posts_per_page' ' => '5', ya que es el número de entradas que serán generadas.

Llevando esto un poco más lejos, puedes escribir dos consultas: una para mostrar la entrada más reciente y una segunda para mostrar diez entradas más, excluyendo esa entrada:

1

$args = array(

2

    'posts_per_page' => '1'

3

);

4

5

// Query and loop go here as well as resetting posts.

6

7

$args = array(

8

    'posts_per_page' => '10',

9

    'offset' => '1'

10

);

11

12

// Second query, loop, and resetting go here.

También puedes utilizar posts_per_page para mostrar todas las entradas:

1

$args = array(

2

    'posts_per_page' => '-1'

3

);

Entradas fijadas

Normalmente, tus entradas fijadas se mostrarán en primer lugar en cualquier consulta: si quieres invalidar esto, usa ignore_sticky_posts:

1

$args = array(

2

    'posts_per_page' => '5',

3

    'ignore_sticky_posts' => true

4

);

Los anteriores argumentos devolverán las cinco entradas más recientes, independientemente de si son entradas fijas o no.

Ten en cuenta que si deseas mostrar solo entradas fijadas, tendrás que utilizar la función get_option() y el argumento post__in de la siguiente manera:

1

$sticky = get_option( 'sticky_posts' );

2

3

$args = array(

4

    'posts_per_page' => '5',

5

    'post__in' => $sticky

6

);

Lo anterior mostraría las últimas cinco entradas fijadas: si hay menos de cinco (por ejemplo, tres) entradas fijadas, no mostrará entradas no fijas, sino solo las tres entradas fijadas más recientes.

Paginación en archivos

Además de definir cuántas entradas se obtienen de la base de datos, también puedes utilizar parámetros de paginación para definir cómo se paginarán las entradas resultantes en las páginas de archivo y de búsqueda.

Por ejemplo, en una página de archivo podrías utilizar este código para mostrar 20 entradas por página en el archivo:

1

$args = array(

2

    'posts_per_archive_page' => '20'

3

);

Nota: el argumento posts_per_archive_page invalidará posts_per_page.

También puedes elegir generar solo las páginas que aparecerían en una página determinada en las páginas paginadas. Por ejemplo, si deseas mostrar las 20 entradas que aparecerán en la tercera página del anterior ejemplo, usarías esto:

1

$args = array(

2

    'posts_per_archive_page' => '20',

3

    'paged' => '3'

4

);

Una forma alternativa de consultar las mismas entradas sería usar el argumento offset:

1

$args = array(

2

    'posts_per_page' => '20',

3

    'offset' => '40'

4

);

Esto omite las primeras 40 entradas (que estarían en las dos primeras páginas de archivo) y recupera las siguientes 20 entradas (que estarían en la tercera página de archivo. ¡Una de las cosas que me encanta de WordPress es que muy a menudo te proporciona más de una manera de conseguir algo!

También puedes desactivar por completo la paginación, para asegurarte de que todas las entradas serán mostradas en la misma página:

1

$args = array(

2

    'nopaging' => true

3

);

Resumen

La clase WP_Query te da mucha flexibilidad a la hora de determinar cuántas entradas deseas consultar, en qué orden deseas mostrarlas y qué estado de entrada deseas mostrar.

Algunos de estos argumentos son esenciales para consultar ciertos tipos de entradas (por ejemplo, 'post_status' => 'inherited' para los datos adjuntos), mientras que otros simplemente ofrecen más control sobre la forma en que se ejecutan las consultas.

Mediante el uso de estos parámetros puedes crear consultas personalizadas que hacen mucho más que simplemente generar las entradas más recientemente publicadas.