WYSIWYG Editor Configuration

Version 31.1 by Thomas Mortagne on 2017/03/28 15:17

Welcome to the WYSIWYG editor configuration guide. This page will help you configure XWiki's GWT rich text editor so that it meets your needs.

The information on this page applies only to the GWT-based WYSIWYG editor which is not used by default anymore starting with XWiki 8.2. The new WYSIWYG editor used by default is now CKEditor.

Quick Reference

Configuration Parameters

Parameter NameDescriptionDefault Value
allowExternalImagesSpecifies if inserting external images is allowed or not. Setting this configuration parameter to false hides the External tab from the Insert Image dialog.true
cleanPasteSince 5.0M2. Enable if you want the content that is pasted into the rich text area to be cleaned automatically. The cleaning process implies fixing HTML validity (e.g. by removing elements that are custom to some office document formats) and also filtering text styles like font, color, alignment or margins. Content structure like heading levels, paragraphs, list or tables are preserved. Semantic text styles like strong, emphasize, underline or strikethrough are also preserverd. You can still clean the paste content when this option is disabled if you have the paste icon on the tool bar, but you have to trigger the clean manually. The import plugin is needed in both cases.true
colorsThe list of colors available on the color picker. Colors are specified by their hex code and are separated by comma.#000000,#444444,#666666,#999999,#CCCCCC,#EEEEEE,#F3F3F3,#FFFFFF,
#FF0000,#FF9900,#FFFF00,#00FF00,#00FFFF,#0000FF,#9900FF,#FF00FF,
#F4CCCC,#FCE5CD,#FFF2CC,#D9EAD3,#D0E0E3,#CFE2F3,#D9D2E9,#EAD1DC,
#EA9999,#F9CB9C,#FFE599,#B6D7A8,#A2C4C9,#9FC5E8,#B4A7D6,#D5A6BD,
#E06666,#F6B26B,#FFD966,#93C47D,#76A5AF,#6FA8DC,#8E7CC3,#C27BA0,
#CC0000,#E69138,#F1C232,#6AA84F,#45818E,#3D85C6,#674EA7,#A64D79,
#990000,#B45F06,#BF9000,#38761D,#134F5C,#0B5394,#351C75,#741B47,
#660000,#783F04,#7F6000,#274E13,#0C343D,#073763,#20124D,#4C1130
colorsPerRowThe maximum number of colors the color picker should display on a row8
convertInputWhether to convert the input (the value taken from the hook element) or not. Set this parameter to true if the value of the plain text area being replaced represents wiki syntax. Leave it unset or set it to false if the WYSIWYG editor input is HTMLfalse
debugWhether to load the editor in debug mode or not. In debug mode you can see the dirty HTML generated by the editor, the cleaned HTML, the source text and the rendering events that were triggered during the conversion of the cleaned HTML to source text. The syntax of the source text is controlled by the syntax parameter.false
defaultEditorSpecifies the default tab when displayTabs is true. Use wysiwyg to load initially the WYSIWYG editor and source to load initially the source editor.source
displayTabsWhether to display the WYSIWYG/Source tabs or not. The source editor is not available when the tabs are not displayed. The default tab is controlled by the defaultEditor parameter.false
fontNamesA comma-separated list of font names the user can use to format the text. The font name list box from the toolbar is filled with this list. See font-family CSS property for allowed values.andale mono, arial, arial black, book antiqua, comic sans ms, courier new, georgia, helvetica, impact, symbol, tahoma, terminal, times new roman, trebuchet ms, verdana, webdings, wingdings
fontSizesA space-separated list of font sizes the user can use to format the text. The font size list box from the toolbar is filled with this list. See font-size CSS property for allowed values. Note that relative sizes (like smaller) are not well detected by the editor.8px 10px 12px 14px 18px 24px 36px
hookIdThe id of the HTML element replaced by the editor. Usually the hook element is a plain text area.None
inputURLThe URL of the edited document. Make sure the URL obeys the same origin policy.about:blank
insertimagesSet to currentpage to restrict the image upload and image selection to the edited page. This parameter is used by the insert image feature.None
linkfilesSet to currentpage to restrict the attachment upload and attachment selection to the edited page. This parameter is used by the create link to attachment feature.None
menuA space-separated list of editor plugins that should place their menu entries on the top menu bar. The top menu bar is not displayed if this list is empty, which is the case by default. Make sure the plugins you put on the menu bar are loaded by the editor; see the plugins parameter.Empty string
pageThe name of the edited page. This parameter is used by many plugins in order to be aware of the editing context. See also the space and wiki parameters.None
pluginsA space-separated list of editor plugins that will be loaded. Only the plugins that can work off-line, without the need of a service, are loaded by default. If a plugin provides editing features then you have to change the toolbar parameter in order to enabled them.submit line separator text valign justify list indent history format font color symbol table
rootUIA space-separated list of plugins that extend the editor UI. Make sure the specified plugins are loaded; see the plugins parameter.submit
spaceThe space where the edited page resides. This parameter is used by many plugins in order to be aware of the editing context. See also the page and wiki parameter.None
styleNamesThe list of predefined styles, in JSON format. E.g. [{...}, {"name": "todo", "label": "TODO", "inline": false}, {...}]. A style name is a CSS class name. Only the "name" property is required for each style. "label" equals "name" by default. "inline" is true by default.[]
syncPageThe full name of the page edited in real-time.None
syncResetSet to 1 to reset the synchronization during a real-time editing.0
syntaxThe syntax of the edited document. Make sure the specified syntax is supported by the rendering module. Precisely, there has to be a parser and a renderer for the specified syntax.xhtml/1.0
toolbarA space-separated list of features to be placed on the toolbar. Each feature is provided by a plugin so make sure the required plugins are loaded; see the plugins parameter. You can group features by using the pipe | symbol. To force a multiple line toolbar use the slash / symbol.bold italic underline strikethrough teletype | subscript superscript | justifyleft justifycenter justifyright justifyfull | unorderedlist orderedlist | outdent indent | undo redo | format | fontname fontsize forecolor backcolor | hr removeformat symbol
wikiThe wiki where the edited page resides. This parameter is used by many plugins in order to be aware of the editing context. See also the page and space parameter.None

