Lightstreamer Web Client Guide

Web Client Guide

Target API: Lightstreamer Web Client (Unified) v. 7.2.0

Last updated: 11/03/2019

Table of contents

1 INTRODUCTION...............................................................................................................3

2 WEB CLIENT DEVELOPMENT................................................................................................4

2.1 Deployment Architecture.................................................................................4

2.3.4 LightstreamerClient in a Web Worker..............................................................11

2.4 The Subscription Listeners.............................................................................12

2.4.1 StaticGrid......................................................................................................12

2.4.2 DynaGrid......................................................................................................13

2.5 Building........................................................................................................14

2.5.1 RequireJS optimization tool (r.js)....................................................................14

2.6 Troubleshooting............................................................................................15

2.6.1 Check for exceptions.....................................................................................15

2.6.2 Server-sent errors.........................................................................................15

2.6.3 Logging........................................................................................................16

Basically, by still sharing the same domain name between the Web server and the

Lightstreamer server, and setting such domain explicitly in the page, you guarantee that

streaming mode works across all browsers, including older IE versions. Otherwise, on these

browsers some form of polling mode will be automatically selected instead of streaming. For

many kinds of applications, you will not probably need to care that streaming mode is always

editing the host file of your machine. For example, in a Windows environment, you will edit the

"C:\WINDOWS\system32\drivers\etc\hosts" file and add something like:

NOTE: In case the document.domain property is set on the page hosting the Master Client,

any other page of the site that wants to host a Slave Client needs to set its document domain

too. Vice versa, if the document.domain property is not set on the page hosting the Master

Client, any other page of the site that wants to host a Slave Client cannot set its own

document domain. The simplest way to be sure to avoid any issue is to set or not set the

document.domain in all the pages of the site.

LightstreamerClient exploits the connection hold by a Master Client to subscribe its Subscriptions to

the Lightstreamer Server and to receive real-time updates.

Below are the steps required to transform a normal HTML page into an HTML page receiving updates

from a LightstreamerClient. (The code examples assume that the lightstreamer.js library and, in the

AMD case, the AMD loader require.js are deployed under the "/js" folder of the web server; see

section 2.1).

Note that by default the library is distributed in the basic AMD form. Other versions of the library can

be obtained through the generator.html file distributed with the library itself.

The Asynchronous Module Definition (AMD) API specifies a mechanism for defining

the generator inline help. For the sake of simplicity we will assume the use of the full-blown

RequireJS library.

As a very first action, the HTML page should import, in its HEAD section, the require.js

and lightstreamer.js JavaScript libraries, in this exact order.

This can be done through the following code:

<script src="/js/require.js"></script>

<script src="/js/lightstreamer.js"></script>

All the cascading style sheets (CSS) declared in the Lightstreamer functions should be

the require callback (i.e.: where the "CODE HERE" comment is).

});

Note that once the Subscription is passed to the LightstreamerClient as shown above, it

myClient.connect();

var mySubscription = new Subscription("MERGE",["item1",

"item2", "item3"],["field1", "field2", "field3"]);

mySubscription.setDataAdapter("MyDataAdapter");

mySubscription.addListener({

alert(updateObject.getValue("field1"));

}

});

myClient.subscribe(mySubscription);

});

a ClientMessageListener instance can be used to receive error notifications on sent

messages. Note that the ClientMessageListener interface has some methods other

than the error one that we're going to see now. See the JSDoc for full details

Note the LogMessages module that is required but never used. If this module is not required

by the client JavaScript code, only message codes are produced by the library. Simply

requiring this class will expand the log message codes into full string messages.

Using this approach and the generator.html it is possible to generate a library that does not

include any log message. Note that log codes, generated when the LogMessages module is

not included, can always be transformed back to log messages later