Ciao e benvenuti alla seconda parte di questa serie chiamata "Padroneggiare WP_Query". Nella prima parte, abbiamo iniziato con una semplice introduzione di che cosa è classe WP_Query. E in questa seconda parte, stiamo andando a conoscere le funzioni correlate a WP_Query.

Cominciamo!

Sfruttare la potenza di WP_Query con funzioni, azioni e filtri

Non sono un esperto di programmazione, ma posso vedere che la classe WP_Query è uno dei migliori esempi di modello MVC. È estremamente potente, completamente estendibile e molto facile da usare una volta che si arriva a conoscerne le nozioni base.

Oltre alle sue proprietà, metodi e parametri (che vedremo in futuro), WordPress offre funzioni extra e ganci (cioè azioni e filtri) per lavorare con la classe WP_Query. In questo tutorial, stiamo andando a conoscere le funzioni e nella parte successiva, vedremo le azioni e filtri legati a WP_Query. Se vedete che ho dimenticato qualcosa, non esitate a comunicarmelo lasciando un commento.

WP_Query funzioni correlate

Ci sono 13 funzioni di WordPress che lavorano con la classe WP_Query e che ci aiutano a sfruttare la potenza di WP_Query. Non hanno bisogno di alcuna introduzione, andiamo qui:

Ottenere le variabili di Query pubbliche: get_query_var()

Il nome della nostra prima funzione parla da sé, davvero: prende l'oggetto globale $wp_query e recupera una variabile di query pubblica da esso. Dispone di due parametri: il primo è la variabile che restituisce il relativo valore, e il secondo è un valore predefinito da restituire se la variabile non è impostata:

<?php

$paged = get_query_var( 'paged', 1 );

?>

Che interessano il loop principale: query_posts()

Che ad essere onesti, è una pessima funzione. Non si dovrebbe usarla affatto, ma per dire "nel modo giusto", andremo a dire che è "il modo sbagliato".

query_posts() è una funzione che altera la query principale mettendola da parte ed eseguendo una nuova query — e dopo di questa sarà necessario utilizzare wp_reset_query() per ripristinare i dati.

<?php

query_posts( 'category_name=news' );

?>

Questa funzione è una delle funzioni più abusate nel core di WordPress. Non si dovrebbe usare per creare una query secondaria — è possibile utilizzare la classe WP_Query o la funzione di get_posts() (di cui parleremo più avanti in questo tutorial). Non si dovrebbe usare per modificare la query principale  —  bisognerebbe invece usare l'azione pre_get_posts (di cui parleremo più tardi). Anche il Codex ci sconsiglia di utilizzarlo e mostra alternative.

Ultima riga: non usarla.

Visualizzare un singolo post: get_post()

Un'altra funzione auto-esplicativa è get_post(), che si utilizza per ottenere un singolo post. Ha tre parametri facoltativi:

• Il primo è l'ID del post (o l'ID del post corrente per impostazione predefinita).
• Il secondo è il tipo del risultato che si otterrà: OBJECT, ARRAY_A (matrice associativa) o ARRAY_N (una matrice numerica).
• Il terzo è la scelta di filtrare il risultato. Il valore predefinito è 'raw', quindi non sarà filtrato se non impostate su 'edit', 'display', 'attribute' o 'js'.

<?php

$first_post = get_post( 1, ARRAY_A );
$post_title = $first_post[ 'post_title' ];

?>

Salvare query in array: get_posts()

La funzione get_posts() consente di eseguire query e salvarle come array da utilizzare in vari modi. Richiede gli stessi argomenti di WP_Query quindi è possibile personalizzare la query come si preferisce. (Vedremo parametri di WP_Query in futuro, quindi rimanete sintonizzati!) È il modo migliore e più efficiente per creare elenchi di post — ma non loop.

<?php

$args = array(
    'category_name' => 'news',
    'order' => 'ASC',
    'orderby' => 'post_title',
    'posts_per_page' => -1
);

// Return an array of all posts in the "news" category.
$all_posts_list = get_posts( $args );

?>

