Tudo o que você precisa saber sobre a função get_template_part() do WordPress

Certa vez li que a melhor maneira de aprender programação é lendo o código que outros escreveram. Afinal, a maior parte do tempo que você gasta como desenvolvedor provavelmente estará revisando, aprimorando e corrigindo o código que você ou outro desenvolvedor escreveu no passado. É exatamente por isso que gosto tanto de software livre e de código aberto: ele nos dá acesso ao código-fonte de ótimas ferramentas e possibilita aprender com elas.

Se você está interessado no mundo WordPress (e imagino que esteja, porque você está aqui), o código-fonte do WordPress Core ou o de Gutenberg são duas maneiras muito boas de se tornar um profissional WordPress melhor e aprender sobre desenvolvimento de back-end e front-end.

Desde o primeiro lançamento de Gutenberg, compartilhamos tudo o que aprendemos sobre desenvolvimento de front-end até agora. Assim, por exemplo, fizemos uma série de posts onde ensinamos o básico do React, vimos como reutilizar componentes, explicamos como estender o Gutenberg e discutimos novidades sobre JavaScript para escrever melhor código-fonte, para citar alguns artigos nós escrevemos.

Bem, hoje vamos mudar de marcha e focar no WordPress Core novamente. Por quê? Não sei, talvez porque o anúncio do próximo tema Twenty Twenty-One que saiu há alguns dias seja a desculpa perfeita para fazê-lo?. Então vamos falar sobre um dos elementos mais importantes na hora de criar temas no WordPress: a função get_template_part .

Temas do WordPress

Antes de tudo, vamos revisar como os temas do WordPress funcionam, certo? Essencialmente, um tema é uma coleção de arquivos que define a estrutura HTML e os estilos CSS que nosso site usará.

Se você pensar no esqueleto de qualquer página da web, verá que o mesmo padrão sempre se repete:

• Começamos abrindo as tags html e head . É onde adicionamos scripts, estilos, meta tags e assim por diante.
• Em seguida, fechamos a tag head e abrimos a tag body , que conterá o conteúdo visível do nosso site.
  • Normalmente, o corpo de uma página inclui um cabeçalho com o logotipo da web, um menu, etc.
  • Em seguida, vem o conteúdo em si, que pode ser uma página, um artigo de blog, uma lista de posts, o resultado de uma pesquisa e assim por diante.
  • Por fim, geralmente termina com um rodapé.
• Finalmente, uma vez que toda a página foi renderizada, fechamos todas as tags e pronto.

Então, sim, parece que toda página da web segue mais ou menos uma estrutura semelhante: há uma parte comum (ou seja, cabeçalho, menu, rodapé…) e uma área específica de conteúdo (um post de blog, o conjunto de resultados que obtivemos após uma pesquisa , um produto WooCommerce, etc).

Como os programadores não gostam de repetir código e nós somos (em geral) pessoas organizadas, os temas do WordPress seguem uma estrutura de arquivos muito padronizada. Neste post que escrevi há alguns meses, você tem uma boa explicação sobre os diferentes arquivos em um tema, mas lembre-se de que existem:

• uma folha de estilo: style.css ,
• um arquivo header.php para “abrir” a página web (ou seja, gerar a tag head e, normalmente, a parte inicial do body que é comum a todas as páginas),
• outro arquivo footer.php que “fecha” a página (ou seja, adiciona o rodapé e fecha a tag html ), e
• muitos arquivos adicionais para os diferentes tipos de conteúdo que queremos renderizar.

O que é a função get_template_part e para que serve?

A primeira coisa a fazer quando você se depara com um novo recurso é o oposto do que você faz quando seu pai lhe pede para ajudá-lo a programar seu novo limpador Roomba: leia a documentação . Então vamos fazer isso com nossa função olhando o Codex:

get_template_part fornece um mecanismo simples para que temas filho sobrecarreguem seções reutilizáveis ​​de código no tema.

Inclui a parte de modelo nomeada para um tema ou, se um nome for especificado, uma parte especializada será incluída. Se o tema não contiver nenhum arquivo {slug}.php, nenhum modelo será incluído.

O modelo é incluído usando require, não require_once, portanto, você pode incluir a mesma parte do modelo várias vezes.

Para o parâmetro $name, se o arquivo for chamado “{slug}-special.php” então especifique “special”.

Nota: get_template_part() falha silenciosamente

documentos get_template_part em WordPress.org

Ver? Em menos de um minuto, obtivemos todas as informações de que precisávamos. Agora sabemos que esta função é usada para criar “partes reutilizáveis” em um tema (evitando assim a duplicação de código) e o faz de forma que um tema filho possa adaptá-las. Também temos informações sobre seus parâmetros, seu funcionamento interno (ele usa a função require do PHP) e o que podemos esperar dele (ele “falha silenciosamente”).

Infelizmente, existem algumas coisas que ainda não estão claras, como esses arquivos {slug}.php e {slug}-special.php que ele menciona. O que eles são? O que eles contêm? O que eles fazem? Muitas perguntas difíceis de responder olhando apenas a documentação, então é hora de pular para os exemplos.

