Hide last authors
Marius Dumitru Florea 38.1 1 {{velocity output="false"}}
2 #set ($discard = $xwiki.ssx.use('xwiki:Documentation.UserGuide.Features.KeyboardShortcuts'))
3 {{/velocity}}
Marius Dumitru Florea 1.1 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.
Marius Dumitru Florea 29.1 7 {{toc start="2"/}}
Marius Dumitru Florea 3.2 8
Marius Dumitru Florea 1.1 9 == Standard CKEditor Features ==
Marius Dumitru Florea 3.2 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"]].
Marius Dumitru Florea 1.1 12
Marius Dumitru Florea 3.1 13 {{image reference="ckeditor.png"/}}
Marius Dumitru Florea 1.1 15 == XWiki Features ==
Marius Dumitru Florea 3.3 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.
Marius Dumitru Florea 1.1 18
Marius Dumitru Florea 3.2 19 === Advanced Content Filter for XWiki Syntax ===
Marius Dumitru Florea 35.1 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>>platform:Main.XWikiSyntax]].
Marius Dumitru Florea 3.3 22
Marius Dumitru Florea 81.1 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
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.
Marius Dumitru Florea 82.1 30 Checkout the [[XWiki Rendering Framework>>rendering:Main.WebHome]] documentation for more information on available syntaxes.
Marius Dumitru Florea 1.1 32 === Wiki Syntax Source ===
Marius Dumitru Florea 74.1 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}}).
Marius Dumitru Florea 4.1 35
36 {{image reference="ckeditor-source.png"/}}
Marius Dumitru Florea 1.1 38 === Wiki Links ===
Marius Dumitru Florea 9.2 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.
Marius Dumitru Florea 6.1 41
42 {{gallery}}
43 image:ckeditor-linkDialog.png
44 image:ckeditor-linkDialog-suggestions.png
45 image:ckeditor-linkDialog-picker.png
46 {{/gallery}}
Marius Dumitru Florea 9.2 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.
Marius Dumitru Florea 38.1 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.
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}}
Marius Dumitru Florea 58.1 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
Marius Dumitru Florea 1.1 65 === Image Attachments ===
Marius Dumitru Florea 9.3 67 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.
Marius Dumitru Florea 9.2 68
Marius Dumitru Florea 9.3 69 {{gallery}}
70 image:ckeditor-imageDialog.png
71 image:ckeditor-imageDialog-suggestions.png
72 image:ckeditor-imageDialog-picker.png
73 {{/gallery}}
75 You can select the image attachment from the list of suggestions that you get as you type or from the tree picker. You can attach new images to the edited page from the Upload tab or you can simply drop them over the editing area and the editor will automatically upload and insert them.
Marius Dumitru Florea 1.1 77 === Wiki Macros ===
Marius Dumitru Florea 68.1 79 We added support for inserting [[wiki syntax macros>>platform:Main.XWikiSyntax||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.
Marius Dumitru Florea 18.1 80
Marius Dumitru Florea 43.1 81 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.
Marius Dumitru Florea 40.1 82
Marius Dumitru Florea 46.1 83 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.
Marius Dumitru Florea 43.1 84
Marius Dumitru Florea 18.1 85 {{gallery}}
86 image:ckeditor-macro-toolbar.png
87 image:ckeditor-macro-select.png
88 image:ckeditor-macro-edit.png
Marius Dumitru Florea 48.1 89 image:ckeditor-macro-edit-groups.png
Marius Dumitru Florea 51.1 90 image:ckeditor-macro-edit-pickers.png
Marius Dumitru Florea 18.1 91 image:ckeditor-macro-output.png
92 {{/gallery}}
Marius Dumitru Florea 43.1 94 When the output of a macro is selected, the macro name appears on the path displayed on the editor status bar.
Marius Dumitru Florea 40.1 96 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.
Marius Dumitru Florea 23.1 97
Marius Dumitru Florea 47.1 98 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.
Marius Dumitru Florea 40.1 99
Marius Dumitru Florea 45.1 100 {{velocity}}
101 {{html clean="false"}}
102 <video controls muted src="$doc.getAttachmentURL('ckeditor-macro-inline-edit.webm')" width="780">
103 Sorry, your browser doesn't support embedded videos.
104 </video>
105 {{/html}}
106 {{/velocity}}
Marius Dumitru Florea 52.1 108 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:
110 * groups of related parameters (e.g. ##reference## and ##type## in the case of the Include Macro)
111 * 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)
113 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.
Marius Dumitru Florea 32.1 115 === Office Import ===
117 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]].
119 {{gallery}}
120 image:ckeditor-office-toolbar.png
121 image:ckeditor-office-modal.png
122 {{/gallery}}
124 This feature requires the Office Server to be connected. See the [[Office Importer Application>>extensions:Extension.Office Importer Application]] documentation for more information.
Marius Dumitru Florea 1.1 126 === Custom Styles ===
Marius Dumitru Florea 16.1 128 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.
130 {{image reference="ckeditor-styles.png"/}}
Marius Dumitru Florea 57.1 132 === Spell Checker ===
Jean-Sébastien Dennebouy 36.1 133
Marius Dumitru Florea 57.1 134 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:
Jean-Sébastien Dennebouy 36.1 135
Marius Dumitru Florea 57.1 136 * Windows: (% class="key" %)Ctrl(%%) + Right Click
Marius Dumitru Florea 39.1 137 * MacOS: (% class="key" %)Alt(%%) + (% class="key" %)Cmd
138 * Linux: (% class="key" %)Ctrl(%%) + Right Click
Jean-Sébastien Dennebouy 36.1 139
Marius Dumitru Florea 57.1 140 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.
Marius Dumitru Florea 75.1 142 If you're looking for a more secure (local) spell checker then there are CKEditor plugins that provide this functionality.
Marius Dumitru Florea 57.1 143
Marius Dumitru Florea 1.1 144 === Full Screen Mode ===
Marius Dumitru Florea 13.2 146 We modified the standard full screen mode from CKEditor to integrate with XWiki's form action buttons.
148 {{image reference="ckeditor-fullScreen.png"/}}
Marius Dumitru Florea 17.3 150 === Unsaved Changes Protection ===
Marius Dumitru Florea 1.1 151
Marius Dumitru Florea 17.3 152 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.
Marius Dumitru Florea 17.2 153
Marius Dumitru Florea 83.1 154 === Keyboard Shortcuts ===
156 The following keyboard shortcuts are available:
158 * [[standard keyboard shortcuts>>https://ckeditor.com/docs/ckeditor4/latest/features/shortcuts.html]] provided by CKEditor, independent of its integration in XWiki
159 * XWiki custom shortcut keys:
160 ** (% class="key" %)[(%%) (open square bracket) provided by XWiki's custom [[link plugin>>||anchor="HWikiLinks"]]
161 ** (% class="key" %)@(%%) (at sign) provided by [[Mentions Application>>Extension.Mentions Application.WebHome||anchor="HMentionsAuto-Completion"]]
Marius Dumitru Florea 87.1 162 ** [[edit form shortcut keys>>xwiki:Documentation.UserGuide.Features.KeyboardShortcuts||anchor="HEditMode"]] to preview, save or cancel the edit form
Marius Dumitru Florea 84.1 163 * 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"]].
Marius Dumitru Florea 83.1 164
Marius Dumitru Florea 1.1 165 === Administration Section ===
Marius Dumitru Florea 24.1 166
Marius Dumitru Florea 31.1 167 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.
Marius Dumitru Florea 24.1 168
169 {{image reference="ckeditor-administration.png"/}}
Marius Dumitru Florea 75.1 170
Marius Dumitru Florea 76.1 171 == Classic Editor vs. Inline Editor ==
Marius Dumitru Florea 75.1 172
Marius Dumitru Florea 77.1 173 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:
Marius Dumitru Florea 75.1 174
Marius Dumitru Florea 78.1 175 |=|=Classic Editor|=Inline Editor
176 |**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"]]
177 |**Height**|Fixed|Variable
178 |**Toolbar position**|Fixed, above the editing area|Floating, at the top or at the bottom of the edited section, visible only on focus
Marius Dumitru Florea 80.1 179 |**Missing features**|JavaScript execution disabled by default within the editing area|Bottom (path) bar

Get Connected