Generator: GetWebBundles

Description

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

It assembles and minimizes the scripts and styles together as much as possible and returns the list of bundles. Because the name of each bundle includes a unique stamp, they can be cached for a long periods. When files included in a bundle are modified, this generator automatically produces 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 automatically include the imported styles into the main file. In CSS, the paths to images and other files are automatically rewritten.

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 are saved using the following extensions .min.js and .min.css.

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

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

Data URIs

The CSS bundler additionally includes inline, any referenced background image under 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), set the threshold to 0.

File naming

Bundled files are automatically named as:

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

• bundle name – is specified in the configuration.
• date – is the creation date of the bundle.
• etag – is the 4-character alphanumerical stamp.
• 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 creates 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, 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 uses the default configuration which 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 is ‘default’ if it isn't specified.

Disabling bundling

During development, it can be useful to disable the bundling for debugging, disable 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 changes if any of the included files are updated.