Entenda os shortcodes do WordPress: crie, personalize e use seus próprios shortcodes em PHP

• O que são códigos de acesso no WordPress?
• Onde você pode usar códigos de acesso do WordPress?
• Crie seu próprio shortcode no WordPress
• Criar shortcode com atributos
• Usar shortcode em postagens e páginas
• Use shortcodes em PHP: Tema, Tema filho, funções.php
• Shortcode de saída em PHP
• Salvar conteúdo de shortcode em uma variável
• Buffering de saída para códigos de acesso que usam echo em vez de return
• Personalizar e estender shortcodes
• Vantagens e desvantagens dos códigos de acesso do WordPress
• Segurança e práticas recomendadas para seus próprios códigos de acesso

Se você já trabalha com WordPress há muito tempo, dificilmente conseguirá evitar os códigos de acesso. Independentemente de ser um formulário de contato, galeria, controle deslizante ou caixas especiais para informações – essas funções geralmente contêm um código curto entre colchetes.

Neste post vou mostrar o que são shortcodes do WordPress, como criar seus próprios shortcodes, como usá-los em posts e páginas e como você pode usar shortcodes diretamente em PHP no seu tema ou tema filho. Também veremos as vantagens e desvantagens dos códigos de acesso e algumas práticas recomendadas para que seu código possa ser mantido posteriormente.

O que são códigos de acesso no WordPress?

Os códigos de acesso são pequenos espaços reservados entre colchetes, por exemplo:

[gallery]
[contact-form-7 id="123"]
[mein_shortcode foo="bar"]

O WordPress reconhece esses códigos de acesso ao renderizar o conteúdo e os substitui por código HTML ou outra saída. A lógica real está nas funções PHP registradas por meio da API de shortcode.

Resumindo:
Os códigos de acesso são um atalho para incorporar funções complexas em postagens e páginas do WordPress sem que o editor precise escrever PHP.

Exemplos típicos de códigos de acesso do WordPress:

• Formulários de contato
• Galerias de imagens e controles deslizantes
• Caixas de informações, botões, acordeões
• listas dinâmicas, por exemplo, postagens ou produtos mais recentes

Onde você pode usar códigos de acesso do WordPress?

Os códigos de acesso não se limitam apenas a postagens ou páginas. Você pode usá-los em vários lugares do seu projeto WordPress.

Isso torna os códigos de acesso flexíveis e especialmente práticos quando você deseja reutilizar funções ou integrá-los em locais diferentes.

Crie seu próprio shortcode no WordPress

Você pode criar seus próprios códigos de acesso usando a função add_shortcode(). Você atribui um nome e uma função de retorno de chamada que gera a saída.

Um exemplo muito simples é assim:

// In die functions.php deines Child Themes oder in ein eigenes Plugin
add_shortcode('my_shortcode', function ($atts) {
    $result = 1 + 1;

    return $result;
});

Alguns pontos importantes:

• O nome do shortcode aqui é my_shortcode. Você pode chamá-lo mais tarde com [my_shortcode].
• A função de retorno de chamada deve return e não usar diretamente echo.
• Você pode então salvar o shortcode em uma variável posteriormente e usá-lo de maneira flexível.

Criar shortcode com atributos

Na prática, muitas vezes você deseja passar parâmetros, por exemplo:

[box color="red" title="Hinweis"]
Mein Box Inhalt
[/box]

Você pode usar shortcode_atts() para definir valores padrão e processar atributos de forma limpa:

add_shortcode('my_box', function ($atts, $content = '') {

    $atts = shortcode_atts([
        'color' => 'blue',
        'title' => '',
    ], $atts, 'my_box');

    $color = esc_attr($atts['color']);
    $title = esc_html($atts['title']);

    ob_start();
    ?>
    <div class="my-box my-box-<?php echo $color; ?>">
        <?php if ($title) : ?>
            <h3 class="my-box-title"><?php echo $title; ?></h3>
        <?php endif; ?>
        <div class="my-box-content">
            <?php echo do_shortcode($content); ?>
        </div>
    </div>
    <?php
    return ob_get_clean();
});

Aqui você pode ver como você:

• Forneça atributos com valores padrão
• proteja a saída com esc_attr e esc_html
• Usa buffer de saída para blocos HTML mais longos (ob_start() e ob_get_clean())

Isso mantém o código limpo e facilmente expansível.

Usar shortcode em postagens e páginas

Supondo que você criou o shortcode my_box do exemplo acima. Em uma postagem ou página você pode usá-lo assim:

[my_box color="green" title="Info"]
Das ist eine grüne Box mit einem Info Titel.
[/my_box]

No Editor Gutenberg você faz isto:

