microsoft/roosterjs

microsoft/roosterjs

Description: roosterjs is a framework-independent javascript rich text editor.

Language: TypeScript

License: NOASSERTION

Stars: 1312

Forks: 184

Open issues: 56

Created: 2017-07-13T16:39:51Z

Pushed: 2026-06-17T06:41:18Z

Default branch: master

Fork: no

Archived: no

README: 

Rooster

Rooster is a framework-independent JavaScript rich-text editor neatly nested inside one HTML `` element. Editing operations performed by end users are handled in simple ways to generate the final HTML.

Rooster is working on top of a middle layer data structure called "Content Model". All format API and editing operation are using this Content Model layer as content format, and finally convert to HTML and show it in editor.

To view the demo site, please click the link below:

RoosterJs Demo Site.

Upgrade from RoosterJs 8.\*

Please see here.

Features

Packages

Rooster contains 6 basic packages.

1. roosterjs: A facade of all Rooster code for those who want a quick start. Use the createEditor() function in roosterjs to create an editor with default configurations.

2. roosterjs-content-model-core: Defines the core editor and plugin infrastructure. Use roosterjs-content-model-core instead of roosterjs to build and customize your own editor.

3. roosterjs-content-model-api: Defines APIs for editor operations. Use these APIs to modify content and formatting in the editor you built using roosterjs-content-model-core.

4. roosterjs-content-model-dom: Defines APIs for Content Model and DOM operations. This package do conversion between DOM tree and roosterjs Content Model.

5. roosterjs-content-model-plugins: Defines basic plugins for common features.

6. roosterjs-content-model-types: Defines public interfaces and enumerations, including Content Model types, API parameters and other types.

There are also some extension packages to provide additional functionalities.

1. roosterjs-color-utils: Provide color transformation utility to make editor work under dark mode.

2. roosterjs-content-model-markdown: Defines public APIs to enable conversions between Markdown and ContentModel

To be compatible with old (8.\*) versions, you can use EditorAdapter class from the following package which can act as a 8.\* Editor:

1. roosterjs-editor-adapter: Provide a adapter class EditorAdapter to work with Editor (9.\*) and legacy plugins (via EditorAdapterOptions.legacyPlugins)

All old packages (8.\*) are moved to branch roosterjsv8, including

1. roosterjs-editor-core 2. roosterjs-editor-api 3. roosterjs-editor-dom 4. roosterjs-editor-plugins 5. roosterjs-editor-types 6. roosterjs-editor-types-compatible 7. roosterjs-react

We will not update these branches any more unless there are new security bugs.

APIs

Rooster provides Content Model level APIs (in roosterjs-content-model-dom), core APIs (in roosterjs-content-model-core), and formatting APIs (in roosterjs-content-modelapi) to perform editing operations.

roosterjs-content-model-dom provides several levels of Content Model operations:

• Create Content Model elements
• Convert DOM tree to Content Model
• Convert Content Model to DOM tree
• Format handlers
• A few DOM level API

roosterjs-content-model-core provides APIs for editor core. Editor class will call such APIs to perform basic editor operations. These APIs can be overridden by specifying API overrides in Editor options when creating the editor.

roosterjs-content-model-api provides APIs for scenario-based operations triggered by user interaction.

roosterjs-content-model-markdown provides API to transform Markdown language in Content Model objects.

Plugins

Rooster supports plugins. You can use built-in plugins or build your own. Plugins call APIs to communicate with the editor. When an operation is performed by the user or when content is changed by code, the editor will trigger events for the plugins to handle.

Here's a sample plugin which will show a dialog containing "Hello Rooster" when an "a" is typed in the editor:

class HelloRooster implements EditorPlugin {
getName() {
return 'HelloRooster';
}

initialize(editor: IEditor) {}

dispose() {}

onPluginEvent(e: PluginEvent) {
if (e.eventType == 'input' && e.rawEvent.which == 65) {
alert('Hello Rooster');
}
}
}

Installation

Install via NPM or Yarn:

yarn add roosterjs

You can also install sub packages separately:

yarn add roosterjs-content-model-core

yarn add roosterjs-content-model-api

...

In order to run the code below, you may also need to install webpack:

yarn add webpack -g

Usage

A quick start

1. Create editor.htm which contains a DIV with some styles, buttons to handle some click events and a reference to rooster.js (update with the path to your rooster.js file):

B I
U


var contentDiv = document.getElementById('contentDiv');
var editor = roosterjs.createEditor(contentDiv);

editor.setContent('Welcome to RoosterJs!');
document.getElementById('buttonB').addEventListener('click', function () {
roosterjs.toggleBold(editor);
});
document.getElementById('buttonI').addEventListener('click', function () {
roosterjs.toggleItalic(editor);
});...