Como criar shortcodes WordPress 1: tinyMCE e caixas

Acompanhe a série e crie sua própria coleção de shortcodes, incluindo botão de inserção via tinyMCE.
0
87

Os shortcodes foram introduzidos no WordPress 2.5, logo se revelando numa das ferramentas mais versáteis do sistema de gerenciamento de conteúdo. Com eles você pode inserir vídeos, formatar texto, aplicar formatação condicional e o que mais a necessidade e imaginação permitir em seus artigos.

Além das opções nativas do WordPress, como os de inserção de vídeo, áudio, tweets e galerias de imagem, podemos usar a API para criar nossos próprios shortcodes.

Mas o que são exatamente os shortcodes e sua API? Uma explicação do próprio WordPress:

A Shortcode API é um conjunto simples de funções para criar shortcodes para uso em posts e páginas. Por exemplo, o seguinte shortcode, se introduzido num post ou página, vai exibir uma galeria de imagens vinculada àquela página ou post:

[gallery]

A API permite que desenvolvedores de plugins criem tipos especiais de conteúdo que podem ser vinculados a certas páginas ao adicionar o shortcode correspondente. Exemplos: vídeos, galerias de imagem, conteúdo de sites externos (tweets, posts do Facebook, etc), contagem de categorias, etc.

Isso é só a superfície do que se pode fazer com eles. Se usados em conjunto com outra ferramenta já inclusa no WordPress, o tinyMCE, podemos montar uma bela "caixa de ferramentas" para nosso editor visual.

É o que vamos acompanhar a partir desse artigo.

Antes de começar

Sempre é recomendável ter uma instalação local do WordPress, ou seja, num servidor de testes. Evite fazer experiências num servidor de trabalho, como no seu site já publicado. Para ter um servidor local, é só instalar um pacote de softwares como o Wamp, Xampp e similares.

Os shortcodes serão criados numa instalação limpa do WordPress, usando o tema padrão atual (Twenty Seventeen), sem nenhum plugin rodando. As instruções valem para praticamente qualquer outro tema, já que usa arquivos comuns como as folhas de funções e estilos.

Crie um tema filho

Para não perder suas alterações, crie um tema filho. Em wp-content/themes, crie uma pasta com o nome "twentyseventeen-child".

Crie um arquivo de texto, e nele cole o seguinte (edite onde está indicado com maiúsculas):

/*
Theme Name: Twenty Seventeen Child
Theme URI: https://wordpress.org/themes/twentyseventeen/
Description: Twenty Seventeen Child Theme
Author: VOCÊ
Author URI: http://SEUURL
Template: twentyseventeen
Version: 1.0.0
License: GNU General Public License v2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Tags: light, dark, two-columns, right-sidebar, responsive-layout, accessibility-ready
Text Domain: twenty-seventeen-child
*/

Salve este arquivo na pasta do tema filho com o nome style.css. Abra o painel de gerenciamento de temas (Aparência > Temas) e seu tema filho deve estar pronto para ser ativado.

Crie outro arquivo de texto, e nele cole:

<?php

?>

São as marcações de abertura e fechamento da sua folha de funções. Salve o arquivo como functions.php, na pasta do tema filho. ESSA É A FOLHA DE FUNÇÕES DO TEMA.

Na mesma pasta, crie uma nova pasta e chame-a "admin". Dentro dela crie os arquivos:

  • tt-scripts.js — a folha de Javascript, com funções da caixa do tinyMCE.
  • tt-styles.css — na mesma pasta, será a folha de estilos dos shortcodes.
  • tt-functions.php — a folha de funções dos shortcodes.
  • admin-styles.css — a folha de estilos do painel.

Ao final, esta será a estrutura de suas pastas de tema e tema filho:

Agora sim, prontos para começar.

Criando um listbox no tinyMCE

Digitar os shortcodes quando forem necessários é péssima escolha, até porque serão muitos. Melhor ter um botão que automatize isso. Vamos criar um listbox, um objeto do tinyMCE que renderiza uma caixa de seleção. Essa lista suspensa terá as opções de shortcodes, facilmente acessíveis na barra superior do editor do WordPress.

