RenderingModule
Version 24.1 by VincentMassol on 2009/04/03 14:30
Rendering Module
This module is in charge of converting textual input in a given syntax into some rendered output. It's used in XWiki notably for rendering pages in XHTML, for performing syntax conversions, for performing page refactorings and to provide users with access to the page's structured information directly inside their wiki pages using one of the supported scripting macros.
Features
- Parsers for multiple syntaxes
- Round trip between XWiki Syntax 2.0 and XHTML. This features allows us to have a strong WYSIWYG editor that doesn't loose information when editing wiki pages. It also allows us to import Office documents into XWiki without loosing information.
- Macro support.
- Ability to get the result of the parsing as an AST tree (called XDOM) which can then be used to get access to all structured elements from the flat text input.
- Supports wiki syntax in link labels even for syntaxes that don't support it.
- Automatic conversion from any of the supported input syntaxes to XWiki Syntax 2.0 or to XHTML.
General Architecture
- Parser: Parses some textual input in a given syntax and generate a XDOM object which is an AST representing the input into structured blocks.
- Renderer: Takes a XDOM as input and generates some output.
- Transformation: Takes some XDOM and modifies it to generate modified XDOM. One important Transformation registred by default is the MacroTransformation which looks for all Macro Blocks in the XDOM object and replaces them by blocks generated by the various Macros.
- Macro: Takes a Macro definition as input and generates XDOM Blocks.
Supported Syntaxes
Input Syntaxes:
- XWiki Syntax 1.0
- XWiki Syntax 2.0
- Confluence Syntax
- JSPWiki Syntax
- TWiki syntax
- Creole 1.0 Syntax
- XHTML and HTML Syntaxes
Output Syntaxes:
- XWiki Syntax 2.0
- XHTML
- Plain Text: Print all than can be rendered in a simple notepad-like editor such as words, special symbols and spaces. It also generates the link label and prints it when the link does not have any. Last it provides very basic formatting (e.g. separates paragraph with new lines and separate list items with new lines).
Example
// Parse xwiki 2.0 syntax
Parser parser = (Parser) componentManager.lookup(Parser.ROLE, "xwiki/2.0");
XDOM xdom = parser.parse(new StringReader("This is **bold** {{code language=\"java\"}}something{{/code}}"));
// Run macros
TransformationManager txManager = (TransformationManager) componentManager.lookup(TransformationManager.ROLE);
txManager.performTransformations(xdom, new Syntax(SyntaxType.XWIKI, "2.0"));
// Generate XHTML for example
WikiPrinter printer = new DefaultWikiPrinter();
Listener htmlListener = new XHTMLRenderer(printer);
// Perform the rendering
xdom.traverse(htmlListener);
assertEquals("<p>This is <strong>bold</strong> <!--startmacro:code|-|language=\"java\"|-|something-->"
+ "<span class=\"box code\">something</span><!--stopmacro--></p>", printer.toString());
Parser parser = (Parser) componentManager.lookup(Parser.ROLE, "xwiki/2.0");
XDOM xdom = parser.parse(new StringReader("This is **bold** {{code language=\"java\"}}something{{/code}}"));
// Run macros
TransformationManager txManager = (TransformationManager) componentManager.lookup(TransformationManager.ROLE);
txManager.performTransformations(xdom, new Syntax(SyntaxType.XWIKI, "2.0"));
// Generate XHTML for example
WikiPrinter printer = new DefaultWikiPrinter();
Listener htmlListener = new XHTMLRenderer(printer);
// Perform the rendering
xdom.traverse(htmlListener);
assertEquals("<p>This is <strong>bold</strong> <!--startmacro:code|-|language=\"java\"|-|something-->"
+ "<span class=\"box code\">something</span><!--stopmacro--></p>", printer.toString());
Adding a new Syntax
Adding support for a new syntax (i.e. the ability to write page contents using a new syntax) is as easy as implementing a Parser. To do so simply implement the Parser interface and register it as a component against the Component Manager.
Example:
public class MyParser implements Parser
{
private static final Syntax SYNTAX = new Syntax(SyntaxType.getSyntaxType("mysyntax"), "1.0");
public Syntax getSyntax()
{
return SYNTAX;
}
public XDOM parse(Reader source) throws ParseException
{
XDOM xdom = new XDOM(Collections.singletonList(new WordBlock("amazing")));
return xdom;
}
}
{
private static final Syntax SYNTAX = new Syntax(SyntaxType.getSyntaxType("mysyntax"), "1.0");
public Syntax getSyntax()
{
return SYNTAX;
}
public XDOM parse(Reader source) throws ParseException
{
XDOM xdom = new XDOM(Collections.singletonList(new WordBlock("amazing")));
return xdom;
}
}
Adding a new Macro
In order to implement a new Macro you'll need to write 2 classes:
- One that is a pure Java Bean and that represents the parameters allowed for that macro, including mandatory parameters, default values, parameter descriptions. An intance of this class will be automagically populated when the user calls the macro in wiki syntax.
- Another one that is the Macro itself. This class should implement the Macro interface or for simplicity extend AbstractMacro (it does more of the heavy lifting for you).
Example of a Macro Parameters class (notice the annotations):
public class MyMacroParameters
{
public enum MyEnum { VALUE1, VALUE2; }
private MyEnum myEnum;
private String param1;
@ParameterMandatory
@ParameterDescription("param explanation here")
public void setParam1(String param1)
{
this.param1 = param1;
}
public String getParam1()
{
return this.param1;
}
@ParameterDescription("explanations here")
public void setMyEnum(MyEnum myEnum)
{
this.myEnum = myEnum;
}
public MyEnum getMyEnum()
{
return this.myEnum;
}
}
{
public enum MyEnum { VALUE1, VALUE2; }
private MyEnum myEnum;
private String param1;
@ParameterMandatory
@ParameterDescription("param explanation here")
public void setParam1(String param1)
{
this.param1 = param1;
}
public String getParam1()
{
return this.param1;
}
@ParameterDescription("explanations here")
public void setMyEnum(MyEnum myEnum)
{
this.myEnum = myEnum;
}
public MyEnum getMyEnum()
{
return this.myEnum;
}
}
Example of a Macro class:
TODO
Adding a new Transformation
TODO
