Os campos padrão do WordPress são suficientes até ao seu primeiro projeto personalizado. No momento em que precisa de mostrar especificações de produto num cartão, adicionar uma galeria a uma página ou anexar um bloco de condições de envio, atinge as limitações do editor: título, texto, categorias e pouco mais.

Existe uma solução, e não é o ACF Pro a $149 por ano. As caixas de meta personalizadas adicionam campos arbitrários diretamente à interface de edição de artigos, sem um construtor visual e sem uma dúzia de módulos desnecessários. O CMB2 faz exatamente isso: fornece uma API PHP para descrever caixas de meta em código que reside no controlo de versões, e não na base de dados.

Abaixo encontra o fluxo de trabalho completo: desde a instalação do plugin até à exibição dos dados no frontend. No final deste artigo, terá um ficheiro de caixa de meta funcional que se adapta a qualquer tipo de conteúdo, desde páginas a produtos do WooCommerce.

💡 Visão geral rápida:

• Instale o CMB2 a partir do diretório do WordPress.org: o plugin é gratuito e instala-se em dois cliques.
• Crie um ficheiro metaboxes.php na pasta do seu tema e descreva os campos necessários através do hook cmb2_admin_init.
• Inclua o ficheiro no functions.php com uma única linha require_once e verifique a caixa de meta no painel de administração.
• Exiba os dados guardados no frontend através de get_post_meta() com o escape adequado.

O que é o CMB2: código em vez de um construtor visual

O CMB2 é uma biblioteca para programadores que cria caixas de meta, campos personalizados e formulários no WordPress. De raiz, suporta dezenas de tipos de campo: texto, editor WYSIWYG, upload de ficheiros, seletor de data, seletor de cor, botões de rádio, listas suspensas, repetidores e grupos.

A principal diferença em relação ao ACF: o CMB2 não tem construtor visual. Todas as caixas de meta são descritas em ficheiros PHP dentro do seu tema. Para os programadores, isto é uma vantagem: a configuração reside no Git, não pode ser eliminada acidentalmente através do painel de administração e a migração entre staging e produção resume-se à implementação de código. Ao mesmo tempo, o CMB2 é completamente gratuito, enquanto o ACF Pro lhe custará cerca de $149 por ano para campos repetíveis e grupos.

A biblioteca tem sido ativamente mantida desde 2014. No WordPress.org, o plugin tem uma classificação de 5 estrelas e mais de 300.000 instalações ativas. O repositório no GitHub recebe atualizações regulares: a versão mais recente abordou a compatibilidade com o PHP 8.4 e o WordPress 6.7. Este não é um projeto abandonado que será descontinuado em seis meses.

Passo 1: Instalar o plugin

Vá a Plugins → Adicionar Novo, escreva "CMB2" na caixa de pesquisa e clique em "Instalar". Após a ativação, o plugin carrega o seu motor, mas não altera nada no painel de administração por si só: as caixas de meta só aparecerão depois de as descrever em código.

Se estiver a incluir o CMB2 manualmente dentro do seu tema sem o instalar através do painel de administração, adicione o seguinte ao início do functions.php:

1
require_once __DIR__ . '/cmb2/init.php';

