The Backbase page skeleton

There is one more thing we would like to take care of before we really start. It will save a lot of useless book space if we can explain what a typical starter page for the Backbase framework looks like and then forget about it. Of course, the examples that are supplied with this book are all ready to execute and therefore this source code will repeat the skeleton page code where required.

For any Backbase enabled page, you need an HTML file, usually named index.html, which looks like this:

<!-- -->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html 
 >
 <head>
 <meta http-equiv="Content-Type" 
 content="text/xhtml; charset=UTF-8" />
 <title>The Title of your Application</title>
 <script type="text/javascript" 
 src="../../backbase/4_3_1/engine/boot.js" >
 </script>
 </head>
 <body>
 <script type="application/backbase+xml">
 <xi:include 
 href="../../backbase/4_4_1/bindings/config.xml">
 </xi:include> 
 <!-- YOUR APPLICATION CODE GOES HERE -->
 </script>
 </body>
</html>

The version number of the Backbase Client Framework release is specified in the [version] folder name (for example, 4_4_1). If your version of the Backbase Client Framework is different from the one shown here, you must adapt the code samples accordingly.

There are some interesting points:

If you are including third-party libraries or your own JavaScript libraries, you should include them in the head section of the HTML document, as usual.
At the place where it says: , you can put your application code. We will call this a Backbase area. The code that you can put here can be ordinary XHTML, widgets that are provided by Backbase, or widgets that you have built yourself.
The  part is contained within script tags with type="application/backbase+xml". The type attribute signals the Client Runtime that it should process the contents. The xml part of the type attribute says that the contents should be proper XML.
There can be multiple Backbase area's areas. In fact, there can be as many areas as you like. This is convenient if you are converting an older web application to a Backbase application or when you have large chunks of conventional HTML in your application. As the Backbase framework takes some overhead to process this HTML, there is a performance advantage to put code that does not require processing by the Client Runtime outside a Backbase area.
The code in a Backbase must adhere to XHTML standards and most importantly, all tags must be properly closed. This can be a source of errors if you are converting an older application where for example <input> and <img> tags are often not closed. Another XHTML violation to watch out for is that attribute values in tags must be enclosed in quotes and all attributes specified must have a value. For example, you should code selected="selected" instead of just selected in a select box.
The Backbase JavaScript engine in boot.js is loaded in the header of the HTML page. It is very important to make sure that you have a proper path specification here. Many times, when you set up a new application, you get an empty page at your first try to see your application. The cause is almost always that your path specification is wrong. If this happens to you, it is convenient to use a tool like Firebug to see what the server returns and why it cannot find the Backbase libraries.
To use the Backbase widgets, you must include the configuration files, also called implementation bindings for the tags:
```
<xi:include href="../../backbase/4_4_1/bindings/config.xml">
</xi:include>
```
The config.xml file contains an additional include for the specific skin you want to use. The default is the chameleon skin . As an alternative, you can use the system skin. Similar to the earlier point, your path specification must be correct; otherwise your page will most likely stay empty.
The inclusion of the configuration files is done with the statement: xi:include. We make use here of XInclude, or XML Inclusions, which is a W3C standard for merging XML files. This facility makes it possible to code your web pages in a more modular way by dividing your code in smaller chunks, which can be combined at runtime. See http://www.w3.org/TR/xinclude/ for details. Backbase has implemented the XInclude standard in its framework according to the standard and you see it used here to include the configuration files. We will see more of it later in this article.
The HTML tag contains two namespace declarations—
target="_blank">>From now on, we will usually take for granted that you know how to surround our example code with the right skeleton code.

"Hello Backbase" in four variations

In the previous section,we showed what a Backbase starter page looks like. So finally, we can show real Backbase code.

It is time to say "Hello Backbase!" We will do so by showing typical "Hello World" examples as follows:
- The first example shows a simple alert when you click on the Click me text. It serves to make sure that we have the right setup for our applications.
- The second and third examples are a bit more interesting: a balloon from the Backbase Tag Library is shown, with the text that you typed in an input field. The difference between the two is the use of JavaScript or the XML Execution Language, as you will see.
- The fourth example is an AJAX example. It involves communication with a server, which echoes the text typed in, together with a timestamp. The response is added to earlier responses without refreshing the page.
Directly Download the example code for the article. The downloadable files contain instructions on how to use them.

We assume that you have a web development environment set up now and that you have put the Backbase libraries at the right place. We will take a follow-along approach for explaining the "Hello World!" examples, but of course you can also just execute the ready-to-run downloaded source code instead of typing the code yourself.

Start with creating a new folder named bookApps, or whatever name you like better. Next, create a subfolder of the bookApps folder named helloWorld.

