CKEditor Integration

Last modified by Marius Dumitru Florea on 2017/12/11 11:18

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

Marius Dumitru Florea

Active Installs2355
Rating
Rate!
13 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Enterprise

Compatibility

XWiki 6.2.5+

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.

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.

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.

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.

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.

Wiki Macros

We added a button on the tool bar to insert wiki syntax macros. This button opens the Macro Wizard which allows you to select a macro and set its parameters. 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.

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

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

Full Screen Mode

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

ckeditor-fullScreen.png

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.

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

Customization

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

Put Dedicated Insert Macro Buttons on the Tool Bar

Starting with version 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.

config['xwiki-macro'] = config['xwiki-macro'] || {};
config['xwiki-macro'].insertButtons = [
 'documentTree',
  {
    commandId: 'xwiki-macro-html-dirty',
    macroCall: {
      name: 'html',
      parameters: {
        clean: false,
        wiki: true
      }
    }
  }
];

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 move buttons for the same macro)

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.

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.:
      CKEDITOR.plugins.addExternal('foo', new XWiki.Document('Foo', 'Sandbox').getURL('jsx'));

      And the content of the Sandbox.Foo JSX would look something like:

      CKEDITOR.plugins.add('foo', {
        init: function(editor) {
          ...
        }
      });
    • In a JavaScript skin extension. E.g.:
      require(['deferred!ckeditor'], function(ckeditorPromise) {
        ckeditorPromise.done(function(ckeditor) {
          ckeditor.plugins.addExternal('foo', "$xwiki.getSkinFile('ckeditorPlugins/foo.js')");
        });
      });
  2. Enable the plugin in the CKEditor configuration:
    config.extraPlugins = 'foo,bar';

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.

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)

Tested on

This extension has been tested with the following configurations.

Extension VersionXWiki FlavorNotes
1.0XWiki Enterprise [6.2.5, 7.1-milestone-1)
1.1XWiki Enterprise 7.1-milestone-1+
1.2XWiki Enterprise 6.2.5+

The tree pickers are not available on 6.2.5 but otherwise the editor works fine. If you want the document/attachment pickers you need 6.3+

1.2XWiki Enterprise 7.4.1

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

This version includes the following:

TypeKeyStatusSummaryAssignee
ImprovementCKEDITOR-195ClosedNormalize the white space from the link reference when creating a link to a new pageMarius Dumitru Florea
BugCKEDITOR-196ClosedText color is lost when pasting from Office with disabled paste filterMarius Dumitru Florea

v1.19

This version includes the following:

TypeKeyStatusSummaryAssignee
ImprovementCKEDITOR-193ClosedAdd a "Clean Paste Content Automatically" option for CKEditorMarius Dumitru Florea
BugCKEDITOR-191ClosedTab title in Applications; WYSIWYG Editor Section is "Config"Marius Dumitru Florea

v1.5

This version is not usable due to CKEDITOR-64. You should install a more recent version (1.6+).

v1.0

The first version of the integration includes:

  • a new entry in the Edit menu to trigger the CKEditor
  • standard editing features (text formatting, styles, tables, etc.)
  • support for editing the wiki syntax (the Source button on the tool bar)
  • support for protecting wiki macro output (read only)
  • preview, save, save & continue, cancel

Dependencies

Dependencies for this extension (org.xwiki.contrib:application-ckeditor-ui 1.20):

Tags:
Created by Marius Dumitru Florea on 2017/08/25 10:13
    

Get Connected