Wiki source code of Features

Last modified by Manuel Leduc on 2023/10/10 13:52

Show last authors
1 {{velocity output="false"}}
2 #set ($discard = $xwiki.ssx.use('xwiki:Documentation.UserGuide.Features.KeyboardShortcuts'))
3 {{/velocity}}
4
5 The CKEditor integration with XWiki provides most of the standard editing features available in [[CKEditor>>https://ckeditor.com/]] and some additional features that are specific to XWiki.
6
7 {{toc start="2"/}}
8
9 == Standard CKEditor Features ==
10
11 The standard features include: text formatting, lists, links, images, tables and many more. Check the [[CKEditor>>https://ckeditor.com/]] web site to see all the supported features. Note that by default XWiki doesn't enable all the features available in CKEditor because we want the users to focus on the content and leave the styling in the hands of the XWiki skin. This way all wiki pages will have a consistent style. For this we disable by default the features that are related to styles, such as text aligning, changing fonts or text color. If you really need these features you can enable them from the dedicated [[administration section>>||anchor="HAdministrationSection"]].
12
13 {{image reference="ckeditor.png"/}}
14
15 == XWiki Features ==
16
17 In order to integrate CKEditor with XWiki we had to modify some of the standard features, like links and images, and to add new features that only make sense in XWiki, like support for wiki macros.
18
19 === Advanced Content Filter for XWiki Syntax ===
20
21 From the start you need to know that the content you edit with the CKEditor is saved in XWiki as wiki syntax. This means that the HTML produced by the CKEditor is converted at save time to wiki syntax. In order for this conversion to be possible we have to disable the CKEditor features that produce content that cannot be written in wiki syntax and to remove (filter) such content from the CKEditor output. We achieve this by configuring the [[Advanced Content Filter>>https://docs.ckeditor.com/#!/guide/dev_acf]] and the [[Paste Filter>>https://docs.ckeditor.com/ckeditor4/docs/#!/api/CKEDITOR.config-cfg-pasteFilter]] with rules for the [[XWiki Syntax>>xwiki:Documentation.UserGuide.Features.XWikiSyntax.WebHome]].
22
23 In order for a wiki syntax to be compatible with the CKEditor it needs to:
24 * have a parser so that we can convert from the wiki syntax to HTML before the editor is loaded or when switching from Source to WYSIWYG mode
25 * have a renderer so that we can convert from HTML to wiki syntax on save or when switching from WYSIWYG mode to Source
26 * provide a configuration for the Advanced Content Filter; this is hard-coded at the moment unfortunately but we plan to make it plugable
27
28 Changing the wiki syntax while the content is being edited with the CKEditor will trigger a reload of the editor because the Advanced Content Filter configuration cannot be updated on the fly. But don't worry, unsaved changes won't be lost. In case the new wiki syntax doesn't support WYSIWYG editing (because it doesn't have a renderer that would allow the editor to convert the edited content from HTML to the new syntax) then the CKEditor will force the Source mode after the reload, disabling the WYSIWYG mode at the same time.
29
30 Checkout the [[XWiki Rendering Framework>>rendering:Main.WebHome]] documentation for more information on available syntaxes.
31
32 === Wiki Syntax Source ===
33
34 The Source button from the tool bar allows you to view and edit the underlying wiki syntax that is generated by the CKEditor. The text selection (caret) is preserved when switching between Source and WYSIWYG mode ({{info}}since v1.45{{/info}}).
35
36 {{image reference="ckeditor-source.png"/}}
37
38 === Wiki Links ===
39
40 We modified the [[link dialog>>https://ckeditor.com/addon/link]] to add support for creating links to wiki pages and attachments. You can still create links to arbitrary web pages (URLs) and links to mail addresses though.
41
42 {{gallery}}
43 image:ckeditor-linkDialog.png
44 image:ckeditor-linkDialog-suggestions.png
45 image:ckeditor-linkDialog-picker.png
46 {{/gallery}}
47
48 You can select the target page or attachment from the list of suggestions that you get as you type or from the tree picker. You can attach files to the edited page from the Upload tab that is visible when the link target type is set to Attachment, or you can drop them over the editing area and the editor will automatically create a link to the new attachment.
49
50 You can also create links to existing wiki pages and attachments directly from the editing area using the link auto-complete feature. Just type (% class="key" %)[(%%) (open square bracket) followed by at least 2 characters and you will get link suggestions based on the typed text.
51
52 {{velocity}}
53 {{html clean="false"}}
54 <video controls muted src="$doc.getAttachmentURL('ckeditor-link-autocomplete.webm')" width="780">
55 Sorry, your browser doesn't support embedded videos.
56 </video>
57 {{/html}}
58 {{/velocity}}
59
60 To remove a link (unlink) you have multiple options:
61 * click on the link and use the balloon (context) toolbar
62 * right click on the link and use the context menu
63 * or use the toolbar button, if it's available
64
65 {{version since='15.7RC1'}}
66 You can create a link by uploading an attachment using the slash (quick actions) shortcut.
67 {{velocity}}
68 {{html clean="false"}}
69 <video controls muted src="$doc.getAttachmentURL('link-upload.mp4')" width="780">
70 Sorry, your browser doesn't support embedded videos.
71 </video>
72 {{/html}}
73 {{/velocity}}
74 {{/version}}
75
76 === Image Attachments ===
77
78 We modified the [[image dialog>>https://ckeditor.com/addon/image2]] to add support for inserting images that are attached to wiki pages. You can still insert external image though.
79
80 {{version since='14.10RC1'}}
81 The new image dialog is now activated by default on new instances, or when ##CKEditor.Config## does not exists.
82 Otherwise, activating the new image dialog must be done by removing ##xwiki-image## from the disabled plugins list in the ##WYSIWYG Editor## section of the Administration.
83 To switch back to the previous image dialog, ##xwiki-image## must be added back to the disabled plugins.
84 {{/version}}
85
86 {{warning}}
87 Note that there are 2 reasons where you could automatically get the new Image plugin enabled when you upgrade to XWiki 13.10.x even if you haven't done so explicitly:
88 * If you've customized the CKEditor configuration (e.g. you enabled or disabled some CKEditor features using the dedicated administration section) then the new image dialog is enabled because your CKEditor configuration is overwriting the new default configuration that is supposed to disable the new image dialog, so you should disable it yourself after the upgrade.
89 * If you've simply hit "Save" in the dedicated administration section for the WYSIWYG editor, even if you didn't make any change.
90 {{/warning}}
91
92
93 {{gallery}}
94 image:image_plugin_select_gallery.png
95 image:image_plugin_select_document_tree.png
96 image:image_plugin_select_upload.png
97 image:image_plugin_select_icon.png
98 image:image_plugin_select_url.png
99 image:image_plugin_edit_standard.png
100 image:image_plugin_edit_advanced.png
101 {{/gallery}}
102
103
104 You can select the image attachment from the list images gallery, from the document tree, by uploading a new attachment, by using an icon, or by inserting an external link. You can also drop images over the editing area and the editor will automatically upload and insert them.
105
106 {{version since='1.62'}}
107
108 The new ##xwiki-image## plugin aims at covering the same feature as ##xwiki-image-old##. In addition, the new ##xwiki-image## allows users to select an image style, giving a standardized appearance to an image by selecting a style from a dropdown list. Image style can be configured from the [[Image Style Administration page>>Extension.Image.Style.UI.WebHome]].
109
110 {{/version}}
111
112 {{version since='1.64'}}
113 The image size fields (widget and height) from the image edit advanced panel locks the dimensions by default. When changing one of the dimension, the other one is updated accordingly, following the ratio between the dimensions of the selected image.
114 This behavior can be dactivated by clicking on the lock button.
115 {{/version}}
116
117 {{version since='1.63'}}
118 Note for developers: The image selection tabs are now provided using an [[User Interface Extension Point>>doc:xwiki:Documentation.DevGuide.Tutorials.UIXTutorial.WebHome]]. For more information see the [[UIXP documentation>>doc:xwiki:Documentation.DevGuide.ExtensionPoint.CKEditor Plugin Image Selector]].
119 {{/version}}
120
121 {{version since='15.1RC1'}}
122 A warning message is displayed to the user when the width or height of an image are larger than the dimensions of the selected image.
123
124 {{image reference="image_dimensions_warning.png" width="350px"/}}
125 {{/version}}
126
127 {{version since='15.6RC1'}}
128 You can also insert images using the slash (quick actions) shortcut by searching for the image action and then searching for the image you want to insert. Images attached to the current page appear first in the drop-down with a "This page" badge. Images that were uploaded more recently appear higher in the list. An "External" badge is displayed to identify images from other wikis. The "Upload Image" entry can be used to upload a new image and insert it.
129 {{velocity}}
130 {{html clean="false"}}
131 <video controls muted src="$doc.getAttachmentURL('image-quick-action-demo.mp4')" width="780">
132 Sorry, your browser doesn't support embedded videos.
133 </video>
134 {{/html}}
135 {{/velocity}}
136 {{/version}}
137
138 === Wiki Macros ===
139
140 We added support for inserting [[wiki syntax macros>>xwiki:Documentation.UserGuide.Features.XWikiSyntax.WebHome||queryString="syntax=2.1&section=Macros"]]. For this you can use either the generic Insert {{velocity}}$services.icon.render('add'){{/velocity}} menu or the dedicated macro toolbar button, when available, which opens the Macro Wizard, allowing you to select a macro and set its parameters.
141
142 Most macros have their output protected (read-only) within the editing area because the output is generated by transforming the macro content based on the parameters you set. The only way to modify the output of such a macro is through the Macro Wizard, which you can open using the same tool bar button or simply by double clicking anywhere on the macro output. If the macro output is empty a place-holder is displayed instead so that you are able to edit the macro parameters.
143
144 If the macro is on a separate line (stand-alone, not inside a paragraph of text) and its content is rendered without being transformed then the editor allows editing the macro content in-place, directly inside the editing area. Some parts of the macro output will still be protected but the area where the macro content is displayed is editable. Using the tool bar button while the caret is inside the macro content will insert a nested macro. Double clicking on the macro output won't open the Macro Wizard. If you want to edit the macro parameters you can use the balloon tool bar visible when the macro content is focused.
145
146 {{gallery}}
147 image:ckeditor-macro-toolbar.png
148 image:ckeditor-macro-select.png
149 image:ckeditor-macro-edit.png
150 image:ckeditor-macro-edit-groups.png
151 image:ckeditor-macro-edit-pickers.png
152 image:ckeditor-macro-output.png
153 image:extension-recommended.png
154 image:installextension-warning.png
155 {{/gallery}}
156
157 When the output of a macro is selected, the macro name appears on the path displayed on the editor status bar.
158
159 {{version before='14.4.3, 14.6RC1'}}
160 On the "Select Macro" step of the Macro Wizard the deprecated and internal macros are hidden from the "All Macros" category that is selected by default. If you need to use a deprecated or internal macro you need to select the corresponding category explicitly.
161 {{/version}}
162 {{version since='14.6RC1'}}
163 On the "Select Macro" step, it is now possible to filter by several categories (as macros can now be attached to several categories). The listed macros are the one who have at least all of the selected categories. If no category is selected, all the macros are listed. Macros with an hidden category are not displayed to users who have ##Display hidden pages## set to ##False## in their preferences. Hidden macros categories are ##Deprecated## and ##Internal## by default, and can be [[configured by Admins>>doc:xwiki:Documentation.AdminGuide.Configuration.WebHome||anchor="HMacroscategoriesandvisibility"]] since 14.8+.
164 {{/version}}
165
166 {{version since="14.4"}}It's also possible to install and select a not yet installed macro by searching for the "Not Installed" category.{{/version}}
167
168 On the Edit Macro step the mandatory parameters and those that have an explicit value set are shown first. The advanced parameters are shown last. The deprecated parameters and those that can be edited in-place (within the editing area) are not shown. If there are too many parameters, some of them are collapsed under a "More" section. When inserting a macro, the macro content text area is prefilled with the text selected within the editing area. This means you can for instance transform a paragraph into an error message by selecting the paragraph text, click the Insert Macro button from the tool bar, select the Error Message macro and insert it. The Macro Wizard doesn't show the macro content text area if the macro content can be edited in-place.
169
170 {{velocity}}
171 {{html clean="false"}}
172 <video controls muted src="$doc.getAttachmentURL('ckeditor-macro-inline-edit.webm')" width="780">
173 Sorry, your browser doesn't support embedded videos.
174 </video>
175 {{/html}}
176 {{/velocity}}
177
178 The macro parameters can be grouped, if the macro descriptor says so. Check for instance the [[Include Macro>>extensions:Extension.Include Macro]]. Two types of macro parameter groups are supported:
179
180 * groups of related parameters (e.g. ##reference## and ##type## in the case of the Include Macro)
181 * groups of alternative parameters (only one parameter in the group should be set); this type of groups are displayed using tabs (e.g. "Resource" and "Page" in the case of the Include Macro)
182
183 Some macro parameters will have pickers, depending on their type. The binding between macro parameter types and the associated pickers is done on the server side (check the ##templates/html_displayer## folder inside the XWiki WAR). For instance, if you have a [[wiki-based rendering macro>>xwiki:Documentation.DevGuide.Tutorials.WritingMacros.WikiMacroTutorial.WebHome]], you can set the type of a macro parameter to "org.xwiki.model.reference.DocumentReference" in order to get a document picker when inserting or editing your macro from the WYSIWYG editor.
184
185 {{version since="15.5RC1"}}
186 You can also insert macros using the slash (quick actions) shortcut. The default category of each macro is mapped to a quick action category. The rest of the categories are displayed as quick action badges. For uninstalled macros there is a "Recommended" badge displayed. The macro name and description are mapped to the quick action name and description.
187 {{/version}}
188
189 === Quick Actions ===
190
191 {{version since="15.5RC1"}}
192 You can use the ##/## (slash) key to activate the Quick Actions drop down that allows you to perform most of the editing features using only the keyboard. Typing after slash will filter the quick actions using fuzzy search. You can use the Escape key to close the Quick Actions drop down (e.g. if your intention was to insert the slash symbol).
193
194 {{velocity}}
195 {{html clean="false"}}
196 <video controls muted src="$doc.getAttachmentURL('quick-actions-macros-install.mp4')" width="780">
197 Sorry, your browser doesn't support embedded videos.
198 </video>
199 {{/html}}
200 {{/velocity}}
201
202 Quick Actions are grouped in categories. Each quick action has a label (name), a description and an icon. Some quick actions can have a dedicated shortcut key displayed on the right of the name. Quick Actions can also have badges, displayed below the name. Rendering macros are displayed directly as quick actions. Administrators can also see uninstalled macros and can install them from the quick actions drop down, similar to the Macro Selector modal.
203
204 Some quick actions are contextual, meaning that they are available only when the caret is placed in a specific context. For instance, place the caret inside a table and check the table-specific quick actions. Other quick actions depend on the availability of an editor command: if you disable the editor plugin that provides that editor command then the corresponding quick action is also removed.
205
206 {{velocity}}
207 {{html clean="false"}}
208 <video controls muted src="$doc.getAttachmentURL('quick-actions-table.webm')" width="780">
209 Sorry, your browser doesn't support embedded videos.
210 </video>
211 {{/html}}
212 {{/velocity}}
213
214 Check the configuration section to see how you can configure the available quick actions.
215 {{/version}}
216
217 {{version since="15.7RC1"}}
218 You can browse and insert icons using the the slash (quick actions) shortcut.
219
220 {{velocity}}
221 {{html clean="false"}}
222 <video controls muted src="$doc.getAttachmentURL('icon-quick-action.mp4')" width="780">
223 Sorry, your browser doesn't support embedded videos.
224 </video>
225 {{/html}}
226 {{/velocity}}
227
228 {{/version}}
229
230 === Office Import ===
231
232 You can import office files using a dedicated button from the tool bar. The files are uploaded and attached to the edited page and their content (including images) is inserted in the content of the page. You have the option to filter the styles and to use the [[Office Viewer macro>>extensions:Extension.Office Macro]].
233
234 {{gallery}}
235 image:ckeditor-office-toolbar.png
236 image:ckeditor-office-modal.png
237 {{/gallery}}
238
239 This feature requires the Office Server to be connected. See the [[Office Importer Application>>extensions:Extension.Office Importer Application]] documentation for more information.
240
241 === Custom Styles ===
242
243 We customized the Styles drop down from the tool bar to include only the styles that make sense in XWiki. We added new styles for tables, images and paragraphs that are specific to the XWiki skin.
244
245 {{image reference="ckeditor-styles.png"/}}
246
247 === Spell Checker ===
248
249 The CKEditor integration uses by default the native browser spell checker. To access the spell checking suggestions you need to use one of the following shortcuts:
250
251 * Windows: (% class="key" %)Ctrl(%%) + Right Click
252 * MacOS: (% class="key" %)Alt(%%) + (% class="key" %)Cmd
253 * Linux: (% class="key" %)Ctrl(%%) + Right Click
254
255 If you don't get any suggestions then it may be the case that your browser doesn't support spell checking natively. You can also configure CKEditor to use an external spell checking web service. Checkout the [[CKEditor documentation>>https://ckeditor.com/docs/ckeditor4/latest/guide/dev_spellcheck.html]] for more information.
256
257 If you're looking for a more secure (local) spell checker then there are CKEditor plugins that provide this functionality.
258
259 === Full Screen Mode ===
260
261 We modified the standard full screen mode from CKEditor to integrate with XWiki's form action buttons.
262
263 {{image reference="ckeditor-fullScreen.png"/}}
264
265 === Empty Line Placeholder ===
266
267 {{version since='15.5RC1'}}
268 A placeholder text is displayed on currently focused empty lines. By default it indicates the type of content block that holds the caret (e.g. paragraph, heading, list item, etc.), but it could also show tips on how to use the editor in that particular context. This is for instance used to advertise the Quick Actions shortcut (slash).
269
270 {{image reference="ckeditor-focusedlineplaceholder.png" width='350px'/}}
271
272 For administrators, you can configure the placeholder from the dedicated [[administration section>>||anchor="HAdministrationSection"]] by adding the following snippet:
273
274 {{code language="js"}}
275 // Replace h1 with the corresponding HTML tag name.
276 config["xwiki-focusedplaceholder"].placeholder.h1 = "Your Heading 1 placeholder";
277 {{/code}}
278
279 For developers, the placeholder plugin uses two configurations:
280 * {{code language="js"}}editor.config["xwiki-focusedplaceholder"].ignoreIfEmpty{{/code}} which is an array of DOM node names that do not appear on screen. If your plugin changes the style of a previously hidden element, it should be removed from this array.
281 * {{code language="js"}}editor.config["xwiki-focusedplaceholder"].placeholder{{/code}} which is an object associating a tag name to a translation key. If your plugin needs to advertise a feature, it should change the translation key this tag name.
282 {{/version}}
283
284 === Unsaved Changes Protection ===
285
286 A confirmation popup is shown when leaving the page with unsaved changes. This should prevent you from loosing unsaved changes by mistake. Additionally, on Firefox, unsaved changes are cached and restored if you leave the page and then go back. The same happens if you (soft) reload the page.
287
288 === Keyboard Shortcuts ===
289
290 The following keyboard shortcuts are available:
291
292 * [[standard keyboard shortcuts>>https://ckeditor.com/docs/ckeditor4/latest/features/shortcuts.html]] provided by CKEditor, independent of its integration in XWiki
293 * XWiki custom shortcut keys:
294 ** (% class="key" %)[(%%) (open square bracket) provided by XWiki's custom [[link plugin>>||anchor="HWikiLinks"]]
295 ** (% class="key" %)@(%%) (at sign) provided by [[Mentions Application>>Extension.Mentions Application.WebHome||anchor="HMentionsAuto-Completion"]]
296 ** [[edit form shortcut keys>>xwiki:Documentation.UserGuide.Features.KeyboardShortcuts||anchor="HEditMode"]] to preview, save or cancel the edit form
297 * custom shortcut keys that an administrator can add using the [[##keystrokes##>>https://ckeditor.com/docs/ckeditor4/latest/api/CKEDITOR_config.html#cfg-keystrokes]] CKEditor configuration parameter from the dedicated [[administration section>>||anchor="HAdministrationSection"]].
298
299 === Administration Section ===
300
301 A dedicated section in the [[Wiki Administration>>extensions:Extension.Administration Application]] is available for the CKEditor where you can enable or disable editing features. Check the [[customization guide>>extensions:Extension.CKEditor Integration||anchor="HCustomization"]] for more advanced configuration options.
302
303 {{image reference="ckeditor-administration.png"/}}
304
305 == Classic Editor vs. Inline Editor ==
306
307 CKEditor can be integrated either by replacing (or acting as) a text area ([[the classic editor>>https://ckeditor.com/docs/ckeditor4/latest/examples/classic.html]]) or by making a paragraph or a section of the page editable in-place ([[the inline editor>>https://ckeditor.com/docs/ckeditor4/latest/examples/inline.html]]). Let's see what are the main differences:
308
309 |=|=Classic Editor|=Inline Editor
310 |**Used by**|[[WYSIWYG edit mode>>xwiki:Documentation.UserGuide.Features.PageEditing||anchor="HWikieditingmode"]], [[Form edit mode>>xwiki:Documentation.UserGuide.Features.PageEditing||anchor="HFormeditingmode28akainlinemode29"]] for TextArea properties|[[In-place editing>>xwiki:Documentation.UserGuide.Features.PageEditing||anchor="HIn-placeediting"]]
311 |**Height**|Fixed|Variable
312 |**Toolbar position**|Fixed, above the editing area|Floating, at the top or at the bottom of the edited section, visible only on focus
313 |**Missing features**|JavaScript execution disabled by default within the editing area|Bottom (path) bar

Get Connected