dijit.Editor¶
| Authors: | Becky Gibson, Bill Keese, Nikolai Onken, Marcus Reimann, Jared Jurkiewicz |
|---|---|
| Developers: | Liu Cougar, Bill Keese, Douglas Hays, Becky Gibson, Jared Jurkiewicz |
| Available: | since V1.0 |
Contents
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.
Features¶
- Provides Rich Text (word processor-like), editing of HTML documents.
- Extensible toolbar with a default set of icons for common actions (bold, italic, underline, indent, and so on)
- Cross-browser support. The RTE cababilities of browsers vary in what they provide and how they are set up. The dijitEditor abtracts this away and provides a single wat to create a rich-text editing field in your pages.
- Built-in filtering support. The editor provides hooks to register HTML and DOM filters with the editor, to pre and post process data going in, or coming out of, the document being edited.
- Pluggable architecture. The editor’s functionality can be extended by implementing and registering plugins with the editor. In fact, all the base commands of editor are effectively plugins. The plugin architecture makes it relatively easy to add new buttons and actions to the toolbar, to being ‘headless’, where it simply registers filters or augments existing actions.
Limitations¶
- The dijit.Editor uses an iframe to separate the document being edited from the rest of the content of your page. This helps protect your main page from being corrupted by editor content and vice-versa. But because of it being iframe isolated, the editor initializes asynchronously. To avoid any actions firing too early against editor content, you should make use of the ‘onLoadDeferred’ object of the editor. For example, see the following example that changes the content after init completes:
<script>
dojo.addOnLoad(function(){
var editor = dijit.byId("myEditor");
editor .onLoadDeferred.addCallback(function(){
editor.attr("value", "<b>This is new content.</b>");
});
});
</script>
<div dojoType="dijit.Editor" id="myEditor">
<p>This is the initial content.</p>
</div>
- The editor’s value property accepts all HTML and renders it in the document being edited. To avoid cross site scripting issues, use the editor’s content filter properties to sanitize the HTML:
dojo.require("dijit.Editor");
dojo.require("my.favorite.sanitizer");
function create() {
var myEditor = new dijit.Editor({
contentPreFilters: [ my.favorite.sanitizer.sanitize ],
contentPostFilters: [ my.favorite.sanitizer.sanitize ]
});
}
- The editor cannot be created on a hidden div. This is in large part due to the frames and similar. You will get odd browser errors should you attempt to create an editor on a hidden div.
- All browsers implement some of the underlying commands differently and may generate different markup, so do not expect identical markup out of each browser. All markup generated by any browser should render ‘equivalently’.
Examples¶
Declarative example¶
<script type="text/javascript">
dojo.require("dijit.Editor");
</script>
<div dojoType="dijit.Editor" id="editor1" onChange="console.log('editor1 onChange handler: ' + arguments[0])">
<p>This instance is created from a div directly with default toolbar and plugins</p>
</div>
Programmatic example¶
Of course, the editor can be created programmatically in addition to declaratively, although even when created programatically you need to specify a source DOM node to replace:
<div id="programmatic2">This div will become an auto-expanding editor.</div>
<button
id="create2"
onclick="new dijit.Editor({height: '', extraPlugins: ['dijit._editor.plugins.AlwaysShowToolbar']}, dojo.byId('programmatic2')); dojo.query('#create2').orphan();">
create expanding editor
</button>
Declarative example: Custom Toolbar¶
Of course the toolbar can be reordered and customized to suit your layout needs.
<script type="text/javascript">
dojo.require("dijit.Editor");
</script>
<div dojoType="dijit.Editor" id="editor1" onChange="console.log('editor1 onChange handler: ' + arguments[0])"
plugins="['cut','copy','paste','|','bold','italic','underline','strikethrough','subscript','superscript','|', 'indent', 'outdent', 'justifyLeft', 'justifyCenter', 'justifyRight']">
<p>This instance is created with a subset of functions enabled in the order we want</p>
</div>
Plugins¶
A plugin (a.k.a. extension) is something that adds a function to the editor, or changes it’s behavior. Dojo includes a number of editor plugins, and developers can write additional plugins on their own.
Most plugins have an associated toolbar button(s), such as the FontChoice plugin (which has a drop down list for fonts), but some plugins (like AlwaysShowToolbar) just affect the Editor’s behavior without changing the toolbar.
The “plugins” parameter controls which plugins are available, and also controls which builtin editor commands are available. It can also be used to re-arrange the default ordering of the buttons.
The basic plugins which are enabled by default are: undo, redo, cut, copy, paste, bold, italic, underline, strikethrough, insertOrderedList, insertUnorderedList, indent, outdent, justifyLeft, justifyRight, justifyCenter, justifyFull, dijit._editor.plugins.EnterKeyHandling
If you want to just add plugins above and beyond the standard configuration, then you should use the “extraPlugins” parameter.
Both the “plugins” parameter and the “extraPlugins” parameter are arrays, where each element in the array can be a simple string or an object (if you need to set options on a plugin).
This example adds the text color, background color, and font selection plugins to the editor by setting extraPlugins. (Technically, the FontChoice plugin provides two commands, foreground-color and highlight-color.)
<script type="text/javascript">
dojo.require("dijit.Editor");
dojo.require("dijit._editor.plugins.FontChoice"); // 'fontName','fontSize','formatBlock'
dojo.require("dijit._editor.plugins.TextColor");
</script>
<div dojoType="dijit.Editor" id="editor2"
extraPlugins="['foreColor','hiliteColor',{name:'dijit._editor.plugins.FontChoice', command:'fontName', generic:true}]"
onChange="console.log('editor2 onChange handler: ' + arguments[0])">
<p>This instance is created with additional toolbar/ plugins</p>
</div>
This example starts from scratch, thus removing some items from the toolbar (as compared to the default), like underline, and adding other features, namely the LinkDialog:
<script type="text/javascript">
dojo.require("dijit.Editor");
dojo.require("dijit._editor.plugins.LinkDialog");
</script>
<div dojoType="dijit.Editor" id="editor3"
plugins="['bold','italic','|','createLink']"
onChange="console.log('editor3 onChange handler: ' + arguments[0])">
<p>This instance is created with customized toolbar/ plugins</p>
</div>
Builtin Commands¶
This is a list of the default commands (plugins) supported by the editor as built-in capabilities. They can be specified in the plugins parameter (in addition to actual editor plugins in the editor/plugins directory or other places):
| Command/Plugin | Description |
| undo | Undo the last operation on the editor contents. |
| redo | Redo the last operation that was ‘undone’ on the editor contents |
| cut | Remove the currently selected text and put it on the clipboard. Please note that some browsers, such as FireFox, do not allow direct access to the clipboard by default (for security purposes). The editor, therefore, cannot use its own events to access and past content there. In those cases, the editor will warn you it cannot and tell you what native hotkey sequence to use to perform the operation. |
| copy | Copy the currently selected text and put it on the clipboard. Please note that some browsers, such as FireFox, do not allow direct access to the clipboard by default (for security purposes). The editor, therefore, cannot use its own events to access and past content there. In those cases, the editor will warn you it cannot and tell you what native hotkey sequence to use to perform the operation. |
| paste | Paste content currently in the clipboard to the editor. Please note that some browsers, such as FireFox, do not allow direct access to the clipboard by default (for security purposes). The editor, therefore, cannot use its own events to access and past content there. In those cases, the editor will warn you it cannot and tell you what native hotkey sequence to use to perform the operation. |
| selectAll | Select all the content in the editor. |
| bold | Bold the currently selected text. |
| italic | Italic the currently selected text. |
| underline | Underline the currently selected text. |
| strikethrough | Strike through the currently selected text. |
| subscript | Make the currently selected text subscript. |
| superscript | Make the currently selected text superscript. |
| removeFormat | Remove formatting on current block. |
| insertOrderedList | Insert an ordered list (1, 2, 3, etc) |
| insertUnorderedList | Insert an unordered list (bullets) |
| insertHorizontalRule | Insert a horizontal line. |
| indent | Indent the current text block or list item |
| outdent | ‘Unindent’ the current text block or list item. |
| justifyLeft | Justify the current text block/selected text to the left. |
| justifyRight | Justify the current text block/selected text to the right. |
| justifyCenter | Center the current text block/selected text. |
| justifyFull | Full-justify the current text block/selected text. |
| createLink | Create a hyperlink. Works best when using the dijit._editor.plugins.LinkDialog <dijit/_editor/plugins/LinkDialog> plugin. |
| unlink | Unlink the current hyperlink undet the cursor/selected text. |
| delete | Delete the currently selected text. |
Additional Editor Plugins¶
There are several additional editor plugins provided by dijit and are listed out on the page: dijit._editor.plugins. These plugins add very useful functionality above and beyond the basics of editor. Please note that several of the plugins actually provide multiple capabilities. To make full use of those plugins, you must register the editor with each capability (short name). A quick summary of the provided function is below:
| Plugin | Short Name(s) | Description |
| dijit._editor.plugins.ToggleDir | toggleDir | A toolbar button for toggling the editor contents between Right-To-Left and Left-ToRight |
| dijit._editor.plugins.TextColor | foreColor and hiliteColor | A plugin that provides two actions for altering text color in the editor, the font color (foreColor) and the background color (hiliteColor). |
| dijit._editor.plugins.FontChoice | fontName, fontSize, and formatBlock | A plugin that allows users to edit certain properties of text, such as the size, the font name, and the block formatting (<p>, <pre>, etc) |
| dijit._editor.plugins.LinkDialog | createLink insertImage | A plugin that provides two actions involving links to external content. The actions handle inserting hyperlinks (<a> tags) and inserting images (<img> tags). The plugin provides basic, but decent validating Tooltip Dialog editors for working with both types of external links. |
| dijit._editor.plugins.FullScreen | fullscreen | A toolbar button plus hotkey for invoking an action that will toggle the editor’s fullscreen mode, where it takes over the full viewport of the browser window object. Note that running the editor in an iframe means the editor can only take over the iframe. New to Dojo toolkit 1.4. |
| dijit._editor.plugins.ViewSource | viewsource | A toolbar button plus hotkey for invoking an action that toggles the viewport of the editor between Rich-Text and HTML view. New to Dojo toolkit 1.4. |
| dijit._editor.plugins.Print | A toolbar button that allows you to print the contents of the editor New to Dojo toolkit 1.4. | |
| dijit._editor.plugins.NewPage | newpage | A toolbar button that allows you clear the contents of the editor to a default state, such as blank. New to Dojo toolkit 1.4. |
Please refer to each plugin’s detail page for more information about it.
DojoX (Dojo eXtensions) contains even more plugins for improving the capabilities of the dijit.Editor. These are functions that were deemed ‘less common’ requirements and were therefore put in the extensions namespace. Please refer to the landing page for more information about them. Below is a quick description of each.
| Plugin | Short Name(s) | Description |
| dojox.editor.plugins.PrettyPrint | prettyprint | A headless (no button), plugin that improves the formatting of the HTML returned from editor.attr(“value”). New to Dojo toolkit 1.4. |
| dojox.editor.plugins.PageBreak | pagebreak | A toolbar button and hotkey for inserting a ‘page break’ into the document. When the document is printed, the printer will break to output to new pages at those points. New to Dojo toolkit 1.4. |
| dojox.editor.plugins.ShowBlockNodes | showblocknodes | A toolbar button and hotkey for showing the block html elements being used to lay out the editor content. New to Dojo toolkit 1.4. |
| dojox.editor.plugins.Preview | preview | A toolbar button that allows you to view the content in a new window You can also have it apply custom stylesheets so that the content is is styled differently from how it appears in the editor. New to Dojo toolkit 1.4. |
| dojox.editor.plugins.Save | save | A toolbar button that allows you to post back the content of the editor to a remote service easily. It is intended for subclassing to customize save behavior. New to Dojo toolkit 1.4. |
| dojox.editor.plugins.ToolbarLineBreak | || or toolbarlinebreak | A simple plugin for splitting the toolbar up into multiple lines. Useful in controlling how the dijit.Editor toolbar wraps. New to Dojo toolkit 1.4. |
| dojox.editor.plugins.NormalizeIndentOutdent | normalizeindentoutdent | A headless plugin that tries to standardize how browsers hander indent and outdent operations on content. This plugin is experimental New to Dojo toolkit 1.4. |
| dojox.editor.plugins.Breadcrumb | breadcrumb | A plugin that adds a footer toolbar to the editor that allows you to see the node position of the cursor. It also provides selection, deletion, and cursor move functions. This plugin is experimental. New to Dojo toolkit 1.4. |
| dojox.editor.plugins.FindReplace | findreplace | A plugin that provides a find and replace togglable toolbar to the editor. This plugin is experimental. New to Dojo toolkit 1.4. |
| dojox.editor.plugins.PasteFromWord | pastefromword | A plugin that provides paste window for content from Microsoft Word and similar formats and tries to filter out bad classnames, styles, and so on. New to Dojo toolkit 1.5. |
| dojox.editor.plugins.InsertAnchor | insertanchor | A simple plugin for inserting anchors (named hash points) in the page New to Dojo toolkit 1.5. |
| dojox.editor.plugins.CollapsibleToolbar | collapsibletoolbar | A simple plugin for allowing the collapse of the top button tooolbar for more editor space. New to Dojo toolkit 1.5. |
| dojox.editor.plugins.TextColor | foreColor hiliteColor | A varient of the dijit._editor.plugins.TextColor that uses the dojox.widget.ColorPicker as the color selector. New to Dojo toolkit 1.5. |
| dojox.editor.plugins.Blockquote | blockquote | A plugin for marking a section as a quite by wrapping it in a blockquote tag. New to Dojo toolkit 1.5. |
Auto-expanding editor¶
Typically an editor has a constant height, and if there’s a lot of content it gets a scrollbar. This is in addition to the main scrollbar for the page.
Editor also has a mode like dijit.form.Textarea where the more a user types, the more the text box expands.
However, that’s a bit tricky because if implemented naively the toolbar would eventually scroll off the top of the page.
The AlwaysShowToolbar plugin prevents that. It’s used along with setting height=”” parameter setting.
<script type="text/javascript">
dojo.require("dijit.Editor");
dojo.require("dijit._editor.plugins.AlwaysShowToolbar");
</script>
<div dojoType="dijit.Editor" id="editor5"
extraPlugins="['dijit._editor.plugins.AlwaysShowToolbar']">
<p>
This editor is created from a div with AlwaysShowToolbar plugin (do not forget to set height="").
</p>
</div>
Accessibility (1.0 and later versions)¶
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.
Screen Reader Issues¶
In order for the screen reader to announce a label for the editor, the developer must include a label element that is associated with the editor using the for attribute. When the editor is created, Dojo will create a title element for the HTML document within the editor that contains the label text. The screen reader will announce that title when the editor component gets focus.
Known Issues¶
- On Firefox, 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). Even though Firefox 3 now supports the use of the contentEditable attribute to create the editor using a div element, the dijit editor is still implemented using an iframe in Firefox 3 and this tabbing issue remains. Some people are unhappy with the loss of the tab key functionality within the editor. Version 1.2 includes a plug-in option to allow the use of tab and shift-tab within the editor to indent and outdent text. The tabbing issue has been updated for Dojo 1.4. Two tab key presses are no longer required to interact with the editor in the supported browsers.
- 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.