The patches on this page should only be used with a JSPWiki 2.5.x version (not 2.4.x).

Updates#

14-June-2007#

FCKeditor 2.4.3 is available. The latest Wysiwyg Editing patches are already included in the latest JSPWiki alpha release.

01-Jun-2007#

New patches available for 2.5.69 - fixes the remaining medium issues.

10-Apr-2007#

New patches available for 2.5.40 - fixed the medium issues and added support for all the AugmentedWikiLink attributes. See the patch_notes.txt for more details.

03-Apr-2007#

FCKeditor 2.4.1 is available. Upgrading is recommended since it seems to fix a number of issues (one of them is identified in the quirks section on this page).

05-Mar-2007#

New patches available - many of the known critical & medium issues are now handled. The WysiwygEditingTest.txt file included in the zip is a wikipage to help test WYSIWYG editing. --David Au


General instructions for building JSPWiki with these patches#

These install instructions are tested using JDK 1.5 and Tomcat 5.5.

  1. Obtain the latest 2.5.x source code of JSPWiki from the JSPWikiDownload page or from CVS.
  2. Replace the corresponding files in your $JSPWiki_Source directory with the patched ones from the WysiwygEditingPatch-latest.zip(info) file. (Or use the *.patch files if you know how.)
  3. Run 'ant opened-war' from the command line.
  4. Copy the /build/JSPWiki directory to your webapp directory (typically $Tomcat/webapps/) .
  5. Unzip the FCKeditor_2.4.x.zip file into your $Tomcat/webapps/JSPWiki/scripts/ directory. This will overwrite the existing fckeditor stub directory.
  6. That's it -- you're done, go ahead and start JSPWiki and you should see 'FCK' as an option on the 'Editor' dropdown list.

Note: If you get an error message when trying to save your page, with an error message like "AbstractSAXParser Exception java.lang.NoClassDefFoundError", then try adding the xercesImpl-2.6.2.jar file found under your $JSPWiki_Source/lib directory to your $Tomcat/webapps/JSPWiki/WEB-INF/lib/ directory or the $Tomcat/common/endorsed/ one. This problem might be caused by using an older version of the JDK or Tomcat.

Known Issues and Limitations#

WARNING
Editing wiki pages with FCKeditor is not 100% safe yet! There are still some quirks when editing and saving with FCKeditor. In some cases, the original wiki syntax may either become mangled or may just disappear. You'll have to test and decide if you can live with these problems. Listed below are just the known ones.

Critical Problems#

These are the ones where the original wiki markup will become completely lost or are just really bad problems.
  1. Only affects Firefox: when the first line of a code block contains only whitespace, then all the linebreaks in the code block will be lost due to FCK's html tidying. Although this isn't caused by the html-to-wiki conversion, it's a really bad problem. A bug report has been submitted to the FCKeditor project. A related whitespace bug that affects both IE and FF has been reported too. For now, we have a workaround for this bug in the WysiwygEditingRenderer class.
  2. When editing a page with spaces in the name, if there are wiki links that also have spaces in their names, then the page will either not display in FCK at all or the links will be truncated.

Medium Issues#

These are the ones where the original wiki markup gets mangled. (And also issues that fall somewhere in the middle..)
  1. Inlined images that have a link and were created using the bracket syntax will be converted to the ImagePlugin syntax upon saving.

Quirks and Limitations#

