WYSIWYG Editor Module
 | Generic API for all WYSIWYG content editors. |
| Type | JAR |
| Category | Other |
| Developed by | XWiki Development Team |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
Table of contents
Description
This module provides a generic API that can be used by any WYSIWYG editor that wants to integrate with XWiki. Besides that, it also publishes a section in the Wiki Administration to configure the default WYSIWYG content editor.
Generic API
This module provides the following APIs:
- clean HTML coming from a WYSIWYG editor
- convert between (annotated) HTML and wiki syntax
- round-trip conversion (go from annotated HTML to wiki syntax and back, which is useful if you want to render the wiki syntax rendering macros)
- an HTTP filter to convert automatically the value of specific HTTP request parameters from HTML to wiki syntax
- import content from office attachments
- a script service ($services.wysiwyg) that exposes most of the above, plus adds support for:
- checking if a specific wiki syntax can be edited by a WYSIWYG editor
- retrieving the HTML syntax used by the WYSIWYG editor
- render a specific page template (the WYSIWYG editor content template)
Administration Section
The administration section allows administrators to configure the default WYSIWYG content editor, which is useful in case multiple installed extensions provide WYSIWYG content editing capability.
WYSIWYG Editor Integrations
The following WYSIWYG editor integrations are available:
- CKEditor Integration
- Realtime WYSIWYG Editor (based on CKEditor Integration)
- GWT WYSIWYG Editor (deprecated and unmaintained)
Conversion Filter
This module provides a servlet request filter that supports converting the content submitted by a WYSIWYG editor, from the syntax used internally by the editor to the syntax used to store the content. For instance the content is normally stored as wiki syntax but the WYSIWYG editor doesn't know how to edit wiki syntax. It knows how to edit HTML, we need to:
- convert the wiki syntax to HTML before loading the editor, in order to pass the HTML to the editor
- convert the HTML produced by the editor back to the wiki syntax used to store the edited content in a wiki page
The latter is achieved using the conversion filter: the WYSIWYG editor submits HTML and the conversion filter intercepts the submit request (server-side) and replaces the HTML with the result of converting the HTML to the storage wiki syntax. For this to work the editor needs to send 3 request parameters like this:
fieldName=value
RequiresHTMLConversion=fieldName
fieldName_syntax=xwiki/2.1Replace "fieldName" with the name of the edited field and replace "xwiki/2.1" with the ID of the storage syntax.
XWiki 17.4.0+
If the WYSIWYG editor doesn't use HTML internally to edit the content, then it needs to submit 4 parameters instead:
fieldName=value
RequiresConversion=fieldName
fieldName_inputSyntax=foo/1.0
fieldName_outputSyntax=xwiki/2.1Note that an important difference between RequiresHTMLConversion and RequiresConversion is that the former performs some HTML cleanup as well, while the latter simply converts from one syntax to another. So while you can use the second method to convert from HTML to wiki syntax, you must be aware that you lose the cleanup.
Rendering transformations (e.g. macros) are not executed in both cases (RequiresHTMLConversion and RequiresConversion).
Configuration
XWiki 17.5.0+
Some properties of this module can be configured through xwiki.properties:
#-------------------------------------------------------------------------------------
# WYSIWYG API
#-------------------------------------------------------------------------------------
#-# [Since 17.5.0]
#-# Define if the type of the macro parameter should be inferred from their default value when no specific type is
#-# indicated to build the macro configuration UI. This is currently used to automatically set the type to Boolean
#-# when a parameter has a default value set to 'true' or 'false' and doesn't define a specific type.
# wysiwyig.inferMacroParameterTypeBasedOnDefaultValue=truePrerequisites & Installation Instructions
We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).
You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.
Dependencies
Dependencies for this extension (org.xwiki.platform:xwiki-platform-wysiwyg-api 17.8.0):
- org.xwiki.commons:xwiki-commons-xml 17.8.0
- org.xwiki.rendering:xwiki-rendering-syntax-annotatedhtml5 17.8.0
- org.xwiki.platform:xwiki-platform-oldcore 17.8.0
- org.xwiki.platform:xwiki-platform-bridge 17.8.0
- org.xwiki.platform:xwiki-platform-model-api 17.8.0
- org.xwiki.platform:xwiki-platform-container-api 17.8.0
- org.xwiki.commons:xwiki-commons-displayer 17.8.0
- org.xwiki.commons:xwiki-commons-velocity 17.8.0
