Embed a WYSIWYG Editor in a Form
Steps
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.
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 answers.
- 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:
{{velocity}} {{html clean="false"}} <form class="xform" action="" method="post"> <dl> <dt><label for="description">Description</label></dt> <dd> ## The editor goes here. </dd> </dl> <p><span class="buttonwrapper"><input type="submit" class="button" value="Save"/></span></p> </form> {{/html}} {{/velocity}}clean="false" is required: the HTML cleaner would otherwise rewrite the markup the editor generates.
- Render the editor where the field goes, passing the content to edit, its syntax, and the parameters of the field:
$!services.edit.syntaxContent.wysiwyg( 'one **two** three', $services.rendering.resolveSyntax('xwiki/2.1'), { 'id': 'description', 'name': 'description', 'rows': 25, 'cols': 80 } )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.
- 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:
Parameter Value above What it sets id description the id of the field, which is what the <label for> points at name description the request parameter the field is submitted under cols 80 the width of the field, in characters rows 25 its height, in lines 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.
- Read the submitted value back under the name you passed:
{{velocity}} #set ($description = $request.getParameter('description')) {{/velocity}}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.
- 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:
