Integrating the FCKeditor with Lenya

This document describes how to get the open source FCKeditor WYSIWYG editor working within Apache Lenya 1.2. (For Lenya 2.0 and beyond, see HowToIntegrateFCKEditor2.0.) FCKeditor is a browser-based web page editor written entirely in Javascript, superficially similar to the Kupu editor that comes with Lenya. FCKeditor is one of the most stable and mature such editor available, and its itegration into Lenya makes Lenya a more usable CMS.

These integration files are licensed under the same Apache license as Lenya itself. FCKeditor itself, however, uses the GNU lesser general public license, which is incompatible with the Apache license. For that reason, FCKeditor can't be distributed with Lenya itself.

Prerequisites

  1. Lenya 1.2.4 or 1.2.x (may also work with older 1.2 versions). These instructions will NOT work with Lenya 2.0 (but see HowToIntegrateFCKEditor2.0).

  2. FCKeditor 2.0, 2.1, 2.2 or 2.3. You will download this as part of the installation below. NOTE: For FCKeditor 2.4 and beyond some very slight adjustments are needed along the lines of http://issues.apache.org/bugzilla/show_bug.cgi?id=41842.

Installation Instructions

1. Download lenya-fckeditor.zip. This ZIP file contains everything needed to make FCKeditor work within Lenya (but does not contain FCKeditor itself), and extract it to your lenya/webapp/lenya/usecases folder. It will install a subfolder called "fckeditor" within that location.

2. If you're working with the binary copy of Lenya, move the FredSaveAction.class and UploadFredAsset.class files from the fckeditor folder into your build/lenya/classes/org/apache/lenya/cms/cocoon/acting/ folder. Or, if you're working with the Lenya source code, instead copy FredSaveAction.java and UploadFredAsset.java into your existing src/java/org/apache/lenya/cms/cocoon/acting/ folder and rebuild Lenya.

3. Download FCKeditor from http://www.fckeditor.net/. FCkeditor's ZIP file will contain everything within a starting "FCKeditor" folder, so just extract the contents of the ZIP file into your newly-created lenya/webapp/lenya/usecases/fckeditor folder.

4. Edit your /lenya/webapp/global-sitemap.xmap file, adding the following after the <!-- Editor BXE --> and <!-- Editor Epoz --> sections:

5. To add FCKeditor to your publication's Edit menu, edit your lenya/webapp/lenya/pubs/%PUB_NAME%/config/menus/generic.xsp file, adding a line like the following after the "Edit with BXE" line:

Limitations & Missing Features

1. You can only edit pages that are in the publication's default language.

2. Links are created absolute (starting with a slash), not relative, which means that you have to modify the export process if you export your files to static HTML.

3. <img> tags pointing to URL's outside of the site are corrupted when the document is saved.

4. Create Directory doesn't work.

5. File Upload doesn't (quite) work. Close, though.

6. Validation needs to be added to FredSaveAction.java. It is currently possible to introduce invalid XHTML into the source by cut-and-paste or editing in the source view. Such invalid text will result in an "<map:call function> did not send a response" error upon saving.

Also: There is probably a better way to get the lenya dc meta tags in the document when saving rather than hard coding them in the xsl file. The usecase-fckeditor.xmap file also needs to be cleaned up, and there are some unneeded files in the xslt folder generated by copying bxe folders.

Deleting What You Don't Need

There are almost 200 files that come with FCKeditor that you won't need for Lenya. You can leave them in place with no ill effect, or you can delete them to save space. All of the following files/folders under the fckeditor/FCKeditor folder can be deleted:

1. Any file or folder beginning with "_":

2. Any support files for other languages:

Making It Better

FCKeditor itself is highly customizable. You can control which tool icons are available, turning off any tools that you want to hide from your users, or even define entirly new toolbar sets. You can also set up special styles to appear in the Styles drop-down menu. Browse through some of the options in the fckconfig.js file to see what is available. BUT -- and this is important -- you should set all your preferences & customizations in the resources/invokeEditor.js file rather than the FCKeditor/fckconfig.js file so that you can later upgrade FCKeditor by just dropping a new version in place.

Internationalization

