Rich Text Editor

Getting Started

To include the source files for Rich Text Editor and its dependencies, first load the YUI seed file if you haven't already loaded it.

<script src="http://yui.yahooapis.com/3.18.1/build/yui/yui-min.js"></script>

Next, create a new YUI instance for your application and populate it with the modules you need by specifying them as arguments to the YUI().use() method. YUI will automatically load any dependencies required by the modules you specify.

<script>
// Create a new YUI instance and populate it with the required modules.
YUI().use('editor', function (Y) {
    // Rich Text Editor is available and ready for use. Add implementation
    // code here.
});
</script>

For more information on creating YUI instances and on the use() method, see the documentation for the YUI Global Object.

Creating an Editor

This simple example will create an Editable area inside of another Node. It will not contain a GUI, only the iframe. You can use various Editor events to wire up your own toolbar.

YUI().use('editor-base', function(Y) {

    var editor = new Y.EditorBase({
        content: '<strong>This is <em>a test</em></strong> <strong>This is <em>a test</em></strong> '
    });

    //Add the BiDi plugin
    editor.plug(Y.Plugin.EditorBidi);

    //Focusing the Editor when the frame is ready..
    editor.on('frame:ready', function() {
        this.focus();
    });

    //Rendering the Editor.
    editor.render('#editor');

});

Inline Editor

You can alternatively create a content editable editor, referred to as an inline editor, on a node. To do this, include the editor-inline and create a new instance of the Y.InlineEditor.

You can read more about content editable in HTML5 on MDN.

YUI().use('editor-inline', function(Y) {

    var editor = new Y.InlineEditor({
        content: '<strong>This is <em>a test</em></strong> <strong>This is <em>a test</em></strong> '
    });

    //Add the BiDi plugin
    editor.plug(Y.Plugin.EditorBidi);

    //Focusing the Editor when ready
    editor.on('ready', function() {
        editor.focus();
    });

    //Rendering the Editor.
    editor.render('#editor');

});

Frame Instance

When the Editor is created, it creates a YUI instance inside itself and attaches that instance to the editable iframe. This means that you now have the full power of YUI 3 inside the Editor iframe. You can use Event, Stylesheet, Node and even DD inside the iframe, without having to load all the JavaScript inside the document.

Getting access to this instance is simple. Just use the getInstance method on the Editor instance, like this:

YUI().use('editor-base', function(Y) {

    var editor = new Y.EditorBase({
        content: '<strong>This is <em>a test</em></strong> <strong>This is <em>a test</em></strong> '
    });

    //Add the BiDi plugin
    editor.plug(Y.Plugin.EditorBidi);

    //Focusing the Editor when the frame is ready..
    editor.on('frame:ready', function() {
        this.focus();

        var inst = this.getInstance();
        //inst is now an instance of YUI that is bound to the iframe.

        var body = inst.one('body');
        //body is a Node instance of the BODY element "inside" the iframe.


        var strongs = inst.all('strong');
        //strongs is a NodeList instance of all the STRONG elements "inside" the iframe.
    });

    //Rendering the Editor.
    editor.render('#editor');

});

Events

By default, the frame instance under the hood of Editor attaches a listener for all known DOM events. The example below shows how you can listen and interact with them.

YUI().use('editor-base', function(Y) {

    var editor = new Y.EditorBase({
        content: '<strong>This is <em>a test</em></strong> <strong>This is <em>a test</em></strong> '
    });

    //Add the BiDi plugin
    editor.plug(Y.Plugin.EditorBidi);

    editor.on('frame:keydown', function(e) {
        //Listen for the keydown event inside the Editor.
        /*
            This event object contains 3 new properties:
                frameEvent
                frameTarget
                frameCurrentTarget

            These properties are the original properties before
            the Event was fired, so you can use them like:

                e.frameEvent.halt();
        */
    });

    editor.on('frame:mouseup', function(e) {
        //Listen for the mouseup event inside the Editor.
    });

    //Rendering the Editor.
    editor.render('#editor');

});

Node Change Event

The nodeChange event is a special event that Editor emits so that you can react to certain important moments that occured.

The most common use for the nodeChange event is to update the state of a Toolbar.

nodeChange event properties

This list contains the properties that are added to the Event object when the nodeChange event is fired.

Event Property	Description
changedEvent	The event that caused the nodeChange
changedNode	The node that was interacted with
changedType	The type of change: mousedown, mouseup, right, left, backspace, tab, enter, etc..
commands	The list of execCommands that belong to this change and the dompath that's associated with the changedNode
classNames	An array of classNames that are applied to the changedNode and all of its parents
dompath	A sorted array of node instances that make up the DOM path from the changedNode to body.
backgroundColor	The cascaded backgroundColor of the changedNode
fontColor	The cascaded fontColor of the changedNode
fontFamily	The cascaded fontFamily of the changedNode
fontSize	The cascaded fontSize of the changedNode

Module Descriptions

Using YUI 3's plugin architecture, this version of the Rich Text Editor is even more modular and extensible than the previous version. Almost every part of the Editor infrastructure is a plugin or extension. Below you will find the current list of plugins shipped with Editor.

Module Name	Description
frame	Controls the creation and set up of the editable area
editor-selection	Cross-browser selection normalization
exec-command	Plugs into frame to extend document.execCommand support.
editor-tab	Overrides the default tab key handler and indents/outdents the current block level element.
editor-para	Paragraph support (opposite of editor-br)
editor-br	Line break support (opposite of editor-para)
editor-bidi	Paragraph/Bi-Directional support
createlink-base	Simple prompt based link creation.
editor-base	Rollup of the above modules
editor	Rollup of the above modules

Note: Either editor-br or editor-para should be plugged. One, but not both, is required for proper functionality.

Known Issues

Editor will currently not function inside of the WinJS Windows 8 application environment. Editor relies on several DOM tricks under the hood to deal with the browser's inconsistencies. Due to the security limitations inside of the WinJS environment, Editor can not use these techniques and will not function as expected.