Detailed example of inserting custom HTML records in Quill editor

It is already 2020. Hungry humans are no longer satisfied with simple texts, so there are fancy texts with various styles. However, having texts is not enough. We also need to allow users to insert various custom message types when editing, so that the soft articles we send out will be more beautiful. Therefore, this article is written.

Preface

Due to the rich text filtering that comes with the Quill editor (most mainstream editors will filter rich text), developers encounter a lot of trouble when they want to configure custom HTML templates.

1. Quill rendering logic analysis

In order to customize the HTML block content in Quill, you first need to understand Quill's internal rendering process. Here are a few key concepts to understand:

1. Delta

Delta is a data format defined within Quill, which is used to represent document content and document modification operations. It is easy to read and has a simple format. Document content is maintained in the form of Delta. HTML content and Delta can be converted into each other.

For example:

Such a rich text will be represented in the following format:

{  
"ops":[ 
{"insert":"this is a simple text.\\nbut when "}, 
{"attributes":{"bold":true},"insert":"it is "}, 
{"insert":"not bold.\\nlet me try "}, 
{"attributes":{"italic":true},"insert":"italic "}, 
{"insert":"haha\\nwhat about "}, {"attributes": 
{"italic":true,"bold":true},"insert":"both"}, 
{"insert":" ?\\n"} ]  
}"

Ordinary text will be defined as insert actions, each item represents a delta, which is a description of the text content.

Similarly, if modification or deletion occurs, a corresponding delta will be generated, and then the newly generated change delta will be merged with the original delta to generate a new delta. (Delta contains three operations: insert, delete, retain)

Keep the first 10 characters and bold the following 20 characters. The delta is as follows:

{
  "ops": [
    { "retain": },
    { "retain": , "attributes": { "bold": } }
  ]
}

Keep the first 10 characters and delete the following 20 characters as follows:

{
  "ops": [
    { "retain": },
    { "delete": }
  ]
}

2. Parchment

Parchment is an abstract document model that manages Blots.

If Parchment is understood as a complete DOM tree structure, then Blot is a single node in it. In addition to the default ones in Quill, Blot also allows us to customize it, providing more room for expansion.

3. Blot

Blot is a component of the Parchment document, which is equivalent to the abstraction of the DOM node type. However, a specific Blot instance still contains other node information.

The global root node Blot is a Scroll type Blot customized by Quill, which manages all the Blots under it.

For the implementation definition of Blot, please refer to here: https://github.com/quilljs/parchment#blots

The default definition of Blot in Quill is as follows:

Common ones include TextBlot (ordinary text in a line), Inline (ordinary text with styles in a line), Block (block-level line, usually in paragraphs p), Break (line break), Image (image IMG insertion), and Bold (bold text).

How does a piece of HTML construct a Blot? Quill will prioritize excluding text nodes based on the node type. If it is an element node, it will be judged again based on the node's ClassName. If a matching BlotName still cannot be found, the following mapping relationship will be matched by default to find the corresponding BlotClass.

4. The practical significance of Delta

Since we already have Blot to represent our content structure, why do we still need Delta? Delta itself is just a maintenance of content data. That is to say, any update of HTML, whether it is user input or API operation, will be synchronously updated to Delta. If Delta is not used as the data source of HTML, then what is the point of maintaining a copy of Delta data?

If HTML => Delta, but Delta=>HTML does not exist, then what is the point of constantly maintaining a delta?

1. Generating HTML from Delta actually exists, but its application scenario is limited to initializing the document. Quill will parse the incoming initialization HTML string and generate the corresponding Delta. Then, by applying Delta, it will generate a DOM node and display it on the page.

