Creando bucles personalizados – La clase wp_query y su funcionamiento

Introducción

En este artículo vamos a tratar uno de los pilares del funcionamiento de WordPress: «la clase WP_Query y su funcionamiento». Cuando hablamos de WP_Query nos estamos refiriendo al bucle, loop o consulta principal de WordPress, es la consulta que se ejecuta siempre en todas las páginas de nuestro blog antes de la carga de la plantilla.

EL OBJETIVO de este artículo: es aprender a implementar consultas o bucles personalizados con wp_query y poder modificar el contenido que se mostrará en cada plantilla de nuestro theme.

¿Qué es WP_Query?

WP_Query es una clase que forma parte del núcleo de WordPress, cuando instalas WordPress esta clase se instala con el resto de archivos, puedes encontrarla dentro de la carpeta wp-includes de tu WordPress:

wp-includes/query.php

La función de WP_Query es decidir que consulta tiene que hacer a la base de datos para mostrar el contenido según la página que se visite en ese momento, la información a mostrar será diferente según el tipo de página (mostrar entradas, mostrar sólo una entrada, mostrar una página estática…) Esta consulta sobre la base de datos se realiza antes de cargar la plantilla y los  que se quiere visualizar.

Si abres una plantilla de tu tema (por ejemplo page.php, index.php…) verás algo similar a lo siguiente:

<?php if (have_posts()) : while (have_posts()) : the_post(); ?>
      
        <h1><?php the_title(); ?></h1>
        
        <?php the_content(); ?>
        
        
        <?php endwhile; else: ?>
        
            <h3>Lo siento, no hay entradas</h3>
        
        <?php endif; ?>

Si te das cuenta empiezan siempre con la comprobación: si hay post entonces comienza el bucle y de cada post se muestra el título y el contenido, si no hay post entonces salta al mensaje «Lo siento…», es decir el array con los post ya se ha creado antes de cargar la plantilla y lo que hacemos aquí es mostrar el contenido de esta consulta principal de WordPress.

WP_Query nos permite a los desarrolladores realizar modificaciones en WordPress sin tener que implementar mucho código, resulta muy sencillo cuando entiendes esta clase crear consultas o bucles personalizados y es una forma segura de trabajar.

5 maneras diferentes de crear consultas personalizadas o bucles personalizados con WP_Query

En este artículo vamos a trabajar con consultas personalizadas sobre la clase wp_query. Wp_query no es el único recurso disponible en WordPress para realizar consultas personalizadas existen 4 recursos más que explicaremos brevemente. 

Aquí tienes los 5 recursos disponibles en WordPress para crear loops, bucles o consultas personalizadas mediante las cuales podemos mostrar distintos contenidos en las páginas de nuestro sitio. 

1. wp_query (la vemos en este artículo)

2. pre_get_post – es un hook

3. get_posts() –  es una función

4. get_pages() – es una función

5. query_posts() – es una función en desuso

En este artículo vamos a explicar wp_query, si te interesa conocer el uso de pre_get_post, get_posts()… visita el siguiente artículo de este blog:

>> 5 maneras diferentes de crear consultas personalizadas en WordPress

WP_Query es la manera adecuada de crear bucles o loop alternativos en nuestras plantillas de WordPress. Utilizando WP_Query creamos una nueva instancia del objeto WP_Query dejando la consulta principal de WordPress intacta. Es decir:

creamos una nueva consulta adaptada a nuestras necesidades y trabajando desde 0.

¿Cuándo utilizar WP_Query?

Normalmente yo sí utilizo wp_query para bucles personalizados en los siguientes casos:

1. Para crear varias consultas, loops o bucles en la misma página. ¿Por qué?  si utilizas query_post() para los bucles secundarios de una misma página el resultado puede arrojar datos inesperados y que no se muestre los post, entradas… que queremos. Si necesitas crear dos consultas en la misma página, añadir una consulta en el pie de página o en el lateral, utiliza WP_Query.
2. Cuando trabajo con Custom Post Types o tipos personalizados y nuevas plantillas.

No utilizo wp_query para:

1. Para añadir más campos dentro del bucle, por ejemplo añadir campo resumen, añadir enlaces, añadir campos personalizados… en estos casos añado campos dentro del bucle en la plantilla o la duplico para añadir estos campos.
2. Cuándo quiero que en una determinada página salgan post de cierto contenido (aquí utilizo pre_get_post).
3. Cuándo necesito filtrar contenido del bucle principal que sólo afecta a post, por ejemplo modificar el número de post que se ven en la página, que sólo se vean los post de un tipo, que no se vea un determinado post… aquí utilizo get_posts().

…

¿Dónde escribo el código WP_Query?

Directamente en tus plantillas de archivo, puedes modificar las que vienen por defecto en wordpress como page.php (si afecta a todas las entradas) o crear nuevas páginas (plantillas). Si las vas a modificar borra el bucle principal y en su lugar implementa lo que te explico a continuación.

Partes de una consulta o bucle personalizado con WP_Query

Para explicaros cómo crear nuestras nuevas consultas, vamos a dividir el código en partes.

