CK Editor v5 - plugin

The Equation Editor plugin for CK Editor

Usage

To create a new equation, first click within the text area where you need to add the equation.
Click the `fx` button on the CK Editor toolbar, to launch the CodeCogs Equation Editor.
Create your equation.
Select Ok to insert the equation into your document at the cursor position.
Double-click existing equations to edit them in the Equation Editor.

Quick Installation with NPM

In your existing npm project with CKEditor v5 already installed, find the directory with package.json, open a terminal and run:
```
  npm install @codecogs/eqneditor-ckeditor5
```

Find where CKEditor v5 is imported and instantiated and add the Equation Equation Editor elements to load the plugins and add a button to the toolbar:

Typical CKEditor imports:

import Essentials from '@ckeditor/ckeditor5-essentials/src/essentials';
import Bold from '@ckeditor/ckeditor5-basic-styles/src/bold';
import Italic from '@ckeditor/ckeditor5-basic-styles/src/italic';
import Heading from '@ckeditor/ckeditor5-heading/src/heading';
import Paragraph from '@ckeditor/ckeditor5-paragraph/src/paragraph';
...

Additional imports for the Equation Editor:

import Eqneditor5 from '@codecogs/eqneditor-ckeditor5/src/eqneditor5';
import Image from '@ckeditor/ckeditor5-image/src/image';
import MediaEmbed from '@ckeditor/ckeditor5-media-embed/src/mediaembed';

CKEditor Instantiation:

ClassicEditor
  .create( document.querySelector( '#editor' )) {
  	plugins: [
      Essentials,
      Bold,
      Italic,
      Heading,

      /* ... Other required plugins */

      Image,          /* Need by EqnEditor 5 */
      MediaEmbed,     /* Need by EqnEditor 5 */
      EqnEditor5      /* Core of EqnEditor 5 */
    ],
    toolbar: [
      'undo', 'redo',
      '|',
      'EqnEditor5', /* Added fx button for EqnEditor 5 */
      'bold', 'italic', 
    ]
});

The CodeCogs Equation Editor will now appear in the toolbar group you specified when creating the editor.

General Installation (for Vanilla Websites)

It is not possible to integrate the Equation Editor into CKEditor without using NPM. So for more traditional website that do not need or use additional web frameworks or libraries managed by NPM, we build a custom `ckeditor5.js` that contains the plugins required, including the Equation Editor.

Warning:If you using CKEditor from a CDN, as shown in this example below then you need to follow these instructions.

Example of CDN code for CKEditor that must be changed (full code is here):

<script type="importmap">
{
    "imports": {
        "ckeditor5": "https://cdn.ckeditor.com/ckeditor5/43.0.0/ckeditor5.js",
        "ckeditor5/": "https://cdn.ckeditor.com/ckeditor5/43.0.0/"
    }
}</script>

Follow these steps:

Download the source files you need, from either:
- or you can download the original files from the git ckeditor5-build-classic repository.
```
git clone https://github.com/ckeditor/ ckeditor5-build-classic.git
```
  This library was last updated in 2020 so it now requires some changes to work as we need
Install the NPM dependencies (these are defined in `package.json`)
```
cd ckeditor5-build-classic
npm install
```

If you see errors, then some dependencies listed in `package.json` maye be out of date. We were able to update them with:

npm install stylelint@latest postcss-unique-selectors@latest stylehacks@latest sugarss@latest --save-dev 
npm install postcss-loader@latest --save-dev
npm audit fix --force

Install our Equation Editor plugin for CKEditor from NPM:
```
npm install @codecogs/eqneditor-ckeditor5
```