These are the ones that are due to quirks and limitations of JSPWiki or FCKeditor. And also those that are not directly caused by the html-to-wiki conversion process. Most of the ones on this list are not likely to ever be fixed, unless certain changes are made to FCKeditor or JSPWiki.
  1. Clearly, there are many little things that don't work. For example, the table summary attribute set in FCKeditor won't appear in the resulting wiki markup because there's simply no equivalent representation for it in wiki markup. There's not much we can do about these, except possibly disable these options in FCK.
  2. Another example to illustrate the many limitations is if you add a list to a table cell in FCK, then the table will be broken when the page is saved and viewed. This limitation is actually due to JSPWiki, since it's not possible to add a list to a table with the plain text editor either.
  3. Even though using FCKeditor allows you to perform Wysiwyg-editing, you can still utilize wiki markup within it. For example, if you entered [Testlink] in FCKeditor, then 'Testlink' will become a link when the page is saved and viewed. Same thing happens if you tried to start a line with '----', which will generate a horizontal rule. So FCK isn't 100% WYSIWYG, it's a sort of hybrid.
  4. Tabbed sections and collapsible lists won't appear properly while being edited in FCKeditor. However, there is no problem translating them from html to wiki syntax -- it seems to be just a visual problem.
  5. If you have a set of consecutive links, each separated by a single newline, after saving, all of the links will appear on the same line when the page is viewed. Same thing occurs when you have consecutive css styles too. This behavior is not caused by the html-to-wiki conversion process, it's actually the native behavior of JSPWiki. If you tried entering consecutive links or css styles the same way with the plain text editor, the same behavior occurs.
  6. If you add multiple lines of spacing between two bodies of text (or other html elements) by pressing the ENTER key, after saving, the multiple lines of spacing will be reduced to a single line. This behavior is actually similar to how multiple blank lines are interpreted when using the plain text editor too. This is actually caused by the html-to-wiki conversion since empty <p> tags are discarded. And there's a workaround for this: just press CTRL + ENTER to create multiple lines of spacing instead.
  7. Fixed in FCKeditor 2.4.1 Pressing the ENTER key in a info, error, warning, or commentbox block will produce another copy of it. This quirk is due to FCK's ENTER key behavior. If you wish to make a linebreak, press CTRL + ENTER instead.
  8. When using FCK, it will spit out different html tags in certain cases depending on the web browser that you are using. For example, with Firefox, <span> tags will mostly be used for css styling. But with Internet Explorer, the deprecated <font> tags are used instead. As a result, with IE, the style tags tend to accumulate when you apply a new style over the previous one. A workaround for this is to use the "Remove Formatting" button on existing styles before applying a new one. Similarly, the alignment buttons will produce different attributes between IE & Firefox.
  9. You might also notice that on occasion, when you apply a css style (font type, color, size, etc) to the middle of some text that already has some pre-existing css styling, upon saving, all the text on the page either becomes bolded or colored. This is not a bug with the html-to-wiki conversion -- you can produce this problem using the plain text editor too if you are not careful. The difference is that it's easier to make this mistake with FCK since it's easier to apply styles in the first place. If your users run into this alot, then you might want to consider disabling some of the offending toolbar buttons.
  10. It's very difficult to apply css styles to just the <table> tag, e.g. centering or background color. Often you'll end up applying it to an individual table cell or row instead and after saving, you'll get a broken table! Applying text effects to table cells are okay though. Again, this is yet another quirk when using FCK. And not just when it's integrated with JSPWiki, but probably even when used with other wiki's.
  11. Although this isn't a complete list of all the possible quirks and limitations, it's enough to illustrate how problematic it might be. On the other hand, even though this seems like a long and scary list of issues, you might just find that these issues are negligible when you finally try editing with FCK.

To Do List#

Current#

  1. Ongoing Fix the critical problems first, then the medium issues.
  2. Done Implement a WysiwygEditingRenderer class whose responsibility is to prep the rendered XHTML for better Wysiwyg editing.
    1. Shorten the URL string for wiki links to just their wiki page name. For example, if href="Wiki.jsp?page=MyPage", then we'll shorten it to just href="MyPage" so that the user has less to look at when editing the href in FCK.
    2. Do the same as above for Undefined Page links.
    3. Remove html elements & attributes that shouldn't appear in FCK.
  3. Done Include a "Section Headings Page Template" in the fcktemplates.xml file
  4. Done Handle link attributes available due to the new AugmentedWikiLinks feature.
  5. Mostly Done Update the JUnit tests for the XHtmlElementToWikiTranslator class and write one for the WysiwygEditingRenderer class once changes to them have become more final.
  6. Identify the items on the list of quirks that can be submitted to the FCKeditor project as a bug or as an enhancement request.
  7. The wikipage content within FCKeditor is now displayed properly with the new default template. It works despite the fact that FCKeditor is utilizing only the jspwiki.css file instead of both the jspwiki.css and the skin-specific skin.css files. The only limitation is that the wikipage content will always be displayed using the css styles from the PlainVanilla skin -- regardless of which skin you are actually using. See this post on the FCKeditor forums for more info about FCK and multiple CSS files.

Other#

HelpWanted: if anyone wants to volunteer to do any of the following, that'll be great!

Taking the time to test the current patches and reporting any serious problems is helpful too!

FCKeditor client-side javascript#

