Out of all the things that I've had a hand working on for Clearspace (and that's a lot) the one that I've found to be the most challenging and frustrating to implement would have to be the new wiki syntax support. As many of you are aware wiki syntax is a very useful (and fast) way to markup text to create things like lists, tables, links and styles without having to type html. We looked at a variety of existing wiki markup syntaxes and decided on a syntax that was as common as possible. It's very fast to use once you've know the syntax - and potentially a deal breaker to new users who don't want or have the time to learn the syntax no matter how simple it may be. Thus in Clearspace we decided it would be best to allow documents to be created in one of two ways - using a graphical editor (IE or Firefox) or a plain text editor with preview functionality.


[existing wiki markup syntaxes|http://jivesoftware.com/blog/wp-content/uploads/2007/01/create.png]


Since users will have the ability to switch between the two editors we needed a way to convert the html content generated from the GUI editor into the wiki syntax supported by the plain text editor and vice versa. It was this requirement that proved to be the source of many frustrating hours stepping through code trying to isolate yet another bug.


Not surprisingly we couldn't find an open source wiki syntax implementation that met all of the requirements so we had to roll our own. Our existing rendering solution found in Jive Forums proved not to be up to the task so we had to design one from scratch to meet the new requirements. Before that though we had to evaluate and test a variety of html parsers to facilitate the conversion from the html syntax generated from the GUI editor back into the wiki syntax. We settled on a flexible and extremely fast parser from the open source Sitemesh project which we modified slightly to suit the requirements. Spending the time to research and choose the right tools proved to be a life saver - it allowed us to handle the "wikification" of the html in a very clean manner.


Once the tools were chosen we created the API for the new render system and started writing the implementation. As you can see from the following code the general use case is fairly straightforward for generating html from the stored wikified text:

RenderManager rManager = jiveContext.getRenderManager();
String htmlText = rManager.render(doc, RenderType.DOCUMENT_BODY, wikifiedText);

Going the other way from html to wiki text requires a bit more work but is also fairly straightforward:

RenderStrategy strategy = new RenderStrategy(
RenderTarget.TARGET_PLAIN_TEXT, RenderStrategy.RENDER_ALL);
RenderManager rManager = jiveContext.getRenderManager();
String wikifiedText = rManager.render(doc,
RenderType.DOCUMENT_BODY, strategy, htmlText);

Getting it all right though required a lot of time and a large number of test cases to work out the bugs. Without these test cases I'm sure some of the more subtle bugs that cropped up would never have been caught. I'm very proud of the outcome of all this work - it's going to be a great feature as well as the basis of quite a bit of new functionality in future releases of Clearspace.