O WordPress oferece uma API (desde a versão 2.5) para criação e uso de Shortcodes e com isso proporcionar o uso mais abrangente da ferramenta, tanto para desenvolvedores como para  usuários finais e outros que não são familiarizados com códigos.

Shortcodes são palavras entre [ ] (colchetes) que ao serem lidas (interpretadas) pelo WordPress, fazem com que ele execute determinadas atividades.

Um exemplo básico seria criarmos um shortchode para exibir o logo do site, e então toda vez que a pessoa precisar exibir o logo ela usaria apenas isso [logo]. Os shortcodes são muito úteis para itens que são muito repetitivos no site.

As possibilidades com shortcodes são inúmeras, para não dizer infinitas. Com isso inicio aqui uma série de artigos que pretendem tratar desse assunto, com os seguintes objetivos

  • Explicar como funcionam os shortcodes;
  • Utilização dos shortcodes nativos;
  • Uso de plugins de shortcodes;
  • Criação de seus próprios shortcodes.

Nesse primeiro artigo vamos iniciar conhecendo a API, entendendo em quais ambientes ela se aplica e entender suas possibilidades.

Breve Introdução

Um exemplo básico que podemos observar no próprio WordPress é o shortcode que imprime no nosso post (ou página) uma galeria de fotos, o shortcode (sempre entre []):

gallery

Com esse shortcode, o post exibe a galeria que você criou para ele. Sua função é imprimir uma marcação XHTML com as fotos e informações que você configurou na administração.

Aparentemente simples e realmente é. Mas vamos aprofundar mais nesse shortcode e entender as possibilidades que podemos construir com essa API. Os shortcodes também podem receber atributos, por exemplo:

gallery id="123" size="medium"

Aqui é fácil identificar que a galeria a ser exibida é referente ao post de ID 123 com thumbnails de tamanho medium. Com a possibilidade de informar o ID do post que você quer exibir a galeria, podemos utilizar ele fora do seu post de origem, abrangendo ainda mais o campo de atuação dos shortcodes; por exemplo, podemos exibir essa galeria de fotos em um widget, em outro post ou mesmo diretamente nos códigos PHP (explicarei como mais abaixo).

Apenas para ilustrar o shortcode gallery que estamos usando como exemplo, abaixo seguem algumas configurações avançadas para seu uso:

orderby
Especifica a ordem para mostrar as miniaturas. O padrão é “menu_order ASC, ID ASC”.

itemtag
Especifica a tag XHTML usada para envolver cada item da galeria. O padrão é “dl”.

icontag
Especifica a tag XHTML usada para envolver cada ícone de miniatura da galeria. O padrão é “dt”.

captiontag
Especifica a tag XHTML usada para envolver cada legenda. O padrão é “dd”.

link
Com essa configuração você pode especificar qual link será usado em cada item da galeria. O padrão é o link permanente do anexo.

include
IDs dos anexos que deseja incluir na galeria separados por vírgulas

exclude
IDs dos anexos que deseja remover da galeria separados por vírgulas

Exemplo:

gallery itemtag="div" icontag="span" captiontag="p" link="file"

Bom, com a explicação até aqui conseguimos entender o que uma simples palavra (ou alguns atributos) é capaz quando envolvida em um shortcode; deixando o trabalho “pesado” oculto aos olhos dos usuários finais. Ainda nesse post vou colocar dois exemplos básico/avançados de como criar seu próprio shortcode e então poderá entender com mais clareza como ele funciona por trás dos bastidores.

Usando shortcode no tema

Em alguns casos é preciso adicionar um shortcode diretamente nos códigos PHPs do seu tema. Para isso o WordPress oferece uma função que interpreta o seu shortcode como se ele estivesse dentro de um post. A função usada para isso é do_shortcode(), veja como usar com nosso exemplo [logo]:

echo do_shortcode('[logo]');

Isso é muito usado quando usamos plugins de formulários de contato, mapas de localização e sliders, que nos retorna um shortcode para aplicarmos onde queremos tal funcionalidade.

Fecha ou não fecha o shortcode?

Os shortcodes podem funcionar de duas formas, dependendo do seu objetivo. A primeira forma é como o exemplo que usamos [logo], ele é apenas um shortcode que tem a função de imprimir o HTML referente ao logo que você definiu.

Outra forma são com shortcodes que abrem e fecham, exemplo:

[laranja]Exibir texto com a cor Laranja[/laranja]

Nesse exemplo queremos colorir um trecho do texto com a cor laranja. Para isso iniciamos com o shortcode [laranja] e finalizamos com [/laranja].

A relação é muito próxima do HTML, onde você usa uma tag para abrir e a mesma com / (barra) para terminar o item.

Criando seus próprios shortcodes

Até aqui conhecemos um shortcode básico, como ele recebe argumentos e shortcodes que envolvem um determinado item (texto, imagem, etc). Vamos então iniciar uma parte mais complexa desse post e desenvolver nossos próprios shortcodes, criando os shortcodes exibidos acima, [logo] e [laranja].

O limite aqui é sua necessidade e criatividade. Shortcodes são extremamente úteis quando temos ações muito repetitivas durante a escrita de um post (ou página).

Para essa etapa será necessário ter acesso ao functions.php do seu tema. Lembrando que se você não estiver familiarizado em trabalhar nos arquivos do seu tema é preciso muito cuidado e atenção para não prejudicar o seu site.

O functions.php é um arquivo em seu tema que é incluído no WordPress automaticamente, e nele podemos escrever nossas funções e incluir outros arquivos.

[logo]

