🛠 Como adicionar o teu próprio shortcode no WordPress: detalhe do add_shortcode() [+2 exemplos]

Criou um snippet, adicionou-o ao functions.php e o WordPress diz «cheatin' uh?» Parece-lhe familiar? Os shortcodes, o mecanismo de extensão central do WordPress, e o add_shortcode() desbloqueiam isso em 15 linhas de código. Mas entre um «Hello World» e um cenário real existem algumas armadilhas: return vs echo, ordem dos parâmetros do callback e conflitos de tags.

Os shortcodes surgiram no WordPress 2.5 e desde então tornaram-se a base do ecossistema: formulários de contacto, galerias, sliders, saída de campos personalizados, tudo isto vive dentro de parênteses retos. O add_shortcode() não muda há anos e pode dominá-lo em meia hora.

A seguir, uma análise completa da função com dois exemplos prontos a usar: desde um ano de atualização automática no rodapé até uma lista de utilizadores do site.

💡 Visão geral rápida:

• Sintaxe e parâmetros do add_shortcode(), tag e callback
• A regra: sempre return, nunca echo
• O hook init, porque é que o seu shortcode pode não funcionar sem ele
• Duas formas de passar dados: conteúdo entre tags e atributos
• Código pronto a usar: um shortcode para ano automático e uma lista de utilizadores

Como funciona o add_shortcode() no WordPress

A função add_shortcode() é o ponto de entrada para registar qualquer shortcode personalizado. Recebe dois parâmetros obrigatórios: uma tag única e o nome da função de callback que devolverá o conteúdo.

De acordo com a documentação do WordPress, o callback recebe três argumentos numa ordem fixa:

• $attributes, um array de atributos passados no shortcode
• $content, o texto entre as tags de abertura e fecho
• $tag, o nome da tag com que o shortcode está registado

Um exemplo básico, um shortcode que produz «Hello World!»:

1
// Shortcode callback function
2
function hello_world_shortcode_callback( $attributes, $content, $tag ) {
3
    return 'Hello World!';
4
}
5
// Shortcode registration
6
function hello_world_shortcode() {
7
    add_shortcode( 'hello-world', 'hello_world_shortcode_callback' );
8
}
9
add_action( 'init', 'hello_world_shortcode' );

O código vai para o functions.php do seu tema filho ou através de um plugin de Code Snippets. Depois disso, [hello-world] no editor de artigos produzirá «Hello World!».

Porquê return e não echo

Repare no return dentro da função de callback. Se usar echo, a saída acontece antes de o WordPress construir o resto da página, «Hello World!» acaba no topo e o conteúdo circundante fica deslocado.

A regra é simples: **um callback de shortcode devolve sempre um valor via ****return**. Nada de echo, print ou saída direta de HTML fora de um buffer.

O hook init é obrigatório

Os programadores do WordPress.org recomendam ligar o registo do shortcode ao init, e não chamar o add_shortcode() diretamente no corpo do functions.php. Sem o init, o WordPress pode não ter terminado de inicializar os seus mecanismos internos e o shortcode simplesmente não será executado.

Sintaxe e parâmetros

Assinatura da função:

1
add_shortcode( string $tag, callable $callback )

$tag, o nome do shortcode (sem parênteses retos). Se dois plugins registarem um shortcode com a mesma tag, o último substitui o anterior. Para evitar conflitos, adicione um prefixo único: não [gallery], mas [myplugin_gallery].

$callback, o nome da função que devolve o conteúdo. Pode passar uma string com o nome da função, uma função anónima ou um método de classe (passando um array [ $object, 'method_name' ]).

Como usar shortcodes no editor

No editor do WordPress, Gutenberg ou Clássico, um shortcode é inserido entre parênteses retos. Para o nosso exemplo:

[hello-world]

A forma completa com tag de fecho também funciona:

[hello-world][/hello-world]

A segunda opção é necessária quando se passa conteúdo entre as tags (mais sobre isso abaixo).

Como chamar um shortcode em PHP

Nos templates de temas ou plugins, os shortcodes são executados via do_shortcode():

1
echo do_shortcode( '[hello-world]' );

A função recebe uma string que contém um shortcode e devolve o resultado da sua execução. É útil quando precisa de incorporar a saída de um shortcode na lógica PHP, por exemplo, no header.php ou dentro de um loop.

Passar dados para um shortcode: duas formas

Método 1: conteúdo entre tags

Coloque os dados entre as tags de abertura e fecho:

[hello-world]from John to Mary[/hello-world]

O callback recebe a string from John to Mary através do segundo parâmetro $content:

1
// Callback with content substitution between tags
2
function hello_world_shortcode_callback( $attributes, $content, $tag ) {
3
    return 'Hello ' . $content . ' World!';
4
}
5
// Registration
6
function hello_world_shortcode() {
7
    add_shortcode( 'hello-world', 'hello_world_shortcode_callback' );
8
}
9
add_action( 'init', 'hello_world_shortcode' );

Resultado: «Hello from John to Mary World!».

Método 2: atributos

Passe parâmetros diretamente na tag de abertura:

[hello-world from="John" to="Mary"][/hello-world]

Na função de callback, os atributos estão disponíveis através do primeiro parâmetro $attributes, um array associativo onde as chaves correspondem aos nomes dos atributos:

