Getting Started Tutorial
Setting up your Classpath
Before you can try any of the examples listed below you need to gather the JARs required for the XWiki Rendering so that you have them in your Java Classpath.
More specifically you'll need:
- The xwiki-rendering-api JAR.
- The Parser implementation JARS for the Syntax Parser you need (XWiki 2.0 syntax, Confluence, Creole, JSPWiki, etc):
- xwiki-rendering-syntax-wikimodel if you want to parse content written in one of the following syntaxes: Confluence, Creole, JSPWiki, MediaWiki.
- xwiki-rendering-syntax-xwiki2 if you want to parse content written in one of the following syntaxes: XWiki Syntax 2.0, XWiki Syntax 2.1.
- xwiki-rendering-syntax-xhtml if you want to parse content written in HTML or XHTML syntax.
- xwiki-rendering-syntax-doxia if you want to parse content written in TWiki syntax.
- xwiki-rendering-syntax-xwiki10 if you want to parse content written in XWiki Syntax 1.0.
- Since XWiki Rendering uses XWiki Component, you'll also need an XWiki Component Manager implementation. You could develop one that bridges to your own component system (Guice, Spring, etc) or you can use the xwiki-commons-component-default one that we provide.
In addition if you plan to use macros you'll need to add the following JARs:
- the xwiki-rendering-transformation-macro JAR
- the JARs for the macros you want to use (macros correspond to directories named xwikirendering-macro-*).
Note that not only you need the JARs mentioned above but you also need all the transitive dependencies required by those JARs.
Using Maven
Simply reference these JARs as dependencies from your own project. For example (note that haven't added a dependency on xwiki-rendering-api since the xwiki-rendering-parser-xwiki2 one gets it transitively):
<modelVersion>4.0.0</modelVersion>
<groupId>com.acme</groupId>
<artifactId>acme</artifactId>
<name>Acme</name>
<version>1.0-SNAPSHOT</version>
<packaging>jar</packaging>
<dependencies>
<dependency>
<groupId>org.xwiki.rendering</groupId>
<artifactId>xwiki-rendering-syntax-xwiki2</artifactId>
<version>3.0</version>
</dependency>
<dependency>
<groupId>org.xwiki.commons</groupId>
<artifactId>xwiki-commons-component-default</artifactId>
<version>3.0</version>
</dependency>
</dependencies>
</project>
Note that you can get the full transitive dependency list by typing mvn dependency:list or mvn dependency:tree and you can get an uberjar with mvn assembly:single -DdescriptorId=jar-with-dependencies.
If you want to use macros you'll also need to add dependencies for them. For example if you want to use the toc and html macros you'd write:
<modelVersion>4.0.0</modelVersion>
<groupId>com.acme</groupId>
<artifactId>acme</artifactId>
<name>Acme</name>
<version>1.0-SNAPSHOT</version>
<packaging>jar</packaging>
<dependencies>
<dependency>
<groupId>org.xwiki.rendering</groupId>
<artifactId>xwiki-rendering-syntax-xwiki2</artifactId>
<version>3.0</version>
</dependency>
<dependency>
<groupId>org.xwiki.commons</groupId>
<artifactId>xwiki-commons-component-default</artifactId>
<version>3.0</version>
</dependency>
<dependency>
<groupId>org.xwiki.rendering</groupId>
<artifactId>xwiki-rendering-transformation-macro</artifactId>
<version>3.0</version>
</dependency>
<dependency>
<groupId>org.xwiki.rendering</groupId>
<artifactId>xwiki-rendering-macro-toc</artifactId>
<version>3.0</version>
</dependency>
<dependency>
<groupId>org.xwiki.rendering</groupId>
<artifactId>xwiki-rendering-macro-html</artifactId>
<version>3.0</version>
</dependency>
</dependencies>
</project>
Using the XWiki Rendering Standalone JAR
If you're not using Maven then we've made available a Standalone JAR (snapshot versions available too) which contains all the classes in one JAR. However note that this standalone JAR is using Class relocation to try to prevent JAR version hell but under some special conditions it could fail (like running it in Google App Engine).
Initializing the XWiki Rendering
Once you have the correct classpath, all you need to be able to use XWiki Rendering is to create an instance of the XWiki Component Manager as follows (assuming you're using the default one we provide in xwiki-commons-component-default):
EmbeddableComponentManager componentManager = new EmbeddableComponentManager();
componentManager.initialize(this.getClass().getClassLoader());
Then you can use any of the examples defined below.
Note that XWiki Rendering supports 2 cases: if you're inside a wiki or not. If you're not inside a wiki for example the Link and Image Renderers will only handle links and images pointing to URLs and not handle them if they point to a document. To decide if it's inside a wiki or not, the code checks to see if it can find a component implementing the WikiModel interface (not to be confused with the WikiModel project that we use too). This interfaces exposes methods corresponding to features that any wiki should have. This allows you to integrate XWiki Rendering with your own wiki.
Examples
These examples are using XWiki Rendering 3.0 and beyond(you can download them here).
Render XWiki Syntax 2.0 content into XHTML
Take content written in XWiki Syntax 2.0 and generate XHTML as output.
Converter converter = componentManager.lookup(Converter.class);
// Convert input in XWiki Syntax 2.0 into XHTML. The result is stored in the printer.
WikiPrinter printer = new DefaultWikiPrinter();
converter.convert(new StringReader("This is **bold**"), Syntax.XWIKI_2_0, Syntax.XHTML_1_0, printer);
Assert.assertEquals("<p>This is <strong>bold</strong></p>", printer.toString());
Modify all Links to be displayed in italics
Parse content written in XWiki Syntax 2.0, look for all links and wrap them with italics and render the whole thing in XWiki Syntax 2.0.
Parser parser = componentManager.lookup(Parser.class, Syntax.XWIKI_2_0.toIdString());
XDOM xdom = parser.parse(new StringReader("This a [[link>MyPage]]"));
// Find all links and make them italic
for (Block block : xdom.getBlocks(new ClassBlockMatcher(LinkBlock.class), Block.Axes.DESCENDANT)) {
Block parentBlock = block.getParent();
Block newBlock = new FormatBlock(Collections.<Block>singletonList(block), Format.ITALIC);
parentBlock.replaceChild(newBlock, block);
}
// Generate XWiki 2.0 Syntax as output for example
WikiPrinter printer = new DefaultWikiPrinter();
BlockRenderer renderer = componentManager.lookup(BlockRenderer.class, Syntax.XWIKI_2_0.toIdString());
renderer.render(xdom, printer);
Assert.assertEquals("This a //[[link>MyPage]]//", printer.toString());
Execute Macros
Parse a content written in XWiki Syntax 2.0 and containing the Id Macro and generate XHTML.
XDOM xdom = parser.parse(new StringReader("{{id name=\"test\"/}}"));
// Execute the Macro Transformation to execute Macros.
Transformation transformation = componentManager.lookup(Transformation.class, "macro");
TransformationContext txContext = new TransformationContext(xdom, parser.getSyntax());
transformation.transform(xdom, txContext);
// Convert input in XWiki Syntax 2.0 into XHTML. The result is stored in the printer.
WikiPrinter printer = new DefaultWikiPrinter();
BlockRenderer renderer = componentManager.lookup(BlockRenderer.class, Syntax.XHTML_1_0.toIdString());
renderer.render(xdom, printer);
Assert.assertEquals("<div id=\"test\"></div>", printer.toString());
