CKEditor5 Template
Un plugin de CKEditor 5 para Drupal que permite insertar plantillas de contenido HTML predefinidas en el editor de texto enriquecido a través de un práctico menú desplegable en la barra de herramientas.
ckeditor5_template
Instalar
composer require 'drupal/ckeditor5_template:^1.0'
Overview
CKEditor5 Template es un módulo contribuido de Drupal que integra funcionalidad de inserción de plantillas en CKEditor 5. Es el sucesor del módulo legacy ckeditor_template, que solo soportaba CKEditor 4. Este módulo permite a los editores de contenido insertar rápidamente fragmentos HTML predefinidos, como bloques de texto de uso frecuente, tablas o estructuras de contenido formateado, directamente desde la barra de herramientas del editor.
El módulo añade un botón personalizable "Template" a la barra de herramientas de CKEditor 5. Al hacer clic, muestra un menú desplegable poblado con plantillas definidas en un archivo JSON externo. Cada plantilla puede tener su propio icono, título, descripción (mostrada como tooltip) y contenido HTML. Los editores de contenido simplemente pueden hacer clic en una plantilla para insertarla en la posición actual del cursor en el editor.
Los administradores del sitio pueden configurar qué archivo JSON de plantillas usar por formato de texto, permitiendo diferentes conjuntos de plantillas para diferentes tipos de contenido o roles de usuario. La apariencia del botón de la barra de herramientas también puede personalizarse, incluyendo si se muestra una etiqueta de texto junto al icono.
Features
- Añade un botón Template en la barra de herramientas con menú desplegable a CKEditor 5
- Soporta plantillas HTML personalizadas ilimitadas definidas en un archivo JSON
- Cada plantilla puede tener un icono SVG personalizado, título, tooltip descriptivo y contenido HTML
- Configurable por formato de texto, permitiendo diferentes conjuntos de plantillas para diferentes casos de uso
- Las plantillas se cargan dinámicamente desde un archivo JSON externo
- El botón de la barra de herramientas puede mostrar una etiqueta de texto opcional junto al icono
- Incluye un archivo JSON de ejemplo para comenzar rápidamente
- El menú desplegable soporta desplazamiento cuando hay muchas plantillas definidas
- Funciona con Drupal 10.3+ y Drupal 11
Use Cases
Bloques de contenido estandarizados para equipos de marketing
Los equipos de marketing a menudo necesitan insertar contenido promocional estandarizado, bloques de llamada a la acción o secciones de contenido con marca. Crea plantillas para elementos de marketing comunes como cajas de suscripción a boletines, bloques de destacados de productos o banners promocionales. Esto asegura la consistencia de marca en todo el contenido mientras ahorra tiempo a los creadores de contenido.
Inserción de texto legal y de cumplimiento
Las organizaciones que necesitan incluir texto legal estándar, descargos de responsabilidad, avisos de copyright o declaraciones de cumplimiento pueden crear plantillas para estos bloques de texto recurrentes. Esto asegura que se use la redacción exacta aprobada cada vez y reduce el riesgo de errores u omisiones.
Plantillas para documentación técnica
Para sitios con documentación técnica, crea plantillas para estructuras comunes como ejemplos de código con texto explicativo, cajas de advertencia/nota/consejo, formatos de instrucciones paso a paso o patrones de documentación de API. Esto ayuda a mantener un estilo de documentación consistente en todo el sitio.
Formatos de notas de prensa y artículos de noticias
Los sitios de noticias y medios pueden proporcionar plantillas para formatos estándar de notas de prensa, bloques de citas de entrevistas, patrones de atribución de imágenes o encabezados de secciones de artículos. Esto ayuda a mantener los estándares de estilo periodístico mientras acelera la creación de contenido.
Bloques de contenido para boletines por correo electrónico
Al crear contenido que se usará en boletines por correo electrónico, las plantillas pueden proporcionar secciones preformateadas que se sabe que se renderizan correctamente en clientes de correo electrónico, incluyendo diseños basados en tablas, encabezados con estilo y botones de llamada a la acción.
Contenido multilingüe con estructura consistente
Para sitios multilingües, las plantillas pueden ayudar a asegurar que el contenido traducido mantenga el mismo formato estructural en todos los idiomas. Los traductores pueden enfocarse en el contenido del texto mientras la estructura HTML permanece consistente.
Tips
- Crea tu archivo JSON de plantillas en un directorio de tema o módulo personalizado en lugar de en la carpeta del módulo ckeditor5_template para evitar perder cambios durante las actualizaciones del módulo
- Usa títulos de plantilla significativos y descriptivos ya que aparecen en el menú desplegable y deben ser instantáneamente reconocibles para los editores de contenido
- Incluye iconos SVG personalizados para las plantillas para hacerlas visualmente distinguibles en el menú desplegable
- Mantén el HTML de las plantillas simple y semántico - los estilos complejos deben manejarse por el CSS de tu tema, no por estilos en línea en las plantillas
- Prueba las plantillas con todos tus filtros de texto habilitados para asegurar que la salida HTML no se elimine o altere inesperadamente
- Para sitios con muchas plantillas, organízalas lógicamente en el archivo JSON ya que aparecen en orden en el menú desplegable
- Considera crear diferentes archivos de plantillas para diferentes formatos de texto (ej., plantillas más simples para formatos de texto básicos, más complejas para formatos HTML completos)
- El menú desplegable se desplaza automáticamente cuando tienes muchas plantillas, limitado al 50% de la altura del viewport
Technical Details
Admin Pages 1
/admin/config/content/formats/manage/{format}
Los ajustes del plugin Template están integrados dentro de la configuración de la barra de herramientas de CKEditor 5 para cada formato de texto. Después de añadir el botón Template a la barra de herramientas activa, hacer clic en su icono de engranaje revela las opciones de configuración para la ubicación del archivo de plantillas y la apariencia del botón de la barra de herramientas.
Troubleshooting 5
Asegúrate de que la ruta del archivo de plantillas sea relativa al directorio raíz de Drupal y comience con una barra diagonal (ej., /sites/default/files/templates/my-templates.json). Verifica que el archivo exista en esa ubicación y tenga los permisos de lectura adecuados.
Verifica que tu archivo JSON tenga un formato JSON válido. Usa un validador JSON para verificar la sintaxis. Asegúrate de que cada plantilla tenga al menos las propiedades 'title' y 'html'. Revisa la consola del navegador en busca de errores de JavaScript que puedan indicar problemas al cargar el archivo de plantillas.
Esto usualmente indica que el archivo JSON de plantillas no se puede obtener. Revisa la pestaña Network en las herramientas de desarrollador del navegador para ver si la solicitud del archivo JSON está fallando. Las causas comunes son rutas de archivo incorrectas, archivos faltantes o problemas de permisos del servidor.
Los filtros de tu formato de texto pueden estar modificando el HTML. Verifica qué filtros están habilitados (ej., 'Limitar etiquetas HTML permitidas') y asegúrate de que permitan los elementos HTML usados en tus plantillas. Puede que necesites añadir etiquetas permitidas a la configuración de tu filtro.
Asegúrate de que el valor del icono sea contenido SVG válido que comience con '<svg'. Todo el marcado SVG debe incluirse como cadena en el JSON. Un SVG inválido causará que el módulo use el icono de plantilla predeterminado.
Security Notes 4
- El contenido HTML de las plantillas se inserta directamente en el editor sin sanitización a nivel del plugin. Asegúrate de que tu formato de texto tenga los filtros apropiados habilitados para sanitizar la salida cuando se muestre el contenido
- Solo los administradores de confianza deben tener acceso para modificar los archivos JSON de plantillas, ya que pueden contener HTML arbitrario incluyendo scripts
- El archivo de plantillas debe ser accesible mediante solicitud HTTP desde el navegador. No almacenes archivos de plantillas que contengan información sensible en ubicaciones accesibles públicamente
- Considera usar el sistema de configuración de Drupal o un módulo personalizado para gestionar las plantillas si necesitas control de versiones y registros de auditoría para los cambios en las plantillas