Templates do WordPress | Como funciona a hierarquia

A hierarquia de templates é a espinha dorsal de qualquer tema WordPress. Não existe desenvolver tema sem saber qual arquivo o WordPress carrega, em que ordem e por quê.

Neste artigo mostramos como o WordPress decide qual template incluir, o papel dos parâmetros de URL nesse fluxo, o que acontece com links permanentes habilitados e como funcionam as templates de páginas singulares (post, página estática, tipo de conteúdo personalizado e anexo).

Hierarquia de templates até a versão 4.3. Clique para expandir.

Os parâmetros de URL como controladores

Antes de entrar na hierarquia, é preciso entender o básico do fluxo de requisição. Quando alguém acessa uma página do seu site, o que acontece no servidor?

O WordPress usa os parâmetros de URL como controladores para decidir qual arquivo de template carregar. Parâmetros de URL são as variáveis acrescentadas depois do sinal de interrogação (?) e, quando há mais de um, ficam separadas pelo “e comercial” (&). Em uma instalação nova, o post “Olá Mundo” responde na URL http://seuwp.com?p=1.

O parâmetro p=1 informa ao WordPress que está sendo requisitada a página interna de um post cujo ID é 1. A partir daí o WordPress valida as configurações de leitura definidas na administração, consulta o banco em busca do post com aquele ID e, encontrando o registro, seleciona no tema o arquivo determinado pela hierarquia de templates.

Os parâmetros mais comuns em uma URL WordPress:

• ?p=1 : post com ID 1

• ?page_id=2 : página com ID 2

• ?cat=1 : categoria de posts com ID 1

• ?tag=2 : tag de posts com ID 2

• ?author=1 : autor do site com ID 1

• ?s=teste : busca pelo termo “teste”

• ?m=201508 : posts do mês de agosto/2015

E se o conteúdo requisitado não existir?

Há casos em que o WordPress não encontra no banco o conteúdo apontado pelo parâmetro, seja post, página, tag, categoria ou qualquer outro. Nesse cenário a requisição é identificada como página não encontrada e o fluxo passa a procurar a template de erro 404.

E se o tema não tiver a template que o WordPress procura?

Calma, o WordPress é mais esperto que isso. Para garantir que o usuário nunca veja uma tela em branco, sempre que o tema não possuir a template esperada o WordPress cai no index.php para renderizar o conteúdo. Por isso o index.php é o único arquivo obrigatório da hierarquia. Sem ele, você não tem um tema WordPress.

Hierarquia de templates com links permanentes habilitados

Aí vem a pergunta: e quando o site não expõe parâmetros na URL, porque os links permanentes estão habilitados? O que muda na hierarquia?

Nada. A hierarquia de templates é sempre a mesma. O que ocorre é a tradução da URL amigável para a URL padrão equivalente. A requisição de http://seuwp.com/category/noticias é interpretada internamente como http://seuwp.com?cat=2.

E como o WordPress faz isso?

Ao habilitar os links permanentes, o WordPress grava no banco as regras de reescrita de URL (rewrite rules), consultadas a cada requisição. São elas que convertem a URL amigável em algo interpretável e devolvem o fluxo para a hierarquia de templates descrita acima.

Um trecho das regras de reescrita deste blog:

Array ( [category/(.+?)/feed/(feed|rdf|rss|rss2|atom)/?$] => index.php?category_name=$matches[1]&feed=$matches[2] [category/(.+?)/(feed|rdf|rss|rss2|atom)/?$] => index.php?category_name=$matches[1]&feed=$matches[2] [category/(.+?)/page/?([0-9]{1,})/?$] => index.php?category_name=$matches[1]&paged=$matches[2] [category/(.+?)/?$] => index.php?category_name=$matches[1] [tag/([^/]+)/feed/(feed|rdf|rss|rss2|atom)/?$] => index.php?tag=$matches[1]&feed=$matches[2] [tag/([^/]+)/(feed|rdf|rss|rss2|atom)/?$] => index.php?tag=$matches[1]&feed=$matches[2] [tag/([^/]+)/page/?([0-9]{1,})/?$] => index.php?tag=$matches[1]&paged=$matches[2] [tag/([^/]+)/?$] => index.php?tag=$matches[1] [author/([^/]+)/feed/(feed|rdf|rss|rss2|atom)/?$] => index.php?author_name=$matches[1]&feed=$matches[2] [author/([^/]+)/(feed|rdf|rss|rss2|atom)/?$] => index.php?author_name=$matches[1]&feed=$matches[2] [author/([^/]+)/page/?([0-9]{1,})/?$] => index.php?author_name=$matches[1]&paged=$matches[2] [author/([^/]+)/?$] => index.php?author_name=$matches[1] )