FCKEDITOR is fully internationalized, with dozens of language translations available, chosen automatically based on the web browser's default language. The Lenya/FCKeditor integration works just fine with your publication's default language. The use of languages other than your publication's default, however, is not fully supported yet.

Upgrading to a Newer Version of FCKeditor

Everything from the www.fckeditor.net web site -- that is, the editor itself -- is kept inside our fckeditor/FCKeditor folder. So you can just drop in a new FCKeditor version into that folder without losing your settings and the special customizations that make FCKeditor work well with Lenya. But there is one thing inside the fckeditor/FCKeditor folder that must be added back after an FCKeditor upgrade: the "lenya" file browser. This is the fckeditor/FCKeditor/editor/filemanager/browser/lenya folder. Just remember to copy it back after upgrading FCKeditor and you'll be all set. If you don't do this important step, the "Browse Server" buttons won't work properly.

Developers: Understanding the Lenya/FCKeditor Integration

This section details exactly how the Lenya/FCKeditor integration works. You can skip over this section if you are just using FCKeditor. But if you're modifying or improving how FCKeditor works with Lenya, do read on...

Usecases

The usecase-fckeditor.xmap file implements the "open" and "edit" usecases. "Open" opens the editor and reads in the file. "Edit" handles the save and cancel steps.

The usecase-fckeditor.xmap file also handles File Browser interactions, which include listing of files and folders on the server as well as file upload and folder creation. Technically speaking, these interactions are not real Lenya usecases, since they don't use the lenya.usecase parameter in the URI. This is dictated by limitations in the way FCKeditor forms the URI of its requests to the server. Such URI's start look like this:

Since FKeditor doesn't know how to formulate lenya.usecase parameters, we adapt the Lenya pipelines to FCKeditor rather than adapting FCKeditor to Lenya. We have incorporated these non-usecase interactions into the usecase-fckeditor.xmap file merely for convenience of packaging.

To satisfy FCKeditor's "FoldersAndFiles" request, we use separate pipelines for folders and files, using DirectoryGenerator on the content/authoring and resources/authoring folders, respectively, and then we aggregate those two results into one XML output stream.

File Browser

In FCKeditor, the "File Browser" is a collection html, javascript and icon files that create a pop-up window to let you select from files on the server, much like a File Open dialog box. The javascript code makes AJAX-like calls to the server, requesting an XML data stream that lists the files and folders that FCKeditor should display to the user.

We use Cocoon's DirectoryGenerator component to generate that XML data stream. However, because Lenya's URL's don't contain true file names (for a URI of /foo/bar.html, for example, the actual data file may be .../foo/bar/index_en.xml), a simple folder listing wouldn't allow the selection of CMS documents (although assets would be selectable). To enable selection of CMS documents (nodes in the site tree, or folders in the content/authoring area), we copied FCKeditor's "Default" file browser, named it "Lenya", and added [SELECT] links to the right of each folder name, with the links in the "foldername.html" form.

File browseer requests look something like this, where %PUB_NAME% is your publication name, and %DOC_ID% is your document ID:

The first part of that URI (/fckeditor/editor/filelmanager/browser/lenya/) comes directly from the filemgr variable in invokeEditor.js file. TODO: if %DOC_ID includes the _xx (language) ending then the formation of the directory name for DirectoryGenerator is incorrect. This needs to be fixed.

Lenya Toolbar

The "Lenya" Toolbar, defined in config.js, is a variation of FCKeditor's "Default" toolbar, with certain items removed. In particular, the "New" and "Template" tools are removed because they erase the contents of the editor without confirmation. Also removed are the form tools (checkboxes, radio buttons, etc), which are unlikely to be useful to most users. If you want to change the selection of tools available in the "Lenya" toolbar, just edit the fckeditor/resources/config.js file.

File Upload

This is implemented but currently broken. It's probably easy to fix.

Folder Creation

Within the File Browser, the user is offered the option to create a sub-folder within the currently displayed folder. This functionality is not yet implemented. One idea is to implement this to internally create a simple Lenya document (with corresponding site tree node and content directory), perhaps that automatically contains a list of the contents of its resource folder.

HowToIntegrateFCKEditor (last edited 2009-09-20 23:27:14 by localhost)