This page just copied from [JSPWiki Blog|] [entry|] - I think it is useful to keep its copy here.


JSPWiki 2.3 includes a new RenderingManager, which replaces the old TranslatorReader system. The rendering flow has also changed from being a simple "String-in, String-out" into a "String-in,DOM-out,cache-DOM,String-out". This was done so that we could cache at least parts of the parsed data. We could've also stored the XHTML, but then we lose any ability to do cool DOM manipulation before rendering.

There's a new API called MarkupParser, which has one concrete subclass called JSPWikiMarkupParser. The MarkupParser.parse() method creates a DOM tree, which is almost-but-not-quite XHTML.

The resulting DOM tree has two special elements in it, PluginContent and VariableContent. These store the parsed versions of the arguments, but at this point the plugins are not yet executed, nor are the variable values fetched.

The actual rendering is done by instantiating a WikiRenderer instance. There are currently two renderers, CleanTextRenderer and XHTMLRenderer. The former rips away all markup and produces something resembling plain text, whereas the latter should produce XHTML. During the rendering phase the PluginContent and the VariableContent classes (which are DOM components) are asked to render themselves, which in turn means that they call the respective methods in PluginManager and VariableManager to figure out the real content.

Take a look at RenderingManager to understand the process better. You can also look at WikiEngine.textToHTML() internal method.

Here's a bit of sample code to show you how it works, though RenderingManager complicates things a bit by caching the actual document using OSCache.

public String render( WikiContext context, String pagedata )
    // Create new parser and parse the content into a WikiDocument

    MarkupParser parser = new JSPWikiMarkupParser( context, 
                                                   new StringReader(pagedata) );
    WikiDocument doc = parser.parse();

    // WikiDocument is a DOM Document, so you could manipulate it 
    // here in any way you want, e.g. with XPath

    // We now create a new WikiRenderer
    WikiRenderer rend = new XHTMLRenderer( context, doc );

    //  Now, do the rendering.
    return rend.getString();