Dois pontos importantes. Primeiro: o init.php deve ser carregado o mais cedo possível, fora de quaisquer hooks. Não o envolva em verificações if ( ! class_exists(...; o CMB2 trata dos conflitos de carregamento duplicado por si próprio. Segundo: com a inclusão manual, terá de atualizar o CMB2 manualmente, ao contrário das atualizações automáticas através do painel de administração.

Passo 2: Escrever o ficheiro da caixa de meta

Crie uma pasta cmb2-metaboxes na raiz do seu tema filho e um ficheiro metaboxes.php dentro dela. Este ficheiro conterá todas as suas definições de campos.

Abaixo está o código funcional que adiciona um editor de texto, uma descrição curta e um seletor de distintivo aos produtos do WooCommerce. Copie-o para o metaboxes.php:

1
add_action( 'cmb2_admin_init', 'sdstudio_register_metaboxes' );
2
 
3
function sdstudio_register_metaboxes() {
4
 
5
    $prefix = '_sdstudio_';
6
 
7
    $cmb = new_cmb2_box( array(
8
        'id'           => 'product_extra_info',
9
        'title'        => __( 'Дополнительная информация о товаре', 'cmb2' ),
10
        'object_types' => array( 'product' ),
11
        'context'      => 'normal',
12
        'priority'     => 'high',
13
        'show_names'   => true,
14
    ) );
15
 
16
    $cmb->add_field( array(
17
        'name'    => __( 'Описание для карусели на главной', 'cmb2' ),
18
        'desc'    => __( 'Текст, который будет показан в слайдере товаров.', 'cmb2' ),
19
        'id'      => $prefix . 'carousel_desc',
20
        'type'    => 'wysiwyg',
21
        'options' => array(
22
            'textarea_rows' => 5,
23
        ),
24
    ) );
25
 
26
    $cmb->add_field( array(
27
        'name' => __( 'Короткое описание', 'cmb2' ),
28
        'desc' => __( 'Одна строка — для карточки товара в сетке.', 'cmb2' ),
29
        'id'   => $prefix . 'short_desc',
30
        'type' => 'textarea_small',
31
    ) );
32
 
33
    $cmb->add_field( array(
34
        'name' => __( 'Бейдж товара', 'cmb2' ),
35
        'desc' => __( 'Метка «Новинка», «Хит» или «Распродажа».', 'cmb2' ),
36
        'id'   => $prefix . 'badge',
37
        'type' => 'select',
38
        'show_option_none' => true,
39
        'options'          => array(
40
            'new'   => __( 'Новинка', 'cmb2' ),
41
            'hit'   => __( 'Хит', 'cmb2' ),
42
            'sale'  => __( 'Распродажа', 'cmb2' ),
43
        ),
44
    ) );
45
 
46
}

O que está a acontecer aqui: o hook cmb2_admin_init é acionado quando o painel de administração carrega e regista a caixa de meta na página de edição do produto. new_cmb2_box() cria um contentor com o título "Informação adicional do produto" e três chamadas add_field() adicionam-lhe campos: um editor WYSIWYG, um campo de texto compacto e uma lista suspensa com opções predefinidas. Cada campo recebe um id único com o prefixo _sdstudio_ para evitar conflitos com outros plugins.

Se precisar de páginas normais em vez do WooCommerce, substitua 'object_types' => array( 'product' ) por 'object_types' => array( 'page' ). Para vários tipos de conteúdo, liste-os: array( 'page', 'post' ).

Para obter a lista completa de tipos de campo, consulte a documentação oficial do CMB2 no GitHub. Estão disponíveis dezenas de opções de raiz: desde editores de texto simples e WYSIWYG a uploads de ficheiros, seletores de cor, botões de rádio e taxonomias. Escolha o tipo certo para a sua tarefa específica com base na documentação, não em suposições.

Passo 3: Incluí-lo no functions.php

Agora precisa de carregar o ficheiro que criou. Abra o functions.php no seu tema filho e adicione uma única linha antes da tag de fecho ?>, ou no final do ficheiro se não houver tag de fecho:

1
require_once __DIR__ . '/cmb2-metaboxes/metaboxes.php';

Antes de adicionar o código, faça uma cópia de segurança do functions.php. Um erro de sintaxe no require_once fará o site ir abaixo com um erro fatal de PHP, e só conseguirá restaurar o ficheiro via FTP ou através do painel de alojamento. Depois de guardar, abra qualquer produto no painel de administração e verifique se a caixa de meta "Informação adicional do produto" aparece abaixo do editor de conteúdo.

Preencha os campos de teste e clique em "Atualizar". O CMB2 guarda automaticamente os dados na tabela wp_postmeta. Não são necessárias chamadas adicionais ao hook save_post: a biblioteca interceta a gravação do artigo e processa os seus campos por si própria.

Passo 4: Exibir os dados no frontend

Os dados estão guardados na base de dados; agora precisa de os mostrar aos visitantes. Abra o ficheiro do tema responsável pela página de produto, normalmente single-product.php ou content-single-product.php. Adicione o código dentro do ciclo do WordPress:

1
<?php
2
$carousel_desc = get_post_meta( get_the_ID(), '_sdstudio_carousel_desc', true );
3
$badge         = get_post_meta( get_the_ID(), '_sdstudio_badge', true );
4
 
5
if ( ! empty( $carousel_desc ) ) : ?>
6
    <div class="product-carousel-desc">
7
        <?php echo wp_kses_post( $carousel_desc ); ?>
8
    </div>
9
<?php endif; ?>
10
 
11
<?php if ( ! empty( $badge ) ) : ?>
12
    <span class="product-badge product-badge--<?php echo esc_attr( $badge ); ?>">
13
        <?php echo esc_html( $badge ); ?>
14
    </span>
15
<?php endif; ?>
16

Análise: get_post_meta() recupera o valor pelo ID do campo. Para um campo WYSIWYG, use wp_kses_post(), que permite tags HTML permitidas e filtra as potencialmente perigosas. Para texto simples ou um campo de seleção, esc_html() é suficiente: converte caracteres especiais em entidades HTML e previne XSS.

Se a caixa de meta for criada para páginas ('object_types' => array( 'page' )), coloque este mesmo código em page.php ou content-page.php. A mecânica é a mesma: get_post_meta() dentro do ciclo, escape com base no tipo de campo.

Vídeo: CMB2 da instalação a uma caixa de meta funcional

Neste tutorial de 20 minutos, o autor percorre o fluxo de trabalho completo: instalação, criação de campos, inclusão de ficheiros e exibição de dados no frontend. Útil para ver se as instruções em texto deixaram lacunas.

⁉️🤔 Perguntas frequentes

Em que é que o CMB2 difere do ACF?

O ACF fornece um construtor visual de campos diretamente no painel de administração: pode montar uma caixa de meta sem escrever uma única linha de código. O CMB2 requer a descrição dos campos em ficheiros PHP dentro do seu tema. Para programadores que armazenam a configuração no Git, o CMB2 é mais conveniente: as caixas de meta não dependem do estado da base de dados, não podem ser eliminadas acidentalmente através do painel de administração e a migração entre staging e produção resume-se à implementação de código. O ACF Pro custa a partir de $149 por ano para campos repetíveis e grupos; o CMB2 é gratuito.

O CMB2 pode ser usado sem instalar o plugin?

Sim. Copie a pasta do CMB2 para dentro do seu tema e inclua o init.php no functions.php, como mostrado no passo 1. Esta abordagem é conveniente para temas premium que devem funcionar imediatamente após a ativação, sem exigir que o utilizador instale um plugin de terceiros. A desvantagem: terá de atualizar o CMB2 manualmente a cada nova versão.

Os campos do CMB2 funcionam no editor Gutenberg?

Sim, as caixas de meta do CMB2 são exibidas abaixo do editor Gutenberg da forma habitual, na secção abaixo do conteúdo. No entanto, de raiz, não se integram nos blocos do editor. Se precisar de incorporar um campo diretamente num bloco, será necessário desenvolvimento adicional através da API do CMB2 e do register_block_type().

O que devo fazer se a caixa de meta não aparecer no painel de administração?

Verifique três coisas. Primeiro: o object_types corresponde ao tipo de artigo que está a ser editado? Para produtos do WooCommerce, precisa de 'product', não 'post'. Segundo: existe um erro de sintaxe PHP? Ative o WP_DEBUG no wp-config.php e verifique o log. Terceiro: o prefixo do id do campo está em conflito com outro plugin? Use um prefixo único como _sdstudio_.

Posso criar grupos de campos repetíveis?

Sim. O CMB2 suporta campos repetíveis através da flag 'repeatable' => true e grupos repetíveis através de $cmb->add_group_field(). Um grupo permite-lhe adicionar um bloco "Característica: valor" e criar novas instâncias com um botão "Adicionar linha" diretamente no painel de administração.

O CMB2 funciona com multisite?

Sim, o plugin é totalmente compatível com o WordPress Multisite. As caixas de meta podem ser registadas globalmente no functions.php do tema de rede ativo ou individualmente para cada site. A chamada get_post_meta() funciona da mesma forma em ambos os modos.

CMB2 ou ACF: que abordagem escolher para a sua tarefa

O CMB2 resolve exatamente uma tarefa: criar caixas de meta personalizadas através de código, com a configuração armazenada em ficheiros de tema e não na base de dados. A escolha resume-se ao seu fluxo de trabalho, não a um abstrato "qual é o melhor".

• Se é um programador e armazena toda a configuração do projeto no Git, opte pelo CMB2. As caixas de meta residem no metaboxes.php, são implementadas com o seu tema e não requerem sincronização da base de dados entre staging e produção.

• Se precisa de um construtor visual, campos flexíveis repetíveis e blocos Gutenberg prontos a usar sem escrever código, opte pelo ACF Pro. A subscrição a partir de $149 anuais compensa em velocidade de prototipagem.

• Se o seu projeto já usa o CMB2 e as caixas de meta funcionam de forma fiável, mantenha-o. A biblioteca não está abandonada, não requer migração urgente e recebe regularmente atualizações de compatibilidade.

Experimente ambas as abordagens num site de teste: construa a mesma caixa de meta no CMB2 e no ACF. A diferença na abordagem tornar-se-á óbvia em 20 minutos. Que ferramenta utiliza? Partilhe nos comentários.