Como Criar um Plugin TinyMCE para WordPress

Se você é um desenvolvedor WordPress, em algum momento poderá se deparar com a personalização ou extensão do Editor Visual do WordPress. Por exemplo, você pode querer adicionar um botão à barra de ferramentas do Editor Visual 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 iniciante que deseja apenas estender o editor visual, consulte o plugin TinyMCE Advanced ou dê uma olhada nestas dicas sobre como usar o editor visual do WordPress.

Para este tutorial, você precisará de conhecimentos básicos de codificação, acesso a uma instalação do WordPress onde você possa testá-lo.

É uma má prática desenvolver plugins em um site ativo. Um pequeno erro no código pode tornar seu site inacessível. Mas se você precisar fazer isso em um site ativo, pelo menos faça backup do WordPress primeiro.

Criando Seu Primeiro Plugin TinyMCE

Começaremos criando um plugin WordPress para registrar nosso botão de barra de ferramentas TinyMCE personalizado. 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é lá, vamos criar o plugin passo a passo.

Primeiro, você precisa criar um diretório na pasta wp-content/plugins da sua instalação do WordPress. Nomeie esta pasta como tinymce-custom-link-class.

A partir daqui, começaremos a adicionar o código do nosso plugin.

O Cabeçalho do Plugin

Crie um novo arquivo no diretório do plugin que acabamos de criar e nomeie este arquivo como tinymce-custom-link-class.php. Adicione este código ao arquivo e salve-o.

/**
 * Plugin Name: TinyMCE Custom Link Class
 * Plugin URI: http://wpbeginner.com
 * Version: 1.0
 * Author: WPBeginner
 * Author URI: https://www.wpbeginner.com
 * Description: A simple TinyMCE Plugin to add a custom link class in the Visual Editor
 * License: GPL2
 */

Este é apenas um comentário PHP, que informa ao WordPress o nome do plugin, bem como o autor e uma descrição.

Na área administrativa do WordPress, ative seu novo plugin indo em Plugins > Plugins Instalados e, em seguida, clicando em Ativar ao lado do plugin TinyMCE Custom Link Class:

Configurando Nossa Classe de Plugin

Se dois plugins do WordPress tiverem funções com o mesmo nome, isso causaria um erro. Evitaremos esse problema tendo nossas funções encapsuladas em uma classe.

class TinyMCE_Custom_Link_Class {
	
	/**
	* Constructor. Called when the plugin is initialised.
	*/
	function __construct() {
		
	}

}

$tinymce_custom_link_class = new TinyMCE_Custom_Link_Class;

Isso cria nossa classe PHP, juntamente com um construtor, que é chamado quando chegamos à linha $tinymce_custom_link_class = new TinyMCE_Custom_Link_Class;.

Quaisquer funções que adicionarmos dentro desta classe não devem entrar em conflito com outros plugins do WordPress.

Começando a Configurar Nosso Plugin TinyMCE

Em seguida, precisamos dizer ao TinyMCE que podemos querer adicionar nosso botão personalizado à barra de ferramentas do Editor Visual. Para fazer isso, podemos usar as ações do WordPress – especificamente, a ação init.

Adicione o seguinte código dentro da função __construct() do seu plugin:

if ( is_admin() ) {
	add_action( 'init', array(  $this, 'setup_tinymce_plugin' ) );
}

Isso verifica se estamos na interface de Administração do WordPress. Se estivermos, então pede ao WordPress para executar a função setup_tinymce_plugin dentro da nossa classe quando o WordPress terminar sua rotina inicial de carregamento.

Em seguida, adicione a função setup_tinymce_plugin:

