Page MenuHomec4science
Files F73532682

ckeditor.webdoc
No OneTemporary
Actions

File Metadata

Created
Mon, Jul 22, 11:26

ckeditor.webdoc
View Options

## -*- mode: html; coding: utf-8; -*-
## This file is part of Invenio.
## Copyright (C) 2008, 2010, 2011 CERN.
##
## Invenio is free software; you can redistribute it and/or
## modify it under the terms of the GNU General Public License as
## published by the Free Software Foundation; either version 2 of the
## License, or (at your option) any later version.
##
## Invenio is distributed in the hope that it will be useful, but
## WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
## General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with Invenio; if not, write to the Free Software Foundation, Inc.,
## 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
<!-- WebDoc-Page-Title: CKEditor Integration -->
<!-- WebDoc-Page-Navtrail: <a class="navtrail" href="<CFG_SITE_URL>/help/hacking">Hacking Invenio</a> -->
<!-- WebDoc-Page-Revision: $Id$ -->
<h2>Contents</h2>
<ul style="list-style-type:None">
<li><strong>1. <a href="#1.">About CKEditor</a></strong></li>
<li><strong>2. <a href="#2.">Maintenance</a></strong>
<ul style="list-style-type:None">
<li>2.1&nbsp;&nbsp;<a href="#2.1">Installation</a></li>
<li>2.2&nbsp;&nbsp;<a href="#2.2">Upgrade</a></li>
<li>2.3&nbsp;&nbsp;<a href="#2.3">Configuration</a></li>
<li>2.4&nbsp;&nbsp;<a href="#2.4">Javscript vs Python Integration</a></li>
</ul>
</li>
<li><strong>3. <a href="#3.">APIs</a></strong>
<ul style="list-style-type:None">
<li>3.1&nbsp;&nbsp;<a href="#3.1">Basic Integration</a></li>
<li>3.2&nbsp;&nbsp;<a href="#3.2">File Upload Support</a></li>
</ul>
</li>
</ul>
<p>This documentation is <strong>developer-oriented</strong>, and
provides maintenance information about the CKEditor integration with
Invenio. <br />
Read the Invenio INSTALL file to learn how to install CKEditor on
your Invenio instance.</p>
<h2><a name="1.">1. About CKEditor</a></h2>
<p><a href="http://www.ckeditor.net/">CKEditor</a> is a GPL WYSWYG
javascript-based HTML editor. It is currently used in the following
modules of Invenio:</p>
<ul>
<li>WebComment: HTML-formatted comments/reviews, and file
attachment.</li>
<li>WebSubmit: some submissions (eg. Journal) can use it in response
elements.</li>
</ul>
<h2><a name="2.">Maintenance</a></h2>
<h3><a name="2.1">Installation</a></h3>
<p>Read the Invenio INSTALL file to learn <em>how</em> to deploy CKEditor on your installation.</p>
The <code>invenio/Makefile.am::install-ckeditor-plugin</code> installs the necessary files
for the user:
<ul>
<li><strong>Editor:</strong> The editor itself and all the necessary
files (HTML and Javascript) are installed in
<code>/opt/invenio/var/www/ckeditor/</code></li>
</ul>
<p>Usually, only the necessary files are copied (<a href="http://docs.cksource.com/CKEditor_3.x/Developers_Guide/Minimum_Setup">Check which files need to be deployed</a>) and none are modified.</p>
Additional files from Invenio are needed to support the editor
(these files might already be installed): <ul>
<li><strong><code>invenio/modules/webstyle/etc/invenio-ckeditor-config.js</code>:</strong>
custom configuration file. Installed in
<code>/opt/invenio/var/www/ckeditor/</code>.</li>
<li><strong><code>invenio/modules/miscutil/lib/htmlutils.py</code>:</strong>
contains function <code>get_html_text_editor(..)</code> 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 "<code>make install-ckeditor-plugin</code>"
has never run.</li>
<li><strong><code>invenio/modules/webstyle/lib/ckeditor_invenio_connector.py</code>:</strong>
adds server-side integration to
support files upload. This file is always installed, even if
"<code>make install-ckeditor-plugin</code>" has not never run.</li>
</ul>
<h3><a name="2.2">Upgrade</a></h3>
<p>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.</p>
<p>First check the CKEditor release note, and read tips
<a href="http://docs.cksource.com/CKEditor_3.x/Developers_Guide/Installation">how to upgrade the editor</a>
to ensure that the way <code>invenio/Makefile.am</code> installs
the files is ok.</p>
<p>The easiest to test an upgrade is to increase the version number in
<code>invenio/Makefile.am</code>, variable <code>CKV</code> and run
"<code>Make install</code>". Make sure that the archive can still be
downloaded from the usual URL.</p>
<p>What should be specifically checked are
<code>htmlutils.get_html_text_editor(..)</code>,
<code>invenio/modules/webstyle/etc/invenio-ckeditor-config.js</code> and
<code>invenio/modules/webstyle/lib/ckeditor_invenio_connector.py</code>:
they are basically the only files that interface with the CKEditor,
and must adapt to modifications of CKEditor APIs.</p>
<h3><a name="2.3">Configuration</a></h3>
<p>The configuration of CKEditor (colors, size, behaviour) can be
done when instantiating the editor ("inline", in
<code>htmlutils.get_html_text_editor(..)</code> function) or via a
Javascript config file placed in a web accessible location. Read
CKEditor documentation to learn more about these options.<br/>
The current solution is to have a maximum of the configuration made in
<code>htmlutils.get_html_text_editor(..)</code>, such that it is easy
to customize the editor directly from the source code, without having
to change any Javascript config file.</p>
<p>For the moment a single Javascript file
(<code>invenio-ckeditor-config.js</code>) is used, mainly to define
the toolbar sets, that cannot be defined "inline".</p>
<p><strong>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.</strong></p>
<h2><a name="3.">APIs</a></h2>
<h3><a name="3.1">Basic Integration</a></h3>
<p>To integrate the CKEditor, please exclusively use the following method:</p>
<pre>
from htmlutils import get_html_text_editor
[...]
out += get_html_text_editor('myeditor')
</pre>
<p>Refer to <code>htmlutils.py</code> for more information about the
function and its parameters.</p>
<p>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
<code>&lt;textarea/&gt;</code> is used instead.<br/>
If you need to know what type of input form (<code>textarea</code> or
CKEditor) was used by the client, you can catch the value of the form
variable <code>editor_type</code>, which is submitted at the same time
as other elements of your form.</p>
<h3><a name="3.2">File Upload Support</a></h3>
<p>In order to support file upload rigth from CKEditor, you must call
<code>get_html_text_editor(..)</code> with its <code>file_upload_url</code>
parameter set to the URL to which the file will be uploaded.</p>
<p>The second step is to implement the URL handler
<code>file_upload_url</code> 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.</p>
<p>To do so, the easiest is to
use <code>ckeditor_invenio_connector.process_CKEditor_upload()</code> function with the necessary
input parameters, and use the returned <code>callback_function</code>
value as input in
<code>ckeditor_invenio_connector.send_response()</code> function to
send the response to the editor. Note that you have
to <strong>implement yourself restrictions checking in your
code</strong>, as this is not managed by the CKEditorConnectorInvenio
class </p>
<p>Check
<code>invenio/modules/webcomment/webcomment_webinterface::WebInterfaceCommentsFiles</code>
URL handler to see how it works</p>
<p><em>There is currently no implementation for server files browsing.</em></p>

Event Timeline

c4science · Help