Nuiton-js

Presentation

Nuiton-js is a libraries used to:

  • package javascript and css libraries as maven artifacts

  • aggregate severals libraries into a single file

  • minimize and reduce size using wro mechanisms

  • simply package new libraries

Using Servlet 3 API

To use nuiton-js in a servlet 3 container, you just have to add following dependencies in your project pom.xml file:

<dependency>
  <groupId>org.nuiton.js</groupId>
  <artifactId>nuiton-js-wro</artifactId>
  <version>${versionNuitonJs}</version>
</dependency>

Using Servlet 2 API

If you're not using a servlet 3 container, you will have to add following configuration in your application's web.xml file (in addition to maven dependencies into your pom file):

<filter>
  <filter-name>WebResourceOptimizer</filter-name>
  <filter-class>org.nuiton.js.wro.NuitonJsFilter</filter-class>
</filter>
<filter-mapping>
  <filter-name>WebResourceOptimizer</filter-name>
  <url-pattern>/nuiton-js/*</url-pattern>
</filter-mapping>

Common configuration

Then, you will have to add the js or css libraries your want to use packaged as maven dependencies. Nuiton-js will take care about transitive dependencies.

For example, to use jquery and jquery-ui:

<dependency>
  <groupId>org.nuiton.js</groupId>
  <artifactId>nuiton-js-jquery</artifactId>
  <version>${versionJQuery}</version>
</dependency>

<dependency>
  <groupId>org.nuiton.js</groupId>
  <artifactId>nuiton-js-jquery-ui</artifactId>
  <version>${versionJQueryUI}</version>
</dependency>

In your JSP pages, you could then retrieve jquery resources with following url:

/nuiton-js/jquery.js

JSP will use following code to import it:

<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %>
...
<script type="text/javascript" src="<c:url value="/nuiton-js/jquery.js"/>"></script>

If you don't want javascript code to be minimized by nuiton-js, you could append ?minimize=false to the url (if you're using the default debug=true configuration):

<script type="text/javascript" src="<c:url value="/nuiton-js/jquery.js?minimize=false"/>"></script>

When deploying your site in production, you could change default configuration editing file WEB-INF/nuiton-js.properties by adding:

debug=false

Using wro to manage application own resources

You can create a file in W``EB-INF/wro.xml`` to manage your own resources with wro. You can also reference libraries package by nuiton-js. Libraries group name is resources group name. For example, if you use nuiton-js-jquery, group name will be jquery.

For more information about wro.xml file format, please refer to wro documentation at https://code.google.com/p/wro4j/wiki/WroFileFormat

WEB-INF/wro.xml file example:

<groups xmlns="http://www.isdc.ro/wro">
 <group name='MyApp'>
  <group-ref>jquery</group-ref>
  <group-ref>bootstrap-responsive</group-ref>
  <group-ref>jquery-ui</group-ref>
  <group-ref>jqplot</group-ref>
  <!-- plugin jqplot -->
  <group-ref>jqplot.canvasAxisTickRenderer</group-ref>
  <group-ref>jqplot.canvasTextRenderer</group-ref>
  <group-ref>jqplot.categoryAxisRenderer</group-ref>
  <group-ref>jqplot.cursor</group-ref>
  <group-ref>jqplot.highlighter</group-ref>
  <!-- js et css specifique a l'application -->
  <css>/css/MonApp.css</css>
  <js>/js/MonApp.js</js>
 </group>
</groups>

and, in your html or jsp files:

<link href="<c:url value='/nuiton-js/MyApp.css'/>" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="<c:url value='/nuiton-js/MyApp.js'/>"></script>

Advanced use

You can force model reload or cache cleaning using following urls:

/nuiton-js/wroAPI/reloadModel
/nuiton-js/wroAPI/reloadCache

Available configuration

Using file WEB-INF/nuiton-js.properties, you can change wro behaviour.

Nuiton-js use following options by default:

debug=true
managerFactoryClassName=org.nuiton.js.wro.NuitonJsWroManagerFactory
preProcessors=cssUrlRewriting,cssImport,semicolonAppender,cssMin
postProcessors=cssVariables,jsMin
uriLocators=servletContext,uri,classpath

For more details about wro configuration, refer to following url: https://code.google.com/p/wro4j/wiki/ConfigurationOptions

Using maven plugin to generate static resources

Here is an example of using wro4j-maven-plugin to generate static resources. The main difference with standard configuration is the use of org.nuiton.js.wro.NuitonJsMavenWroManagerFactory configuration for wroManagerFactory and plugin dependencies:

<build>
  <plugins>
    <plugin>
      <groupId>ro.isdc.wro4j</groupId>
      <artifactId>wro4j-maven-plugin</artifactId>
      <version>1.6.3</version>

      <dependencies>
        <dependency>
          <groupId>org.nuiton.js</groupId>
          <artifactId>nuiton-js-jquery</artifactId>
          <version>1.8.3-1</version>
        </dependency>
        <dependency>
          <groupId>org.nuiton.js</groupId>
          <artifactId>nuiton-js-jqgrid</artifactId>
          <version>4.4.1-1</version>
        </dependency>
      </dependencies>

      <executions>
        <execution>
          <phase>compile</phase>
          <goals>
            <goal>run</goal>
          </goals>
        </execution>
      </executions>

      <configuration>
        <targetGroups>MonApp</targetGroups>
        <minimize>true</minimize>
        <destinationFolder>${basedir}/src/main/webapp/wro/</destinationFolder>
        <contextFolder>${basedir}/src/main/webapp/</contextFolder>
        <wroFile>${basedir}/src/main/webapp/WEB-INF/wro.xml</wroFile>
        <wroManagerFactory>org.nuiton.js.wro.NuitonJsMavenWroManagerFactory</wroManagerFactory>
        <extraConfigFile>${basedir}/src/main/webapp/WEB-INF/wro.properties</extraConfigFile>
      </configuration>
    </plugin>
  </plugin>
</build>

Then you could use statics js and css files in your application:

<link href="<c:url value='/wro/MonApp.css'/>" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="<c:url value='/wro/MonApp.js'/>"></script>

Creating a new module

To add a new module for a new javascript or css library, you need to respect a few rules:

  • setup module version using the same packaged resource's version with an additional packaging number. For example, to package jquery 1.9.1, module version have to be 1.9.1-1 for the first packaging release

  • put resources in directory src/main/resources/nuiton-js-<resource name>

  • add resource configuration file src/main/resources/META-INF/nuiton-js/wro-<resource name>.xml

  • define a group name according to resource name in wro configuration file

Resource have to be committed unminimized. Nuiton-js will minimize then at runtime.

It's a good practice to prefix directory name with 'nuiton-js' and resource name. This will avoid any future problem if use define his own directory with resource name in the classpath.

wro.xml file example:

<groups xmlns="http://www.isdc.ro/wro">
  <import>classpath:META-INF/nuiton-js/wro-jquery.xml</import>
  <group name='jquery-ui'>
    <group-ref>jquery</group-ref>
    <js>classpath:nuiton-js-jquery-ui/js/**.js</js>
    <css>classpath:nuiton-js-jquery-ui/css/**.css</css>
  </group>
</groups>

For more information about this file format, please refer to wro documentation: https://code.google.com/p/wro4j/wiki/WroFileFormat

If a library depends on another one, it must be present in pom.xml file too as maven dependencies.

In pom.xml file, you may use a minimum version instead of a hardcoded one. User will be warned if he use a smaller version of dependencies library. For example, jquery-ui-1.10.1 depends on jquery at least in version 1.6, pom.xml file must define following dependency:

<dependency>
  <groupId>org.nuiton.js</groupId>
  <artifactId>nuiton-js-jquery</artifactId>
  <version>[1.6,)</version> <!-- jquery ui is compatible with jquery >= 1.6 -->
  <scope>runtime</scope>
</dependency>