Tópico 5 — Tema e Hierarquia de Templates | Guia Técnico WordPress, Banco de Dados e Next.js

1. O que é um Tema

O tema define a camada visual do WordPress, controlando o layout, estilos, scripts e como o conteúdo é renderizado. Ele traduz os dados vindos do banco de dados em HTML e CSS.

Objetivo aprender como os arquivos do tema se relacionam, entender a hierarquia de templates e criar componentes reutilizáveis e organizados.

2. Estrutura de um Tema

Arquivos principais

meu-tema/
├── style.css           # Metadados e estilo principal
├── functions.php       # Configurações e hooks
├── index.php           # Template base
├── header.php          # Cabeçalho global
├── footer.php          # Rodapé global
├── sidebar.php         # Barra lateral (opcional)
├── single.php          # Exibição de posts individuais
├── page.php            # Exibição de páginas
├── archive.php         # Listas de posts
├── 404.php             # Página de erro
└── template-parts/     # Componentes (cards, banners, etc.)

Dica Sempre mantenha uma estrutura limpa. Evite misturar lógica PHP complexa no HTML — prefira funções auxiliares em functions.php.

3. Hierarquia de Templates

Quando o WordPress processa uma página, ele identifica o tipo de conteúdo e seleciona o template correspondente, seguindo uma ordem de prioridade.

Ordem de prioridade

single-{post_type}.php → single.php → singular.php → index.php
page-{slug|id}.php → page.php → singular.php → index.php
category.php → archive.php → index.php
tag.php → archive.php → index.php
taxonomy.php → archive.php → index.php
search.php → index.php
404.php → index.php

O arquivo index.php é obrigatório e serve como fallback para qualquer tipo de conteúdo.

3.1. Visualização da Hierarquia

As imagens a seguir ilustram de forma visual como o WordPress decide qual template usar. Clique nas imagens para abrir em tamanho completo em nova janela:

Hierarquia de Templates - Versão Desktop Dark

Identificação de Tipo de Página no WordPress

4. O Loop Principal

O Loop é o núcleo do tema — ele percorre os posts retornados pela query principal e renderiza seu conteúdo. Todo template que exibe posts usa o Loop.

Loop padrão

<?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>
  <article>
    <h1><?php the_title(); ?></h1>
    <div class="content"><?php the_content(); ?></div>
  </article>
<?php endwhile; else : ?>
  <p>Nenhum conteúdo encontrado.</p>
<?php endif; ?>

Boas práticas use the_excerpt() em listas e the_content() em páginas completas. Sempre valide se há posts antes do loop.

5. Componentes Reutilizáveis

É comum separar partes do layout em pequenos arquivos dentro da pasta template-parts. Isso facilita a manutenção e evita repetição de código.

template-parts/content-card.php

<article class="card">
  <h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
  <p><?php the_excerpt(); ?></p>
</article>

Usando o componente em index.php

<?php
if ( have_posts() ) :
  while ( have_posts() ) : the_post();
    get_template_part('template-parts/content', 'card');
  endwhile;
endif;
?>

6. Enfileirando Scripts e Estilos

Os arquivos CSS e JS devem ser registrados com as funções wp_enqueue_style() e wp_enqueue_script(), garantindo carregamento otimizado e sem conflitos.

functions.php — enfileiramento correto

add_action('wp_enqueue_scripts', function(){
  wp_enqueue_style('main', get_stylesheet_uri(), [], '1.0');
  wp_enqueue_script('main-js', get_template_directory_uri().'/assets/js/main.js', [], '1.0', true);
});

Evite adicionar tags <script> e <link> diretamente em header.php. Isso quebra o controle de dependências do WordPress.

7. Boas Práticas em Desenvolvimento de Temas

Use get_template_part() para organizar componentes.
Padronize nomes de arquivos e classes CSS.
Evite lógica de negócio no tema — use plugins para isso.
Separe estilos e scripts por responsabilidade (página, layout, componente).
Valide HTML e CSS com ferramentas automáticas.

Resultado Um tema modular, escalável e fácil de manter.