Adds support for packaging web resources (JavaScript, CSS, images, fonts, etc.) using WebJars

Description

The WebJars project solves the issue of packaging JavaScript frameworks by bundling them as JARs. This allows XWiki Extensions to depend on JavaScript frameworks and be installable by the Extension Manager Application.

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>
   <groupId>org.webjars</groupId>
   <artifactId>angularjs</artifactId>
   <version>1.2.11</version>
   <scope>runtime</scope>
  </dependency>
• Create a JavaScript Skin Extension (a.k.a jsx) to load the JavaScript library you wish to use. For example:
  require(["$services.webjars.url('angularjs', 'angular.js')"], function() {
      ...
  });
• Note the usage of the WebJars scripting API $services.webjars.url() which is used to compute an XWiki WebJars URL (which triggers a WebJars Resource Handler). 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 (but this is a bad practice for an extension since it makes you code very fragile since any upgrade of the library will break it):

  $services.webjars.url('angularjs/1.2.11/angular.js')
  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>
   <groupId>org.xwiki.platform</groupId>
   <artifactId>xwiki-platform-webjars-api</artifactId>
   <version>${platform.version}</version>
   <scope>runtime</scope>
  </dependency>

URL Format

XWiki 7.4.3/8.1M2 The URL format for WebJar URLs is: 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.

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!

Caching

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.

Examples

Here's an example of the AngularJS Todo Application which 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 use Color Theme variables in 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.

Less Code Evaluation

Prerequisites & Installation Instructions

We recommend using the Extension Manager to 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.

Dependencies

Dependencies for this extension (org.xwiki.platform:xwiki-platform-webjars-api 16.10.1):

• org.xwiki.platform:xwiki-platform-classloader-xwiki 16.10.1
• commons-io:commons-io 2.17.0
• org.xwiki.commons:xwiki-commons-classloader-api 16.10.1
• org.xwiki.commons:xwiki-commons-extension-api 16.10.1
• org.xwiki.platform:xwiki-platform-wiki-api 16.10.1
• org.xwiki.commons:xwiki-commons-velocity 16.10.1
• org.xwiki.platform:xwiki-platform-resource-default 16.10.1
• org.xwiki.platform:xwiki-platform-resource-servlet 16.10.1
• org.xwiki.platform:xwiki-platform-url-api 16.10.1
• org.xwiki.platform:xwiki-platform-url-scheme-filesystem 16.10.1
• org.xwiki.platform:xwiki-platform-oldcore 16.10.1
• org.xwiki.platform:xwiki-platform-lesscss-api 16.10.1