Create an editor using Editor class

Go back to How to use

createEditor function provides the most common options to quickly create an editor. However, if you want to have more controls on a highly customized editor, you should directly use Editor class.

Constructor of Editor

constructor(contentDiv: HTMLDivElement, options: EditorOptions = {});

contentDiv parameter specify an HTML DIV element which will become an editable editor. You can set any CSS styles to this DIV to make it best fit your page.

options parameter includes all the options to customize the editor.

Options

interface EditorOptions {
    plugins?: EditorPlugin[];
    defaultFormat?: DefaultFormat;
    undo?: UndoService;
    initialContent?: string;
    disableRestoreSelectionOnFocus?: boolean;
    omitContentEditableAttributeChanges?: boolean;
}

All the elements, including the option itself, are optional. So you only need to specify the option which you don't want to use with default values.

plugins

Use plugins parameter to specify a plugin array that you want to use within your editor. If not specified, the default value will be an empty array, which means there is no plugin is used (except Undo, see below).

It is highly recommended to included the 4 basic plugins with your editor since they will provide the basic editing functions such as bullet list operations, pasting operations, default shortcut and automatically hyperlink. And using the plugin parameter allow you to pass in parameters to each plugin to customize them.

Besides the basic plugins, you can also add your own plugins or 3rd party plugins.

defaultFormat

You can specify a default format with this parameter so that when there's no initial content in editor, the default format that user typed will be in this format.

interface DefaultFormat {
    fontFamily?: string;
    fontSize?: string;
    textColor?: string;
    backgroundColor?: string;
    bold?: boolean;
    italic?: boolean;
    underline?: boolean;
}

By default, the text style will be not bold, not italic, not underline. Font family, font size, text color and background color will be determined by current style of you editor content DIV. For example, if your contentDiv looks like

<div style="font-family: Arial; font-size: 14px; color: black; background-color: white"></div>

and these default formats are not specified in defaultFormat parameter, then the default format will be a 14px Arial font with black text and white background.

The default format will be applied when there's no initial content in editor, or the first line of initial content is empty. Otherwise the original format will be preserved.

undo

RoosterJs provides its own undo service, and by default you don't need to specify it in editor option and the Undo object will always be used. However, if you want to use your own undo service to replace the default behavior, or you'd like to customize the default undo behavior, you can create your own undo object and specify it using this parameter.

An undo service object must implement UndoService interface:

interface UndoService extends EditorPlugin {
    undo: () => void;
    redo: () => void;
    addUndoSnapshot: () => void;
    canUndo: () => boolean;
    canRedo: () => boolean;
    clear: () => void;
}

Although UndoService is extended from EditorPlugin, you never need and you never should add it into plugin list because Editor will do this for you.

To create the default undo object, you can use the constructor of Undo class:

constructor(private preserveSnapshots?: boolean) {}

Parameter preserveSnapshots allows you to preserve existing undo snapshot even when editor and its plugins are disposed. So that you can reuse these snapshots when you want to create the editor again with the same undo object.

initialContent

It is possible to set initial content to the editor before user is able to edit it. And of cause you can also set content using Editor.setContent() API any time after editor is created. The difference is, content set by initialContent parameter is not undoable, while after setting content using Editor.setContent(), user is still able to undo to the state before setContent() is called.

disableRestoreSelectionOnFocus

Editor has the ability to remember your last selection inside editor. If you select some content then focus out of editor, the previous selection is remembered. So that when you focus back into editor, the previous selection is preserved. However if for any reason you don't want to restore the previous selection, you can set this parameter to true to skip this behavior.

omitContentEditableAttributeChanges

When you call the constructor with a DIV element, this element will be added contenteditable attribute so that it is editable. However, if for any reason you'd like to add this attribute yourself, you can set this parameter to true to skip the default behavior.

Sample code

Here's an example to show how to use constructor with the parameters:

import {
    Editor,
    EditorPlugin,
    ContentEdit,
    DefaultShortcut,
    Paste,
    HyperLink,
    DefaultFormat,
    Undo,
    EditorOptions,
} from 'roosterjs';

class MyPlugin implements EditorPlugin {
    initialize() {}
    dispose() {}    
}
window.onload = () => {

    let plugins: EditorPlugin[] = [
        new ContentEdit(),
        new DefaultShortcut(),
        new Paste(true /*useDirectPaste*/),
        new HyperLink(href => 'Ctrl+click to open link ' + href),
        new MyPlugin(),
    ];
    
    let defaultFormat: DefaultFormat = {
        bold: true,
        fontFamily: 'Arial',
        textColor: 'green',
    };
    
    let initialContent = '<div><br></div><div>Welcome to RoosterJs</div>';
    
    let undo = new Undo(true /*preserveSnapshot*/);
    
    let options: EditorOptions = {
        plugins: plugins,
        defaultFormat: defaultFormat,
        initialContent: initialContent,
        undo: undo,
    };
    
    let contentDiv = document.getElementById('div') as HTMLDivElement;
    let editor = new Editor(contentDiv, options);
}

More info

Package: roosterjs-editor-core

Support from: 6.0.0

Source code: Editor.ts