Editor
Dijit's Rich Text editor, Dijit.Editor, is a text box on steroids. Designed to look and work like a word processor. The editor features a toolbar, HTML output, and a plugin architecture that supports new commands, new buttons and other new features.
Note: Editor is currently in development. Since we had problems getting an example to work over CDN, this example requires locally-installed Dojo. See Quick Installation for details. These problems should be worked out in the 1.0 time frame. (We use /dojoroot here, but you can substitute your own Dojo root directory with no problems.)
Examples
The default configuration of Dijit.Editor has a toolbar along the top with icons for Copy, Cut, Paste, Bold, Italic, Underline, Numbered and Bulleted Lists, and Indent Left and Right.
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Editor Demo</title>
<style type="text/css">
@import "http://o.aolcdn.com/dojo/1.0/dijit/themes/tundra/tundra.css";
@import "http://o.aolcdn.com/dojo/1.0/dojo/resources/dojo.css"
</style>
<script type="text/javascript" src="http://o.aolcdn.com/dojo/1.0/dojo/dojo.xd.js"
djConfig="parseOnLoad: true"></script>
<script type="text/javascript">
dojo.require("dojo.parser");
dojo.require("dijit.Editor");
</script>
</head>
<body class="tundra">
<form method="post">
<textarea name="field" width="200px" dojoType="dijit.Editor">
It was a dark and stormy night. Your story belongs here!
</textarea>
<input type="submit" value="Save" />
</form>
</body>
</html>
Toolbar Customization
You may limit the commands people can perform, such as removing the Indent Left button. Each button corresponds to a plugin, hence you specify toolbar buttons with the plugins attribute. For example, the following toolbar includes copy, cut, paste and bold: /* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */ .geshifilter {font-family: monospace;} .geshifilter .imp {font-weight: bold; color: red;} .geshifilter .kw1 {color: #000066; font-weight: bold;} .geshifilter .kw2 {color: #003366; font-weight: bold;} .geshifilter .kw3 {color: #000066;} .geshifilter .co1 {color: #009900; font-style: italic;} .geshifilter .coMULTI {color: #009900; font-style: italic;} .geshifilter .es0 {color: #000099; font-weight: bold;} .geshifilter .br0 {color: #66cc66;} .geshifilter .st0 {color: #3366CC;} .geshifilter .nu0 {color: #CC0000;} .geshifilter .me1 {color: #006600;} .geshifilter .re0 {color: #0066FF;}
plugins="['copy','cut','paste','|','bold']">
</textarea>
The plugins attribute is specified in JavaScript array literal format. Here is a list of built-in plugins that you can reference: (names are case sensitive and those in italics are not yet implemented)
- Character Formatting: bold, italic, underline, strikethrough, subscript, superscript, removeFormat, forecolor, hilitecolor
- Paragraph Formatting:: indent, outdent,justifyCenter, justifyFull, justifyLeft, justifyRight, delete, selectall
- Inserting Objects:insertOrderedList, insertUnorderedList, createlink (use LinkDialog plugin), inserthtml
- Misc.: undo, redo, cut, copy, paste
|
dijit.Editor (Rich Text Editor)
|
||
|
Attributes
|
||
| captureEvents | String[] [] |
Events that should be connected to the underlying editing area, events in this array will be addListener with capture=true |
| customUndo | Boolean true for IE |
Whether to use custom undo/redo support instead of the native browser support. By default, only enable customUndo for IE is available, as it has broken native undo/redo support. Note: the implementation does support other browsers which have W3C DOM2 Range API. |
| editActionInterval | Integer 3 |
When using customUndo, not every keystroke is saved as a step. Instead typing (including delete) will be grouped together: after a user stop typing for editActionInterval seconds, a step will be saved; if a user resume typing within editActionInterval seconds, the timeout will be restarted. By default, editActionInterval is 3 seconds. |
| events | String[] ["onKeyPress", "onKeyDown", "onKeyUp", "onClick"] |
Events that should be connected to the underlying editing area |
| focusOnLoad | Boolean false |
Whether focusing into this instance of rich text when page onload |
| height | String 300px |
Set height to fix the editor at a specific height, with scrolling. By default, this is 300px. If you want to have the editor always resize to accommodate the content, use AlwaysShowToolbar plugin and set height="" |
| inheritWidth | Boolean false |
Whether to inherit the parent's width or (if false) simply use 100%. |
| isClosed | Boolean true |
|
| isLoaded | Boolean false |
|
| minHeight | String 1em |
The minimum height that the editor requires |
| name | String | If a save name is specified, the content is saved and restored when the user leaves the page and returns, or if the editor is not properly closed after editing has started. |
| onLoadDeferred | dojo.Deferred | Deferred can be used to connect to the onLoad function. This will only be set if dojo.Deferred is required |
| plugins | See plugin section | |
| styleSheets | String | Semicolon (";") separated list of .css files for the editing area. |
| toolbar | dijit.Toolbar DOM Node | To use your own custom toolbar |
| updateInterval | Number 200 |
Number of ms between display changes for onNormalizedDisplayChanged |
|
Methods
|
||
| addKeyHandler(/*String*/key, /*Int*/modifiers, /*Function*/handler) | Add a handler for a keyboard shortcut | |
| addPlugin(/*String||Object*/plugin, /*Integer?*/index) | Takes a plugin name as a string or a plugin instance and adds it to the toolbar and associates it with this editor instance. The resulting plugin is added to the Editor's plugins array. If index is passed, it's placed in the plugins array at that index. No big magic, but a nice helper for passing in plugin names via markup. | |
| addStyleSheet(/*dojo._Url*/uri) | Add an external stylesheet for the editing area | |
| beginEditing(/* String */cmd) | Set mark for capturing undo steps | |
| close(/*Boolean*/save, /*Boolean*/force) | Ends the editor and optionally writes back the modified contents to the element from which it originated. | |
| endEditing(/* Boolean */ignore_caret) | Clear the undo buffer, as in after a save | |
| exec(/* String */cmd) | Execute given command | |
| String escapeXml(/*String*/str, /*Boolean*/noSingleQuotes) | Adds escape sequences for special characters in XML: &<>"' Optionally skips escapes for single quotes | |
| open(/*DomNode?*/element) | Transforms the node referenced in this.domNode into a rich text editing node. This results in the creation and replacement with an iframe if designMode(FF)/contentEditable(IE) is used. | |
| placeCursorAtEnd() | Place the cursor at the end of the editing area | |
| placeCursorAtStart() | Place the cursor at the start of the editing area | |
| Boolean queryCommandAvailable(/*Boolean*/ disabled) | Tests whether a command is supported by the host. Clients should check whether a command is supported before attempting to use it, behaviour for unsupported commands is undefined. | |
| Boolean queryCommandEnabled(/* String */cmd) | Checks whether a command is enabled or not | |
| Boolean queryCommandState(/*Boolean*/ disabled) | Checks the state of a given command | |
| String queryCommandValue(/* String */cmd) | Checks the value of a given command | |
| redo() | Redoes last un-done command | |
| removeStyleSheet(/*dojo._Url*/uri) | Remove an external stylesheet for the editing area | |
| replaceValue/*String*/html | This function sets the content while trying to maintain the undo stack (currently, this only works okay with Moz, this is identical to setValue in all other browsers) | |
| undo() | Undo last command | |
|
Extension Points
|
||
| onChange | This is initiated if the editor loses focus and the content is changed | |
| onDisplayChanged | This event is initiated each time the display context changes and the result needs to be reflected in the UI. If you do not want to have the update too often, use onNormalizedDisplayChanged instead | |
| onNormalizedDisplayChanged | This event is initiated on each updateInterval ms or more | |
| setupDefaultShortcuts() | Override to setup your own handlers. The default implementation does not use Editor commands, but directly runs the builtin commands within the underlying browser support. | |
Accessibility (Applies to 1.0 version of editor)
Keyboard for Editor
| Action | Key |
|---|---|
| Move focus to the next widget in the tab order. | Tab (must press tab twice in some situations - see Known Issues below) |
| Move focus to the prior widget in the tab order (the editor toolbar) | Shift+Tab (must press shift-tab twice in some situations - see Known Issues below) |
Keyboard for Editor Toolbar
| Action | Key |
|---|---|
| Move focus to the next enabled button in the toolbar. | arrow right in left to right locales, arrow left in right to left locales |
| Move focus to the previous widget in the toolbar | arrow left in left to right locales; arrow right in right to left locales. |
The arrow keys will not work within any optional drop down lists such as ComboBox or FilteringSelect in the editor toolbar until the drop down list of choices has been activated. Use the backspace or escape key to clear the current selection in the textbox associated with the drop down. When the list of choices is not activated, the arrow keys will move between toolbar buttons rather than within the combobox or select.
Known Issues
- On Firefox 2, the user must press the Tab key twice before keyboard focus moves to the next widget. This is a permanent restriction on Firefox 2. The reason for this is because Firefox implements usage of the tab key within the editor to indent text and shift-tab to outdent text. There is no keyboard mechanism in Firefox to move focus out of the editor. So, the dijit editor traps the tab key in the editor and sets focus to the editor iframe. From there pressing tab again will move to the next focusable item after the editor. When shift-tab is pressed within the editor, focus is set to the toolbar associated with the editor (currently there is always a toolbar defined for a dijit editor). Some people are unhappy with the loss of the tab key functionality within the editor so future versions may have an option to allow the use of tab and shift-tab within the editor to indent and outdent text.
- In IE6 or 7 when the editor has been created from a textarea the user must press tab twice to set focus into the editor to begin inserting or editing text. Likewise, with focus within editor text the user must press shift-tab twice to set focus back to the toolbar.
Plugins
A dijit.Editor plugin adds more features to the Editor widget. It may correspond to one "verb", or command, or it may add other features, such as special enter key handling. The built-in verbs of dijit.Editor (see the list in , like copy/cut/paste and indent/outdent, are implemented inside the editor code. You can add your own by adding Dojo classes with some special properties.
| Plugin | Description |
| AlwaysShowToolbar | Set to true to always display toolbar. No corresponding button. |
| EnterKeyHandling | Make enter key handling consistent across browsers. The blockNodeForEnter property decides the behavior of Enter key. It can be either P, DIV, BR, or empty (which means disable this feature). Anything else will trigger errors. No corresponding button. |
| FontChoice | Adds font drop down. |
| LinkDialog | Provides a dialog for inserting URLs |
| TextColor | Adds text color button |
Setup Clipboard actions for FF
To protect users' private information, unprivileged scripts cannot invoke the Cut, Copy, and Paste commands in the Mozilla rich text editor, so the corresponding buttons on the dijit Editor widget will not work. To enable these functions for purposes of the demo, you must modify your browser preferences.
Configure Firefox
- Quit Firefox. If you have Quick Launch running (in Windows, an icon in the toolbar), quit that too.
- Find your Firefox profile directory. On Windows, this is often located in
C:\Documents and Settings\<Windows login>\Application
Data\Mozilla\Firefox\Profiles\<one folder>.(See also editing configuration files for more info on locating your profile folder.)
- Open the
user.jsfile from that directory in a text editor. If there's nouser.jsfile, create one. - Add these lines to
user.js:
user_pref("capability.policy.policynames", "allowclipboard"); user_pref("capability.policy.allowclipboard.sites", "http://localhost file:// http://dojotoolkit.org"); user_pref("capability.policy.allowclipboard.Clipboard.cutcopy", "allAccess"); user_pref("capability.policy.allowclipboard.Clipboard.paste", "allAccess");*Change the value of capability.policy.allowclipboard.sites to where you want to enable this function. In the example above, this function is enabled for localhost, accessing local files directly (in your own hard drive, without a http server) and dojo website.
- Save the file, and restart Firefox. The Clipboard buttons should now function.
Note: The preference is site as well as protocol specific. For example
user_pref("capability.policy.allowclipboard.sites", "http://dojotoolkit.org")is not the same as
user_pref("capability.policy.allowclipboard.sites", "https://dojotoolkit.org")(the first is http and the second is https)
For more information about security policies, see http://www.mozilla.org/projects/security/components/ConfigPolicy.html.
This page is modified from Setting Prefs for the Mozilla Rich Text Editing Demo.