/**
* Check if the current user can edit Posts or Pages, and is using the Visual Editor
* If so, add some filters so we can register our plugin
*/
function setup_tinymce_plugin() {

// Check if the logged in WordPress User can edit Posts or Pages
// If not, don't register our TinyMCE plugin
	
if ( ! current_user_can( 'edit_posts' ) && ! current_user_can( 'edit_pages' ) ) {
	        return;
}

// Check if the logged in WordPress User has the Visual Editor enabled
// If not, don't register our TinyMCE plugin
if ( get_user_option( 'rich_editing' ) !== 'true' ) {
return;
}

// Setup some filters
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 atual logado no WordPress pode editar Posts ou Páginas. Se eles não puderem, não há sentido em registrar nosso Plugin TinyMCE para esse Usuário, pois eles nunca verão o Editor Visual.

Em seguida, verificamos se o usuário está usando o Editor Visual, pois alguns usuários do WordPress desativam isso em Usuários > Seu Perfil. Novamente, se o usuário não estiver usando o Editor Visual, retornamos (saímos) da função, pois não precisamos fazer mais nada.

Finalmente, adicionamos dois Filtros do WordPress – mce_external_plugins e mce_buttons, para chamar nossas funções que carregarão o arquivo Javascript necessário para o TinyMCE e adicionarão um botão à barra de ferramentas do TinyMCE.

Registrando o Arquivo Javascript e o Botão no Editor Visual

Vamos adicionar a função add_tinymce_plugin:

/**
* Adds a TinyMCE plugin compatible JS file to the TinyMCE / Visual Editor instance
*
* @param array $plugin_array Array of registered TinyMCE Plugins
* @return array Modified array of registered TinyMCE Plugins
*/
function add_tinymce_plugin( $plugin_array ) {

$plugin_array['custom_link_class'] = plugin_dir_url( __FILE__ ) . 'tinymce-custom-link-class.js';
return $plugin_array;

}
    

Esta função informa ao TinyMCE que ele precisa carregar os arquivos Javascript armazenados na matriz $plugin_array. Esses arquivos Javascript dirão ao TinyMCE o que fazer.

Também precisamos adicionar algum código à função add_tinymce_toolbar_button, para informar ao TinyMCE sobre o botão que gostaríamos de adicionar à barra de ferramentas:

/**
* Adds a button to the TinyMCE / Visual Editor which the user can click
* to insert a link with a custom CSS class.
*
* @param array $buttons Array of registered TinyMCE Buttons
* @return array Modified array of registered TinyMCE Buttons
*/
function add_tinymce_toolbar_button( $buttons ) {

array_push( $buttons, '|', 'custom_link_class' );
return $buttons;
}

Isso adiciona dois itens à matriz de botões do TinyMCE: um separador (|) e o nome programático do nosso botão (custom_link_class).

Salve seu plugin e, em seguida, edite uma Página ou Post para ver o Editor Visual. Provavelmente, a barra de ferramentas não está sendo exibida no momento:

Não se preocupe – se usarmos o console inspetor do nosso navegador web, veremos que um erro 404 e um aviso foram gerados pelo TinyMCE, informando que ele não consegue encontrar nosso arquivo Javascript.

Isso é bom – significa que registramos com sucesso nosso plugin personalizado do TinyMCE e agora precisamos criar o arquivo Javascript para dizer ao TinyMCE o que fazer.

Criando o Plugin Javascript

Crie um novo arquivo em sua pasta wp-content/plugins/tinymce-custom-link-class e nomeie-o como tinymce-custom-link-class.js. Adicione este código ao seu arquivo js:

(function() {
	tinymce.PluginManager.add( 'custom_link_class', function( editor, url ) {
		
	});
})();

Isso chama a classe TinyMCE Plugin Manager, que podemos usar para executar várias ações relacionadas a plugins do TinyMCE. Especificamente, estamos adicionando nosso plugin ao TinyMCE usando a função add.

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 em programação, uma função anônima é simplesmente uma função sem nome. Por exemplo, function foobar() { ... } é uma função que poderíamos chamar em outro lugar do nosso código usando foobar().

Com uma função anônima, não podemos chamar essa função em outro lugar do nosso código – ela está sendo chamada apenas no ponto em que a função add() é invocada.

Salve seu arquivo Javascript e, em seguida, edite uma Página ou Post para ver o Editor Visual. Se tudo funcionou, você verá a barra de ferramentas:

No momento, nosso botão não foi adicionado a essa barra de ferramentas. Isso ocorre porque apenas 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', function( editor, url ) {
		// Add Button to Visual Editor Toolbar
		editor.addButton('custom_link_class', {
			title: 'Insert Button Link',
			cmd: 'custom_link_class',
		});	
	});
})();