1
// Callback with reading shortcode attributes
2
function hello_world_shortcode_callback( $attributes, $content, $tag ) {
3
    return 'Hello from ' . $attributes['from'] . ' to ' . $attributes['to'] . '!';
4
}
5
// Registration
6
function hello_world_shortcode() {
7
    add_shortcode( 'hello-world', 'hello_world_shortcode_callback' );
8
}
9
add_action( 'init', 'hello_world_shortcode' );

Saída: «Hello from John to Mary!». Os atributos são melhores para dados estruturados (preço, URL, ID), enquanto o conteúdo entre tags é melhor para texto arbitrário.

Na prática, deve adicionar imediatamente shortcode_atts() aos atributos, uma função integrada do WordPress que funde os atributos passados com um array de valores predefinidos. Sem ela, aceder a $attributes['from'] lançará um Aviso de PHP se o utilizador não tiver especificado o atributo. Com shortcode_atts(), obtém sempre um array preenchido: chaves definidas com valores de recurso e os atributos desconhecidos são filtrados automaticamente.

Dois shortcodes prontos a usar para WordPress

1. Ano atual automático

O shortcode [current-year] insere o ano atual por si só, sem necessidade de atualizar a data no rodapé todos os meses de janeiro:

1
// Callback: returns current year via date('Y')
2
function current_year_shortcode_callback( $attributes, $content, $tag ) {
3
    return date( 'Y' );
4
}
5
// Registration of shortcode [current-year]
6
function current_year_shortcode() {
7
    add_shortcode( 'current-year', 'current_year_shortcode_callback' );
8
}
9
add_action( 'init', 'current_year_shortcode' );

Coloque [current-year] no rodapé ou no texto de um artigo e o ano será atualizado automaticamente.

2. Lista de utilizadores registados

O shortcode [users-list] produz os nomes de todos os utilizadores do site como uma lista de marcas. Útil numa página de «Equipa» ou em relatórios de administração:

1
// Callback: gets all users and generates HTML list
2
function my_custom_users_list() {
3
    $users = get_users();
4
    $list_html = '<ul>';
5
    foreach ( $users as $user ) {
6
        $list_html .= '<li>' . $user->data->display_name . '</li>';
7
    }
8
    $list_html .= '</ul>';
9
    return $list_html;
10
}
11
// Registration of shortcode [users-list]
12
function register_my_users_list_shortcode() {
13
    add_shortcode( 'users-list', 'my_custom_users_list' );
14
}
15
add_action( 'init', 'register_my_users_list_shortcode' );

get_users() sem argumentos devolve todos os utilizadores. Para limitar a consulta por função, passe um array: get_users( [ 'role' => 'editor' ] ). O código vai para o functions.php do tema ativo ou para um plugin personalizado.

Vídeo: criar shortcodes no WordPress

Um pequeno vídeo sobre o tema, registar um shortcode de raiz, desde escrever a função até testar no editor:

⁉️🤔 Perguntas frequentes

O que acontece se dois plugins registarem um shortcode com a mesma tag?

O WordPress executa o que foi carregado por último. O primeiro shortcode é substituído silenciosamente, sem erros. É por isso que deve usar sempre um prefixo nos seus shortcodes: [acme_gallery] em vez de [gallery]. Isto elimina conflitos com qualquer outro plugin ou tema.

Os shortcodes podem ser chamados dentro de outros shortcodes?

Sim. Se o callback do primeiro shortcode devolver uma string que contenha a tag do segundo shortcode, o WordPress processa o shortcode aninhado automaticamente. Mas não se esqueça do do_shortcode(): se estiver a construir conteúdo manualmente e este contiver shortcodes, passe a string por do_shortcode() explicitamente. O comportamento padrão do the_content faz isto por si, mas uma chamada direta ao callback não o faz.

Onde deve residir o código do shortcode, no tema ou num plugin?

Os shortcodes personalizados transportam funcionalidade, não aparência, por isso é melhor extraí-los para um plugin separado. Mudar de tema não quebrará o site: os shortcodes continuarão a funcionar. No mínimo, use um tema filho se tiver a certeza de que não vai mudar o tema principal.

Há restrições quanto ao nome da tag?

O nome deve ser composto por letras latinas, dígitos e hífenes. Espaços, underscores e caracteres especiais não são permitidos. O comprimento recomendado é até 20 caracteres, em minúsculas. Exemplo: [my-plugin-shortcode].

Como depurar um shortcode se não produzir nada?

Primeiro passo, ative o WP_DEBUG no wp-config.php. Segundo, verifique se o callback devolve um valor via return, e não echo. Terceiro, certifique-se de que o hook init está presente. Se não houver erros, mas a saída estiver vazia, adicione error_log() dentro do callback e verifique os logs do servidor.

O que recordar sobre os shortcodes do WordPress

Os shortcodes são um mecanismo maduro e estável. O add_shortcode() não muda há anos: tag, callback, hook init, return em vez de echo. Lembre-se destas quatro coisas e qualquer shortcode personalizado funcionará à primeira tentativa.

• Se estiver a produzir o ano no rodapé, aproveite o [current-year] já pronto.
• Se precisar de uma lista de utilizadores, [users-list] com um filtro de função.
• Se estiver a escrever o seu próprio shortcode de raiz, use sempre um prefixo e use sempre o init.

Para o próximo passo, explore como empacotar um shortcode como um plugin autónomo e submetê-lo ao diretório do WordPress.org, é a melhor forma de separar a funcionalidade do tema e elevar o seu perfil de programador.