|License||GNU Lesser General Public License 2.1|
Table of contents
Writing an XWiki Extension using WebJars consists in:
- Declare a Maven dependency in your pom.xml. For example if you need AngularJS, you would write something like:<dependency>
- Note the usage of the WebJars scripting API $services.webjars.url() which is used to compute an XWiki WebJars URL (which triggers a WebJars ). The version of the angularjs WebJar (in this case) is determined automatically since 6.3RC1. If there are multiple versions available you can choose the version using:
This API is also useful if the version of the WebJar doesn't match the version of the packaged library. In this case you have to specify the library version. Note that on older version of XWiki (6.0M1 to 6.3RC1) this is the only API available, so you must always specify the library version on these older versions of XWiki.
- This extension is not bundled by default, although it may be already installed as a transitive dependency. In order to be safe it's recommended to add the following dependency to your project's pom.xml (if you're building with Maven, of course):<dependency>
http://<server>/<context path>/webjars/<namespace>/<path/to/resource>[?version=<version>&evaluate=true|false]. For example: http://<server>/<context path>/webjars/wiki:mywikiAjaxQ/0.0.2/ajaxq.js.The URL format for WebJar URLs is:
Previous WebJars URL formats:
- XWiki 7.4M2+: http://<server>/<context path>/webjars/<path/to/resource>[?version=<version>&evaluate=true|false&wiki=<wiki id>]. For example: http://<server>/<context path>/webjars/AjaxQ/0.0.2/ajaxq.js?wiki=mywiki.
- XWiki 7.1M1+: http://<server>/<context path>/webjars/<path/to/resource>[?version=<version>&evaluate=true|false].
However make sure that you use the Script Service's $services.webjars.url() method to get a valid WebJar URL so that your code is independent of the format and will continue to work even if the format is changed in the future!
It is very important for the WebJar resources to be cached by the browser as this helps reducing the page loading time. Here's the history regarding caching support for Webjars in XWiki:
- Between 6.0M1 and 6.2.1 / 6.3M1 the WebJar resources were not cached at all. This means that each time you reloaded a page that was using WebJars, the resources from the WebJars were requested again from the server.
- Between 6.2.1 / 6.3M1 and 6.4.3 / 7.0RC1 the WebJar resources were partially cached. The browser is still making a new request for each resource that is being used but passing the 'If-Modified-Since' header which makes the server return a 304 Not Modified (empty) response, which is faster than sending the resource back again.
- Starting with 6.4.3 / 7.0RC1 the WebJar resources that are static (e.g. no Velocity code) are cached permanently. The browser won't make a new request to get the resource unless:
- You clear the browser cache or force reload the page (Ctrl + F5)
- You reload the page using F5. In this case the browser will send a request with 'If-Modified-Since' header and the server will responde with an empty 304 Not Modified.
Here's an example of thewhich uses this WebJars integration module.
Custom Group Id (6.3RC1+)
Maven projects that generate WebJars have by default the org.webjars group id. That's why when you write
you specify only the artifact id ('jstree'). If you don't follow the WebJar convention and the group id is different then you need to specify it:
Note that the group id is not needed when you specify the version:
Velocity Code Evaluation (6.3RC1+)
You can use Velocity code in the resources that are packaged as WebJar. For instance you may want to usein your CSS files. In this case, when requesting the resource you need to specify that it has Velocity code that needs to be evaluated:
Note that the last argument is a map of parameters to pass to the requested resource. They will be added in the query string of the resource WebJar URL.
Prerequisites & Installation Instructions
We recommend using theto install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).
You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.
- org.xwiki.platform:xwiki-platform-classloader-xwiki 9.3.1
- commons-io:commons-io 2.5
- org.xwiki.platform:xwiki-platform-wiki-api 9.3.1
- org.xwiki.platform:xwiki-platform-resource-default 9.3.1
- org.xwiki.platform:xwiki-platform-resource-servlet 9.3.1
- org.xwiki.platform:xwiki-platform-url-scheme-filesystem 9.3.1
- org.xwiki.platform:xwiki-platform-oldcore 9.3.1