3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass<div class="intro">
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <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>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <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>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass{{>getting-started}}
046ea4d1ee0f22d956cd360e1e0c0b275aa4bbd0Dav Glass<h2 id="query">Creating an Editor</h2>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass<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>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav GlassYUI().use('editor-base', function(Y) {
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass var editor = new Y.EditorBase({
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass content: '<strong>This is <em>a test</em></strong> <strong>This is <em>a test</em></strong> '
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass //Add the BiDi plugin
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass //Focusing the Editor when the frame is ready..
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass editor.on('frame:ready', function() {
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass //Rendering the Editor.
046ea4d1ee0f22d956cd360e1e0c0b275aa4bbd0Dav Glass<h2 id="instance">Frame Instance</h2>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass<p>When the Editor is created, it creates a YUI instance inside itself and attaches that instance to the editable iframe.
3f2ac16886fbbccf85547608b11143a8795d8db4Dav GlassThis means that you now have the full power of YUI 3 inside the Editor iframe. You can use Event, Stylesheet, Node and even DD
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glassinside the iframe, without having to load all the JavaScript inside the document.</p>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass<p>Getting access to this instance is simple. Just use the `getInstance` method on the Editor instance, like this:</p>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav GlassYUI().use('editor-base', function(Y) {
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass var editor = new Y.EditorBase({
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass content: '<strong>This is <em>a test</em></strong> <strong>This is <em>a test</em></strong> '
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass //Add the BiDi plugin
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass //Focusing the Editor when the frame is ready..
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass editor.on('frame:ready', function() {
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass //inst is now an instance of YUI that is bound to the iframe.
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass var body = inst.one('body');
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass //body is a Node instance of the BODY element "inside" the iframe.
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass var strongs = inst.all('strong');
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass //strongs is a NodeList instance of all the STRONG elements "inside" the iframe.
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass //Rendering the Editor.
046ea4d1ee0f22d956cd360e1e0c0b275aa4bbd0Dav Glass<h2 id="events">Events</h2>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass<p>By default, the frame instance under the hood of Editor attaches a listener for all known DOM events. The example
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glassbelow shows how you can listen and interact with them.</p>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav GlassYUI().use('editor-base', function(Y) {
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass var editor = new Y.EditorBase({
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass content: '<strong>This is <em>a test</em></strong> <strong>This is <em>a test</em></strong> '
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass //Add the BiDi plugin
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass editor.on('frame:keydown', function(e) {
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass //Listen for the keydown event inside the Editor.
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass This event object contains 3 new properties:
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass frameCurrentTarget
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass These properties are the original properties before
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass the Event was fired, so you can use them like:
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass editor.on('frame:mouseup', function(e) {
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass //Listen for the mouseup event inside the Editor.
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass //Rendering the Editor.
046ea4d1ee0f22d956cd360e1e0c0b275aa4bbd0Dav Glass<h2 id="nodechange">Node Change Event</h2>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass<p>The `nodeChange` event is a special event that Editor emits so that you can react to certain important moments that occured.</p>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass<p>The most common use for the `nodeChange` event is to update the state of a Toolbar.</p>
046ea4d1ee0f22d956cd360e1e0c0b275aa4bbd0Dav Glass<h3>nodeChange event properties</h3>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass<p>This list contains the properties that are added to the Event object when the `nodeChange` event is fired.</p>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <th>Event Property</th>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <th>Description</th>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td nowrap="nowrap">`changedEvent`</td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td>The event that caused the nodeChange</td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td nowrap="nowrap">`changedNode`</td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td>The node that was interacted with</td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td nowrap="nowrap">`changedType`</td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td>The type of change: mousedown, mouseup, right, left, backspace, tab, enter, etc..</td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td nowrap="nowrap">`commands`</td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td>The list of execCommands that belong to this change and the dompath that's associated with the changedNode</td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td nowrap="nowrap">`classNames`</td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td>An array of classNames that are applied to the changedNode and all of its parents</td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td nowrap="nowrap">`dompath`</td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td>A sorted array of node instances that make up the DOM path from the changedNode to body.</td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td nowrap="nowrap">`backgroundColor`</td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td>The cascaded backgroundColor of the changedNode</td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td nowrap="nowrap">`fontColor`</td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td>The cascaded fontColor of the changedNode</td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td nowrap="nowrap">`fontFamily`</td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td>The cascaded fontFamily of the changedNode</td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td nowrap="nowrap">`fontSize`</td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td>The cascaded fontSize of the changedNode</td>
046ea4d1ee0f22d956cd360e1e0c0b275aa4bbd0Dav Glass<h2 id="modules">Module Descriptions</h2>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass<p>Using YUI 3's plugin architecture, this version of the Rich Text Editor is even more modular and extensible than the previous version.
3f2ac16886fbbccf85547608b11143a8795d8db4Dav GlassAlmost every part of the Editor infrastructure is a plugin or extension. Below you will find the current list of plugins shipped with Editor.</p>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <th>Module Name</th>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <th>Description</th>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td nowrap="nowrap">`frame`</td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td>Controls the creation and set up of the editable area</td>
cc4d6cf159472379fc6931c6165c556d1fafe76aDav Glass <td nowrap="nowrap">`editor-selection`</td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td>Cross-browser selection normalization</td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td nowrap="nowrap">`exec-command`</td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td>Plugs into frame to extend `document.execCommand` support.</td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td nowrap="nowrap">`editor-tab`</td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td>Overrides the default tab key handler and indents/outdents the current block level element.</td>
22f87c5d1e49ed41349a3cb61608c3ce66287ebaDav Glass <td nowrap="nowrap">`editor-para`</td>
22f87c5d1e49ed41349a3cb61608c3ce66287ebaDav Glass <td>Paragraph support (opposite of `editor-br`)</td>
22f87c5d1e49ed41349a3cb61608c3ce66287ebaDav Glass <td nowrap="nowrap">`editor-br`</td>
22f87c5d1e49ed41349a3cb61608c3ce66287ebaDav Glass <td>Line break support (opposite of `editor-para`) </td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td nowrap="nowrap">`editor-bidi`</td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td nowrap="nowrap">`createlink-base`</td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td>Simple `prompt` based link creation.</td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td nowrap="nowrap">`editor-base`</td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td>Rollup of the above modules</td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td nowrap="nowrap">`editor`</td>
3f2ac16886fbbccf85547608b11143a8795d8db4Dav Glass <td>Rollup of the above modules</td>
22f87c5d1e49ed41349a3cb61608c3ce66287ebaDav Glass<p><strong>Note:</strong> Either `editor-br` or `editor-para` should be plugged. One, but not both, is required for proper functionality.</p>