Backbase 4 RIA Development

If you are like us and like many web developers, you may have started writing simple HTML when developing web applications. After a while, you may have decided to separate presentation from structure and to give your web pages a better look using CSS. The next thing in your evolution as a web developer would have been making your pages more user friendly and interactive, by creating tool tips, pop-up windows, tab boxes, and by validating forms before submitting. Maybe you did this using little pieces of JavaScript downloaded from the Web or by building your own JavaScript function libraries. On top of this, you may have tried to give your web applications the look and feel of a desktop application by using AJAX, requiring more JavaScript everywhere.

Now, what happened to the source code of your web pages? Again, if you are like us, over time the HTML code became littered with many pieces of JavaScript. It became difficult to see what the structure of the page was, even more so when you tried to generate the HTML code from PHP or JSP or some other server-side scripting language. Perhaps, you found out too that it is really hard to make a web page that will show well in all major browsers.

Would it not be nice if there was...

The Backbase Client Framework is such a framework. We will call it Backbase most of the time, which is also the name of the company that built the framework. Backbase can be used freely. There is no difference between the commercial and the community edition, except for the license, which states that you should not deploy it commercially on a server with more than two processors.

This book is intended to make you an expert in using the Backbase framework. We will cover just enough of AJAX, XML, XHTML, namespaces, XPath, CSS, and the Document Object Model (DOM) to make the Backbase framework easier to use, and to understand why Backbase is built like it is. While doing so, we hope that we can increase your knowledge of the core client web technologies and how they relate to each other. With this knowledge, you can evaluate Backbase against other frameworks and decide which one suits your purpose the best.

To round off this introduction, let's summarize the advantages of using the Backbase Client Framework:

To serve web pages locally, you need to have a web server installed on your local PC. You can use any web server you like in combination with the Backbase framework. For example, popular web servers are Apache and IIS.

Also, you will need a server scripting language, such as JSP or PHP. Backbase will work with all server languages, therefore the choice is yours. Just remember that Backbase can communicate with any web server and any server scripting language that outputs the right XHTML to the browser.

If you already have a local development environment set up, then that is fine. Keep using it! Otherwise, you could obtain the XAMPP package, which you can download from: www.apachefriends.org. This package is really easy to install and includes Apache, PHP, MySQL, PHPMyAdmin, and more. It is available for several operating systems including various types of Linux, Mac OS, and Windows.

Examples in this book that require communication with a server will mostly use PHP because that is the easiest environment to set up, and also easy to understand, even if you are not familiar with it.

To execute and view the application we are developing, you need a browser. The browser landscape is changing very fast. A year ago, there would have been only one recommendation that we would have made here: use Mozilla Firefox! Not only because it is a good browser, but mainly because of Firebug, the debugging plugin for Firefox. Firebug gives you the ability to edit, debug, and monitor CSS, XHTML, JavaScript, and network traffic live in any web page viewed in the browser. You can find Firebug at http://www.getfirebug.com.

Today, there are a lot more browsers that do a good job at implementing web standards and that offer good debugging facilities such as Google Chrome, Safari, and Microsoft Internet Explorer 8.

A handy plugin to use for Microsoft Internet Explorer prior to version 8 is the MSIE Developer Toolbar. It provides a variety of tools for quickly creating, understanding, and troubleshooting web pages in the MSIE browser. Search for Developer Toolbar at http://www.microsoft.com/downloads/.

We should specifically mention the Backbase debugger. This is a Firebug style debugger that will work across all supported browsers. It will start automatically in the Backbase development environment when something goes wrong. It will help you to debug applications in browsers for which no good tools are available.

You will need more than one browser to test your application. A considerable percentage of the users of your web application will be using browsers other than the one you chose to develop with, and unfortunately, even Backbase cannot guarantee that your application will look the same in all browsers. At the minimum, you should have Mozilla Firefox and Microsoft Internet Explorer available for testing.

In addition to a web server, you will need a tool that you can use to edit your application source code. Although any text editor such as Notepad is sufficient, you will be more productive if you use a suitable Integrated Development Environment (IDE). Again, if you already use an IDE that you are comfortable with, please keep using it. Otherwise, we would recommend installing the Eclipse IDE. Eclipse is an open source IDE with many plugins available for specific development tasks. One of those is a Backbase plugin that will help with code completion. This plugin is included in the package when you download the Backbase framework. However, Eclipse can be downloaded from http://www.eclipse.org. Be sure to download a version of Eclipse with web development capabilities already included. A plugin that supports PHP, of which there are several available, is useful too.