Edit `src/ckeditor.js' and customise to include the plugins and toolbar elements you need:

/**
 * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
 * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
 */

// The editor creator to use.
import ClassicEditorBase from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';

import Essentials from '@ckeditor/ckeditor5-essentials/src/essentials';
import Bold from '@ckeditor/ckeditor5-basic-styles/src/bold';
import Italic from '@ckeditor/ckeditor5-basic-styles/src/italic';
import Heading from '@ckeditor/ckeditor5-heading/src/heading';
import Paragraph from '@ckeditor/ckeditor5-paragraph/src/paragraph';

import Indent from '@ckeditor/ckeditor5-indent/src/indent';
import IndentBlock from '@ckeditor/ckeditor5-indent/src/indentblock';

import FontSize from '@ckeditor/ckeditor5-font/src/fontsize';
import FontColor from '@ckeditor/ckeditor5-font/src/fontcolor';
import FontBackgroundColor from '@ckeditor/ckeditor5-font/src/fontbackgroundcolor';

import List from '@ckeditor/ckeditor5-list/src/list';

// Following are essential for CodeCogs Equation Editor
import Image from '@ckeditor/ckeditor5-image/src/image';
import MediaEmbed from '@ckeditor/ckeditor5-media-embed/src/mediaembed';
import EqnEditor5 from '@codecogs/eqneditor-ckeditor5/src/eqneditor5';


export default class ClassicEditor extends ClassicEditorBase {}

// Plugins to include in the build.
ClassicEditor.builtinPlugins = [
  Essentials,
  Bold,
  Italic,
  Heading,
  Indent, IndentBlock,
  FontSize, FontColor, FontBackgroundColor,
  List,
  Image,        /* Need by EqnEditor 5 */
  MediaEmbed,     /* Need by EqnEditor 5 */
  EqnEditor5      /* Core of EqnEditor 5 */
];

// Editor configuration.
ClassicEditor.defaultConfig = {
  toolbar: {
    items: [
      'undo', 'redo',
      '|',
      'EqnEditor5', /* Added fx button for EqnEditor 5 */
      'bold', 'italic', 
      '|',
      'numberedList', 'bulletedList', 'outdent', 'indent',
      '|',
      'heading', 'fontsize', 'fontColor', 'fontBackgroundColor'
    ]
  },
  // This value must be kept in sync with the language defined in webpack.config.js.
  language: 'en'
};

If you do this right then you should have a smaller CKEditor library that will make your website more responsive.

Unfortunately, because the git repository is a few years old, you also need to update the file `webpack.config.js` so the last module section looks like this:

   ...
    module: {
    rules: [
      {
        test: /\.svg$/,
        use: [ 'raw-loader' ]
      },
      {
        test: /\.css$/,
        use: [
          {
            loader: 'style-loader',
            options: {
              injectType: 'singletonStyleTag',
              attributes: {
                'data-cke': true
              }
            }
          },
          'css-loader',
          {
            loader: 'postcss-loader',
            options: {
              postcssOptions: styles.getPostCssConfig({
                themeImporter: {
                  themePath: require.resolve('@ckeditor/ckeditor5-theme-lark')
                },
                minify: true
              })
            }         
          }
      ...

Compile the library together to create your own custom library:
```
npm run build
```
Copy all the files (and any sub-directories) in the directory `build/` to a publicly accessible folder within your website, e.g.
```
cp build/* WEBSITE/public/js/
```

You can now use the CKEditor with the Equation Editor in your website:

Example code for a fully working editor:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <script src="/js/ckeditor.js"></script>
    <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/43.0.0/ckeditor5.css" />
  </head>
  <body>
    <p>Example CK Editor with Equation Editor:</a></p>

    <textarea id="editor5" name="editor5"></textarea>
    <script>
      ClassicEditor
          .create( document.querySelector( '#editor5' ) )
          .catch( error => {
              console.error( error );
          } );
    </script>
  </body>
</html>

OR change these lines from the CKEditor example (full code is here):

<script type="importmap">
{
    "imports": {
        "ckeditor5": "/js/ckeditor5.js",
        "ckeditor5/": "https://cdn.ckeditor.com/ckeditor5/43.0.0/"
    }
}</script>

All the file above and the extended `ckeditor.js` are also available here:

Change History

v1.2 (deprecated) - Our first version for CKEditor v4, which builds on our earlier version for CKEditor v3
v1.3 (deprecated) - Improvement support for secure websites. Fixed bug that prevented equations being edited.
v2 - Improved integration with the CKEditor, using CKEditor dialogs that appear on page.
v2.1 - Bug fix that allows more Eqn plugins to work with multiple edit areas on a single page.
v2.2 - General update in line with the movement of CodeCogs to new servers. (Recommended upgrade).
v3 - Adds compatibility for CKEditor v5.