| Home > Hacking Invenio > CKEditor Integration |
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.
CKEditor is a GPL WYSWYG javascript-based HTML editor. It is currently used in the following modules of Invenio:
Read the Invenio INSTALL file to learn how to deploy CKEditor on your installation.
Theinvenio/Makefile.am::install-ckeditor-plugin installs the necessary files
for the user:
/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.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.
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.
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.
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.