1. Editar postagem ou página
2. Clique no símbolo de mais
3. Pesquise “Código de acesso”
4. Inserir bloco de shortcode
5. Insira o texto do shortcode, por exemplo [my_box color="green"]Inhalt[/my_box]
6. Salvar ou publicar postagem

O WordPress substitui automaticamente o shortcode pelo código HTML da sua função quando você abre a página.

Use shortcodes em PHP: Tema, Tema filho, funções.php

Às vezes você deseja usar códigos de acesso diretamente em modelos PHP, por exemplo, em single.php, page.php ou em um modelo personalizado.

É para isso que serve do_shortcode().

Shortcode de saída em PHP

Se quiser gerar um shortcode diretamente no modelo, você pode instalá-lo assim:

echo do_shortcode('[my_box color="red" title="Achtung"]Inhalt aus dem Template[/my_box]');

• do_shortcode() processa o shortcode e retorna uma string
• Com echo você gera o resultado no modelo

Salvar conteúdo de shortcode em uma variável

Você também pode salvar o resultado de um shortcode em uma variável e reutilizá-lo. Isso é útil, por exemplo, se você precisar do conteúdo em vários lugares ou ainda quiser editá-lo.

Das suas anotações:

$shortcode_content = do_shortcode('[my_shortcode]');

A saída agora está em $shortcode_content e você pode exibi-la mais tarde ou processá-la posteriormente.

Buffering de saída para códigos de acesso que usam echo em vez de return

Na verdade, os códigos de acesso sempre devem funcionar com return. Na realidade, existem plugins que usam echo diretamente no shortcode. Nesse caso, você pode trabalhar com buffer de saída:

ob_start();
do_shortcode('[inconvenient_shortcode]');
$shortcode_content2 = ob_get_clean();

• ob_start() inicia o buffer de saída
• tudo o que o shortcode gera acaba no buffer
• com ob_get_clean() você obtém o conteúdo como uma string em uma variável e esvazia o buffer

Assim você coloca o conteúdo em uma variável mesmo com códigos de acesso “inconvenientes”.

Personalizar e estender shortcodes

Em muitos projetos, você não deseja apenas escrever novos códigos de acesso, mas também adaptar ou estender os códigos de acesso existentes, por exemplo:

• adicionar classes CSS adicionais
• Alterar valores padrão
• ajustar a estrutura HTML

Basicamente você tem duas opções:

• Crie seu próprio shortcode com um novo nome
• Remova um shortcode existente e registre-o novamente

Exemplo de remoção de um shortcode:

add_action('init', function () {
    remove_shortcode('old_shortcode');
});

Você pode então armazenar sua própria implementação com add_shortcode('old_shortcode', 'meine_neue_funktion');. Mas você só deve fazer isso se souber exatamente o impacto que isso terá no conteúdo existente.

Vantagens e desvantagens dos códigos de acesso do WordPress

Os códigos de acesso são úteis, mas não são perfeitos. Especialmente desde que o Editor de Blocos foi introduzido, vale a pena dar uma olhada nas vantagens e desvantagens.

Para novos projetos vale a pena considerar se um bloco de Gutenberg não seria uma solução melhor. Mas os códigos de acesso ainda são úteis, especialmente:

• para funções auxiliares menores
• em combinação com temas e plug-ins existentes
• se você quiser usar funções no editor e nos modelos

Segurança e práticas recomendadas para seus próprios códigos de acesso

Para garantir que seus códigos de acesso do WordPress permaneçam seguros e com bom desempenho, você deve seguir algumas regras básicas.

1. Use nomes e prefixos exclusivos É melhor usar um prefixo, por exemplo, o nome do seu blog ou a abreviatura do seu projeto: add_shortcode('cosci_box', 'cosci_box_shortcode'); Isso reduzirá conflitos com outros temas ou plug-ins.
2. Validar atributos e saídas de escape
   • Forneça atributos com valores padrão significativos por meio de shortcode_atts().
   • Saída segura com esc_html, esc_attr ou wp_kses
3. Os códigos de acesso devem usar return em vez de echo Se o seu código de acesso sempre retornar uma string, você poderá usá-lo em postagens, páginas, variantes, condições e modelos sem soluções alternativas com buffer de saída.
4. Fique de olho no desempenho Se um shortcode fizer consultas complexas ao banco de dados ou chamadas externas à API, isso pode ser um freio se houver muitas ocorrências em uma página. Cache, transientes ou lógica de consulta inteligente ajudam aqui.
5. É melhor terceirizar os códigos de acesso para um plugin Se você colocar seus próprios códigos de acesso em um plugin pequeno, eles sobreviverão a uma mudança de tema. Isso significa que seu projeto permanece mais flexível no longo prazo.

Este artigo foi traduzido com a ajuda de IA.