Observe que nossa função anônima tem dois argumentos. O primeiro é a instância editor – este é o Editor Visual do TinyMCE. Da mesma forma que podemos chamar várias funções no PluginManager, também podemos chamar várias funções no editor. Neste caso, estamos chamando a função addButton, para adicionar um botão à barra de ferramentas.

Salve seu arquivo Javascript e volte para o seu Editor Visual. À primeira vista, nada parece ter mudado. No entanto, se você passar o cursor do mouse para a direita do ícone mais à direita da primeira linha, um tooltip deverá aparecer:

Adicionamos um botão à barra de ferramentas com sucesso, mas ele precisa de uma imagem. Adicione o seguinte parâmetro à função addButton, abaixo da linha title::

image: url + '/icon.png',

url is the URL to our plugin. This is handy if we want to reference an image file within our plugin folder, as we can append the image file name to the URL. In this case, we’ll need an image called icon.png in our plugin’s folder. Use the below icon:

Reload our Visual Editor, and you’ll now see your button with the icon:

Definindo um Comando para Executar

No momento, se você clicar no botão, nada acontecerá. Vamos adicionar um comando ao TinyMCE dizendo o que fazer quando nosso botão for clicado.

Em nosso arquivo Javascript, adicione o seguinte código abaixo do final da seção editor.addButton:

// Add Command when Button Clicked
editor.addCommand('custom_link_class', function() {
	alert('Button clicked!');
});

Recarregue 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 ele deseja envolver o texto selecionado no Editor Visual:

// Add Command when Button Clicked
editor.addCommand('custom_link_class', function() {
	// Check we have selected some text that we want to link
	var text = editor.selection.getContent({
		'format': 'html'
	});
	if ( text.length === 0 ) {
		alert( 'Please select some text to link.' );
		return;
	}

	// Ask the user to enter a URL
	var result = prompt('Enter the link');
	if ( !result ) {
		// User cancelled - exit
		return;
	}
	if (result.length === 0) {
		// User didn't enter a URL - exit
		return;
	}

	// Insert selected text back into editor, wrapping it in an anchor tag
	editor.execCommand('mceReplaceContent', false, '<a class="button" href="' + result + '">' + text + '</a>');
});

Este bloco de código executa algumas ações.

Primeiro, verificamos se o usuário selecionou algum texto para ser vinculado no Editor Visual. Caso contrário, ele verá um alerta informando para selecionar algum texto para vincular.

Em seguida, pedimos que ele insira um link, novamente verificando se ele o fez. Se ele cancelou ou não inseriu nada, não fazemos mais nada.

Finalmente, executamos a função execCommand no editor TinyMCE, especificamente executando a ação mceReplaceContent. Isso substitui o texto selecionado pelo nosso código HTML, que compreende um link âncora com a classe "button", usando o texto que o usuário selecionou.

Se tudo funcionou, você verá que o texto selecionado agora está vinculado nas visualizações Editor Visual e Texto, com a classe definida como button:

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 dos filtros do WordPress disponíveis para integrações TinyMCE.

Adicionamos código para que, quando um usuário clicar em nosso botão personalizado, ele seja solicitado a selecionar algum texto no Editor Visual, que poderá então vincular a um URL de sua escolha. Finalmente, nosso plugin substitui o texto selecionado por uma versão vinculada que contém uma classe CSS personalizada chamada button.

Esperamos que este tutorial tenha ajudado você a aprender como criar um plugin TinyMCE para WordPress. Você também pode conferir nosso guia sobre como criar um plugin específico do WordPress.

Se você gostou deste artigo, então por favor inscreva-se em nosso Canal do YouTube para tutoriais em vídeo do WordPress. Você também pode nos encontrar no Twitter e Facebook.