Guia dos Shortcodes do WordPress

O que são os shortcodes do WordPress

Os shortcodes são etiquetas especiais entre parênteses retos que o motor do WordPress substitui automaticamente por conteúdo dinâmico. Por exemplo, [gallery] mostra uma galeria de imagens, [video] incorpora um vídeo e [contact-form] apresenta um formulário de contacto. Os shortcodes permitem que utilizadores sem conhecimentos técnicos insiram conteúdos complexos em publicações e páginas escrevendo simplesmente um código curto.

Os shortcodes integrados do WordPress cobrem as necessidades básicas, mas o verdadeiro poder está na possibilidade de criar os seus próprios shortcodes. Os programadores de plugins usam-nos para adicionar funcionalidades como formulários, tabelas de preços, sliders e botões, enquanto os programadores de temas usam shortcodes para elementos de design recorrentes. Compreender o sistema de shortcodes é uma competência importante para qualquer utilizador e programador de WordPress.

Shortcodes integrados do WordPress

O WordPress vem com vários shortcodes integrados que cobrem necessidades multimédia básicas. Estes shortcodes funcionam de imediato, sem necessidade de plugins adicionais, e suportam vários parâmetros para personalizar o resultado.

Lista de shortcodes integrados

• [caption] - adiciona uma legenda por baixo da imagem com uma moldura estilizada
• [gallery] - mostra uma galeria de imagens da biblioteca de média com opções de colunas e tamanho
• [audio] - incorpora um leitor de áudio com controlos de reprodução
• [video] - incorpora um leitor de vídeo com suporte para os formatos MP4, WebM e Ogg
• [playlist] - cria uma lista de reprodução de áudio ou vídeo a partir de vários ficheiros
• [embed] - incorpora conteúdo de serviços externos através do protocolo oEmbed

O shortcode gallery em detalhe

O shortcode gallery é o shortcode integrado mais utilizado, pois permite criar rapidamente galerias de imagens. Suporta parâmetros como ids para imagens específicas, columns para o número de colunas, size para o tamanho da imagem, orderby para a ordenação e link para determinar para onde leva o clique na imagem. Por exemplo, [gallery ids="1,2,3" columns="3" size="medium"] mostra três imagens específicas em três colunas de tamanho médio.

Criar shortcodes personalizados

Criar os seus próprios shortcodes no ambiente de desenvolvimento do WordPress é surpreendentemente simples. É utilizada a função add_shortcode(), que recebe dois argumentos: o nome do shortcode e a função de callback que devolve o HTML a apresentar. Adiciona-se esta função ao functions.php do seu tema ou a um plugin personalizado.

Estrutura básica

A função de callback recebe até três parâmetros: $atts (matriz de atributos que o utilizador passa), $content (conteúdo entre a etiqueta de abertura e de fecho) e $tag (nome do próprio shortcode). A função deve devolver uma string com HTML e nunca deve usar echo, pois isso quebraria a ordem de apresentação na página. Este é um erro comum dos iniciantes, que leva a que o conteúdo do shortcode apareça no topo da página em vez de no local onde o shortcode foi inserido.

Exemplo de shortcode simples

Imagine que quer um shortcode que apresente uma citação em destaque com o nome do autor. No functions.php definiria uma função que recebe atributos (author, color) e conteúdo (texto da citação) e devolve um bloco HTML estilizado. O utilizador escreveria no editor [quote author="Eça de Queirós"]A cidade e as serras...[/quote] e o WordPress substituí-lo-ia por uma citação formatada com o nome do autor por baixo do texto.

Parâmetros dos shortcodes

Os parâmetros (atributos) tornam os shortcodes flexíveis, pois permitem aos utilizadores personalizar o resultado sem alterar o código. Use a função shortcode_atts() para definir valores predefinidos e combiná-los com os valores que o utilizador passou. Isto garante que o shortcode funciona mesmo quando o utilizador não especifica todos os parâmetros.

Tipos de parâmetros

