Se você é desenvolvedor do WordPress, então, em algum momento, você pode encontrar a personalização ou a extensão do Editor Visual do WordPress. Por exemplo, você pode querer adicionar um botão à barra de ferramentas do Visual Editor para permitir que seu cliente insira facilmente uma caixa de texto ou um botão de chamada para ação sem escrever nenhum código HTML. Neste artigo, mostraremos como criar um plugin TinyMCE no WordPress.
Requisitos
Este tutorial destina-se a usuários avançados. Se você é um usuário de nível iniciante que apenas quer ampliar o editor visual, então confira o plugin TinyMCE Advanced ou veja estas dicas sobre como usar o editor visual WordPress.
Para este tutorial, você precisará de habilidades básicas de codificação, acesso a uma instalação do WordPress onde você pode testá-la.
É uma prática ruim para desenvolver plugins em um site ao vivo. Um pequeno erro no código pode tornar o seu site inacessível. Mas se você deve fazê-lo em um site ao vivo, então, pelo menos, faça o backup do WordPress primeiro.
Criando seu primeiro plugin TinyMCE
Começaremos criando um plugin do WordPress para registrar nosso botão personalizado da barra de ferramentas TinyMCE. Quando clicado, este botão permitirá ao usuário adicionar um link com uma classe CSS personalizada.
O código-fonte será fornecido na íntegra no final deste artigo, mas até então, vamos criar o plugin passo a passo.
Primeiro, você precisa criar um diretório em wp-content / plugins pasta da sua instalação do WordPress. Nomeie esta pasta tinymce-custom-link-class .
A partir daqui, começaremos a adicionar o nosso código de plugin.
O cabeçalho do plugin
Crie um novo arquivo no diretório do plugin que acabamos de criar e nomeie este arquivo tinymce-custom-link-class.php . Adicione este código ao arquivo e salve-o.
/ ** * Nome do Plugin: TinyMCE Custom Link Classe * URI do plugin: http://site.com * Versão: 1.0 * Autor: site * URI do autor: http://www.site.com * Descrição: Um simples plugin TinyMCE para adicionar uma classe de link personalizada no Visual Editor * Licença: GPL2 * /
Este é apenas um comentário PHP, que diz ao WordPress o nome do plugin, bem como o autor e uma descrição.
Na área de administração do WordPress, ative seu novo plugin indo para Plugins> Plugins instalados e, em seguida, clique em Ativar ao lado do plugin TinyMCE Custom Link Class:
Configurando nossa classe de complemento
Se dois plugins do WordPress tiverem funções com o mesmo nome, isso causaria um erro. Nós evitaremos esse problema ao ter nossas funções envolvidas em uma classe.
classe TinyMCE_Custom_Link_Class {
/ **
* Construtor. Chamado quando o plugin é inicializado.
* /
função __construct () {
}
}
$ tinymce_custom_link_class = new TinyMCE_Custom_Link_Class;
Isso cria nossa classe PHP, juntamente com uma construção, que é chamada quando chegamos à linha $ tinymce_custom_link_class = new TinyMCE_Custom_Link_Class; .
Todas as funções que adicionamos nesta classe não devem entrar em conflito com outros plugins do WordPress.
Comece a configurar nosso plugin TinyMCE
Em seguida, precisamos dizer ao TinyMCE que podemos querer adicionar nosso botão personalizado à barra de ferramentas do Visual Editor. Para fazer isso, podemos usar as ações do WordPress – especificamente, a nisso açao.
Adicione o seguinte código dentro do seu plugin __construir() função:
se (is_admin ()) {
add_action ('init', array ($ this, 'setup_tinymce_plugin'));
}
Isso verifica se estamos na interface de administração do WordPress. Se for o caso, pede ao WordPress que execute o setup_tinymce_plugin Funciona dentro da nossa classe quando o WordPress terminou a rotina de carregamento inicial.
Em seguida, adicione o setup_tinymce_plugin função:
/ **
* Verifique se o usuário atual pode editar Publicações ou Páginas e está usando o Visual Editor
* Se sim, adicione alguns filtros para que possamos registrar nosso plugin
* /
função setup_tinymce_plugin () {
// Verifique se o usuário do WordPress conectado pode editar Posts ou Páginas
// Se não, não registre o nosso plugin TinyMCE
se (! current_user_can ('edit_posts') &&! current_user_can ('edit_pages')) {
Retorna;
}
// Verifique se o usuário com sessão iniciada do WordPress possui o Editor Visual habilitado
// Se não, não registre o nosso plugin TinyMCE
se (get_user_option ('rich_editing')! == 'true') {
Retorna;
}
// Configurar alguns filtros
add_filter ('mce_external_plugins', array (& $ this, 'add_tinymce_plugin'));
add_filter ('mce_buttons', array (& $ this, 'add_tinymce_toolbar_button'));
}
Isso verifica se o usuário registrado no WordPress atualizado pode editar Publicações ou Páginas. Se não puderem, não há nenhum ponto em registrar nosso plugin TinyMCE para esse usuário, pois nunca verão o Visual Editor.
Em seguida, verificamos se o usuário está usando o Visual Editor, já que alguns usuários do WordPress desligam isso via Usuários> Seu Perfil. Novamente, se o usuário não estiver usando o Visual Editor, retornamos (saia) a função, pois não precisamos fazer nada mais.
Finalmente, adicionamos dois filtros do WordPress – mce_external_plugins e mce_buttons , para chamar nossas funções que carregarão o arquivo Javascript requerido para o TinyMCE e adicione um botão à barra de ferramentas TinyMCE.
Registrando o arquivo e o botão Javascript ao Editor Visual
Vamos em frente e adicione o add_tinymce_plugin função:
/ **
* Adiciona um arquivo JS compatível com o plugin TinyMCE na instância do TinyMCE / Visual Editor
*
* @param array $ plugin_array Array de Plugins TinyMCE registrados
* @return array Matriz modificada de plugins TinyMCE registrados
* /
função add_tinymce_plugin ($ plugin_array) {
$ plugin_array ['custom_link_class'] = plugin_dir_url (__FILE__). 'tinymce-custom-link-class.js';
retornar $ plugin_array;
}
Esta função diz ao TinyMCE que precisa carregar os arquivos Javascript armazenados no $ plugin_array matriz. Esses arquivos de Javascript direcionarão ao TinyMCE o que fazer.
Também precisamos adicionar algum código ao add_tinymce_toolbar_button função, para dizer ao TinyMCE sobre o botão que gostaríamos de adicionar à barra de ferramentas:
/ **
* Adiciona um botão ao TinyMCE / Visual Editor que o usuário pode clicar
* para inserir um link com uma classe CSS personalizada.
*
* @param array $ buttons Array de Botões TinyMCE registrados
* @return array Arranjo modificado dos botões TinyMCE registrados
* /
função add_tinymce_toolbar_button ($ buttons) {
array_push ($ buttons, '|', 'custom_link_class');
retornar $ botões;
}
Isso empurra dois itens na matriz de botões TinyMCE: um separador (|), e o nome programático do nosso botão ( custom_link_class ).
Salve seu plugin e edite uma página ou publicação para visualizar o Visual Editor. As possibilidades são, a barra de ferramentas não está sendo exibida agora:
Não se preocupe – se usarmos o console do inspetor do nosso navegador, veremos que um erro e aviso 404 foram gerados pelo TinyMCE, dizendo-nos que não pode encontrar o nosso arquivo Javascript.
Isso é bom – significa que registramos com sucesso o nosso plugin personalizado TinyMCE, e agora precisamos criar o arquivo Javascript para dizer ao TinyMCE o que fazer.
Criando o plugin Javascript
Crie um novo arquivo em seu wp-content / plugins / tinymce-custom-link-class pasta e nomeie-o tinymce-custom-link-class.js . Adicione este código no seu arquivo js:
(function () {
tinymce.PluginManager.add ('custom_link_class', função (editor, url) {
});
}) ();
Isso chama a classe TinyMCE Plugin Manager, que podemos usar para executar várias ações relacionadas ao plugin TinyMCE. Especificamente, estamos adicionando nosso plugin ao TinyMCE usando o adicionar função.
Isso aceita dois itens; o nome do plugin ( custom_link_class ) e uma função anônima.
Se você está familiarizado com o conceito de funções na codificação, uma função anônima é simplesmente uma função sem nome. Por exemplo, função foobar () {...} é uma função que poderíamos chamar para outro lugar em nosso código usando Foobar () .
Com uma função anônima, não podemos chamar essa função em outro lugar em nosso código – é apenas chamado no ponto em que adicionar() a função é invocada.
Guarde o ficheiro Javascript e, em seguida, edite uma página ou publicação para visualizar o Editor Visual. Se tudo funcionou, você verá a barra de ferramentas:
Agora, nosso botão não foi adicionado a essa barra de ferramentas. Isso porque nós só dissemos ao TinyMCE que somos um plugin personalizado. Agora precisamos dizer ao TinyMCE o que fazer, ou seja, adicionar um botão à barra de ferramentas.
Atualize seu arquivo Javascript, substituindo seu código existente pelo seguinte:
(function () {
tinymce.PluginManager.add ('custom_link_class', função (editor, url) {
// Add Button to Visual Editor Toolbar
editor.addButton ('custom_link_class', {
título: 'Insert Button Link',
cmd: 'custom_link_class',
});
});
}) ();
Observe que nossa função anônima tem dois argumentos. O primeiro é o editor instância – este é o TinyMCE Visual Editor. Da mesma forma, podemos chamar várias funções no PluginManager , também podemos chamar várias funções no editor . Nesse caso, estamos chamando a addButton função, para adicionar um botão à barra de ferramentas.
Salve seu arquivo Javascript e volte para o Visual Editor. Em um primeiro aspecto, nada parece ter mudado. No entanto, se você posicionar o cursor do mouse sobre a direita do ícone mais à direita da primeira fila, você deve ver uma dica de ferramenta:
Nós adicionamos com sucesso um botão à barra de ferramentas, mas precisa de uma imagem. Adicione o seguinte parâmetro ao addButton função abaixo do título: linha:
imagem: url + '/icon.png',
url é o URL do nosso plugin. Isso é útil se quisermos fazer referência a um arquivo de imagem dentro da nossa pasta de plugins, pois podemos anexar o nome do arquivo de imagem ao URL. Neste caso, precisamos de uma imagem chamada icon.png na pasta do nosso plugin. Use o ícone abaixo: 
Recarregue o nosso Editor Visual e agora você verá seu botão com o ícone: 
Definindo um comando para executar
Agora, se você clicar no botão, nada vai acontecer. Vamos adicionar um comando ao TinyMCE dizendo o que fazer quando o nosso botão é clicado.
No nosso arquivo Javascript, adicione o seguinte código abaixo do final do editor.addButton seção:
// Adicionar comando quando o botão clicado
editor.addCommand ('custom_link_class', function () {
alerta ('Botão clicado!');
});
Recarregue o nosso Editor Visual, clique no botão e um alerta aparecerá confirmando que acabamos de clicar no botão:
Vamos substituir o alerta por um prompt, perguntando ao usuário o link que deseja envolver em torno do texto selecionado no Visual Editor:
// Adicionar comando quando o botão clicado
editor.addCommand ('custom_link_class', function () {
// Verifique que selecionamos algum texto que queremos vincular
var text = editor.selection.getContent ({
'formato': 'html'
});
se (text.length === 0) {
alerta ('Por favor, selecione um texto para vincular.');
Retorna;
}
// Peça ao usuário para inserir um URL
var result = prompt ('Insira o link');
se (! result) {
// Usuário cancelado - saída
Retorna;
}
se (result.length === 0) {
// O usuário não inseriu um URL - saia
Retorna;
}
// Insira o texto selecionado de volta ao editor, envolvendo-o em uma marca de âncora
editor.execCommand ('mceReplaceContent', false, '' + text + '');
});
Esse bloco de código executa algumas ações.
Primeiro, verificamos se o usuário selecionou algum texto a ser vinculado no Visual Editor. Caso contrário, eles verão um alerta informando para selecionar algum texto para o link.
Em seguida, solicitamos que digitem um link, verificando novamente se o fizeram. Se eles cancelaram, ou não entraram nada, não fazemos mais nada.
Finalmente, corremos o execComputador função no editor TinyMCE, executando especificamente o mceReplaceContent açao. Isso substitui o texto selecionado por nosso código HTML, que inclui um link de âncora com class = “button”, usando o texto que o usuário selecionou.
Se tudo funcionou, você verá que o texto selecionado agora está vinculado nas visualizações do Visual Editor e Text, com a classe configurada para botão :
Resumo
Criamos com sucesso um plugin do WordPress que adiciona um botão ao editor visual TinyMCE no WordPress. Este tutorial também abordou alguns dos conceitos básicos da API TinyMCE e filtros WordPress disponíveis para integrações TinyMCE.
Nós adicionamos o código para que quando um usuário clica no nosso botão personalizado, eles são solicitados a selecionar algum texto no Visual Editor, que eles podem então vincular a uma URL de sua escolha. Finalmente, nosso plugin substitui o texto selecionado por uma versão vinculada que contém uma classe CSS personalizada chamada botão .
Esperamos que este tutorial o ajude a aprender como criar um plugin WordPress TinyMCE. Você também pode verificar o nosso guia sobre como criar um plugin WordPress específico do site.