Bundler

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

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

Property summary

The properties below are prefixed by berlioz

Default configuration

The default the configuration is equivalent to:

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

Property references

Property minimize

Minimization (or minification) is the process of removing characters such as white spaces, unnecessary symbols or implied units which can be removed safely while keeping the code semantically equivalent. This reduces the size of the code making it more suitable for delivery even if using HTTP compression.

The minimize property can be used to enable or disable minimization of the code using the built-in Berlioz minimizer. This property applies to both JavaScript and CSS.

The built-in analyzer is not particularly aggressive. For example, it will not try to rewrite variables in JavaScript. But it is good enough to reduce significantly the size of CSS and JavaScript files.

Although, the bundler does not detect whether the content of a file has been already minimized, it will not attempt to minimize files when their filename ends in .min.js or .min.css. In other words, if files have already been minimized, it is best to adhere to this file naming convention to prevent unnecessary minimization.

Usage

Minimization is enabled by default for both CSS and JavaScript. The allows developers to keep unminimized files in the source code at the same location and to debug application online by simply disabling bundling temporarily rather than rely on external builders.

The default settings are the equivalent of

<cssbundler minimize="true"/>
<jsbundler minimize="true"/>

When using well tested external libraries, it is recommended that you store the minimized version if the filename ending in .min.js or .min.css or use a CDN.

Property location

The location property on a bundler defines where the bundled files are stored. It is the path relative to the application context for the end users (e.g. http://example.org/style/_/ ), Berlioz will determine what this corresponds in the file system (e.g. /jetty/home/webapps/myapp/style/_/ )

The default location is:

• /script/_/ for JavaScript
• /style/_/ for styles

The default configuration is therefore:

<cssbundler location="/style/_/"/>
<jsbundler location="/script/_/"/>

Property datauris.threshold

The CSS bundler can automatically inline images as Base64 data URIs to avoid making numerous requests to the server for small images and making the styles self-contained.

This property defines the threshold in bytes for the file size of images to inline so that large images are not inlined. Setting this property to 0 effectively disables image inlining. The default value is 4096 (4K).

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

Property configs.[config]

The bundler can be configured to include different bundles.

Default config

The default config for both the JS and CSS bundlers is to include:

• a global bundle, for all services
• a service group bundle, common to all services from the same group
• a service bundle that is specific to the service.

This allows front-end developers to choose put scripts or styles at the right level of specificity. For example, if a style or script is only ever needed for a service, it can be put on that service.

It is the equivalent of

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

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

It is possible to change the default config. For example, if the application only ever defines a global set of styles, there is no need for the bundler to check whether specific ones have been defined. It is generally preferable to use custom configuration rather then override the default set of bundles.

<cssbundler>
   <configs default="global"/>
</cssbundler>

Custom config

There may be situations where some services need to use a different set of bundles than the defaults.

For example, this may be because some generic script or style defined in shared bundles are not applicable to these services, or to prevent the bundler from attempting to unnecessary load bundles, or to add a bundle to the default.

The example below define custom configurations to only load the global bundle (global-only), define an alternative to the global javascript (other) and load the default as well as another style (plus). Note that any bundle referenced in the config would need to be defined using the bundles.[bundle] property.

<cssbundler>
   <configs global-only="global"
                  other="other,group,service"
                   plus="base,global,group,service"/>
</cssbundler>

Property bundles.[bundle]

Bundles define a comma separated list of scripts or styles to bundle together. As with the location property (see above) the path is relative to the application context.

There are three predefined bundles for both the CSS and JS bundler:

Bundles can use special tokens in the filename to resolve dynamically at runtime:

• {GROUP} will resolve to the name of the group of services
• {SERVICE} will resolve to the service ID.

The default configuration is equivalent to

<cssbundler>
  <bundles global="/style/global.css"
            group="/style/{GROUP}.css"
          service="/style/{GROUP}/{SERVICE}.css">
</cssbundler>
<jsbundler>
  <bundles global="/script/global.js"
            group="/script/{GROUP}.js"
          service="/script/{GROUP}/{SERVICE}.js">
</jsbundler>

Example

This means that using the default configuration, when for the service 'delete-account' from the 'admin' group of services. The bundler will look for the following files.

Customizing default bundles

A common requirement is to include a library in the global bundle (e.g. for analytics, jQuery plugins, etc...). This can easily be achieved by changing the definition of the global bundle as in the example below:

<cssbundler>
  <bundles global="/style/global.css,/style/lib/foundation-6.0.5.min.css">
</cssbundler>
<jsbundler>
  <bundles global="/script/global.js,/script/lib/jquery.myplugin.js">
</jsbundler>

Creating custom bundles

It isn't always desirable to modify the default bundles, in that case is it safer to create a custom bundle. Custom bundles can then be referred to in the bundle config.

In the example below, we've defined an 'admin' bundle configuration which loads the 'admin' bundle and the 'admin-service' bundle in JavaScript.

<cssbundler>
  <configs admin="admin"/>
  <bundles admin="/styles/admin.min.css"/>
</cssbundler>
<jsbundler>
  <configs admin="admin,admin-service"/>
  <bundles admin="/script/admin.min.js,/script/lib/somelib-1.2.3.min.js"
   admin-service="/script/admin/{SERVICE}.min.js"
</jsbundle>

Created on 17 December 2015 , last edited on 17 December 2015 at 17:08