Wiki source code of Features

Version 40.1 by Marius Dumitru Florea on 2018/08/17 10:33

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>>platform:Main.XWikiSyntax]].
22
23 === Wiki Syntax Source ===
24
25 The Source button from the tool bar allows you to view and edit the underlying wiki syntax that is generated by the CKEditor.
26
27 {{image reference="ckeditor-source.png"/}}
28
29 === Wiki Links ===
30
31 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.
32
33 {{gallery}}
34 image:ckeditor-linkDialog.png
35 image:ckeditor-linkDialog-suggestions.png
36 image:ckeditor-linkDialog-picker.png
37 {{/gallery}}
38
39 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.
40
41 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.
42
43 {{velocity}}
44 {{html clean="false"}}
45 <video controls muted src="$doc.getAttachmentURL('ckeditor-link-autocomplete.webm')" width="780">
46 Sorry, your browser doesn't support embedded videos.
47 </video>
48 {{/html}}
49 {{/velocity}}
50
51 === Image Attachments ===
52
53 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.
54
55 {{gallery}}
56 image:ckeditor-imageDialog.png
57 image:ckeditor-imageDialog-suggestions.png
58 image:ckeditor-imageDialog-picker.png
59 {{/gallery}}
60
61 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.
62
63 === Wiki Macros ===
64
65 We added a button on the tool bar to insert [[wiki syntax macros>>platform:Main.XWikiSyntax||queryString="syntax=2.1&section=Macros"]]. This button opens the Macro Wizard which allows you to select a macro and set its parameters.
66
67 The macro output injected into the editing area is read-only because it is generated by the macro based on the parameters you set. The only way to modify the macro output is through the macro parameters. Double click on the macro output opens the Macro Wizard. If the macro output is empty a place-holder is displayed instead so that you are able to edit the macro parameters. When you click on the macro output the macro name appears on the path displayed on the editor status bar.
68
69 {{gallery}}
70 image:ckeditor-macro-toolbar.png
71 image:ckeditor-macro-select.png
72 image:ckeditor-macro-edit.png
73 image:ckeditor-macro-output.png
74 {{/gallery}}
75
76 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.
77
78 On the Edit Macro step the mandatory parameters and those that have an explicit value set are shown first. The rest of the macro parameters 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.
79
80 === Office Import ===
81
82 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]].
83
84 {{gallery}}
85 image:ckeditor-office-toolbar.png
86 image:ckeditor-office-modal.png
87 {{/gallery}}
88
89 This feature requires the Office Server to be connected. See the [[Office Importer Application>>extensions:Extension.Office Importer Application]] documentation for more information.
90
91 === Custom Styles ===
92
93 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.
94
95 {{image reference="ckeditor-styles.png"/}}
96
97 === Spell Checker support ===
98
99 CKEditor offers a cut/copy/paste function with the right click of the mouse. And also supports the browser's native spell-check feature.
100 To obtain the browser's regular right click menu on a CKEditor content windows, please use one of the following shortcut:
101
102 * Windows: (% class="key" %)Ctrl(%%) + Right Click
103 * MacOS: (% class="key" %)Alt(%%) + (% class="key" %)Cmd
104 * Linux: (% class="key" %)Ctrl(%%) + Right Click
105
106 === Full Screen Mode ===
107
108 We modified the standard full screen mode from CKEditor to integrate with XWiki's form action buttons.
109
110 {{image reference="ckeditor-fullScreen.png"/}}
111
112 === Unsaved Changes Protection ===
113
114 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.
115
116 === Administration Section ===
117
118 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.
119
120 {{image reference="ckeditor-administration.png"/}}

Get Connected