WYSIWYG Editor Configuration

Version 7.1 by JueWang on 2009/10/17 08:33
Warning: For security reasons, the document is displayed in restricted mode as it is not the current version. There may be differences and errors due to this.

WYSIWYG Editor Configuration

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.

Before you add any button to the toolbar (how to do this please refer to Configuration Section in this page), please make sure you included the corresponding plug-in templates/macros.vm or wysiwyg.plugins in XWiki.XWikiPreferences object.

Let's take add a background color button to WYSIWYG editor toolbar by adding macros.vm file for example:

First, we find this line,  plugins: '$xwiki.getXWikiPreference("wysiwyg.plugins", "submit line separator text list indent history format symbol link image table macro importer#if($full && $request.sync) sync#end")', in your macros.vm file, then we add color, then this line looks like: plugins: '$xwiki.getXWikiPreference("wysiwyg.plugins", "submit line separator text color list indent history format symbol link image table macro importer#if($full && $request.sync) sync#end")'. By doing this your have added the corresponding plug-in to your WYSIWYG editor. You can find what the plug-ins are available in Plugins and Features section.

The second step, we add  "backcolor" toolbar: '$xwiki.getXWikiPreference("wysiwyg.toolbar", "bold italic underline strikethrough backcolor teletype | subscript superscript | unorderedlist orderedlist | outdent indent | undo redo | hr symbol | link unlink | importer")'. Then it is all done. You can reload your web container. You should see the background color button appears on the toolbar of your WYSIWYG editor.

Quick Reference

Configuration Parameters

Parameter NameDescriptionDefault Value
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
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 tool bar 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 comma-separated list of font sizes the user can use to format the text. The font size list box from the tool bar 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.8pt, 10pt, 12pt, 14pt, 18pt, 24pt, 36pt
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
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

XWiki Preferences

Each preference listed below has a matching configuration parameter which it overwrites.

Preference NameTypeConfiguration Parameter
wysiwyg.pluginsStringplugins
wysiwyg.menuStringmenu
wysiwyg.toolbarStringtoolbar

Plugins and Features

The Plugin Name, Toolbar Features and Menu columns match the plugins, toolbar and menu configuration parameters 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
-
indentAllows you to increase or decrease the indentation of list items.
  • outdent: decrease indentation
  • indent: increase indentation
-
imageAdds support for inserting and editing images-image
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
listAdds support for creating lists
  • unorderedlist: creates bulleted lists
  • orderedlist: numbered lists
-
macroAdds support for inserting and editing macros-macro
separatorOffers different kind of content and tool bar separators
  • hr: inserts a horizontal ruler
  • |: separates tool bar features in groups
  • /: breaks the tool bar in multiple lines
-
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
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

By editing XWiki preferences

Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [extensions:Extension.GWT WYSIWYG Editor.Configuration.WebHome]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.

Edit XWiki.XWikiPreferences page with the object editor and fill the properties specified in the XWiki Preferences section. If the XWiki.XWikiPreferences object doesn't have those properties then you'll have to add them to the class.

By editing the velocity templates

The WYSIWYG editor is configured by a velocity macro named wysiwyg_storeConfig which can be found in templates/macros.vm. In older versions of XWiki Enterprise (prior to 1.9) the code of the wysiwyg_storeConfig macro is placed in templates/editwysiwygnew.vm. Use the parameters listed in the Configuration Parameters section to configure the editor.

By customizing the skin

You have to overwrite the wysiwyg_storeConfig velocity macro from templates/macros.vm in your skin.

Get Connected