Contents

• 1. About FCKeditor
• 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 FCKeditor integration with Invenio.
Read the Invenio INSTALL file to learn how to install FCKeditor on your Invenio instance.

Also note that a major revision of FCKeditor is planned for version 3 (as well as a renaming to "CKEditor"). As a consequence, links from this page to the FCKeditor documentation might be broken or outdated, and the integration might need to be reworked. This documentation should help in this respect.

1. About FCKeditor

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

It can optionally (and rather easily) be integrated into WebSubmit Response Elements too, but there is no WebSubmit Core Element using FCKeditor for the moment.

Maintenance

Installation

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

The invenio/Makefile.am::install-fckeditor-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/fckeditor/
• Server-side integration: the class to embed the editor using Python (instead of Javascript) goes here: /opt/invenio/lib/python/invenio/fckeditor/fckeditor.py
• Server-side connector: the base Python classes for the server-side connection (to support files upload/browsing) are copied into /opt/invenio/lib/python/invenio/fckeditor/editor/filemanager/connectors/py/, keeping the source hierarchy of directories

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-fckeditor-config.js: custom configuration file. Installed in /opt/invenio/var/www/fckeditor/.
• 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-fckeditor-plugin" has never run.
• invenio/modules/webstyle/lib/fckeditor_invenio_connector.py: subclasses the fckeditor connector for server-side integration, to support files upload. This file is always installed, even if "make install-fckeditor-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 FCKeditor 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 FCKV 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-fckeditor-config.js and invenio/modules/webstyle/lib/fckeditor_invenio_connector.py: they are basically the only files that interface with the FCKeditor, and must adapt to modifications of FCKeditor APIs.

Configuration

The configuration of FCKeditor (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 FCKeditor 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-fckeditor-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.

Javscript vs Python Integration

FCKeditor can be integrated into pages either via Javascript, or using the Python wrapper. The current way of doing is to use the Python wrapper.

Pro and cons of using the Python wrapper:

• + easier to read and maintain
• + can be pylinted
• + faster on client-side?
• + can partly hide changes in FCKeditor APIs?
• - cannot check if client has enabled Javascript (can only check user-agent for compatibility)*
• - might be dropped at some point?

* A trick is applied to check if client has enabled Javascript when editor is integrated via Python: the complete instantiation code is written via document.write(..) (in Javascript) and a <noscript> tag is used to fall back on a regular <textarea>.

APIs

Basic Integration

To integrate the FCKeditor, 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 FCKeditor 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 FCKeditor) 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 FCKeditor, 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 FCKeditor, does something with the file (eg. moves it to a chosen location) and sends a correct reply.

To do so, the easiest is to instantiate an FCKeditorConnectorInvenio object with the input parameters, and sends back the value returned by its doResponse() function. Note that you have to correctly set the response headers by reading the object headers member and implement yourself restrictions checking in your code, as this is not managed by the FCKeditorConnectorInvenio class

You can use the following parameters when instantiating the connector:

user_files_absolute_path

the base path where the files should be saved. Eg:%(CFG_PREFIX)s/var/data/comments/%(recid)s/%(uid)s

user_files_path

the base URL where the files can be accessed from the web, if user_files_absolute_path is not a web accessible folder. Eg: %(CFG_SITE_URL)s/record/%(recid)i/comments/attachments/get/%(uid)s

Note that if you set user_files_path, you have to implement your own handler to stream the files from the directory user_files_absolute_path.
Also note that whatever value you choose for the above parameters, FCKeditor appends sub-paths automatically, such as /file/ for regular files, or /image/ for images.

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

There is currently no implementation for server files browsing.