Application structure

This section is critical to understanding the way that your application should be organised in order to have a seamless development experience with BladeRunnerJS, while at the same time achieving a modular application structure.


Apps consist of a number of bladesets and aspects. They conform to the Java Enterprise Edition 5 specification of a web-app, so you’re free to add your own servlets and filters to the WEB-INF/lib directory, and update the web.xml file appropriately. The servlets and filters that comprise the BladeRunnerJS server infrastructure are populated when an App is created.

Other JavaScript libraries can be added into the thirdparty-libraries directory. You can also create your own user libraries and add them to the libs directory. They will all be included into the JavaScript bundle file if they are referenced in your code.

BladeRunnerJS apps are delivered as J2EE WAR files. The specific settings for each environment are configured via JNDI. You can specify a database connection or even an environmental string to be used, in HTML. BladeRunnerJS filters replace known tokens with the value of your JNDI configured variable.

br apps dir 2


Typically, different Aspects will use different layout managers. A fully-fledged desktop browser aspect for example, might use a complex layout manager like Webcentric, with a mouse-oriented display, and many components and panels in view at the same time. Another aspect might use HTML, and embed single components for use on a mobile device. Aspects allow you to share blades between different web pages.

Users will request the entry page of the aspect (usually index.html) from the root of the aspect’s directory. The various bundlers scan the entry page, perform their dependency analysis and generate the appropriate bundles. Only the referenced blades are loaded, and blades from different bladesets may be included. Any assets common to the whole aspect are loaded from the src, test and resources directories of the aspect.

If you wish to create code (or use libraries) that are not compatible with the Caplin bundlers, simply place that code and other assets inside the unbundled-resources folder.

Directory structure for Aspects


A bladeset is a collection of blades that share some common code. They can also share assets such as styles, HTML templates and images. This allows you to create logical groupings of blades that display information in a consistent way. For instance: you would use a bladeset to share the custom code for numerical formatting in a set of blades, or to house a common date-chooser configuration.

Directory Structure for Bladesets


Each blade is a separate module, containing the code and resources for a single feature. For example: a form component, which receives, validates and submits data to the server. Largely, it consists of various JavaScript classes that contain business and presentation logic, plus some CSS and HTML that provide the view. It contains all the assets required to:

  1. Run the feature in a containing App.

  2. Run the feature in a stand-alone web-page known as a workbench.

  3. Test any code that is part of the blade (unit and acceptance tests).

Blades can reference code in libraries, but cannot directly reference code in other blades. This isolation means blades can be moved, deleted, copied and changed without affecting other blades. All the assets are held under a single directory that conforms to the structure shown below, with any assets that are shared between blades being held at the bladeset level.

Directory Structure for Blades
A themes directory at any level can contain a common directory for images and CSS which are common to any theme selected (such as structural CSS). The contents of this directory are always included in the application.

You supply common services to your blade via our service registry. Blades communicate with each other indirectly via the event hub.

All code must reside under the correct sub-directory e.g. all JavaScript code must be placed inside the src directory. Most of your app’s code consists of a (possibly large) number of blades. The code from those blades is automatically combined by the bundlers and returned to the browser.