En este artículo quiero enseñarte a implementar rápidamente un campo de edición de texto enriquecido que entrega Markdown como respuesta. Eso quiere decir que puedes tener una especie de textarea en tu web, en un formulario, y que el usuario pueda editar el texto aplicando estilos en lo que yo le llamo "vista diseño". Luego puedes obtener el código markdown de aquello que has introducido en el campo editable.

Lo haremos usando un componente web, un custom element del estándar de Web Components, por lo que puedes usar este mismo componente en todo tipo de aplicaciones, desde un formulario HTML básico, que envía los datos a una página PHP de toda la vida, hasta un componente de toma de datos realizado en una aplicación frontend que podría estar perfectamente implementada en una librería como React o un framework como Angular, Vue, etc.

Este componente es público y lo puedes usar fácilmente, simplemente con instalarlo en tu proyecto vía npm. La documentación completa la tienes en la página del Editor Markdown dile-editor. En este artículo te vamos a explicar más detalladamente cómo usarlo.

Algunos puntos que vamos a cubrir en el artículo Implementar un campo de formulario que produce markdown con dile-editor:

• ¿Qué es dile-editor?
• Cómo implementar el editor markdown dile-editor
• Características principales de dile-editor
• Eventos personalizados
• Personalización de estilos del editor markdown
• Ejemplos prácticos de uso de dile-editor
• Cómo añadir tus propios botones

¿Qué es dile-editor?

dile-editor es un web component que ofrece una experiencia de edición enriquecida (tipo WYSIWYG), pero también permite al usuario alternar al modo de código markdown. Por lo tanto, ofrece las posibilidades de editar el texto en "vista diseño" como en "vista de código markdown" (para quienes conocen el lenguaje y desean un control más fino sobre lo que están produciendo).

Este componente te servirá si necesitas implementar un editor de texto enriquecido en una página web que te devuelva el texto en el lenguaje Markdown, que es ideal para recibir la entrada de datos por parte del usuario, ya que se trata de un lenguaje muy seguro donde no te pueden introducir elementos conflictivos como scripts o iframes que sí podrían colarse en el HTML.

Si trabajas en la web y buscas algo flexible, extensible y sencillo de usar es ideal para ti, ya que dile-editor lo puedes usar en cualquier proyecto donde funcione Javascript, independientemente si usas Javascript nativo o usas un framework frontend.

El componente dile-editor está basado en ProseMirror, una potente herramienta para construir editores de texto personalizados que hemos explicado ya en nuestro Manual de Prosemirror. No necesitas saber Prosemirror para usarlo, aunque si quieres extenderlo creando tus propias herramientas en la toolbar (como veremos más adelante) te vendría bien conocer esa librería.

Cómo implementar el editor markdown dile-editor

A continuación te explicamos los pasos para integrarlo en tu proyecto, y cómo sacar partido a este editor con ejemplos concretos.

Lo puedes usar como un campo de formulario o como parte de una aplicación más compleja. Además, puedes personalizar su aspecto, controlar su barra de herramientas, e incluso añadir tus propios comandos.

Instalación rápida

Lo más cómodo para usar este componente es instalarlo mediante npm, como hacemos con cualquier otra librería Javascript. Lo consigues con este comando.

npm i @dile/editor

Importar el componente dile-editor

Luego simplemente necesitas importar el componente en tu código Javascript, que haces con la sentencia import del lenguaje.

import '@dile/editor/editor.js';

Observa que hemos importado este componente por medio del nombre del package npm. Si estás familiarizado con el desarrollo frontend esto no debería sorprenderte, pero si no es así cabe decir que para que esto funcione necesitarás usar algo como Vite o Webpack. Estas son herramientas muy habituales en cualquier tipo de proyecto web moderno.

Y luego simplemente tendrás que usar el componente dile-editor en tu HTML, por medio de la siguiente etiqueta:

<dile-editor></dile-editor>

Características principales de dile-editor

El componente dile-editor está pensado para funcionar en muchos tipos de contextos, aunque manteniendo su sencillez de funcionamiento. Vamos a ver las propiedades que te permiten adaptarlo a tu caso de uso:

• value: El contenido markdown actual.
• label: Texto que sirve como etiqueta para el campo. Es opcional pero permite poner un texto encima del editor para explicar el contenido que se solicita escribir en el.
• viewSelected: Modo de vista, lo que permite decir el tipo de edición que se está realizando (las opciones posibles son editor o markdown).
• disableToolbarItems: Puedes desactivar botones de la toolbar con una simple cadena con cadenas separadas por una tubería ("h3|italic|link").
• additionalCommands: Esta es la herramienta que sirve para añadir botones personalizados a la barra. Te lo explicamos más abajo.
• language: Idioma del editor (actualmente soporta "es" y "en" pero podrías crear otras adaptaciones a otros idiomas).
• errored: muestra el estado del componente como que tiene un error.
• hideErrorOnInput: Hace qie los estilos visuales de error desaparezcan cuando el usuario cambia el contenido del editor.
• message: Una cadena que aparece en la parte de abajo del editor, que puedes usar para cualquier cosa, como una ayuda para explicar como se usa o lo que se espera de este campo, pero que típicamente usamos para conseguir mostrar los motivos por los que un componente tiene un error.
• name: No es especialmente una propiedad del componente pero la puedes usar si quieres que este componente pueda entregar o enviar los datos como un campo nativo de formulario.

