Show last authors
1 {{toc start="2"/}}
2
3 == Configure the Editor ==
4
5 XWiki integrates CKEditor. However XWiki doesn't offer by default all the options you'll find in CKEditor by default. The reason is that we want to offer a simple editor suited for a wiki and there are some features that are less useful in a wiki. In addition we'd like users to be able to focus on writing content and less about style. However you can tune the configuration if you wish to enable those options.
6
7 Starting with version 1.9 the recommended way to configure the CKEditor is through the [[dedicated "WYSIWYG Editor" section>>extensions:Extension.CKEditor Integration||anchor="HAdministrationSection"]] in the [[Wiki Administration>>extensions:Extension.Administration Application]].
8
9 If you want to configure the CKEditor globally for all the wikis in your farm then you have to copy the file ##META-INF/resources/webjars/application-ckeditor-webjar/<version>/**config.js**## from ##WEB-INF/lib/application-ckeditor-webjar-<version>.jar## to ##WEB-INF/classes##, preserving its path, and modify it. Don't forget that the configuration properties set at wiki level overwrite the global settings.
10
11 If you have an **older version** of the CKEditor Integration extension installed (<1.9) and you cannot upgrade, you can still configure the editor. You have the following options:
12
13 1. You can edit the ##CKEditor.EditSheet## page using the Object editor, expand the first ##JavaScriptExtension## object ("CKEditor Loader") and look for the ##ckeditor.replace## line. You'll notice there the configuration options.
14 1. On XWiki 8.1M1+ you can create a [[JavaScript extension>>platform:DevGuide.SkinExtensionsTutorial]] with the following code:(((
15 {{code language="js"}}
16 require(['deferred!ckeditor'], function(ckeditorPromise) {
17 ckeditorPromise.done(function(ckeditor) {
18 ckeditor.on('instanceCreated', function(event) {
19 // The editor instance was created but it not yet initialized. Unfortunately the configuration object passed when
20 // the instance was created has not been merged with the global configuration yet.
21 event.editor.once('configLoaded', function(event) {
22 // The editor configuration has been loaded (the instance configuration has been merged with the global
23 // configuration) but the editor has not been fully initialized yet so we can modify the configuration.
24 ckeditor.tools.extend(event.editor.config, {
25 height: 200,
26 ...
27 }, true);
28 });
29 });
30 });
31 });
32 {{/code}}
33
34 Don't forget to set "Use this extension" to "On this wiki".
35 )))
36
37 == Configuration Parameters ==
38
39 Check out the CKEditor documentation for [[the full list of **generic** configuration parameters>>http://docs.ckeditor.com/#!/api/CKEDITOR.config]]. Besides these, there are also some configuration parameters that are **specific to XWiki**. You can set any configuration parameter (either generic or XWiki-specific) using the Advanced configuration text area from the CKEditor administration section. The XWiki-specific parameters are set like this:
40
41 {{code language="js"}}
42 // 'xwiki-link' is the name of a CKEditor plugin.
43 config['xwiki-link'] = config['xwiki-link'] || {};
44 // 'autoGenerateLabels' is the configuration parameter for that plugin.
45 config['xwiki-link'].autoGenerateLabels = true;
46 {{/code}}
47
48 |=Plugin|=Parameter|=Description|=Since
49 ||applyPasteFilterAfterPasteFromWord|Whether to apply the paste filter after the Word filter. Default value is ##true##|1.19
50 |xwiki-image|resourceTypes|The resource types you can select from on the Image dialog. See [[ResourceType.java>>https://github.com/xwiki/xwiki-rendering/blob/master/xwiki-rendering-api/src/main/java/org/xwiki/rendering/listener/reference/ResourceType.java]] for the list of supported resource types. The default value is: ##['attach', 'icon', 'url']##|\\
51 |xwiki-link|resourceTypes|The resource types you can select from on the Link dialog. See [[ResourceType.java>>https://github.com/xwiki/xwiki-rendering/blob/master/xwiki-rendering-api/src/main/java/org/xwiki/rendering/listener/reference/ResourceType.java]] for the list of supported resource types. The default value is: ##['doc', 'attach', 'url', 'mailto']##|\\
52 ||autoGenerateLabels|Whether to create links with [[auto-generated labels>>platform:AdminGuide.Configuration||anchor="HLinkLabelGeneration"]] or links with explicit labels. Auto-generated labels are updated automatically when the target page is moved or renamed but they increase a bit the rendering time and the output may be technical, depending on how you configure the link label generation. The default value is ##false##|1.14
53 ||labelGenerator|The service used to obtain the generated link labels, in case ##autoGenerateLabels## is ##true##.|1.14
54 |xwiki-macro|insertButtons|Used to put dedicated insert macro buttons on the tool bar. See the following sections for more information. The default value is ##[]##|1.13
55 |xwiki-resource|dispatcher|The service used to obtain resource URLs.|\\
56 |xwiki-save|saveAndContinueButton|The CSS selector for the Save & Continue button. The default value is: ##'input[name=action_saveandcontinue]'##|\\
57 ||leaveConfirmation|Whether to ask for confirmation when leaving the editor with unsaved changes. The default value is ##true##|\\
58 |xwiki-source|htmlConverter|The service used to convert between HTML and wiki syntax. This is used when switching between WYSIWYG and Source modes.|
59
60 == Put Dedicated Insert Macro Buttons on the Tool Bar ==
61
62 Starting with version 1.13 you can speed up macro insertion by placing dedicated insert buttons on the tool bar. The following configuration adds two more buttons to the tool bar: the first inserts a Page Tree and the second inserts an HTML snippet.
63
64 {{code language="js"}}
65 config['xwiki-macro'] = config['xwiki-macro'] || {};
66 config['xwiki-macro'].insertButtons = [
67 'documentTree',
68 {
69 commandId: 'xwiki-macro-html-dirty',
70 macroCall: {
71 name: 'html',
72 parameters: {
73 clean: false,
74 wiki: true
75 }
76 }
77 }
78 ];
79 {{/code}}
80
81 As you can see, there are two ways in which you can specify the buttons:
82
83 * a simple way: you just specify the macro name
84 * an advanced way: you can specify also the macro parameter values and the command name (which is needed if you add move buttons for the same macro)
85
86 Then, you can control the button icon by using some CSS in a [[custom skin>>platform:AdminGuide.Skins]] or by using a [[SSX Skin Extension>>platform:DevGuide.SkinExtensionsTutorial]]. Here's an example:
87
88 {{code language="css"}}
89 a.cke_button.cke_button__xwiki-macro-documenttree > span.cke_button_icon.cke_button__xwiki-macro-documenttree_icon {
90 font-family: 'Glyphicons Halflings';
91 position: relative;
92 top: 1px;
93 }
94 .cke_button_icon.cke_button__xwiki-macro-documenttree_icon::before {
95 content: "\e199";
96 display: inline-block;
97 text-align: center;
98 width: 16px;
99 }
100 {{/code}}
101
102 In this example we've used a font icon, but you can use whatever icon you want through CSS.
103
104 == Use additional CKEditor plugins ==
105
106 For the CKEditor integration with XWiki we have selected a list of CKEditor plugins that we bundle by default. They provide the basic WYSIWYG editing features like text formatting, inserting links, images, tables, etc. The integration with these default plugins is supported by the XWiki Development Team, which means you can report issues and we'll look into them. There are many more [[CKEditor plugins>>http://ckeditor.com/addons/plugins/all]] available that you can integrate separately in XWiki, but you should be aware that they are not supported by the XWiki Development Team. The most common issue you can have with these plugins is that they may generate HTML that cannot be converted to the XWiki syntax.
107
108 You need to do two things if you want to integrate additional CKEditor plugins:
109
110 1. Let CKEditor know where the plugin is located:(((
111 {{code language="js"}}
112 CKEDITOR.plugins.addExternal('plugin name', 'plugin URL or path');
113 {{/code}}
114
115 You can put this:
116
117 * in the "Advanced Configuration" text area from the CKEditor administration section, if you can hard-code the plugin URL/path or compute it on the client-side using only JavaScript. E.g.: assuming the CKEditor plugin is defined in the ##Sandbox.Foo## JavaScript [[skin extension>>platform:DevGuide.SkinExtensionsTutorial]] like this(((
118 {{code language="js"}}
119 CKEDITOR.plugins.add('foo', {
120 init: function(editor) {
121 ...
122 }
123 });
124 {{/code}}
125
126 then you can specify its location with this:
127
128 {{code language="js"}}
129 CKEDITOR.plugins.addExternal('foo', new XWiki.Document('Foo', 'Sandbox').getURL('jsx'));
130 {{/code}}
131 )))
132 * or in a JavaScript [[skin extension>>platform:DevGuide.SkinExtensionsTutorial]]. E.g.: assuming the CKEditor plugin is defined by ##resources/ckeditorPlugins/foo.js## within the XWiki WAR then you can specify its location with(((
133 {{code language="js"}}
134 require(['deferred!ckeditor'], function(ckeditorPromise) {
135 ckeditorPromise.done(function(ckeditor) {
136 ckeditor.plugins.addExternal('foo', "$xwiki.getSkinFile('ckeditorPlugins/foo.js')");
137 });
138 });
139 {{/code}}
140
141 Make sure the JSX is configured to be loaded automatically on the entire wiki.
142 )))
143 )))
144 1. Enable the plugin in the CKEditor configuration:(((
145 {{code language="js"}}
146 config.extraPlugins = 'foo,bar';
147 {{/code}}
148 )))
149
150 == Execute JavaScript code inside the editing area (XWiki 10.10+) ==
151
152 The sheet (##CKEditor.ContentSheet##) used to render the content of the edited page inside the editing area doesn't load, by default, the JavaScript code required by the edited content. This means, for instance, that if the edited content is using a macro that requires some JavaScript code in order to be displayed properly then that JavaScript code is not executed and thus the macro output doesn't look good inside the editing area. There are multiple reasons for this behavior:
153
154 * loading and executing the JavaScript code slows down the editor
155 * the JavaScript code could modify the edited content (outside of the protected macro output) and these changes would be saved
156 * the JavaScript code could throw exceptions or interfere with the CKEditor code thus breaking the editor which may lead to content loss
157 * executing the JavaScript code opens the door to XSS attacks
158
159 One way to fix the macro output, while still being safe with respect to JavaScript, is to modify the macro code so that it behaves differently when executed in WYSIWYG edit mode. The macro could for instance generate a placeholder (e.g. an image) in WYSIWYG edit mode, that doesn't need JavaScript.
160
161 If this is not enough and you really want to execute the JavaScript code inside the editing area then you need to do this:
162
163 1. Enable the loading of the JavaScript Skin Extensions from the CKEditor administration section
164 1. Modify the macro code to mark the scripts that are safe to be loaded inside the editing area:(((
165 {{code language="none"}}
166 #set ($discard = $xwiki.jsx.use('Path.To.MyMacro', {'wysiwyg': true}))
167 {{/code}}
168 )))
169 1. Use the macro from the CKEditor and look for:(((
170 * JavaScript exceptions in the JavaScript console
171 * Content that should not be saved
172
173 If you get this then you need to fix the JavaScript code.
174 )))
175
176 == Replace the Default Editor (before XWiki 8.2) ==
177
178 {{info}}
179 Starting with [[XWiki 8.2>>xwiki:ReleaseNotes.ReleaseNotesXWiki82||anchor="HCKEditorBecomestheDefaultWYSIWYGEditor"]] the CKEditor **is** the default WYSIWYG editor so this section applies only to the older versions of XWiki.
180 {{/info}}
181
182 === When Editing a Page ===
183
184 By default this extension adds a new "CKEditor" entry to the [[Edit menu>>platform:Features.PageEditing||anchor="HAdvancedMode"]]. This means that the CKEditor won't be available for your simple users because only the advanced users have the Edit menu. The simple users have only the Edit button/link/icon. In order to open the CKEditor by default (i.e. replace the default editor) you can [[navigate>>xwiki:FAQ.How can I navigate to a given page]] to the ##CKEditor.EditMenuEntry## page and from the [[Objects editing mode>>platform:Features.PageEditing||anchor="HObjectseditingmode"]] replace the Code property of the existing [[##JavaScriptExtension##>>platform:DevGuide.SkinExtensionsTutorial]] object with:
185
186 {{code language="js"}}
187 require(['jquery'], function($) {
188 $('#tmEdit > a, a#tmEditDefault').attr('href', function(index, url) {
189 return url + (url.indexOf('?') < 0 ? '?' : '&') + 'editor=inline&sheet=CKEditor.EditSheet';
190 });
191 $('a#tmEditWysiwyg').attr('href', function(index, url) {
192 return url.replace('editor=wysiwyg', 'editor=inline&sheet=CKEditor.EditSheet');
193 });
194 });
195 {{/code}}
196
197 As a result the URL of the default edit link will point to the CKEditor. This has no effect though if you open the edit page directly using the URL (browser address bar). If you want the default edit URL (e.g. ##/xwiki/bin/edit/A/B/C##) to open the CKEditor then you'll have to modify the ##edit.vm## Velocity template (e.g. in a custom skin).
198
199 === When Editing a Section of a Page ===
200
201 In order to be able to edit page sections using the CKEditor you need to edit the ##CKEditor.EditMenuEntry## page as indicated in the previous section and append the following JavaScript code to the end of the Code property:
202
203 {{code language="js"}}
204 require(['jquery'], function($) {
205 var modifySectionEditLinks = function() {
206 // Use the CKEditor for editing page sections.
207 $('.edit_section > a').attr('href', function(index, oldHref) {
208 return oldHref + '&editor=inline&sheet=CKEditor.EditSheet';
209 });
210 };
211 if (window.XWiki && XWiki.domIsLoaded) {
212 modifySectionEditLinks();
213 } else {
214 // XWiki 6.4+
215 require(['xwiki-events-bridge'], function() {
216 $(document).on('xwiki:dom:loaded', modifySectionEditLinks);
217 });
218 }
219 });
220 {{/code}}
221
222 If you're using the CKEditor Integration version 1.2 or older you also need to modify the ##CKEditor.EditSheet## page as indicated in [[this commit>>https://github.com/xwiki-contrib/application-ckeditor/commit/31c170a620d5a3b0e8c3fbde2a390d9aef7a7ffd]].
223
224 === When Creating a Blank Page ===
225
226 When you [[create a page>>platform:Features.DocumentLifecycle||anchor="HCreate"]] using the "Blank page" (or "Empty wiki page") type (template) you are redirected to the edit mode for that page. In order to use the CKEditor in this case, instead of the default WYSIWYG editor, you need to [[import>>platform:Features.Imports||anchor="HImportingXWikipages"]] the attach:application-ckeditor-blank-page.xar file.

Get Connected