Backbase Tag Library

The focus of this article is the Backbase Tag Library (BTL). BTL concerns itself with the visible aspect of a web application user interface. For its dynamic behavior, we need JavaScript, or the XML Execution Language and Command Functions tag libraries.

When you are developing a user interface, you will find that you are solving the same problems over and over again:

  • Create a layout
  • Show a menu of options
  • Have tabs to structure the space on a page
  • Provide pop ups and tool tips
  • Do form validation

These are just a few examples from a long list. The BTL is a set of UI widgets that can be used out of the box, which are extensible, and should appear the same in all browsers. By using these, you should be able to develop your website faster with a more robust result.

Backbase Tag Library widget overview

There are eight categories of BTL widgets for every aspect of layout and user interaction. If that is not enough, you can extend the BTL widgets to add new behavior or new looks and you can also develop your own widgets.

The following schema shows an overview of the widgets that are available:

There is also a ninth category of BTL elements. They are special because they can appear as attributes on other tags to specify extra behaviors that can be applied to any UI element. An example of such a behavior is drag-and-drop.

If you are using the Backbase Explorer to find examples for the BTL widgets (, the schema shown above may be a handy reference to find widgets you are looking for.

We always use the b prefix when referring to BTL widgets, although you can use whatever (nonconflicting) prefix you want.

The BTL abstract elements

If you are interested mainly in learning what BTL widgets look like, then the subject of this section about abstract elements maybe a little too abstract. Feel free to skip it, but before you do, take a look at the picture of the inheritance relationships between abstract elements. The picture shows the attributes that are available on many BTL elements.

Most of these attributes will be familiar to you and remind you of a not so distant past when you were still coding HTML instead of XHTML. While coding XHTML instead of HTML, you should use class and style instead of more specific attributes like width or margin. However, while using BTL, you must partly unlearn this for the BTL elements because using class or style could upset the styling that is done for the BTL elements, to make them look as they do.

Abstract element inheritance structure

The BTL markup language was developed using the Backbase Tag Definition Language. This means that BTL widgets are objects that can inherit properties from other TDL objects. It also means that you are able to extend the BTL objects into customized objects suitable for your application.

The BTL objects that we are looking at in this article, the layout objects, inherit from more basic, abstract objects. It is useful to look at some of these abstract elements because their attributes can be used by inheritance on the layout objects. The BTL elements we will be looking at are element, containerElement, dimensionElement, postionElement, and visualElement. All layout BTL elements inherit from these.

Here is a diagram of the inheritance structure:

For those of you who are not so familiar with object-oriented models: the picture says that element is the object from which all others inherit. Therefore, for all BTL widgets, you can use the id and xml:base attributes, because these are defined on the element element.

The Backbase Tag Definition Language supports multiple inheritance. Therefore, a cardStack element can use the attributes of both dimensionElement and positionElement, and by looking further up in the tree, also of visualElement and element.

The relationship between card and cardStack says that a cardStack can contain zero or more card elements.

The picture does not describe the methods available. The only public methods that are interesting, belong to cardStack, which has the next and previous methods.

Now, let's look at some of the BTL elements in detail:


Base element from which all the elements in the BTL namespace are derived.




Unique ID of the element.


Specifies a base URI other than the base URI of the document or external entity. The value of this attribute is interpreted as a URI reference.


Although element has no parent within the BTL namespace, it derives from the element JavaScript object in the DOM Core of the Backbase framework. The element JavaScript object implements the node interface, which means that all familiar DOM-related attributes and methods to append and remove children, and to navigate the DOM tree, are available. See the Backbase Reference for more details.


An element from which all the visual elements in the BTL namespace are derived. This element takes care of some of the visual and interaction aspects.

visualElement inherits from element.




Used to set CSS classes to BTL elements. It is not recommended that this attribute be used, as it might break the styling of controls. More specific attributes are implemented to take care of certain styling properties. Font-related styling can be used safely.


Sets how the element is displayed. It works like the CSS display property. Because setting display can be tricky in some cases, the true and false values have been added. False does exactly the same as none, and true will reset the display property of the viewNode. The result is that the element is displayed according to the default rules or according to settings specified in the CSS classes.


Sets the opacity of the element, allowing you to see through it. It works like the CSS3 opacity property. The (decimal) ranges between 0.0 (not visible) to 1.0 (100% visible).


Used to set styles to BTL elements. It is not recommended that this attribute be used because it might break the styling of controls. More specific attributes are implemented to take care of certain styling properties. Font-related styling can be used safely.


Sets the title of the element.


Sets the visibility of the element. It works like the CSS visibility property. As opposed to setting the display, setting the visibility of the element does not change its dimensions. It will not disappear from the layout.



This element implements attributes that can position the elements that inherit from it.

positionElement inherits from visualElement.




Sets the distance from the bottom of the element to the bottom of the offset parent. It works like the CSS bottom property. You must add the proper CSS unit type.


Sets the distance from the left side of the element to the left side of the offset parent. It works like the CSS left property. You must add the proper unit type.


Sets the margin around the element. It works like the CSS margin property. You must add the proper unit type.


Sets the position of the element. It works like the CSS position property.


Sets the distance from the right side of the element to the right side of the offset parent. It works like the CSS right property. You must add the proper CSS unit type (for example, px).


Sets the distance from the top of the element to the top of the offset parent. It works like the CSS top property. You must add the proper CSS unit type (for example, px).


Sets the z-index of the element. It works like the CSS z-index property.



This element implements attributes that set the dimensions of the elements that inherit from it.

dimensionElement inherits from visualElement.





Sets the height of the widget. The widget height is relative to the height of its container.


Sets the width of the widget. The widget width is relative to the width of its container.


cardStack and card

There is a set of layout widgets that have a container—containment relationship. They use cardStack and card to inherit from. The widgets involved are:

  • accordion and accordionItem
  • deck and deckItem
  • tabBox and tab

cardStack is the parent element for all widgets that represent a stack of cards. It allows users to navigate through items (cards). The content of the card on top will be visible.

cardStack has one attribute and a set of methods that can be called to navigate through the stack.

cardStack inherits from disableElement, dimensionElement, and positionElement.




When set to true, the previous or next methods will, when called, continue to select either the last or first item. If set to false, these methods will not continue to select an item when reaching the beginning or end of the list.




Selects the next item in the cardStack (that is not disabled). If the loop attribute is set to false, it will not select an item when the end of the list is reached. If set to true, it will continue with the first item in the list.


Selects the previous item in the cardStack (that is not disabled). If the loop attribute is set to false, it will not select an item when the beginning of the list is reached. If set to true, it will continue with the last item in the list.


A card is an abstract element that provides the ability to enable and disable a widget. When the selected attribute is set to true, this card is the one that is shown when the cardStack is loaded into the page.

card inherits from disableElement, dimensionElement, and containerElement.




The selected state of the item (true/false).


This section does not sum up all the basic abstract elements implemented in BTL. For example, disableElement or focusableElement may interest you, for which you can find the details, as always, in the Reference.

There is another set of abstract elements that you will find mentioned in the Reference—the base element for each widget. Many widgets have a generic implementation that is common to both the system and the chameleon skin, and then specific implementations for each skin. The file structure for the tabBox widget, for example, is as follows:

For both the chameleon and the system skin, there is a tabBox BTL object, which inherits from the tabBoxBase BTL object. In fact, it is the tabBoxBase object that inherits from all basic elements as described before. The tabBox itself conveniently inherits everything from its base object.

Just for fun, we created the previous picture from the following code snippet:

<b:tree xmlns="" 
<b:treeBranch open="true">
<b:treeBranch label="chameleon">
<b:treeBranch label="media" open="true">
<b:treeLeaf label="tabHead.png" />
<b:treeLeaf label="tabBox.xml" />
<b:treeBranch label="system" open="true">
<b:treeLeaf label="tabBox.xml" />
<b:treeLeaf label="tabBoxBase.xml" />

This code hardly needs explanation by now.

From now on, we will usually take the existence of the base element for granted and ignore it in our description of inheritance relationships.

Now, we have all the background we need to know how the layout widgets are constructed. With this in mind, you can use the information in the next section without needing to look into the Backbase API Reference because we will mention the specific attributes for each widget. By looking at the inheritance information that we showed earlier, you will know what inherited attributes you can use.


Styling techniques for GUI widgets

This section talks about CSS and about the two skins available in the Backbase framework—the chameleon skin and the system skin.

We assume that you have experience working with CSS (Cascading Style Sheets). You probably did style your web pages by coloring texts and by filling areas with background images, or by drawing borders. Another aspect of using CSS is to specify layout for HTML, which you probably are familiar with too.

In this section, we will cover both aspects, that is, using CSS in Backbase applications as well as other facilities that are available.

Using CSS

CSS helps you to separate visual aspects of the application from its content markup. Generally speaking, you can use CSS to style many properties of your application markup, such as colors, fonts, sizes, positioning, and so on. The following example shows how an ID selector was used to give the calendar component a width:

<style type="text/css">
#myCalendar { width: 200px; }
<b:calendar id="myCalendar" />

Keep in mind that Internet Explorer doesn't support multiple class selectors. So, creating a rule .myclass1 .myclass2 will be applied only to elements that have either myclass1 and/or myclass2 classes specified.

Styling BTL components can also be done with CSS. However, here you need to follow certain conventions. Let's take a look at an example:

<style type="text/css">
.btl-calendar-input { color: red; }
<b:calendar value="10/03/2009" />

Here, we gave a red color to the text that displays the calendar value. The class selector we used was constructed by concatenating the following parts with a - character: btl, indicating the BTL component namespace, calendar for the name of the component, and input, indicating that this style is to be applied to the component's input field.

You can style other BTL components in a similar way.


When a set of widgets share a common skin, a consistent look and feel is propagated throughout the web application.

The Backbase Client Framework provides two skins for all renderable BTL elements: a system skin, which has the same look and feel as the Windows XP classic skin, and a modern, configurable chameleon skin. This is how a slider widget looks in system skin:

Here's how the same slider widget looks in chameleon skin:

You can change the skin used by altering the backbase/4_4_1/bindings/config.xml file. In this file, alter the value of the href attribute in the include statement to reflect the system skin file (config.xhtml_btl.system.xml) or the chameleon skin file (config.xhtml_btl.chameleon.xml).

For example, to change the skin to a chameleon skin, you can use this code:

<include xmlns=""
href="config.xhtml_btl.chameleon.xml" />

The Backbase Client Framework provides a few different options to alter the look and feel of Backbase widgets. The application developer can alter the chameleon skin simply by updating attribute values in the skin settings.

The BTL skinSettings widget

When using the chameleon skin, a tag called skinSettings is available. This tag has attributes that allow you to alter the background and text colors of the chameleon skin.

The slider, in this example, will be yellow; the button will have a purple border when pressed, and the calendar will show a variety of colors when dates are clicked:

<b:skinSettings activeText="cyan" highlightText="green" 
activeBackground="yellow" activeBorder="purple" />
<b:slider id="mySlider"
max="30" min="0" step="2" value="15" />
<b:button> This is a button </b:button>
<b:calendar mode="inline" />

Default colors are represented by the default values of attributes of the skinSettings.xml widget. By changing these attributes, you alter the stylesheet settings.

Refer to the API Reference for the default values of the chameleon skin.

Many features of the Backbase chameleon skin cannot be customized as easily as it may seem from this story. One reason is the use of background images and the other reason is that the intricate interplay of the various CSS settings can easily be upset if you change things.

If you don't want to use the chameleon skin, or you only want to alter a subset of the chameleon skin widgets, or want to create your own skin, you will have to extend widget(s) using TDL. Refer to the Widget Development Guide for more information.

Height problems

When putting GUI widgets on a page, it may happen that they look different than what you expected in the browser. Especially, the panelSet has a tendency to not appear at all, causing frustration to developers. Let's look at the cause and its solutions.

It can happen that the container element of the widget does not have a height set. In that case, the container will be sized according to the contents of the container. By default many BTL widgets do have a height of 100%, but if the height of the container is not set, this may be 100% of zero. The widget will collapse and will not be visible.

Solutions to these problems are as follows:

  • Don't use height: 100% but use a fixed height.
  • Set a height to the container. While using 100%, please understand that you're setting a size relative to the (offset) parent. You are actively setting a relative size. If you are not aware of the size of the (offset) parent, you may have to start with setting the height of the html element to 100%.

Part of the issue is the browser behavior. Take the following test case:

<!-- -->
<html xmlns="">
<style type="text/css">
html { background-color: blue; }
body { background-color: red; }
<body> </body>

You will find that in Firefox, the color you see will be blue. In Internet Explorer, in quirks mode, it is red. In IE, in standards mode, it will be blue, but with a red bar (even if there is no content in the body). The conclusion is that the body does not have a height initially (the content would determine the height). A height of 100% of something that has no height will result in no height.

The next step is to give the body a height. If we want "full screen" behavior, we will use 100%. However, the screen will still only show a blue background. Setting a height to the html element quickly solves this.


In this article, we took a closer look at the Backbase Tag Library.

We discussed about the following:

  • Backbase Tag Library widget overview
  • The BTL abstract elements
  • Styling techniques for GUI widgets

You've been reading an excerpt of:

Backbase 4 RIA Development

Explore Title