SL4B Tutorial Page

This tutorial serves as a short introduction to SL4B. It demonstrates using bare bones code examples how SL4B is used within a webpage and how to operate it so that it returns the desired data from Liberator.

Loading SL4B in Your Webpage

The first step to making use of SL4B within your web application is to include it in all the resources that need to make use of it. For the purpose of this tutorial and subsequent examples the resources will be simple HTML pages. To keep this example simple we concentrate on a very straightforward application.

To include SL4B takes only a single line of code.

Listing 1. Including SL4B into your HTML page.
<script id="sl4b" type="text/javascript" src="http://liberator.company.com:8080/sl4b" configurationfile="common-attributes.js"></script>

This script tag would normally be placed inside the HTML <head> tag although it would also work in the body. The table below explains the meaning and function of the attributes of the tag.

Table 1. SL4B tag attributes and their significance.
Attribute Description
Name Value
id sl4b The identifier of the script tag element.
type text/javascript The mimetype for javascript, the language that the SL4B library has been written in.
src http://liberator.company.com:8080/sl4b The location of the SL4B library. Replace "liberator.company.com:8080" with the appropriate url for your liberator.
configurationfile common-attributes.js The location of the configuration file that will be loaded. In this case it is relative to the web page's location. This file defines the user and password attributes that are required by this page.

The SL4B configuration file

The configuration file itself contains a number of settings that may need to be tweaked.

Listing 2. SL4B configuration file.

 
var oConfiguration = SL4B_Accessor.getConfiguration(); 

/* The username and password for accessing the data on the Liberator */
oConfiguration.setAttribute("user", "demouser"); 
oConfiguration.setAttribute("password", "demopass");

/* We usually want the flash library to be loaded */
oConfiguration.setAttribute("enableflash", "true");

/* If we were serving these files from a webserver that was not also the liberator, we'd
 * also need to configure the liberator url here. */
oConfiguration.setAttribute("serverurl", "http://liberator.company.com:8080");

/* Assuming this file is being served from a host called appserver.company.com and liberator
 * is running on a host called liberator.company.com, then the common domain part is company.com
 */
oConfiguration.setAttribute("commondomain", "company.com");

The configuration file sets up user information such as username and password. The one displayed above also has extra settings like enableflash which will be explained later on it the tutorial. The serverurl setting is used to point SL4B to Liberator's location and port. Web pages served from one domain are not normally able to make requests to services running on another, as the browsers security model disallows it. In order to allow this page to successfully communicate with liberator, the common domain property must be set to a domain fragment shared by both the server this page is served from, and the server that liberator is run from.

Setting up an SL4B connection

Once SL4B is included in your HTML page the next step is to create an object that can receive information from the Liberator. These objects are called subscribers because they subscribe to data objects on the Liberator. Once a subscriber has subscribed to a data object on the liberator, any time there is a change to that object, Liberator will send that change to the subscriber, which can then take the appropriate action - usually updating the page.

Code Listing 1. Creating an SL4B subscriber object.

 
function ExampleSubscriber()
{			
	// This is the constructor of our object.
	
	// Any subclass of SL4B_AbstractSubscriber must call initialise in its constructor.
	// Once initialisation is finished, SL4B will call ready() on this object.
	this.initialise();
}

// Declares that the ExampleSubscriber is a subclass of SL4B_AbstractSubscriber
ExampleSubscriber.prototype = new SL4B_AbstractSubscriber();

ExampleSubscriber.prototype.ready = function() {	
	// Once the SL4B Object has completed this.initialise() it will call ready()
	alert("SL4B has connected and is ready");
};

var Subscriber = new ExampleSubscriber();

The result of the above code can be seen on this webpage. This example simply shows a popup message as soon as the newly created ExampleSubscriber class receives the ready call back from the SL4B library.

When initialise() is called the object is registered with the SL4B library and SL4B attempts to ensure that there is an open connection to the Liberator. Once SL4B has an open connection and can provide a communications channel to the Liberator it will call the ready() method which we implemented here as a simple method with an alert.

SL4B data requests and responses

Although the above example demonstrated how to connect to the Liberator using SL4B, it didn't show how to actually receive any data from the server. Now that SL4B has told our class that it is ready, we can request to be notified of changes. 

function ExampleSubscriber()
{			
	// Any subclass of SL4B_AbstractSubscriber must call initialise in its constructor.
	// Once initialisation is finished, SL4B will call ready() on this object.
	this.initialise();
}

// Declares that the ExampleSubscriber is a subclass of SL4B_AbstractSubscriber
ExampleSubscriber.prototype = new SL4B_AbstractSubscriber();