Eventos personalizados

Además, puedes escuchar el evento element-changed, que se dispara cada vez que el contenido cambia:

editor.addEventListener('element-changed', (e) => {
  console.log('Contenido actualizado:', e.detail.value);
});

Personalización de estilos del editor markdown

Como otros web components del catálogo dile-components, puedes usar CSS custom properties para adaptar completamente su aspecto visual:

dile-editor {
  --dile-editor-background-color: #fffbe6;
  --dile-editor-toolbar-color: #b36b00;
  --dile-icon-size: 20px;
}

Puedes ver la lista completa de custom CSS properties en la página de documentación del componente.

Ejemplos prácticos de uso de dile-editor

Vamos a ver ahora algunos ejemplos sencillos de implementación del editor markdown. En realidad verás que es tan sencillo como usar una etiqueta HTML.

Editor básico con etiqueta

Algo típoco sería usar el editor con una etiqueta para encabezarlo.

<dile-editor label="Comentarios:"></dile-editor>

Editor con funciones deshabilitadas

Si necesitas desactivar algunas de las funcionalidades del toolbar puedes hacerlo así.

<dile-editor disableToolbarItems="h1|h2|italic|link"></dile-editor>

El listado completo de opciones disponibles, con las cadenas que tienes que usar para deshabilitarlas la tienes en la página de documentación de dile-editor.

Editor con contenido inicial

Si necesitas cargar un contenido inicial al editor puedes hacerlo escribiendo ese contenido dentro de la etiqueta del componente, de esta manera.

<dile-editor>
# Bienvenido al editor markdown

En este campo de texto puedes colocar contenido enriquecido o bien código escrito en **markdown**.
</dile-editor>

Por supuesto, también podrías setear el valor de la propiedad value del editor para cambiar su contenido.

editor.value = 'Nuevo contenido para colocar **en el editor markdown**.

Usar el elemento en un formulario nativo

Este componente lo puedes usar perfectamente en un formulario HTML de toda la vida. A la etiqueta <dile-editor> simplemente le tienes que poner un atributo name para indicar el nombre de la variable que se enviará con el código markdown de lo que el usuario haya escrito en el editor.

Aquí tendrías un ejemplo de uso, que envía los datos a una página llamada procesar.php. Para que funcione solamente tienes que incluir el import del componente en tu bundle Javascript.

<form method="POST" action="http://localhost:8000/procesar.php">
  <dile-editor id="editor" name="contenido_markdown" label="Tu contenido"></dile-editor>
  <br><br>
  <button type="submit">Enviar</button>
</form>

Para usar este campo de texto enriquecido no tienes que hacer nada en especial en tu página PHP, ya que el contenido enviado por el dile-editor se entrega como cualquier otro elemento de formulario nativo que puedas haber usado antes.

<?php
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $contenido = $_POST['contenido_markdown'] ?? '';
    echo "<h1>Contenido recibido</h1>";
    echo "<pre>" . htmlspecialchars($contenido) . "</pre>";
}
?>

Cómo añadir tus propios botones

Puedes añadir botones personalizados con cualquier acción. No es algo trivial pero puedes conseguirlo de una manera relativamente sencilla, ya que dile-editor expone una API para ampliar la toolbar con tus propios comandos.

En principio en el package de @dile/editor encuentras algunas clases que pueden facilitarte crear comandos básicos, como veremos en un ejemplo un poco más abajo. Si necesitas implementar funcionalidades más avanzadas, tendrás que lidiar un poco con componentes ofrecidos por Prosemirror.

Esto es ideal si quieres crear, por ejemplo, un botón personalizado para insertar emojis, imágenes de una biblioteca de medios personal, un bloque especial que genere contenido prefabricado o incluso atajos para estructuras comunes.

Vamos a ver aquí un ejemplo simplificado al máximo simplemente para que sirva de orientación.

import { ToolbarItem } from '@dile/editor/src/prosemirror/toolbar-item.js';
import { boldCommand } from '@dile/editor/src/prosemirror/markdown-commands.js';
import { homeIcon } from '@dile/icons';

const customBold = new ToolbarItem({
  command: boldCommand,
  commandName: 'bold',
  icon: homeIcon,
});

this.additionalCommands = {
  toolbarItems: [customBold]
};

Luego lo usas así:

<dile-editor .additionalCommands=${this.additionalCommands}></dile-editor>

Conclusión

Esto ha sido una presentación sencilla de las posibilidades y modos de uso de dile-editor. Espero que te haya parecido útil y puedas implementarlo en tus proyectos. Si tienes cualquier duda nos puedes preguntar en la sección de FAQs.

Gracias a dile-editor dispones de u editor markdown flexible, que puedes usarlo para trabajar en modo WYSIWYG y código plano en formato markdown. Además puedes adaptarlo para cambiar su aspecto visual vía CSS y personalizar los comandos de la interfaz para ajustarlo a tus necesidades particulares.

Lo bueno es que puedes usarlo para todo tipo de proyectos, desde un CMS o una solicitud de datos sencilla de un formulario, en una página PHP pero también en un proyecto frontend con cualquier framework. Este componente es suficientemente sencillo, ligero y versátil para que puedas adoptarlo en cualquer proyecto con una buena experiencia de usuario.