logo polydile dile-components

dile-editor

Web component for implementing a rich markdown editor that allows editing in WYSIWYG mode as well as directly editing plain markdown code. It supports customization of both its appearance and the available toolbar options, making it flexible for a variety of use cases.

Installation

npm i @dile/editor

Usage

Import the component:

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

Use the component:

<dile-editor></dile-editor>

Properties

Methods

Events

CSS Custom Properties

You can customize the editor using these CSS Custom Properties.

Custom property Description Default
--dile-input-section-width Editor width 100%
--dile-editor-focus-border-color Color border on focused state 36px
--dile-input-label-font-size Font size for the label 1em
--dile-input-label-color Color for the label text #59e
--dile-input-label-font-weight Label text font weight normal
--dile-input-label-margin-bottom Label marging bottom 4px
--dile-editor-background-color Editor background color #fff;
--dile-editor-views-nav-background-color Editor views selector background color #f5f5f5
--dile-editor-views-nav-color Editor views selector text color #106eda
--dile-editor-views-nav-selected-color Editor views selected view text color #0f4e96
--dile-editor-views-nav-selected-line-color Editor views selected view line color #0f4e96
--dile-editor-toolbar-background-color Toolbar background color transparent
--dile-editor-toolbar-color Toolbar icons color #303030
--dile-icon-size Toolbar icons size 24px
--dile-input-message-padding-top Space from input to message 4px
--dile-input-message-font-size Message font size 0.875rem
--dile-input-message-color Message text color #888
--dile-input-message-error-color Message text color on errored state #c00
--dile-editor-toolbar-block-background-color Block type selector background color #eee
--dile-editor-line-height Editor content line-height 1.3rem
--dile-editor-code-background-color The background color of the code block #eee
--dile-editor-code-font-family The font family used for the code block Consolas, Monaco, "Andale Mono", "Ubuntu Mono", monospace
--dile-editor-code-font-size The font size of the code text 0.9em
--dile-editor-code-color The text color of the code block #657b83

As this component is based on many other Dile Components, like dile-select or dile-button, you can use their custom properties to change the diferent UI styles.

Toolbar option names for disabling

These are the names of the options available in the toolbar, which can be used to disable the corresponding formatting functionalities in the editor.

Adding Additional Options to the Editor Toolbar

The dile-editor component allows adding other custom actions to the editor's toolbar. To achieve this, it is possible to assign an object value to the additionalCommands property.

Syntax of the additionalCommands Object

The object to be added consists of three properties, all optional, where you can set an array of new commands. These properties place actions in different locations of the toolbar.

How to Create New Commands

To create new commands, it is necessary to use the mechanisms provided by Prosemirror, the WYSIWYG editor creation framework that dile-editor is based on. However, thanks to the code classes provided in the dile-editor component itself, it is possible to create basic commands with a bit more ease.

Let’s look at a code example to achieve this.

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

const newBold = new ToolbarItem({
  command: boldCommand,
  commandName: 'bold',
  icon: homeIcon,
});
const newImage = new ToolbarImage({
  command: linkCommand,
  commandName: 'image',
  icon: editIcon,
  dialogTemplate: (language) => html`<dile-editor-image-dialog language="${language}" id="imageDialog"></dile-editor-image-dialog>`,
});
const heading5 = {
  command: headingCommandCreator(5),
  commandName: 'h5',
};
const heading6 = {
  command: headingCommandCreator(6),
  commandName: 'h6',
};

this.additionalCommands = {
  toolbarItems: [newBold, newImage],
  blockItems: [heading5, heading6],
};

Once the additional commands object is created, we can bind it to the dile-editor component:

<dile-editor .additionalCommands=${this.additionalCommands} label="Customized Editor"></dile-editor>

dile-editor demos

Empty editor

<script type="module">
  import '@dile/editor/editor.js';
</script>
<dile-editor></dile-editor>

Disable some toolbar options

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

Using a label

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

Initialize editor with some markdown content

The markdown editor has two ways for initializing its content:

Using the value property

Setting the value property of the component's tag, which will set that text as the initial content of the component.

Using the slot content

Placing any markdown content inside the host tag as a slot. This is a much more convenient way as it easily allows you to introduce any type of content, even content that spans multiple lines, such as paragraphs, lists, headings, etc. The following example demonstrates the markdown initialization by the slot content.

# Dile editor In this editor, some options are disabled due to the property: `disableToolbarItems="h4|italic"`.
<dile-editor label="Markdown editor" disableToolbarItems="h4|italic"># Dile editor
In this editor, some options are disabled due to the property: `disableToolbarItems="h4|italic"`.
</dile-editor> 

Styled editor

### I have some styles Do you like them? - Yes - No
<style>
  .styled {
  --dile-editor-background-color: #ffc;
  --dile-editor-views-nav-background-color: rgb(171, 111, 0);
  --dile-editor-views-nav-color: #ffc;
  --dile-editor-toolbar-background-color: #f4f4f4;
  --dile-editor-toolbar-color: rgb(171, 111, 0);
  --dile-input-color: rgb(171, 111, 0);
  --dile-icon-size: 18px;
  --dile-editor-border: 2px solid #666;
  }
</style>
<dile-editor class="styled">### I have some styles

Do you like them?       

- Yes
- No
</dile-editor>

Editor with new custom options

<script type="module">
  import { LitElement, html, css } from 'lit';
  import { ToolbarItem, ToolbarImage } from '@dile/editor/src/prosemirror/toolbar-item.js'
  import { homeIcon, photoIcon } from '@dile/icons';
  import {
    boldCommand,
    headingCommandCreator,
    linkCommand,
  } from '@dile/editor/src/prosemirror/markdown-commands.js';
  export class DileEditorCustomized extends LitElement {
    static styles = [
      css`
        :host {
          display: block;
        }
      `
    ];
  
    constructor() {
      super();
      const newBold = new ToolbarItem({
        command: boldCommand,
        commandName: 'bold',
        icon: homeIcon,
      });
      const newImage = new ToolbarImage({
        command: linkCommand,
        commandName: 'image',
        icon: photoIcon,
        dialogTemplate: (language) => html`<dile-editor-image-dialog language="${language}" id="imageDialog"></dile-editor-image-dialog> `,
      });
      const heading5 = {
        command: headingCommandCreator(5),
        commandName: 'h5',
      };
      const heading6 = {
        command: headingCommandCreator(6),
        commandName: 'h6',
      };

      this.additionalCommands = {
        toolbarItems: [newBold, newImage],
        blockItems: [heading5, heading6],
      }
    }
    render() {
      return html`
        <dile-editor .additionalCommands=${this.additionalCommands} label="Customized Editor"></dile-editor>
      `;
    }
  }
  customElements.define('dile-editor-customized', DileEditorCustomized);
</script>
<dile-editor-customized></dile-editor-customized>