CKEditor Integration

Last modified by Admin on 2024/10/15 01:40

page_white_editAdds support for editing wiki pages using CKEditor.
TypeXAR
Category
Developed by

XWiki Development Team

Rating
0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Standard

Compatibility
  • XWiki 6.2.5+
  • Requires XWiki 9.8+ to have the office import button in the CKEditor WYSIWYG editor

Installable with the Extension Manager

Description

Adds support for editing wiki pages using the CKEditor. Starting with XWiki 8.2 this is the default WYSIWYG editor.

On older versions of XWiki (<8.2), after installing this extension, you should see a new entry in the Edit menu called "CKEditor". Of course, in order to get the Edit menu you need to set the "User Type" to "Advanced" in your user profile preferences.

editMenu.png

Features

The CKEditor integration with XWiki provides most of the standard editing features available in CKEditor and some additional features that are specific to XWiki.

Standard CKEditor Features

The standard features include: text formatting, lists, links, images, tables and many more. Check the CKEditor 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.

ckeditor.png

XWiki Features

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.

Advanced Content Filter for XWiki Syntax

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 and the Paste Filter with rules for the XWiki Syntax.

In order for a wiki syntax to be compatible with the CKEditor it needs to:

  • 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
  • have a renderer so that we can convert from HTML to wiki syntax on save or when switching from WYSIWYG mode to Source
  • provide a configuration for the Advanced Content Filter; this is hard-coded at the moment unfortunately but we plan to make it plugable

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.

Checkout the XWiki Rendering Framework documentation for more information on available syntaxes.

Wiki Syntax Source

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 (since v1.45).

ckeditor-source.png

We modified the link dialog 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.

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.

You can also create links to existing wiki pages and attachments directly from the editing area using the link auto-complete feature. Just type [ (open square bracket) followed by at least 2 characters and you will get link suggestions based on the typed text.

To remove a link (unlink) you have multiple options:

  • click on the link and use the balloon (context) toolbar
  • right click on the link and use the context menu
  • or use the toolbar button, if it's available

XWiki 15.7+ You can create a link by uploading an attachment using the slash (quick actions) shortcut.

XWiki 16.8.0+

You can select in the suggester to create a link to a page not yet existing: when doing so the created reference will always comply with the configured name strategy. Note that advanced user can also specify a full reference in the suggester, in which case it's resolved and transformed to respect the name strategy.
It's also possible to chose the not yet existing page by creating a hierarchy within the page tree, with the same result that the created reference will comply with the configured name strategy.

Image Attachments

We modified the image dialog to add support for inserting images that are attached to wiki pages. You can still insert external image though.

XWiki 14.10+ The new image dialog is now activated by default on new instances, or when CKEditor.Config does not exists.
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.
To switch back to the previous image dialog, xwiki-image must be added back to the disabled plugins.

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:

  • 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.
  • If you've simply hit "Save" in the dedicated administration section for the WYSIWYG editor, even if you didn't make any change.

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.

XWiki 1.62+ 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.

XWiki 1.64+ 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.
This behavior can be dactivated by clicking on the lock button.

XWiki 1.63+ Note for developers: The image selection tabs are now provided using an User Interface Extension Point. For more information see the UIXP documentation.

XWiki 15.1+

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.

image_dimensions_warning.png

XWiki 15.6+ 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.

XWiki 16.3.0+ When selecting an attachment to insert in the Gallery, it's now possible to quickly validate the choice and move on to the second step Edit Image by double clicking or pressing Enter when focusing the attachment.

Wiki Macros

We added support for inserting wiki syntax macros. For this you can use either the generic Insert menu or the dedicated macro toolbar button, when available, which opens the Macro Wizard, allowing you to select a macro and set its parameters.

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.

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.

When the output of a macro is selected, the macro name appears on the path displayed on the editor status bar.

XWiki <14.4.3, <14.6 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.
XWiki 14.6+ 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 since 14.8+.

XWiki 14.4+ It's also possible to install and select a not yet installed macro by searching for the "Not Installed" category.

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.

The macro parameters can be grouped, if the macro descriptor says so. Check for instance the Include Macro. Two types of macro parameter groups are supported:

  • groups of related parameters (e.g. reference and type in the case of the Include Macro)
  • 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)

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, 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.

