() translation by (you can also view the original English article)
En artículos anteriores de esta serie, has aprendido cómo está estructurado WP_Query y cuáles son sus propiedades y métodos. El próximo paso consiste en entender los distintos argumentos que puedes usar con él y la mejor forma de hacerlo.
WP_Query tiene un gran número de argumentos posibles, que lo hacen extremadamente flexible. Como lo puedes usar para consultar cualquier cosa contenida en tu tabla wp_posts, tiene argumentos para cada permutación de consulta que puedas desear ejecutar sobre tu contenido.
En este tutorial veremos dos tipos de argumentos para lo siguiente:
- Categorías
- Etiquetas
Los argumentos para estas dos taxonomías son similares pero presentan algunas diferencias que debes conocer si quieres usarlas de forma eficaz.
Un Recordatorio Sobre Cómo Funcionan los Argumentos en WP_Query
Antes de empezar, recordemos cómo funcionan los argumentos en WP_Query. Cuando introduces WP_Query en tus temas o plugins, debes incluir cuatro elementos principales:
- Los argumentos para la consulta, usando los parámetros que veremos en este tutorial.
- la consulta en sí.
- el loop.
- y para terminar: el restablecimiento de los datos del post
En la práctica esto tendrá un aspecto parecido a esto:
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 indicará a WordPress qué datos extraer de la base de datos, que es lo que vamos a ver ahora. Aquí nos vamos a centrar en la primera parte del código:
1 |
$args = array( |
2 |
// Arguments for your query.
|
3 |
);
|
Como puedes ver, los argumentos están contenidos dentro de una cadena. Aprenderás cómo codificarlos a través de este tutorial.
Creando el Código Para Tus Argumentos
Existe una forma concreta de crear el código para los argumentos de la cadena, es la siguiente:
1 |
$args = array( |
2 |
'parameter1' => 'value', |
3 |
'parameter2' => 'value', |
4 |
'parameter3' => 'value' |
5 |
);
|
Debes colocar los parámetros y sus valores entre paréntesis, usa => entre ellos, y sepáralos mediante comas. Si cometes aquí un fallo, WordPress podría no añadir todos tus argumentos en la consulta o podrías acabar con la conocida pantalla en blanco.
Parámetros de Categoría
Empecemos con los parámetros de categoría. Las opciones en este caso son las siguientes:
-
cat(int): usa el id de la categoría. -
category_name(string): usa el slug de la categoría (NO su nombre). -
categori__and(array): usa el id de la categoría. -
category__in(array): usa el id de la categoría. -
category__not_in(array): usa el id de la categoría.
Advierte que en ninguno de ellos usamos el nombre de la categoría. Hasta el parámetro category_name toma el slug de la misma como valor. Yo suelo usarlo en lugar del ID ya que cuando vuelvo al código pasado un tiempo, los slugs son más fáciles de identificar que los IDs. Sin embargo, si piensas que quizá los usuarios de tu sitio vayan a cambiar el slug de una o varias categorías, te recomiendo que uses el ID para evitar cualquier problema en el futuro.
Echemos un vistazo a cómo usar cada uno de estos.
El Parámetro cat
El parámetro cat es bastante sencillo: usa el ID de una categoría o una cadena de IDs de varias categorías.
La consulta de una categoría tendría el siguiente aspecto:
1 |
$args = array( |
2 |
'cat' => '12' |
3 |
);
|
La consulta de varias categorías tendría este aspecto:
1 |
$args = array( |
2 |
'cat' => '12, 13, 14' |
3 |
);
|
Lo anterior le indicará a WordPress que debe consultar los post existentes en cualquiera de las categorías listadas. Si quieres encontrar post pertenecientes a una cadena de categorías, usa el parámetro category_and, veremos esto más adelante.
TAmbién puedes usar el parámetro cat para encontrar posts que pertenezcan a una categoría pero no a otra, usando el signo de restar justo antes del ID de la categoría, como en el siguiente ejemplo:
1 |
$args = array( |
2 |
'cat' => '12, -13' |
3 |
);
|
Lo anterior consultará los posts de la categoría 12, pero solo aquellos que no pertenezcan a su vez a la categoría 13.
El Parámetro category_name
El parámetro category_name usa el slug de la categoría, no su nombre (confuso, ¡lo sé!). De nuevo puedes usarlo para una sola categoría o con una cadena de categorías para encontrar entradas que estén en cualquiera de ellas.
Para consultar posts pertenecientes a una única categoría añades lo siguiente:
1 |
$args = array( |
2 |
'category_name' => 'my-slug' |
3 |
);
|
Y para encontrar las entradas pertenecientes a una o más categorías, usa esto:
1 |
$args = array( |
2 |
'category_name' => 'my-slug, your-slug, another-slug' |
3 |
);
|
Al igual que ocurre con el parámetro cat, esto no encontrará los posts existentes en todas las categorías, sino los posts de cualquiera de las categorías.
El Parámetro category_and
Si quieres encontrar posts presentes en todas las categorías de una cadena, este es el parámetro que debes usar. Se necesitan los IDs de la categoría para su valor. Por tanto, para encontrar los posts pertenecientes a todas las tres categorías, usarías lo siguiente:
1 |
$args = array( |
2 |
'category__and' => array( |
3 |
'12', |
4 |
'13', |
5 |
'14'
|
6 |
)
|
7 |
);
|
Observa que esto hace uso de un array, no de una cadena, por eso el código es distinto. El parámetro tiene dos guiones bajos en su nombre: si usas solo uno no funcionará.
El Parámetro category_in
El siguiente parámetro busca los posts pertenecientes a una o más de una de las categorías de un array. Realmente funciona de la misma manera que el parámetro cat, y además toma el ID de la categoría como su valor.
Por tanto, para consultar posts pertenecientes a una o más categorías de un array, usarías lo siguiente:
1 |
$args = array( |
2 |
'category__in' => array( |
3 |
'12', |
4 |
'13', |
5 |
'14'
|
6 |
)
|
7 |
);
|
El ejemplo de arriba devolverá los posts pertenecientes a una o más de una de esas categorías.
El Parámetro category_not_in
El parámetro category_not_in sirve para lo que te estás imaginando: consulta los posts que no pertenecen a una cierta categoría o a un array de categorías.
Para excluir posts de una categoría, usarías el siguiente código:
1 |
$args = array( |
2 |
'category__not_in' => '12' |
3 |
);
|
Y para excluir posts de un array de categorías:
1 |
$args = array( |
2 |
'category__not_in' => array( |
3 |
'12', |
4 |
'13', |
5 |
'14'
|
6 |
)
|
7 |
);
|
Esto excluirá los posts de cualquiera de estas categorías.
Parámetros de Etiqueta
Las etiquetas tienen parámetros un poco distintos a las categorías: no puedes puedes conocer cuáles podrían ser basándote en tus conocimientos sobre los parámetros de las categorías, ¡lo siento!
Los parámetros de etiqueta son:
-
tag(string): usa el slug de la etiqueta. -
tag_id(int): usa el id de la etiqueta. -
tag__and(array): usa los ids de las etiquetas. -
tag__in(array): usa ids de etiquetas. -
tag__not_in(array): usa ids de etiquetas. -
tag_slug__and(array): usa el slug de la etiqueta. -
tag_slug__in(array): usa el slug de la etiqueta.
Veamos cada uno de ellos.
El Parámetro tag
El parámetro tag usa el slug de la etiqueta como valor y puede usarse para encontrar posts que tengan asignada una determinada etiqueta o cualquier etiqueta que definas mediante una cadena.
Por tanto, para encontrar posts con una determinada etiqueta, usarías lo siguiente:
1 |
$args = array( |
2 |
'tag' => 'my-tag' |
3 |
);
|
Y para encontrar posts con etiquetas presentes en un array de etiquetas:
1 |
$args = array( |
2 |
'tag' => 'my-tag, your-tag, another-tag' |
3 |
);
|
Observa que la anterior consulta localiza los posts con cualquiera de las etiquetas presentes en el array, no necesariamente todas.
El Parámetro tag_id
El parámetro tag_id funciona de forma similar a como lo hace el parámetro cat: toma el ID de la etiqueta y puede usarse con una sola etiqueta o con varias.
Para encontrar posts con una única etiqueta usa esto:
1 |
$args = array( |
2 |
'tag_id' => '21' |
3 |
);
|
Para encontrar posts con una o más etiquetas definidas en una cadena de IDs de etiquetas:
1 |
$args = array( |
2 |
'tag_id' => '21, 22, 23' |
3 |
);
|
También puedes utilizar tag_id para excluir etiquetas, tanto para etiquetas individuales o como para varias.
Por tanto para consultar posts excluyendo aquellos con una determinada etiqueta, usarías lo siguiente:
1 |
$args = array( |
2 |
'tag_id' => '-21' |
3 |
);
|
Mientras que para encontrar posts con una de entre dos etiquetas pero además excluir otra, usarías lo siguiente:
1 |
$args = array( |
2 |
'tag_id' => '21, -22, 23' |
3 |
);
|
Es decir, lo anterior localizaría los posts con alguna o ambas de las siguientes etiquetas, 21 o 23, pero que en ningún caso tengan asignada la etiqueta 22.
El Parámetro tag_in
Este parámetro le permite buscar mensajes con uno o más de un conjunto de etiquetas. Funciona de la misma manera que tag cuando se utiliza con un array:
1 |
$args = array( |
2 |
'tag_in' => array( |
3 |
'21', |
4 |
'22', |
5 |
'23'
|
6 |
)
|
7 |
);
|
Para consultar los posts con cualquiera o todas las etiquetas enumeradas. Si deseas buscar posts con todas las etiquetas, usa tag__and, lo explicaré en un momento.
El Parámetro tag__not_in
El parámetro tag__not_in te permite consultar los posts que no tienen asignada una determinada etiqueta o ninguna de las etiquetas presentes en un array.
Úsalo para excluir una etiqueta:
1 |
$args = array( |
2 |
'tag__not_in' => array( '21' ) |
3 |
);
|
Observa que todavía necesitas usar un array, aunque solo estés usando una etiqueta. Para usar más etiquetas, usa:
1 |
$args = array( |
2 |
'tag__not_in' => array( |
3 |
'21', |
4 |
'22', |
5 |
'23'
|
6 |
)
|
7 |
);
|
Esto consultará los posts que no tengan asignada ninguna de las etiquetas de arriba.
Los Parámetros tag_slug__and y tag_slug__in
Estos dos parámetros se comportan en la misma forma que los parámetros tag__and y tag__in, salvo que utilices ese slug de etiqueta en tus arrays en lugar del ID de etiqueta.
Así que por ejemplo, para encontrar posts que tengan ambos pares de etiquetas, usarías tag__slug_in:
1 |
$args = array( |
2 |
'tag_slug__in' => array( |
3 |
'my-tag', |
4 |
'your-tag', |
5 |
'another-tag'
|
6 |
)
|
7 |
);
|
Esto localizará los posts pertenecientes a cualquiera de estas etiquetas. También podrías usar el parámetro de la etiqueta con una cadena slugs de etiquetas para conseguir el mismo resultado.
Para incluir los posts con todas las etiquetas de un grupo, usa tag_slug__and:
1 |
$args = array( |
2 |
'tag_slug__and' => array( |
3 |
'my-tag', |
4 |
'your-tag', |
5 |
'another-tag'
|
6 |
)
|
7 |
);
|
En lugar de consultar los posts con cualquiera de estas etiquetas, esto consultará solo los posts que tienen asignadas todas estas etiquetas.
Resumen
Consultar tus posts por categoría y/o etiqueta es algo que muy probablemente tendrás ocasión de usar con WP_Query. Usando los argumentos anteriores, y combinándolas en caso necesario, puede crear argumentos poderosos para extraer exactamente los datos que necesita de la base de datos.
