Advanced

Advanced topics

 

Generator: GetWebBundles

Class name:org.weborganic.bastille.web.GetWebBundles
Version:0.7.11 - 3 December 2012
Library:Bastille
Cacheable:Yes
Generated:2012-12-21

Description

This generator returns the list of timestamped scripts and styles for a given service.

It will assemble and minimize the scripts and styles together as much as possible and return the list of bundles. Because the name each bundle includes unique stamp, they can be cached for a long periods. When files included in a bundle are modified, this generator will automatically produce a new bundle with a new stamp so that it results in a different URL.

Bundling

Scripts are simply concatenated. Styles are concatenated and import rules will automatically include the imported styles into the main file. In CSS, the paths to images and other files are automatically rewritten.

Note

Use relative paths to images and imported styles or the bundler many not be able to reference them properly.

If there is no file to include in the bundle or if the file does not exist, the bundle isn't created.

Minimization

Both styles and scripts can be minimized after the bundling. Minimized bundles will be saved using the following extensions .min.js and .min.css.

If files to be bundled already use the *.min.* extension, it will be considered to be already minimized and won't be minimized again.

The bundler uses the minimizers defined in Bastille. To use other minimizers, simply preprocess the files and saves them with the *.min.* extension.

Data URIs

The CSS bundler will additionally include inline any referenced background image below a given size threshold as a data URI (using a base 64 encoder) as background:url(data:image/png;base64,...)

The default threshold is 4KB, but this can be configured.

To disable data URIs (for example, to support legacy browsers), simply set the threshold to 0.

File naming

Bundled files are automatically named as:

[bundlename]-[date]-[etag].[ext]

The bundle name is specified in the configuration; the date is the creation date of the bundle; the etag is the 4-character alphanumerical stamp; and the extension depends on the MIME type and minimization options.

Configuration

This generator is highly configurable and the configuration properties are specific (but similar) for styles and scripts.

Properties pertaining to scripts and styles are prefixed by respectively bastille.jsbundler and bastille.cssbundler .

Global options

The minimize boolean property can be used to control minimization of the code. The default is true.

The location property can be used to define where the bundled files should be stored. It should be the path relative to the application context. By default, they go to /style/_/ or /script/_/ .

For example, you can disable the JavaScript minimization and change the location by using:

<jsbundler minimize="false" location="/js/bundles/"/>

Bundles

The list and order of bundles to create can be specified using the configs property and mapping the name of a configuration to a list of bundles to create.

For example, the default configuration will create a global bundle first, then a bundle for the group of services, and a bundle specific to the service:

<configs default="global,group,service"/>

To create a new config, simply map it to the list of bundles to include:

<configs acme="global,acme"/>

Each individual bundle is then specified using the bundles property node where the bundle names are mapped to the comma separated list of paths to include using the include property.

The filename for the bundle can also be specified using the filename property. If the filename isn't specified it is the same as the bundle name.

The bundler supports special tokens that are replaced with the name of the current service group and service id, respectively {GROUP} and {SERVICE}.

Data URIs threshold

You can set the size threshold (in bytes) for the data URIs using the following property:

<cssbundler>
  <datauris threshold="4096"/>
  ...
</cssbundler>

You can disable data URIs by setting the threshold to 0.

Default configuration

If no configuration is provided, it will use the default configuration which is is the equivalent of:

<bastille>
  <cssbundler minimize="true" location="/style/_/">
    <datauris threshold="4096"/>
    <configs default="global,group,service"/>
    <bundles>
      <global  filename="global"    include="/style/global.css"/>
      <group   filename="{GROUP}"   include="/style/{GROUP}.css"/>
      <service filename="{SERVICE}" include="/style/{GROUP}/{SERVICE}.css"/>
    </bundles>
  </cssbundler>
  <jsbundler minimize="true" location="/script/_/">
    <configs default="global,group,service"/>
    <bundles>
      <global  filename="global"    include="/script/global.js"/>
      <group   filename="{GROUP}"   include="/script/{GROUP}.js"/>
      <service filename="{SERVICE}" include="/script/{GROUP}/{SERVICE}.js"/>
    </bundles>
  </jsbundler>
  ...
</bastille>

Legacy configuration

Prior to Bastille 0.8.x, this class could be configured using the following:

<node name="bastille.cssbundler">
  <map>
    <entry key="minimize"  value="true"/>
    <entry key="location"  value="/style/_/"/>
  </map>
  <node name="bundles">
    <map>
      <entry key="global"    value="/style/global.css"/>
      <entry key="{GROUP}"   value="/style/{GROUP}.css"/>
      <entry key="{SERVICE}" value="/style/{GROUP}/{SERVICE}.css"/>
    </map>
  </node>
</node>
<node name="bastille.jsbundler">
  <map>
    <entry key="minimize"  value="true"/>
    <entry key="location"  value="/script/_/"/>
  </map>
  <node name="bundles">
    <map>
      <entry key="global"    value="/script/global.js"/>
      <entry key="{GROUP}"   value="/script/{GROUP}.js"/>
      <entry key="{SERVICE}" value="/script/{GROUP}/{SERVICE}.js"/>
    </map>
  </node>
</node>

Parameters

No parameters are required for this generator.

The configuration to use can be specified using the config parameter. It must match one of the default configurations defined in the configs property for the bundle. The config will be 'default' is it isn't specified.

Disabling bundling

During development ,it can be useful to disable the bundling for debugging, can be disabled by setting the berlioz-bundle parameter to false. For example:

http://localhost/test.html?berlioz-bundle=false

Returned XML

The XML returns the scripts and styles in the order in which they are defined.

<script src="[jslocation]/[bundle].js" bundled="[true|false]" minimized="[true|false]" />
 ...
<style  src="[csslocation]/[bundle].css" bundled="[true|false]" minimized="[true|false]" />
 ...
 

ETag

The ETag is computed using the last modified date of each file included in the bundle. It will change if any of the included files is updated.

Created on , last edited on