Plugins and Features

The Plugin Name, Toolbar Features and Menu columns match the plugins, toolbar and menu configuration parameters from the previous section, respectively.

Plugin NameDescriptionToolbar FeaturesMenu
colorControls the colors used inside the rich text area
  • forecolor: text color
  • backcolor: highlight color

fontControls the font used.
  • fontname: change the font name
  • fontsize: change the font size

formatApplies or removes predefined text styles.
  • format: format the text as heading or paragraph
  • removeformat: remove all in-line text formatting

historyControls the editing history.
  • undo: go one step back in the editing history
  • redo: go one step forward in the editing history

imageAdds support for inserting and editing images
  • image: top menu entry
  • imageInsertAttached: insert an image that is attached to a wiki page
  • imageInsertURL: insert an external image, specified by its URL
  • imageEdit: edit selected image
  • imageRemove: remove selected image
importAdds support for importing external content
  • import:officefile: import office documents
  • paste: paste rich text from the clipboard
  • import: top menu entry
  • importOffice: import office documents
indentAllows you to increase or decrease the indentation of list items.
  • outdent: decrease indentation
  • indent: increase indentation

justifyControls the text alignment.
  • justifyleft: align text left
  • justifycenter: center text
  • justifyright: align text right
  • justifyfull: justify text

lineControls the behavior of the Enter key inside the rich text area.
linkAdd support for creating and editing different kind of links
  • link: top menu entry
  • linkEdit: edit the selected link
  • linkRemove: remove the selected link
  • linkWikiPage: create a link to a wiki page
  • linkAttachment: create a link to an attached file
  • linkWebPage: create a link to a web page, specified by its URL
  • linkEmail: create a link to an email address
listAdds support for creating lists
  • unorderedlist: creates bulleted lists
  • orderedlist: numbered lists

macroAdds support for inserting and editing macros
  • macro:macroId: insert the macro with the specified identifier, e.g. use macro:velocity to add a button on the tool bar that triggers the insert Velocity macro wizard
  • macro: top menu entry
  • macroInsert: insert a macro
  • macroEdit: edit the selected macro
  • macroRefresh: re-render all the macros
  • macroCollapse: collapse the selected macros, or all the macros if none is selected
  • macroExpand: expand the selected macros, or all the macros if none is selected
readonlyAllows us to have read-only regions inside the rich text area. The macro plugin depends on it. Read-only elements are marked with the readOnly CSS class name.
separatorOffers different kind of content and toolbar separators
  • hr: inserts a horizontal ruler
  • |: separates toolbar features in groups
  • /: breaks the toolbar in multiple lines
  • |: horizontal menu item separator
styleEnhances the editor with the ability to apply predefined styles to the current text selection.
  • stylename: installs a list box on the tool bar with the available styles

submitEnsures that the content of the editor is submitted and also cached by the browser.
symbolAllows you to insert a special symbol.
  • symbol

tableAdds support for inserting and editing tables.
  • table: top menu entry
  • inserttable: insert a table
  • insertcolbefore: insert a column before the current one
  • insertcolafter: insert a column after the current one
  • deletecol: delete the current column
  • insertrowbefore: insert a row before the current one
  • insertrowafter: insert a row after the current one
  • deleterow: delete current row
  • deletetable: delete current table
textOffers standard text formatting.
  • bold: formats text as bold
  • italic: formats text as italic
  • underline: formats text as underlined
  • strikethrough: formats text as stroke through
  • teletype: formats text as monospace

valignAllows you to write simple formulas.
  • subscript: formats the text as subscript
  • superscript: formats the text as superscript

Configuration

Administration Section

Starting with XWiki Enterprise 3.0 the recommended way to configure the WYSIWYG content editor is through its global administration section.

Velocity Templates

The WYSIWYG editor is configured by a velocity macro named wysiwyg_storeConfig which can be found in templates/macros.vm. Use the parameters listed in the Configuration Parameters section to configure the editor. You may have to restart the server in order for the changes to take effect because velocity templates can be cached at application startup.

Custom Skin

You can overwrite the wysiwyg_storeConfig velocity macro from templates/macros.vm in your custom skin. Reload the edited page to see the WYSIWYG editor changes.

Example

Add an 'Insert HTML macro' button on the tool bar

Suppose you use the HTML macro very often and thus you'd like to have a quick way to insert it from the tool bar. You don't use the HTML macro that often? No problem, it works with any macro. You just need to follow this steps:

  1. Add macro:html (or macro:yourCoolMacro if you like yourCoolMacro more) to the tool bar configuration (use the administration section)
  2. Set a custom icon for the tool bar button by adding:
.macro-html {
  background-image:url("/xwiki/resources/icons/silk/html.gif") !important;
}

to your skin. Of course you can use a different icon and you can replace html with the identifier of your macro. The easiest way to add this CSS fragment to the skin is by adding a XWiki.StyleSheetExtension object to a page and set it to be always used on the wiki.

Get Connected