Getting Started Tutorial

Last modified by Vincent Massol on 2020/01/28 15:59

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:

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

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

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

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

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

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

Prior to XWiki 4.4M1 we used to distribute a Standalone JAR which was shading dependencies. We've removed it in 4.4M1 since it could lead to issues as shading isn't a perfect process (some dependencies couldn't be shaded for example). We thus believe it's better that you take care of integrating the various dependencies required by XWiki Rendering when you use it in your own project.

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

// 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.

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.

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

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

Parser parser = componentManager.getInstance(Parser.class, Syntax.XWIKI_2_1.toIdString());
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.

Tags:
    
  • Powered by XWiki 14.10.18-node1. Hosted and managed by XWiki SAS

Get Connected