Wiki source code of Customization
Last modified by Vincent Massol on 2024/03/27 13:33
Hide last authors
| author | version | line-number | content |
|---|---|---|---|
 |
1.2 | 1 | {{toc start="2"/}} |
| 2 | |||
| |
14.1 | 3 | == Configuration Levels == |
| 4 | |||
| 5 | The CKEditor integration in XWiki is configured at multiple leves: | ||
| 6 | |||
| |
16.1 | 7 | 1. (% class="badge" %)app(%%) ##config.js## (from ##application-ckeditor-webjar##): **default** global (static) configuration, no Velocity evaluation |
| 8 | 1. (% class="badge" %)app(%%) ##CKEditor.ConfigSheet## (from ##application-ckeditor-ui##): **default** global (dynamic) configuration, with Velocity evaluation | ||
| 9 | 1. (% class="badge" %)admin(%%) ##CKEditor.Config##: global (static) configuration, no Velocity evaluation <- this page is created when administrators use the dedicated CKEditor administration section | ||
| 10 | 1. (% class="badge" %)app(%%) ##CKEditor.EditSheet## (from ##application-ckeditor-ui##): **default** instance (dynamic) configuration | ||
| 11 | 1. (% class="badge" %)dev(%%) instance configuration passed when creating the editor <- provided by developers that use the CKEditor API | ||
| 12 | 1. (% class="badge" %)dev(%%) custom instance configuration done by listening to editor events (from code that doesn't control the editor instance creation) <- provided by developers that use the CKEditor API; see below for examples | ||
| |
14.1 | 13 | |
| |
16.1 | 14 | Each level in this list can overwrite the configuration from previous levels (it's actually a merge). The levels marked with (% class="badge" %)app(%%) provide default configuration that shouldn't be modified directly by users. The users can and should configure the editor: |
| |
14.1 | 15 | |
| |
16.1 | 16 | * either through the dedicated CKEditor administration section (that generates the ##CKEditor.Config## page) |
| 17 | * or using the CKEditor API (when creating the editor or by listening to editor events) | ||
| 18 | |||
| |
1.1 | 19 | == Configure the Editor == |
| 20 | |||
| 21 | 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. | ||
| 22 | |||
| |
2.1 | 23 | 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]]. |
| |
1.1 | 24 | |
| 25 | 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. | ||
| 26 | |||
| 27 | 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: | ||
| 28 | |||
| 29 | 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. | ||
 |
27.1 | 30 | 1. On XWiki 8.1M1+ you can create a [[JavaScript extension>>xwiki:Documentation.DevGuide.Tutorials.SkinExtensionsTutorial.WebHome]] with the following code:((( |
| |
1.1 | 31 | {{code language="js"}} |
| 32 | require(['deferred!ckeditor'], function(ckeditorPromise) { | ||
| 33 | ckeditorPromise.done(function(ckeditor) { | ||
| 34 | ckeditor.on('instanceCreated', function(event) { | ||
| 35 | // The editor instance was created but it not yet initialized. Unfortunately the configuration object passed when | ||
| 36 | // the instance was created has not been merged with the global configuration yet. | ||
| 37 | event.editor.once('configLoaded', function(event) { | ||
| 38 | // The editor configuration has been loaded (the instance configuration has been merged with the global | ||
| 39 | // configuration) but the editor has not been fully initialized yet so we can modify the configuration. | ||
| 40 | ckeditor.tools.extend(event.editor.config, { | ||
| 41 | height: 200, | ||
| 42 | ... | ||
| 43 | }, true); | ||
| 44 | }); | ||
| 45 | }); | ||
| 46 | }); | ||
| 47 | }); | ||
| 48 | {{/code}} | ||
| 49 | |||
| 50 | Don't forget to set "Use this extension" to "On this wiki". | ||
| 51 | ))) | ||
| 52 | |||
| 53 | == Configuration Parameters == | ||
| 54 | |||
| 55 | 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: | ||
| 56 | |||
| 57 | {{code language="js"}} | ||
| 58 | // 'xwiki-link' is the name of a CKEditor plugin. | ||
| 59 | config['xwiki-link'] = config['xwiki-link'] || {}; | ||
| 60 | // 'autoGenerateLabels' is the configuration parameter for that plugin. | ||
| 61 | config['xwiki-link'].autoGenerateLabels = true; | ||
| 62 | {{/code}} | ||
| 63 | |||
| 64 | |=Plugin|=Parameter|=Description|=Since | ||
| |
4.1 | 65 | ||applyPasteFilterAfterPasteFromWord|Whether to apply the paste filter after the Word filter. Default value is ##true##|1.19 |
| |
1.1 | 66 | |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']##|\\ |
| |
21.1 | 67 | |(% rowspan="3" %)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']##|\\ |
| |
27.1 | 68 | |autoGenerateLabels|Whether to create links with [[auto-generated labels>>xwiki:Documentation.AdminGuide.Configuration.WebHome||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 |
| |
21.1 | 69 | |labelGenerator|The service used to obtain the generated link labels, in case ##autoGenerateLabels## is ##true##.|1.14 |
| |
1.1 | 70 | |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 |
| 71 | |xwiki-resource|dispatcher|The service used to obtain resource URLs.|\\ | ||
| 72 | |xwiki-save|saveAndContinueButton|The CSS selector for the Save & Continue button. The default value is: ##'input[name=action_saveandcontinue]'##|\\ | ||
| 73 | ||leaveConfirmation|Whether to ask for confirmation when leaving the editor with unsaved changes. The default value is ##true##|\\ | ||
| 74 | |xwiki-source|htmlConverter|The service used to convert between HTML and wiki syntax. This is used when switching between WYSIWYG and Source modes.| | ||
| |
23.1 | 75 | |(% rowspan="3" %)xwiki-slash|extraQuickActionGroups|Define additional quick action groups; the value is an array of ##{id, name, order}## objects; a lower ##order## number will show the group higher in the quick actions drop down; note that groups are shown only when they contain at least one action; default value is ##[]## (empty array); here's an example:((( |
| |
21.1 | 76 | {{code language="js"}} |
| |
25.1 | 77 | config.extraQuickActionGroups = [{ |
| |
21.1 | 78 | id: 'diagrams', |
| 79 | name: 'Diagrams', | ||
| 80 | order: 300 | ||
| 81 | }]; | ||
| 82 | {{/code}} | ||
| 83 | )))|15.5RC1 | ||
| 84 | |extraQuickActions|Define additional quick actions; the value is an array of ##{group, id, name, description, iconClass, iconURL, shortcut, command, outputHTML}## objects; the quick action icon is specified either using a CSS class (e.g. when a font icon is used) or an URL; the actual action performed is defined either by the HTML that is inserted in the edited content or by the editor command that is executed; default value is ##[]## (empty array); here's an example:((( | ||
| 85 | {{code language="js"}} | ||
| |
25.1 | 86 | config.extraQuickActions = [{ |
| |
21.1 | 87 | group: 'content', |
| 88 | id: 'a', | ||
| 89 | name: 'Link', | ||
| 90 | iconClass: 'fa fa-link', | ||
| 91 | shortcut: '[', | ||
| 92 | description: 'Insert a link to a wiki page or attachment.', | ||
| 93 | outputHTML: '[' | ||
| 94 | }, { | ||
| 95 | group: 'formatting', | ||
| 96 | id: 'macro-code-js', | ||
| 97 | name: 'JavaScript Snippet', | ||
| 98 | iconClass: 'fa fa-code', | ||
| 99 | description: 'Insert a snippet of JavaScript code', | ||
| 100 | command: { | ||
| 101 | name: 'xwiki-macro', | ||
| 102 | data: { | ||
| 103 | name: 'code', | ||
| 104 | parameters: { | ||
| 105 | language: 'js' | ||
| 106 | }, | ||
| 107 | } | ||
| 108 | } | ||
| 109 | }]; | ||
| |
22.1 | 110 | {{/code}} |
| |
21.1 | 111 | )))|15.5RC1 |
| 112 | |removeQuickActions|Specifies which quick actions to remove; the value is an array of quick action identifiers (strings); default value is ##[]## (empty array); here's an example:((( | ||
| 113 | {{code language="js"}} | ||
| |
26.1 | 114 | config.removeQuickActions = ['blockquote', 'macro-toc']; |
| |
22.1 | 115 | {{/code}} |
| |
21.1 | 116 | )))|15.5RC1 |
| |
24.1 | 117 | |(% rowspan="2" %)xwiki-focusedplaceholder|placeholder|Associates a placeholder text to an HTML tag name; here's an example:((( |
| 118 | {{code language="js"}} | ||
| 119 | config["xwiki-focusedplaceholder"].placeholder.h1 = "Your Heading 1 placeholder"; | ||
| 120 | {{/code}} | ||
| 121 | )))|15.5RC1 | ||
| 122 | |ignoreIfEmpty|The list of HTML tag names that should be ignored if empty, i.e. the list of DOM elements that won't get a placeholder text even if they are empty; default value is ##["#text", "a", "abbr", "b", "bdi", "bdo", "br", "cite", "data", "dfn", "em", "i", "mark", "s", "small", "span", "strong", "time", "u", "var", "wbr", "del", "ins"]##|15.5RC1 | ||
| |
1.1 | 123 | |
| 124 | == Put Dedicated Insert Macro Buttons on the Tool Bar == | ||
| 125 | |||
| |
10.1 | 126 | {{version since="1.13"}} |
| 127 | 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. Both buttons will open the Edit Macro dialog to allow the user to fill the macro parameter values (some values will be pre-filled based on the macro call configuration). | ||
| 128 | {{/version}} | ||
| |
1.1 | 129 | |
| |
10.1 | 130 | {{version since="1.57"}} |
| 131 | If you want to insert the macro directly, without going through the Edit Macro dialog, you can do so, by setting ##insertDirectly: true##. Check the third button we insert on the toolbar in the example below. | ||
| 132 | {{/version}} | ||
| 133 | |||
| |
1.1 | 134 | {{code language="js"}} |
| 135 | config['xwiki-macro'] = config['xwiki-macro'] || {}; | ||
| 136 | config['xwiki-macro'].insertButtons = [ | ||
| |
11.1 | 137 | // First button, specifies only the macro name. |
| |
1.1 | 138 | 'documentTree', |
| |
11.1 | 139 | // Second button, specifies also macro parameter values. |
| |
1.1 | 140 | { |
| 141 | commandId: 'xwiki-macro-html-dirty', | ||
| 142 | macroCall: { | ||
| 143 | name: 'html', | ||
| 144 | parameters: { | ||
| 145 | clean: false, | ||
| 146 | wiki: true | ||
| 147 | } | ||
| 148 | } | ||
| |
10.1 | 149 | }, |
| |
11.1 | 150 | // Third button, specifies also the macro content, and the macro is inserted directly. |
| |
10.1 | 151 | { |
| 152 | insertDirectly: true, | ||
| 153 | macroCall: { | ||
| 154 | name: 'info', | ||
| 155 | content: 'type message here' | ||
| 156 | } | ||
| |
1.1 | 157 | } |
| 158 | ]; | ||
| 159 | {{/code}} | ||
| 160 | |||
| 161 | As you can see, there are two ways in which you can specify the buttons: | ||
| 162 | |||
| 163 | * a simple way: you just specify the macro name | ||
| |
9.1 | 164 | * an advanced way: you can specify also the macro parameter values and the command name (which is needed if you add more buttons for the same macro) |
| |
12.1 | 165 | ** you can control whether the macro is inserted inline or as a block element from the macro call configuration:((( |
| 166 | {{code language="none"}} | ||
| 167 | macroCall: { | ||
| 168 | name: 'mention', | ||
| 169 | inline: false|true|'enforce', | ||
| 170 | ... | ||
| 171 | } | ||
| 172 | {{/code}} | ||
| |
13.1 | 173 | |
| |
12.1 | 174 | Note that due to the way the XWiki rendering works, passing ##inline:true## doesn't lead to an inline macro if the macro is alone in a paragrah. {{version since="1.58"}}If you want the macro to be inserted inline even in this case then you need to pass ##inline:'enforce'##. This will also place the caret after the macro so that the user can continue editing.{{/version}} |
| 175 | ))) | ||
| |
1.1 | 176 | |
| |
27.1 | 177 | Then, you can control the button icon by using some CSS in a [[custom skin>>xwiki:Documentation.AdminGuide.Skins]] or by using a [[SSX Skin Extension>>xwiki:Documentation.DevGuide.Tutorials.SkinExtensionsTutorial.WebHome]]. Here's an example: |
| |
1.1 | 178 | |
| 179 | {{code language="css"}} | ||
| 180 | a.cke_button.cke_button__xwiki-macro-documenttree > span.cke_button_icon.cke_button__xwiki-macro-documenttree_icon { | ||
| 181 | font-family: 'Glyphicons Halflings'; | ||
| 182 | position: relative; | ||
| 183 | top: 1px; | ||
| 184 | } | ||
| 185 | .cke_button_icon.cke_button__xwiki-macro-documenttree_icon::before { | ||
| 186 | content: "\e199"; | ||
| 187 | display: inline-block; | ||
| 188 | text-align: center; | ||
| 189 | width: 16px; | ||
| 190 | } | ||
| 191 | {{/code}} | ||
| 192 | |||
| 193 | In this example we've used a font icon, but you can use whatever icon you want through CSS. | ||
| 194 | |||
 |
