roosterjs-content-model-api
Advanced tools
Rooster is a framework-independent JavaScript rich-text editor neatly nested
inside one HTML <div> element. Editing operations performed by end users are
handled in simple ways to generate the final HTML.
To view the sample site, please click the link below:
Please see here.
Rooster contains 6 basic packages.
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.
roosterjs-editor-core:
Defines the core editor and plugin infrastructure. Use roosterjs-editor-core
instead of roosterjs to build and customize your own editor.
roosterjs-editor-api:
Defines APIs for editor operations. Use these APIs to modify content and
formatting in the editor you built using roosterjs-editor-core.
roosterjs-editor-dom:
Defines APIs for DOM operations. Use roosterjs-editor-api instead unless
you want to access DOM API directly.
roosterjs-editor-plugins: Defines basic plugins for common features. Examples: making hyperlinks, pasting HTML content, inserting inline images.
roosterjs-editor-types: Defines public interfaces and enumerations.
There are also some extension packages to provide additional functionalities.
roosterjs-color-utils: Provide color transformation utility to make editor work under dark mode.
roosterjs-react: Provide a React wrapper of roosterjs so it can be easily used with React.
roosterjs-editor-types-compatible: Provide types that are compatible with isolatedModules mode. When using isolatedModules mode, "const enum" will not work correctly, this package provides enums with prefix "Compatible" in their names and they have the same value with const enums in roosterjs-editor-types package
Rooster provides DOM level APIs (in roosterjs-editor-dom), core APIs (in roosterjs-editor-core), and formatting APIs
(in roosterjs-editor-api) to perform editing operations.
roosterjs-editor-dom provides several levels of DOM operations:
wrap(), unwrap(), ...InlineElement or BlockElement and perform
operations with DOM Walker API.InlineElements and BlockElements with scope using
ContentTraverser API.roosterjs-editor-core provides APIs for editor core. Editor class will call such
APIs to perform basic editor operations. These APIs are overridable by specifying
API overrides in Editor options when creating the editor.
roosterjs-editor-api provides APIs for scenario-based operations triggered by
user interaction.
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 == PluginEventType.KeyPress && e.rawEvent.which == 65) {
alert('Hello Rooster');
}
}
}
Install via NPM or Yarn:
yarn add roosterjs
You can also install sub packages separately:
yarn add roosterjs-editor-core
yarn add roosterjs-editor-api
...
In order to run the code below, you may also need to install webpack:
yarn add webpack -g
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):<html>
<body>
<div style="width: 500px; height: 400px; border: solid 1px black" id="contentDiv"></div>
<button id="buttonB">B</button> <button id="buttonI">I</button>
<button id="buttonU">U</button>
<script src="rooster.js"></script>
<script>
var contentDiv = document.getElementById('contentDiv');
var editor = roosterjs.createEditor(contentDiv);
editor.setContent('Welcome to <b>RoosterJs</b>!');
document.getElementById('buttonB').addEventListener('click', function () {
roosterjs.toggleBold(editor);
});
document.getElementById('buttonI').addEventListener('click', function () {
roosterjs.toggleItalic(editor);
});
document.getElementById('buttonU').addEventListener('click', function () {
roosterjs.toggleUnderline(editor);
});
</script>
</body>
</html>
To view the sample site, please click here.
To build the sample site code yourself, follow these instructions:
Get dependencies using yarn or npm:
yarn
Build the source code, and start the sample editor:
yarn start
or
npm start
There are two options for debugging:
Debugging from VSCode
Debugging directly from the development tools within the web browser
There are two ways that tests can be run:
yarn test
As a NodeJs package, RoosterJs has dependencies for runtime (specified in package.json under each sub packages in "dependencies" section) and dependencies for build time (specified in package.json under root path in "devDependencies" section).
For runtime dependencies, there are two parts:
Currently we have very few external dependencies. Before adding any new dependency, we need to check:
What's the value of the new dependency and the code using the dependency bring into roosterjs? If we add a new dependency and create our new API to just call into the dependency, that new API doesn't actually bring too much value, and people who uses roosterjs in their project can do this themselves in their code, and we should not add such dependency to people who don't really need it.
What's the dependency tree of the dependency? If we introduce a new dependency which has a deep dependency tree, we need to be careful since it means we are actually adding a lot of new dependencies and our code size may be increased a lot.
How much functionalities do we need from the dependency? If the dependency provides a lot of functionalities but we actually only need a small piece of them, we may need to consider other solutions, such as find another smaller one, or do it ourselves.
What's the license of the dependency? A dependency package under MIT license is good to be used for RoosterJs. For other licenses, we need to review and see if we can take it as a dependency.
If you still feel a new dependency is required after checking these questions, we can review it and finally decide whether we should add the new dependency.
For build time dependencies, it is more flexible to add new dependencies since it won't increase runtime code size or dependencies.
We are still working on more documentation in roosterjs wiki and API reference.
License Copyright (c) Microsoft Corporation. All rights reserved.
Licensed under the MIT License.
FAQs
Format API for roosterjs
We found that roosterjs-content-model-api demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.