XWiki 15.5+ 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.

XWiki 16.3.0+ The macro parameter modal now behaves like a regular form, and it can be submitted by pressing enter after filling up a parameter.

Quick Actions

XWiki 15.5+

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).

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.

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.

Check the configuration section to see how you can configure the available quick actions.

XWiki 15.7+

You can browse and insert icons using the the slash (quick actions) shortcut.

Office Import

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.

This feature requires the Office Server to be connected. See the Office Importer Application documentation for more information.

Custom Styles

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.

ckeditor-styles.png

Spell Checker

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:

  • Windows: Ctrl + Right Click
  • MacOS:  Alt + Cmd
  • Linux: Ctrl + Right Click

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 for more information.

If you're looking for a more secure (local) spell checker then there are CKEditor plugins that provide this functionality.

Full Screen Mode

We modified the standard full screen mode from CKEditor to integrate with XWiki's form action buttons.

ckeditor-fullScreen.png

Empty Line Placeholder

XWiki 15.5+

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).

ckeditor-focusedlineplaceholder.png

For administrators, you can configure the placeholder from the dedicated administration section by adding the following snippet:

// Replace h1 with the corresponding HTML tag name.
config["xwiki-focusedplaceholder"].placeholder.h1 = "Your Heading 1 placeholder";

For developers, the placeholder plugin uses two configurations:

  • editor.config["xwiki-focusedplaceholder"].ignoreIfEmpty 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.
  • editor.config["xwiki-focusedplaceholder"].placeholder 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.

Unsaved Changes Protection

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.

Keyboard Shortcuts

The following keyboard shortcuts are available:

Administration Section

A dedicated section in the Wiki Administration is available for the CKEditor where you can enable or disable editing features. Check the customization guide for more advanced configuration options.

ckeditor-administration.png

Classic Editor vs. Inline Editor

CKEditor can be integrated either by replacing (or acting as) a text area (the classic editor) or by making a paragraph or a section of the page editable in-place (the inline editor). Let's see what are the main differences:

Classic EditorInline Editor
Used byWYSIWYG edit mode, Form edit mode for TextArea propertiesIn-place editing
HeightFixedVariable
Toolbar positionFixed, above the editing areaFloating, at the top or at the bottom of the edited section, visible only on focus
Missing featuresJavaScript execution disabled by default within the editing areaBottom (path) bar

Supported Syntaxes

You can write page content in different syntaxes. Depending on the syntax used, the page will be editable in WYSIWYG or not. The rule is that a page will be editable in the WYIWYG editor when it has both a parser and a renderer for its syntax. The reason is that the original syntax needs to be converted to HTML (this requires a parser for the syntax and a renderer for HTML, which exists), and back from HTML to the original syntax when saving (this requires an HTML parser - which exists -, and a renderer to the original syntax).

Thus, you can check the list of supported syntaxes to verify those that have both a parser and a renderer. These ones can be edited using the WYSIWYG editor.

Customization

Configuration Levels

The CKEditor integration in XWiki is configured at multiple leves:

  1. app config.js (from application-ckeditor-webjar): default global (static) configuration, no Velocity evaluation
  2. app CKEditor.ConfigSheet (from application-ckeditor-ui): default global (dynamic) configuration, with Velocity evaluation
  3. admin CKEditor.Config: global (static) configuration, no Velocity evaluation <- this page is created when administrators use the dedicated CKEditor administration section
  4. app CKEditor.EditSheet (from application-ckeditor-ui): default instance (dynamic) configuration
  5. dev instance configuration passed when creating the editor <- provided by developers that use the CKEditor API
  6. 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

