Show last authors
1 1 Creating Plugins
2
3 Plugins are quite handy when you want to interact with third-party code from the Velocity context. Check the [Code Zone>Code.WebHome] for a list of existing plugins.
4
5 Here are steps to develop a Hello World plugin and more.
6
7 #toc("" "" "")
8
9 1.1 The plugin architecture
10
11 Basically, a plugin is composed of two parts:
12
13 * The *plugin* itself: it must implement the [XWikiPluginInterface>http://fisheye2.cenqua.com/browse/xwiki/xwiki-platform/core/trunk/xwiki-core/src/main/java/com/xpn/xwiki/plugin/XWikiPluginInterface.java] interface. For simplicity you can also extends the [XWikiDefaultPlugin>http://fisheye2.cenqua.com/browse/xwiki/xwiki-platform/core/trunk/xwiki-core/src/main/java/com/xpn/xwiki/plugin/XWikiDefaultPlugin.java] class which is an adapter to the XWikiPluginInterface. The plugin contains the core functions of your plugin. They will not be accessible from scripting (without programming rights).
14 * Its *API*: it should extend the [Api>http://fisheye2.cenqua.com/browse/xwiki/xwiki-platform/core/trunk/xwiki-core/src/main/java/com/xpn/xwiki/api/Api.java] class. Will contain all the public methods, accessible from scripting.
15
16 Although you can write the functionality inside the API, this is not recommended; the plugin functionality is written in the ~~hidden~~ part ("hidden" as in "not publicly accessible"), and the API can filter the access to privileged users, beautify the method names or parameter list, etc., or simply forward the call to the hidden part.
17
18 1.1.1 Plugin lifecycle
19
20 When the XWiki engine is initialized, the Plugin Manager calls the class constructor for all the enabled plugins (classes implementing the com.xpn.xwiki.plugin.XWikiPluginInterface). For each plugin the class constructor is called only once, and the plugin manager calls the <code>init(XWikiContext)</code> method of the plugin. Each time a plugin is referenced by a Velocity script, for example, when you call a method served by the plugin API:
21 {code}
22 #set($helloWorldText = "$xwiki.helloworld.hello()")
23 {code}
24 or when you ask the XWiki instance for the plugin API object :
25 {code}
26 #set($pluginObject = $xwiki.getPlugin("helloworld")
27
28 #* the name given as argument of getPlugin() should be
29 the one returned by the getName() method of the Plugin class.
30 *#
31 {code}
32 XWiki calls the <code>getPluginApi()</code> method for the plugin's instance, which itself creates an instance of the class <code>com.xpn.xwiki.plugin.PluginApi</code>. This is why you should not store things in fields of the class extending <code>PluginApi</code> in your plugin, since the usual behavior for the <code>getPluginApi()</code> method is to create a new instance of the <code>PluginApi</code> class every time Velocity needs to access the API for your plugin. This is not true if you store the returned plugin API in a variable, for example:
33 {code}
34 #set($myPluginApi = $xwiki.helloworld)
35 {code}
36 The <code>myPluginApi</code> variable will point to the same object as long as the variable exists. You can declare fields in your plugin class instead, since there is only one instance of this class, whose lifecycle spans over the entire servlet's lifecycle.
37
38 1.1 Write the plugin
39
40 First of all let's *declare our plugin class*:
41
42 {code:java}
43 public class HelloWorldPlugin extends XWikiDefaultPlugin {...}
44 {code}
45
46 Then let's *implement the needed constructor*:
47
48 {code:java}
49 public HelloWorldPlugin(String name, String className, XWikiContext context) {
50 super(name,className,context);
51 }{code}
52
53 *Set a method to get the name of the plugin*. That's how we will call it from Velocity. For example, we will be able to use our plugin with \$xwiki.helloworld.myMethod()
54
55 {code:java}
56 public String getName() {
57 return "helloworld";
58 }
59 {code}
60
61 *Write a method to get the plugin API*. Don't forget to cast the plugin.
62
63 {code:java}
64 public Api getPluginApi(XWikiPluginInterface plugin, XWikiContext context) {
65 return new HelloWorldPluginApi((HelloWorldPlugin) plugin, context);
66 }
67 {code}
68
69 *Overload the cache flush method* (optional)
70
71 {code:java}
72 public void flushCache() {}
73 {code}
74
75 Optionally, we can *create a [log4j>http://logging.apache.org/log4j/docs/index.html] instance* for the plugin:
76 {code:java}
77 private static final Log LOG = LogFactory.getLog(HelloWorldPlugin.class);
78 {code}
79
80 This is very useful for debugging. The logger could be invoked from any method like:
81 {code:java}
82 public String getName() {
83 LOG.debug("Entered method getName");
84 return "helloworld";
85 }
86 {code}
87
88 Then, to enable logging at a specific level for your plugin, edit webapps/xwiki/WEB-INF/classes/log4j.properties and add, for example:
89 {code}
90 log4j.com.xpn.xwiki.plugin.helloworld.HelloWorldPlugin=debug
91 {code}
92
93 You'll then be able to follow your plugin's log messages by tailing your xwiki.log file. Note that you'll need to restart the app server for changes to log4j.properties to take effect.
94
95 And finally, *write a method to init the context*.
96 {code:java}
97 public void init(XWikiContext context) {
98 super.init(context);
99 }
100 {code}
101
102 Here is the code you should have now:
103
104 {code:java}
105 package com.xpn.xwiki.plugin.helloworld;
106
107 import org.apache.commons.logging.Log;
108 import org.apache.commons.logging.LogFactory;
109
110 import com.xpn.xwiki.XWikiContext;
111 import com.xpn.xwiki.api.Api;
112 import com.xpn.xwiki.plugin.XWikiDefaultPlugin;
113 import com.xpn.xwiki.plugin.XWikiPluginInterface;
114
115 public class HelloWorldPlugin extends XWikiDefaultPlugin {
116
117 private static Log LOG = LogFactory.getLog(HelloWorldPlugin.class);
118
119 public HelloWorldPlugin(String name, String className, XWikiContext context) {
120 super(name,className,context);
121 init(context);
122 }
123
124 public String getName() {
125 return "helloworld";
126 }
127
128 public Api getPluginApi(XWikiPluginInterface plugin, XWikiContext context) {
129 return new HelloWorldPluginApi((HelloWorldPlugin) plugin, context);
130 }
131
132 public void flushCache() {
133 }
134
135 public void init(XWikiContext context) {
136 super.init(context);
137 }
138 }
139 {code}
140
141
142 1.1 Write the API
143
144 Let's write the API class which will contain the methods that can be called from Velocity.
145
146 Firstly, *class declaration*:
147
148 {code:java}
149 public class HelloWorldPluginApi extends Api {...}
150 {code}
151
152 Then, *plugin field declaration*. It will let our API to call backend methods.
153
154 {code:java}
155 private HelloWorldPlugin plugin;
156 {code}
157
158 *Required constructor*
159
160 {code:java}
161 public HelloWorldPluginApi(HelloWorldPlugin plugin, XWikiContext context) {
162 super(context);
163 setPlugin(plugin);
164 }
165 {code}
166
167 Classic *plugin getter and setter*. These methods are not required at all, on the contrary, they should not be defined, unless they are really needed.
168
169 {code:java}
170 public HelloWorldPlugin getPlugin(){
171 return (hasProgrammingRights() ? plugin : null);
172 // Uncomment for allowing unrestricted access to the plugin
173 // return plugin;
174 }
175
176 public void setPlugin(HelloWorldPlugin plugin) {
177 this.plugin = plugin;
178 }
179 {code}
180
181 Here is the key *API method*. Here is the one that you will call from velocity. You can define any number of them and call your plugin backend from them.
182 {code:java}
183 public String hello() {
184 return "Hello World!";
185 }
186 {code}
187 You can also have <code>void</code> methods :
188 {code:java}
189 public void updatePage() {
190 //...
191 }
192 {code}
193
194 Here is the complete API code:
195
196 {code:java}
197 package com.xpn.xwiki.plugin.helloworld;
198
199 import com.xpn.xwiki.XWikiContext;
200 import com.xpn.xwiki.api.Api;
201
202 public class HelloWorldPluginApi extends Api {
203 private HelloWorldPlugin plugin;
204
205 public HelloWorldPluginApi(HelloWorldPlugin plugin, XWikiContext context) {
206 super(context);
207 setPlugin(plugin);
208 }
209
210 public HelloWorldPlugin getPlugin(){
211 return (hasProgrammingRights() ? plugin : null);
212 // Uncomment for allowing unrestricted access to the plugin
213 // return plugin;
214 }
215
216 public void setPlugin(HelloWorldPlugin plugin) {
217 this.plugin = plugin;
218 }
219
220 public String hello() {
221 return "Hello World!";
222 }
223
224 public void updatePage() {
225 //...
226 }
227 }
228 {code}
229
230
231
232 1.1 Integrate the plugin in your XWiki installation
233
234 First of all you need to *copy your classes to the XWiki servlet installation*. Don't forget to be consistent with your package tree. With a Linux Tomcat installation, you do this. You should be able to reproduce these steps easily in your favourite operating system.
235
236 {code}
237 go to the tomcat installation folder (or whatever container you are using)
238 $ cd myTomcatInstallation
239 go to the xwiki WEB-INF directory
240 $ cd webapps/xwiki/WEB-INF
241 create the classes tree, compliant to the "package" directive that you set in the plugin source files
242 $ mkdir classes/com/xpn/xwiki/plugin/helloworld
243 And then copy the class files to this location
244 $ cp myPluginsFolder/HelloWorldPlugin.class classes/com/xpn/xwiki/plugin/helloworld
245 $ cp myPluginsFolder/HelloWorldPluginAPI.class classes/com/xpn/xwiki/plugin/helloworld
246 {code}
247
248 Alternatively, you can jar up your classes (with the required directory structure) and place the jar in webapps/xwiki/WEB-INF/lib. This is a more agreeable way of distributing your plugin.
249
250 Finally you need to *register your plugin* in the ~~xwiki.cfg~~ file located in ~~WEB-INF~~
251
252 {code}
253 xwiki.plugins=com.xpn.xwiki.plugin.calendar.CalendarPlugin,\
254 ...,\
255 com.xpn.xwiki.plugin.helloworld.HelloWorldPlugin
256 {code}
257
258 Don't forget to restart your servlet container after this. XWiki has to re-read the configuration file.
259
260 1.1 Use the plugin
261
262 Here is the simplest part. Edit a page and write:
263 {code}
264 My plugin says: "$xwiki.helloworld.hello()"
265 {code}
266 It should be rendered like this
267 {code}
268 My plugin says: "Hello World!"
269 {code}
270 You can also call <CODE>void</code> methods specified in the API class :
271 {code}
272 $xwiki.helloworld.updatePage()
273 The page has been updated.
274 {code}
275
276
277 1.1 Examples
278
279 Here are some examples of what you can do with plugins.
280 You should actually check the [API Guide>DevGuide.APIGuide], since it contains examples on how to use the XWiki API. The examples in the API Guide are written in Velocity, and are thus easily applicable to Java.
281
282 1.1.1 Accessing pages, objects and object properties from pages
283
284 This is something you can do from Velocity as well, but when you need to perform complex treatments on your XWiki pages, you need to do it from a java plugin.
285
286 The class representing a document in the XWiki Java model is <code>com.xpn.xwiki.doc.XWikiDocument</code>.
287 The class representing an object in the XWiki Java model is <code>com.xpn.xwiki.objects.BaseObject</code>.
288
289 If you need to access existing documents from your plugin, you use the XWiki class, <code>com.xpn.xwiki.XWiki</code>, which has a <code>getDocument()</code> method.
290 You can retrieve the current Xwiki instance by using the <code>com.xpn.xwiki.XWikiContext</code> class, which has a <code>getWiki()</code> method.
291
292 The rule, in plugin programming, is to pass the current context as a <code>com.xpn.xwiki.XWikiContext</code> function parameter, between the different methods of your plugin class. The plugin API class also has a <code>context</code> property pointing to the current context.
293
294 {code}
295 // You need the current context, which you always have in a plugin anyway
296 com.xpn.xwiki.doc.XWikiDocument doc = context.getDoc(); // current document;
297 com.xpn.xwiki.doc.XWikiDocument doc = context.getWiki().getDocument("theSpace.theDoc", context); // any document
298 com.xpn.xwiki.objects.BaseObject meta;
299 meta = doc.getObject("fooSpace.fooClass");
300 String docType = (String)meta.getStringValue("type"); //if the class of the object has a property named "type", which can accept a text value...
301 meta.set("type", "newValue", context);
302 {code}
303
304 If you need to access the parent of an XWiki document, you should use the <code>getDocument()</code> method of the <code>XWiki</code> class, as seen in the example above, with, as parameter value, the parent's full name returned by the <code>getParent()</code> method of the <code>XWikiDocument</code> class.
305 {code}
306 com.xpn.xwiki.doc.XWikiDocument parentDocument = context.getWiki().getDocument(childDocument.getParent());
307 {code}
308 You should not use <code>XWikiDocument.getParentDoc</code> since it only returns a blank <code>XWikiDocument</code> object set with the same ful name as the parent's full name.

Get Connected