Contents
Introducción
Este artículo explica paso a paso cómo añadir un botón personalizado a la barra del editor clásico (TinyMCE) en WordPress usando JavaScript y el habitual registro/encolado desde PHP. Incluye ejemplos completos de código (PHP y JS), manejo de permisos, localización de datos, ejemplos de inserción simple y de diálogo modal, y notas sobre compatibilidad y buenas prácticas de seguridad.
Qué vamos a lograr
- Añadir un botón visible en la barra de herramientas del editor clásico.
- Insertar contenido en el editor al pulsar el botón (texto, HTML o shortcode).
- Mostrar un diálogo para recoger opciones y generar contenido dinámico.
- Registrar y encolar los scripts correctamente desde un plugin o tema hijo.
Requisitos y consideraciones
- Esto funciona con el editor clásico (TinyMCE 4). Si usas Gutenberg/Editor de bloques necesitarás otro enfoque (un bloque o un plugin para el editor).
- Se recomienda crear esto desde un plugin o un tema hijo, no modificar archivos núcleo.
- Comprobar capacidades: solo usuarios con capacidad de editar posts deberían ver el botón (por ejemplo, current_user_can(edit_posts)).
- Escapar y sanear cualquier entrada que venga desde AJAX o formularios.
Estructura de archivos sugerida
- my-plugin/
- my-plugin.php (archivo principal del plugin)
- assets/js/editor-button.js (JavaScript que añade el botón a TinyMCE)
- assets/css/editor-button.css (opcional, estilos del botón o ventana)
Paso 1 — Registrar y encolar los scripts desde PHP
En el archivo principal del plugin (o en functions.php del tema hijo) registramos y encolamos el script que contiene el plugin de TinyMCE y pasamos datos mediante wp_localize_script (por ejemplo, ajax_url o nonce).
admin_url( admin-ajax.php ),
nonce => wp_create_nonce( miboton_nonce ),
button_text => __( Mi Botón, mi-textdomain ),
) )
wp_enqueue_script( miboton_tinymce )
// CSS opcional para estilos del modal o icono
wp_enqueue_style( miboton_editor_css, plugins_url( assets/css/editor-button.css, __FILE__ ) )
}
?>
Nota: no estamos forzando que el plugin solo cargue si Classic Editor está activo estamos cargando en las pantallas de edición y realizando una comprobación de capacidades. Si necesitas detectar explícitamente si Gutenberg está activo, hay funciones adicionales, pero no son necesarias si tu objetivo es el editor clásico.
Paso 2 — Código JavaScript: registrar el plugin de TinyMCE y añadir el botón
El archivo assets/js/editor-button.js debe contener la definición del plugin TinyMCE. Usaremos tinymce.PluginManager.add y luego añadiremos el botón con editor.addButton. El ejemplo incluye:
(function() {
// Esperar a que tinymce exista
if ( typeof tinymce === undefined ) {
return
}
// Registrar el plugin
tinymce.PluginManager.add(miboton_plugin, function(editor, url) {
// Añadir un botón simple que inserta texto
editor.addButton(miboton_button, {
text: mibotonData.button_text Mi Botón,
icon: false,
onclick: function() {
// Insertar contenido en el editor donde esté el cursor
editor.insertContent(Contenido insertado por Mi Botón)
}
})
// Alternativamente, añadir un botón que abre una ventana modal
editor.addButton(miboton_dialog, {
text: Insertar con diálogo,
icon: false,
onclick: function() {
editor.windowManager.open({
title: Opciones del botón,
body: [
{ type: textbox, name: title, label: Título },
{ type: textbox, name: subtitle, label: Subtítulo }
],
onsubmit: function( e ) {
var titulo = editor.dom.encode( e.data.title )
var subtitulo = editor.dom.encode( e.data.subtitle )
// Insertar HTML seguro
editor.insertContent( titulo
subtitulo
)
}
})
}
})
// Opcional: crear un botón con icono como imagen (image: url)
editor.addButton(miboton_icon, {
image: url /icono-16.png, // si se tiene un icono dentro del plugin
tooltip: Mi botón con icono,
onclick: function() {
editor.insertContent([mi_shortcode])
}
})
// Registrar el botón en los menús o toolbars si se necesita
})
// Indicar a WordPress que cargue el plugin TinyMCE cuando se inicialice
// Nota: WordPress inyecta automáticamente todos los plugins que se registran
})()
Importante: el objeto mibotonData proviene de wp_localize_script en PHP y permite pasar datos de forma segura (ajax_url, nonce, textos traducibles, etc.).
Para que WordPress cargue el plugin de TinyMCE y muestre el botón en la barra, añadiremos hooks que integren el plugin con TinyMCE y añadan el nombre del botón a la lista de botones.
Con esto WordPress conocerá el plugin y añadirá el botón en la barra del editor clásico.
Paso 4 — Ejemplo de manejo AJAX (opcional)
Si el botón necesita obtener datos desde el servidor (por ejemplo, para autocompletar o generar contenido), puedes usar admin-ajax.php y pasar una nonce con wp_localize_script. Ejemplo de handler en PHP:
Datos desde AJAX,
time => current_time( mysql )
)
wp_send_json_success( result )
}
?>
Y el correspondiente uso desde JS (fetch/jQuery.ajax) puede aprovechar mibotonData.ajax_url y mibotonData.nonce.
Buenas prácticas y puntos a considerar
- Escapar y sanear: cualquier dato recibido por AJAX o por formulario debe validarse y sanearse (sanitize_text_field, wp_kses_post, etc.).
- Permisos: comprobar current_user_can en los handlers y encolar scripts sólo para usuarios apropiados.
- Compatibilidad: el código mostrado está pensado para TinyMCE4 (editor clásico). Para TinyMCE 5 o Gutenberg el enfoque cambia.
- Traducciones: si necesitas internacionalizar, usa __(), _x(), y asegurate de cargar el textdomain del plugin.
- Pruebas: probar en distintos navegadores y con distintos plugins que puedan modificar la barra de TinyMCE.
- Iconos: puedes usar dashicons para estilos, o imágenes propias en TinyMCE puedes usar la propiedad image o una clase CSS en la que uses background-image.
Ejemplo completo resumido
Resumen de los pasos clave:
- Registrar y encolar assets (JS/CSS) en admin con comprobaciones de pantalla y permisos.
- Localizar datos (ajax_url, nonce, textos) con wp_localize_script.
- Registrar el plugin TinyMCE con mce_external_plugins y añadir el botón con mce_buttons.
- Crear el plugin JS usando tinymce.PluginManager.add y editor.addButton / editor.windowManager.
- Sanear/sanitizar/validar cualquier dato enviado al servidor.
Recursos útiles
Conclusión
Añadir un botón al editor clásico de WordPress es directo si sigues la secuencia adecuada: encolar scripts, registrar el plugin TinyMCE, añadir el botón y, opcionalmente, crear diálogos o llamadas AJAX. Siguiendo las buenas prácticas de permisos, escaping y localización tendrás una integración robusta y segura.
|
|
Acepto donaciones de BAT's mediante el navegador Brave 🙂 |