Guia dos Custom Post Types do WordPress

O que são os custom post types

Por predefinição, a plataforma WordPress inclui dois tipos de conteúdo - artigos (posts do blogue) e páginas. No entanto, a maioria dos sites tem conteúdo que não pertence a nenhum destes tipos. Projetos de portefólio, produtos, análises, eventos, anúncios imobiliários, receitas ou membros da equipa são exemplos de conteúdo que exige uma estrutura e uma apresentação próprias. Os custom post types permitem-lhe criar novos tipos de conteúdo com os seus próprios campos, taxonomias e templates.

Os custom post types são um conceito fundamental no desenvolvimento em WordPress que transforma o WordPress de uma plataforma de blogues num CMS completo (Content Management System). Todos os plugins de WordPress que adicionam um novo tipo de conteúdo, como os produtos do WooCommerce, os eventos do The Events Calendar ou os plugins de Portefólio, utilizam custom post types nos bastidores. Compreender os CPTs dá-lhe controlo total sobre a estrutura de conteúdo do seu site.

Registar um custom post type

A função register_post_type

Um custom post type é registado através da função do WordPress register_post_type, invocada dentro do hook init. A função recebe dois argumentos - um slug, que é o identificador interno do tipo de conteúdo, e um array de argumentos que definem o comportamento e o aspeto no painel de administração. O slug deve estar no singular, em minúsculas, sem espaços e com um máximo de 20 carateres. Por exemplo, para projetos de portefólio o slug seria project, para imóveis property, para receitas recipe.

Argumentos principais

• labels: Um array de etiquetas que o WordPress usa na interface de administração, incluindo name para o plural, singular_name para o singular, add_new para o botão de adicionar, edit_item para o título da página de edição e search_items para a pesquisa.
• public: Indica se o tipo de conteúdo está publicamente disponível no frontend. Defina como true para conteúdo que os visitantes devem ver.
• has_archive: Indica se o tipo de conteúdo tem uma página de arquivo que apresenta todos os itens, à semelhança da página de blogue para os artigos.
• supports: Quais as funcionalidades do WordPress disponíveis para este tipo de conteúdo, incluindo title, editor, thumbnail, excerpt, custom-fields, comments e revisions.
• menu_icon: Um ícone Dashicons apresentado na barra lateral de administração. O WordPress inclui mais de 300 ícones para diferentes finalidades.
• rewrite: Define a estrutura de URL para este tipo de conteúdo. Por exemplo, o slug portfolio cria URLs como oseusite.com/portfolio/nome-do-projeto.
• show_in_rest: Ativa o editor Gutenberg e o acesso à REST API. Defina como true para sites WordPress modernos.

Advanced Custom Fields (ACF)

Porquê usar o ACF

Os custom fields do WordPress são o mecanismo básico para adicionar dados extra ao conteúdo, mas a interface nativa é pouco prática. O plugin Advanced Custom Fields transforma a experiência de criação de conteúdo ao adicionar campos intuitivos como caixa de texto, área de texto, seletor de imagem, seletor de data, campo do Google Maps, campos de relação e muito mais. O ACF é o padrão de facto no desenvolvimento em WordPress, com mais de 2 milhões de instalações ativas, e é utilizado por agências em todo o mundo.

Tipos de campo

O ACF oferece mais de 30 tipos de campo organizados em categorias. Os campos básicos incluem texto, área de texto, número, email, URL e palavra-passe. Os campos de escolha são select, checkbox, radio button, button group e true/false. Os campos de conteúdo são imagem, ficheiro, editor WYSIWYG, oEmbed para vídeo e galeria. Os campos relacionais são link, post object, page link, relationship e taxonomy. Os campos de layout são group, repeater para secções repetidas, flexible content para layouts modulares e clone. O campo repeater é particularmente poderoso porque permite criar estruturas repetidas como uma lista de membros da equipa, secções com ícones ou uma tabela de especificações.

