Hide last authors
Marius Dumitru Florea 23.4 1 {{velocity output="false"}}
2 $xwiki.ssx.use($doc.name)
3 {{/velocity}}
4
Marius Dumitru Florea 1.1 5 = WYSIWYG Editor Configuration =
6
JueWang 10.1 7 (% class="floatinginfobox" %)
8 (((**Contents**
Marius Dumitru Florea 1.1 9
JueWang 10.1 10 {{toc/}})))
Marius Dumitru Florea 1.1 11
12
Marius Dumitru Florea 9.1 13 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.
JueWang 6.1 14
Marius Dumitru Florea 21.1 15 {{info}}The information from this page applies only to the new GWT-based WYSIWYG editor that comes with XWiki 2.0 syntax.{{/info}}
JueWang 6.1 16
Marius Dumitru Florea 1.1 17 == Quick Reference ==
18
19 === Configuration Parameters ===
20
Marius Dumitru Florea 23.2 21 (% class="oddEven" style="clear:right" %)
Marius Dumitru Florea 15.1 22 |=(% width="15%" %)Parameter Name|=(% width="50%" %)Description|=Default Value
Marius Dumitru Florea 12.1 23 |**allowExternalImages**|Specifies if inserting external images is allowed or not. Setting this configuration parameter to ##false## hides the //External// tab from the Insert Image dialog.|##true##
JueWang 10.1 24 |**colors**|The 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,
25 #FF0000,#FF9900,#FFFF00,#00FF00,#00FFFF,#0000FF,#9900FF,#FF00FF,
26 #F4CCCC,#FCE5CD,#FFF2CC,#D9EAD3,#D0E0E3,#CFE2F3,#D9D2E9,#EAD1DC,
27 #EA9999,#F9CB9C,#FFE599,#B6D7A8,#A2C4C9,#9FC5E8,#B4A7D6,#D5A6BD,
28 #E06666,#F6B26B,#FFD966,#93C47D,#76A5AF,#6FA8DC,#8E7CC3,#C27BA0,
29 #CC0000,#E69138,#F1C232,#6AA84F,#45818E,#3D85C6,#674EA7,#A64D79,
30 #990000,#B45F06,#BF9000,#38761D,#134F5C,#0B5394,#351C75,#741B47,
31 #660000,#783F04,#7F6000,#274E13,#0C343D,#073763,#20124D,#4C1130##
Marius Dumitru Florea 1.1 32 |**colorsPerRow**|The maximum number of colors the color picker should display on a row|##8##
Marius Dumitru Florea 14.1 33 |**convertInput**|Whether 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 HTML|##false##
Marius Dumitru Florea 21.2 34 |**debug**|Whether 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##
35 |**defaultEditor**|Specifies the default tab when ##displayTabs## is ##true##. Use ##wysiwyg## to load initially the WYSIWYG editor and ##source## to load initially the source editor.|##source##
36 |**displayTabs**|Whether 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##
Marius Dumitru Florea 9.1 37 |**fontNames**|A 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##
Marius Dumitru Florea 24.1 38 |**fontSizes**|A 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##
Marius Dumitru Florea 1.1 39 |**hookId**|The id of the HTML element replaced by the editor. Usually the hook element is a plain text area.|//None//
40 |**inputURL**|The URL of the edited document. Make sure the URL obeys the same origin policy.|##about:blank##
41 |**insertimages**|Set to ##currentpage## to restrict the image upload and image selection to the edited page. This parameter is used by the insert image feature.|//None//
42 |**linkfiles**|Set 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//
Marius Dumitru Florea 21.3 43 |**menu**|A 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//
44 |**page**|The 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//
45 |**plugins**|A 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>>#HPluginsandFeatures]] 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##
46 |**rootUI**|A space-separated list of plugins that extend the editor UI. Make sure the specified plugins are loaded; see the ##plugins## parameter.|##submit##
47 |**space**|The 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//
Marius Dumitru Florea 18.1 48 |**styleNames**|The 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.|##[]##
Marius Dumitru Florea 1.1 49 |**syncPage**|The full name of the page edited in real-time.|//None//
50 |**syncReset**|Set to ##1## to reset the synchronization during a real-time editing.|##0##
51 |**syntax**|The 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##
Marius Dumitru Florea 21.3 52 |**toolbar**|A 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##
53 |**wiki**|The 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//
Marius Dumitru Florea 1.1 54
55 === Plugins and Features ===
56
Marius Dumitru Florea 21.4 57 The //Plugin Name//, //Toolbar Features// and //Menu// columns match the ##plugins##, ##toolbar## and ##menu## configuration parameters from the previous section, respectively.
Marius Dumitru Florea 1.1 58
Marius Dumitru Florea 23.2 59 (% class="oddEven" %)
Marius Dumitru Florea 1.1 60 |=Plugin Name|=Description|=Toolbar Features|=Menu
61 |**color**|Controls the colors used inside the rich text area|(((* **forecolor**: text color
Marius Dumitru Florea 21.4 62 * **backcolor**: highlight color)))|
Marius Dumitru Florea 1.1 63 |**font**|Controls the font used.|(((* **fontname**: change the font name
Marius Dumitru Florea 21.4 64 * **fontsize**: change the font size)))|
Marius Dumitru Florea 1.1 65 |**format**|Applies or removes predefined text styles.|(((* **format**: format the text as heading or paragraph
Marius Dumitru Florea 21.4 66 * **removeformat**: remove all in-line text formatting)))|
Marius Dumitru Florea 1.1 67 |**history**|Controls the editing history.|(((* **undo**: go one step back in the editing history
Marius Dumitru Florea 21.4 68 * **redo**: go one step forward in the editing history)))|
Marius Dumitru Florea 25.1 69 |**image**|Adds support for inserting and editing images||(((* **image**: top menu entry
70 * **imageInsertAttached**: insert an image that is attached to a wiki page
71 * **imageInsertURL**: insert an external image, specified by its URL
72 * **imageEdit**: edit selected image
73 * **imageRemove**: remove selected image)))
74 |**import**|Adds support for importing external content|(((* **import:officefile**: import office documents
75 * **paste**: paste rich text from the clipboard)))|(((* **import**: top menu entry
76 * **importOffice**: import office documents)))
Marius Dumitru Florea 1.1 77 |**indent**|Allows you to increase or decrease the indentation of list items.|(((* **outdent**: decrease indentation
Marius Dumitru Florea 21.4 78 * **indent**: increase indentation)))|
Marius Dumitru Florea 1.1 79 |**justify**|Controls the text alignment.|(((* **justifyleft**: align text left
80 * **justifycenter**: center text
81 * **justifyright**: align text right
Marius Dumitru Florea 21.4 82 * **justifyfull**: justify text)))|
83 |**line**|Controls the behavior of the Enter key inside the rich text area.||
Marius Dumitru Florea 25.1 84 |**link**|Add support for creating and editing different kind of links||(((* **link**: top menu entry
85 * **linkEdit**: edit the selected link
86 * **linkRemove**: remove the selected link
87 * **linkWikiPage**: create a link to a wiki page
88 * **linkAttachment**: create a link to an attached file
89 * **linkWebPage**: create a link to a web page, specified by its URL
90 * **linkEmail**: create a link to an email address)))
Marius Dumitru Florea 1.1 91 |**list**|Adds support for creating lists|(((* **unorderedlist**: creates bulleted lists
Marius Dumitru Florea 21.4 92 * **orderedlist**: numbered lists)))|
Marius Dumitru Florea 26.2 93 |**macro**|Adds 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
Marius Dumitru Florea 26.1 94 * **macroInsert**: insert a macro
95 * **macroEdit**: edit the selected macro
96 * **macroRefresh**: re-render all the macros
97 * **macroCollapse**: collapse the selected macros, or all the macros if none is selected
98 * **macroExpand**: expand the selected macros, or all the macros if none is selected)))
Marius Dumitru Florea 21.4 99 |**readonly**|Allows 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.||
Marius Dumitru Florea 9.1 100 |**separator**|Offers different kind of content and toolbar separators|(((* **hr**: inserts a horizontal ruler
101 * **|**: separates toolbar features in groups
Marius Dumitru Florea 27.1 102 * **/**: breaks the toolbar in multiple lines)))|(((* **|**: horizontal menu item separator)))
Marius Dumitru Florea 21.4 103 |**style**|Enhances 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)))|
104 |**submit**|Ensures that the content of the editor is submitted and also cached by the browser.||
Marius Dumitru Florea 21.6 105 |**symbol**|Allows you to insert a special symbol.|(((* **symbol**)))|
Marius Dumitru Florea 27.1 106 |**table**|Adds support for inserting and editing tables.||(((* **table**: top menu entry
107 * **inserttable**: insert a table
108 * **insertcolbefore**: insert a column before the current one
109 * **insertcolafter**: insert a column after the current one
110 * **deletecol**: delete the current column
111 * **insertrowbefore**: insert a row before the current one
112 * **insertrowafter**: insert a row after the current one
113 * **deleterow**: delete current row
114 * **deletetable**: delete current table)))
Marius Dumitru Florea 1.1 115 |**text**|Offers standard text formatting.|(((* **bold**: formats text as bold
116 * **italic**: formats text as italic
117 * **underline**: formats text as underlined
118 * **strikethrough**: formats text as stroke through
Marius Dumitru Florea 21.4 119 * **teletype**: formats text as monospace)))|
Marius Dumitru Florea 1.1 120 |**valign**|Allows you to write simple formulas.|(((* **subscript**: formats the text as subscript
Marius Dumitru Florea 21.4 121 * **superscript**: formats the text as superscript)))|
Marius Dumitru Florea 1.1 122
Marius Dumitru Florea 21.1 123 === XWiki Preferences ===
124
Marius Dumitru Florea 21.13 125 In XWiki Enterprise 2.x the WYSIWYG content editor is configurable using XWiki preferences. Each preference listed below has a matching configuration parameter which it overwrites.
Marius Dumitru Florea 21.1 126
Marius Dumitru Florea 23.2 127 (% class="oddEven" %)
Marius Dumitru Florea 21.1 128 |=Preference Name|=Type|=Configuration Parameter
129 |**wysiwyg.plugins**|TextArea|plugins
130 |**wysiwyg.menu**|String|menu
131 |**wysiwyg.toolbar**|TextArea|toolbar
132
Marius Dumitru Florea 1.1 133 == Configuration ==
134
Marius Dumitru Florea 21.1 135 === Administration Section ===
Marius Dumitru Florea 1.1 136
Marius Dumitru Florea 21.9 137 Starting with XWiki Enterprise 3.0 the recommended way to configure the WYSIWYG content editor is through its global administration section.
Marius Dumitru Florea 1.1 138
Marius Dumitru Florea 21.1 139 === XWiki.XWikiPreferences ===
Marius Dumitru Florea 1.1 140
Marius Dumitru Florea 21.1 141 {{warning}}Configuring the WYSIWYG editor through XWiki preferences is possible only in XWiki Enterprise **2.x**.{{/warning}}
Marius Dumitru Florea 1.1 142
Marius Dumitru Florea 21.7 143 Edit ##XWiki.XWikiPreferences## page with the object editor and fill the properties specified in the [[XWiki Preferences>>#HXWikiPreferences]] quick reference section above. If the ##XWiki.XWikiPreferences## object doesn't have those properties then you'll have to add them to the class. Finally, reload the edited page to see the WYSIWYG editor changes.
Marius Dumitru Florea 2.1 144
Marius Dumitru Florea 21.1 145 === Velocity Templates ===
Marius Dumitru Florea 1.1 146
Marius Dumitru Florea 21.7 147 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>>#HConfigurationParameters]] quick reference 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.
Marius Dumitru Florea 9.1 148
Marius Dumitru Florea 21.1 149 === Custom Skin ===
150
Marius Dumitru Florea 21.7 151 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.
Marius Dumitru Florea 21.1 152
Marius Dumitru Florea 9.1 153 == Examples ==
154
155 === Enable toolbar features ===
156
Marius Dumitru Florea 21.1 157 {{warning}}This applies only to XWiki Enterprise **2.x**. Starting with **3.x** you can use the administration section.{{/warning}}
158
Marius Dumitru Florea 9.1 159 Editing features (e.g. make text bold, change text color) are provided by editor plugins (e.g. text, color). Another way to see this is that similar editing features are grouped together in a plugin (e.g. changing the background color and the text color features form the color plugin). In order to enable a feature and make it available on the toolbar for instance you first have to enable the plugin that provides that feature.
160
Marius Dumitru Florea 21.8 161 Let's see how you can add the Background Color button to the WYSIWYG editor toolbar. In this example we're going to edit ##macros.vm## template but you can do the same using only XWiki preferences.
Marius Dumitru Florea 9.1 162
Marius Dumitru Florea 21.8 163 First, search for the ##wysiwyg_storeConfig## velocity macro in ##templates/macros.vm##. This macro should have a line like this:
Marius Dumitru Florea 9.1 164
165 {{code}}
Marius Dumitru Florea 21.8 166 #set($ok = $parameters.put('plugins', $xwiki.getXWikiPreference('wysiwyg.plugins', "submit line separator embed text
167 valign list indent history format symbol link image table macro import#if($full && $request.sync) sync#end")))
Marius Dumitru Florea 9.1 168 {{/code}}
169
Marius Dumitru Florea 21.8 170 Add the ##color## plugin:
Marius Dumitru Florea 9.1 171
172 {{code}}
Marius Dumitru Florea 21.8 173 #set($ok = $parameters.put('plugins', $xwiki.getXWikiPreference('wysiwyg.plugins', "submit line separator embed text color
174 valign list indent history format symbol link image table macro import#if($full && $request.sync) sync#end")))
Marius Dumitru Florea 9.1 175 {{/code}}
176
177 The position of the plugin name in the list is not important. What matters is that it appears in the list so the WYSIWYG editor can load it. You can find what plugins are available in [[Plugins and Features>>#HPluginsandFeatures]] section of this page.
178
Marius Dumitru Florea 21.8 179 Next you have to add ##backcolor## feature to the toolbar. Change the following line:
Marius Dumitru Florea 9.1 180
181 {{code}}
Marius Dumitru Florea 21.8 182 #set($ok = $parameters.put('toolbar', $xwiki.getXWikiPreference('wysiwyg.toolbar', 'bold italic underline strikethrough |
183 subscript superscript | unorderedlist orderedlist | outdent indent | undo redo | format | hr symbol | paste')))
Marius Dumitru Florea 9.1 184 {{/code}}
185
186 to
187
188 {{code}}
Marius Dumitru Florea 21.8 189 #set($ok = $parameters.put('toolbar', $xwiki.getXWikiPreference('wysiwyg.toolbar', 'bold italic underline strikethrough |
190 subscript superscript | unorderedlist orderedlist | outdent indent | undo redo | format | hr symbol | paste | backcolor')))
Marius Dumitru Florea 9.1 191 {{/code}}
192
193 You can place the Background Color button anywhere on the toolbar. Just make sure you leave a space before and after, unless its the first or the last feature on the toolbar.
194
Marius Dumitru Florea 11.1 195 That's it. You have to restart your server because macros.vm is cached by default at application startup. Reload the edited page and you should see the Background Color button appear on the toolbar of your WYSIWYG editor.
Marius Dumitru Florea 13.1 196
197 === Add an 'Insert HTML macro' button on the tool bar ===
198
199 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:
200
Marius Dumitru Florea 21.9 201 1. Add ##macro:html## (or ##macro:yourCoolMacro## if you like ##yourCoolMacro## more) to the tool bar configuration. For XWiki Enterprise 2.x you can follow the previous example. For XWiki Enterprise 3.x please use the administration section.
Marius Dumitru Florea 13.1 202 1. Set a custom icon for the tool bar button by adding:
203
204 {{code language=none}}
205 .macro-html {
206 background-image:url("/xwiki/resources/icons/silk/html.gif") !important;
207 }
208 {{/code}}
209
210 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 adds 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