Modelos de arquivo personalizados: um breve guia

Sempre que você estiver trabalhando com modelos de arquivo no WordPress, as postagens geralmente são listadas por data em ordem decrescente. Ou seja, as postagens mais recentes são listadas no topo e, a partir daí, segue.

Ultimamente, tenho trabalhado em alguns projetos que se integram com APIs de terceiros. Essas APIs retornam datas – às vezes duas datas, uma data de início e uma data de término – para um determinado evento e os clientes desejam usar essas informações para listar postagens em vez da data da postagem. Ou seja, eles querem modelos de arquivo personalizados.

Não é muito difícil fazer isso, mas antes de fazer isso, acho importante fornecer algumas informações básicas sobre como o projeto é construído para que haja um pouco mais de contexto sobre por que, digamos, uma consulta personalizada é necessária e por que você pode ou pode não precisa olhar em pre_get_posts.

Vou começar com um TL;DR primeiro, no entanto. Dessa forma, você pode ter a ideia antes de ler a coisa toda.

Modelos de arquivo personalizados

Então o TL;DR por trás da coisa toda é isso:

• as informações de data fornecidas pela API de terceiros são mantidas na tabela de metadados post,
• a chave é a data de início e o valor é a data real,
• Ordeno o conteúdo em ordem decrescente e pelo valor meta.

A paginação pode ser um problema e, se você usar um tipo de postagem personalizado, precisará de alguns parâmetros extras, mas essa é a ideia geral.

Agora para toda a configuração.

Tipos de postagem personalizados

Quando se trata de interface com APIs de terceiros, sou um grande fã de tipos de postagem personalizados porque costumo pensar neles como um híbrido entre modelos e visualizações.

• O componente de modelo inclui qualquer coisa que seja tangencialmente relacionada e possa ser gravada no banco de dados. Isso significa qualquer informação de taxonomia ou meta-dados de postagem.
• O componente de visualização geralmente é qualquer coisa que vá para o modelo que possa alavancar quaisquer tags de modelo pré-existentes, ou qualquer coisa que precise ser criada e que também leia informações do banco de dados.

Para este post, vou usar acme-event como o tipo de post personalizado.

Postar metadados

Eu defino as datas nos metadados do post e não no post em si, porque se algo acontecer no futuro e os dados forem definidos no próprio registro do post, o WordPress o tratará como um post agendado que não foi publicado .

Em vez disso, prefiro publicar a postagem e alterar a maneira como os metadados são exibidos no modelo.

Paginação

O WordPress faz uma distinção sutil com a paginação em sua base de código. Ou seja, a variável de consulta para sites sem uma página inicial estática usa paged e o caso oposto usa page.

Isso é importante quando você está construindo os argumentos para a consulta que vou abordar momentaneamente.

Arquivar apenas páginas

Lembre-se de que sempre que estiver introduzindo a paginação, você só deseja alterar a consulta sempre que estiver na página de arquivo real.

Isso significa que você não se importa com casos em que está na área administrativa do WordPress e não deseja alterar a consulta para arquivos não personalizados do tipo post. Para esse fim, você deve certificar-se de que está configurando a variável de consulta corretamente no retorno de chamada pre_get_posts.

Observe que posso mostrar uma função de como fazer isso, mas por causa de como escrevemos código no WordPress – ou seja, alguns escrevem código procedural, outros escrevem código orientado a objetos – vou simplesmente exibi-lo em código procedural.

Juntando tudo

Primeiro, vou construir a consulta:

<?php

$eventQuery = new WP_Query([
    'post_type' => 'acme-events',
    'post_status' => 'publish',
    'orderby' => 'meta_value',
    'order' => 'desc',
    'meta_key' => 'acme-event-start-date-time',
    'posts_per_archive_page' => 5,
    'paged' => get_query_var('paged')? get_query_var('paged'): 1
]);

Observe que no código acima há um argumento para paged. Vou falar sobre o código para isso momentaneamente.

Em seguida, o modelo incluirá todas as informações que você optar por exibir. Estou optando por não compartilhar o código do meu modelo neste post porque é irrelevante para a ideia maior em questão.

Além disso, você tem tudo o que precisa para exibir o conteúdo.

Em seguida, definirei a paginação. Primeiro, preciso fazer isso usando o gancho pre_get_posts para garantir que a variável de consulta adequada esteja definida :

<?php

add_action('pre_get_posts', 'setCustomQueryVariable');
public function setCustomQueryVariable($query)
{
    if (is_admin() || !is_archive()) {
        return;
    }

    if ($query->is_archive('acme-events')) {
        set_query_var('posts_per_page', 5);
    }
}

Em seguida, implementarei a paginação usando a consulta personalizada:

<?php

<a class="next page-numbers" href="<?php echo esc_attr(get_next_posts_page_link($eventQuery->max_num_pages)); ?>">
    Next Page
</a>

<a class="prev page-numbers" href="<?php echo esc_attr(get_previous_posts_page_link()); ?>">
    Previous Page
</a>

E depois disso, vou redefinir a variável global $post usando wp_reset_postdata() caso alguma coisa da postagem original precise ser usada.

<?php wp_reset_postdata(); ?>

Isso geralmente é considerado uma boa limpeza sempre que você usa uma consulta personalizada.

Links Úteis

Abaixo está uma lista de funções, páginas e referências que você pode achar úteis no que se refere ao código acima ou a qualquer trabalho futuro que você possa fazer.

• WP_Query
• Paginação
• pre_get_posts
• get_query_var
• set_query_var
• get_next_posts_page_link
• get_previous_posts_page_link
• update_post_meta
• wp_reset_postdata
• O código completo neste post.

Se você trabalha com o WordPress há muito tempo, alguns deles podem parecer redundantes. Em outros casos, pode parecer novo ou pode esclarecer áreas das APIs do WordPress que você não sabia que existiam (pelo menos foi o meu caso).

Por que se incomodar com tudo isso?

Isso pode parecer um post longo para uma tarefa aparentemente simples, mas as informações estão um pouco espalhadas por toda a web no que se refere a fazer algo assim.

Então eu queria tentar juntar tudo isso com explicações, código de exemplo e links para páginas que podem ser de interesse dependendo de como a implementação é feita.

Afinal, muitos de nós estão usando o WordPress além do gerenciamento básico de conteúdo neste momento, mas isso não significa que não devemos aproveitar suas funções e APIs integradas quando possível.