Edit API
 | Provides APIs to associate editors to data types. |
| Type | JAR |
| Category | API |
| Developed by | |
| Rating | |
| License | GNU General Public License 1 |
| Bundled With | XWiki Standard |
| Compatibility | XWiki 8.2RC1+ |
Table of contents
Description
The Edit API allows us to associate editors to data types. For instance we can associate a date picker to java.util.Date, or a WYSIWYG editor to org.xwiki.rendering.block.XDOM. There can be multiple editors available for a specific data type and the user or the administrator can configure the preferred one.
Some data types can be edited in multiple ways. For instance the content of a wiki page can be edited using a plain text editor or using a visual (WYSIWYG) editor. In order to support this use case each editor can specify a category, which most of the time represents the editing mode. The user can configure the preferred editor for each category. Categories are not mandatory though.
Create Editors
Editors are components. You can create editors directly from Java, using the Component API, or from a wiki page, in which case a component is created and registered for you under the hood.
From Java
To create the editor in Java you need to implement the Editor<D> interface, where D is the data type the editor can edit. Most of the time you will be extending the AbstractTemplateEditor<D> though, for which you only need to specify the template that produces the editor HTML. The editor template can access the edited data and the editor parameters from the "edit" script binding. For Velocity this means:
$edit.parameters
From a Wiki Page
To create the editor from a wiki page you need to edit the page in object mode and add an object of type XWiki.EditorClass. The Code property is used to generate the editor HTML. The edited data and the editor parameters are accessible in the same way as from an editor template, the only difference being that the Code property accepts wiki syntax. The page title and content are used for the editor pretty name and description, respectively.
The wiki-based editors, unlike the Java-based ones, can specify the scope where they should be visible (user, wiki or global).
Configure the Default Editor
The Edit Module provides configuration sources to help you configure the default editor for a specific data type. By adding objects of type XWiki.EditorBindingClass to the user profile, any nested page's WebPreferences page or to the wiki preferences page you can configure the default editor at the level of user, nested page and wiki, respectively.
The Data Type property of XWiki.EditorBindingClass holds the Java class name of the data type and an optional suffix that specifies the category. For instance, here's how the default WYSIWYG editor can be configured:
Role Hint: ckeditor
If no configuration is found in the wiki then the edit module falls back on xwiki.properties where we currently have this:
#-# Indicate the default editor to use for a specific data type.
#-# The editors are components so they are specified using their role hints.
#-# Some data types can be edited in multiple ways, by different types of editors.
#-# Thus you can also indicate the default editor to use from a specific category (editor type).
#-#
#-# The format is this:
#-# edit.defaultEditor.<dataType>=<roleHintOrCategory>
#-# edit.defaultEditor.<dataType>#<category>=<roleHintOrSubCategory>
#-#
#-# The default bindings are:
# edit.defaultEditor.org.xwiki.rendering.syntax.SyntaxContent=text
# edit.defaultEditor.org.xwiki.rendering.syntax.SyntaxContent#text=text
# edit.defaultEditor.org.xwiki.rendering.block.XDOM=text
# edit.defaultEditor.org.xwiki.rendering.block.XDOM#text=text
This means that by default, if there's no editor bindings specified in wiki pages (preferences) and the xwiki.properties is not modified, the Wiki editor is used to edit wiki content.
If you want to configure the default editor for a particular data type in a different way, e.g. using other configuration properties, you can do it by implementing EditorConfiguration<D>.
Known Data Types
- org.xwiki.rendering.syntax.SyntaxContent: text content that uses a specific (wiki) syntax; this is the data type used to associate an editor to the wiki page content and the TextArea object properties.
- org.xwiki.rendering.block.XDOM: the abstract syntax tree (AST) corresponding to wiki content; see the Rendering Module documentation for more information; this is used internally (SyntaxContent is parsed into XDOM) and associating editors to it won't have any effect on the XWiki UI (end users) currently (use SyntaxContent instead)
Known Categories
- text: the text representation of the input (data type) is edited as is (without any transformation); editors in this category can provide syntax highlighting or autocomplete but the user is editing directly the text representation
- wysiwyg: what you see is what you get; the user is editing the visual representation of the input (data type); this corresponds to the WYSIWYG edit mode where the configured (preferred) WYSIWYG editor is loaded
Known Editors
- text: the default wiki syntax editor available in XWiki (text category)
- puretext: plain text editor (no wiki syntax, text category); this is used by TextArea properties that have their "Editor" meta property set to "Plain Text"
- ckeditor: the default WYSIWYG editor available in XWiki, provided by the CKEditor Integration extension (wysiwyg category)
Examples
Following are some examples of how to configure the default editor for a specific data type.
Use CKEditor by default for a given page and its children
If you want the CKEditor (or any other editor for that matter) to be used by default for editing wiki content (page content, TextArea properties, etc.) inside a nested (non-terminal) page and its children then you should:
- edit the page preferences in object mode
- add an object of type XWiki.EditorBindingClass
- set "Data Type" to org.xwiki.rendering.syntax.SyntaxContent
- set the "Role Hint" to ckeditor
- save and then check the result by editing that page or any child page; the editor used should be CKEditor, unless something else overwrites it (e.g. user preference or sheet binding)
Note that if you have multiple WYSIWYG editors installed, CKEditor being one of them, and you just want to set the default WYSIWYG editor for that page and its children then you need to change the "Data Type" to org.xwiki.rendering.syntax.SyntaxContent#wysiwyg (i.e. you specify the category).
Script Service
The Edit API provides a script service to access the editors. Sub-services may be available for specific data types.
$services.edit.getEditor('org.xwiki.rendering.block.XDOM', 'gwt')
$services.edit.getDefaultEditor('java.util.Date')
$services.edit.syntaxContent.getEditors('wysiwyg')
$services.edit.xdom.getEditor('gwt')
$services.edit.syntaxContent.defaultEditor
$services.edit.syntaxContent.defaultWysiwygEditor
$services.edit.syntaxContent.wysiwyg($content, $syntax, $parameters)
Examples
Use the WYSIWYG Editor in a Form
In this example the content edited using the WYSIWYG editor is not bound to an object property.
{{html clean="false"}}
<form class="xform">
...
<dl>
...
<dt><label for="description">Description</label></dt>
<dd>
$!services.edit.syntaxContent.wysiwyg(
'one **two** three',
$services.rendering.resolveSyntax('xwiki/2.1'),
{
'id': 'description',
'name': 'description',
'rows': 25,
'cols': 80
}
)
</dd>
...
</dl>
...
</form>
{{/html}}
{{/velocity}}