No arquivo functions.php (do tema filho, aquele que você criou), insira o seguinte entre as marcações de abertura e fechamento que já estavam lá:

require_once('admin/tt-functions.php');

Isso vai requerer que o arquivo de funções dos shortcodes seja incluído na execução do tema. Assim mantemos funções separadas do functions principal do tema, mas funcionando como se fossem um só.

A partir de agora, você só vai adicionar funções ao tt-functions.php, scripts aos tt-scripts.js, e estilos às duas folhas de estilo.

No tt-functions.php, adicione:

<?php
function tt_tinymce_plugin($plugin_a) {
 $plugin_a['tt_shortcode_plugin'] = get_stylesheet_directory_uri() . '/admin/tt-scripts.js';
 return $plugin_a;
}
function tt_register_button($button) {
 array_push($button, "tt_button_key");
 return $button;
}
function tt_add_button() {
 global $typenow;
 // verifica permissões do usuário
 if (!current_user_can('edit_posts') && !current_user_can('edit_pages') ) {
 return;
 }
 // verifica tipo de post
 if (!in_array( $typenow, array( 'post', 'page' ) ) )
 return;
 // verifica se WYSIWYG está ativo
 if ( get_user_option('rich_editing') == 'true') {
 add_filter('mce_external_plugins', 'tt_tinymce_plugin');
 add_filter('mce_buttons', 'tt_register_button');
 }
}
add_action('admin_head', 'tt_add_button');
?>

Salve o arquivo.

  • As duas primeiras funções vão registrar o script que estará na tt-scripts.js, ainda vamos trabalhar nisso.
  • A verificação de post garante que a caixa só vai aparecer em posts e páginas, e não em outros tipos de post, como alguns especiais gerados por plugins (como o Advanced Custom Fields, o MyCred e outros).
  • Em seguida, como comentado no código, verificamos se o modo WYSIWYG (editor em tempo real, digamos) está ativo para então exibir a listbox.
  • Por fim, a função é adicionada à área de administração do WordPress.

No arquivo tt-scripts.js, insira:

(function() {
 "use strict";
 tinymce.PluginManager.add('tt_shortcode_plugin', function(editor, url) {
 editor.addButton('tt_button_key', {
 type: 'listbox',
 text: 'Shortcodes',
 values: [
 { // CAIXAS
 text: 'Caixas',
 onclick: function() {
 var get_select;
 if (tinyMCE.activeEditor.selection.getContent() === '' ) {
 get_select = '';
 }
 else {
 get_select = tinyMCE.activeEditor.selection.getContent();
 }
 editor.windowManager.open({
 title: 'Configuração da Caixa',
 body: [
 {
 type:'textbox',
 name: 'caixa_conteudo',
 label: 'Conteúdo',
 value: get_select
 }
 ]
 });
 }
 }]
 });
 } );
} )();

Com isso estamos preparando nossos primeiros shortcodes, que serão para criar caixas de conteúdo. O código acima é só a estrutura básica, mas já vai mostrar algum resultado. Salve os arquivos e atualize a página do editor de posts. Lá deve estar sua caixa:

Aparência da listbox gerada.

A lista foi definida no início do código: em...

editor.AddButton

...dizemos ao tinyMCE para criar um botão no editor, e mais abaixo, criamos o botão...

tt_button_key

...com um objeto do tipo listbox. A partir de values estarão os objetos guardados pela caixa e suas respectivas funções — todas inseridas no arquivo tt-scripts.js.

Clique na caixa, e será exibida uma opção "Caixas". Clique nela e será exibida uma janela popup — criada pelo...

editor.windowManager.open

Ela ainda não tem qualquer função, exceto uma: se você mantiver um texto selecionado antes de abrir a caixa, verá que o texto será copiado para o campo Conteúdo.

Vamos partir disso para fazer algo de verdade.

Shortcode de Caixas

