Dear Wiki user, You have subscribed to a wiki page or wiki category on "Lenya Wiki" for change notification.
The following page has been changed by BobHarner: http://wiki.apache.org/lenya/HowToIntegrateFCKEditor The comment on the change is: Greatly simplified installation instructions (all files in usecases/fckeditor/) ------------------------------------------------------------------------------ = Integrating the FCKeditor with Lenya = - This is still very much a work in progress. This will get the famous FCKeditor (which we have nicknamed "Fred" to reduce snickering) to load with content, save the content, and link to assets. However, validation still needs to be implemented when saving, and the asset upload portion is not quite ready. We've only tried this with Lenya 1.2.3/1.2.4 and FCKeditor 2.0/2.11. Full credit for all this goes to K. Haenni. + This document describes how to get the open source FCKeditor WYSIWYG editor working within the Apache Lenya content management system (CMS). FCKeditor is a browser-based WYSIWYG written entirely in Javascript, superficially similar to the Kupu editor that comes with Lenya. FCKeditor is arguably 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. + + This folder contains all the files needed to get FCKeditor running with Lenya EXCEPT the editor itself (which you will obtain from www.fckeditor.net). Throughout this text, the variable `%LENYA_HOME%` will refer to the main Lenya directory (i.e. the subdirectory `/lenya/webapp` of the complete Lenya application) and `%PUB_HOME%` will refer to the directory of your working publication (i.e. `%LENYA_HOME%/pubs/{yourpub}/`). - 1. Download Fred (the FCK Editor) from http://www.fckeditor.net/. Extract the ZIP or tar file into `%LENYA_HOME%/lenya/resources/. The ZIP or tar file will contain files starting with a "FCKeditor/" directory, so after extracting, rename "FCKeditor" to "fckeditor". + == Prerequisites == - 2. Download [attachment:invokeEditor.js] into that same `%LENYA_HOME%/lenya/resources/fckeditor` directory. + 1. Lenya 1.2.4 or 1.2.x (may also work with older 1.2 versions). It will NOT work with 1.4 (yet). + + 2. FCKeditor 2.0, 2.1 or 2.2 (may also work with other versions). You will download this as part of the installation below. - 3. Add the following to `%LENYA_HOME%/lenya/resources/fckeditor/fckconfig.js` after the line `FCKConfig.ImageDlgHideAdvanced` (around line 120): + == Installation Instructions == + 1. Download [attachment:invokeEditor.js]. 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. - {{{ - // Need to get the publication id and doc id from the cookie. - var dc = document.cookie.split(";"); - var path = ""; - for(var j = 0; j < dc.length; j++){ - var value = dc[j]; - if(value.indexOf("url") > -1){ - path = value.substring(5,value.length); - } - } - var filemgr = '/fckeditor/filemanager/browser/default/browser.html'; - }}} - IMPORTANT: Set filemgr (above) to start with your servlet context root (e.g. '/lenya/fckeditor/...') if you aren't using Jetty or your servlet context is not "/". + 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. - Then, modify the `LinkBrowserURL`, `ImageBrowserURL` and `FlashBrowserURL` values as follows: + 4. Edit your /lenya/webapp/global-sitemap.xmap file, adding the following after the <!-- Editor BXE --> and <!-- Editor Epoz --> sections: + + <!-- Editor FCKeditor + Note: we send all fckeditor/** requests to the usecase-fckeditor.xmap file + even though they are not true usecase requests. (Leaving them as not true + usecase requests minimizes changes to the factory FCKeditor javascript code + for easier upgrades later.) + --> + <map:pipeline> + <map:match pattern="fckeditor/**"> + <map:mount uri-prefix="fckeditor" src="lenya/usecases/fckeditor/usecase-fckeditor.xmap" check-reload="true" reload-method="synchron"/> + </map:match> + </map:pipeline> - {{{ - FCKConfig.LinkBrowserURL = filemgr + '?Type=File&Connector=' + path + '/connectors/lenya/connector.lenya'; - FCKConfig.ImageBrowserURL = filemgr + '?Type=Image&Connector=' + path + '/connectors/lenya/connector.lenya'; - FCKConfig.FlashBrowserURL = filemgr + '?Type=Flash&Connector=' + path + '/connectors/lenya/connector.lenya'; - }}} + 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: + + <item wf:event="edit" uc:usecase="fckeditor" uc:step="open" href="?"><i18n:text>Edit with FCKeditor</i18n:text></item> + + If your users like FCKeditor enough, you may even want to remove the other + editors from the menu and label the FCKeditor menu item as simply + "Edit Page". + + == 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. - 4. Edit `%LENYA_HOME%/lenya/resources/fckeditor/fckeditor.js` as follows: + == Deleting What You Don't Need == - a. Set the height and width of the editor (near the top) to: + 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 "_": - {{{ - this.Width = width || '100%' ; - var usAgent = navigator.userAgent.toLowerCase() ; - if ( usAgent.indexOf("msie") != -1) // Internet Explorer - this.Height = height || '95%' ; - else // Gecko - this.Height = height || screen.height * 0.6; - }}} - IMPORTANT: Also set `this.BasePath` to start with your servlet context root (e.g. '/lenya/fckeditor/...') if you aren't using Jetty or your servlet context is not "/". + _documentation.html + _whatsnew.html + _samples/ (78 files) + _testcases/ (13 files) + editor/_source/ (90 files) - 5. Download the following files to `%LENYA_HOME%/lenya/resources/misc/fckeditor`: + 2. Any support files for other languages: - * [attachment:uploadComplete.xhtml] + *.afp + *.asp + *.cfc + *.cfm + *.lasso + *.php + *.pl + *.py - * [attachment:index.xhtml] - * [attachment:content-namespaces.xml] + == Making It Better == - These file are just simple container pages. The remaining html will be added during the transformations. `index.xhtml` is the container for the editor page itself, and `uploadComplete.xhtml` is the response that's sent to Fred after an asset has been uploaded which contains the name of the file being uploaded and an error code. + 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. - 6. Add the following to `global-sitemap.xmap` just before `<!-- Editor BXE -->` (around line 237): + == Internationalization == - {{{ - <map:pipeline> - <map:match pattern="fckeditor/**"> - <map:mount uri-prefix="fckeditor" src="lenya/fckeditor.xmap" check-reload="true" reload-method="synchron"/> - </map:match> - </map:pipeline> - }}} - 7. Download [attachment:fckeditor.xmap] to `%LENYA_HOME%/lenya/` + 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. - 8. Download [attachment:usecase-fckeditor.xmap] to `%LENYA_HOME%/lenya/usecases/fckeditor/ (a new folder). + == Upgrading to a Newer Version of FCKeditor == - 9. Add the following line to `%LENYA_HOME%/lenya/pubs/pubname/config/menus/generic.xsp` after - `<item wf:event="edit" uc:usecase="bxeng" uc:step="open" href="?"><i18n:text>Edit with BXE</i18n:text></item>` (around line 127): + 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. - {{{ - <item wf:event="edit" uc:usecase="fckeditor" uc:step="open" href="?"><i18n:text>Edit with FCKeditor</i18n:text></item> - }}} - Alternatively, if you want to *only* use the FCKeditor, comment out the other editors in generic.xsp and give the FCKeditor item a label like "Edit Page". - 10. Copy `%LENYA_HOME%/lenya/xslt/bxeng/*` to `%LENYA_HOME%/xslt/fckeditor/`, then download the following files to that new directory: + == Developers: Understanding the Lenya/FCKeditor Integration == - * [attachment:aggregate.xsl] (replacing existing file) + 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... - * [attachment:asset.xsl] (replacing existing file) + === Usecases === - * [attachment:change-image-path.xsl] + 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. - * [attachment:uploadAssetComplete.xsl] + 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: + /fckeditor/editor/filemanager/browser/lenya/{PUBID}/{DOCID}/connectors/lenya/connector.lenya?Command=GetFolders&Type=File&CurrentFolder=/ - * [attachment:savedContent.xsl] + 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. - 11. If you are building Lenya from source, download [attachment:FredSaveAction.java] and [attachment:UploadFredAsset.java] into `src/java/org/apache/lenya/cms/cocoon/acting/`. These are new actions to save edited content and save uploaded files to the page's asset directory, respectively, and rebuild Rebuild Lenya (run build.sh or build.bat). This should automatically compile the java classes from the previous step. If you are *not* building lenya from source (i.e. you downloaded the Lenya binary) just download [attachment:FredSaveAction.class] and [attachment:UploadFredAsset.class] into `%LENYA_HOME%/WEB-INF/classes/org/apache/lenya/cms/cocoon/acting/`. + 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. - Note: `FredSaveAction.java` and `UploadFredAsset.java` are basically the same as `org.apache.lenya.cms.cocoon.acting.OneFormEditorSaveAction.java` and `org.apache.lenya.cms.cocoon.acting.UploadAction.java`, with a few modifications. + === File Browser === - TODO: Validation needs to be added to `FredSaveAction.java`. + 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. - TODO: When creating the Publication, one of the parameters required is the context. Right now, this is hard coded. I have yet to figure out a way to get this. Obviously, hard coding is not the solution - still working on this. Thinking about putting the context in a properties files somewhere. + 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. - To get Fred to work with all your pubs, you will need to repeate step 9 for each publication. + File browseer requests look something like this, where %PUB_NAME% is your publication name, and %DOC_ID% is your document ID: - There are a lot of steps here, and this is still very much a work in progress, but should get the basics of Fred working. In addition, I'm sure there's a better way to get the lenya tags in the document when saving rather than hard coding them in the xsl file. The `fckeditor-usecase.xmap` also needs to be cleaned up, and there are some unneeded files generated by copying bxe directories. Any suggestions or comments are welcome! + /fckeditor/editor/filemanager/browser/lenya/%PUB_NAME%/%DOC_ID%/connectors + /lenya/connector.lenya?Command=GetFoldersAndFiles&Type=File& + CurrentFolder=/%DOC_ID%/fckeditor/editor/filemanager/browser/lenya + /%PUB_ID%/%DOC_ID%/connectors/lenya/connector.lenya? + Command=GetFoldersAndFiles&Type=File&CurrentFolder=/%DOC_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. + --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
