Ace Code Editor
Integra el editor de código JavaScript Ace en Drupal, proporcionando resaltado de sintaxis, autocompletado y capacidades de edición de código para áreas de texto, visualización de campos y fragmentos de código incrustados.
ace_editor
Instalar
composer require 'drupal/ace_editor:^2.0'
composer require 'drupal/ace_editor:8.x-1.4'
Overview
Ace Code Editor es una integración completa de la popular biblioteca JavaScript Ace editor en Drupal. Ace es un editor de código independiente escrito en JavaScript que ofrece características de nivel profesional, incluyendo resaltado de sintaxis para más de 100 lenguajes de programación, indentación adecuada, atajos de teclado, buscar y reemplazar con soporte de expresiones regulares, y autocompletado.
Este módulo proporciona tres puntos de integración principales: (1) Un plugin de editor de texto que puede asignarse a formatos de texto, reemplazando las áreas de texto estándar con el editor Ace en los formularios de edición de contenido; (2) Un formateador de campo que muestra el contenido de campos de texto como código de solo lectura con resaltado de sintaxis; (3) Un filtro de texto que procesa etiquetas personalizadas <ace> para incrustar y mostrar fragmentos de código dentro del contenido con resaltado de sintaxis configurable.
El módulo soporta amplias opciones de personalización incluyendo selección de tema (más de 35 temas como Monokai, Cobalt, Twilight), selección de modo de sintaxis (más de 100 modos de lenguaje incluyendo PHP, JavaScript, HTML, Python, YAML), dimensiones del editor, tamaño de fuente, números de línea, márgenes de impresión, visualización de caracteres invisibles, ajuste de línea y autocompletado.
Features
- Reemplaza las áreas de texto de Drupal con el editor de código Ace, ofreciendo resaltado de sintaxis profesional y capacidades de edición de código en formularios de edición de nodos y bloques
- Soporta más de 100 modos de sintaxis de lenguajes de programación incluyendo PHP, JavaScript, HTML, CSS, Python, Ruby, Java, SQL, YAML, JSON, Markdown, y muchos más
- Proporciona más de 35 temas de colores incluyendo opciones populares como Monokai, Cobalt, Twilight, Solarized Dark/Light, Tomorrow Night y GitHub
- Habilita el autocompletado con el atajo de teclado Ctrl+Space mientras se edita código
- El formateador de campo muestra el contenido de campos de texto como código de solo lectura con resaltado de sintaxis en los modos de visualización de entidades
- El filtro de texto procesa etiquetas <ace> para incrustar fragmentos de código con resaltado de sintaxis directamente en el contenido con atributos personalizables
- Configuraciones de editor ajustables incluyendo altura, ancho, tamaño de fuente, números de línea, márgenes de impresión, caracteres invisibles y ajuste de línea
- Carga dinámicamente solo los archivos JavaScript de tema y modo requeridos para optimizar el rendimiento
- Soporta integración con formatos de texto permitiendo que el editor Ace se use con cualquier configuración de formato de texto
Use Cases
Edición de plantillas HTML/PHP en contenido
Los constructores de sitios o desarrolladores que necesitan almacenar y editar código HTML, PHP o JavaScript directamente en contenido de nodos o bloques pueden usar Ace Editor para una experiencia de codificación profesional. Configure un formato de texto con Ace como editor de texto, luego use ese formato para tipos de contenido que contengan código. Las características de resaltado de sintaxis y autocompletado hacen mucho más fácil escribir y mantener fragmentos de código.
Mostrar ejemplos de código en documentación
Los sitios de documentación técnica pueden usar el filtro Ace para incrustar ejemplos de código bellamente formateados directamente en el contenido de artículos. Los autores envuelven el código en etiquetas <ace syntax="php" theme="monokai">, y el filtro renderiza el código con resaltado de sintaxis profesional. Se pueden usar diferentes lenguajes y temas para diferentes bloques de código dentro del mismo contenido.
Visualización de campo de fragmento de código
Los tipos de contenido que incluyen un campo dedicado para almacenar código (como un campo text_long 'Ejemplo de Código') pueden usar el formateador Ace para mostrar el campo con resaltado de sintaxis en la vista de la entidad. Configure la visualización del campo para usar 'Formato Ace' y seleccione el modo de sintaxis apropiado para el contenido esperado.
Edición de archivos de configuración
Cuando los administradores del sitio necesitan editar formatos YAML, JSON u otras configuraciones directamente en la interfaz de Drupal, Ace Editor proporciona resaltado de sintaxis adecuado y retroalimentación de validación a través de señales visuales, reduciendo los errores de configuración.
Blog de desarrollador o sitio de tutoriales
Un blog de desarrollador que muestra tutoriales de código puede aprovechar las tres características: usar Ace Editor para escribir contenido de artículos, el filtro para incrustar ejemplos de código en el cuerpo, y el formateador para mostrar contenidos completos de archivos de código almacenados en campos separados. Se pueden usar múltiples temas para coincidir con la estética de diseño del sitio.
Tips
- Use Ctrl+Space para activar el autocompletado mientras edita código en el editor Ace
- La etiqueta <ace> soporta atributos para anular los ajustes predeterminados: theme, syntax, height, width, font-size, line-numbers, print-margin e invisibles
- Ejemplo: <ace theme="monokai" syntax="php" height="400px">su código aquí</ace>
- Para el filtro, los atributos booleanos como line-numbers aceptan valores '1' o '0' para habilitar o deshabilitar características
- Solo se necesita una versión de la biblioteca Ace - la versión minificada (src-min o src-min-noconflict) se recomienda para producción
- La carga dinámica de bibliotecas significa que solo se cargan los archivos de tema y modo realmente usados, optimizando el rendimiento de la página
- El formateador muestra el contenido como solo lectura - los usuarios no pueden editar el código mostrado, haciéndolo seguro para visualización en el front-end
Technical Details
Admin Pages 1
/admin/config/content/formats/manage/{format_id}
Cuando Ace Editor se selecciona como el editor de texto para un formato de texto, se hacen disponibles ajustes adicionales para configurar la apariencia y comportamiento del editor. Estos ajustes se aplican a todas las áreas de texto que usan este formato de texto.
Permisos 1
Hooks 2
hook_library_info_build
Construye dinámicamente definiciones de biblioteca para todos los temas y modos de sintaxis Ace disponibles escaneando el directorio de la biblioteca Ace en busca de archivos theme-*.js y mode-*.js.
hook_library_info_alter
Altera las definiciones de biblioteca para agregar el archivo core ace.js y ext-language_tools.js (para autocompletado) a las bibliotecas apropiadas según la ruta de biblioteca detectada.
Troubleshooting 5
La biblioteca JavaScript Ace debe estar instalada en el directorio /libraries/. Descargue ace-builds desde https://github.com/ajaxorg/ace-builds o use Composer con el repositorio npm-asset. Asegúrese de que ace.js sea accesible en una ruta como /libraries/ace/ace.js o /libraries/ace-builds/src-min/ace.js. Solo se requiere una versión (minificada, noconflict, etc.).
Verifique que: (1) El formato de texto tenga 'Ace Editor' seleccionado como editor de texto en /admin/config/content/formats, (2) El usuario tenga permiso para usar ese formato de texto, (3) La biblioteca Ace esté correctamente instalada y detectada.
Asegúrese de que el archivo mode-*.js correspondiente exista en su instalación de la biblioteca Ace. El módulo escanea dinámicamente los modos disponibles. Si falta un modo, descargue el paquete completo ace-builds que incluye todos los modos de lenguaje.
Habilite el 'Filtro Ace' para el formato de texto usado por su contenido en /admin/config/content/formats/manage/{format_id}. El filtro debe estar habilitado para que las etiquetas se procesen y muestren con resaltado de sintaxis.
El módulo intencionalmente no elimina el formato de texto 'Ace Editor' al desinstalar para preservar el contenido. Si está seguro de que ningún contenido usa este formato, desactívelo o elimínelo manualmente en /admin/config/content/formats.
Security Notes 4
- El plugin Editor está marcado como is_xss_safe = FALSE, lo que significa que el contenido no está garantizado como seguro contra XSS y debe usarse con filtros de formato de texto apropiados
- El permiso 'administer ace_editor' está marcado como acceso restringido - otorgue este permiso con cuidado
- El código mostrado a través del formateador o filtro se renderiza en modo de solo lectura, previniendo modificaciones del lado del cliente
- Cuando use el filtro con contenido enviado por usuarios, asegúrese de que otros filtros de texto apropiados estén en su lugar para sanitizar entradas potencialmente maliciosas