Wiki source code of Write an Editor in a Wiki Page
Last modified by superadmin on 2026/10/14 10:44
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | Add an editor to a running instance without compiling anything, by writing it as a wiki page instead of [[in Java>>doc:documentation.xs.dev.edit.write-java-editor.WebHome]]. | ||
| 2 | |||
| 3 | The editor is an ##XWiki.EditorClass## object on a page, and the object's properties say what it edits, under which identifier and with which code. The example below is a plain text area for wiki content, in the ##text## category. | ||
| 4 | |||
| 5 | 1. Create the page that will hold the editor. Its **title** becomes the editor's name and its **content** the editor's description, read from the translated page every time the editor is described, so both follow the reader's language: ((( | ||
| 6 | {{code language="none"}} | ||
| 7 | Title: Simple Text Area | ||
| 8 | Content: A plain text area with no toolbar, for editing wiki syntax by hand. | ||
| 9 | {{/code}} | ||
| 10 | ))) | ||
| 11 | 1. Add an object of type ##XWiki.EditorClass## to that page with the [[Object editor>>doc:documentation.xs.user.base.page.edit.edit-object-editor.WebHome]]: ((( | ||
| 12 | {{image reference="add-editor-class-object.png" size="extra" alt="The object editor of the Simple Text Area page, with EditorClass typed in the New object field and XWiki EditorClass offered in the drop down list below it"/}} | ||
| 13 | ))) | ||
| 14 | 1. Fill the object's six properties: ((( | ||
| 15 | |=Property|=Value in this example|=What it is | ||
| 16 | |Data Type|##org.xwiki.rendering.syntax.SyntaxContent##|the Java type the editor edits | ||
| 17 | |Role Hint|##simple-textarea##|the editor's identifier | ||
| 18 | |Code|(the next step)|the wiki content that produces the editor | ||
| 19 | |Icon|##pencil##|the icon shown for the editor | ||
| 20 | |Category|##text##|the editing mode the editor belongs to | ||
| 21 | |Scope|Current Wiki|where the editor is registered | ||
| 22 | |||
| 23 | {{image reference="editor-class-properties.png" size="extra" alt="The EditorClass object of the Simple Text Area page, with Data Type set to org.xwiki.rendering.syntax.SyntaxContent, Role Hint to simple-textarea, the Code property holding the editor code, Icon set to pencil, Category to text and Scope to Current Wiki"/}} | ||
| 24 | |||
| 25 | The first two decide whether the editor exists at all: the query that collects the editors defined in wiki pages skips an object whose **Role Hint** is empty, and an object whose **Data Type** is not a type the instance can load fails to register, with the reason in the log. **Scope** is the one thing a Java editor cannot choose: **Current User** registers the editor for the page's author only, **Current Wiki** for the wiki holding the page, **Global** for every wiki of the farm, and an empty value is read as Current Wiki. | ||
| 26 | ))) | ||
| 27 | 1. Write the **Code** property. Unlike the template of a Java editor it is page content, so it is written in the page's own syntax and may use macros. It reads ##$edit.data## and ##$edit.parameters## from [[the same ##edit## binding a Java editor's template uses>>doc:documentation.xs.dev.edit.write-java-editor.WebHome]]: ((( | ||
| 28 | {{code language="velocity"}} | ||
| 29 | {{velocity}} | ||
| 30 | {{html clean="false"}} | ||
| 31 | <div class="box infomessage">Editing $escapetool.xml($edit.data.syntax.toIdString()) content.</div> | ||
| 32 | <textarea id="$!edit.parameters.id" name="$!edit.parameters.name" | ||
| 33 | rows="$!edit.parameters.rows" cols="$!edit.parameters.cols">$escapetool.xml($edit.data.content)</textarea> | ||
| 34 | {{/html}} | ||
| 35 | {{/velocity}} | ||
| 36 | {{/code}} | ||
| 37 | |||
| 38 | {{warning}} | ||
| 39 | The code runs with the rights of the editor page's author, but in the context of the page being edited, which is how it reaches the data put on the script context. Giving edit right on the editor page is therefore giving the ability to run code for everyone who opens the editor. | ||
| 40 | {{/warning}} | ||
| 41 | ))) | ||
| 42 | 1. Save the page. The editor is registered as soon as the page is saved, and naming it in the query string of an edit URL is enough to see it at work on the data type and category it declared: ((( | ||
| 43 | {{code language="none"}} | ||
| 44 | /bin/edit/Sandbox/MeetingNotes?editor=wiki&SyntaxContent.text.editor=simple-textarea | ||
| 45 | {{/code}} | ||
| 46 | |||
| 47 | {{image reference="wiki-page-editor-rendered.png" size="extra" alt="The wiki edit form of the Meeting Notes page rendering the Simple Text Area editor, with the message Editing xwiki 2.1 content above the content text area"/}} | ||
| 48 | |||
| 49 | To hand the editor to a user, a space or the whole wiki without naming it in the URL, see [[Configure the Default Editor>>doc:documentation.xs.dev.edit.configure-default-editor.WebHome]]. | ||
| 50 | ))) | ||
| 51 | |||
| 52 | Two of the editors shipped with XWiki are written this way and are worth reading as examples: ##CKEditor.SyntaxContentEditor## registers ##ckeditor## in the ##wysiwyg## category, and ##XWiki.Realtime.WikiEditor## registers ##realtime-wiki## in the ##text## category, both with the Current Wiki scope. Both keep the editor code in the page content and set the Code property to an include of their own page, and both guard that content so that it renders only while the page is being used as an editor, which keeps it out of the editor's description. |
