d6fa26d0adaec6c910115be34fe7a5a5f402c14fMark Andrews<div class="intro">

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User <p>The Rich Text Editor is a UI control that allows for the rich formatting of text content, including common structural treatments like lists, formatting treatments like bold and italic text.</p>

71cef386fae61275b03e203825680b39fedaa8c6Tinderbox User <p>The current release of the Rich Text Editor for YUI 3 is the base utility layers that provide a foundation on which you can create an Editor. <strong>This version of Editor does not contain a GUI of any kind.</strong></p>

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User</div>

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User{{>getting-started}}

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User<h4 id="query">Creating an Editor</h4>

d6fa26d0adaec6c910115be34fe7a5a5f402c14fMark Andrews<p>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.</p>

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User```

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox UserYUI().use('editor-base', function(Y) {

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User var editor = new Y.EditorBase({

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User content: '<strong>This is <em>a test</em></strong> <strong>This is <em>a test</em></strong> '

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User });

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User //Add the BiDi plugin

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User editor.plug(Y.Plugin.EditorBidi);

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User //Focusing the Editor when the frame is ready..

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User editor.on('frame:ready', function() {

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User this.focus();

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User });

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User //Rendering the Editor.

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User editor.render('#editor');

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User});

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User```

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User<h4 id="instance">Frame Instance</h4>

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User<p>When the Editor is created, it creates a YUI instance inside itself and attaches that instance to the editable iframe.

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox UserThis means that you now have the full power of YUI 3 inside the Editor iframe. You can use Event, Stylesheet, Node and even DD

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userinside the iframe, without having to load all the JavaScript inside the document.</p>

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<p>Getting access to this instance is simple. Just use the `getInstance` method on the Editor instance, like this:</p>

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User```

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox UserYUI().use('editor-base', function(Y) {

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User var editor = new Y.EditorBase({

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User content: '<strong>This is <em>a test</em></strong> <strong>This is <em>a test</em></strong> '

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User });

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User //Add the BiDi plugin

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User editor.plug(Y.Plugin.EditorBidi);

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User //Focusing the Editor when the frame is ready..

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User editor.on('frame:ready', function() {

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User this.focus();

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User var inst = this.getInstance();

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User //inst is now an instance of YUI that is bound to the iframe.

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User var body = inst.one('body');

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User //body is a Node instance of the BODY element "inside" the iframe.

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User

7e71f05d8643aca84914437c900cb716444507e4Tinderbox User var strongs = inst.all('strong');

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User //strongs is a NodeList instance of all the STRONG elements "inside" the iframe.

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User });

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User //Rendering the Editor.

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User editor.render('#editor');

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User});

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User```

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User<h4 id="events">Events</h4>

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<p>By default, the frame instance under the hood of Editor attaches a listener for all known DOM events. The example

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userbelow shows how you can listen and interact with them.</p>

7e71f05d8643aca84914437c900cb716444507e4Tinderbox User

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User```

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox UserYUI().use('editor-base', function(Y) {

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User var editor = new Y.EditorBase({

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User content: '<strong>This is <em>a test</em></strong> <strong>This is <em>a test</em></strong> '

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User });

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User //Add the BiDi plugin

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User editor.plug(Y.Plugin.EditorBidi);

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User editor.on('frame:keydown', function(e) {

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User //Listen for the keydown event inside the Editor.

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User /*

7e71f05d8643aca84914437c900cb716444507e4Tinderbox User This event object contains 3 new properties:

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User frameEvent

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User frameTarget

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User frameCurrentTarget

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User These properties are the original properties before

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User the Event was fired, so you can use them like:

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User

7e71f05d8643aca84914437c900cb716444507e4Tinderbox User e.frameEvent.halt();

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User */

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User });

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User editor.on('frame:mouseup', function(e) {

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User //Listen for the mouseup event inside the Editor.

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User });

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User //Rendering the Editor.

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User editor.render('#editor');

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User});

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User```

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User<h4 id="nodechange">Node Change Event</h4>

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User<p>The `nodeChange` event is a special event that Editor emits so that you can react to certain important moments that occured.</p>

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User<p>The most common use for the `nodeChange` event is to update the state of a Toolbar.</p>

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User<h5>nodeChange event properties</h5>

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User<p>This list contains the properties that are added to the Event object when the `nodeChange` event is fired.</p>

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User<table>

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User <thead>

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User <tr>

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User <th>Event Property</th>

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User <th>Description</th>

c313914d0e66b20969215e519bbf2ab4ecf39512Tinderbox User </tr>

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User </thead>

1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User <tbody>

<tr>

<td nowrap="nowrap">`changedEvent`</td>

<td>The event that caused the nodeChange</td>

</tr>

<tr>

<td nowrap="nowrap">`changedNode`</td>

<td>The node that was interacted with</td>

</tr>

<tr>

<td nowrap="nowrap">`changedType`</td>

<td>The type of change: mousedown, mouseup, right, left, backspace, tab, enter, etc..</td>

</tr>

<tr>

<td nowrap="nowrap">`commands`</td>

<td>The list of execCommands that belong to this change and the dompath that's associated with the changedNode</td>

</tr>

<tr>

<td nowrap="nowrap">`classNames`</td>

<td>An array of classNames that are applied to the changedNode and all of its parents</td>

</tr>

<tr>

<td nowrap="nowrap">`dompath`</td>

<td>A sorted array of node instances that make up the DOM path from the changedNode to body.</td>

</tr>

<tr>

<td nowrap="nowrap">`backgroundColor`</td>

<td>The cascaded backgroundColor of the changedNode</td>

</tr>

<tr>

<td nowrap="nowrap">`fontColor`</td>

<td>The cascaded fontColor of the changedNode</td>

</tr>

<tr>

<td nowrap="nowrap">`fontFamily`</td>

<td>The cascaded fontFamily of the changedNode</td>

</tr>

<tr>

<td nowrap="nowrap">`fontSize`</td>

<td>The cascaded fontSize of the changedNode</td>

</tr>

</tbody>

</table>

<h4 id="modules">Module Descriptions</h4>

<p>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.</p>

<table>

<thead>

<tr>

<th>Module Name</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td nowrap="nowrap">`frame`</td>

<td>Controls the creation and set up of the editable area</td>

</tr>

<tr>

<td nowrap="nowrap">`selection`</td>

<td>Cross-browser selection normalization</td>

</tr>

<tr>

<td nowrap="nowrap">`exec-command`</td>

<td>Plugs into frame to extend `document.execCommand` support.</td>

</tr>

<tr>

<td nowrap="nowrap">`editor-tab`</td>

<td>Overrides the default tab key handler and indents/outdents the current block level element.</td>

</tr>

<tr>

<td nowrap="nowrap">`editor-para`</td>

<td>Paragraph support (opposite of `editor-br`)</td>

</tr>

<tr>

<td nowrap="nowrap">`editor-br`</td>

<td>Line break support (opposite of `editor-para`) </td>

</tr>

<tr>

<td nowrap="nowrap">`editor-bidi`</td>

<td>Paragraph/Bi-Directional support</td>

</tr>

<tr>

<td nowrap="nowrap">`createlink-base`</td>

<td>Simple `prompt` based link creation.</td>

</tr>

<tr>

<td nowrap="nowrap">`editor-base`</td>

<td>Rollup of the above modules</td>

</tr>

<tr>

<td nowrap="nowrap">`editor`</td>

<td>Rollup of the above modules</td>

</tr>

</tbody>

</table>

<p><strong>Note:</strong> Either `editor-br` or `editor-para` should be plugged. One, but not both, is required for proper functionality.</p>