For the following items, we would want to use the FCKeditor API instead of hacking FCK because we don't want to maintain a customized distribution of FCKeditor in JSPWiki. Ideally, we should implement these customizations in a separate js file that can be placed directly underneath the $JSPWiki_Root/scripts/ directory.
  1. Replace the functionality of the 'Save' and the 'Preview' buttons on the FCK toolbar so that they would do the same thing as clicking on the 'Save' and 'Preview' buttons at the bottom of the Edit page.
  2. Utilize JSPWiki's JSON-RPC interface to provide wiki link suggestions for the URL textfield on the Insert Link pop-up window so that it works like Google Suggest. This one would be very nice to have. But not sure how feasible it is to implement without resorting to hacking FCK.
  3. Also, if you can confirm that a bug exists in a standalone instance of FCKeditor, please report the bug to the FCKeditor project (and the fix if available). It will not only help WYSIWYG editing with JSPWiki, but also potentially other Wiki's or content management systems that utilize FCKeditor.

Incorporate the FCKeditor.Java package.#

This server-side package allows a webserver to provide FCKeditor with a Link/Image Browser and also an Image Upload Utility.

This package might not be too useful since JSPWiki already has an attachment upload utility and users can also visit the "Page Index" link on the LeftMenu to see all the wiki pages they can link to.

However, this would be useful for JSPWiki setups where you want a separate image or file repository on the webserver. And these files don't have to be attached a particular wiki page.

One thing to observe is that the FCKeditor.Java package seems like it hasn't been updated for a little while, so it might not be in sync latest version of FCK.

Add integration support for TinyMCE#

TinyMCE is another popular open-source WYSIWYG XHTML editor that is probably as feature-rich as FCKeditor. The XHtmlElementToWikiTranslator class is not exclusive to FCKeditor integration. It should work with TinyMCE or other XHTML editors as well. We just need the right javascript configuration and a new TinyMCE.jsp file to support this editor.

It looks like CodeBeamer has been able to integrate it with their version of JSPWiki.

Also, it seems that some people are using TinyMCE with the allowHTML option, forgoing the html-to-wiki conversion and just saving the page in HTML instead. That method has its pro's and con's though such as the loss of plugins & ACL's, but gains the ability to use more HTML attributes & formatting.

Comments and Discussion#

Please also use this section to report any problems or issues.

It's great that you're working to integrate a WYSIWYG editor the right way: translating its output back and forth to wiki markup. I think that's how it should be. A big advantage is that the rest of the wiki system can see and process the content: it enables the "Referenced by" list and the "Table of contents" plugin, which are based on scanning the wiki markup syntax.

In the list of quirks, you wrote, "Even though using FCKeditor allows you to perform Wysiwyg-editing, you can still utilize wiki markup within it. For example, if you entered [Testlink] in FCKeditor, then 'Testlink' will become a link when the page is saved and viewed."

I don't think this is a quirk, I think this is a bug. I think the output of FCKeditor should go through a "washing" step where wiki markup characters are escaped, so I see what I typed - after all, that's what WYSIWYG stands for. WYSIWYG users don't want things they happen to put in brackets to appear as links!

The one exception to this rule is if I use bracket-brace (as in [{foo}]) to invoke a plug-in. There's no way for that to be WYSIWYG, so just let that go through the editing process untouched. But other instances of brackets, dashes, exclamation marks etc. should be escaped so they appear in the end product just like I typed them. That's my opinion. Thanks for listening.

--AnonymousCoward, 07-Apr-2007


Well, I've thought about this before and I pretty much agree with you that it's somewhat unintuitive for someone using a WYSIWYG editor to produce a link by typing in [TestLink]. This issue didn't fit under the other more serious categories, however it can be considered a "light bug".

Besides plugins, there are others types of jspwiki syntax such as filters, ACL, and wiki variables, which might not ever be WYSIWYG-editable.

At this time, my plan is to focus on tackling all the serious problems with html-to-wiki conversion first -- to the point where it'll be reasonably safe to edit wiki pages with FCK, and then address the workable issues on the quirks and limitation list.

--David Au, 09-Apr-2007


The latest patch is now included in 2.5.41, except for the HtmlStringToWikiTranslatorTest patch, which failed dismally (I have no idea what happened). Could you email me a new version of that patch?

--JanneJalkanen, 10-Apr-2007

Add new attachment

Only authorized users are allowed to upload new attachments.

List of attachments

Kind Attachment Name Size Version Date Modified Author Change note
png
IE5_Width_Bug.PNG 72.7 kB 1 07-Mar-2007 10:07 84.150.205.30
zip
WysiwygEditingPatch-latest.zip 46.1 kB 4 01-Jun-2007 04:05 David Au for JSPWiki 2.5.69
xml
jspwiki_module.xml 1.1 kB 1 22-Apr-2007 01:22 David Au
« This page (revision-35) was last changed on 15-Jun-2007 13:48 by David Au