.. _dijit/Editor:
dijit.Editor
============
:Status: Draft
:Version: 1.0
: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::
:depth: 2
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:
.. cv:: html
This is the initial content.
* 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
-------------------
.. cv-compound::
.. cv:: javascript
.. cv:: html
This instance is created from a div directly with default toolbar and plugins
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:
.. cv:: html
This div will become an auto-expanding editor.
Declarative example: Custom Toolbar
-----------------------------------
Of course the toolbar can be reordered and customized to suit your layout needs.
.. cv-compound::
.. cv:: javascript
.. cv:: html
This instance is created with a subset of functions enabled in the order we want
=======
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.)
.. cv-compound::
.. cv:: javascript
.. cv:: html
This instance is created with additional toolbar/ plugins
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:
.. cv-compound::
.. cv:: javascript
.. cv:: html
This instance is created with customized toolbar/ plugins
================
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 ` 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: :ref:`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 eidtor contents between |
| | |Right-To-Left and Left-ToRight |
+---------------------------------------------+-----------------+----------------------------------------------------------------------+
|dijit._editor.plugins.TextColor |foreColor and |A plugin that provides two actions for altering text color in the |
| |hiliteColor |editor, the font color (foreColor) and the background color |
| | |(hiliteColor). |
+---------------------------------------------+-----------------+----------------------------------------------------------------------+
|dijit._editor.plugins.FontChoice |fontName, |A plugin that allows users to edit certain properties of text, such as|
| |fontSize, and |the size, the font name, and the block formatting (