Contents

• 1. About CKEditor
• 2. Maintenance
  • 2.1  Installation
  • 2.2  Upgrade
  • 2.3  Configuration
  • 2.4  Javscript vs Python Integration
• 3. APIs
  • 3.1  Basic Integration
  • 3.2  File Upload Support

This documentation is developer-oriented, and provides maintenance information about the CKEditor integration with Invenio.
Read the Invenio INSTALL file to learn how to install CKEditor on your Invenio instance.

1. About CKEditor

CKEditor is a GPL WYSWYG javascript-based HTML editor. It is currently used in the following modules of Invenio:

• WebComment: HTML-formatted comments/reviews, and file attachment.
• WebSubmit: some submissions (eg. Journal) can use it in response elements.

Maintenance

Installation

Read the Invenio INSTALL file to learn how to deploy CKEditor on your installation.

The invenio/Makefile.am::install-ckeditor-plugin installs the necessary files for the user:

• Editor: The editor itself and all the necessary files (HTML and Javascript) are installed in /opt/invenio/var/www/ckeditor/

Usually, only the necessary files are copied (Check which files need to be deployed) and none are modified.

Additional files from Invenio are needed to support the editor (these files might already be installed):

• invenio/modules/webstyle/etc/invenio-ckeditor-config.js: custom configuration file. Installed in /opt/invenio/var/www/ckeditor/.
• invenio/modules/miscutil/lib/htmlutils.py: contains function get_html_text_editor(..) to wrap the initialization of the editor. Should one change the way the editor is integrated, this function only would need to be changed. This file is always installed, even if "make install-ckeditor-plugin" has never run.
• invenio/modules/webstyle/lib/ckeditor_invenio_connector.py: adds server-side integration to support files upload. This file is always installed, even if "make install-ckeditor-plugin" has not never run.

Upgrade

Since the integration modifies no file of the editor, it should be straightforward to upgrade to a newer version of the editor, especially with minor revisions.

First check the CKEditor release note, and read tips how to upgrade the editor to ensure that the way invenio/Makefile.am installs the files is ok.

The easiest to test an upgrade is to increase the version number in invenio/Makefile.am, variable CKV and run "Make install". Make sure that the archive can still be downloaded from the usual URL.

What should be specifically checked are htmlutils.get_html_text_editor(..), invenio/modules/webstyle/etc/invenio-ckeditor-config.js and invenio/modules/webstyle/lib/ckeditor_invenio_connector.py: they are basically the only files that interface with the CKEditor, and must adapt to modifications of CKEditor APIs.

Configuration

The configuration of CKEditor (colors, size, behaviour) can be done when instantiating the editor ("inline", in htmlutils.get_html_text_editor(..) function) or via a Javascript config file placed in a web accessible location. Read CKEditor documentation to learn more about these options.
The current solution is to have a maximum of the configuration made in htmlutils.get_html_text_editor(..), such that it is easy to customize the editor directly from the source code, without having to change any Javascript config file.

For the moment a single Javascript file (invenio-ckeditor-config.js) is used, mainly to define the toolbar sets, that cannot be defined "inline".

It is to be thought if it would not be better to have the configuration for each call of the function (or each Invenio module) in different config files. That would make the customization of each instance possible by admin users.

APIs

Basic Integration

To integrate the CKEditor, please exclusively use the following method:

from htmlutils import get_html_text_editor
[...]
out += get_html_text_editor('myeditor')

Refer to htmlutils.py for more information about the function and its parameters.

It is wise to always use the above method and never directly rely on any CKEditor file. You have to expect that the editor is not always installed on the server, or that the client might not support it (eg. Javascript disabled). In these cases, a basic <textarea/> is used instead.
If you need to know what type of input form (textarea or CKEditor) was used by the client, you can catch the value of the form variable editor_type, which is submitted at the same time as other elements of your form.

File Upload Support

In order to support file upload rigth from CKEditor, you must call get_html_text_editor(..) with its file_upload_url parameter set to the URL to which the file will be uploaded.

The second step is to implement the URL handler file_upload_url so that that it understands the "commands" sent by CKEditor, does something with the file (eg. moves it to a chosen location) and sends a correct reply.

To do so, the easiest is to use ckeditor_invenio_connector.process_CKEditor_upload() function with the necessary input parameters, and use the returned callback_function value as input in ckeditor_invenio_connector.send_response() function to send the response to the editor. Note that you have to implement yourself restrictions checking in your code, as this is not managed by the CKEditorConnectorInvenio class

Check invenio/modules/webcomment/webcomment_webinterface::WebInterfaceCommentsFiles URL handler to see how it works

There is currently no implementation for server files browsing.