Wiki source code of Embed a WYSIWYG Editor in a Form
Last modified by Eleni Cojocariu on 2026/10/14 10:44
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | A form of your own can offer a visual editor for wiki content that no object property holds, by rendering one with the [[Edit Script Service>>doc:documentation.xs.dev.edit.script-service.WebHome]]. | ||
| 2 | |||
| 3 | A TextArea property is given its editor by the class it belongs to, so nothing has to be written for it. A field of a form on a wiki page belongs to no object and has no such owner, so the editor is rendered by hand instead. Which editor that is stays the wiki's decision: the call asks for the preferred editor of the ##wysiwyg## category, and [[the resolution chain>>doc:documentation.xs.dev.edit.default-editor-resolution.WebHome]] answers. | ||
| 4 | |||
| 5 | 1. Write the form around the field. ##xform## is the platform's own form style, and pairing a ##~<label for~>## with the field's ##id## is what names the editor for a screen reader: ((( | ||
| 6 | {{code language="velocity"}} | ||
| 7 | {{velocity}} | ||
| 8 | {{html clean="false"}} | ||
| 9 | <form class="xform" action="" method="post"> | ||
| 10 | <dl> | ||
| 11 | <dt><label for="description">Description</label></dt> | ||
| 12 | <dd> | ||
| 13 | ## The editor goes here. | ||
| 14 | </dd> | ||
| 15 | </dl> | ||
| 16 | <p><span class="buttonwrapper"><input type="submit" class="button" value="Save"/></span></p> | ||
| 17 | </form> | ||
| 18 | {{/html}} | ||
| 19 | {{/velocity}} | ||
| 20 | {{/code}} | ||
| 21 | |||
| 22 | ##clean="false"## is required: the HTML cleaner would otherwise rewrite the markup the editor generates. | ||
| 23 | ))) | ||
| 24 | 1. Render the editor where the field goes, passing the content to edit, its syntax, and the parameters of the field: ((( | ||
| 25 | {{code language="velocity"}} | ||
| 26 | $!services.edit.syntaxContent.wysiwyg( | ||
| 27 | 'one **two** three', | ||
| 28 | $services.rendering.resolveSyntax('xwiki/2.1'), | ||
| 29 | { | ||
| 30 | 'id': 'description', | ||
| 31 | 'name': 'description', | ||
| 32 | 'rows': 25, | ||
| 33 | 'cols': 80 | ||
| 34 | } | ||
| 35 | ) | ||
| 36 | {{/code}} | ||
| 37 | |||
| 38 | Write the call with ##$!## rather than ##$##. It returns ##null## when the ##wysiwyg## category holds no editor at all, and a bare ##$## would then print the expression itself into the form. ##$services.edit.syntaxContent.text(...)## is the same call for the ##text## category, and renders the Wiki editor into the field instead. | ||
| 39 | ))) | ||
| 40 | 1. Set the parameters of the field. They are the attributes of the ##~<textarea~>## the editor builds itself, so they are also what the form needs in order to be submitted and labelled: ((( | ||
| 41 | |=Parameter|=Value above|=What it sets | ||
| 42 | |##id##|##description##|the ##id## of the field, which is what the ##~<label for~>## points at | ||
| 43 | |##name##|##description##|the request parameter the field is submitted under | ||
| 44 | |##cols##|##80##|the width of the field, in characters | ||
| 45 | |##rows##|##25##|its height, in lines | ||
| 46 | |||
| 47 | Two more are accepted. ##disabled##, set to ##true##, renders the field for reading only, and ##restricted##, set to ##true##, tells the editor the content is rendered in a restricted context, so that the macros in it are not executed while it is being edited. Any other entry of the map is ignored. | ||
| 48 | ))) | ||
| 49 | 1. Read the submitted value back under the ##name## you passed: ((( | ||
| 50 | {{code language="velocity"}} | ||
| 51 | {{velocity}} | ||
| 52 | #set ($description = $request.getParameter('description')) | ||
| 53 | {{/velocity}} | ||
| 54 | {{/code}} | ||
| 55 | |||
| 56 | The value arrives in **wiki syntax**, not in the HTML the editor was editing. Alongside the field, the editor writes the hidden inputs that ask XWiki to convert the parameter back to the syntax it was given, and the conversion happens before the form's action runs. Posting ##~<p~>hello ~<strong~>world~</strong~>~</p~>## through the form above yields ##hello **world**##. | ||
| 57 | ))) | ||
| 58 | 1. Open the page. The field is a live WYSIWYG editor over the content you passed, and submitting the form hands that content to your own code: ((( | ||
| 59 | {{image reference="wysiwyg-field-form.png" size="extra" alt="A form on a wiki page with a Description label above a WYSIWYG editor showing the text one two three with two in bold, its formatting toolbar across the top, and a Save button below the editor"/}} | ||
| 60 | ))) |
