JavaScript Client Guide

Target API: Lightstreamer JavaScript Client v. 6.1.4

Last updated: 15!"#!14
Table of contents
1 INTRODUCTION................................................................................................................3
2 JAVASCRIPT CLIENT DEVELOPMENT.........................................................................................4
2.1 Deployment Ar!"tet#re..................................................................................4
2.1.1 Deployment $n% &ro'(er(................................................................................4
2.2 S"te)Appl"$t"on Ar!"tet#re.............................................................................*
2.3 T!e L"+!t(tre$merCl"ent...................................................................................,
2.3.1 U("n+ $n AMD lo$%er........................................................................................-
2.3.2 U("n+ .lo/$l O/0et(........................................................................................1
2.3.3 N$me Cl$(!e(................................................................................................12
2.3.4 L"+!t(tre$merCl"ent "n $ 3e/ 3or4er...............................................................11
2.3.* T!e No%e.0( $(e............................................................................................12
2.4 T!e S#/(r"pt"on L"(tener(..............................................................................13
2.4.1 St$t".r"%.......................................................................................................13
2.4.2 Dyn$.r"%.......................................................................................................14
2.* &#"l%"n+.........................................................................................................1*
2.*.1 Re5#"reJS opt"m"6$t"on tool 7r.0(8.....................................................................1*
2., Tro#/le(!oot"n+.............................................................................................1,
2.,.1 C!e4 9or e:ept"on(......................................................................................1,
2.,.2 Ser;er<(ent error(..........................................................................................1,
2.,.3 Lo++"n+.........................................................................................................1-
2.,.4 St"ll "n tro#/le.................................................................................................1=
$ # $
1 Introduction
This d%cument pr%vides a c%nceptual intr%ducti%n t% the devel%pment %& Lightstreamer Clients 'ased
%n JavaScript.
A &ull JavaScript API reference is availa'le '%th %nline and (ithin the s%&t(are distri'uti%n:
)nline JS*%c: http:(((.lightstreamer.c%md%csclient+,avascript+uni+apiinde-.html
.undled JS*%c: /Lightstreamer*)CS$S*0ssd1+client+,avascriptd%cAPI$re&erence$
inde-.html/
$ 2 $
# JavaScript Client Development
The Lightstreamer Javascript Client is a set %& JavaScript classesm%dules that can 'e included
int% an3 4e' site5 6T7L5 applicati%n5 %r JavaScript applicati%n in general in %rder t% ma1e it
/Lightstreamer$ena'led/5 that is5 read3 t% receive and send real$time data &r%mt% Lightstreamer
Server.
The JavaScript client li'rar35 in the 'asic &%rm pr%vided in the distri'uti%n5 is c%mprised %& %ne single
JavaScript &ile5 lightstreamer.s5 that c%ntains all %& the availa'le classes8 in this &%rm5 it als%
re9uires an A7* l%ader t% 'e used. It is p%ssi'le t% cust%mi:e the li'rar3 t% %nl3 include the desired
classes and t% 'e usa'le (ith%ut an3 A7* l%ader '3 the means %& a generat%r distri'uted (ith the
li'rar3 itsel&. The generat%r is in the &%rm %& a simple 6T7L &ile: generator.html. An alread3
cust%mi:ed versi%n %& the li'rar35 lightstreamer!node.s5 is als% included in the distri'uti%n8 this
versi%n %nl3 c%ntains classes c%mpati'le (ith ;%de.,s.
#.1 *epl%3ment Architecture
<%r dem% purp%se5 Lightstreamer Server c%ntains an internal (e' server that is a'le t% serve static
(e' res%urces. This ma1es it simple t% distri'ute %ut$%&$the$'%- dem%s =such as the St%c1$List
*em%> and t% get started (ith Lightstreamer devel%pment. .ut &%r actual pr%,ects and pr%ducti%n
scenari%s5 it is highl3 rec%mmended that an e-ternal (e' server is used ='ecause Lightstreamer is
%ptimi:ed &%r pushing real$time data5 n%t &%r serving static pages>.
T3picall35 a Lightstreamer Server and an3 c%mm%n (e' server =e.g. Apache5 ngin-5 IIS %r an3 %ther
(e' server %& 3%ur ch%ice> are depl%3ed in the *7? net(%r1. Lightstreamer Server gets the data and
metadata &r%m the 'ac1$end servers that are pr%tected '3 the sec%nd &ire(all. The (e' 'r%(ser gets
the static (e' pages5 as usual5 &r%m 3%ur (e' server5 then it c%nnects t% Lightstreamer Server t%
receive the &l%( %& real$time updates. )& c%urse5 '%th servers can 'e clustered &%r &ail$%ver and l%ad
'alancing.
It is als% p%ssi'le t% let a 'r%(ser l%ad the static (e' pages directl3 &r%m the &ile s3stem %& the client
machine5 a case that is use&ul during devel%pment and testing.
".#.# Deplo$ment and %ro&sers
Depen%"n+ on t!e !o(en %eployment $r!"tet#re> on t!e /ro'(er "n #(e> $n% on (ome
on9"+#r$t"on p$r$meter(> t!e J$;$Sr"pt Cl"ent l"/r$ry '"ll try to onnet to t!e %e("+n$te%
L"+!t(tre$mer Ser;er "n t!e /e(t po(("/le '$y.
$ 4 $
3"t! pre;"o#( ;er("on( o9 t!e ?TML)JS L"+!t(tre$mer l"ent l"/r$ry> "t '$( m$n%$tory t!$t t!e
3e/ (er;er $n% t!e L"+!t(tre$mer (er;er shared the same domain name 7e.+.
'''.myomp$ny.om $n% re$lt"me.myomp$ny.om8. St$rt"n+ 9rom J$;$Sr"pt Cl"ent l"/r$ry
,.2> t!"( "( no longer required> e;en "9 t!ere $re $(e( '!ere t!"( m"+!t /e #(e9#l. A
(pre$%(!eet "( $;$"l$/le onl"ne> '!"! (#mm$r"6e( t!e l"ent<("%e om/"n$t"on( $n% t!e
"n(tr#t"on( on '!"! (ett"n+( to #(e to +#$r$ntee t!$t $n opt"m$l onnet"on "( e(t$/l"(!e%.
See t!e le+en% on t!e (eon% t$/ to le$rn $/o#t t!e me$n"n+ o9 e$! ol#mn@
Lightstreamer JS Client - Deployment Config Matrix
AAB http://goo.gl/ry2ffs
.asicall35 '3 still sharing the same d%main name 'et(een the 4e' server and the
Lightstreamer server5 and setting such d%main e-plicitl3 in the page5 3%u guarantee that
streaming m%de (%r1s acr%ss all 'r%(sers5 including %lder I@ versi%ns. )ther(ise5 %n these
'r%(sers s%me &%rm %& p%lling m%de (ill 'e aut%maticall3 selected instead %& streaming. <%r
man3 1inds %& applicati%ns5 3%u (ill n%t pr%'a'l3 need t% care that streaming m%de is al(a3s
ena'led. .ut &%r ver3 high$per&%rmance applicati%ns =high thr%ughput and l%( latenc3> that
re9uire %ld$'r%(ser c%mpati'ilit35 3%u might pre&er t% 1eep the same$d%main rule.
'(T) (' CL*ST)+I'G: @-cept &%r the 7%derat% versi%n %& Lightstreamer5 using multiple
instances %& Lightstreamer Server in a cluster is supp%rted. In this scenari%5 as e-plained in
Clustering.pd&5 Astic1inessB can 'e achieved '3 leveraging the Cc%ntr%l+lin1+addressD
c%n&igurati%n8 in this case a &urther n%te %n the server side c%n&igurati%n applies.
In &act5 (hen Cc%ntr%l+lin1+addressD is c%n&igured5 the access t% the Server can als% ta1e
place thr%ugh the speci&ied h%stname. This means that (henever the pages set their
document.domain pr%pert3 t% ena'le access t% the Server data5 the Cc%ntr%l+lin1+addressD
setting sh%uld 'e set c%nsistentl3 (ith the d%main speci&ied. 7%re precisel35 this is needed
%nl3 (hen the d%main chec1 is reall3 per&%rmed '3 the 'r%(ser8 (ith re&erence t% the
a&%rementi%ned Deplo$ment Config ,atri-5 this %ccurs in all cases in (hich a re9uirement
%n Call%(ed+d%mainD is stated.
<urtherm%re5 &%r this same set %& cases5 an3 setting %& Cc%ntr%l+lin1+machine+nameD (%uld
%verride the setting %& Cc%ntr%l+lin1+addressD8 this (%uld 'e the %nl3 (a3 t% ena'le
multih%sting5 that is5 the use %& multiple h%stnames5 'el%nging t% di&&erent d%mains5 t% access
the site. I& the Cc%ntr%l+lin1+machine+nameD setting is leveraged5 then the c%nsistenc3 %& the
Ac%ntr%l lin1B (ith the document.domain setting is alread3 guaranteed.
.I'T: In case 3%u need t% test a depl%3ment scenari%5 inv%lving speci&ic h%stnames and
d%main names &%r the 4e' server and the Lightstreamer server5 and 3%u are devel%ping %n a
stand$al%ne machine (ith%ut a *;S =s% 3%u pr%'a'l3 have Lightstreamer Server and the 4e'
server %n the same machine %n di&&erent p%rts>5 3%u can simulate the &inal envir%nment '3
editing the h%st &ile %& 3%ur machine. <%r e-ample5 in a 4ind%(s envir%nment5 3%u (ill edit the
/C:E4I;*)4SEs3stem2#EdriversEetcEh%sts/ &ile and add s%mething li1e:
1#".!.!.1 (((.m3c%mpan3.c%m
1#".!.!.1 realtime.m3c%mpan3.c%m
#.# SiteApplicati%n Architecture
@ach page %& the site that is g%ing t% receive and%r send real$time updates &r%mt% Lightstreamer
Server must include a LightstreamerClient instance5 (hich transparentl3 manages the c%nnecti%ns
t% Lightstreamer Server.
$ 5 $
I& 3%u have multiple pages %r page instances %& 3%ur site %pen at the same time (ithin di&&erent
'r%(ser ta's %r (ind%(s5 3%u might (ant di&&erent LightstreamerClient instances t% share the
same sessi%n and c%nnecti%n5 t% av%id saturating the 'r%(ser c%nnecti%n p%%l =i& applica'le> and%r
t% av%id %pening several sessi%ns &%r the same user. F%u can achieve that '3 leveraging the
ConnectionSharing instance availa'le %n each LightstreamerClient. 4hen di&&erent
LightstreamerClient instances share the same c%nnecti%n there is %ne single instance h%lding the
c%nnecti%n8 such instance is called the ,aster LightstreamerClient =%r simpl3 7aster Client> (hile
the %thers are re&erred t% as Slaves. In case the 7aster LightstreamerClient is terminated =e.g. its
ta' is cl%sed>5 the Slave LightstreamerClients (ill aut%maticall3 and transparentl3 elect a ne(
7aster5 (hich (ill rest%re the c%nnecti%n and all the su'scripti%ns.
'(T): In case the document.domain pr%pert3 is set %n the page h%sting the 7aster Client5
an3 %ther page %& the site that (ants t% h%st a Slave Client needs t% set its d%cument d%main
t%%. Gice versa5 i& the document.domain pr%pert3 is n%t set %n the page h%sting the 7aster
Client5 an3 %ther page %& the site that (ants t% h%st a Slave Client cann%t set its %(n
d%cument d%main. The simplest (a3 t% 'e sure t% av%id an3 issue is t% set %r n%t set the
d%cument.d%main in all the pages %& the site.
S%5 (hen 3%u have multiple pages %pen at a time c%nnecting t% the same Lightstreamer applicati%n5
3%u (ill pr%'a'l3 share the sessi%nc%nnecti%n am%ng them. .ut (hat i& 3%u navigate 3%ur site
seriall35 page a&ter pageH The Lightstreamer sessi%n (ill %pen and cl%se %n each page5 'ecause the
LightstreamerClient %',ect is created and destr%3ed t%gether (ith the h%sting page. This is usuall3
accepta'le5 as the sessi%n creati%n is ver3 &ast =depending %n 3%ur cust%m server$side 7etadata
Adapter implementati%n5 &%r handling authenticati%n>. Sh%uld 3%u need t% persist the ph3sical
sessi%nc%nnecti%n acr%ss page navigati%n5 a s%luti%n (%uld 'e t% place the 7aster
LightstreamerClient inside a hidden &rame =%r i&rame>5 and per&%rm the actual site navigati%n in a
visi'le &rame =%r i&rame>. An e-ample %& this strateg3 is the pre$installed //ramed Stoc01List Demo/.
The user can navigate 'et(een t(% lists %& 15 st%c1s. @ach list is c%ntained in a separate page. The
7aster LightstreamerClient is l%aded in a hidden &rame %& the encapsulating &rameset5 s% that the
Lightstreamer sessi%n survives an3 page s(itch. S(itching 'et(een the t(% pages %riginates the
su'scripti%nsunsu'scripti%ns re9uests t% Lightstreamer Server as part %& the same sessi%n.
The lightstreamer.,s li'rar3 is designed t% (%r1 even %utside %& a 'r%(ser c%nte-t. This means 3%u
can use it (ithin an3 JavaScript$'ased envir%nment5 including 'ode.s5 PhoneGap5 SmartT25 and
%thers.
C%nnecti%n sharing 'et(een multiple instances %& LightstreamerClient is n%t supp%rted in these
c%nte-ts.
#.2 The LightstreamerClient
An 6T7L page5 pr%duced thr%ugh an3 1ind %& server techn%l%g3 =e.g. JSP5 ASP5 P6P5 ;%de.,s5 etc.>
can h%st a LightstreamerClient t% c%nnect t% a Lightstreamer Server.
As said a'%ve5 a ,aster LightstreamerClient =%r 7aster Client> is a LightstreamerClient instance
that has als% the resp%nsi'ilit3 %& h%lding the c%nnecti%n t% the Lightstreamer Server. A Slave
LightstreamerClient e-pl%its the c%nnecti%n h%ld '3 a 7aster Client t% su'scri'e its Su'scripti%ns t%
the Lightstreamer Server and t% receive real$time updates.
.el%( are the steps re9uired t% trans&%rm a n%rmal 6T7L page int% an 6T7L page receiving updates
&r%m a LightstreamerClient. =The c%de e-amples assume that the lightstreamer.s client li'rar3 and5
in the A7* case5 the A7* l%ader re3uire.s are depl%3ed under the /,s/ &%lder %& the (e' server8 see
secti%n #.1>.
;%te that '3 de&ault the li'rar3 is distri'uted in the 'asic A7* &%rm. )ther versi%ns %& the li'rar3 can
'e %'tained thr%ugh the generator.html &ile distri'uted (ith the li'rar3 itsel&.
$ 6 $
".4.# *sing an A,D loader
The As$nchronous ,odule Definition =A,D> API speci&ies a mechanism &%r de&ining
m%dules such that the m%dule and its dependencies can 'e as3nchr%n%usl3 l%aded. See
https:githu'.c%mamd,samd,s$api(i1iA7*
T% use the de&ault versi%n %& the Lightstreamer li'rar3 an A7* l%ader is needed. 4e suggest
using +e3uireJS: http:re9uire,s.%rg
A ver3 simple A7* l%ader5 that d%es n%t supp%rt d3namic l%ading %& .,s &iles5 can 'e
em'edded in the Lightstreamer.s thr%ugh the generator.html8 usage details can 'e &%und
%n the generat%r inline help. <%r the sa1e %& simplicit3 (e (ill assume the use %& the &ull$'l%(n
Ie9uireJS li'rar3.
. Include the libraries
As a ver3 &irst acti%n5 the 6T7L page sh%uld imp%rt5 in its 6@A* secti%n5 the re3uire.s
and lightstreamer.s JavaScript li'raries5 in this e-act %rder.
This can 'e d%ne thr%ugh the &%ll%(ing c%de:
<script src="/js/require.js"></script>
<script src="/js/lightstreamer.js"></script>
2. Include the st$le sheets
All the cascading st$le sheets =CSS> declared in the Lightstreamer &uncti%ns sh%uld 'e
de&ined %r lin1ed in the 6@A* secti%n %& the page.
!. (btain the LightstreamerClient class
)nce the li'raries are included5 a script element sh%uld 'e added t% include the
applicati%n c%de. In the A7* versi%n %& the li'rar3 n%ne %& the availa'le classes is
declared as a gl%'al %',ect %n the page: a call t% the re9uire meth%d %& the A7* l%ader in
use is needed t% %'tain the vari%us c%nstruct%rs. <%r n%( (e (ill %nl3 require the
LightstreamerClient class5 as sh%(n 'el%(. The c%de in the ne-t 'ullets (ill 'e placed in
the require call'ac1 =i.e.: (here the /C)*@ 6@I@/ c%mment is>.
<script>
require(["LightstreamerClient"],
function(LightstreamerClient) {
//C!" #"$"
%)&
</script>
". Create the LightstreamerClient obect
T% c%nnect t% a Lightstreamer Server5 a LightstreamerClient obect has t% 'e created5
c%n&igured5 and instructed t% c%nnect t% the Lightstreamer Server.
A minimal versi%n %& the c%de that creates a LightstreamerClient and c%nnects t% the
Lightstreamer Server %n http:push.m3c%mpan3.c%m (ill l%%1 li1e this:
var m'Client = new
LightstreamerClient("http(//push.m'c)mpan'.c)m",
"*'+,apter-et")&
m'Client.c)nnect()&
$ " $
In the e-ample a'%ve %nl3 a minimal c%n&igurati%n5 c%nsisting %& the address %& the server
and the Adapter Set t% 'e used5 is d%ne. A t3pical versi%n %& the script5 h%(ever5 (%uld
set %ne %r m%re LightstreamerClient pr%perties thr%ugh the setter meth%ds pr%vided &%r
the LightstreamerClient %',ect and its mem'er %',ects and (%uld als% add a listener &%r
the instance. Please5 c%nsult the JSDoc &%r details %n the LightstreamerClient5
C%nnecti%n*etails and C%nnecti%n)pti%ns classes.
#. Sharing a connection
As previ%usl3 stated5 it is p%ssi'le t% ma1e di&&erent LightstreamerClient instances share
the same c%nnecti%n.
.3 de&ault the c%nnecti%n is n%t shared s%5 'e&%re calling the c%nnect meth%d5 it is
necessar3 t% instruct the client %n the sharing p%licies t% 'e applied &%r the sharing t%
happen. I& such sharing is desired5 the a'%ve c%de (ill change li1e this:
var m'Client = new
LightstreamerClient("http(//push.m'c)mpan'.c)m")&
m'Client.c)nnecti)n-haring.ena.le-haring("*'+pplicati)n",
"+//+C#","C$"+/"")&
m'Client.c)nnect()&
/73Applicati%n/ is a uni9ue name &%r the applicati%n5 /ATTAC6/ is the p%lic3 t% 'e applied
i& a c%mpati'le c%nnecti%n is &%und and /CI@AT@/ is the p%lic3 t% 'e applied i& such a
c%nnecti%n is n%t &%und. In the a'%ve case (eJve instructed the client t% attach t% an
e-isting c%nnecti%n i& availa'le =thus 'ec%ming a Slave Client> %r t% create its %(n i& n%t
='ec%ming a 7aster Client>. C%nsult the JS*%c &%r details %n the availa'le p%licies and
their e&&ects.
$. (btain the Subscription class
<%r each su'scripti%n t% 'e su'scri'ed t% a Lightstreamer Server a Su'scripti%n instance
is needed. As a &irst step (e need t% e-tend %ur re9uire call t% als% include the
Su'scripti%n class:
<script>
require(["LightstreamerClient","-u.scripti)n"],
function(LightstreamerClient,-u.scripti)n) {
//C!" #"$"
%)&
</script>
%. Create a Subscription obect
)nce the Su'scripti%n class is availa'le5 an instance has t% 'e created and c%n&igured t%
descri'e the su'scripti%n (e are g%ing t% send t% the Lightstreamer Server. A simple
Su'scripti%n c%ntaining three items and three &ields t% 'e su'scri'ed in 7@IK@ m%de is
easil3 created =see Lightstreamer Keneral C%ncepts>:
var m'-u.scripti)n = new -u.scripti)n("*"$0"",["item1",
"item2", "item3"],["4iel,1", "4iel,2", "4iel,3"])&
Several c%n&igurati%n %pti%ns are availa'le. In particular5 in case the Adapter Set c%ntains
multiple *ata Adapters5 speci&3ing the name %& the *ata Adapter that supplies the items in
the su'scripti%n ma3 'e needed. This is acc%mplished thr%ugh a line %& c%de li1e the
&%ll%(ing:
m'-u.scripti)n.set!ata+,apter("*'!ata+,apter")&
$ L $
The su'scripti%n t% the server %& the ne(l3 created Su'scripti%n instance is per&%rmed
thr%ugh a simple call:
m'Client.su.scri.e(m'-u.scripti)n)&
;%te that %nce the Su'scripti%n is passed t% the LightstreamerClient as sh%(n a'%ve5 it
(ill 'e persisted acr%ss sessi%ns meaning that i& the 7aster Client disc%nnects &r%m the
server and then rec%nnects again there is n% need t% per&%rm a ne( su'scri'e call.
&. Listen for real1time updates
.e&%re sending the su'scripti%n t% the server5 usuall3 at least %ne listener is attached t%
the Su'scripti%n instance in %rder t% c%nsume the real$time updates. The &%ll%(ing c%de
sh%(s the value %& the /&ield1/ &ield in a JavaScript alert each time a ne( update is
received &%r the su'scripti%n:
m'-u.scripti)n.a,,Listener({
)n5tem6p,ate( function(up,ate.ject) {
alert(up,ate.ject.get7alue("4iel,1"))&
%
%)&
S%me read3$made Su'scripti%nListener classes are availa'le in the li'rar3. Such listeners
(ill 'e descri'ed in secti%n #.4
'. The complete code
.el%( is the c%mplete JavaScript c%de:
<script>
require(["LightstreamerClient","-u.scripti)n"],
function(LightstreamerClient,-u.scripti)n) {
var m'Client = new
LightstreamerClient("http(//push.m'c)mpan'.c)m")&

m'Client.c)nnecti)n-haring.ena.le-haring("*'+pplicati)n",
"+//+C#","C$"+/"")&
m'Client.c)nnect()&
var m'-u.scripti)n = new -u.scripti)n("*"$0"",["item1",
"item2", "item3"],["4iel,1", "4iel,2", "4iel,3"])&
m'-u.scripti)n.set!ata+,apter("*'!ata+,apter")&
m'-u.scripti)n.a,,Listener({
)n5tem6p,ate( function(up,ate.ject) {
alert(up,ate.ject.get7alue("4iel,1"))&
%
%)&
m'Client.su.scri.e(m'-u.scripti)n)&
%)&
</script>
".4." *sing Global (bects
I& the use %& an A7* l%ader is n%t desired5 it is p%ssi'le t% generate a Lightstreamer
JavaScript Client li'rar3 that declares its classes in the gl%'al namespace.
$ M $
1. Generate the librar$
T% create such a li'rar3 the generator.html must 'e l%aded inside a 'r%(ser and
c%n&igured (ith the /Nse gl%'als/ %pti%n selected. )nce the /Create li'rar3/ 'utt%n has
'een clic1ed the resulting li'rar3 (ill 'e created in the te-t$area %n the '%tt%m %& the
generat%r. C%p3 the sh%(n te-t inside a te-t edit%r and save as lightstreamer.s.
2. Include the librar$
As the A7* l%ader is n% l%nger needed there is %nl3 %ne li'rar3 t% 'e included:
<script src="/js/lightstreamer.js"></script>
3. The complete code
The c%de %& the applicati%n remains 9uite the same as the previ%us e-ample
e-cluding the re9uire (rapping:
<script>
var m'Client = new
LightstreamerClient("http(//push.m'c)mpan'.c)m")&
m'Client.c)nnecti)n-haring.ena.le-haring("*'+pplicati)n",
"+//+C#","C$"+/"")&
m'Client.c)nnect()&
var m'-u.scripti)n = new -u.scripti)n("*"$0"",["item1",
"item2", "item3"],["4iel,1", "4iel,2", "4iel,3"])&
m'-u.scripti)n.set!ata+,apter("*'!ata+,apter")&
m'-u.scripti)n.a,,Listener({
)n5tem6p,ate( function(up,ate.ject) {
alert(up,ate.ject.get7alue("4iel,1"))&
%
%)&
m'Client.su.scri.e(m'-u.scripti)n)&
</script>
".4.4 'ame Clashes
4hen (%r1ing %n 'ig 6T7L &r%nt$end including di&&erent JavaScript li'raries5 s%me name
c%llisi%ns ma3 %ccur in '%th the A7* and Kl%'al cases. The generat%r %&&ers t(% %pti%ns5
namel3 *se namespaced globals and *se A,D &ith namespaced names5 that can 'e
used t% generate a li'rar3 that prevents such c%llisi%ns &r%m happening.
$ 1! $
. A,D case
In the A7* case the %nl3 di&&erence is in the names used in the &irst parameter %& the
re9uire call:
<script>
require(["Lightstreamer/LightstreamerClient",
"Lightstreamer/-u.scripti)n"],
function(LightstreamerClient,-u.scripti)n) {
//C!" #"$"
%)&
</script>
ever3thing else remains as is in the n%rmal A7* case.
2. Globals case
The Kl%'als case needs a little m%re (%r1 'ecause the Lightstreamer. pre&i- has t% 'e
added t% the c%nstruct%r names each time an instance %& %ne %& the classes &r%m the
Lightstreamer li'rar3 is needed. In the a'%ve e-amples t(% instances =%ne
LightstreamerClient and %ne Su'scripti%n> are generated. The related c%de (ill then
'ec%me li1e this:
var m'Client = new
Lightstreamer.LightstreamerClient("http(//push.m'c)mpan'.c)m")&
var m'-u.scripti)n = new Lightstreamer.-u.scripti)n("*"$0"",
["item1", "item2", "item3"],["4iel,1", "4iel,2", "4iel,3"])&
".4.6 LightstreamerClient in a 7eb 7or0er
A LightstreamerClient instance can als% 'e used inside a 4e'4%r1er even th%ugh in this case
c%nnecti%n sharing is disa'led. Als% n%te that the Lightstreamer JavaScript Client li'rar3
cann%t 'e used inside a 4%r1er i& the target 'r%(ser is )pera.
. Create a 7or0er
T% l%ad the client in a 4%r1er a 4%r1er is needed &irst. A listener %n the (%r1er can 'e
used t% receive messages &r%m the (%r1er itsel&. Simpl3 put the &%ll%(ing c%de in a
6T7L &ile
<script>
var 8)r9er = new :)r9er(;in,e<.js;)&
8)r9er.a,,"=entListener(;message;, function(e=ent) {
alert(e=ent.,ata)&
%)&
</script>
$ 11 $
2. Prepare the 7or0er Code
The inde-.,s &ile speci&ied in the a'%ve c%de (ill c%ntain the JavaScript c%de used t%
c%nnect t% a Lightstreamer Sever. It starts including the needed li'raries
imp)rt-cripts("require.js")&
imp)rt-cripts("lightstreamer.js")&
then the same c%de sh%(n in the A7* e-ample can 'e used =c%mprised %& the
require call> (ith %nl3 %ne single di&&erence5 that is5 a di&&erent appr%ach is used t%
c%nsume the Su'scripti%n data: such data is sent 'ac1 as an event using the
p%st7essage &acilit3 =n%te that the alert meth%d is n%t even availa'le in the 4%r1er
c%nte-t>:
m'-u.scripti)n.a,,Listener({
)n5tem6p,ate( function(up,ate.ject) {
p)st*essage(up,ate.ject.get7alue("4iel,1"))&
%
%)&
".4.8 The 'ode.s case
4hen the li'rar3 is used inside ;%de.,s5 %nl3 the A7* cases are supp%rted. 7%re%ver %nl3
part %& the availa'le classes is c%mpati'le (ith ;%deJS =as sh%(n in the generator.html> and
s%me third$part3 li'rar3 need t% 'e installed via npm &%r the LightstreamerClient t% (%r1.
1. Install the re3uired libraries using npm
Paste the &%ll%(ing lines in a c%mmand line t% install the re9uired li'raries =n%te that
npm has t% 'e alread3 installed in the s3stem>
npm install requirejs
npm install <mlhttprequest
npm install 4a'e>8e.s)c9et
". Include and configure +e3uireJS
At the start %& the inde-.,s &ile that (ill c%ntain the JavaScript c%de %& the applicati%n
include the &%ll%(ing lines:
var requirejs = require(;requirejs;)&
requirejs.c)n4ig({
,eps( ["lightstreamer.js"],
n),e$equire( require
%)&
4. Prepare the code
$ 1# $
Again the applicati%n c%de (ill 'e 9uite the same as the %ne %& the A7* case (ith t(%
small changes.
The re9uire call (ill 'e trans&%rmed int% a re9uire,s call:
requirejs(["LightstreamerClient","-u.scripti)n"],
function(LightstreamerClient,-u.scripti)n) {
//C!" #"$"
%)&
as the alert meth%d is n%t availa'le in ;%deJS a di&&erent appr%ach is used t%
c%nsume the Su'scripti%n data: such data is printed %n screen using the c%ns%le.l%g
&acilit3:
m'-u.scripti)n.a,,Listener({
)n5tem6p,ate( function(up,ate.ject) {
c)ns)le.l)g(up,ate.ject.get7alue("4iel,1"))&
%
%)&
6. +un the application
As (ith an3 ;%de.,s applicati%n5 simpl3 run the created inde-.,s &ile (ith the &%ll%(ing
c%de:
n),e in,e<.js
#.4 The Su'scripti%n Listeners
The Lightstreamer JavaScript Client Li'rar3 includes s%me SubscriptionListener implementati%ns
that can 'e used in an 6T7L page t% sh%( the data received %n a Su'scripti%n.
.el%( is a descripti%n %& the t(% main implementati%ns: StaticGrid and D$naGrid. Actuall35 such
classes can als% 'e used (ith%ut listening %n Su'scripti%n %',ects5 'ut such usage is %ut %& the sc%pe
%& this d%cument.
In the &%ll%(ing descripti%n the term cell is used t% re&er t% the at%mic unit3 %& visuali:ati%n &%r data
pushed '3 Lightstreamer and ass%ciated t% a field =see Keneral C%ncepts>.
In %rder t% declare a cell5 a special DI2 element %r a special SPA' element sh%uld 'e used. It is
p%ssi'le t% ch%%se 'et(een a *IG and a SPA; tag &%r each cell5 acc%rding t% the &r%nt$end
re9uirements
1
. Alternative (a3s &%r suppl3ing push cells are availa'le5 (hich all%( the use %& an3 1ind
%& tag. See the JS*%c &%r details.
".6.# StaticGrid
In a StaticKrid each cell is staticall3 de&ined in the 6T7L page.
@ach cell &%r this 1ind %& grid can de&ine the &%ll%(ing special pr%perties:
Omandat%r3P data1source: this special pr%pert3 must 'e speci&ied (ith its value 'eing
/lightstreamer/ in %rder t% auth%ri:e the StaticKrid t% use such 6T7L element as a
cell.
Omandat%r3P data1grid: an identi&ier that is used t% ass%ciate a cell (ith a StaticKrid
instance: the same value has t% 'e speci&ied in the c%nstruct%r %& the said StaticKrid.
1
See !ttp@))'''.'3.or+)TR)REC<!tml42)(tr#t)+lo/$l.!tmlC!<-.*.4 9or $ 9orm$l (pe"9"$t"on o9 t!e %"99erene /et'een DIV
$n% SPAN.
$ 12 $
Omandat%r3P data1ro&: a num'er representing the r%( num'er this cell is ass%ciated
(ith. As all the cells have t% 'e manuall3 de&ined5 the num'er %& r%(s in the grid is
de&ined '3 the 'iggest value %& this pr%pert3 in all the cells related t% the StaticKrid
=n%te that data1item can 'e used instead %& data$r%( in s%me special cases. Chec1
the JS*%c &%r details>.
Omandat%r3P data1field: the name %& the &ield t% 'e ass%ciated (ith the cell =it can als%
'e a &ield inde-5 see the JS*%c &%r details>
O%pti%nalP data1num: i& there is the re9uirement t% have m%re cells related t% the same
r%(&ield pair5 it is p%ssi'le t% speci&3 this pr%pert3 in %rder t% distinguish 'et(een such
cells (hen handling the StaticKrid events.
O%pti%nalP data1update: '3 de&ault the c%ntent %& a cell is updated (ith the received
values. .3 speci&3ing this pr%pert35 it is p%ssi'le t% target an3 pr%pert3 %& the 6T7L
element =e.g.: the src pr%pert3 %& an I7K tag> %r its st3lesheet.
O%pti%nalP data1fieldt$pe The StaticKrid class %&&ers the e-tract<ieldList and
e-tractC%mmandSec%ndLevel<ieldList &uncti%ns t% read &r%m the html the data$&ield
values %& the ass%ciated cells. Nsing this pr%pert3 is p%ssi'le t% speci&3 i& a &ield has t%
'e e-tracted during e-tract<ieldList e-ecuti%ns =missing data$&ieldt3pe pr%pert3 %r
A&irst$levelB value>5 during e-tractC%mmandSec%ndLevel<ieldList =data$&ieldt3pe set t%
Asec%nd$levelB> %r neither =data$&ieldt3pe set t% Ae-traB>
Example (HTML part)
...
<,i= ,ata>s)urce="lightstreamer" ,ata>gri,="qu)tes" ,ata>r)8="1"
,ata>4iel,="4iel,1">></,i=>
<,i= ,ata>s)urce="lightstreamer" ,ata>gri,="qu)tes" ,ata>r)8="1"
,ata>4iel,="4iel,2">></,i=>
<,i= ,ata>s)urce="lightstreamer" ,ata>gri,="qu)tes" ,ata>r)8="2"
,ata>4iel,="4iel,1">></,i=>
<,i= ,ata>s)urce="lightstreamer" ,ata>gri,="qu)tes" ,ata>r)8="2"
,ata>4iel,="4iel,2">></,i=>
...
Example (JavaScript part)
new -tatic0ri,("qu)tes",true)&
)nl3 the 'asic 'its %& the StaticKrid are descri'ed in this guide8 chec1 %ut the JS*%c &%r all
the details.
".6." D$naGrid
In a *3naKrid %nl3 %ne r%( %& cells is de&ined in the 6T7L page =the template>. ;e( r%(s
are then cl%ned &r%m the given template r%(. The template r%( (ill 'e ass%ciated t% the
*3naKrid instance via its id pr%pert3 and (ill c%ntain all %& the necessar3 cells. The data$
s%urce pr%pert3 %& this template has t% 'e c%n&igured as i& it (as a cell.
@ach cell &%r this 1ind %& grid can de&ine the &%ll%(ing special pr%perties:
Omandat%r3P data1source: this special pr%pert3 must 'e speci&ied (ith its value 'eing
/lightstreamer/ in %rder t% auth%ri:e the StaticKrid t% use such 6T7L element as a
cell.
Omandat%r3P data1field: the name %& the &ield t% 'e ass%ciated (ith the cell =it can als%
'e a &ield inde-5 see the JS*%c &%r details>
O%pti%nalP data1num: i& there is the re9uirement t% have m%re cells related t% the same
&ield5 it is p%ssi'le t% speci&3 this pr%pert3 in %rder t% distinguish 'et(een such cells
(hen handling the *3naKrid events.
O%pti%nalP data1update: '3 de&ault the c%ntent %& a cell is updated (ith the received
values. .3 speci&3ing this pr%pert3 it is p%ssi'le t% target an3 pr%pert3 %& the 6T7L
element =e.g.: the src pr%pert3 %& an I7K tag> %r its st3lesheet.
$ 14 $
O%pti%nalP data1fieldt$pe The StaticKrid class %&&ers the e-tract<ieldList and
e-tractC%mmandSec%ndLevel<ieldList &uncti%ns t% read &r%m the html the data$&ield
values %& the ass%ciated cells. Nsing this pr%pert3 is p%ssi'le t% speci&3 i& a &ield has t%
'e e-tracted during e-tract<ieldList e-ecuti%ns =missing data$&ieldt3pe pr%pert3 %r
A&irst$levelB value>5 during e-tractC%mmandSec%ndLevel<ieldList =data$&ieldt3pe set t%
Asec%nd$levelB> %r neither =data$&ieldt3pe set t% Ae-traB>
Example (HTML part)
...
<,i= i,="qu)tes" ,ata>s)urce="lightstreamer">
<,i= ,ata>s)urce="lightstreamer" ,ata>4iel,="4iel,1">></,i=>
<,i= ,ata>s)urce="lightstreamer" ,ata>4iel,="4iel,2">></,i=>
</,i=>
...
Example (JavaScript part)
new !'na0ri,("qu)tes",true)&
#.5 .uilding
4hen using an A7* l%ader it is e-pected &%r the cust%m JS c%de t% 'e splitted in a series %& small
m%dules each %ne in its %(n .,s &ile. This is a ver3 g%%d appr%ach during devel%pment as it permits t%
have a (ell %rgani:ed pr%,ect and (ell structured c%de. Nn&%rtunatel3 that appr%ach is n%t suita'le t%
depl%3 the pr%,ect %n the (e' since each JS m%dule (ill re9uire the 'r%(ser t% per&%rm a 6TTP K@T
re9uest t% the (e' server t% 'e d%(nl%aded thus increasing l%ad times.
S%me t%%ls e-ist that s%lve this pr%'lem '3 c%m'ining ,s &iles t%gether t% ma1e them Adepl%3$&riendl3B.
4hen using such t%%ls it is imp%rtant t% 'e a'le t% instruct the pr%cess t% av%id searching &%r
Lightstreamer m%dules since such m%dules are alread3 c%mpressed in %ne single &ile.
".8.# +e3uireJS optimi9ation tool :r.s;
Ie9uireJS %&&ers an %ptimi:ati%n t%%l that is per&ect &%r the tas1. It c%m'ines A7* m%dules
&iles t%gether8 it als% leverages either K%%gle Cl%sure C%mpiler %r Ngli&3JS t% &urther
c%mpress and %ptimi:e the JavaScript c%de t% 'e depl%3ed.
T% run it re9uires either Ihin% %r ;%de.,s =(hen used (ith ;%de.,s it d%es n%t supp%rt the
K%%gle Cl%sure C%mpiler>. F%u can &ind a &ull descripti%n %& the t%%l %n its (e'site.
4hen preparing its c%n&igurati%n &ile it is p%ssi'le t% speci&3 (hich m%dules d% n%t need t%
'e res%lved and c%ncatenated (ith the rest %& the c%de '3 using the paths %pti%n:
A,D version
paths( {
"LightstreamerClient"( "empt'(",
"-u.scripti)n"( "empt'("
%
A,D &ith namespaced names version<
paths( {
"Lightstreamer/LightstreamerClient"( "empt'(",
"Lightstreamer/-u.scripti)n"( "empt'("
%
$ 15 $
;)T@: the a'%ve e-amples assume that %nl3 LightstreamerClient and
-u.scripti)n classes are used &r%m the Lightstreamer li'rar38 %ne entr3 per each used
class is needed.
#.6 Tr%u'lesh%%ting
*uring devel%pment it is al(a3s p%ssi'le t% enc%unter issues preventing cust%m c%de &r%m (%r1ing as
e-pected. I& that happens 3%u can &%ll%( the tips in this secti%n t% s%lve the issues.
".=.# Chec0 for e-ceptions
The &irst thing t% l%%1 at (hen &acing an issue is the c%ns%le %& the 'r%(ser in use. 7%st
m%dern 'r%(sers %&&er s%me s%rt %& 'uilt$in JavaScript c%ns%le: &ire it up and rel%ad 3%ur
applicati%n8 i& there is a piece %& c%de thr%(ing an e-cepti%n it (ill 'e li1el3 sh%(n there.
".=." Server1sent errors
4hen c%nnecting t% a server5 su'scri'ing t% an item %r sending a message5 s%mething can
g% (r%ng due t% misc%n&igurati%n5 adapter err%rs %r server c%nstraints. In these cases the
server (ill send 'ac1 an err%r that (ill 'e e-p%sed %n the appr%priate listener=s>. F%u can
register a listener %n 3%ur %',ects t% receive such n%ti&icati%ns:
Connection errors
a ClientListener instance can 'e used t% receive err%r n%ti&icati%ns %n
LightstreamerClient instances. ;%te that the ClientListener inter&ace has s%me
meth%ds %ther than the err%r %ne that (eJre g%ing t% see n%(. See the JSDoc &%r &ull
details
var m'L-Client = new LightstreamerClient()&
m'L-Client.a,,Listener({
)n-er=er"rr)r( function(err)rC),e,err)r*essage) {
//here ')u can c)nsume the err)r
%
%)&
Subscription errors
a Su'scripti%nListener instance can 'e used t% receive err%r n%ti&icati%ns regarding
a Su'scripti%n. ;%te that the Su'scripti%nListener inter&ace has s%me meth%ds %ther
than the err%r %nes that (eJre g%ing t% see n%(. See the JSDoc &%r &ull details
var m'-u.scripti)n = new -u.scripti)n()&
m'-u.scripti)n.a,,Listener({
)n-u.scripti)n"rr)r( function(err)rC),e,err)r*essage) {
//here ')u can c)nsume the err)r
%,
)nC)mman,-ec)n,Le=el-u.scripti)n"rr)r(
function(err)rC),e,err)r*essage,relate,9e') {
//this )ne can )nl' .e 4ire, in case a t8)>le=el
su.scripti)n is create,
//here ')u can c)nsume the err)r
%
%)&
$ 16 $
,essage errors
a Client7essageListener instance can 'e used t% receive err%r n%ti&icati%ns %n sent
messages. ;%te that the Client7essageListener inter&ace has s%me meth%ds %ther
than the err%r %ne that (eJre g%ing t% see n%(. See the JSDoc &%r &ull details
m'L-Client.sen,*essage(m'*essage,m'-equence,m'/ime)ut,{
)n"rr)r( function(m'*essage) {
//here ')u can c)nsume the err)r
%,
)n!en'( function(m'*essage,,en'C),e,,en'*essage) {
//here ')u can c)nsume the err)r
%
%)&
".=.4 Logging
The Lightstreamer JavaScript client includes a simple L%ggerPr%vider l%gging inter&ace that
can 'e implemented t% c%nsume l%g messages &r%m (ithin the li'rar3.
A read3$made implementati%n %& such inter&ace5 t%gether (ith several l%g appender classes5 is
distri'uted (ith the li'rar3. The c%n&igurati%n %& this l%gging &acilit3 sh%uld 'e di&&erent 'et(een
devel%pment and pr%ducti%n envir%nments.
The suggested appr%ach is t% use a C%ns%leAppender c%n&igured at I;<) level during
devel%pment and a Iem%teAppender c%n&igured at @II)I level %r n% appenders at all %n
pr%ducti%n depl%3ments.
The l%g messages are als% identi&ied '3 a categ%r3. <%r &ull details a'%ut availa'le classes
and categ%ries c%nsult the JSDoc.
Development setup
*uring devel%pment (e suggest t% setup a C%ns%leAppender at I;<) level t% 1eep
an e3e %n (hat is happening %n the li'rar3. 7%st m%dern des1t%p 'r%(sers include
=%r can 'e e-tended (ith> a c%ns%le sh%(ing the messages pr%duced '3 such
appender. =e.g.: <ire'ug &%r <ire&%->.
T% setup such l%gging the &%ll%(ing c%de can 'e used:
require(["LightstreamerClient","-impleL)gger?r)=i,er",
"C)ns)le+ppen,er","L)g*essages"],
function(LightstreamerClient,-impleL)gger?r)=i,er,
C)ns)le+ppen,er,L)g*essages) {
var l)gger?r)=i,er = new -impleL)gger?r)=i,er()&
LightstreamerClient.setL)gger?r)=i,er(l)gger?r)=i,er)&
var m'+ppen,er = new C)ns)le+ppen,er("5@A","B")&
l)gger?r)=i,er.a,,L)gger+ppen,er(m'+ppen,er)&
%)&
$ 1" $
Production setup
*uring pr%ducti%n (e suggest t% rem%ve the C%ns%leAppender and add a
Iem%teAppender that (ill &%r(ard its messages t% the c%n&igured Lightstreamer
Server
T% setup such l%gging the &%ll%(ing c%de can 'e used =(here m3Client is the instance
%& LightstreamerClient c%nnected t% the server (here the l%gging has t% 'e sent>:
require(["LightstreamerClient","-impleL)gger?r)=i,er",
"$em)te+ppen,er","L)g*essages"],
function(sharingClient,LightstreamerClient,
-impleL)gger?r)=i,er,$em)te+ppen,er,L)g*essages) {
var l)gger?r)=i,er = new -impleL)gger?r)=i,er()&
LightstreamerClient.setL)gger?r)=i,er(l)gger?r)=i,er)&
var m'+ppen,er = new $em)te+ppen,er(""$$$","B",
m'Client)&
l)gger?r)=i,er.a,,L)gger+ppen,er(m'+ppen,er)&
%)&
;%te the L%g7essages m%dule that is re9uired 'ut never used. I& this m%dule is n%t re9uired
'3 the client JavaScript c%de5 %nl3 message c%des are pr%duced '3 the li'rar3. Simpl3
re9uiring this class (ill e-pand the l%g message c%des int% &ull string messages.
Nsing this appr%ach and the generator.html it is p%ssi'le t% generate a li'rar3 that d%es n%t
include an3 l%g message. ;%te that l%g c%des5 generated (hen the L%g7essages m%dule is
n%t included5 can al(a3s 'e trans&%rmed 'ac1 t% l%g messages later
require(["L)g*essages"], 4uncti)n(L)g*essages) {
L)g*essages.get*essage(c),e/)Ce/rans4)rme,)&
%)&
".=.6 Still in trouble
I9 none o9 t!e $/o;e (#++e(t"on( m$%e yo# 9"n% $ (ol#t"on to yo#r pro/lem( yo# $n re$!
o#t to o#r p#/l" 9or#m(.
$ 1L $