Note: The plug-in may continue to be updated after this article is published. See wangeditor-plugin-Formula for the latest documentation

preface

With the official release of wangEditor V5 just around the corner, I’ve developed several common third-party plug-ins to verify its extensibility. This article introduces the design and use of Formula plug-in.

To insert mathematical formulas using LateX syntax, render formulas rely on the tool KateX. Such as c = \ PM \ SQRT {a^2 + b^2} will be rendered as the formula below.

PS: this plugin does not depend on any framework, JS Vue React and other frameworks can be used normally.

use

To begin, you need to understand the most basic installation and use of wangEditor V5, refer to the documentation. Then consult the documentation for the wangeditor-plugin-formula plug-in.

Installation and Registration

Install Katex and @wangEditor /plugin-formula

yarn add katex
yarn add @wangeditor/plugin-formula
Copy the code

Registered to wangEditor

import { Boot } from '@wangeditor/editor'
import formulaModule from '@wangeditor/plugin-formula'

/ / register. Register the editor only once before creating it.
Boot.registerModule(formulaModule)
Copy the code

At this point, wangEditor is ready to display the formula, but you need to configure the menu: Insert the formula, edit the formula.

Configuration menu

Configure the toolbar to insert insertFormula and editFormula at the positions specified by index.

import { IToolbarConfig } from '@wangeditor/editor'

// Toolbar configuration
const toolbarConfig: Partial<IToolbarConfig> = {
  insertKeys: {
    index: 0./ / custom
    keys: [
      'insertFormula'.// Insert formula menu
      // 'editFormula' // 'editFormula' menu],},/ / other...
}
Copy the code

Of course, editFormula can also be configured into the hover menu in the editor

import { IEditorConfig } from '@wangeditor/editor'

const editorConfig: Partial<IEditorConfig> = {
  // Hover menu when formula node is selected
  hoverbarKeys: {
    formula: {
      menuKeys: ['editFormula'].// Edit formula menu}},/ / other...
}
Copy the code

At this point, the formula can be inserted through the menu:

When the formula node is selected, you can also edit the formula:

According to the HTML

The HTML format of the formula node obtained by executing editor.gethtml () is plain , where data-value is a string of LateX syntax.

<span data-w-e-type="formula" data-w-e-is-void data-w-e-is-inline data-value="c = \pm\sqrt{a^2 + b^2}"></span>
Copy the code

Render this as a formula card, again with KateX, easy and convenient.

katex.render("c = \\pm\\sqrt{a^2 + b^2}", spanElement, {
    throwOnError: false
})
Copy the code

Echo HTML (reedit)

The obtained HTML still supports echo to the editor and can be normally parsed into formula cards. These capabilities are already available after registering with formulaModule.

const editor = createEditor({
  selector: '#editor-container'.config: editorConfig,
  html: `
hello  world
`,})Copy the code

design

Some of the basic extension capabilities, such as registering menus, generating HTML, parsing HTML, and so on, are already available and mature in wangEditor, just refer to the documentation and the source code of the plug-in.

Editor internal render formula card

This article focuses on: How to use KateX to render formula cards in the editor? Because the rendering process in wangEditor is quite complex, as shown below:

To render with KateX is to manipulate the DOM directly, while the wangEditor internal rendering needs to create the VDOM and then patch the DOM using snabbdom.js. The two are incompatible.

The solution was to customize DOM elements. Register a < W-e-formula -card data-value=” XXX “>< W-e-formula -card> element to generate the VDOM as normal

and patch rendering.

// Build a formula VNode
const { value = ' ' } = elem as FormulaElement
const formulaVnode = h(
    'w-e-formula-card',
    {
        dataset: { value },
    },
    null
)
Copy the code

registered<w-e-formula-card>Custom elements

With KateX, it’s very simple to develop. Register a custom element and use Shadow DOM rendering internally.

import katexStyleContent from '!!!!! raw-loader! katex/dist/katex.css'
import katex from 'katex'

class WangEditorFormulaCard extends HTMLElement {
  private span: HTMLElement

  // The attR to be listened on
  static get observedAttributes() {
    return ['data-value']}constructor() {
    super(a)const shadow = this.attachShadow({ mode: 'open' }) // Shadow DOM
    const document = shadow.ownerDocument

    const style = document.createElement('style')
    style.innerHTML = katexStyleContent // Load CSS text
    shadow.appendChild(style)

    const span = document.createElement('span')
    span.style.display = 'inline-block'
    shadow.appendChild(span)
    this.span = span
  }

  // Re-render the DOM when 'data-value' changes
  attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null) {
    if (name === 'data-value') {
      if (oldValue == newValue) return
      this.render(newValue || ' ')}}// Use the KateX rendering formula
  private render(value: string) {
    katex.render(value, this.span, {
      throwOnError: false,}}}window.customElements.define('w-e-formula-card', WangEditorFormulaCard)
Copy the code

conclusion

This paper mainly

  • Formulas are rendered using LateX syntax using the KateX tool
  • The editor registers custom elements internally<w-e-formula-card>Rendering formula
  • The development of the Formula plug-in validates the full extensibility of wangEditor V5

You can submit an issue on Github if you have any problems.