Come risolvere la paginazione per i loop personalizzati?

Il Problema

Per impostazione predefinita, in qualsiasi contesto, WordPress utilizza la query principale per determinare l'impaginazione. L'oggetto della query principale è memorizzato nella variabile globale $wp_query, che viene utilizzata anche per generare il loop della query principale:

if ( have_posts() ) : while ( have_posts() ) : the_post();

Quando si utilizza una query personalizzata, si crea un oggetto query completamente separato:

$custom_query = new WP_Query( $custom_query_args );

E quella query viene generata tramite un loop completamente separato:

if ( $custom_query->have_posts() ) : 
    while ( $custom_query->have_posts() ) : 
        $custom_query->the_post();

Ma i tag template per l'impaginazione, inclusi previous_posts_link(), next_posts_link(), posts_nav_link() e paginate_links(), basano il loro output sull'oggetto query principale, $wp_query. Quella query principale potrebbe essere impaginata o meno. Se il contesto corrente è un template di pagina personalizzato, ad esempio, l'oggetto principale $wp_query consisterà in un singolo post - quello dell'ID della pagina a cui è assegnato il template personalizzato.

Se il contesto corrente è un indice di archivio di qualche tipo, la query principale $wp_query potrebbe contenere abbastanza post da causare l'impaginazione, il che porta alla parte successiva del problema: per l'oggetto query principale $wp_query, WordPress passerà un parametro paged alla query, basato sulla variabile di query URL paged. Quando la query viene recuperata, quel parametro paged verrà utilizzato per determinare quale insieme di post impaginati restituire. Se viene cliccato un link di impaginazione visualizzato e viene caricata la pagina successiva, la tua query personalizzata non avrà alcun modo di sapere che l'impaginazione è cambiata.

La Soluzione

Passare il Parametro Paged Corretto alla Query Personalizzata

Supponendo che la query personalizzata utilizzi un array di argomenti:

$custom_query_args = array(
    // Parametri della query personalizzata vanno qui
);

Sarà necessario passare il parametro paged corretto all'array. Puoi farlo recuperando la variabile di query URL utilizzata per determinare la pagina corrente, tramite get_query_var():

get_query_var( 'paged' );

Puoi quindi aggiungere quel parametro al tuo array di argomenti della query personalizzata:

$custom_query_args['paged'] = get_query_var( 'paged' ) 
    ? get_query_var( 'paged' ) 
    : 1;

Nota: Se la tua pagina è una pagina frontale statica, assicurati di utilizzare page invece di paged poiché una pagina frontale statica utilizza page e non paged. Questo è ciò che dovresti avere per una pagina frontale statica

$custom_query_args['paged'] = get_query_var( 'page' ) 
    ? get_query_var( 'page' ) 
    : 1;

Ora, quando la query personalizzata viene recuperata, verrà restituito il set corretto di post impaginati.

Utilizzare l'Oggetto Query Personalizzata per le Funzioni di Impaginazione

Affinché le funzioni di impaginazione producano l'output corretto - cioè i link precedenti/successivi/pagina relativi alla query personalizzata - WordPress deve essere forzato a riconoscere la query personalizzata. Ciò richiede un piccolo "hack": sostituire l'oggetto query principale $wp_query con l'oggetto query personalizzato, $custom_query:

Modificare l'oggetto query principale

1. Eseguire il backup dell'oggetto query principale: $temp_query = $wp_query
2. Annullare l'oggetto query principale: $wp_query = NULL;

3. Sostituire la query personalizzata nell'oggetto query principale: $wp_query = $custom_query;

   $temp_query = $wp_query;
   $wp_query   = NULL;
   $wp_query   = $custom_query;
   

Questo "hack" deve essere fatto prima di chiamare qualsiasi funzione di impaginazione

Ripristinare l'oggetto query principale

Una volta che le funzioni di impaginazione sono state generate, ripristinare l'oggetto query principale:

$wp_query = NULL;
$wp_query = $temp_query;

Correzioni alle Funzioni di Impaginazione

La funzione previous_posts_link() funzionerà normalmente, indipendentemente dall'impaginazione. Determina semplicemente la pagina corrente e poi genera il link per pagina - 1. Tuttavia, è necessaria una correzione per next_posts_link() per generare correttamente l'output. Questo perché next_posts_link() utilizza il parametro max_num_pages:

<?php next_posts_link( $label , $max_pages ); ?>