Parte 1.- Argumentos

Así iniciamos la nueva consulta al principio de nuestra plantilla o archivo del theme.

<?php
 
$parametros = array(
    // un array con los parámetros de nuestra consulta.
);

Creamos un nuevo array $args con los parámetros de nuestra consulta; por ejemplo post de una determinada categoría, post de un determinado tipo…

Ejemplo de array con argumentos:

<?php $parametros = array( 'post_type' => 'oferta',  'order' => 'ASC','posts_per_page' => -1);

en este ejemplo quiero que muestre los post personalizados (Custom Post Type) de tipo «oferta» ordenados de forma ascendente y que muestre todos.

Aquí te dejo un enlace a todos los parámetros, propiedades y métodos de wp_quey.

Parte 2.- Creando la nueva instancia del objeto wp_query

Definimos una variable que guardará nuestra consulta y le pasamos el array de argumentos o parámetros creados en el paso 1:

$wp_query_personalizada = new WP_Query( $parametros ); ?>

puedes juntar la parte 1 y 2 en una línea de código de la siguiente manera:

$query = new WP_Query( array( 'post_type' => 'oferta',  'order' => 'ASC','posts_per_page' => -1) );

Parte 3.- Comprobación y comienzo del bucle

<?php if($wp_query_personalizada->have_posts()) : 
while($wp_query_personalizada->have_posts()) :
$wp_query_personalizada->the_post();?>

En palabras si nuestra instancia tiene post entonces mientras existan post vamos llamando uno por uno para en el siguiente paso mostrar la información de cada post que nos interese.

Parte 4.- Mostrando información de cada post dentro del bucle

En este caso vamos a mostrar de cada post: la imagen en miniatura con un tamaño propio y que he definido (tamanyo_img_ofertas) en el archivo functions.php, el título the_title(), un campo personalizado the_field(‘precio’), el contenido the_content().

<div class="servicio">
      <?php if(has_post_thumbnail()) {
	the_post_thumbnail('tamanyo_img_ofertas');}?>	

	<div class="servicio-text listas_servicio">	
           <h1 class="entry-title"><?php the_title(); ?> - Precio: <?php the_field('precio'); ?> &euro; </h1>
	   <?php the_content(); ?>
           <p class="precio"><?php the_field('precio'); ?> &euro;</p>
          
     </div> <!-- .servicio-text listas_servicio -->
</div> <!-- .servicio -->

Parte 5. Fin del bucle

<?php   endwhile;?>
</div>

Parte 6. Llamada a paginación (OPCIONAL)

Entre el final del bucle y antes de resetear la consulta puedes poner tus llamadas a las funciones de paginación, si necesitas crear nuevas funciones de paginación en tu blog, aquí te dejo un artículo con el código de algunas funciones de paginación interesantes.

Parte 7. IMPORTANTE – Resetear la consulta

<?php wp_reset_postdata(); ?>

Después de crear una consulta o bucle personalizado con wp_query hay que utilizar , así evitamos que otros bucles de la misma página se vean afectados por este restaurando la variable global $post de la consulta o loop principal.

Recuerda: si utilizas the_post() en tu consulta personalizada, en nuestro caso lo utilizamos aquí 

$wp_query_personalizada->the_post();

debes utilizar después del bucle wp_reset_postdata()

Hay otros métodos para restaurar el loop principal como wp_reset_query(), pero no debes utilizarlo aquí, deja este método para utilizarlo con query_posts().

Parte 8. Mensaje a mostrar si nuestra consulta no tiene post (OPCIONAL)

<?php else : ?>
	<p><?php echo "SIN POST"; ?></p>
<?php endif; ?>

Si no quieres mostrar el mensaje opcional aquí sólo debes poner el cierre del if 

<?php endif; ?>

CÓDIGO COMPLETO PARA COPIAR Y PEGAR

<?php $parametros = array( 'post_type' => 'oferta',  'order' => 'ASC','posts_per_page' => -1);
$wp_query_personalizada = new WP_Query( $parametros ); ?>

    <?php if($wp_query_personalizada->have_posts()) : 
          while($wp_query_personalizada->have_posts()) :
                 ?>
          
          <div class="servicio">
      <?php if(has_post_thumbnail()) {
	the_post_thumbnail('tamanyo_img_ofertas');}?>	

	<div class="servicio-text listas_servicio">	
           <h1 class="entry-title"><?php the_title(); ?> - Precio: <?php the_field('precio'); ?> &euro; </h1>
	   <?php the_content(); ?>
           <p class="precio"><?php the_field('precio'); ?> &euro;</p>
          
         </div> <!-- .servicio-text listas_servicio -->
        </div> <!-- .servicio -->
<?php   endwhile;?>
</div>

	<!-- llamadas a Funciones de paginacion -->
<?php wp_reset_postdata(); ?>
<?php else : ?>
	<p><?php echo "SIN POST"; ?></p>
<?php endif; ?>

Si necesitas más información y ejemplos puedes recurrir a la página oficial del codex de wordpress pulsando aquí.