14 Jun
2013
14 Jun
'13
8:56 a.m.
Hi guys,
I've been working on this little side project which I originally needed to
scratch a personal itch that came up during my work on the Resilience research project.
I needed an efficient way to generate XWiki export (.xar) files and post them to a
running wiki for rapid prototyping. In the past I would do some work from within the
wiki and once the bulk of the work was done, I'd export an xar file and unzip it.
Fixing up the XML and making small changes would be done by hand editing the XML dumps.
To test it, the XML files would be packaged into .xar file using Maven then uploaded
into the wiki by using the import function in the Admin interface.
There are a few problems with this process:
1. Manually editing XMhelL files.
2. My attention span lasts from `mvn clean install` to `[INFO] Scanning for projects...`
3. The turnaround cycle from making a change in the git repository to seeing it in the
wiki is somewhere around 2 minutes (edit, compile, upload in browser, test)
My solution is called xwiki-tools, it's a Javascript framework for scripting the
creation
of XWiki packages with documents, objects and classes.
Code Golf example:
This is the shortest xwiki-tools script which will run (it makes a .xar file):
var XWiki = require('xwiki-tools');
var pack = new XWiki.Package();
pack.setName("XWiki - Contrib - XWiki Tools Tiny Example");
pack.setDescription("package name, description and extensionId are required");
pack.setExtensionId("org.xwiki.contrib:xwiki-tools-tiny-example");
var doc = new XWiki.model.XWikiDoc(["Main","TinyExample"]);
doc.setContent("A code-golf example of making an XWiki .xar file with 1
document.");
pack.addDocument(doc);
pack.genXar('XWikiToolsTinyExample.xar');
You can copy/paste this little .js script into a file and run `node yourFile.js` and
it will output XWikiToolsTinyExample.xar.
But wait, there's more!
xwiki-tools doesn't just allow you to wrap little documents into .xar files, it
allows you to add attachments, XObjects and even define your own XClasses.
It can also generate more than a xar file, it can post the package directly to a
running wiki which allows you to edit a file, run the command, page over to the
browser and immediately see your changes!
If you want, it can also generate output as an Apache Maven build.
Check out the example here: https://github.com/cjdelisle/xwiki-tools-example
to learn how to add attachments, XObjects and XClasses to your package and how to
post to a wiki or generate a Maven build.
Performance:
user@ubnta8:~/wrk/resiliance/xwiki-tools-example$ time ./do >/dev/null
real 0m0.643s
user@ubnta8:~/wrk/resiliance/xwiki-tools-example$ time ./do --mvn >/dev/null
real 0m0.416s
user@ubnta8:~/wrk/resiliance/xwiki-tools-example$ cd mvnout/
user@ubnta8:~/wrk/resiliance/xwiki-tools-example/mvnout$ time mvn clean install
>/dev/null
real 0m20.578s
XWiki Classes:
So you've decided you want to give this a shot and you have a big ugly
class which you need to represent. If you've looked at one of the existing
classes such as:
https://github.com/cjdelisle/xwiki-tools/blob/master/lib/model/classes/Wiki…
then you know what it needs to look like but getting your class in that form
would be painful. Fortunately there is a tool which reads your .xml file with
the XClass and prints a .js file like the one above.
Just unzip the xar export from XWiki and run the following:
node ./bin/describeclass.js /path/to/YourBigClass.xml
Note: some of the class properties are unimplemented so some classes will not work.
License:
LGPLv2.1, same as XWiki, generated code/data explicitly exempted.
Thanks,
Caleb