Como criar shortcode no WordPress

Na vida de um desenvolvedor que trabalha com WordPress, disponibilizar shortcodes para uso nos sites criados é uma tarefa que estará presente em praticamente todos os projetos. Se você tem dúvidas de como criar shortcode no WordPress ou quer aprender um pouco mais sobre como eles funcionam, este artigo irá esclarecer todas essas dúvidas.

O que é e como usar shortcode no WordPress?

Shortcode é um tipo de elemento do WordPress que permite que o usuário insira desde pequenas informações personalizadas até controlar a exibição de parte do conteúdo com um simples [shortcode].

Usar shortcodes é uma tarefa extramente simples e pode ser feita de duas maneiras (dependendo editor que você esta usando). Caso você utilize o “Editor Clássico” do WordPress, você só precisa escrever entre colchetes o nome shortcode e os parâmetros que quiser passar para a função. Porém se você usa o Gutenberg, você só precisa inserir um bloco de conteúdo do tipo “Shortcode” e inserir o nome e parâmetros desejados.

Se você usa o editor Gutemberg, uma dica extra. Caso haja qualquer erro no shortcode inserido você verá um erro ao tentar salvar o post em edição.

Então, como criar shortcode para WordPress?

Agora já está claro como inserir um shortcode nos posts, vamos falar da parte realmente interessante deste artigo e por a mão na massa!

Nós podemos dividir os shortcodes em 3 tipos + 1 tipo extra que é uma sutil modificação para o caso de funções anonimas do PHP.

add_shortcode()

A função add_shortcode() é a responsável por registrar e criar realmente os shortcodes dentro do seu tema e plugin personalizado. Ela aceita dois parâmetros onde o primeiro será o texto que o usuário do site irá usar para “invocar” o shortcode e o segundo é a função callback que será executada pelo shortcode.

Para ficar claro, neste caso o usuário do site iria inserir “[shortcode-padrao]” no editor de conteúdos e o ao visualizar o post, no lugar do shortcode, seria impresso “Conteudo”.

Shortcode Simples

# [shortcode-padrao]
function funcaoParaShortcode()
{
    return 'Conteudo';
}
add_shortcode('shortcode-padrao', 'funcaoParaShortcode'); 

Criar um shortcode simples não requer muito trabalho, basicamente é criar a função callback e mapeá-la com a função add_shortcode() como pode ser visto acima.

Shortcode Anonimo

Um shortcode anonimo é o “tipo extra” de shortcodes mencionado acima, isso porque ao invés de ser criada uma função no PHP para reutilização no site, você cria ela “anonimamente” dentro da própria função add_shortcode() passando ela como parâmetro.

add_shortcode('shortcode-anonino', function() {
    return 'Conteudo';
});

O uso dos shortcodes anônimos não é muito adequado porque você acaba restringindo a funcionalidade e não conseguiria mais usar a função sem invocar o shortcode, então use apenas para funções que não tem chance alguma de ser reaproveitada no restante do seu código.

Shortcode com Parâmetros

Para criar um shortcode com parâmetros (ou atributos), você precisará passar na função CallBack um argumento que será responsável por conter os valores que o usuário informar durante o uso do shortcode. Para exemplificar o código acima, o usuário utilizaria o shortcode da seguinte maneira:

[shortcode-com-parametros parametro0=”22″ parametro1=”10″]

Caso o parametro0 ou o parametro1 não fossem informados, então a nossa função assumiria os valores 0 e 1 (respectivamente) por serem nossos valores padrões definidos na função shortcode_atts().

function funcaoParaShortcodeComParams($params)
{
    $a = shortcode_atts([
        'parametro0' => 0,
        'parametro1' => 1,
    ], $params);

    return $a['paramentro0'] + $a['paramentro1'];
}
add_shortcode('shortcode-com-parametros', 'funcaoParaShortcodeComParams');

Shortcode com conteúdo

Shortocodes com conteúdos são aqueles onde você pode “aprisionar” parte do conteúdo dentro do shortcode e utilizar este conteúdo da maneria como achar mais adequado em sua função.

Por exemplo, você pode criar um shortcode onde o conteúdo que estiver aprisionado apareça apenas para usuários administradores do site!

function funcaoParaShortcodeComConteudo($params, $content = NULL)
{
    $a = shortcode_atts([
        'parametro0' => 0,
        'parametro1' => 1,
    ], $params);

    return '<p>'. $content .'</p>';
}
add_shortcode('shortcode-com-conteudo', 'funcaoParaShortcodeComConteudo');

Para exemplificar melhor o uso do shortocode com conteúdo, o usuário utilizaria ele da seguinte maneira:

[shortcode-com-conteudo] Lorem Ipsum Dolor Sit Amet [/shortcode-com-conteudo]

Vale frisar que neste tipo de shortcode é obrigatório passar o primeiro parâmetro (mesmo que não seja usado na função) e definir o valor padrão para o argumento da função que aprisionará o valor do conteúdo do shortcode como NULL.

Informação importante ao criar shortcodes

Você sempre deve utilizar return ao final dos seus shortcodes personalizados e nunca echo, print_r, require, include… ou até mesmo funções do WP como get_template_part(). Se você fizer isso, o conteúdo do seu shortcode irá ser renderizado bem no topo da tela.

Se você for um desenvolvedor organizado e trabalhar com ambientes separados para usas views e suas funções, a maneira correta de reter as informações seria usando a função ob_start() no inicio da função em conjunto com a ob_get_contents() e ob_end_clean() ao final. Saiba mais sobre essas funções aqui.

BÔNUS: Como usar shortcode em templates

Ao contrário de inserir shortcodes pelo editor de posts, quando você trabalha com a criação de templates para temas e tipos de post, você não pode simplesmente colocar [meu-shortcode] no seu arquivo php e achar que vai funcionar.

O uso correto de shortcode em um template de página e post é através da função abaixo, onde ela recebe como parâmetro o shortcode necessário.

apply_shortcodes(‘[meu-shortcode]’)

Cuidado com informações legadas!

A função acima irá funcionar apenas para instalações do WordPress acima da versão 5.4, para versões anteriores você deve usar a função do_shortcode() que tem o funcionamento exatamente igual a função mais recente do CMS.

É isso!

Esperamos que este tutorial tenha sido valioso para você e que você tenha aprendido de vez como criar shortcode no WordPress!

Se você quiser visualizar mais facilmente as funções, dê uma olhada no GitHub deste projeto!

Ver no GitHub

Se você ainda tiver alguma dúvida ou esteja precisando que algum shortcode personalizado, deixe nos comentários abaixo!