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!