Wiki source code of Getting Started Tutorial

Last modified by Vincent Massol on 2020/01/28 15:59
Show last authors
1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
4
5 = Setting up your Classpath =
6
7 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:
8
9 * The [[##xwiki-rendering-api## JAR>>http://repo2.maven.org/maven2/org/xwiki/rendering/xwiki-rendering-api/]].
10 * 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):
11 ** [[##xwiki-rendering-syntax-xwiki20##>>http://repo2.maven.org/maven2/org/xwiki/rendering/xwiki-rendering-syntax-xwiki20/]] for XWiki Syntax 2.0
12 ** [[##xwiki-rendering-syntax-xwiki21##>>http://repo2.maven.org/maven2/org/xwiki/rendering/xwiki-rendering-syntax-xwiki21/]] for XWiki Syntax 2.1
13 ** [[##xwiki-rendering-syntax-xwiki10##>>http://repo2.maven.org/maven2/org/xwiki/rendering/xwiki-rendering-syntax-xwiki10/]] for XWiki Syntax 1.0
14 ** [[##xwiki-rendering-syntax-confluence##>>http://repo2.maven.org/maven2/org/xwiki/rendering/xwiki-rendering-syntax-confluence/]] for Confluence markup
15 ** [[##xwiki-rendering-syntax-creole##>>http://repo2.maven.org/maven2/org/xwiki/rendering/xwiki-rendering-syntax-creole/]] for Creole markup
16 ** [[##xwiki-rendering-syntax-jspwiki##>>http://repo2.maven.org/maven2/org/xwiki/rendering/xwiki-rendering-syntax-jspwiki/]] for JSPWiki markup
17 ** [[##xwiki-rendering-syntax-mediawiki##>>http://repo2.maven.org/maven2/org/xwiki/rendering/xwiki-rendering-syntax-mediawiki/]] for MediaWiki markup
18 ** [[##xwiki-rendering-syntax-xhtml##>>http://repo2.maven.org/maven2/org/xwiki/rendering/xwiki-rendering-syntax-xhtml/]] for XHTML syntax
19 ** [[##xwiki-rendering-syntax-html##>>http://repo2.maven.org/maven2/org/xwiki/rendering/xwiki-rendering-syntax-html/]] for HTML 4.01 syntax
20 ** [[##xwiki-rendering-syntax-twiki##>>http://repo2.maven.org/maven2/org/xwiki/rendering/xwiki-rendering-syntax-twiki/]] for TWiki syntax
21 ** [[##xwiki-rendering-syntax-docbook##>>http://repo2.maven.org/maven2/org/xwiki/rendering/xwiki-rendering-syntax-docbook/]] for DocBook syntax
22 ** [[##xwiki-rendering-syntax-plain##>>http://repo2.maven.org/maven2/org/xwiki/rendering/xwiki-rendering-syntax-plain/]] for Plain text
23 ** [[##xwiki-rendering-syntax-tex##>>http://repo2.maven.org/maven2/org/xwiki/rendering/xwiki-rendering-syntax-tex/]] for LaTeX
24 ** [[##xwiki-rendering-syntax-annotatedxhtml##>>http://repo2.maven.org/maven2/org/xwiki/rendering/xwiki-rendering-syntax-annotatedxhtml/]] for Annotated XHTML
25 ** [[##syntax-markdown-markdown11##>>http://maven.xwiki.org/releases/org/xwiki/contrib/markdown/syntax-markdown-markdown11/]] For [[Markdown 1.1>>extensions:Extension.Markdown Syntaxes]] (and [[##syntax-markdown-markdown10##>>http://maven.xwiki.org/releases/org/xwiki/contrib/markdown/syntax-markdown-markdown10/]] For [[Markdown 1.0>>extensions:Extension.Markdown Syntaxes]])
26 ** ... and more
27 * Since XWiki Rendering uses [[XWiki Components>>extensions:Extension.Component Module]], you'll also need the Component Manager API JAR ([[##xwiki-commons-component-api##>>http://repo2.maven.org/maven2/org/xwiki/commons/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##>>http://repo2.maven.org/maven2/org/xwiki/commons/xwiki-commons-component-default/]] one that we provide.
28
29 In addition if you plan to use macros you'll need to add the following JARs:
30
31 * the [[##xwiki-rendering-transformation-macro## JAR>>http://repo2.maven.org/maven2/org/xwiki/rendering/xwiki-rendering-transformation-macro/]]
32 * the [[JARs for the macros you want to use>>http://repo2.maven.org/maven2/org/xwiki/rendering/]] (macros correspond to directories named ##xwiki-rendering-macro-*##).
33
34 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:
35 * 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.
36 * The ##logback-classic## JAR which sends SLF4J calls to Logback.
37
38 Of course you can choose to use [[any of the other SLF4J bindings available>>http://www.slf4j.org/manual.html]] (see [[diagram>>http://www.slf4j.org/images/concrete-bindings.png]]). You can also decide to not provide a binding in which cases logs will just be ignored.
39
40 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.
41
42 == Using Maven ==
43
44 {{info}}The XWiki Rendering JARs are available in the [[Maven Central Repository>>http://repo2.maven.org/maven2/org/xwiki/rendering/]] since XWiki Rendering 3.2 Milestone 3.{{/info}}
45
46 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):
47
48 {{code language="xml"}}
49 <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">
50 <modelVersion>4.0.0</modelVersion>
51 <groupId>com.acme</groupId>
52 <artifactId>acme</artifactId>
53 <name>Acme</name>
54 <version>1.0-SNAPSHOT</version>
55 <packaging>jar</packaging>
56 <dependencies>
57 <dependency>
58 <groupId>org.xwiki.rendering</groupId>
59 <artifactId>xwiki-rendering-syntax-xwiki21</artifactId>
60 <version>4.1.3</version>
61 </dependency>
62 <dependency>
63 <groupId>org.xwiki.commons</groupId>
64 <artifactId>xwiki-commons-component-default</artifactId>
65 <version>4.1.3</version>
66 </dependency>
67 <!-- Logging with Logback -->
68 <dependency>
69 <groupId>ch.qos.logback</groupId>
70 <artifactId>logback-classic</artifactId>
71 <scope>runtime</scope>
72 </dependency>
73 <dependency>
74 <groupId>org.slf4j</groupId>
75 <artifactId>jcl-over-slf4j</artifactId>
76 <scope>runtime</scope>
77 </dependency>
78 </dependencies>
79 </project>
80 {{/code}}
81
82 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##.
83
84 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):
85
86 {{code language="xml"}}
87 <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">
88 <modelVersion>4.0.0</modelVersion>
89 <groupId>com.acme</groupId>
90 <artifactId>acme</artifactId>
91 <name>Acme</name>
92 <version>1.0-SNAPSHOT</version>
93 <packaging>jar</packaging>
94 <dependencies>
95 <dependency>
96 <groupId>org.xwiki.rendering</groupId>
97 <artifactId>xwiki-rendering-syntax-xwiki21</artifactId>
98 <version>4.1.3</version>
99 </dependency>
100 <dependency>
101 <groupId>org.xwiki.commons</groupId>
102 <artifactId>xwiki-commons-component-default</artifactId>
103 <version>4.1.3</version>
104 </dependency>
105 <dependency>
106 <groupId>org.xwiki.rendering</groupId>
107 <artifactId>xwiki-rendering-macro-toc</artifactId>
108 <version>4.1.3</version>
109 </dependency>
110 <dependency>
111 <groupId>org.xwiki.rendering</groupId>
112 <artifactId>xwiki-rendering-macro-html</artifactId>
113 <version>4.1.3</version>
114 </dependency>
115 <!-- Logging with Logback -->
116 <dependency>
117 <groupId>ch.qos.logback</groupId>
118 <artifactId>logback-classic</artifactId>
119 <scope>runtime</scope>
120 </dependency>
121 <dependency>
122 <groupId>org.slf4j</groupId>
123 <artifactId>jcl-over-slf4j</artifactId>
124 <scope>runtime</scope>
125 </dependency>
126 </dependencies>
127 </project>
128 {{/code}}
129
130 == Using the XWiki Rendering Standalone ZIP ==
131
132 {{info}}Prior to XWiki 4.4M1 we used to distribute a Standalone JAR which was [[shading>>http://maven.apache.org/plugins/maven-shade-plugin/]] 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.{{/info}}
133
134 If you're not using Maven then we've made available a [[Standalone ZIP>>http://maven.xwiki.org/releases/org/xwiki/rendering/xwiki-rendering-standalone/]] ([[snapshot versions available too>>http://maven.xwiki.org/snapshots/org/xwiki/rendering/xwiki-rendering-standalone/]]) which contains all the JARs in one ZIP. You'll need to take those JARs and make them available in your runtime CLASSPATH.
135
136 = Initializing the XWiki Rendering =
137
138 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>>http://repo2.maven.org/maven2/org/xwiki/commons/xwiki-commons-component-default/]]):
139
140 {{code language="java"}}
141 // Initialize Rendering components and allow getting instances
142 EmbeddableComponentManager componentManager = new EmbeddableComponentManager();
143 componentManager.initialize(this.getClass().getClassLoader());
144 {{/code}}
145
146 Then you can use any of the examples defined below.
147
148 {{id name="examples"/}}
149
150 = Examples =
151
152 These examples should work with XWiki Rendering 4.1 and beyond (you can download them {{scm project="xwiki-rendering" path="xwiki-rendering-standalone/src/test/java/org/xwiki/rendering/example"}}here{{/scm}}).
153
154 == Render XWiki Syntax 2.1 content into XHTML ==
155
156 Take content written in XWiki Syntax 2.1 and generate XHTML as output.
157
158 {{code language="java"}}
159 // Use the Converter component to convert between one syntax to another.
160 Converter converter = componentManager.getInstance(Converter.class);
161
162 // Convert input in XWiki Syntax 2.1 into XHTML. The result is stored in the printer.
163 WikiPrinter printer = new DefaultWikiPrinter();
164 converter.convert(new StringReader("This is **bold**"), Syntax.XWIKI_2_1, Syntax.XHTML_1_0, printer);
165
166 Assert.assertEquals("<p>This is <strong>bold</strong></p>", printer.toString());
167 {{/code}}
168
169 == Modify all Links to be displayed in italics ==
170
171 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.
172
173 {{code language="java"}}
174 // Parse XWiki 2.1 Syntax using a Parser.
175 Parser parser = componentManager.getInstance(Parser.class, Syntax.XWIKI_2_1.toIdString());
176 XDOM xdom = parser.parse(new StringReader("This a [[link>MyPage]]"));
177
178 // Find all links and make them italic
179 for (Block block : xdom.getBlocks(new ClassBlockMatcher(LinkBlock.class), Block.Axes.DESCENDANT)) {
180 Block parentBlock = block.getParent();
181 Block newBlock = new FormatBlock(Collections.<Block>singletonList(block), Format.ITALIC);
182 parentBlock.replaceChild(newBlock, block);
183 }
184
185 // Generate XWiki 2.1 Syntax as output for example
186 WikiPrinter printer = new DefaultWikiPrinter();
187 BlockRenderer renderer = componentManager.getInstance(BlockRenderer.class, Syntax.XWIKI_2_1.toIdString());
188 renderer.render(xdom, printer);
189
190 Assert.assertEquals("This a //[[link>MyPage]]//", printer.toString());
191 {{/code}}
192
193 == Execute Macros ==
194
195 Parse a content written in XWiki Syntax 2.1 and containing the Id Macro and generate XHTML.
196
197 {{code language="java"}}
198 Parser parser = componentManager.getInstance(Parser.class, Syntax.XWIKI_2_1.toIdString());
199 XDOM xdom = parser.parse(new StringReader("{{id name=\"test\"/}}"));
200
201 // Execute the Macro Transformation to execute Macros.
202 Transformation transformation = componentManager.getInstance(Transformation.class, "macro");
203 TransformationContext txContext = new TransformationContext(xdom, parser.getSyntax());
204 transformation.transform(xdom, txContext);
205
206 // Convert input in XWiki Syntax 2.1 into XHTML. The result is stored in the printer.
207 WikiPrinter printer = new DefaultWikiPrinter();
208 BlockRenderer renderer = componentManager.getInstance(BlockRenderer.class, Syntax.XHTML_1_0.toIdString());
209 renderer.render(xdom, printer);
210
211 Assert.assertEquals("<div id=\"test\"></div>", printer.toString());
212 {{/code}}
213
214 == Miscellaneous ==
215
216 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 {{scm project="xwiki-rendering" path="xwiki-rendering-api/src/main/java/org/xwiki/rendering/wiki/WikiModel.java" raw="true"}}WikiModel interface{{/scm}}. This interfaces exposes methods corresponding to features that any wiki should have. This allows you to integrate XWiki Rendering with your own wiki.

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

  • Powered by XWiki 15.10.8-node2. Hosted and managed by XWiki SAS

Get Connected