Como criar templates parciais em nosso tema

Vamos dar uma olhada no tema Twenty Twenty-One para descobrir se ele usa esses “modelos parciais” e, se usar, como eles se parecem e o que você deve fazer para implementá-los em seu próprio tema.

Se você ler meu post sobre a hierarquia de arquivos de um tema WordPress, saberá que “ index.php é o modelo padrão para nosso tema. Ele é usado para renderizar qualquer conteúdo em nosso site, desde que esse conteúdo não tenha um modelo específico projetado para isso.” Como este é um modelo padrão, acho que é uma boa ideia começar por aí. Este é o conteúdo do index.php no tema Twenty Twenty-One:

 get_header(); if ( have_posts() ) { // Load posts loop. while ( have_posts() ) { the_post(); get_template_part( 'template-parts/content/content' ); } // Previous/next page navigation. twenty_twenty_one_the_posts_navigation(); } else { // If no content, include the "No posts found" template. get_template_part( 'template-parts/content/content-none' ); } get_footer();

Como você pode ver, temos todas as partes que comentamos anteriormente:

• Inclui o cabeçalho usando get_header .
• Ele renderiza o próprio conteúdo.
• Ele fecha a página com get_footer .

O interessante aqui, obviamente, é a área de “conteúdo” no index.php . Especificamente, vemos que temos um pequeno controle para saber se estamos vendo algum conteúdo válido ou não ( função have_posts do Loop do WordPress) e, dependendo se temos ou não, carregamos um template parcial ( …/content ) ou outro ( …/content-none ).

Se agora dermos uma olhada no template parcial content.php , veremos aproximadamente o seguinte:

 <article <?php post_class(); ?>> <header class="entry-header alignwide"> … the_title( … ); … </header> <div class="entry-content"> <?php the_content( … ); wp_link_pages( … ); ?> </div> <footer class="entry-footer default-max-width"> <?php twenty_twenty_one_entry_meta_footer(); ?> </footer> … </article>

Bem direto, não é? Tudo o que temos é um pequeno modelo projetado para renderizar conteúdo genérico do WordPress, como, por exemplo, um post de blog. Observe que o esqueleto HTML resultante nada mais é do que uma tag de article com um título, seu conteúdo e um rodapé, todos usando tags de modelo do WordPress para extrair o conteúdo real.

Por que a API do WordPress é incrível

Mesmo que você não soubesse que todas essas funções existem ( get_header , get_footer ou today's star: get_template_part ), tenho certeza de que você teria organizado seu código seguindo uma abordagem semelhante. Afinal, parece bastante lógico criar um template para o cabeçalho, outro para o rodapé, outro para o conteúdo… e depois ter um arquivo especial ou algo que grude tudo junto, certo?

Se você seguiu essa abordagem, aposto que seu arquivo index.php seria algo assim:

 require_once 'header.php'; if ( have_posts() ) { // Load posts loop. while ( have_posts() ) { the_post(); require 'template-parts/content.php'; } // Previous/next page navigation. twenty_twenty_one_the_posts_navigation(); } else { // If no content, include the "No posts found" template. require 'template-parts/content-none.php'; } require_once 'footer.php';

que é muito semelhante ao que temos no tema Twenty Twenty-One. Então, neste ponto, você pode se perguntar: o que eu ganho usando funções específicas do WordPress? Não é o mesmo usar diretamente um PHP require , especialmente considerando que, de acordo com a documentação do WordPress, é exatamente isso que essas funções auxiliares usam?

Bem, o principal motivo é mencionado na própria documentação: facilita a criação do tema filho. Assim, se você estiver criando um tema filho e usar get_template_part , o WordPress procurará o modelo no filho e, se não estiver, usará o do pai.

Mas isso não é tudo! As funções do WordPress costumam estar repletas de filtros e ações que permitem adaptar o resultado final. Por exemplo, se observarmos a função interna get_template_part no arquivo wp-includes/general-template.php :

 function get_template_part( … ) { do_action( "get_template_part_{$slug}", … ); … do_action( 'get_template_part', … ); if ( ! locate_template( … ) ) { return false; } }

veremos que temos algumas ações que os plugins e o próprio tema podem alavancar. E se continuarmos puxando o tópico, poderemos até ver como o WordPress localiza ( locate_template ) e carrega o modelo que ele acabará usando:

 function locate_template( $template_names, … ) { $located = ''; foreach ( $template_names as $name ) { if ( file_exists( STYLESHEETPATH . "/$name" ) ) { $located = …; // in child theme break; } else if ( file_exists( STYLESHEETPATH . "/$name" ) ) { $located = …; // in parent theme break; } else { … } } if ( $located ) { load_template( $located, $require_once, $args ); } return $located; }

Espero que o post de hoje tenha ajudado você a entender um pouco melhor como os temas do WordPress funcionam. Também espero que tenha mostrado como aprender sobre o WordPress lendo sua documentação e navegando em seu código-fonte. E se você gostou, compartilhe com seus amigos e deixe-nos um comentário.

Imagem em destaque de Joshua Sortino no Unsplash.