Each level in this list can overwrite the configuration from previous levels (it's actually a merge). The levels marked with app provide default configuration that shouldn't be modified directly by users. The users can and should configure the editor:

  • either through the dedicated CKEditor administration section (that generates the CKEditor.Config page)
  • or using the CKEditor API (when creating the editor or by listening to editor events)

Configure the Editor

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.

Starting with version 1.9 the recommended way to configure the CKEditor is through the dedicated "WYSIWYG Editor" section in the Wiki Administration.

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.

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:

  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.
  2. On XWiki 8.1M1+ you can create a JavaScript extension with the following code:
    require(['deferred!ckeditor'], function(ckeditorPromise) {
      ckeditorPromise.done(function(ckeditor) {
        ckeditor.on('instanceCreated', function(event) {
         // The editor instance was created but it not yet initialized. Unfortunately the configuration object passed when
         // the instance was created has not been merged with the global configuration yet.
         event.editor.once('configLoaded', function(event) {
           // The editor configuration has been loaded (the instance configuration has been merged with the global
           // configuration) but the editor has not been fully initialized yet so we can modify the configuration.
           ckeditor.tools.extend(event.editor.config, {
              height: 200,
              ...
            }, true);
          });
        });
      });
    });

    Don't forget to set "Use this extension" to "On this wiki".

Configuration Parameters

Check out the CKEditor documentation for the full list of generic configuration parameters. 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:

// 'xwiki-link' is the name of a CKEditor plugin.
config['xwiki-link'] = config['xwiki-link'] || {};
// 'autoGenerateLabels' is the configuration parameter for that plugin.
config['xwiki-link'].autoGenerateLabels = true;
PluginParameterDescriptionSince
 applyPasteFilterAfterPasteFromWordWhether to apply the paste filter after the Word filter. Default value is true1.19
xwiki-imageresourceTypesThe resource types you can select from on the Image dialog. See ResourceType.java for the list of supported resource types. The default value is: ['attach', 'icon', 'url'] 
xwiki-linkresourceTypesThe resource types you can select from on the Link dialog. See ResourceType.java for the list of supported resource types. The default value is: ['doc', 'attach', 'url', 'mailto'] 
autoGenerateLabelsWhether to create links with auto-generated labels 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 false1.14
labelGeneratorThe service used to obtain the generated link labels, in case autoGenerateLabels is true.1.14
xwiki-macroinsertButtonsUsed to put dedicated insert macro buttons on the tool bar. See the following sections for more information. The default value is []1.13
xwiki-resourcedispatcherThe service used to obtain resource URLs. 
xwiki-savesaveAndContinueButtonThe CSS selector for the Save & Continue button. The default value is: 'input[name=action_saveandcontinue]' 
 leaveConfirmationWhether to ask for confirmation when leaving the editor with unsaved changes. The default value is true 
xwiki-sourcehtmlConverterThe service used to convert between HTML and wiki syntax. This is used when switching between WYSIWYG and Source modes. 
xwiki-slashextraQuickActionGroupsDefine 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:
config.extraQuickActionGroups = [{
  id: 'diagrams',
  name: 'Diagrams',
  order: 300
}];
15.5RC1
extraQuickActionsDefine 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:
config.extraQuickActions = [{
  group: 'content',
  id: 'a',
  name: 'Link',
  iconClass: 'fa fa-link',
  shortcut: '[',
  description: 'Insert a link to a wiki page or attachment.',
  outputHTML: '['
}, {
  group: 'formatting',
  id: 'macro-code-js',
  name: 'JavaScript Snippet',
  iconClass: 'fa fa-code',
  description: 'Insert a snippet of JavaScript code',
  command: {
    name: 'xwiki-macro',
    data: {
      name: 'code',
      parameters: {
        language: 'js'
      },
    }
  }
}];
15.5RC1
removeQuickActionsSpecifies which quick actions to remove; the value is an array of quick action identifiers (strings); default value is [] (empty array); here's an example:
config.removeQuickActions = ['blockquote', 'macro-toc'];

Note: if you want to remove a macro use the prefix "macro-" and add the id of the macro.

15.5RC1
xwiki-focusedplaceholderplaceholderAssociates a placeholder text to an HTML tag name; here's an example:
config["xwiki-focusedplaceholder"].placeholder.h1 = "Your Heading 1 placeholder";
15.5RC1
ignoreIfEmptyThe 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

Put Dedicated Insert Macro Buttons on the Tool Bar

XWiki 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. 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).

XWiki 1.57+ 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.

