Cómo crear un plugin TinyMCE de WordPress

Si eres un desarrollador de WordPress, en algún momento te encontrarás personalizando o extendiendo el Editor Visual de WordPress. Por ejemplo, es posible que desees agregar un botón a la barra de herramientas del Editor Visual para permitir que tu cliente inserte fácilmente un cuadro de texto o un botón de llamada a la acción sin escribir ningún código HTML. En este artículo, te mostraremos cómo crear un plugin TinyMCE en WordPress.

Requisitos

Este tutorial está destinado a usuarios avanzados. Si eres un usuario principiante que solo quiere extender el editor visual, consulta el plugin TinyMCE Avanzado o echa un vistazo a estos consejos sobre el uso del editor visual de WordPress.

Para este tutorial, necesitarás habilidades básicas de codificación, acceso a una instalación de WordPress donde puedas probarlo.

Es una mala práctica desarrollar plugins en un sitio web en vivo. Un pequeño error en el código puede hacer que tu sitio sea inaccesible. Pero si debes hacerlo en un sitio en vivo, al menos haz una copia de seguridad de WordPress primero.

Creando tu primer plugin TinyMCE

Crearemos primero un plugin de WordPress para registrar nuestro botón de barra de herramientas personalizado de TinyMCE. Al hacer clic, este botón permitirá al usuario agregar un enlace con una clase CSS personalizada.

El código fuente se proporcionará completo al final de este artículo, pero hasta entonces, creemos el plugin paso a paso.

Primero, necesitas crear un directorio en la carpeta wp-content/plugins de tu instalación de WordPress. Nombra esta carpeta tinymce-custom-link-class.

A partir de aquí, comenzaremos a agregar nuestro código de plugin.

La cabecera del plugin

Crea un nuevo archivo en el directorio del plugin que acabamos de crear y nombra este archivo tinymce-custom-link-class.php. Agrega este código al archivo y guárdalo.

