Edit Script Service
Reference
$services.edit is the entry point to the editor registry from Velocity. Each of its methods mirrors one on the Java EditorManager role, so a template can list the editors available for a data type, look one up by role hint, or ask for the one that the resolution chain prefers. A lookup that finds nothing returns null rather than raising an error.
Three sub-services narrow it. document answers one question about in-place editing; syntaxContent and xdom are the same methods with their data type already bound, plus a shorthand for each of the two usual categories. The render helpers text and wysiwyg exist only on syntaxContent. A sub-service is reached with get($name), which in Velocity is also written as a property, as in $services.edit.syntaxContent.
Methods
| Expression | Returns | Notes |
|---|---|---|
| $services.edit.getEditors($dataType[, $category]) | The editors registered for the data type, restricted to the category when one is given. | The Java signature takes a java.lang.reflect.Type, but the class name as a String works through automatic argument conversion. XWiki.WYSIWYG.DefaultEditorConfig calls it that way. |
| $services.edit.getEditor($dataType, $hint) | The editor registered under that role hint. | null when no editor carries the hint. |
| $services.edit.getDefaultEditor($dataType[, $category]) | The preferred editor, resolved by the chain. | null when no editor at all is registered for the data type, which is the case for most Java types: only SyntaxContent and XDOM have editors. |
| $services.edit.getDefaultEditorId($dataType[, $category]) | The role hint of that editor, as a String. | Use it when the identifier is what you need, not the editor. |
| $services.edit.get($name) | A sub-service. | syntaxContent, xdom and document. |
| $services.edit.syntaxContent.getEditors([$category]) | As above, for SyntaxContent. | $services.edit.xdom offers the same members for XDOM. |
| $services.edit.syntaxContent.getEditor($hint) | As above, for SyntaxContent. | For instance ckeditor. |
| $services.edit.syntaxContent.defaultEditor | The preferred editor for the data type, with no category. | defaultEditorId returns its role hint instead. The comment field uses it. |
| $services.edit.syntaxContent.defaultTextEditor | The preferred editor of the text category. | Shorthand for getDefaultEditor('text'). |
| $services.edit.syntaxContent.defaultWysiwygEditor | The preferred editor of the wysiwyg category. | The most used expression of all in the platform, usually followed by .descriptor.id. |
| $services.edit.syntaxContent.text($content, $syntax, $parameters) | The HTML of the preferred text editor, rendered over that content. | null when the category has no editor. The skin's editwiki.vm renders the Wiki editor this way. |
| $services.edit.syntaxContent.wysiwyg($content, $syntax, $parameters) | The HTML of the preferred wysiwyg editor, rendered over that content. | null when the category has no editor. editwysiwyg.vm renders the standalone WYSIWYG editor this way, and Embed a WYSIWYG Editor in a Form shows the parameters. |
| $services.edit.document.inPlaceEditingEnabled() | Whether a Page may be edited without leaving the view. | Reads edit.document.inPlaceEditing.enabled, which defaults to true. |
In-Place Editing
The Edit API also ships the shell that lets a Page be edited in place, without leaving the view. It is switched off instance-wide by setting edit.document.inPlaceEditing.enabled to false in xwiki.properties, and a template asks whether it is on with $services.edit.document.inPlaceEditingEnabled().
A WYSIWYG editor joins in-place editing by shipping a RequireJS module whose name is its own identifier wrapped in xwiki- and -inline, so that the ckeditor editor supplies xwiki-ckeditor-inline and blocknote supplies xwiki-blocknote-inline. The shell builds that name from $services.edit.syntaxContent.defaultWysiwygEditor.descriptor.id and loads it. When the module cannot be loaded, editing falls back to the standalone edit mode without reporting anything.
