Show last authors
1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
4
5 {{warning}}
6 The GWT WYSIWYG editor is no longer available starting with XWiki 9.7. It has been replaced by [[CKEditor>>extensions:Extension.CKEditor Integration.WebHome]].
7 {{/warning}}
8
9 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.
10
11 = Quick Reference =
12
13 == Configuration Parameters ==
14
15 (% class="oddEven" style="clear:right" %)
16 |=(% width="15%" %)Parameter Name|=(% width="50%" %)Description|=Default Value
17 |**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##
18 |**cleanPaste**|Since 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##
19 |**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,
20 #FF0000,#FF9900,#FFFF00,#00FF00,#00FFFF,#0000FF,#9900FF,#FF00FF,
21 #F4CCCC,#FCE5CD,#FFF2CC,#D9EAD3,#D0E0E3,#CFE2F3,#D9D2E9,#EAD1DC,
22 #EA9999,#F9CB9C,#FFE599,#B6D7A8,#A2C4C9,#9FC5E8,#B4A7D6,#D5A6BD,
23 #E06666,#F6B26B,#FFD966,#93C47D,#76A5AF,#6FA8DC,#8E7CC3,#C27BA0,
24 #CC0000,#E69138,#F1C232,#6AA84F,#45818E,#3D85C6,#674EA7,#A64D79,
25 #990000,#B45F06,#BF9000,#38761D,#134F5C,#0B5394,#351C75,#741B47,
26 #660000,#783F04,#7F6000,#274E13,#0C343D,#073763,#20124D,#4C1130##
27 |**colorsPerRow**|The maximum number of colors the color picker should display on a row|##8##
28 |**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##
29 |**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##
30 |**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##
31 |**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##
32 |**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##
33 |**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##
34 |**hookId**|The id of the HTML element replaced by the editor. Usually the hook element is a plain text area.|//None//
35 |**inputURL**|The URL of the edited document. Make sure the URL obeys the same origin policy.|##about:blank##
36 |**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//
37 |**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//
38 |**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//
39 |**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//
40 |**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##
41 |**rootUI**|A space-separated list of plugins that extend the editor UI. Make sure the specified plugins are loaded; see the ##plugins## parameter.|##submit##
42 |**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//
43 |**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.|##[]##
44 |**syncPage**|The full name of the page edited in real-time.|//None//
45 |**syncReset**|Set to ##1## to reset the synchronization during a real-time editing.|##0##
46 |**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##
47 |**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##
48 |**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//
49
50 == Plugins and Features ==
51
52 The //Plugin Name//, //Toolbar Features// and //Menu// columns match the ##plugins##, ##toolbar## and ##menu## configuration parameters from the previous section, respectively.
53
54 (% class="oddEven" %)
55 |=Plugin Name|=Description|=Toolbar Features|=Menu
56 |**color**|Controls the colors used inside the rich text area|(((
57 * **forecolor**: text color
58 * **backcolor**: highlight color
59 )))|\\
60 |**font**|Controls the font used.|(((
61 * **fontname**: change the font name
62 * **fontsize**: change the font size
63 )))|\\
64 |**format**|Applies or removes predefined text styles.|(((
65 * **format**: format the text as heading or paragraph
66 * **removeformat**: remove all in-line text formatting
67 )))|\\
68 |**history**|Controls the editing history.|(((
69 * **undo**: go one step back in the editing history
70 * **redo**: go one step forward in the editing history
71 )))|\\
72 |**image**|Adds support for inserting and editing images||(((
73 * **image**: top menu entry
74 * **imageInsertAttached**: insert an image that is attached to a wiki page
75 * **imageInsertURL**: insert an external image, specified by its URL
76 * **imageEdit**: edit selected image
77 * **imageRemove**: remove selected image
78 )))
79 |**import**|Adds support for importing external content|(((
80 * **import:officefile**: import office documents
81 * **paste**: paste rich text from the clipboard
82 )))|(((
83 * **import**: top menu entry
84 * **importOffice**: import office documents
85 )))
86 |**indent**|Allows you to increase or decrease the indentation of list items.|(((
87 * **outdent**: decrease indentation
88 * **indent**: increase indentation
89 )))|\\
90 |**justify**|Controls the text alignment.|(((
91 * **justifyleft**: align text left
92 * **justifycenter**: center text
93 * **justifyright**: align text right
94 * **justifyfull**: justify text
95 )))|\\
96 |**line**|Controls the behavior of the Enter key inside the rich text area.||\\
97 |**link**|Add support for creating and editing different kind of links||(((
98 * **link**: top menu entry
99 * **linkEdit**: edit the selected link
100 * **linkRemove**: remove the selected link
101 * **linkWikiPage**: create a link to a wiki page
102 * **linkAttachment**: create a link to an attached file
103 * **linkWebPage**: create a link to a web page, specified by its URL
104 * **linkEmail**: create a link to an email address
105 )))
106 |**list**|Adds support for creating lists|(((
107 * **unorderedlist**: creates bulleted lists
108 * **orderedlist**: numbered lists
109 )))|\\
110 |**macro**|Adds support for inserting and editing macros|(((
111 * **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
112 )))|(((
113 * **macro**: top menu entry
114 * **macroInsert**: insert a macro
115 * **macroEdit**: edit the selected macro
116 * **macroRefresh**: re-render all the macros
117 * **macroCollapse**: collapse the selected macros, or all the macros if none is selected
118 * **macroExpand**: expand the selected macros, or all the macros if none is selected
119 )))
120 |**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.||\\
121 |**separator**|Offers different kind of content and toolbar separators|(((
122 * **hr**: inserts a horizontal ruler
123 * **|**: separates toolbar features in groups
124 * **/**: breaks the toolbar in multiple lines
125 )))|(((
126 * **|**: horizontal menu item separator
127 )))
128 |**style**|Enhances the editor with the ability to apply predefined styles to the current text selection.|(((
129 * **stylename**: installs a list box on the tool bar with the available styles
130 )))|\\
131 |**submit**|Ensures that the content of the editor is submitted and also cached by the browser.||\\
132 |**symbol**|Allows you to insert a special symbol.|(((
133 * **symbol**
134 )))|\\
135 |**table**|Adds support for inserting and editing tables.||(((
136 * **table**: top menu entry
137 * **inserttable**: insert a table
138 * **insertcolbefore**: insert a column before the current one
139 * **insertcolafter**: insert a column after the current one
140 * **deletecol**: delete the current column
141 * **insertrowbefore**: insert a row before the current one
142 * **insertrowafter**: insert a row after the current one
143 * **deleterow**: delete current row
144 * **deletetable**: delete current table
145 )))
146 |**text**|Offers standard text formatting.|(((
147 * **bold**: formats text as bold
148 * **italic**: formats text as italic
149 * **underline**: formats text as underlined
150 * **strikethrough**: formats text as stroke through
151 * **teletype**: formats text as monospace
152 )))|\\
153 |**valign**|Allows you to write simple formulas.|(((
154 * **subscript**: formats the text as subscript
155 * **superscript**: formats the text as superscript
156 )))|
157
158 = Configuration =
159
160 == Administration Section ==
161
162 Starting with XWiki 3.0 the recommended way to configure the WYSIWYG content editor is through its global administration section.
163
164 == Velocity Templates ==
165
166 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>>#HConfigurationParameters]] 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.
167
168 == Custom Skin ==
169
170 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.
171
172 = Example =
173
174 == Add an 'Insert HTML macro' button on the tool bar ==
175
176 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:
177
178 1. Add ##macro:html## (or ##macro:yourCoolMacro## if you like ##yourCoolMacro## more) to the tool bar configuration (use the administration section)
179 1. Set a custom icon for the tool bar button by adding:
180
181 {{code language="none"}}
182 .macro-html {
183 background-image:url("/xwiki/resources/icons/silk/html.gif") !important;
184 }
185 {{/code}}
186
187 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