Edit API
Provides APIs to associate editors to data types. |
Type | JAR |
Category | API |
Developed by | XWiki Development Team |
Rating | |
License | GNU General Public License 1 |
Bundled With | XWiki Enterprise |
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 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 the format of the configuration property is this:
edit.defaultEditor.<dataType>#<category>=<roleHintOrSubCategory>
Here's an example:
edit.defaultEditor.org.xwiki.rendering.block.XDOM#wysiwyg=ckeditor
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>.