27.2 | 195 | == Customize the well-known macro list == |
| 196 | |||
| 197 | It's possible to customize the content of the macro list from: | ||
| 198 | |||
| 199 | {{image reference="insertMenuCustomize.png"/}} | ||
| 200 | |||
| 201 | The insert button drop-down is controlled by two configuration properties: | ||
| 202 | |||
| 203 | * {{scm path="xwiki-platform-core/xwiki-platform-ckeditor/xwiki-platform-ckeditor-webjar/src/main/webjar/config.js#L240-L304"}}##toolbarMenuItems##{{/scm}}: you first need to define a "toolbar menu item" for the macros you want to expose. Check the examples:((( | ||
| 204 | {{code language="javascript"}} | ||
| 205 | infoBox: { | ||
| 206 | command: 'xwiki-macro-insert', | ||
| 207 | data: { | ||
| 208 | name: 'info', | ||
| 209 | content: 'Type your information message here.', | ||
| 210 | parameters: {...} | ||
| 211 | } | ||
| 212 | }, | ||
| 213 | {{/code}} | ||
| 214 | |||
| 215 | As you can see you can specify both the macro content and parameters (preset the values). For the ##command## you have two options: | ||
| 216 | * ##xwiki-macro-insert##: insert the macro directly | ||
| 217 | * ##xwiki-macro##: open the macro wizard | ||
| 218 | ))) | ||
| 219 | * {{scm path="xwiki-platform-core/xwiki-platform-ckeditor/xwiki-platform-ckeditor-webjar/src/main/webjar/config.js#L215-L239"}}##toolbarMenus##{{/scm}}: you need to modify the "insert" menu. | ||
| 220 | |||
| 221 | Both of these can be modified from the CKEditor administration section, but you need to set the **entire** value, i.e. you need to copy the current value and modify it (you can't just add a new menu item). | ||
| 222 | |||
| |
1.1 | 223 | == Use additional CKEditor plugins == |
| 224 | |||
| 225 | 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. | ||
| 226 | |||
| 227 | You need to do two things if you want to integrate additional CKEditor plugins: | ||
| 228 | |||
| 229 | 1. Let CKEditor know where the plugin is located:((( | ||
| 230 | {{code language="js"}} | ||
| 231 | CKEDITOR.plugins.addExternal('plugin name', 'plugin URL or path'); | ||
| 232 | {{/code}} | ||
| 233 | |||
| 234 | You can put this: | ||
| 235 | |||
| |
27.1 | 236 | * 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>>xwiki:Documentation.DevGuide.Tutorials.SkinExtensionsTutorial.WebHome]] like this((( |
| |
1.1 | 237 | {{code language="js"}} |
| 238 | CKEDITOR.plugins.add('foo', { | ||
| 239 | init: function(editor) { | ||
| 240 | ... | ||
| 241 | } | ||
| 242 | }); | ||
| 243 | {{/code}} | ||
| |
7.1 | 244 | |
| 245 | then you can specify its location with this: | ||
| 246 | |||
| 247 | {{code language="js"}} | ||
| 248 | CKEDITOR.plugins.addExternal('foo', new XWiki.Document('Foo', 'Sandbox').getURL('jsx')); | ||
| 249 | {{/code}} | ||
| |
1.1 | 250 | ))) |
| |
27.1 | 251 | * or in a JavaScript [[skin extension>>xwiki:Documentation.DevGuide.Tutorials.SkinExtensionsTutorial.WebHome]]. E.g.: assuming the CKEditor plugin is defined by ##resources/ckeditorPlugins/foo.js## within the XWiki WAR then you can specify its location with((( |
| |
1.1 | 252 | {{code language="js"}} |
| 253 | require(['deferred!ckeditor'], function(ckeditorPromise) { | ||
| 254 | ckeditorPromise.done(function(ckeditor) { | ||
| 255 | ckeditor.plugins.addExternal('foo', "$xwiki.getSkinFile('ckeditorPlugins/foo.js')"); | ||
| 256 | }); | ||
| 257 | }); | ||
| 258 | {{/code}} | ||
| |
7.1 | 259 | |
| 260 | Make sure the JSX is configured to be loaded automatically on the entire wiki. | ||
| |
1.1 | 261 | ))) |
| 262 | ))) | ||
| 263 | 1. Enable the plugin in the CKEditor configuration:((( | ||
| 264 | {{code language="js"}} | ||
| 265 | config.extraPlugins = 'foo,bar'; | ||
| 266 | {{/code}} | ||
| 267 | ))) | ||
| 268 | |||
| |
17.1 | 269 | == Extend the default style set == |
| 270 | |||
| 271 | The CKEditor provides a Styles drop down on the tool bar that you can use to apply various styles to the selected content. If you want to add custom styles then you have two options: | ||
| 272 | |||
| 273 | * Use the dedicated administration section to **overwrite** completely the style set. Checkout the [[##styleSet##>>https://ckeditor.com/docs/ckeditor4/latest/api/CKEDITOR_config.html#cfg-stylesSet]] configuration option. You'll probably want to copy some of the [[default styles>>https://github.com/xwiki-contrib/application-ckeditor/blob/master/application-ckeditor-webjar/src/main/resources/styles.js]]. | ||
| 274 | * Use a JavaScript extension (e.g. a JSX object loaded on the wiki) to **extend** the default style set:((( | ||
| 275 | {{code language="js"}} | ||
| 276 | // The following code is executed only when CKEditor is loaded on the current page. | ||
| 277 | require(['deferred!ckeditor'], function(ckeditorPromise) { | ||
| 278 | ckeditorPromise.done(function(ckeditor) { | ||
| 279 | // Wait for an editor instance to be created. | ||
| 280 | ckeditor.once('instanceCreated', function(event) { | ||
| 281 | // Wait for the default style set to be loaded. | ||
| 282 | event.editor.once('stylesSet', function(event) { | ||
| 283 | // Modify the default style set. | ||
| 284 | ckeditor.stylesSet.get('html5').push({name: 'Custom', element: 'p', attributes: {'class': 'custom'}}) | ||
| 285 | }); | ||
| 286 | }); | ||
| 287 | }); | ||
| 288 | }); | ||
| 289 | {{/code}} | ||
| 290 | ))) | ||
| 291 | |||
| |
6.1 | 292 | == Execute JavaScript code inside the editing area (XWiki 10.10+) == |
| |
5.1 | 293 | |
| |
6.1 | 294 | 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: |
| |
5.1 | 295 | |
| |
6.1 | 296 | * loading and executing the JavaScript code slows down the editor |
| |
5.1 | 297 | * the JavaScript code could modify the edited content (outside of the protected macro output) and these changes would be saved |
| 298 | * the JavaScript code could throw exceptions or interfere with the CKEditor code thus breaking the editor which may lead to content loss | ||
| 299 | * executing the JavaScript code opens the door to XSS attacks | ||
| 300 | |||
| 301 | 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. | ||
| 302 | |||
| 303 | If this is not enough and you really want to execute the JavaScript code inside the editing area then you need to do this: | ||
| 304 | |||
| 305 | 1. Enable the loading of the JavaScript Skin Extensions from the CKEditor administration section | ||
| 306 | 1. Modify the macro code to mark the scripts that are safe to be loaded inside the editing area:((( | ||
| 307 | {{code language="none"}} | ||
| 308 | #set ($discard = $xwiki.jsx.use('Path.To.MyMacro', {'wysiwyg': true})) | ||
| 309 | {{/code}} | ||
| 310 | ))) | ||
| 311 | 1. Use the macro from the CKEditor and look for:((( | ||
| 312 | * JavaScript exceptions in the JavaScript console | ||
| 313 | * Content that should not be saved | ||
| 314 | |||
| 315 | If you get this then you need to fix the JavaScript code. | ||
| 316 | ))) | ||
| 317 | |||
| |
1.1 | 318 | == Replace the Default Editor (before XWiki 8.2) == |
| 319 | |||
| 320 | {{info}} | ||
| 321 | 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. | ||
| 322 | {{/info}} | ||
| 323 | |||
| 324 | === When Editing a Page === | ||
| 325 | |||
| |
27.1 | 326 | By default this extension adds a new "CKEditor" entry to the [[Edit menu>>xwiki:Documentation.UserGuide.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>>xwiki:Documentation.UserGuide.Features.PageEditing||anchor="HObjectseditingmode"]] replace the Code property of the existing [[##JavaScriptExtension##>>xwiki:Documentation.DevGuide.Tutorials.SkinExtensionsTutorial.WebHome]] object with: |
| |
1.1 | 327 | |
| 328 | {{code language="js"}} | ||
| 329 | require(['jquery'], function($) { | ||
| 330 | $('#tmEdit > a, a#tmEditDefault').attr('href', function(index, url) { | ||
| 331 | return url + (url.indexOf('?') < 0 ? '?' : '&') + 'editor=inline&sheet=CKEditor.EditSheet'; | ||
| 332 | }); | ||
| 333 | $('a#tmEditWysiwyg').attr('href', function(index, url) { | ||
| 334 | return url.replace('editor=wysiwyg', 'editor=inline&sheet=CKEditor.EditSheet'); | ||
| 335 | }); | ||
| 336 | }); | ||
| 337 | {{/code}} | ||
| 338 | |||
| 339 | 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). | ||
| 340 | |||
| 341 | === When Editing a Section of a Page === | ||
| 342 | |||
| 343 | 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: | ||
| 344 | |||
| 345 | {{code language="js"}} | ||
| 346 | require(['jquery'], function($) { | ||
| 347 | var modifySectionEditLinks = function() { | ||
| 348 | // Use the CKEditor for editing page sections. | ||
| 349 | $('.edit_section > a').attr('href', function(index, oldHref) { | ||
| 350 | return oldHref + '&editor=inline&sheet=CKEditor.EditSheet'; | ||
| 351 | }); | ||
| 352 | }; | ||
| 353 | if (window.XWiki && XWiki.domIsLoaded) { | ||
| 354 | modifySectionEditLinks(); | ||
| 355 | } else { | ||
| 356 | // XWiki 6.4+ | ||
| 357 | require(['xwiki-events-bridge'], function() { | ||
| 358 | $(document).on('xwiki:dom:loaded', modifySectionEditLinks); | ||
| 359 | }); | ||
| 360 | } | ||
| 361 | }); | ||
| 362 | {{/code}} | ||
| 363 | |||
| 364 | 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]]. | ||
| 365 | |||
| 366 | === When Creating a Blank Page === | ||
| 367 | |||
| |
27.1 | 368 | When you [[create a page>>xwiki:Documentation.UserGuide.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>>xwiki:Documentation.UserGuide.Features.Imports||anchor="HImportingXWikipages"]] the attach:application-ckeditor-blank-page.xar file. |
| |
18.1 | 369 | |
| 370 | {{version since='15.2RC1,14.10.7'}} | ||
| 371 | == Add parameters to the CKEditor html conversion request == | ||
| 372 | A ##xwiki:ckeditor:convertHTML## event is send before a request to convert some content to HTML is sent by CKEditor. Listeners can add new request parameters by add properties on the data object send with the event. The example below show how to add an example ##parameter## with value ##1##. | ||
| 373 | |||
| 374 | {{code language="javascript"}} | ||
| 375 | $(document).on('xwiki:ckeditor:convertHTML', function(event, data) { | ||
| 376 | data.example = 1; | ||
| 377 | }); | ||
| 378 | {{/code}} | ||
| 379 | {{/version}} | ||
| |
30.1 | 380 | |
| 381 | == Add a new Link Type == | ||
| 382 | |||
| 383 | If you want to add a new link type in the Link dialog, follow these steps: | ||
| 384 | * [[Configure the list of resource types>>Extension.CKEditor Integration||anchor="HConfigurationParameters"]] to appear in the link modal dropdown:((( | ||
| 385 | {{code language="javascript"}} | ||
| 386 | config['xwiki-link'] = config['xwiki-link'] || {}; | ||
| 387 | config['xwiki-link'].resourceTypes = ['doc', 'attach', 'url', 'mailto', 'sip']; | ||
| 388 | {{/code}} | ||
| 389 | ))) | ||
| 390 | * Specify the resource type metadata, which you can do from a JSX:((( | ||
| 391 | {{code language="javascript"}} | ||
| 392 | require(['deferred!resource'], resourcePromise => { | ||
| 393 | resourcePromise.then(resource => { | ||
| 394 | resource.types.sip = { | ||
| 395 | label: 'SIP Phone Number', | ||
| 396 | icon: 'glyphicon glyphicon-phone', | ||
| 397 | placeholder: '+49XXXXXXXX' | ||
| 398 | }; | ||
| 399 | return resource; | ||
| 400 | }); | ||
| 401 | }); | ||
| 402 | {{/code}} | ||
| 403 | ))) | ||
| 404 | * [[Add the new link type on the XWiki Rendering side>>rendering:Main.Extending.WebHome||anchor="HAddinganewLinkType"]]. | ||
| 405 |
