Edit API

Version 18.2 by Vincent Massol on 2021/04/07 16:50

pencilProvides APIs to associate editors to data types.
TypeJAR
CategoryAPI
Developed by

XWiki Development Team

Rating
0 Votes
LicenseGNU General Public License 1
Bundled With

XWiki Standard

Compatibility

XWiki 8.2RC1+

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.data
$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:

Data Type: org.xwiki.rendering.syntax.SyntaxContent#wysiwyg
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>=<roleHintOrCategory>
edit.defaultEditor.<dataType>#<category>=<roleHintOrSubCategory>

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>.

Example 1

Use the GWT editor for editing wiki content (e.g. page content, textarea xproperty, etc) and the CKEditor editor for... (Marius to fill).

edit.defaultEditor.org.xwiki.rendering.syntax.SyntaxContent#wysiwyg=gwt
edit.defaultEditor.org.xwiki.rendering.block.XDOM#wysiwyg=ckeditor

Example 2

Use the wiki editor as the default editor for any content.

edit.defaultEditor.org.xwiki.rendering.syntax.SyntaxContent=wiki

Script Service

The Edit API provides a script service to access the editors. Sub-services may be available for specific data types.

$services.edit.getEditors('org.xwiki.rendering.syntax.SyntaxContent', 'wysiwyg')
$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.

{{velocity}}
{{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}}
Tags:
    

Get Connected