Anche se questa funzione può essere utilizzata per eseguire "query secondarie" senza un problema, il Codex consiglia di usare WP_Query per creare loop multipli e get_posts() quando si recupera un elenco di post. Peter R. Knight spiega le differenze tra get_posts() e WP_Query in termini semplici: la differenza principale è che WP_Query restituisce più query di database (dati del post, metadati, dati sull'autore e commenti) mentre get_posts() restituisce solo una query (dati del post).

Visualizzare pagine: get_pages()

Questa strana funzione ha lo scopo di andare a prendere un elenco di pagine, anche se ha un parametro di post_type che può anche permettere di selezionare un altro tipo di post (purché il tipo di post sia gerarchico, in caso contrario restituisce false).

<?php

$args = array(
    'sort_order' => 'ASC',
    'sort_column' => 'post_title',
    'hierarchical' => 1,
    'exclude' => '',
    'include' => '',
    'meta_key' => '',
    'meta_value' => '',
    'authors' => '',
    'child_of' => 0,
    'parent' => -1,
    'exclude_tree' => '',
    'number' => '',
    'offset' => 0,
    'post_type' => 'page',
    'post_status' => 'publish'
);

$pages = get_pages( $args );

?>

Accetta argomenti che sono molto simili agli argomenti di WP_Query, ma con alcune differenze:

• sort_order: se ordinare le pagine in ordine crescente (asc) o decrescente (desc).
• sort_column: come ordinare le pagine. Accetta post_title, menu_order, post_date, post_modified, ID, post_author e post_name.
• hierarchical: se elencare pagine gerarchicamente (1) o no (0).
• exclude: un elenco separato da virgole di array di ID di pagine da escludere dall'elenco.
• include: un elenco separato da virgole di array di ID di pagine da includere nell'elenco escludendo tutto il resto.
• meta_key: quando utilizzato con l'argomento meta_value, include solo le pagine che hanno il meta e il valore definito.
• meta_value: quando utilizzato con l'argomento meta_key, include solo le pagine che hanno il meta e il valore definito.
• authors: elenco ID di autori separarato da virgole.
• child_of: un ID di una pagina per recuperare solo suoi figli e nipoti nella lista.
• parent: elenca le pagine che hanno l'ID di pagina indicato come genitore. Perché questo argomento possa lavorare, l'argomento hierarchical deve essere impostato su 0.
• exclude_tree: un elenco separato da virgola di array di pagina ID che esclude i relativi figli.
• number: numero di pagine da recuperare.
• offset: numero di pagine da saltare dall'ultima.
• post_type: il tipo di post su cui eseguire la query. Naturalmente, l'impostazione predefinita è page.
• post_status: un elenco separato da virgole dei tipi di stato dei post da includere.

Verifica se la Query restituisce tutti i post: have_posts()

Senza accettare alcun parametro, questa funzione restituisce semplicemente TRUE se la query trova almeno un post e FALSE se non lo fa.

<?php

if ( have_posts() ) {
    
    // Success.
    
} else {
    
    // Failure.
    
}

?>

Il loop al lavoro: the_post()

Il Codex dice che "itera l'indice del post nel loop". Fa diverse cose:

1. Recupera il record successivo dalla query.
2. Imposta i dati di $post.
3. Imposta il parametro in_the_loop su TRUE.

<?php

if ( have_posts() ) {

    while ( have_posts() ) {

        the_post();

        the_title();

        the_content();

    }
    
}

?>

Impostare $post: setup_postdata()

Questa funzione parla da sola: definisce i dati globali del post. Vediamo che cosa il Codex dice:

setup_postdata() riempie le variabili globali, $id, $authordata, $currentday, $currentmonth, $page, $pages, $multipage, $more, $numpages, che aiutano molti Template Tags a lavorare nell'attuale contesto del post. E non assegna la variabile globale $post, ma sembra aspettarsi che l'argomento sia un riferimento ad essa.

<?php

global $post;

setup_postdata( $post );

?>

Pulire il loop corrente: rewind_posts()

Ancora un'altra funzione il cui nome afferma la sua funzionalità: questa funzione semplicemente "riavvolge" il ciclo di modo che sia possibile eseguirlo nuovamente più tardi.

<?php

// After the loop.
rewind_posts();

?>

Reimpostare $post: wp_reset_postdata()

Questa funzione reimposta la variabile globale $post  alla query principale. È preferibile utilizzarla dopo una query secondaria.

<?php

// After a secondary query.
wp_reset_postdata();

?>

Reimpostare la Query: wp_reset_query()

Questa dovrebbe essere usata se la query principale viene modificata (con la funzione query_posts () o l'azione pre_get_posts che vedremo nella prossima parte) affinché la query principale possa essere reimpostata.

<?php

// After the main query is altered.
wp_reset_query();

?>

Verificare se l'attuale Query è la Query principale: is_main_query()

Questo è un Tag condizionale che restituisce TRUE se la query corrente è la query principale e FALSE se non lo è. Semplice, vero?

<?php

if ( is_main_query() ) {
    
    // Success.
    
} else {
    
    // Failure.
    
}

?>

Verifica se siamo nel Loop: in_the_loop()

Un altro Tag condizionale è in_the_loop() che restituisce TRUE o FALSE a seconda del fatto che il codice sia eseguito all'interno del loop o meno.

<?php

if ( in_the_loop() ) {
    
    // Success.
    
} else {
    
    // Failure.
    
}

?>

Fine della seconda parte

Ci si va — ora sapete (probabilmente) tutte le funzioni relative a WP_Query! Restate sintonizzati per la prossima parte dove impareremo le azioni e i filtri relativi a WP_Query.

Avete qualche commento o qualcosa da aggiungere a questa parte? Sentitevi liberi di condividere i vostri pensieri commentando qui sotto. E se ti è piaciuto questo articolo, non dimenticare di condividerlo con i vostri amici!