• Texto - título, cor, classe, ID (por exemplo, title="Título")
• Numérico - número de colunas, limite de resultados, largura (por exemplo, columns="3")
• Booleano - opções sim/não (por exemplo, show_date="true")
• Lista - IDs separados por vírgula (por exemplo, ids="1,5,12,7")
• Enum - opções predefinidas (por exemplo, size="small|medium|large")

Valide e limpe sempre os parâmetros que o utilizador passa, pois os shortcodes podem ser um vetor de ataques XSS se a entrada do utilizador for incorporada diretamente no HTML. Use as funções esc_attr(), esc_html() e wp_kses() para limpar o resultado. Converta os parâmetros numéricos para int com intval() e compare os parâmetros booleanos com a string true ou false.

Shortcodes aninhados

O WordPress suporta o aninhamento de shortcodes, o que significa que pode colocar um shortcode dentro de outro. Isto é útil para criar layouts complexos onde, por exemplo, tem um shortcode para uma linha e, dentro dela, um shortcode para colunas. O conteúdo aninhado é processado ao chamar a função do_shortcode() sobre o parâmetro $content dentro da sua função de callback.

Uma limitação importante é que não pode aninhar o mesmo shortcode dentro de si próprio, pois o parser do WordPress não consegue distinguir corretamente as etiquetas de abertura e de fecho. Se precisar dessa funcionalidade, crie variantes de shortcode com nomes diferentes, como [row] para a linha e [column] para a coluna dentro da linha. Esta limitação é intencional e é improvável que mude em versões futuras.

Exemplo de aninhamento

Um exemplo clássico é um shortcode de layout onde [row] cria um contentor flex ou grid e [col width="6"] cria uma coluna de largura específica. O utilizador pode escrever [row][col width="4"]Coluna esquerda[/col][col width="8"]Coluna direita[/col][/row] e obter um layout de duas colunas. O shortcode row deve chamar do_shortcode($content) para que o WordPress processe os shortcodes col aninhados antes de devolver o HTML final.

Shortcodes no editor de blocos do WordPress

Com a introdução do editor de blocos Gutenberg, os shortcodes passaram a ter um bloco dedicado chamado Shortcode que aceita qualquer shortcode. No entanto, a tendência no desenvolvimento moderno de WordPress é substituir os shortcodes por blocos personalizados que oferecem uma pré-visualização visual no editor, em vez de texto bruto entre parênteses retos. Para novos projetos, pondere criar blocos em vez de shortcodes, mas para sites existentes os shortcodes continuam totalmente suportados e funcionais.

Quando usar shortcodes em vez de blocos

• Os shortcodes são melhores para inserções simples (citação, botão, ícone)
• Os blocos são melhores para elementos de layout complexos com apresentação visual
• Os shortcodes funcionam no editor Clássico e no editor de blocos
• Os blocos funcionam apenas no editor de blocos (Gutenberg)
• Os shortcodes são mais rápidos de desenvolver; os blocos exigem conhecimentos de JavaScript
• Para compatibilidade com plugins, os shortcodes são mais universais

Dicas práticas e boas práticas

Atribua aos shortcodes o prefixo do seu tema ou plugin para evitar conflitos com outros plugins. Por exemplo, em vez de [button] use [beo_button], pois é menos provável que outro plugin use o mesmo nome. Adicione documentação para cada shortcode que criar, incluindo a lista de parâmetros, os valores predefinidos e exemplos de utilização, pois sem documentação nem você se lembrará de todas as opções passados alguns meses.

Para shortcodes mais complexos que geram HTML significativo, use buffering de saída ou ficheiros de template em vez de concatenação de strings. Isto torna o código mais legível e mais fácil de manter. Faça cache dos resultados dos shortcodes que requerem consultas à base de dados. Use a ferramenta de verificação de desempenho recorrendo à Transients API, pois os shortcodes são executados a cada carregamento de página e shortcodes lentos podem abrandar significativamente o site. Teste sempre os shortcodes em diferentes contextos, incluindo widgets, excertos e feed RSS, pois o comportamento pode variar.