Verifying the installation of the Backbase framework

Create an HTML file named hello1.html and put this file in the helloWorld folder. Copy the skeleton file that we saw in the previous section into hello1.html. Remember the following:
- In this file, we made sure that the Backbase Framework Client Runtime will be loaded because of the <script> tag in the head section of the HTML document.
- The <script> tag in the body section of the HTML document has a type declaration, application/backbase+xml, which tells the client runtime to process whatever is contained within the tag.
- The first thing that the client runtime is asked to process is the inclusion of the config.xml file, which contains the bindings that define the UI widgets.
The position where  is placed tells the runtime that it should process whatever we replace this with.

Namespace declarations are needed for all the namespaces used, in the tag where they are used, or a parent tag within the document.

Replace  with the following content:
```
<div>
 <e:handler 
  
 event="click" type="text/javascript">
 alert('Backbase says hello!');
 </e:handler>
 Click me 
</div>
```
To see your first "Hello" example in action, you can either double-click on hello1.html in the Windows explorer (if you are running Windows), or, if you have started your local server, you can open a browser and type something like this in the address bar: http://localhost/bookApps/helloWorld/hello1.html.

After clicking on the Click me text, you should see a result that is similar to what is shown in the following picture:

What if you do not see anything? The most common problem that could be the cause is that the path to boot.js or config.xml is not correct. If you are running with a server, check that it is running properly, and that it can find your hello1.html.

Unlock access to the largest independent learning library in Tech for FREE!

Get unlimited access to 7500+ expert-authored eBooks and video courses covering every tech area you can think of.

Renews at ₹800/month. Cancel anytime

When all is well: Congratulations! The Backbase Client Framework is running successfully.

Let us look at the code:
- The interesting part of the code is the event handler for the div element that contains the Click me text. The e:handler tag is part of the XML Execution Language (XEL), a custom markup language that is provided with the Backbase Client Framework, and that can be used as a replacement for JavaScript in many cases.
- The namespace that we need for using XEL is declared in the e:handler tag itself; it could also have been declared in the <div> or <html> tags.
- Between the start and end e:handler tags, you can code either JavaScript, as in this example, or XEL, as we will see in the next "Hello World!" example.
You could have coded the example also as "Hello World" without the Backbase event handler: <div onclick="alert('Backbase says hello!');"> Click me! </div>. At first sight, this is shorter, so why would we need Backbase for this? Well, usually, you need more in the event handler than just a short alert. In such case, you have two choices: either clutter your page with hard to read JavaScript or create a JavaScript function that you put in the head section. Before you know it, you will have many of these functions, which become hard to maintain and organize. In the case of the XEL event handler, you can write well-formatted and well-structured JavaScript code that stays local to the widget where you put the event handler. Of course, you can define more global functionality as well and you will see examples of this also.

XML namespaces! In this first example, you saw again a new XML namespace, this time for XEL. We already saw the XHTML and the XInclude namespace declaration in the page skeleton; in the next section you will see the Backbase Tag Library, the Commands, and the Forms namespace. Yes, that is a lot of namespaces. We promise that you will find out how useful these are and that you will get used to it.

This was a very simple example that made sure the Backbase framework is working right. In the next three examples, we will expand your knowledge by demonstrating a personalized "Hello World", using a tag from the Backbase Tag Library. The last "Hello World" example will demonstrate the AJAX functionality of the Backbase Client Framework by showing a form with one input field, which, when submitted, causes a response to be displayed somewhere in the page without a page refresh.

"Hello World" using a Backbase balloon

This section contains a pair of examples showing how to create a BTL balloon that is filled with custom text.

The balloon widget displays an image similar to that of a dialogue box in a comic book. The balloon can contain text, images, or other widgets. The user can click on the x icon in the balloon to close it or the balloon can be displayed for a limited amount of time. The balloon is positioned in relationship to its parent widget.

The balloon widget is similar to a toolTip because they represent information that becomes available only after an action is performed. Most often, these widgets are used to present contextual information about a widget in your application.

This is not the easiest example for showing a Backbase GUI widget from the Backbase Tag Library. However, we have chosen it because we wanted to show an example that illustrates the power of using pre-built widgets.

The example is done twice, to show that BTL can be coded in two ways, either by using an event handler with JavaScript content, or by using no JavaScript at all. The second version of the example shows the Backbase-specific XML Execution Language (XEL) and Backbase Commands instead of JavaScript. Any combination of these two styles is also possible.

Below is a picture of what the result of trying the example will look like:

The user will type a name, and after clicking OK, the balloon will appear. The user can click on the x to close it. Otherwise, it will disappear automatically after a while.