Getting Started Tutorial

Version 20.3 by Vincent Massol on 2012/09/08 19:47

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:

In addition if you plan to use macros you'll need to add the following JARs:

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 JAR you'll get them in that JAR.

Using Maven

The XWiki Rendering JARs are available in the Maven Central Repository since XWiki Rendering 3.2 Milestone 3.

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):

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
 <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>4.1.3</version>
   </dependency>
   <dependency>
     <groupId>org.xwiki.commons</groupId>
     <artifactId>xwiki-commons-component-default</artifactId>
     <version>4.1.3</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:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
 <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>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-transformation-macro</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>
 </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):

// Initialize Rendering components and allow getting instances
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. 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 should work with XWiki Rendering 3.2 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.

// Use the Converter component to convert between one syntax to another.
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.

// Parse XWiki 2.0 Syntax using a Parser.
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.

Parser parser = componentManager.lookup(Parser.class, Syntax.XWIKI_2_0.toIdString());
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());
  • Powered by XWiki 15.10.8-node1. Hosted and managed by XWiki SAS

Get Connected