config['xwiki-macro'] = config['xwiki-macro'] || {};
config['xwiki-macro'].insertButtons = [
 // First button, specifies only the macro name.
 'documentTree',
 // Second button, specifies also macro parameter values.
 {
    commandId: 'xwiki-macro-html-dirty',
    macroCall: {
      name: 'html',
      parameters: {
        clean: false,
        wiki: true
      }
    }
  },
 // Third button, specifies also the macro content, and the macro is inserted directly.
 {
    insertDirectly: true,
    macroCall: {
      name: 'info',
      content: 'type message here'
    }
  }
];

As you can see, there are two ways in which you can specify the buttons:

  • a simple way: you just specify the macro name
  • 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)
    • you can control whether the macro is inserted inline or as a block element from the macro call configuration:
      macroCall: {
        name: 'mention',
        inline: false|true|'enforce',
        ...
      }

      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. XWiki 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.

Then, you can control the button icon by using some CSS in a custom skin or by using a SSX Skin Extension. Here's an example:

a.cke_button.cke_button__xwiki-macro-documenttree > span.cke_button_icon.cke_button__xwiki-macro-documenttree_icon {
 font-family: 'Glyphicons Halflings';
 position: relative;
 top: 1px;
}
.cke_button_icon.cke_button__xwiki-macro-documenttree_icon::before {
 content: "\e199";
 display: inline-block;
 text-align: center;
 width: 16px;
}

In this example we've used a font icon, but you can use whatever icon you want through CSS.

Customize the well-known macro list

It's possible to customize the content of the macro list from:

insertMenuCustomize.png

The insert button drop-down is controlled by two configuration properties:

  • toolbarMenuItems: you first need to define a "toolbar menu item" for the macros you want to expose. Check the examples:
      infoBox: {
        command: 'xwiki-macro-insert',
        data: {
          name: 'info',
          content: 'Type your information message here.',
          parameters: {...}
        }
      },

    As you can see you can specify both the macro content and parameters (preset the values). For the command you have two options:

    • xwiki-macro-insert: insert the macro directly
    • xwiki-macro: open the macro wizard
  • toolbarMenus: you need to modify the "insert" menu.

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).

Use additional CKEditor plugins

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 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.

You need to do two things if you want to integrate additional CKEditor plugins:

  1. Let CKEditor know where the plugin is located:
    CKEDITOR.plugins.addExternal('plugin name', 'plugin URL or path');

    You can put this:

    • 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 like this
      CKEDITOR.plugins.add('foo', {
        init: function(editor) {
          ...
        }
      });

      then you can specify its location with this:

      CKEDITOR.plugins.addExternal('foo', new XWiki.Document('Foo', 'Sandbox').getURL('jsx'));
    • or in a JavaScript skin extension. E.g.: assuming the CKEditor plugin is defined by resources/ckeditorPlugins/foo.js within the XWiki WAR then you can specify its location with
      require(['deferred!ckeditor'], function(ckeditorPromise) {
        ckeditorPromise.done(function(ckeditor) {
          ckeditor.plugins.addExternal('foo', "$xwiki.getSkinFile('ckeditorPlugins/foo.js')");
        });
      });

      Make sure the JSX is configured to be loaded automatically on the entire wiki.

  2. Enable the plugin in the CKEditor configuration:
    config.extraPlugins = 'foo,bar';

Extend the default style set

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:

  • Use the dedicated administration section to overwrite completely the style set. Checkout the styleSet configuration option. You'll probably want to copy some of the default styles.
  • Use a JavaScript extension (e.g. a JSX object loaded on the wiki) to extend the default style set:
    // The following code is executed only when CKEditor is loaded on the current page.
    require(['deferred!ckeditor'], function(ckeditorPromise) {
      ckeditorPromise.done(function(ckeditor) {
       // Wait for an editor instance to be created.
       ckeditor.once('instanceCreated', function(event) {
         // Wait for the default style set to be loaded.
         event.editor.once('stylesSet', function(event) {
           // Modify the default style set.
           ckeditor.stylesSet.get('html5').push({name: 'Custom', element: 'p', attributes: {'class': 'custom'}})
          });
        });
      });
    });

