@deskpro/content-editor

This core package abstracts away the ProseMirror-specific configuration and setup to enable better extensibility, regardless of the target framework or UI.

Getting Started

This package contains most of the base ProseMirror-related logic and implements a robust extension system strongly inspired by tiptap's own extension system.

Usage

Usually, you would want to grab a wrapper package to use on top of this core package. For React, this is where @deskpro/react-content-editor comes in. Only React is fully-supported by this editor at the moment.

Regardless, this core content-editor package contains the base functionality of the editor and its extensibility without keeping a dependency on any frameworks.

Quick Start

To get started, you need to install the core package:

npm install --save @deskpro/content-editor

And set it up manually:

import { Editor, EditorEvents } from '@deskpro/content-editor';

...

// instantiate an editor
const editor = new Editor();

// apply extensions
editor
    .useStandardSchema()
    .useStandardPlugins()
    .use([ ...yourCustomExtensions ]);

// listen to editor events
editor
    .on(EditorEvents.CHANGE, () => {
        console.log('Content changed:', editor.getHTML());
    });

// attach editor to the DOM
const container = document.querySelector("#editor-wrapper");
editor.setRoot(container);

...

Once you call setRoot on the editor, all extensions will be initialized and the contenteditable instance is attached to the given container. From there, you can access a variety of members and methods to manipulate the editor and its data.

While the editor is usable on non-React environments, most of the extensions are currently dependent on reusable React components to speed up development. This means that you won't be able to use most of the built-in features like the standard toolbar, table editing, image manipulation, and pretty much any extension that renders complex menus and popups.

Ideally in the future, all extensions should be available without being tied to React.

Passing Editor Options

You may pass options to the Editor's constructor to set its initial content or template schema.

const editor = new Editor({
    template: "heading paragraph*",
    initialContent: "<h1>Hello~</h1><p>It's me...</p>"
});

The above will force all content on the editor to explicitly start with a heading, and allow only paragraphs after it. Then it will use the provided HTML as the document's initial content.

Accessing Content

You may get and set content through the editor instance.

const editor = new Editor();

editor.getHTML();    // gets the current contents of the editor, in HTML
editor.getContent(); // gets the contents in a ProseMirror object format
editor.getJSON();    // just like getContent, but in a JSON string

// at any point in time, you may replace the contents of the
// entire editor by passing either an HTML string or an object
// output of the above getContent call.
editor.setContent(stringOrObject);

The object received from getContent is a subset of ProseMirror's node data structure as described on the documentation.

Dispatching Commands

You have access to all of the editor's commands through editor.commands, organized based on extensions. You can use these to build transactions and apply those on the editor using editor.dispatch().

const editor = new Editor();

...

// insert some text at the start of the document
const tr = editor.view.state.tr.insertText('some text', 0);
editor.dispatch(tr);

Development

As this is part of a monorepo, make sure you have installed all dependencies through Lerna on the root folder:

lerna bootstrap --hoist

You can start the typescript watcher locally on this package using:

npm run watch