O primeiro shortcode que vamos criar é de Caixas. Com ele, você terá um shortcode com o formato:

[tt_caixa]CONTEÚDO[/tt_caixa]

Pela listbox, vamos abrir um popup de configuração da caixa, com opções de título e ícone. A minha ficou assim:

Com CSS você conseguirá transformá-la no que precisar.

Atalho

O ícone é do kit FontAwesome, que será incluído ao painel do editor e ao site (frontend e backend). Em vez de baixar a folha de estilos e as fontes do site, use as do MaxCDN: esse link aponta sempre a versão mais recente do arquivo.

No tt-functions.php, adicione o seguinte:

function tt_enqueue_admin() {
 wp_register_style( 'fontawesome', '//maxcdn.bootstrapcdn.com/font-awesome/latest/css/font-awesome.min.css' );
 wp_enqueue_style( 'fontawesome' );
}
add_action( 'admin_enqueue_scripts', 'tt_enqueue_admin' );

Agora é uma boa hora também para vincular a folha de estilos exclusiva da área de administração (admin-styles.css). Abra o arquivo e nele cole o seguinte:

.mce-i-cube:before {
 font: 15px FontAwesome;
 content: '\f1b2'; /* cubo */
 position: relative;
 top: 2px;
}

Salve.

Lembra da função tt_enqueue_admin_style que criou agora há pouco para inserir o FontAwesome na área de administração? Edite-a para ficar assim:

function tt_enqueue_admin_style() {
 wp_register_style( 'fontawesome', '//maxcdn.bootstrapcdn.com/font-awesome/latest/css/font-awesome.min.css' );
 wp_register_style( 'adminstyles', get_stylesheet_directory_uri() . '/admin/admin-styles.css');
 
 wp_enqueue_style( array('fontawesome','adminstyles') );
}
add_action( 'admin_enqueue_scripts', 'tt_enqueue_admin_style' );

Registramos os estilos do administrador, e agora chamamos ambos a partir de um array de registros, em wp_enqueue_style. Ou seja: a ação inclui os estilos do FontAwesome e do admin-styles ao backend do site.

Por fim, vamos adicionar uma classe à opção da caixa no listbox. No arquivo tt-scripts.js, procure pelo trecho:

