Integrate new MathType Beta with CKEditor 5

This guide explains how to upgrade an existing CKEditor 5 integration to MathType plugin v9.0.0 beta and enable the new MathType editor. 

It covers installation, configuration changes, breaking changes, event migration, and rollback options.

Since this is a closed, beta-level distribution version for external testing, the instructions focus on updating via a compressed tarball (.tgz) package. To request entering the beta testing, check the details here.

Preparations before installation

Before installing this beta version, it is highly recommended that you use your preferred version control system (e.g., Git) to save your project's current state. This will allow you to safely roll back if you need to return to the current version.

• Using branches: Create a branch of the current commit with the current (8.x.x) version by running git checkout -b mathtype/v8.x.x, then push it with git push --set-upstream origin mathtype/v8.x.x.
• Using tags: Create a tag of the current commit by running git tag mathtype-v8.x.x, then push it with git push --tags.

Requirements and installation

The plugin requires CKEditor 5 version 46.0.0 or higher as a peer dependency. If your project uses an older version of CKEditor, you must upgrade it first.

To install the provided package, run the following command pointing to the .tgz file you were provided:

npm install path/to/your/file/wiris-mathtype-ckeditor5-9.x.x-beta.tgz

Note: Make sure to adjust the file path and name according to the actual file you received.

Basic configuration

The primary goal of this upgrade is to transition your integration to the new MathType editor. Unless explicitly stated otherwise in this guide, you can leave the rest of your current CKEditor configuration exactly as it is.

You can import the plugin into your CKEditor configuration as usual:

import MathType from "@wiris/mathtype-ckeditor5/dist/index.js";

Or using the modern import path:

import { MathType } from "@wiris/mathtype-ckeditor5";

Additionally, make sure you remove any CSS MathType for CKEditor 5 import, such as:

import "@wiris/mathtype-ckeditor5/dist/index.css";

New MathType editor configuration

Starting from version 9, you can access the new MathType editor by configuring it via mathTypeParameters:

Example:

mathTypeParameters: {
    editor: "modern",
    editorParameters: {
        toolbar: "general | simple",
    },
}

Important changes and considerations

If you are upgrading from a previous version, please note the following behavioral and breaking changes.

Automatic CSS loading (breaking change)

In previous versions, you had to explicitly import the plugin's CSS file (e.g., import "@wiris/mathtype-ckeditor5/dist/index.css"; ). In version >=9.0.0, styles are bundled and injected automatically.

You must remove any explicit CSS imports from your integration to avoid build errors or style conflicts.

Deprecation of the "quizzes" Toolbar

The quizzes value for the toolbar configuration is deprecated. If your integration used this value, you must change it to simple in the new version.

Supported parameters and languages

• Supported Parameters: When using the modern editor, currently only the language and toolbar parameters are supported inside editorParameters. Any other parameters will be ignored.
• Language Fallback: The available languages depend on the product configuration and may change frequently. If the language provided in your environment is not supported, the editor will default to English (en). Please consult the official MathType configuration documentation for the most up-to-date list of supported languages.ChemType interface

ChemType interface 

ChemType will continue to open using its traditional editor interface, regardless of the MathType configuration.

Editing existing formulas

When using the new editor, if a user attempts to edit a pre-existing formula whose MathML content is not fully supported, the system will automatically fall back to the classic editor for that editing session.

Deprecation of the Global WirisPlugin Object

Version 9 no longer exposes the global window.WirisPlugin object or helper functions such as window.wrs_addPluginListener and window.wrs_initParse.

If your integration uses these global APIs, migrate your event handling to MATHTYPE_EVENTS on the CKEditor instance.

How to migrate your events

Event handling must now be registered through MATHTYPE_EVENTS on the CKEditor instance. Follow these steps to migrate: 

1. Search your app code for symbols: 
   1. onBeforeFormulaInsertion
   2. onAfterFormulaInsertion
2. Replace listener registration with editor-level events 
   1. Replace onBeforeFormulaInsertion with MATHTYPE_EVENTS.BEFORE_FORMULA_INSERTION 
   2. Replace onAfterFormulaInsertion with MATHTYPE_EVENTS.AFTER_FORMULA_INSERTION

Before Insertion (MATHTYPE_EVENTS.BEFORE_FORMULA_INSERTION) allows you to intercept and mutate the formula (via the mathml property of the payload) before it is written into the model.

After Insertion (MATHTYPE_EVENTS.AFTER_FORMULA_INSERTION) provides the inserted CKEditor model node  (ModelElement).

Implementation Example

import { MATHTYPE_EVENTS } from "@wiris/mathtype-ckeditor5";

// Intercept before insertion
editor.on(MATHTYPE_EVENTS.BEFORE_FORMULA_INSERTION, (_evt, payload) => {
    console.log("Formula to insert:", payload.mathml);
});

// Observe after insertion
editor.on(MATHTYPE_EVENTS.AFTER_FORMULA_INSERTION, (_evt, payload) => {
    console.log("Inserted model node:", payload.node);
});

Optional rollback: reverting to v8.x.x

If you need to leave the beta version and return to the classic v8.x.x editor, follow these steps:

Option 1: Using version control (recommended)

If you created a tag or branch before installation, simply revert your repository to that state:

• With branch: git checkout mathtype/v8.x.x
• With tag: git checkout mathtype-v8.x.x

Option 2: Manual downgrade

If you do not have a backup in your version control, you must downgrade the packages manually:

1. Install the previous stable version by running: npm install @wiris/mathtype-ckeditor5@^8
2. Downgrade CKEditor: If you updated your CKEditor version specifically for this package, reinstall the previous version your project was using.
3. Revert code changes: Remove any version 9-specific configuration (such as editor: “modern”) from your codebase, and restore your global window.WirisPlugin listeners if you had migrated them.