The Rich Text Editor is a UI control that replaces a standard HTML textarea; it allows for the rich formatting of text content, including common structural treatments like lists, formatting treatments like bold and italic text, and drag-and-drop inclusion and sizing of images. The Rich Text Editor's toolbar is extensible via a plugin architecture so that advanced implementations can achieve a high degree of customization.
In order to give you the greatest possible control over the size and performance of the Rich Text Editor codebase, we provide two versions of the Editor module and two versions of the buttons that live on the Toolbar:
Editor: Editor contains all features described on this page;
ToolbarButtonAdvanced: The advanced Toolbar buttons are based on YUI Buttons; they are more richly featured at the cost of more dependencies.
ToolbarButton: The more simple Toolbar buttons have fewer dependencies and so are lighter on the page; they do not support progressive enhancement nor menu-button functionality. (See "Changing the Toolbar" for more about your Toolbar choices.)
Choose the right combination of features in your Editor and Toolbar to get the right tradeoff between size and richness for your application.
Examples: Explore examples of the Rich Text Editor in action.
API Documentation: View the full API documentation for the Rich Text Editor.
Release Notes: Detailed change log for the Rich Text Editor.
License: The YUI Library is issued under a BSD license.
Download: Download the Rich Text Editor as part of the full YUI Library at YUILibrary.com.
Video: Rich Text Editing with YUI
In this 36 minute video, YUI Rich Text Editor author Dav Glass takes you on a guided tour of the component, including both how to use and how to extend the base functionality. [iPod/iPhone compatible download also available.]
Getting Started
To use the Editor, include the following source files in your web page:
<!-- Skin CSS file --><linkrel="stylesheet"type="text/css"href="http://yui.yahooapis.com/2.9.0/build/assets/skins/sam/skin.css"><!-- Utility Dependencies --><scriptsrc="http://yui.yahooapis.com/2.9.0/build/yahoo-dom-event/yahoo-dom-event.js"></script><scriptsrc="http://yui.yahooapis.com/2.9.0/build/element/element-min.js"></script><!-- Needed for Menus, Buttons and Overlays used in the Toolbar --><scriptsrc="http://yui.yahooapis.com/2.9.0/build/container/container_core-min.js"></script><scriptsrc="http://yui.yahooapis.com/2.9.0/build/menu/menu-min.js"></script><scriptsrc="http://yui.yahooapis.com/2.9.0/build/button/button-min.js"></script><!-- Source file for Rich Text Editor--><scriptsrc="http://yui.yahooapis.com/2.9.0/build/editor/editor-min.js"></script>
To use the SimpleEditor, include the following source files in your web page:
<!-- Skin CSS file --><linkrel="stylesheet"type="text/css"href="http://yui.yahooapis.com/2.9.0/build/assets/skins/sam/skin.css"><!-- Utility Dependencies --><scriptsrc="http://yui.yahooapis.com/2.9.0/build/yahoo-dom-event/yahoo-dom-event.js"></script><scriptsrc="http://yui.yahooapis.com/2.9.0/build/element/element-min.js"></script><!-- Needed for Menus, Buttons and Overlays used in the Toolbar --><scriptsrc="http://yui.yahooapis.com/2.9.0/build/container/container_core-min.js"></script><!-- Source file for Rich Text Editor--><scriptsrc="http://yui.yahooapis.com/2.9.0/build/editor/simpleeditor-min.js"></script>
Next, apply the yui-skin-sam class name to an element that is a parent of the element
in which the Rich Text Editor lives. You can usually accomplish this simply by putting the class on the
<body> tag:
<bodyclass="yui-skin-sam">
<bodyclass="yui-skin-sam">
For more information on skinning YUI components and making use of default skins,
see our Understanding YUI Skins
article here on the website.
Where these files come from: The files included using the text above will be served from Yahoo! servers. JavaScript files are minified, meaning that comments and white space have been removed to make them more efficient to download. To use the full, commented versions or the -debug versions of YUI JavaScript files, please download the library distribution and host the files on your own server.
Order matters: As is the case generally with JavaScript and CSS, order matters; these files should be included in the order specified above. If you include files in the wrong order, errors may result.
Using the Rich Text Editor
This section describes several common uses of the Rich Text Editor. It contains these subsections:
The SimpleEditor Control is a smaller more basic version of the Editor Control. Most of the editing features found in the main Editor Control exist in the SimpleEditor version. However a few were removed:
Advanced Image editing — replaced with a simple Javascript prompt
Advanced Link editing — replaced with a simple Javascript prompt
Advanced Drop Down Menus — replaced with standard HTML Select Elements
Header editing
Removing of Format
Superscript & Subscript
Indenting & Outdenting
No support for YAHOO.widget.EditorWindow — The floating panels used for image and link editing
The major difference between the two editors are their dependencies.
The Rich Text Editor is designed to replace an existing HTML <textarea> control. Users whose browsers do not support JavaScript will therefore see a standard <textarea> in place of the Rich Text Editor. The base markup for this approach is as follows:
<strong>Your</strong> HTML <em>code</em> goes here.<br>
This text will be pre-loaded in the editor when it is rendered.
</textarea>
</body>
<bodyclass="yui-skin-sam"><textareaname="msgpost"id="msgpost"cols="50"rows="10"><strong>Your</strong> HTML <em>code</em> goes here.<br>
This text will be pre-loaded in the editor when it is rendered.
</textarea></body>
With this markup in place, the JavaScript to instantiate the Rich Text Editor involves a simple constructor to which is passed a configuration object. Once instantiated, you use the render method to place the Rich Text Editor on the page:
var myEditor =newYAHOO.widget.Editor('msgpost',{
height:'300px',
width:'522px',
dompath:true,//Turns on the bar at the bottom
animate:true//Animates the opening, closing and moving of Editor windows
});
myEditor.render();
var myEditor =newYAHOO.widget.Editor('msgpost',{
height:'300px',
width:'522px',
dompath:true,//Turns on the bar at the bottom
animate:true//Animates the opening, closing and moving of Editor windows});
myEditor.render();
The full list of configuration options that you can pass in your constructor can be found in the API documentation.
With the simple markup and script above, and including the skin stylesheet for Rich Text Editor, you will see rendered to your page a rich control that looks like this:
Rendering the SimpleEditor
You render the SimpleEditor Control the same as the Editor Control, only you call the SimpleEditor constructor instead.
var myEditor =newYAHOO.widget.SimpleEditor('msgpost',{
height:'300px',
width:'522px',
dompath:true//Turns on the bar at the bottom
});
myEditor.render();
var myEditor =newYAHOO.widget.SimpleEditor('msgpost',{
height:'300px',
width:'522px',
dompath:true//Turns on the bar at the bottom});
myEditor.render();
With the simple markup and script above, and including the skin stylesheet for Rich Text Editor, you will see rendered to your page a rich control that looks like this:
Getting the data from the Editor
There are a couple of ways to get the data from the editor. The first way is to let the Editor do it for you by setting the handleSubmit configuration option.
Setting the handleSubmit configuration option, the Editor will attempt to attach itself to its parent form's submit event. Then it will call its saveHTML method, then proceed with the form submission.
The manual way, is to call the saveHTML method yourself. Like this:
var myEditor =newYAHOO.widget.Editor('msgpost');
myEditor.render();
//Inside an event handler after the Editor is rendered
//The var html will now have the contents of the textarea
var html = myEditor.get('element').value;
});
var myEditor =newYAHOO.widget.Editor('msgpost');
myEditor.render();//Inside an event handler after the Editor is renderedYAHOO.util.Event.on('somebutton','click',function(){//Put the HTML back into the text area
myEditor.saveHTML();//The var html will now have the contents of the textareavar html = myEditor.get('element').value;});
Changing the toolbar
The default toolbar included with the editor makes every currently supported feature available by default. You can override this config before the editor is rendered by passing in an object literal of a new toolbar to the constructor.
Select: The Select button is a hybrid of the menu button that mimics an HTML <select> element.
Color: The Color button is another hybrid menu button that contains an interactive color picker; note that this color picker is not an implementation of the YUI Color Picker Control but rather a dedicated text-editing control optimized for styling text.
Spin: The Spin button is a hybrid of a Push button that adds a pair of up and down arrows to the side of the button. It is generally used to allow the user to select a value from a range of numeric values. Selecting one of the buttons causes the value to "spin" up and down the range of possible values.
Separator: The Separator button gives you a way to place a bar ("|") in between two buttons. The separator bar is also given a unique classname so you can use it to style the toolbar as needed.
The following are basic button types:
Push: Push buttons are provided via the default toolbar.
Menu: Menu buttons are provided via the default toolbar.
Select: The Select button is an HTML <select> element.
Color: The Color button is a hybrid menu button that contains an interactive color picker; note that this color picker is not an implementation of the YUI Color Picker Control but rather a dedicated text-editing control optimized for styling text.
Spin: The Spin button is a hybrid of a Push button that adds a pair of up and down arrows to the side of the button. It is generally used to allow the user to select a value from a range of numeric values. Selecting one of the buttons causes the value to "spin" up and down the range of possible values.
Separator: The Separator button gives you a way to place a bar ("|") in between two buttons. The separator bar is also given a unique classname so you can use it to style the toolbar as needed.
With the above code you would get an Editor that looked like this:
Events
The Rich Text Editor and the Toolbar are both loaded with Custom Events to which you can subscribe as you customize the editor's behavior to suit the specific needs of your application.
Some of the more common Rich Text Editor events include the following; for a full list, including the arguments passed to each event, see the API documentation for Rich Text Editor:
SimpleEditor Events
Editor Render Events
toolbarLoaded
afterRender
editorContentLoaded
Editor HTML Event Mapping
editorMouseUp
editorMouseDown
editorDoubleClick
editorKeyUp
editorKeyPress
editorKeyDown
Editor Command Execution Events
beforeNodeChange
afterNodeChange
beforeExecCommand
afterExecCommand
Toolbar Events (accessed via EditorObj.toolbar.on())
toolbarExpanded
toolbarCollapsed
colorPickerClicked
cmdClick (dynamic event)
menucmdClick (dynamic event)
buttonClick
Editor Events
Editor Render Events
toolbarLoaded
afterRender
editorContentLoaded
Editor HTML Event Mapping
beforeEditorMouseUp
editorMouseUp
beforeEditorMouseDown
editorMouseDown
beforeEditorClick
editorClick
beforeEditorDoubleClick
editorDoubleClick
beforeEditorKeyUp
editorKeyUp
beforeEditorKeyPress
editorKeyPress
beforeEditorKeyDown
editorKeyDown
Editor Command Execution Events
beforeNodeChange
afterNodeChange
beforeExecCommand
afterExecCommand
Editor Window Events
beforeOpenWindow
afterOpenWindow
closeWindow
windowCMDOpen (dynamic event)
windowCMDClose (dynamic event)
windowRender
windowInsertImageRender
windowCreateLinkRender
Toolbar Events (accessed via EditorObj.toolbar.on())
toolbarExpanded
toolbarCollapsed
colorPickerClicked
cmdClick (dynamic event)
menucmdClick (dynamic event)
buttonClick
Dynamic Events
Dynamic Events are special CustomEvent's that are dynamically created based on the value of a button in the Toolbar.
For example, if you had a button called "bold" you will be able to listen for the "boldClick" event or if you had a button called "foo", you would be able to listen for the "fooClick" event.
These events are best described with the following code:
//Using the Dynamic Event cmdClick where cmd is the value of the button above
this.toolbar.on('boldClick',function(o){
alert('Bold Button was clicked');
});
//Using the Dynamic Event cmdClick where cmd is the value of the button above
this.toolbar.on('mybutton1Click',function(o){
alert('mybutton1 was clicked');
});
//Standard Custom Event fired for all button clicks
this.toolbar.on('buttonClick',function(o){
switch(o.button.value){
case'bold':
//Bold Code Here
break;
case'mybutton1':
//My Button 1 Code Here
break;
case'mybutton2':
//My Button 2 Code Here
break;
}
});
}, myEditor,true);
myEditor.render();
var myEditor =newYAHOO.widget.Editor('msgpost',{//Snippet from button config
buttons:[{ type:'push', label:'Bold', value:'bold'},{ type:'push', label:'My Button 1', value:'mybutton1'},{ type:'push', label:'My Button 2', value:'mybutton2'}]});
myEditor.on('toolbarLoaded',function(){//Using the Dynamic Event cmdClick where cmd is the value of the button abovethis.toolbar.on('boldClick',function(o){alert('Bold Button was clicked');});//Using the Dynamic Event cmdClick where cmd is the value of the button abovethis.toolbar.on('mybutton1Click',function(o){alert('mybutton1 was clicked');});//Standard Custom Event fired for all button clicksthis.toolbar.on('buttonClick',function(o){switch(o.button.value){case'bold'://Bold Code Herebreak;case'mybutton1'://My Button 1 Code Herebreak;case'mybutton2'://My Button 2 Code Herebreak;}});}, myEditor,true);
myEditor.render();
Please refer to the API documentation for a full list of Custom Events that are available for the Rich Text Editor.
Plugins
The Rich Text Editor's toolbar has a flexible plugin architecture that allows you to customize the editor's behavior for the purposes of your own application.
The example below will add a new button to the default toolbar. When this custom button is clicked it will insert the following HTML: "<b>This is the text to insert.</b>" But the button will only be enabled if the user has focused a <div>, so this text will never be inserted into an element within the editor other than a <div>.
//Start with the constructor for our RTE:
var myEditor =newYAHOO.widget.Editor('msgpost',{
height:'300px',
width:'522px'
});
//Use the toolbarLoaded Custom Event; when that event fires,
//we will execute a function that adds or custom button:
myEditor.on('toolbarLoaded',function(){
//Simple button config
var button ={
type:'push',
label:'My Button 3',
value:'mybutton3',
disabled:false
};
//Add the button to the toolbar; "this"
//refers to myEditor, our RTE instance:
this.toolbar.addButton(button);
//Now listen for the new buttons click and do something with it.
//Note that "mybutton3Click" is an event synthesized for us
//automatically because that's the value we gave our button
//above:
this.toolbar.on('mybutton3Click',function(o){
this.execCommand('inserthtml','<b>This is the text to insert.</b>');
}, myEditor,true);
//Setup the button to be enabled, disabled or selected
this.on('afterNodeChange',function(o){
//Get the selected element
var el =this._getSelectedElement();
//Get the button we want to manipulate
var button =this.toolbar.getButtonByValue('mybutton3');
if(el && el.tagName=='div'){
this.toolbar.enableButton(button);
}
},this,true);
}, myEditor,true);
myEditor.render();
//Start with the constructor for our RTE:var myEditor =newYAHOO.widget.Editor('msgpost',{
height:'300px',
width:'522px'});//Use the toolbarLoaded Custom Event; when that event fires,//we will execute a function that adds or custom button:
myEditor.on('toolbarLoaded',function(){//Simple button configvar button ={
type:'push',
label:'My Button 3',
value:'mybutton3',
disabled:false};//Add the button to the toolbar; "this"//refers to myEditor, our RTE instance:this.toolbar.addButton(button);//Now listen for the new buttons click and do something with it.//Note that "mybutton3Click" is an event synthesized for us//automatically because that's the value we gave our button//above:this.toolbar.on('mybutton3Click',function(o){this.execCommand('inserthtml','<b>This is the text to insert.</b>');}, myEditor,true);//Setup the button to be enabled, disabled or selectedthis.on('afterNodeChange',function(o){//Get the selected elementvar el =this._getSelectedElement();//Get the button we want to manipulatevar button =this.toolbar.getButtonByValue('mybutton3');if(el && el.tagName=='div'){this.toolbar.enableButton(button);}},this,true);}, myEditor,true);
myEditor.render();
Overriding execCommands
The Rich Text Editor uses a method based approach for applying execCommand commands on selected text/elements. For example, when you call myEditor.execCommand('forecolor', 'FF0000');, the editor actually calls an internal method called cmd_forecolor.
This method will then process the command and act on it. It will return an array telling the execCommand method whether it should or should not execute the document.execCommand method.
Below is an example of the cmd_forecolor method.
cmd_forecolor:function(value){
var exec =true,
el =this._getSelectedElement();
if(!this._isElement(el,'body')){
Dom.setStyle(el,'color', value);
this._selectNode(el);
exec =false;
}else{
this._createCurrentElement('span',{ color: value });
this._selectNode(this.currentElement[0]);
exec =false;
}
return[exec];
},
cmd_forecolor:function(value){var exec =true,
el =this._getSelectedElement();if(!this._isElement(el,'body')){
Dom.setStyle(el,'color', value);this._selectNode(el);
exec =false;}else{this._createCurrentElement('span',{ color: value });this._selectNode(this.currentElement[0]);
exec =false;}return[exec];},
Using this technique, you can add support for your own execCommands, or change the way that the Editor handles them.
Toolbar Interactions and the nodeChange Event
If you're intereseted in extending the Toolbar with custom buttons (see the Flickr and Calendar examples that do this), the following section contains important information.
The nodeChange event is your way of knowing when an interesting moment occurs inside of the Editor. Keep in mind that the editing canvas itself (the place where the user is inputting rich text) is, under the hood, an HTML document loaded within an iframe with designMode turned on — which is to say it has a DOM full of nodes. When the user is typing, she is adding to a single DOM node. But when she mouses to a new location, selects new texts, or performs any other action that changes the cursor's current position in the DOM, the nodeChange event fires to let you know that the user appears to be performing an interesting action. Common user actions that can fire nodeChange include mousedown, mouseup, arrow keys and other keypress events.
When a nodeChange event is fired off via an internal editor event (or by manually calling myEditor.nodeChange() in your own script), all of the Toolbar's buttons need to update their status to reflect the new state of the user's editor. All of the buttons that ship with the Rich Text Editor fall into one of three groups:
Can be enabled or disabled depending on the state of the editor. This group is enabled when the user has selected content in the editor and disabled when the user is merely typing.
Always enabled. The "show hidden elements" button, for example, is always enabled.
Always disabled. By default, there are no buttons that are always disabled; under some specific circumstances, there may be times when you want to place a custom button in this category (eg, if you've added a feature that is not always available to all users).
The Toolbar goes through the following states in updating its buttons:
Loop through the _disabled array (that is, the list of buttons that should be disabled when there is no selected content in the editor) and...
...if there is no selection then:
Disable all buttons in the array.
If there is a selection then:
Enable each button NOT in the _alwaysDisabled object.
If a button is NOT in the _alwaysEnabled object, it will deselect the button.
For custom buttons that you add to the Editor, it is best practice to subscribe to the afterNodeChange event and update your button's enabled/disabled state at that time. See the Calendar example for sample code that allows you to do this.
/* These are the overrides to manipulate to control the behavior of the toolbar */
_disabled:[
'createlink',
'forecolor',
'backcolor',
'fontname',
'fontsize',
'superscript',
'subscript',
'removeformat',
'heading'
],
_alwaysDisabled:{},
_alwaysEnabled:{ hiddenelements:true}
/* These are the overrides to manipulate to control the behavior of the toolbar */
_disabled:['createlink','forecolor','backcolor','fontname','fontsize','superscript','subscript','removeformat','heading'],
_alwaysDisabled:{},
_alwaysEnabled:{ hiddenelements:true}
Showing and Hiding the Editor
The Rich Text Editor includes two convenience methods used when showing and hiding the editor. The methods are show() and hide().
These methods do not control the display properties of the editor. They are designed to plugin to an event given by the editor's parent container. See the Editor inside a TabView control example here for more information.
By setting the editor's container or a parent element of the editor to display none, the editor can become un-responsive. So using the show method will allow the editor to fix itself and start behaving again. On the other hand, you don't want the editor doing any processing when it is hidden. So calling the hide method will close all open editor windows and stop all background processes and timers.
A simple example of using the show and hide events on a Container Control
//panel in a reference to a Container Control (Panel/Overlay/Dialog)
//panel in a reference to a Container Control (Panel/Overlay/Dialog)//myEditor is a reference to your Editor instance//Setup the show event
panel.showEvent.subscribe(myEditor.show, myEditor,true);//Setup the hide event
panel.hideEvent.subscribe(myEditor.hide, myEditor,true);
Skinning the Editor
The Rich Text Editor comes with a default presentation or "skin," part of the "Sam Skin" visual treatment that accompanies most YUI controls. You can read more about the general approach to skinning YUI components in this in-depth article.
The CSS provided with the Rich Text Editor is comprised of core, functional CSS as well as the Sam Skin visual treatment.
To explore the CSS which controls the Rich Text Editor's presentation, please review the Rich Text Editor's Skinning Example wherein the full CSS for the control is displayed.
For your convenience we have provided the Rich Text Editor's sprite PSD file in a zip available here.
YUI on Mobile: Using Rich Text Editor with "A-Grade" Mobile Browsers
About this Section: YUI generally works well with mobile browsers that are based on A-Grade browser foundations. For example, Nokia's N-series phones, including the N95, use a browser based on Webkit — the same foundation shared by Apple's Safari browser, which is found on the iPhone. The fundamental challenges in developing for this emerging class of full, A-Grade-derived browsers on handheld devices are:
Screen size: You have a much smaller canvas;
Input devices: Mobile devices generally do not have mouse input, and therefore are missing some or all mouse events (like mouseover);
Processor power: Mobile devices have slower processors that can more easily be saturated by JavaScript and DOM interactions — and processor usage affects things like battery life in ways that don't have analogues in desktop browsers;
Latency: Most mobile devices have a much higher latency on the network than do terrestrially networked PCs; this can make pages with many script, css or other types of external files load much more slowly.
There are other considerations, many of them device/browser specific (for example, current versions of the iPhone's Safari browser do not support Flash). The goal of these sections on YUI User's Guides is to provide you some preliminary insights about how specific components perform on this emerging class of mobile devices. Although we have not done exhaustive testing, and although these browsers are revving quickly and present a moving target, our goal is to provide some early, provisional advice to help you get started as you contemplate how your YUI-based application will render in the mobile world.
The YUI Rich Text Editor does not currently support the iPhone or the Nokia N95. Due to the interaction model (specifically, the inability to make a selection), the Editor will not function as expected. In our tests, it appears that the Apple and Nokia Webkit implementations don't event recognize the Editor as an editing field — meaning that these browsers are, at present, deliberately not supporting the use of an iframe in design mode.
The YUI Library and related topics are discussed on the on the YUILibrary.com forums.
Also be sure to check out YUIBlog for updates and articles about the YUI Library written by the library's developers.
Filing Bugs & Feature Requests
The YUI Library's public bug tracking and feature request repositories are located on the YUILibrary.com site. Before filing new feature requests or bug reports, please review our reporting guidelines.
The Rich Text Editor is a UI control that replaces a standard HTML textarea; it allows for the rich formatting of text content, including common structural treatments like lists, formatting treatments like bold and italic text, and drag-and-drop inclusion and sizing of images. The Rich Text Editor's toolbar is extensible via a plugin architecture so that advanced implementations can achieve a high degree of customization.