Vamos iniciar criando o shortcode [logo], a princípio ele deve apenas imprimir o logo do seu site. No functions.php do seu tema cole o seguinte:

function shortcode_logo(){
 return '<img src="' . get_stylesheet_directory_uri(). '/imagens/logo.png" alt="" title="" width="" height="" />';
}
add_shortcode( 'logo', 'shortcode_logo' );

Explicando: Criamos uma função chamada shortcode_logo(). E como escopo ela apenas retorna a tag HTML <img />, com get_stylesheet_directory_uri() pegamos o endereço para a pasta do tema e somamos com /images/logo.png; que pode ser alterado para o local onde seu logo está.

Finalizamos com a função add_shortcode(), colocando como primeiro atributo o nome que queremos para nosso shortcode, no caso “logo” e o segundo atributo o nome da função que criamos anteriormente.

Pronto. Salve isso e sempre que precisar do logo do site é só escrever o shortcode [logo].

Adicionando atributos ao [logo]

Vamos evoluir esse shortcode. Imaginando que precisamos definir uma URL diferente para o logo; assim facilitamos ainda mais o trabalho do usuário final, fazendo com que seja possível enviar a imagem para sua biblioteca de mídias e então usar o URL dessa imagem.

Com a mesma função anterior, vamos complementar dessa forma:

function shortcode_logo( $atts ){
 
 extract( shortcode_atts(
 array(
 'url' => '',
 ), $atts )
 );

 if ( !empty( $url ) ) {
 $img = '<img src="' . $url . '" alt="" title="" width="" height="" />';
 } else {
 $img = '<img src="' . get_stylesheet_directory_uri(). '/imagens/logo.png" alt="" title="" width="" height="" />';
 }

 return $img;
}
add_shortcode( 'logo', 'shortcode_logo' );

Explicando: Adicionamos na nossa função a variável $atts que será responsável por passar à nossa função os atributos. Dessa variável extraímos os valores com a função shortcode_atts(), observe que por enquanto temos apenas o atributo URL. Abaixo criamos uma condição para, caso a $url esteja vazia o shortcode vai imprimir o logo.png, como uma imagem default (padrão).

Aumentamos consideravelmente a flexibilidade do nosso shortcode, possibilitando que o usuário informe a URL caso não queira a imagem default (padrão). Como falei acima, o que determina até onde o shortcode pode chegar, depende apenas da sua criatividade e necessidade.

Vamos dar mais um salto com esse shortcode e colocar como atributos todos os itens da tag <img />, como alt, title, width e height.

function shortcode_logo( $atts ){
 
 extract( shortcode_atts(
 array(
 'url' => '',
 'alt' => '',
 'title' => '',
 'width' => '',
 'height' => '',
 ), $atts )
 );
if ( !empty( $url ) ) {
 $img = '<img src="' . $url . '" alt="' . $alt . '" title="' . $title . '" width="' . $width . '" height="' . $height . '" />';
 } else {
 $img = '<img src="' . get_stylesheet_directory_uri(). '/imagens/logo.png" alt="' . $alt . '" title="' . $title . '" width="' . $width . '" height="' . $height . '" />';
 }
return $img;
}
add_shortcode( 'logo', 'shortcode_logo' );

Explicando: Para adicionar N atributos é muito simples, no array dentro da função shortcode_atts() é só adicionar os valores que deseja receber. O resultado disso é uma variável com o nome especificado nesse array. Então colocamos essas variáveis para complementar a tag <img />.

Um exemplo de uso desse shortcode completo seria:

[logo url='http://exemplo.com.br/wp-content/uploads/2014/08/expocar.jpg' alt='Imagem do evento ExpoCar' title='Opel Rekord 1971' width='500' height='300']

Um pouco mais complexo, mas também muito completo.

[laranja][/laranja]

Vamos agora ver como funciona o shortcode que recebe conteúdo entre eles. Vamos usar o exemplo que citamos acima [laranja]Exibir texto com a cor Laranja[/laranja]

Esse tipo de shortcode pode ser usado para muitas coisas, em nosso exemplo vamos colocar apenas uma cor, com isso já entendemos que qualquer propriedade de CSS caberia aqui.

Observe que estamos aproveitando o conceito que aprendemos acima sobre atributos ($atts).

No seu functions.php cole o seguinte:

function shortcode_laranja( $atts, $content = null ){
 extract( shortcode_atts(
 array(
 'hexa' => '',
 ), $atts )
 );
if ( empty( $hexa ) ) {
 $hexa = '#FF8000';
 }
return '<span style="color:' . $hexa . '">' . $content . '</span>';
}
add_shortcode( 'laranja', 'shortcode_laranja' );

Explicando: Adicionamos o atributo “hexa” apenas para aumentar a funcionalidade desse shortcode, caso a pessoa queira outro tom de laranja é somente definir o hexadecimal como atributo do shortcode. Caso contrário ele tem um laranja definido (#FF0000) por padrão.

Um exemplo de uso seria:

Exemplo de texto na cor [laranja]Laranja Default[/laranja] e outro com um [laranja hexa='#FFBA75']Laranja Claro[/laranja].

Conclusão

Espero que essas dicas possam ajudar você a implementar melhorias no seu WordPress! As possibilidades são infinitas. Existem também diversos plugins que adicionam shortcodes ao seu site, muito útil para aplicar botões, colunas e outros elementos.

Você que chegou até aqui, imagino que teve ideias de novos shortcodes. Compartilhe conosco colocando sua ideia nos comentários abaixo e quem sabe construímos uma biblioteca de shortcodes colaborativa!