Bundlers are a key part of the BladeRunner framework, assembling the code of different blades into a single application when it is ready to run. This topic explains what they are and how they are used.
Bundlers concatenate all the required code assets across a number of blades into asset-specific "bundle" files. Any dependencies from Caplin or third-party libraries are automatically included.
We use the generic word Assets to describe all of the different types of content that can comprise an application. There are six asset types, each of which has its own bundler.
CSS Resources (e.g. Images, Typefaces, etc
i18n (internationalisation) properties file
How Do Bundlers Work in Practice?
There are three basic scenarios in which you will run your application, and bundling works slightly differently in each of them:
Displaying in a browser during development
Running tests on your code
Building a deployable application
Scenario 1 – Displaying in a Browser during Development
During development, you would want to display a blade in a browser, either in isolation (in a workbench page, while you are working on it) or as part of the whole application, which you would do by viewing the index.html page of a particular aspect.
In either case, every time the browser requests a page, the bundlers run as servlets within BladeRunner’s embedded app server. They treat the requested page as a "seed" file and perform a recursive dependency analysis (which is to say that they check which resources are going to be needed to display the page, and then go and fetch them), before producing bundle files that contain all the code needed to run the application.
This means that any time a line of source code is changed, that affects any part of the page being displayed, the result can be seen just by refreshing your browser. The bundlers are written with performance in mind, and workbench pages typically take just a few tenths of a second to reload.
Scenario 2 – Running Tests on Your Code
plugin: - name: "BundleInjector" jar: ../../../sdk/libs/java/testRunner/js-test-driver-bundler-plugin.jar module: com.caplin.jstestdriver.plugin.CutlassBundleInjectorPlugin
|The path to the js-test-driver-bundler-plugin.jar file will of course vary, depending on the location of the JsTestDriver.conf file that contains the reference. The js-test-driver-bundler-plugin.jar file contains code that emulates all the bundlers; there are not separate jar files for each one.|
The bundlers are executed by js-test-driver every time tests are run.
Scenario 3 - Building a Deployable Application
When deploying an app, the bundlers run in "batch mode" and generate static bundle files which are included in the war file that is installed in the production system. Bundlers are not used in a production environment, as the pre-bundled files are served directly.
Scope and Scoping Rules
The modular structure and conventions that are the basis of BladeRunner, are enforced by the bundlers. This takes place in two ways:
Firstly, if the bundlers are to work, resource files must be kept in their designated places, or the bundlers will not be able to locate them. When the application is run therefore, the resource files will not be assembled properly, making it very likely that errors will occur.
Secondly, and in some respects more fundamentally, bundlers ensure that the modular hierarchy of a BladeRunner application is applied properly. What this means in practice is that code within a particular blade can only be used by that blade, whereas code within a bladeset’s resource folders can be used by any blade within that bladeset. Code that belongs to the wider application, including the Caplin libraries and any third-party libraries, can be used by any blades. The bundlers make sure that the scope of each blade is respected, so that scripts in one blade do not over-ride those of another.
These "scoping rules" vary, depending on the scenario from which you run the bundlers. These rules determine which input files are provided to the bundler in particular conditions. The bundlers for different asset-types have different rules, and each bundler concatenates these files, accordingly.
It should be noted that for some asset types the order in which files are included matters. For example CSS files from the higher levels, such as aspect, are always included after the CSS files from lower level blade directories. This ensures that common rules (background colour for instance) are set at the app level. These behaviours vary for each bundler.