ExampleSubscriber.prototype.ready = function() {
	SL4B_Accessor.getRttpProvider().getObject(this, "/Examples/Records/FX/GBP", "dBestBid");
};

ExampleSubscriber.prototype.recordMultiUpdated = function(sObjectName, oFieldData) {
	var oElement = document.getElementById('messages')
	oElement.innerHTML = (new Date())+ ": New message received<br />"+oElement.innerHTML;
};			
	
var Subscriber = new ExampleSubscriber();

In this code, we subscribe to the server object representing the GBPUSD exchange rate, and specificially to the field representing the bid price. Every time the bid price of this object changes on the server, SL4B receives the upate from the Liberator, and calls recordMultiUpdated on our subscriber class. Since this might happen quite frequently, instead of showing an alert, we add a message indicating that we've received an update to an html element on the page. The result of this code can be seen on this page.

Processing responses

In the previous section we added a message every time that we received an update. However, we did't actually extract the information about what the new bid price on GBPUSD is. The following code subscribes to both the bid and the ask price on GBPUSD, and displays the rates. 

function ExampleSubscriber()
{			
	// Any subclass of SL4B_AbstractSubscriber must call initialise in its constructor.
	// Once initialisation is finished, SL4B will call ready() on this object.
	this.initialise();
}

// Declares that the ExampleSubscriber is a subclass of SL4B_AbstractSubscriber
ExampleSubscriber.prototype = new SL4B_AbstractSubscriber();

ExampleSubscriber.prototype.ready = function() {
	// The fields to subscribe to are in a comma separated list as the third argument of getObject.
	SL4B_Accessor.getRttpProvider().getObject(this, "/Examples/Records/FX/GBP", "dBestBid,dBestAsk");
};

ExampleSubscriber.prototype.recordMultiUpdated = function(sObjectName, oFieldData) {
	var oElement = document.getElementById('messages')
	
	for (var i = 0, size = oFieldData.size(); i < size; i = i + 1) {
		oElement.innerHTML = sObjectName+" "+oFieldData.getFieldName(i)+" = "+oFieldData.getFieldValue(i)+"<br />"+oElement.innerHTML;
	}
};
var Subscriber = new ExampleSubscriber();

The results of running this code can be seen on this page.

A Simple Table

Often we want to display the update for each field and object in its own element. This is particularly the case when we subscribe to more than one object. In such a case, code to locate the correct element could get quite complex. One simple solution is to create elements in the HTML with ids that can easily be generated from the object and field name. 

