Wiki source code of Getting Started Tutorial
Last modified by Vincent Massol on 2020/01/28 15:59
Show last authors
author | version | line-number | content |
---|---|---|---|
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. |