As an alternative, you could consider Aptana Studio, an Eclipse-based IDE that is targeted at AJAX developers. Among many features, it has support for Adobe Air application development. It has many plugins for all kinds of handy development tasks. You can download Aptana as a standalone application or as an Eclipse IDE plugin from http://www.aptana.com.

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:

The position where <!-- YOUR APPLICATION CODE GOES HERE --> 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 <!-- YOUR APPLICATION CODE GOES HERE --> with the following content:

<div>
<e:handler
xmlns:e="http://www.backbase.com/2006/xel"
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.

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

Let us look at the code:

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 in several variations later in the book.

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.

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

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, as many examples in the Backbase documentation and in this book will show.

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.

xmlns:b="http://www.backbase.com/2006/btl" xmlns:e="http://www.backbase.com/2006/xel"

<div style="margin: 80px 0 0 20px; width: 300px;">
<p> Please type your name and click OK: </p>
<input id="myInput" type="text" />
<button style="margin-left: 10px;">
OK
<e:handler event="click" type="text/javascript">
var oBalloon = bb.document.getElementById('myBalloon');
var oInput = bb.document.getElementById('myInput');
var sValue = bb.getProperty(oInput,'value');
bb.command.setText(oBalloon, 'Hello: ' + sValue,'replaceChildren');
oBalloon.setAttribute('open', 'true');
</e:handler>
</button>
<b:balloon label="Backbase says:"
id="myBalloon" mode="top-center"
timeout="10s" width="250px" />
</div>

<div xmlns:b="http://www.backbase.com/2006/btl"
xmlns:c="http://www.backbase.com/2006/command"
xmlns:e="http://www.backbase.com/2006/xel"
style="margin: 80px 0 0 20px; width: 300px;">
<p> Please type your name and click OK: </p>
<input id="myInput" type="text" />
<button style="margin-left: 10px;">
OK
<e:handler event="click">
<c:setText
select="concat('Hello: ',
id('myInput')/property::value,'!')"
destination="id('myBalloon')"
mode="replaceChildren" />
<c:setAttribute
with="id('myBalloon')"
name="open"
select="'true'" />
</e:handler>
</button>
<b:balloon label="Backbase says:"
id="myBalloon" mode="top-center"
timeout="10s" width="250px" />
</div>

To many people, AJAX is almost synonymous with XMLHttpRequest, the API that allows client programs to communicate asynchronously with a server. This example page shows the "Hello World" example communicating via AJAX using a Backbase form. If you are using the Backbase AJAX framework, it is possible that you will never use an XMLHttpRequest object directly, because its use is made transparent to you. If you wish however, it is possible to use it.

Here, we will look at using an ordinary looking form, still the most common means to enter information to be sent to a server. Instead of refreshing the whole page, AJAX is used when you tell the framework that you want to put the response to the form submitted at a particular spot on your page, by using the bf:destination attribute. As a server scripting language, we use PHP in our example because we assume that the majority of developers will be able to understand it. In addition, we show what the response file that PHP generates looks like. You can see from its structure how you could code an AJAX response in other languages.

Below you can see a snapshot of what the result could be of executing the example:

<div style="margin-left: 20px;">
<p>Please type your name and click OK:</p>
<form xmlns:bf="http://www.backbase.com/2007/forms"
action="response.php"
bf:destination="id('server-response-area')"
bf:mode="appendChild" method="post">
<input id="name" name="name" type="text" />
<input type="submit" style="margin-left: 10px;"
value="OK" />
</form>
<div id="server-response-area" style="background: #FFFFC8;"></div>
</div>

<?php
header('Content-type: application/xml');
echo '<?xml version="1.0" encoding="UTF-8"?>';
?>
<div xmlns="http://www.w3.org/1999/xhtml">
<?php
$myname = $_POST['name'];
echo " <p>";
echo "The server says: Hello <strong>$myname</strong> ! - on: ";
echo date('l jS \of F Y h:i:s A');
echo " </p>\n";
?>
</div>