<html>
	<head>
		<script id="sl4b" type="text/javascript" src="/sl4b" configurationfile="../../configuration/common-attributes.js"></script>
		<title>Code Example 4</title>
		<script type="text/javascript">
		//<![CDATA[
		function ExampleSubscriber()
		{			
			// Any subclass of SL4B_AbstractSubscriber must call initialise in its constructor.
			// Once initialisation is finished, SL4B will call ready() on this object.
			this.initialise();
		}
		
		// Declares that the ExampleSubscriber is a subclass of SL4B_AbstractSubscriber
		ExampleSubscriber.prototype = new SL4B_AbstractSubscriber();
		
		ExampleSubscriber.prototype.ready = function() {
			// The objects to subscribe to are passed as a space separated list.
			SL4B_Accessor.getRttpProvider().getObjects(this, "/Examples/Records/FX/GBP /Examples/Records/FX/EUR /Examples/Records/FX/CAD", "dBestBid,dBestAsk");
		};

		ExampleSubscriber.prototype.recordMultiUpdated = function(sObjectName, oFieldData) {
			for (var i = 0, size = oFieldData.size(); i < size; i = i + 1) {
				var sFieldName = oFieldData.getFieldName(i);
				var sFieldValue = oFieldData.getFieldValue(i);
				
				// This is one simple technique for turning an object name and a field name into a html element id.
				// Remove most of the beginning, replace / with _s and append the fieldname.  These ids now match
				// the id's I've specified in the table lower down.
				var elemId = sObjectName.substring(18).replace(/\//g, '_')+"_"+sFieldName;
				document.getElementById(elemId).innerHTML = sFieldValue;
			}
		};
		
		//]]>
		</script>
	</head>
	<body>
		If this page has been correctly configured, updates received from the server should appear in
		the table below.
		
		<table border="1" cellpadding="3" cellspacing="0">
			<thead>
				<tr><th>Currency</th><th>Bid</th><th>Ask</th></tr>
			</thead>
			<tbody>
				<tr><td>GBP</td><td id='FX_GBP_dBestBid'>-</td><td id='FX_GBP_dBestAsk'>-</td></tr>
				<tr><td>EUR</td><td id='FX_EUR_dBestBid'>-</td><td id='FX_EUR_dBestAsk'>-</td></tr>
				<tr><td>CAD</td><td id='FX_CAD_dBestBid'>-</td><td id='FX_CAD_dBestAsk'>-</td></tr>
			</tbody>
		</table>

		<script type="text/javascript">
			var Subscriber = new ExampleSubscriber();
		</script>

	</body>
</html>

This code can be seen in action on this page.

Flashing Updates

SL4B includes some code to enhance updates with flashing effects. These are enabled through the enableflash attribute in the common-attributes.js file. To use them, we modify the code slightly. I've also changed the code, so the constructor takes in the list of objects and fields to subscribe to. Parameterising the class in this way makes it more general and easier to reuse. 

function ExampleSubscriber(sObjects, sFields)
{			
	this.sObjects = sObjects;
	this.sFields = sFields;
	// Any subclass of SL4B_AbstractSubscriber must call initialise in its constructor.
	// Once initialisation is finished, SL4B will call ready() on this object.
	this.initialise();
}

// Declares that the ExampleSubscriber is a subclass of SL4B_AbstractSubscriber
ExampleSubscriber.prototype = new SL4B_AbstractSubscriber();

ExampleSubscriber.prototype.ready = function() {
	// The objects to subscribe to are passed as a space separated list.
	SL4B_Accessor.getRttpProvider().getObjects(this, this.sObjects, this.sFields);
};

ExampleSubscriber.prototype.recordMultiUpdated = function(sObjectName, oFieldData) {
	for (var i = 0, size = oFieldData.size(); i < size; i = i + 1) {
		var sFieldName = oFieldData.getFieldName(i);
		var sFieldValue = oFieldData.getFieldValue(i);
		
		// This is one simple technique for turning an object name and a field name into a html element id.
		// Remove most of the beginning, replace / with _s and append the fieldname.  These ids now match
		// the id's I've specified in the table lower down.
		var elemId = sObjectName.substring(18).replace(/\//g, '_')+"_"+sFieldName;
		var oUpdate = RTSL_CreateUpdate(elemId, "Relative", sFieldValue, false, false, null, 1000);
		RTSL_DisplayUpdate(oUpdate);
	}
};

var Subscriber = new ExampleSubscriber("/Examples/Records/FX/GBP /Examples/Records/FX/EUR /Examples/Records/FX/CAD", "dBestBid,dBestAsk");

The result of the above code can be seen on this page.

Multiple Subscribers

Now that there are no specific reference to the fields and objects within the example subscriber code, it is easy to use the same code more than once, it's simply a matter of creating HTML code with the appropriate ids and creating a new subscriber. 

<table border="1" cellpadding="3" cellspacing="0">
	<thead>
		<tr><th>Ticker</th><th>Bid</th><th>Ask</th><th>Last</th><th>Change</th></tr>
	</thead>
	<tbody>
		<tr><td>AAPL</td><td id='Stocks_AAPL_dBestBid'>-</td><td id='Stocks_AAPL_dBestAsk'>-</td><td id='Stocks_AAPL_dLast'>-</td><td id='Stocks_AAPL_dNet.Chng'>-</td></tr>
		<tr><td>MSFT</td><td id='Stocks_MSFT_dBestBid'>-</td><td id='Stocks_MSFT_dBestAsk'>-</td><td id='Stocks_MSFT_dLast'>-</td><td id='Stocks_MSFT_dNet.Chng'>-</td></tr>
		<tr><td>CSCO</td><td id='Stocks_CSCO_dBestBid'>-</td><td id='Stocks_CSCO_dBestAsk'>-</td><td id='Stocks_CSCO_dLast'>-</td><td id='Stocks_CSCO_dNet.Chng'>-</td></tr>
		<tr><td>INTC</td><td id='Stocks_INTC_dBestBid'>-</td><td id='Stocks_INTC_dBestAsk'>-</td><td id='Stocks_INTC_dLast'>-</td><td id='Stocks_INTC_dNet.Chng'>-</td></tr>
	</tbody>
</table>

<script type="text/javascript">
	var Subscriber = new ExampleSubscriber("/Examples/Records/Stocks/AAPL /Examples/Records/Stocks/MSFT /Examples/Records/Stocks/CSCO /Examples/Records/Stocks/INTC", "dBestBid,dBestAsk,dLast,dNet.Chng");
</script>

The result of the above code can be seen on this page.