Paginate_links() a função matadora do plugin WP-PageNavi

O WordPress, por padrão, exibe dez registros por vez. Isso é uma configuração que define quantos elementos serão exibidos por página. Logo, quando temos mais de dez registros a serem mostrados precisamos paginar os conteúdos para exibi-los em sua totalidade.

Paginação de conteúdo é muito comum e largamente utilizado em todos os tipos de sites e aplicações web. Através do WordPress fazemos isso com o uso de funções nativas e/ou plugins.

No Apiki WP Cursos, mais especificamente no curso Desenvolvimento de Temas WordPress Standard, abordamos o assunto apresentando algumas funções nativas do WordPress, como next_post_link(), previous_post_link(), posts_nav_link() e paginate_links(). Essa última função foi a motivadora deste artigo e ao longo deste encontro descobriremos o motivo.

Nos primórdios do WordPress, as funções next_post_link() e previous_post_link() foram largamente utilizadas para exibir as famosas navegações no estilo “Próximos posts” e “Posts anteriores”. No entanto, projetistas sentiam a necessidade de um modelo diferenciado, com uma melhor experiência e possibilidade de navegação além das setas de avançar e retroceder, chegando ao modelo de uma paginação com números. Para exemplificar esse modelo, pense na paginação com números do Google.

A partir daí, entra um plugin famoso e muito utilizado com mais de três milhões de downloads, chamado WP-PageNavi. Através desse plugin, desenvolvedores conseguiam aplicar a esperada paginação com números.

Para a surpresa de muitos, o WordPress desde sua versão 2.1, lançada em janeiro de 2007, disponibiliza a função paginate_links() que entrega o mesmo resultado que o citado plugin – « Prev 1 … 3 4 5 6 7 … 9 Next ». Assim, temos o recurso de paginação com números sem plugin, de forma nativa, sem a preocupação de baixar um recurso adicional, sem se preocupar em atualizar tal recurso e ainda ganhando em performance e segurança.

Como fazer uso da função paginate_links()

Minha sugestão é criar uma função para englobar a função paginate_links() com seus respectivos parâmetros e configurações. Isso facilitará o reuso da funcionalidade em demais projetos. Encare essa função como uma Template tag personalizada para você; exclusiva. Unica. Neste artigo, chamaremos essa função de apiki_paginate_links().

Essa função deverá ser chamada logo após o loop, seja ele padrão, personalizado ou adicional. Vejo o exemplo:

while( have_posts() ) : the_post();
 // templates tags para exibir conteúdos
 endwhile;

if ( function_exists( 'apiki_paginate_links' ) ) apiki_paginate_links(); // Função que imprimirá a marcação HTML da paginação com números

Observe agora o código da função apiki_paginate_links():

/**
 * This function wraps the WordPress paginate_links function.
 * 
 * @param array $args See http://codex.wordpress.org/Function_Reference/paginate_links for documentation
 * @uses paginate_links()
 */
function apiki_paginate_links( $args = array() )
{
    global $wp_query;

    $defaults = array(
        'big_number' => 999999999,
        'base'       => str_replace( 999999999, '%#%', get_pagenum_link( 999999999 ) ),
        'format'     => '?paged=%#%',
        'current'    => max( 1, get_query_var( 'paged' ) ),
        'total'      => $wp_query->max_num_pages,
        'prev_next'  => true,
        'end_size'   => 1,
        'mid_size'   => 2,
        'type'       => 'list'
    );

    $args = wp_parse_args( $args, $defaults );

    extract( $args, EXTR_SKIP );

    if ( $total == 1 ) return;

    $paginate_links = apply_filters( 'apiki_paginate_links', paginate_links( array(
        'base'      => $base,
        'format'    => $format,
        'current'   => $current,
        'total'     => $total,
        'prev_next' => $prev_next,
        'end_size'  => $end_size,
        'mid_size'  => $mid_size,
        'type'      => $type
    ) ) );

    echo $paginate_links;
}

Essa função deve residir no arquivo functions.php do tema ativo. Conhecido a função, vamos as suas considerações:

• Quando houver apenas uma página, nada será retornado;
• O parâmetro base é usado como referência da URL, o qual é utilizado para criar os links paginados;
• O parâmetro format define como será o parâmetro de URL que armazenará a página em questão;
• O terceiro parâmetro, total, define quantas páginas teremos;
• Já o quarto parâmetro, current, determina a página em exibição;
• Através do parâmetro show_all posso exibir todos os números ou ocultar alguns e exibir somente os números próximos da página atual;
• Os parâmetros end_size e mid_size trabalham em conjunto com o parâmetro show_all quando esse está com o valor false, o padrão. Eles definem a quantidade de números a serem exibidos nas bordas e quantos ao lado do número da página atual, respectivamente;
• O parâmetro prev_next exibe ou oculta a navegação convencial de “Próximo” e “Anterior”;
• Já os parâmetros prev_text e next_text definem o texto para “Anterior” e “Próximo” respectivamente, desde que o parâmetro prev_next tenha o valor true;
• Com o parâmetro type você define como receber a paginação; através de links separados por uma quebra de linha usando a opção “plain“, o padrão; a opção “array” que retorna um array e assim lhe permite percorrer o resultado e criar a marcação desejada e “list” que retorna uma lista não-ordenada, a tag UL;
• Passando um array ao parâmetro add_args você adiciona parâmetros de URL adicionais aos links da paginação;
• Para finalizar, o parâmetro add_fragment lhe dá a opção de adicionar uma string, por exemplo uma âncora, ao final de cada link.

Minha intenção com este artigo é mostrar a importância em estudar e conhecer o core do WordPress cada vez mais e, assim, evitar plugins que fazem mais do mesmo. Sempre que possível, dê preferência às funções nativas.

Grande abraço!