Wiki source code of Edit
Last modified by Eleni Cojocariu on 2026/10/14 11:32
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | The [[Edit API>>doc:extensions:Extension.Edit Module]] associates editors with data types, so that a date is offered a date picker and wiki content a visual editor. It is a registry, not an editor: it answers the question of which editor a piece of data should open in, and leaves the editing itself to the editor it picked. How to use the editors that answer is a different subject, documented under [[Edit a Page>>doc:documentation.xs.user.base.page.edit.WebHome]]. | ||
| 2 | |||
| 3 | Three notions carry the whole topic. A **data type** is the Java type being edited, such as ##org.xwiki.rendering.syntax.SyntaxContent## for wiki content. An **editor** is a component able to edit one data type, registered under a role hint that is also its identifier. Because the same data can be edited in more than one way, an editor may declare a **category**, which is usually the editing mode, ##text## or ##wysiwyg## for wiki content. A category is optional and several editors may share one, which is why the preferred editor is configured per data type and, when it matters, per category. | ||
| 4 | |||
| 5 | {{plantuml}} | ||
| 6 | @startuml | ||
| 7 | !theme bluegray | ||
| 8 | skinparam nodesep 25 | ||
| 9 | skinparam ranksep 45 | ||
| 10 | |||
| 11 | package "Data type" { | ||
| 12 | card "SyntaxContent" as SC | ||
| 13 | card "XDOM" as XD | ||
| 14 | } | ||
| 15 | package "Category (optional)" { | ||
| 16 | card "text" as C1 | ||
| 17 | card "wysiwyg" as C2 | ||
| 18 | card "puretext" as C3 | ||
| 19 | } | ||
| 20 | package "Editor" { | ||
| 21 | card "text\nrealtime-wiki" as E1 | ||
| 22 | card "ckeditor\nblocknote" as E2 | ||
| 23 | card "puretext" as E3 | ||
| 24 | } | ||
| 25 | |||
| 26 | SC --> C1 | ||
| 27 | SC --> C2 | ||
| 28 | SC --> C3 | ||
| 29 | XD --> C1 | ||
| 30 | XD --> C2 | ||
| 31 | XD --> C3 | ||
| 32 | C1 --> E1 | ||
| 33 | C2 --> E2 | ||
| 34 | C3 --> E3 | ||
| 35 | @enduml | ||
| 36 | {{/plantuml}} | ||
| 37 | |||
| 38 | [[Editors, Data Types and Categories>>doc:documentation.xs.dev.edit.editors-data-types-categories.WebHome]] is the inventory: what a standard XWiki registers, and which editors register for what. | ||
| 39 | |||
| 40 | Editors are [[components>>doc:extensions:Extension.Component Module]], and there are two ways to write one. In Java you implement the ##Editor## role, usually by extending a base class that only asks for a template: [[Write an Editor in Java>>doc:documentation.xs.dev.edit.write-java-editor.WebHome]]. In a wiki page you add one xobject and write the editor's HTML as wiki content, and the component is created and registered for you: [[Write an Editor in a Wiki Page>>doc:documentation.xs.dev.edit.write-wiki-page-editor.WebHome]]. Both routes are in use by the editors a standard XWiki ships. | ||
| 41 | |||
| 42 | When more than one editor is registered for the same data, one of them has to win. [[Default Editor Resolution>>doc:documentation.xs.dev.edit.default-editor-resolution.WebHome]] explains the ordered chain of configuration sources that decides it, and the two fallbacks that apply when nothing is configured at all; [[Configure the Default Editor>>doc:documentation.xs.dev.edit.configure-default-editor.WebHome]] is how an instance is actually configured, from the administration or with an editor binding xobject. | ||
| 43 | |||
| 44 | From a template or a wiki page, the registry is reached through [[the edit script service>>doc:documentation.xs.dev.edit.script-service.WebHome]], which exposes the same lookups to Velocity. [[Embed a WYSIWYG Editor in a Form>>doc:documentation.xs.dev.edit.embed-wysiwyg-form.WebHome]] uses it to put a visual editor in a form field that is not bound to any xobject property. | ||
| 45 | |||
| 46 | The in-place editing shell belongs to this module as well; how it is switched off, and how a visual editor joins it, are described on [[the edit script service>>doc:documentation.xs.dev.edit.script-service.WebHome]] page. | ||
| 47 | |||
| 48 | Taking over an edit lock belongs to the editing flow rather than to this registry: when a Page is already being edited by someone else, XWiki asks the user to confirm before taking the lock over, and [[Document Edit Lock Confirmation>>doc:documentation.xs.dev.edit.edit-lock-confirmation.WebHome]] is how an extension waives that question when taking over is harmless. |