type: 'listbox',
 text: 'Shortcodes',
 values: [
 { // CAIXAS
 text: 'Caixas',

Na linha seguinte adicione icon: 'cube',. Fica assim:

type: 'listbox',
 text: 'Shortcodes',
 values: [
 { // CAIXAS
 text: 'Caixas',
 icon: 'cube',

Cube é o identificador de um dos ícones do FA, e o tinyMCE vai gerar o ícone com a classe...

mce-i-cube

...que já estilizamos pouco antes. Salve tudo e volte a testar o menu. Se tudo deu certo, agora você tem um ícone:

O link da listbox está pronto, então vamos escrever a função da janela que o link abre. Aquela função básica que foi escrita antes será alterada. Copie todo este código (o mesmo abaixo) e cole no arquivo customcodes.js, substituindo tudo que já estava lá.

Salve o arquivo. No arquivo admin-styles.css, junte o seguinte:

.mce-menu-has-icons i.mce-ico:before {font: 15px FontAwesome;}
.mce-colorbox i {
 border-top: 1px solid #c5c5c5 !important;
 position: relative;
 top: -6px;
}

Salve. Esvazie o cache do navegador e teste sua caixa de novo. Agora ela deve ter bem mais campos.

Conteúdo: o usuário vai inserir o texto a ser exibido na caixa num textbox ajustado para permitir múltiplas linhas (multiline: true). Se houver texto selecionado antes de abrir a janela, será automaticamente colocado nesse campo.

Cor: inserida através de um objeto colorbox do tinyMCE. Ao observar o código, você verá que ele foi programado para quatro opções: cinza, vermelho, amarelo e verde. O usuário poderá tanto clicar no botão e escolher uma delas (e seu nome vai para o campo de texto) quanto digitar o nome na caixa. Há uma validação simples no código...

var permit = 'greenyellowred';

...para que não sejam aceitas cores incompatíveis com o shortcode que ainda vamos programar. O nome da cor só será aceito e inserido no editor se estiver dentro dessa variável.

Vale notar que essa abordagem deixa espaço para bugs propositais como "greenyellow", "lowred", "enyel", etc, digitados como cor, logo não é um método 100% seguro, só uma verificação simples para evitar "purple", "wheat" e outras cores existentes. Valores inválidos devem resultar numa caixa na cor padrão. Se o usuário escolher o cinza, nada será adicionado ao shortcode como parâmetro; isso foi proposital, já que teremos cinza como cor padrão.

Ícones: o código cria uma caixa com todas as opções de ícone do FontAwesome, organizados em ordem alfabética.

Se o usuário não quiser um ícone na caixa, bastará deixar o listbox na primeira opção, em branco.

Ao clicar em OK para inserir o shortcode, a marcação que deverá ser inserida no editor é similar a isso:

[tt_box icon="gear" color="green" title="Lorem Ipsum"]Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer in tincidunt ligula. Nullam at vulputate magna, sit amet semper leo. Phasellus lacus eros, tincidunt id lorem eu, pharetra molestie erat.[/tt_box]

Mas ela ainda não tem qualquer efeito, porque falta a função.

Função

Com o atalho do shortcode pronto, é hora de criar a função que vai lidar com o shortcode. Abra o functions.php do tema-filho e adicione tudo abaixo em substituição ao que já estava lá:

Abra o tt-styles.css na pasta admin, e nele cole:

Essa folha fornece estilos à todos os shortcodes dentro do site, e já usamos um "enqueue" para isso. Atualize a página e a caixa deve estar assim:

Só isso. Alterando as configurações da geração do shortcode, obtemos outros modelos de caixa. Veja os quatro modelos disponíveis, com as opções de ícone e título ativas:

São poucas limitações:

  • Outros shortcodes dentro do shortcode da caixa podem (ou não) gerar posicionamentos estranhos de objetos, já que tudo dentro da caixa tem estilização própria. Se for o caso, teste.
  • Como explicado, a marcação não é totalmente à prova de bugs, então não é recomendável alterar o que for gerado pelo listbox.

Mas com criatividade, você consegue outros visuais, como não fornecendo um ícone e usando emojis ou imagens no lugar do "title".

Um último detalhe...

O link principal do listbox — escrito Shortcodes — também pode ter um ícone do FontAwesome. Abra o tt-scripts.js e localize esse trecho:

tinymce.PluginManager.add( 'tt_shortcode_plugin', function( editor, url ) {
 editor.addButton( 'tt_button_key', {
 type: 'listbox',
 text: 'Shortcodes',

Logo depois da última vírgula, na linha de baixo, adicione:

icon: ' fa fa-folder',
classes: ' tt',

Salve. No admin-styles.css, adicione:

.mce-tt .mce-ico:before {
 font: 14px FontAwesome !important;
 position: relative;
 top: -10%;
}
.mce-tt.mce-active .mce-ico:before {
 content: "\f07c"; /* pasta aberta */
}

Salve, esvazie os caches e atualize a página do editor. Agora sua caixa deve ter o ícone da pasta aberta ou fechada:

Só um detalhe a mais...

👍

Se não conseguiu, os arquivos completos do tema filho estão disponíveis para download. Clique no botão abaixo e os obtenha gratuitamente.

Teve algum problema? Comente. Na próxima parte, vamos criar o shortcode para caixas de alerta — similares às caixas, mas com um botão para serem fechadas.

- Publicidade -

Receba atualizações do Tutoriart

É grátis, e você pode escolher entre receber só sugestões sobre arte, design gráfico, Photoshop, etc, ou só sobre WordPress, blogging, design web, snippets, etc. Ou tudo, se preferir!

Quero assinar...
Ao assinar, você concorda com os Termos de Privacidade.

DEIXE UMA RESPOSTA

Por favor, digite seu comentário!
Por favor, digite seu nome aqui