/**
 * 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 es solo un comentario de PHP, que le dice a WordPress el nombre del plugin, así como el autor y una descripción.

En el área de administración de WordPress, activa tu nuevo plugin yendo a Plugins > Plugins Instalados, y luego haciendo clic en Activar junto al plugin TinyMCE Custom Link Class:

Configurando nuestra clase de plugin

Si dos plugins de WordPress tienen funciones con el mismo nombre, esto causaría un error. Evitaremos este problema envolviendo nuestras funciones en una clase.

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

}

$tinymce_custom_link_class = new TinyMCE_Custom_Link_Class;

Esto crea nuestra clase de PHP, junto con un constructor, que se llama cuando llegamos a la línea $tinymce_custom_link_class = new TinyMCE_Custom_Link_Class;.

Cualquier función que agreguemos dentro de esta clase no debería entrar en conflicto con otros plugins de WordPress.

Empezando a configurar nuestro plugin de TinyMCE

A continuación, necesitamos indicarle a TinyMCE que podríamos querer agregar nuestro botón personalizado a la barra de herramientas del Editor Visual. Para hacer esto, podemos usar las acciones de WordPress, específicamente la acción init.

Agrega el siguiente código dentro de la función __construct() de tu plugin:

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

Esto verifica si estamos en la interfaz de Administración de WordPress. Si es así, le pide a WordPress que ejecute la función setup_tinymce_plugin dentro de nuestra clase cuando WordPress haya terminado su rutina de carga inicial.

A continuación, agrega la función 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' ) );
		
	}

Esto verifica si el usuario de WordPress actualmente conectado puede editar Publicaciones o Páginas. Si no pueden, no tiene sentido registrar nuestro Plugin TinyMCE para ese usuario, ya que nunca verán el Editor Visual.

Luego verificamos si el usuario está usando el Editor Visual, ya que algunos usuarios de WordPress lo desactivan a través de Usuarios > Tu Perfil. Nuevamente, si el usuario no está usando el Editor Visual, salimos (terminamos) la función, ya que no necesitamos hacer nada más.

Finalmente, agregamos dos filtros de WordPress – mce_external_plugins y mce_buttons, para llamar a nuestras funciones que cargarán el archivo Javascript requerido para TinyMCE, y agregar un botón a la barra de herramientas de TinyMCE.

Registrar el Archivo Javascript y el Botón en el Editor Visual

Vayamos adelante y agreguemos la función 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 función le dice a TinyMCE que necesita cargar los archivos Javascript almacenados en el array $plugin_array. Estos archivos Javascript le dirán a TinyMCE qué hacer.

También necesitamos agregar algo de código a la función add_tinymce_toolbar_button, para informarle a TinyMCE sobre el botón que nos gustaría agregar a la barra de herramientas:

/**
* 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;
}

Esto agrega dos elementos al array de botones de TinyMCE: un separador (|), y el nombre programático de nuestro botón (custom_link_class).

Guarda tu plugin, y luego edita una Página o Publicación para ver el Editor Visual. Lo más probable es que la barra de herramientas no se esté mostrando ahora mismo:

No te preocupes – si usamos la consola del inspector de nuestro navegador web, veremos que TinyMCE ha generado un error 404 y una notificación, diciéndonos que no puede encontrar nuestro archivo Javascript.

Eso es bueno – significa que hemos registrado exitosamente nuestro plugin personalizado de TinyMCE, y ahora necesitamos crear el archivo Javascript para decirle a TinyMCE qué hacer.

Creando el Plugin Javascript

Crea un nuevo archivo en tu carpeta wp-content/plugins/tinymce-custom-link-class, y nómbralo tinymce-custom-link-class.js. Agrega este código en tu archivo js:

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

Esto llama a la clase del Administrador de Plugins de TinyMCE, la cual podemos usar para realizar una serie de acciones relacionadas con plugins de TinyMCE. Específicamente, estamos agregando nuestro plugin a TinyMCE usando la función add.

Esto acepta dos elementos; el nombre del plugin (custom_link_class) y una función anónima.

Si estás familiarizado con el concepto de funciones en programación, una función anónima es simplemente una función sin nombre. Por ejemplo, function foobar() { ... } es una función que podríamos llamar en otro lugar de nuestro código usando foobar().

Con una función anónima, no podemos llamar a esa función en otro lugar de nuestro código; solo se llama en el punto en que se invoca la función add().

Guarda tu archivo de Javascript y luego edita una Página o Publicación para ver el Editor Visual. Si todo funcionó, verás la barra de herramientas:

En este momento, nuestro botón no se ha agregado a esa barra de herramientas. Esto se debe a que solo le hemos dicho a TinyMCE que somos un plugin personalizado. Ahora necesitamos decirle a TinyMCE qué hacer, es decir, agregar un botón a la barra de herramientas.

Actualiza tu archivo de Javascript, reemplazando tu código existente con lo siguiente:

(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',
		});	
	});
})();

Observa que nuestra función anónima tiene dos argumentos. El primero es la instancia editor; este es el Editor Visual de TinyMCE. De la misma manera que podemos llamar a varias funciones en PluginManager, también podemos llamar a varias funciones en editor. En este caso, estamos llamando a la función addButton para agregar un botón a la barra de herramientas.

Guarda tu archivo de Javascript y regresa a tu Editor Visual. A primera vista, nada parece haber cambiado. Sin embargo, si pasas el cursor del mouse a la derecha del ícono más a la derecha de la fila superior, deberías ver que aparece una información sobre herramientas:

Hemos agregado exitosamente un botón a la barra de herramientas, pero necesita una imagen. Agrega el siguiente parámetro a la función addButton, debajo de la línea 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:

Definir un Comando para Ejecutar

En este momento, si haces clic en el botón, no sucederá nada. Agreguemos un comando a TinyMCE diciéndole qué hacer cuando se haga clic en nuestro botón.

En nuestro archivo de Javascript, agrega el siguiente código debajo del final de la sección editor.addButton:

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

Recarga nuestro Editor Visual, haz clic en el botón y aparecerá una alerta confirmando que acabamos de hacer clic en el botón:

Reemplacemos la alerta con un prompt, pidiéndole al usuario el enlace que desea envolver alrededor del texto seleccionado en el 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 bloque de código realiza algunas acciones.

Primero, verificamos si el usuario seleccionó algún texto para enlazar en el Editor Visual. Si no es así, verán una alerta indicándoles que seleccionen algún texto para enlazar.

A continuación, les pedimos que ingresen un enlace, verificando nuevamente si lo hicieron. Si cancelaron o no ingresaron nada, no hacemos nada más.

Finalmente, ejecutamos la función execCommand en el editor TinyMCE, ejecutando específicamente la acción mceReplaceContent. Esto reemplaza el texto seleccionado con nuestro código HTML, que consta de un enlace ancla con class=”button”, utilizando el texto que el usuario seleccionó.

Si todo funcionó, verás que tu texto seleccionado ahora está enlazado en las vistas Editor Visual y Texto, con la clase establecida en button:

Resumen

Hemos creado con éxito un plugin de WordPress que agrega un botón al editor visual TinyMCE en WordPress. Este tutorial también ha cubierto algunos de los conceptos básicos de la API de TinyMCE y los filtros de WordPress disponibles para integraciones de TinyMCE.

Agregamos código para que cuando un usuario haga clic en nuestro botón personalizado, se le pida que seleccione algún texto en el Editor Visual, que luego podrá enlazar a una URL de su elección. Finalmente, nuestro plugin reemplaza el texto seleccionado con una versión enlazada que contiene una clase CSS personalizada llamada button.

Esperamos que este tutorial te haya ayudado a aprender cómo crear un plugin TinyMCE para WordPress. También puedes consultar nuestra guía sobre cómo crear un plugin específico para WordPress.

Si te gustó este artículo, suscríbete a nuestro Canal de YouTube para tutoriales de video de WordPress. También puedes encontrarnos en Twitter y Facebook.