Apresentar os campos do ACF

O ACF fornece funções PHP simples para apresentar os valores dos campos nos temas. A função get_field devolve o valor do campo, enquanto the_field imprime diretamente o valor. Para imagens, get_field devolve um array com URL, largura, altura e texto alternativo. Para os campos repeater, utilize have_rows e the_row num ciclo while para percorrer todas as linhas. Para flexible content, utilize get_row_layout para determinar qual o layout em uso e apresentar o template correspondente. A documentação do ACF é extremamente detalhada, com exemplos para cada tipo de campo.

Taxonomias personalizadas

O que são as taxonomias

As taxonomias são sistemas de classificação de conteúdo. Por predefinição, o WordPress tem duas taxonomias - categorias, que são hierárquicas, e etiquetas, que são planas. Para os custom post types, costumam ser necessárias taxonomias personalizadas. Por exemplo, os projetos de portefólio podem ter uma taxonomia de tipo de projeto com valores como web design, branding e fotografia. Os imóveis podem ter taxonomias para localização, tipo de propriedade e faixa de preço. As receitas podem ter cozinha, tipo de prato e nível de dificuldade.

Registar taxonomias

A função register_taxonomy é invocada dentro do hook init, à semelhança de register_post_type. Recebe três argumentos - o slug da taxonomia, um array dos tipos de conteúdo a que se aplica e um array de argumentos. O argumento hierarchical determina se a taxonomia funciona como as categorias, com uma relação pai-filho, ou como as etiquetas, com uma estrutura plana. As labels definem como a taxonomia é apresentada no painel de administração. O argumento rewrite controla a estrutura de URL das páginas de arquivo da taxonomia.

Taxonomias hierárquicas vs planas

As taxonomias hierárquicas são apresentadas como uma lista de checkboxes no painel de administração, com a possibilidade de criar termos pai e filho. Utilize-as para classificações com uma estrutura clara, como localizações em que Portugal tem as subcategorias Lisboa, Porto e Braga. As taxonomias planas são apresentadas como um campo de introdução de etiquetas onde escreve os termos separados por vírgulas. Utilize-as para etiquetas flexíveis como tecnologias, competências ou caraterísticas, onde não há relação hierárquica.

Ficheiros de template para custom post types

A hierarquia de templates do WordPress

O WordPress utiliza uma hierarquia específica para determinar qual o ficheiro de template usado na apresentação do conteúdo. Para um custom post type com o slug project, o WordPress procura ficheiros pela seguinte ordem. Para itens individuais procura single-project.php, depois single.php, depois singular.php e depois index.php. Para a página de arquivo procura archive-project.php, depois archive.php e depois index.php. Crie ficheiros de template específicos para o seu CPT para ter controlo total sobre a apresentação.

Template single

O template single apresenta um item do seu custom post type. Por exemplo, single-project.php para um projeto de portefólio apresenta o título do projeto, a imagem em destaque, a descrição, campos do ACF como cliente, data, URL do projeto e galeria de imagens. Utilize o ciclo do WordPress the_loop para aceder aos dados do artigo e as funções do ACF para os campos personalizados. Adicione navegação entre projetos com previous_post_link e next_post_link e uma secção de projetos relacionados baseada na taxonomia.

Template de arquivo

O template de arquivo apresenta uma lista de todos os itens com filtragem por taxonomia. Por exemplo, archive-project.php apresenta uma grelha de projetos de portefólio com miniatura, título, categoria e descrição curta. Adicione botões de filtro para as taxonomias para que os visitantes possam filtrar os projetos por tipo. A paginação permite navegar por um grande número de itens. Para uma apresentação avançada, utilize WP_Query com argumentos personalizados para ordenação, filtragem e agrupamento dos itens.

WP_Query para custom post types

Consultas personalizadas