<?xml version="1.0" encoding="UTF-8"?>
<div xmlns="http://www.w3.org/1999/xhtml">
<p>
The server says: Hello <strong>John Doe</strong>! - on:
Friday 30th of May 2008 12:50:43 PM
</p>
</div>

When XML was invented, there was no such thing as a namespace concept. The steadily increasing volume of XML data that was exchanged between different groups of people and different companies revealed a series of problems. One was that it was difficult to properly combine parts of different XML documents into new documents. Basically, these are the causes:

In order to solve these issues, the mechanism of namespaces was introduced into XML. If you are familiar with a programming language like Java, the namespace concept is similar to the package concept in that language. It enabled authors to determine, on markup, vocabularies for their content and facilitated governance.

You can recognize an XML namespace when you see an attribute that starts with xmlns. The part of the attribute that follows xmlns: is called a prefix. It is that part of the namespace declaration that actually sets up a link between a convenience token and a namespace. The namespace declaration scope is limited to the element where it was done and to the element's sub-tree. The names of these attributes are reserved: you cannot use an xmlns attribute or prefix for another purpose.

Let's consider a sample XML document that uses namespaces:

<?xml version="1.0"?>
<catalog
xmlns="http://www.library.com/ns/catalog"
xmlns:isbn="http://www.isbn.com/ns/isbn">
<book isbn:id="1847196705" id="1">
<title>Learning jQuery</title>
<author>Karl Swedberg</author>
<author>Jonathan Chaffer </author>
<isbn:datePublished>February 2009</isbn:datePublished>
</book>
<book isbn:id="1847191444" id="2">
<title>Joomla! Template Design</title>
<author>Tessa Blakeley Silver</author>
<isbn:datePublished>June 2007</isbn:datePublished>
</book>
<!-- More books -->
</catalog>

The catalog could serve as a description of books in a local library. The meaning and structure of the tags can be whatever the local library thinks is practical. In this document there is also the isbn namespace, which is used for tags that are relevant to the worldwide book register that the International Standard Book Number (ISBN) represents.

The Backbase Client Runtime processes all the tags that are placed between script tags that have type="text/backbase+xml" as attribute. To the Backbase Client Runtime, the combination of the namespace and the tag name will determine what the engine will do to interpret the tag.

We call a set of tags that belong to a specific namespace a markup language. In the Backbase point of view, XHTML is just another markup language. It belongs to the http://www.w3.org/1999/xhtml namespace, which you must declare just like the specific Backbase namespaces.

We have already seen several namespaces in our examples. Below is a list of namespaces you can expect to be using with Backbase, together with their preferred prefixes:

xmlns = "http://www.w3.org/1999/xhtml"
xmlns:xi = "http://www.w3.org/2001/XInclude"
xmlns:xs = "http://www.w3.org/2001/XMLSchema"
xmlns:smil = "http://www.w3.org/2005/SMIL21/"
xmlns:b = "http://www.backbase.com/2006/btl"
xmlns:c = "http://www.backbase.com/2006/command"
xmlns:d = "http://www.backbase.com/2006/tdl"
xmlns:e = "http://www.backbase.com/2006/xel"
xmlns:bf = "http://www.backbase.com/2007/forms"

Although it is legal to use different prefixes bound to the same namespace URI in different documents as well as within the same document, it is often convenient to stick to using similar ones.

For each markup language in your application, you must add a namespace declaration. For example, if you are using BTL UI widgets, you will need to add a BTL namespace declaration to your document.

The engine does recognize namespace declarations placed outside its processing space. This means that the best place to declare namespaces for all languages processed by the Client Runtime is as high as possible in the DOM tree, for example the <html> tag.

Here is an example of namespace declarations that you could use with some of the Backbase markup languages:

<script xmlns="http://www.w3.org/1999/xhtml"
xmlns:b="http://www.backbase.com/2006/btl"
xmlns:e="http://www.backbase.com/2006/xel"
xmlns:xi="http://www.w3.org/2001/XInclude"
type="application/backbase+xml">
<div>
Given the correct widget prefixes,
the Client Runtime can now
process all XHTML, BTL, XEL, and XInclude elements.
XHTML is the default namespace, so we don't have to give a
prefix to the parent div tag.
</div>
</script>

Using namespaces in your application can be confusing at first and can be a source of problems for a Backbase beginner. A good piece of advice is to check your namespaces if you have an error that you do not understand. Soon, adding the right namespaces will become second nature.