The Beginner’s Guide to Writing Your Own Custom Shortcode

Shortcodes são uma funcionalidade popular incluída em muitos plugins e temas. Entretanto, se você nunca construiu seus próprios atalhos antes, você pode não ter idéia de como adicioná-los aos seus próprios projetos WordPress.

Felizmente, a API de Atalhos do WordPress torna bastante simples criar seus próprios atalhos. Fazendo isso, os usuários poderão aproveitar os recursos do seu plugin ou tema de qualquer área baseada em texto no seu site WordPress. Incluir atalhos em seus projetos é uma maneira fácil de construir sobre a funcionalidade que você já criou, assim você ganha o máximo de bang pelo seu buck.

Neste artigo, vamos falar um pouco mais sobre como os atalhos funcionam. Depois, vamos mostrar-lhe como pode ser simples programar os seus em três passos. Vamos começar!

Uma Introdução ao Shortcodes e a API de Shortcodes

A API de Shortcodes do WordPress é uma ferramenta útil para desenvolvedores.

Códigos de atalho parecem pequenos pedaços de texto entre parênteses rectos, como este: . Cada um deles representa uma execução única de código pré-definido, que é acionado sob demanda. Você pode usá-los em quase qualquer lugar onde o texto pode ser adicionado no WordPress.

Enquanto a maioria dos atalhos são adicionados por temas e plugins, o núcleo do WordPress tem alguns poucos atalhos padrão que você pode usar. Alguns exemplos deles são áudio, galeria e legenda.

Por exemplo, quando você adiciona uma imagem com legenda, o WordPress gera um atalho particular:

Quando você vê isto no front end, você verá uma imagem com uma legenda:

Felizmente, o Shortcode API torna relativamente simples criar atalhos personalizados para os seus próprios projectos WordPress. Esta é muitas vezes uma idéia inteligente porque torna a vida de seus usuários mais fácil, permitindo que eles usem funcionalidades complexas com apenas algumas teclas.

Como escrever seu próprio código de atalho personalizado (Em 3 passos simples)

Agora que você entende como os atalhos funcionam, vamos aprender como adicionar um ao seu próprio tema ou plugin! É claro, o que o seu código de atalho faz, depende de você. Neste exemplo, vamos usar uma simples função “Olá mundo!” para começar.

Escreva a função de código de atalho

Primeiro, você vai querer abrir um novo arquivo em um editor de texto. A seguir, escreva uma função com um nome único, que executará o código que você gostaria que o atalho disparasse:

function torque_hello_world_shortcode() { return 'Hello world!';}

Se fossemos usar esta função normalmente, ela retornaria Hello world! como uma string que poderia ser emitida para HTML. Esta função também pode tomar parâmetros personalizados. Por exemplo, se você quiser que alguém possa fazer com que ela diga Olá Bob! em vez disso, você pode adicionar um parâmetro de nome. Estes parâmetros são chamados atributos, e todos eles são tratados usando um único array predefinido como $atts pelo WordPress.

Aqui está um exemplo de como usar a função de atalho $atts para tratar corretamente os atributos do atalho no WordPress. Você pode aprender mais sobre como isso funciona para suas próprias necessidades no código do WordPress:

function torque_hello_world_shortcode( $atts ) { $a = shortcode_atts( array( 'name' => 'world' ), $atts ); return 'Hello ' . $a . !';}

Este atributo de nome é o padrão para o mundo se nenhum outro nome estiver disponível. Se um nome for fornecido, a função irá emitir esse atributo no lugar. Aqui está um exemplo de como isto seria executado com um atalho:

// Outputs "Hello world!" // Outputs "Hello Bob!"

Após ter terminado, isto pode ser usado em qualquer área baseada em texto num site WordPress onde o plugin ou tema que contém este atalho está instalado.

Salve o ficheiro e adicione-o ao seu projecto

Após o seu atalho estar pronto, pode criar um novo ficheiro dentro do seu tema ou plugin personalizado para salvar a função. Um nome descritivo irá ajudá-lo a encontrar esse arquivo mais tarde (por exemplo: shortcode-function-hello-world.php).

Agora, é hora de contar ao resto do seu projeto sobre esse novo arquivo. Se você estiver trabalhando com um tema, você vai querer incluí-lo no arquivo functions.php. Se você está construindo um plugin, você pode incluí-lo em qualquer arquivo já carregado no projeto.

Aqui está um exemplo de como você carregaria o arquivo em um tema usando get_stylesheet_directory(). Certifique-se de editar o caminho para o seu ficheiro para corresponder à estrutura de pastas dentro do seu tema:

include( get_stylesheet_directory() . 'path/to/shortcode-function-hello-world.php' );

Por outro lado, isto é o que parece carregar o ficheiro para um plugin, utilizando plugin_dir_url(). Mais uma vez, edite o caminho para o seu ficheiro para corresponder à estrutura de pastas do seu plugin:

include( plugin_dir_url( __FILE__ ) . 'path/to/shortcode-function-hello-world.php' );

Neste ponto, a sua função está agora disponível para uso! Tudo o que resta é registrar ativamente o atalho dentro do WordPress.

Registrar o código de atalho

O último passo é registrar seu novo atalho com a API de código de atalho. Isto é feito com a função add_shortcode. Ela requer dois argumentos:

  1. A tag de atalho para ser usada dentro do editor de texto
  2. O nome da função que manipula a execução do atalho

Baixo da sua função de atalho, inclua esta linha de código e atualize-a para corresponder aos seus próprios valores:

add_shortcode( 'helloworld', 'torque_hello_world_shortcode' );

O primeiro valor irá dentro de parênteses rectos no editor de texto. O segundo irá corresponder ao nome da função que você escreveu nos dois passos anteriores. Ambos devem ser únicos o suficiente para não interferirem com outros atalhos incluídos pelo núcleo, temas ou plugins do WordPress.

Após terminar, tudo o que resta é testá-lo. Entre no administrador do WordPress e tente adicionar seu código de atalho a um post:

É tudo o que há para fazer! O seu atalho pode ser tão complicado ou simples quanto você quiser – o que você decidir construir usando esse poder é com você! Para situações avançadas onde você gostaria de ajustar a saída para diferentes situações, pode valer a pena escrever uma classe PHP única para lidar com seu novo atalho.

Conclusion

Adicionar funcionalidades complexas aos posts e páginas do WordPress é fácil com os atalhos. Eles são simples de programar e agregam valor ao seu projeto existente, tornando o conteúdo simples e dinâmico.

Neste artigo, você aprendeu que são necessários apenas três passos simples para criar um atalho:

  1. Escreva uma função regular que executa o código personalizado desejado.
  2. Salve o código para o plugin ou tema.
  3. Registe o atalho dentro do WordPress.

Deixe um comentário