Execute JavaScript code inside the editing area (XWiki 10.10+)

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:

  • loading and executing the JavaScript code slows down the editor
  • the JavaScript code could modify the edited content (outside of the protected macro output) and these changes would be saved
  • the JavaScript code could throw exceptions or interfere with the CKEditor code thus breaking the editor which may lead to content loss
  • executing the JavaScript code opens the door to XSS attacks

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.

If this is not enough and you really want to execute the JavaScript code inside the editing area then you need to do this:

  1. Enable the loading of the JavaScript Skin Extensions from the CKEditor administration section
  2. Modify the macro code to mark the scripts that are safe to be loaded inside the editing area:
    #set ($discard = $xwiki.jsx.use('Path.To.MyMacro', {'wysiwyg': true}))
  3. Use the macro from the CKEditor and look for:
    • JavaScript exceptions in the JavaScript console
    • Content that should not be saved

    If you get this then you need to fix the JavaScript code.

Replace the Default Editor (before XWiki 8.2)

Starting with XWiki 8.2 the CKEditor is the default WYSIWYG editor so this section applies only to the older versions of XWiki.

When Editing a Page

By default this extension adds a new "CKEditor" entry to the Edit menu. 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 to the CKEditor.EditMenuEntry page and from the Objects editing mode replace the Code property of the existing JavaScriptExtension object with:

require(['jquery'], function($) {
  $('#tmEdit > a, a#tmEditDefault').attr('href', function(index, url) {
   return url + (url.indexOf('?') < 0 ? '?' : '&') + 'editor=inline&sheet=CKEditor.EditSheet';
  });
  $('a#tmEditWysiwyg').attr('href', function(index, url) {
   return url.replace('editor=wysiwyg', 'editor=inline&sheet=CKEditor.EditSheet');
  });
});

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).

When Editing a Section of a Page

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:

require(['jquery'], function($) {
 var modifySectionEditLinks = function() {
   // Use the CKEditor for editing page sections.
   $('.edit_section > a').attr('href', function(index, oldHref) {
     return oldHref + '&editor=inline&sheet=CKEditor.EditSheet';
    });
  };
 if (window.XWiki && XWiki.domIsLoaded) {
    modifySectionEditLinks();
  } else {
   // XWiki 6.4+
   require(['xwiki-events-bridge'], function() {
      $(document).on('xwiki:dom:loaded', modifySectionEditLinks);
    });
  }
});

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.

When Creating a Blank Page

When you create a page 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 the application-ckeditor-blank-page.xar file.

XWiki 15.2+, 14.10.7+

Add parameters to the CKEditor html conversion request

A xwiki:wysiwyg: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.

$(document).on('xwiki:wysiwyg:convertHTML', function(event, data) {
    data.example = 1;
});

Add a new Link Type

If you want to add a new link type in the Link dialog, follow these steps:

  • Configure the list of resource types to appear in the link modal dropdown:
    config['xwiki-link'] = config['xwiki-link'] || {};
    config['xwiki-link'].resourceTypes = ['doc', 'attach', 'url', 'mailto', 'sip'];
  • Specify the resource type metadata, which you can do from a JSX:
    require(['deferred!resource'], resourcePromise => {
      resourcePromise.then(resource => {
        resource.types.sip = {
          label: 'SIP Phone Number',
          icon: 'glyphicon glyphicon-phone',
          placeholder: '+49XXXXXXXX'
        };
       return resource;
      });
    });
  • Add the new link type on the XWiki Rendering side.

Future

The following is not yet supported but we plan to implement in the future:

  • Image preview in the attachment picker
  • Add support for packaging CKEditor plugins as XWiki Extensions

Other tasks remaining to do if we wanted to replace the current WYSIWYG editor:

  • Convert the existing functional tests (or add new ones)

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:

  1. Log in the wiki with a user having Administration rights
  2. Go to the Administration page and select the Import category
  3. Follow the on-screen instructions to upload the downloaded XAR
  4. Click on the uploaded XAR and follow the instructions
  5. You'll also need to install all dependent Extensions that are not already installed in your wiki

Release Notes

v1.64.9

v1.64.8

v1.64.7

v1.64.6

v1.64.5

Dependencies

Dependencies for this extension (org.xwiki.platform:xwiki-platform-ckeditor-ui 16.8.0):

Get Connected