Come per altri parametri di query, per impostazione predefinita la funzione utilizzerà max_num_pages per l'oggetto query principale $wp_query. Per forzare next_posts_link() a considerare l'oggetto $custom_query, sarà necessario passare max_num_pages alla funzione. Puoi recuperare questo valore dall'oggetto $custom_query: $custom_query->max_num_pages:

<?php next_posts_link( 'Post più vecchi' , $custom_query->max_num_pages ); ?>

Mettendo tutto insieme

Quello che segue è un costrutto di base di un loop di query personalizzato con funzioni di impaginazione che funzionano correttamente:

// Definire i parametri della query personalizzata
$custom_query_args = array( /* Parametri vanno qui */ );

// Ottenere la pagina corrente e aggiungerla all'array dei parametri della query personalizzata
$custom_query_args['paged'] = get_query_var( 'paged' ) ? get_query_var( 'paged' ) : 1;

// Istanzare la query personalizzata
$custom_query = new WP_Query( $custom_query_args );

// Correzione dell'impaginazione
$temp_query = $wp_query;
$wp_query   = NULL;
$wp_query   = $custom_query;

// Generare il loop della query personalizzata
if ( $custom_query->have_posts() ) :
    while ( $custom_query->have_posts() ) :
        $custom_query->the_post();
        // Output del loop va qui
    endwhile;
endif;
// Ripristinare i dati del post
wp_reset_postdata();

// Impaginazione del loop della query personalizzata
previous_posts_link( 'Post più vecchi' );
next_posts_link( 'Post più recenti', $custom_query->max_num_pages );

// Ripristinare l'oggetto query principale
$wp_query = NULL;
$wp_query = $temp_query;

Addendum: E query_posts()?

query_posts() per Loop Secondari

Se stai utilizzando query_posts() per generare un loop personalizzato, anziché istanziare un oggetto separato per la query personalizzata tramite WP_Query(), allora stai _doing_it_wrong() e incorrerai in diversi problemi (non il minimo dei quali saranno problemi di impaginazione). Il primo passo per risolvere questi problemi sarà convertire l'uso improprio di query_posts() in una chiamata corretta a WP_Query().

Utilizzare query_posts() per Modificare il Loop Principale

Se vuoi semplicemente modificare i parametri per la query del loop principale - come cambiare il numero di post per pagina o escludere una categoria - potresti essere tentato di utilizzare query_posts(). Ma non dovresti comunque. Quando utilizzi query_posts(), forzi WordPress a sostituire l'oggetto query principale. (WordPress in realtà effettua una seconda query e sovrascrive $wp_query.) Il problema, però, è che fa questa sostituzione troppo tardi nel processo per aggiornare l'impaginazione.

La soluzione è filtrare la query principale prima che i post vengano recuperati, tramite l'hook pre_get_posts.

Invece di aggiungere questo al file del template della categoria (category.php):

query_posts( array(
    'posts_per_page' => 5
) );

Aggiungi quanto segue a functions.php:

function wpse120407_pre_get_posts( $query ) {
    // Test per l'indice dell'archivio della categoria
    // e assicurarsi che la query sia la query principale
    // e non una query secondaria (come l'output di un menu di navigazione
    // o di un widget di post recenti, ecc.
    if ( is_category() && $query->is_main_query() ) {
        // Modificare i post per pagina
        $query->set( 'posts_per_page', 5 ); 
    }
}
add_action( 'pre_get_posts', 'wpse120407_pre_get_posts' );

Invece di aggiungere questo al file del template dell'indice dei post del blog (home.php):

query_posts( array(
    'cat' => '-5'
) );

Aggiungi quanto segue a functions.php:

function wpse120407_pre_get_posts( $query ) {
    // Test per l'indice principale dei post del blog
    // e assicurarsi che la query sia la query principale
    // e non una query secondaria (come l'output di un menu di navigazione
    // o di un widget di post recenti, ecc.
    if ( is_home() && $query->is_main_query() ) {
        // Escludere la categoria ID 5
        $query->set( 'category__not_in', array( 5 ) ); 
    }
}
add_action( 'pre_get_posts', 'wpse120407_pre_get_posts' );

In questo modo, WordPress utilizzerà l'oggetto $wp_query già modificato quando determina l'impaginazione, senza necessità di modifiche al template.

Quando utilizzare quale funzione

Studia questa domanda e risposta e questa domanda e risposta per capire come e quando utilizzare WP_Query, pre_get_posts e query_posts().