As páginas singulares dentro da hierarquia

Resolvido o roteamento, vamos ao grupo de templates que mais aparece no dia a dia: as singulares. Elas entram em cena sempre que a URL requisitada é a de um único conteúdo (um post, uma página estática, um item de tipo de conteúdo personalizado ou um anexo). Este artigo que você está lendo, por exemplo, é renderizado por uma template singular de post.

Singular de posts

Na hierarquia, um post padrão é tratado como blog post. Olhando o diagrama acima, existem três caminhos possíveis dentro do tema.

• singular.php: a mais genérica. Serve quando a interna de post e a interna de página compartilham o mesmo layout.

• single.php: ainda genérica, cobre posts e tipos de conteúdo personalizado. É a mais usada na prática.

• single-post.php: a mais específica. Use quando a interna de post precisa divergir da interna dos demais tipos de conteúdo.

Singular de páginas estáticas

Páginas estáticas são os conteúdos criados no menu Páginas da administração. Além da singular.php, a template genérica para esse caso é a page.php.

Dá para ser mais específico usando o ID ou o slug: uma página com título “Produtos”, slug produtos e ID 28 pode ser renderizada por page-28.php ou page-produtos.php.

Só que amarrar template a ID é problema garantido. O ID de uma página não é o mesmo entre local, homologação e produção, então o arquivo simplesmente deixa de ser aplicado quando o conteúdo muda de ambiente. Em operação com múltiplos editores e deploys frequentes, isso vira chamado.

O caminho que recomendamos é a template customizada de página. Crie um arquivo com o nome que quiser no tema e declare o nome da template em um comentário PHP na primeira linha:

<?php /** * Template Name: Produtos */

Feito isso, o modelo aparece no metabox Atributos de Página ao criar ou editar uma página na administração. O editor escolhe o layout sem abrir chamado para o time de desenvolvimento, e o arquivo pode ficar organizado em uma subpasta dentro do tema. Menos acoplamento, menos fila.

Singular de tipos de posts personalizados

Além de singular.php e single.php, um custom post type (CPT) aceita template nomeada pelo próprio slug do tipo. Um CPT com slug apiki-produtos é renderizado por single-apiki-produtos.php. O slug considerado é o primeiro parâmetro informado na função register_post_type.

Singular de anexos

Todo arquivo enviado pela biblioteca de mídia vira um post no banco. Logo, também tem página singular e lugar na hierarquia. Clique na imagem do diagrama no início deste artigo e você cai justamente nessa template.

Aqui valem singular.php e single.php, mais a attachment.php, que atende todos os tipos de anexo. Dá para especializar por tipo MIME, com image.php para imagens ou video.php para vídeos, e descer ainda mais no subtipo: um arquivo text/plain pode ser exibido por text.php, plain.php ou text_plain.php.

Por que isso importa fora do editor de código

Hierarquia de templates não é assunto só de dev. É o que define se um novo formato de página nasce como configuração de tema ou como demanda de desenvolvimento.

Tema que resolve tudo com single.php e page.php genéricos joga toda variação de layout para a fila da TI. Tema com templates customizadas nomeadas e CPTs bem estruturados devolve autonomia para quem publica. Não é estética. É arquitetura de entrega.

Fechou!

Recapitulando o fluxo: a URL vira parâmetro (por reescrita, quando há links permanentes), o parâmetro define o tipo de requisição, o tipo aponta para uma cadeia de arquivos candidatos no tema, e o WordPress carrega o primeiro que existir. Não existindo nenhum, index.php assume.

O assunto é extenso e não termina aqui. Seguimos detalhando os demais arquivos da hierarquia em outros artigos do blog.

Quer uma leitura do seu tema e da operação de publicação do seu WordPress? Fale com nosso time.