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. There are various ways to do, as explained in the sections below but here's an explanation of the various JARs available and what they mean. You'll need:
- The xwiki-rendering-api JAR.
- The Parser and Renderer JARs for the Syntaxes you wish to parse from/render to (XWiki Syntax 2.0, XWiki Syntax 2.1, Confluence, Creole, JSPWiki, etc):
- xwiki-rendering-syntax-xwiki20 for XWiki Syntax 2.0
- xwiki-rendering-syntax-xwiki21 for XWiki Syntax 2.1
- xwiki-rendering-syntax-xwiki10 for XWiki Syntax 1.0
- xwiki-rendering-syntax-confluence for Confluence markup
- xwiki-rendering-syntax-creole for Creole markup
- xwiki-rendering-syntax-jspwiki for JSPWiki markup
- xwiki-rendering-syntax-mediawiki for MediaWiki markup
- xwiki-rendering-syntax-xhtml for XHTML syntax
- xwiki-rendering-syntax-html for HTML 4.01 syntax
- xwiki-rendering-syntax-twiki for TWiki syntax
- xwiki-rendering-syntax-docbook for DocBook syntax
- xwiki-rendering-syntax-plain for Plain text
- xwiki-rendering-syntax-tex for LaTeX
- ... and more
- Since XWiki Rendering uses XWiki Components, you'll also need the Component Manager API JAR (xwiki-commons-component-api and a 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-*).
Last, you'll need to define a SLF4J binding in your classpath. XWiki Rendering uses the SLF4J API. For example to direct all logs to Logback you'll need:
- The jcl-over-slf4j JAR which tells all JCL calls to be sent to SLF4J. Since XWiki Rendering uses some third party libraries using JCL you'll need this.
- The logback-classic JAR which sends SLF4J calls to Logback.
Of course you can choose to use any of the other SLF4J bindings available (see diagram). You can also decide to not provide a binding in which cases logs will just be ignored.
Note that not only you need the JARs mentioned above but you also need all the transitive dependencies required by those JARs... If you're using Maven then you'll get those dependencies out of the box and if you use the Standalone ZIP you'll get them in the ZIP.
Using Maven
Simply reference the JARs as dependencies from your own project. For example (note that we haven't added a dependency on xwiki-rendering-api nor on xwiki-commons-component-api since the xwiki-rendering-parser-xwiki21 and the xwiki-common-component-default dependencies get them 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-xwiki21</artifactId>
<version>4.1.3</version>
</dependency>
<dependency>
<groupId>org.xwiki.commons</groupId>
<artifactId>xwiki-commons-component-default</artifactId>
<version>4.1.3</version>
</dependency>
<!-- Logging with Logback -->
<dependency>
<groupId>ch.qos.logback</groupId>
<artifactId>logback-classic</artifactId>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>jcl-over-slf4j</artifactId>
<scope>runtime</scope>
</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 (note that we haven't added a dependency on xwiki-rendering-transforation-macro since the macro dependencies get 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-xwiki21</artifactId>
<version>4.1.3</version>
</dependency>
<dependency>
<groupId>org.xwiki.commons</groupId>
<artifactId>xwiki-commons-component-default</artifactId>
<version>4.1.3</version>
</dependency>
<dependency>
<groupId>org.xwiki.rendering</groupId>
<artifactId>xwiki-rendering-macro-toc</artifactId>
<version>4.1.3</version>
</dependency>
<dependency>
<groupId>org.xwiki.rendering</groupId>
<artifactId>xwiki-rendering-macro-html</artifactId>
<version>4.1.3</version>
</dependency>
<!-- Logging with Logback -->
<dependency>
<groupId>ch.qos.logback</groupId>
<artifactId>logback-classic</artifactId>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>jcl-over-slf4j</artifactId>
<scope>runtime</scope>
</dependency>
</dependencies>
</project>
Using the XWiki Rendering Standalone ZIP
If you're not using Maven then we've made available a Standalone ZIP (snapshot versions available too) which contains all the JARs in one ZIP. You'll need to take those JARs and make them available in your runtime CLASSPATH.
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.
Examples
These examples should work with XWiki Rendering 4.1 and beyond (you can download them here).
Render XWiki Syntax 2.1 content into XHTML
Take content written in XWiki Syntax 2.1 and generate XHTML as output.
Converter converter = componentManager.getInstance(Converter.class);
// Convert input in XWiki Syntax 2.1 into XHTML. The result is stored in the printer.
WikiPrinter printer = new DefaultWikiPrinter();
converter.convert(new StringReader("This is **bold**"), Syntax.XWIKI_2_1, 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.1, look for all links and wrap them with italics and render the whole thing in XWiki Syntax 2.1.
Parser parser = componentManager.getInstance(Parser.class, Syntax.XWIKI_2_1.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.1 Syntax as output for example
WikiPrinter printer = new DefaultWikiPrinter();
BlockRenderer renderer = componentManager.getInstance(BlockRenderer.class, Syntax.XWIKI_2_1.toIdString());
renderer.render(xdom, printer);
Assert.assertEquals("This a //[[link>MyPage]]//", printer.toString());
Execute Macros
Parse a content written in XWiki Syntax 2.1 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.getInstance(Transformation.class, "macro");
TransformationContext txContext = new TransformationContext(xdom, parser.getSyntax());
transformation.transform(xdom, txContext);
// Convert input in XWiki Syntax 2.1 into XHTML. The result is stored in the printer.
WikiPrinter printer = new DefaultWikiPrinter();
BlockRenderer renderer = componentManager.getInstance(BlockRenderer.class, Syntax.XHTML_1_0.toIdString());
renderer.render(xdom, printer);
Assert.assertEquals("<div id=\"test\"></div>", printer.toString());
Miscellaneous
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. This interfaces exposes methods corresponding to features that any wiki should have. This allows you to integrate XWiki Rendering with your own wiki.
