Modify content

Go back to How to use

RoosterJs provides several APIs to allow modify existing content inside an editor.

Editor class

Editor class provides several methods to allow insert HTML content or a DOM node at a position, or delete an existing DOM node, or replace an existing DOM node with another node.

Editor.insertContent() (*)

const enum ContentPosition {
    Begin,
    End,
    SelectionStart,
}

interface InsertOption {
    position: ContentPosition;
    replaceSelection: boolean;
    insertOnNewLine: boolean;
    updateCursor: boolean;
}

public insertContent(content: string, option?: InsertOption);

insertContent method allow inserting a given HTML string into a position. The position can be the beginning/ending of the editor content or start of current selection. It also provides options to let you decide if you want to replace current selection with new content, and whether insert new content on new line or current line. If the insert option is not specified, this method will use the following default value:

{
    position: ContentPosition.SelectionStart,
    updateCursor: true,
    replaceSelection: true,
    insertOnNewLine: false,
}

Editor.insertNode() (*)

public insertNode(node: Node, option?: InsertOption): boolean;

Similarly, insertNode method allow you to insert an HTML DOM node into editor. Note that the given node should be created from the same HTML Document with editor. If it is created from another HTML Document (e.g., another window, or IFrame), it can still work in Chrome and Firefox, but it can't work in IE and Edge.

insertNode takes the same insert option parameter with insertContent method, and use the same default value if it is not specified.

Editor.deleteNode()

deleteNode(node: Node): boolean;

This method provides the ability to delete a given HTML DOM node from editor content. If the given node is not found, or it is not a node inside editor, it will not be deleted.

In order to get an existing node from editor, at least you have the following ways:

1. The node is created from your code, so you can always has the reference to the node
2. Use API getNodeAtCursor() to get current focused DOM node
3. Use Editor method Editor.queryContent (*) to query the DOM nodes with a selector
4. Use API queryNodesWithSelection() to query DOM nodes intersect with current selection using a selector
5. Use Editor.getContentTraverser() to get a traverser object and go through the DOM tree to find a node
6. Use DOM walker API provided by roosterjs-editor-dom package to go through the DOM tree to find a node
7. Use HTML DOM API directly

(More documentation about the APIs mentioned above will be added later)

Editor.replaceNode()

replaceNode(existingNode: Node, toNode: Node): boolean;

This method can replace an existing HTML DOM node with another one. If the given node is not found, or it is not a node inside editor, it will not be replaced.

Content replace API

replaceTextBeforeCursorWithNode API

In most case, we are facing a more complex situation, for example, after user input some text we want to replace the text with a given DOM node. Then we can use replaceTextBeforeCursorWithNode API:

function replaceTextBeforeCursorWithNode(
    editor: Editor,
    text: string,
    node: Node,
    exactMatch: boolean,
    cursorData?: CursorData
): boolean;

This API will try to find the matched text before current cursor and replace it with a given node. In HyperLink plugin, this API is used to replace a url before cursor with a <A> tag.

Format API

To change format of current selection, you can call a bunch of format APIs from roosterjs-editor-api package. Please reference to Add format buttons.

Modify content directly

While you have reference to DOM node inside editor, or a selection range in editor, you can also use them to modify the content directly. However, unless you can't find a proper API from roosterjs to archieve your goal, we don't recommend using DOM API directly since the DOM API has too much flexibility which may destroy existing DOM structure outside of editor or event editor itself, once that happens, the calling to an editor API will cause unpredictable results.

*: This API might be changed in newer version.