BIS Lightweight Application Development Engine

Core Architecture

This document explains the inner workings of blade. If you just want to throw some tags up on a page, you should skip this. However, if blade works for you, eventually you're going to want to edit a theme, script components using javascript, or potentially even create a new component. For anything like that, this is required background reading. Note that this document only covers what blade does at the browser end. For any server-side architecture information, look at the platform-specific documentation.

From Tag to HTML

The best way to explain how blade works is with a simple, imaginary component. Pretend that blade supports a component named "colorbox" that puts a colored box up on the screen by creating a div and setting its CSS background-color.

Under the blade framework, the HTML output for an orange-themed colorbox tag would look like this:

<div class="colorbox_main_orange">
 body of the colorbox tag would go here
</div>

The div's class is divided into three parts, separated by underscores: the component, the element, and the theme. For simplicity, the component name here is colorbox, but new components should try to use more namespace-like names to avoid conflicts, such as com-cx-test-colorbox. In this case colorbox only has one element, named main. However, a nestedcolorbox component might have two elements, inner and outer, each with different background colors.

Linking in a Theme

In some theme's css file, the orange colorbox theme would be defined like this:

div.colorbox_main_orange {
	background-color: orange;
}

You could edit the css, js, and xml files that make up a theme by hand, but blade provides an automated compiler that allows themes to extend other themes and inherit their properties. For more information on building themes, look at the themes section of the documentation.

Adding Some Interactivity

Many components involve some sort of javascript-controlled interactivity. The standard blade way of doing this is to have a js class for the component, and instantiate a new instance every time the component appears on the page. The HTML for a dynamiccolorbox tag would then look like this:

<script>page.components["dcb1"] = new DynamicColorBox("dcb1", "orange");</script>

<div class="dynamiccolorbox_main_orange" onmouseover="page.components['dcb1'].rollon()" onmouseout="page.components['dcb1'].rolloff()">
 body of the dynamiccolorbox tag would go here
</div>

The first line creates a new DynamicColorBox object with an id of dcb1 and a theme of orange, and sticks a reference to the object in the page.components array. Additionally, the object's rollon and rolloff methods are called when the div is moused over and moused off.

The javascript file for the DynamicColorBox would look something like this:

DynamicColorBox = function(id, theme) {
	this.id = id;
	this.theme = theme;
}

DynamicColorBox.prototype.rollon = function() {
	page.themes.set("dynamiccolorbox", this.id, this.theme, "on");
}

DynamicColorBox.prototype.rolloff = function() {
	page.themes.set("dynamiccolorbox", this.id, this.theme, "off");
}

Both the rollon and rolloff functions call page.themes.set, telling it that a dynamiccolorbox component with a particular id and theme needs to be set to a given state.

Themes and State Change

Somewhere off in theme land, the theme file for the orange dynamiccolorbox will have provided the following code:

// dynamiccolorbox widget, orange theme, on state
page.themes.addHandler("dynamiccolorbox", "orange", "on", function(id) {
   var elt = document.getElementById(id); if(elt) elt.style.background= "red";
});
page.themes.addHandler("dynamiccolorbox", "orange", "off", function(id) {
   var elt = document.getElementById(id); if(elt) elt.style.background= "orange";
});

Note that the js-abbreviated background is set here, since javascript cannot handle -'s in variable names.

When the page.themes theme handler gets a set request, it matches the component, theme, and state up with the pre-registered function, and calls that function to change the state of the component.

Caveats

Just like the css class name, its a good idea to place the java class in a package. For example, if the component's css class is com-cx-test-dynamiccolorbox, the js class should probably be com.cx.test.DynamicColorBox or something similar. Additionally, in reality the javascript objects should extend blade.base.UIComponent, which provides some basic functionality and a convenience method for setting themes.