2. You may still not be satisfied with this. Why do we have to go through this process? Can't we just use a string document.getElementById('container').innerHTML = val during initialization? Yes, you can, but the existence of Delta makes the user's document more granular, easier to maintain, and traceable. If A and B are editing a document at the same time, and A deletes 10 characters in the second line, there is no need to update the entire document content. Instead, A only needs to submit an action to synchronize his own behavior, and B only needs to resolve the conflict and then merge. Although Delta maintenance makes the logic more complicated, its existence also allows for more possibilities for document expansion.

5. Editor rendering and update process

There are three ways to modify the content:

1. Initialize the editor content: Initialize the call to quill.pasteHTML, and echo it to the edit box after HTML filtering and parsing.

2. Input Event: User input and editing operations are monitored and processed by MutationObserver to update delta.

3. API call: Call the internally provided API through the modify method, and then call the method of the global Scroll instance to modify it.

2. Insert a custom HTML block

As article content becomes more and more diverse, there is a need to insert maps, music players, advertising panels, etc. into articles, which requires us to expand the rich text editor with more functions. But at the same time, we must also do a good job of xss protection attack.

According to the first part, we need to insert a custom HTML block and Quill must be able to recognize it. You must have thought of it, we need to customize a Blot. By defining the Blot method, Quill can recognize our HTML block display during initialization, and it also prevents Quill from filtering dirty HTML when inserting HTML blocks.

The registration Blot method is as follows:

export default function (Quill) {
  // Import BlockEmbed from the source code
  const BlockEmbed = Quill.import('blots/block/embed');
  // Define a new blot type class AppPanelEmbed extends BlockEmbed {
    static create(value) {
      const node = super.create(value);
      node.setAttribute('contenteditable', 'false');
      node.setAttribute('width', '100%');
      // Set custom html
      node.innerHTML = this.transformValue(value)
      return node;
    }

    static transformValue(value) {
      let handleArr = value.split('\n')
      handleArr = handleArr.map(e => e.replace(/^[\s]+/, '')
        .replace(/[\s]+$/, ''))
      return handleArr.join('')
    }

    // Return the value of the node itself for undoing the operation static value(node) {
      return node.innerHTML
    }
  }
  // blotName
  AppPanelEmbed.blotName = 'AppPanelEmbed';
  // The class name will be used to match the blot name AppPanelEmbed.className = 'embed-innerApp';
  // Customize tag type AppPanelEmbed.tagName = 'div';
  Quill.register(AppPanelEmbed, true);
}

Next you just need to call it like this to insert a custom HTML block into the editor:

quill.insertEmbed(quill.getSelection().index || 0, 'AppPanelEmbed', `
          <div class="app_card_header">     
              Custom panel title</div>
          <div class="app_card_content">     
              Customize panel content</div>
          <div class="app_card_footer">     
              footer
          </div>
      `);

The parameter format requirements are as follows:

insertEmbed(index: Number, type: String, value: any, source: String \= 'api'): Delta

This is just a simple example. If you want to enrich the functions of custom Blot, you can refer to: https://github.com/quilljs/parchment#blots

Since the contenteditable attribute is released, in order to prevent XSS attacks, we need to perform special filtering on this attribute. Here we take the XSS module processing as an example:

handleWithXss(content) {
      const options = {
        whiteList: {
         ...
          div: ['class', 'style', 'data-id', 'contenteditable'],
         ...
        },
        css: {
          whiteList: {
            color: true,
            'background-color': true,
            'max-width': true,
          },
        },
        stripIgnoreTag: true,
        onTagAttr: (tag, name, value, isWhiteAttr) => {
          // Processing contenteditable for div if (isWhiteAttr && tag === 'div' && name === 'contenteditable') {
            return 'contenteditable="false"';
          }
        },
      } // Custom rules const myxss = new xss.FilterXSS(options)
      return myxss.process(content)
    }

This is the end of this article about inserting custom HTML records in Quill editor. For more relevant Quill editor custom HTML content, please search 123WORDPRESS.COM’s previous articles or continue to browse the related articles below. I hope you will support 123WORDPRESS.COM in the future!