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

Marius Dumitru Florea

Active Installs1184
Rating
Rate!
2 Votes
LicenseGNU Lesser General Public License 2.1

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

The editor supports all standard formatting features. You can edit the source (Source tool bar button) and the output of the wiki macros is protected (read only).

editMode.png

Starting with version 1.2 you can insert images by drag & drop or through the image dialog, by selecting from the existing image attachments. You can also create links to wiki pages or attachments, by selecting them from the document tree picker.

Starting with version 1.7 you can insert and edit wiki macros. There's a dedicated button for this on the tool bar that triggers the Macro Wizard.

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.

wysiwyg-editor-config.png

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

See the full list of configuration options in the CKEditor documentation.

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:

  • Import office documents
  • 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.12

This version includes the following:

TypeKeyStatusSummaryAssignee
BugCKEDITOR-102ClosedUnable to edit a page in Source mode on IE11Marius Dumitru Florea
BugCKEDITOR-66ClosedCKEdit: Switch to source corrupt page when connection lost or when connection is very slowMarius Dumitru Florea
BugCKEDITOR-143ClosedHorizontal scroll bar displayed when inserting a large image on IE11Marius Dumitru Florea
BugCKEDITOR-73ClosedCKEditor is not center-aligning table that's copied from a Word file where it is center-alignedMarius Dumitru Florea

v1.11

This version includes the following:

TypeKeyStatusSummaryAssignee
TaskCKEDITOR-136ClosedUpgrade to CKEditor 4.6.2Marius Dumitru Florea
ImprovementCKEDITOR-139ClosedEnable the Advanced Content Filter and configure it for the XWiki syntaxMarius Dumitru Florea
BugCKEDITOR-140ClosedVelocity error when inserting a macroMarius Dumitru Florea
BugCKEDITOR-141ClosedImage larger than the screen inserted with CKEditor gets distorted by default by Flamingo (explicit image size is added by default in CKEditor)Marius Dumitru Florea
BugCKEDITOR-142ClosedCannot change the alternative text for free-standing imagesMarius Dumitru Florea
BugCKEDITOR-133ClosedUse of Greasemonkey in Firefox can interfere with CKEditor contentMarius Dumitru Florea
BugCKEDITOR-134ClosedUnclosed {{html}} results in addition of closing tag even when macro isn't actually evaluatedMarius Dumitru Florea
BugCKEDITOR-132ClosedImage not displayed in edit mode: the XDOM editor renders the edited content in the context of the editorMarius Dumitru Florea
BugCKEDITOR-92ClosedCannot add 'cssClass' parameter to the 'box' macroMarius Dumitru Florea
BugCKEDITOR-37ClosedThe yellow marker style is not applied on text contentMarius 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.12):

Tags:
Created by Marius Dumitru Florea on 2015/02/15 10:44
    

Get Connected