A classe WP_Query permite criar consultas personalizadas para obter itens de custom post types com critérios específicos. O argumento post_type define qual o tipo de conteúdo a obter. posts_per_page controla o número de resultados. orderby e order definem a ordenação por data, título, menu_order ou valor de meta. tax_query filtra por taxonomia, com a possibilidade de combinar várias taxonomias usando os operadores AND ou OR. meta_query filtra pelos valores dos custom fields, com operadores como igual a, maior que, menor que, LIKE e BETWEEN.

Exemplos de consultas

Para apresentar os últimos 6 projetos de portefólio da categoria web design ordenados por data, utilize WP_Query com os argumentos post_type project, posts_per_page 6, tax_query com a taxonomia project_type e o termo web-design. Para apresentar anúncios imobiliários com um preço entre 50.000 e 100.000 euros, utilize meta_query com a chave price, o tipo NUMERIC e o operador BETWEEN. Reponha sempre o objeto global do artigo com wp_reset_postdata após consultas personalizadas, para não quebrar o ciclo principal do WordPress.

REST API e Gutenberg

Acesso à REST API

Com o argumento show_in_rest definido como true, o seu custom post type obtém automaticamente um endpoint da REST API em oseusite.com/wp-json/wp/v2/slug. Isto permite obter, criar, atualizar e eliminar itens através de chamadas à API, que é a base para o acesso headless ao WordPress e para frontends em JavaScript. Os campos do ACF podem ser expostos na REST API através do plugin ACF to REST API ou registando manualmente os campos com a função register_rest_field.

Blocos Gutenberg

Com o show_in_rest ativado, o seu CPT utiliza o editor Gutenberg em vez do editor clássico. Pode criar blocos Gutenberg personalizados específicos para o seu tipo de conteúdo usando os ACF Blocks, que permitem criar blocos com templates PHP e campos do ACF sem necessidade de conhecimentos de React. Por exemplo, para um portefólio pode criar um bloco que apresenta uma grelha de projetos selecionados, ou para receitas um bloco que formata a lista de ingredientes e os passos de preparação com um estilo personalizado.

Boas práticas para custom post types

Nomenclatura e organização

Utilize um prefixo no slug do seu CPT para evitar conflitos com outros plugins e com as atualizações do WordPress. Por exemplo, em vez de project utilize myplugin_project. Agrupe o registo dos CPTs e taxonomias numa classe ou ficheiro separado para facilitar a manutenção. Utilize constantes para os slugs para evitar erros de digitação. Documente cada CPT com uma descrição da sua finalidade, a lista de campos do ACF e as taxonomias.

Desempenho

Cada custom post type acrescenta consultas à base de dados, por isso evite criar demasiados CPTs quando as taxonomias conseguem alcançar o mesmo objetivo. Por exemplo, em vez de CPTs separados para blogue, notícias e tutoriais, utilize artigos padrão com categorias. Os campos do ACF são guardados como post meta na base de dados - para campos frequentemente usados em consultas, considere criar uma tabela personalizada para melhor desempenho. Faça cache de consultas WP_Query complexas usando a transient API para reduzir a carga na base de dados. Nas nossas soluções de alojamento WordPress temos um ambiente otimizado para sites com custom post types e consultas avançadas, com memória PHP suficiente e discos SSD rápidos para uma experiência de administração responsiva.

Conclusão

Os custom post types transformam o WordPress de uma plataforma de blogues num CMS poderoso, capaz de gerir qualquer tipo de conteúdo. A combinação da função register_post_type para criar tipos de conteúdo, do ACF para campos personalizados, das taxonomias personalizadas para a classificação e dos ficheiros de template para a apresentação dá-lhe controlo total sobre a estrutura e a apresentação do conteúdo. Este conhecimento é a base do desenvolvimento profissional em WordPress (comece com o nosso guia) e abre possibilidades para criar sites complexos como apresentações de portefólio, catálogos de produtos, diretórios e aplicações de negócio.