September 2014

Never memorize what you can look up in books.

- Albert Einstein
Page 1
Table of Contents
Mobile Applications...........................................................................................................................13
Types of Mobile App architectures...............................................................................................13
esign gui!elines for Mobile Apps...............................................................................................13
"orklight............................................................................................................................................1#
$eleases.........................................................................................................................................1#
Architecture........................................................................................................................................1#
A!apter %omponents.....................................................................................................................1&
Application %enter.........................................................................................................................1&
'nstallation..........................................................................................................................................1(
Prere)usites....................................................................................................................................1(
Parts *ist........................................................................................................................................1(
'nstalling "orklight +tu!io...........................................................................................................1(
'nstalling an An!roi! +, -clipse Plugin.....................................................................................3
%onfiguring the "orklight +tu!io embe!!e! Application +erver.................................................#
'nstalling Mobile Test "orkbench for "orklight..........................................................................&
'nstalling "orklight +erver............................................................................................................&
'nstalling the Application %enter...................................................................................................3/
'nstalling "A+ *iberty..................................................................................................................3/
0ther 'nstallation Tasks.................................................................................................................1#
+ources of 'nformation.......................................................................................................................1&
The 'nfo%enter...............................................................................................................................1&
'2M 3ome Page............................................................................................................................1&
$e!books.......................................................................................................................................1&
!eveloper"orks.............................................................................................................................1&
%ommunities..................................................................................................................................14
5ou Tube.......................................................................................................................................14
Application evelopment...................................................................................................................1(
"orklight +tu!io............................................................................................................................1(
%reating a "orklight Pro6ect.........................................................................................................1/
Anatomy of a Pro6ect.....................................................................................................................1/
Application escriptor...................................................................................................................#.
Application Architecture................................................................................................................#.
A!!ing targete! environments.......................................................................................................#.
"orklight evelopment +erver.....................................................................................................#3
eveloping 7' 8 $ich Page -!itor................................................................................................#1
esigning visually.....................................................................................................................#/
%o!ing in the 3TM* source.....................................................................................................&9
'mages an! graphics..................................................................................................................&9
0ff:line +torage.............................................................................................................................&1
The "orklight ;+0N+tore........................................................................................................&1
Push Notification...........................................................................................................................&.
Testing...........................................................................................................................................&.
7sing the Mobile 2rowser +imulator.......................................................................................&3
'nstalling the 7serAgent +witcher -<tension......................................................................&1
ebugging......................................................................................................................................&&
Artifact management......................................................................................................................&&
A!apters..............................................................................................................................................&/
A!apter Architecture......................................................................................................................&/
Page .
%reating a new A!apter.................................................................................................................49
A!apter 'mplementation................................................................................................................41
A!apter ;ava+cript implementation..........................................................................................41
A!apter Types................................................................................................................................4.
3TTP A!apter...........................................................................................................................4.
3TTP A!apter Proce!ure implementations.........................................................................43
%onfiguring the 3TTP A!apter for ++*..............................................................................41
-<ample 3TTP A!apter.......................................................................................................41
;M+ A!apter.............................................................................................................................4(
;M+ A!apter Proce!ure implementations............................................................................4/
+=* A!apter.............................................................................................................................(9
atabase ;2% rivers........................................................................................................(1
+=* A!apter Proce!ure implementations............................................................................(1
%ast 'ron A!apter......................................................................................................................(1
%alling an a!apter from the %lient.................................................................................................(.
-rror 3an!ling for A!apters..........................................................................................................(3
'nvoking ;ava co!e from an A!apter.............................................................................................(3
'2M "orklight %onsole.....................................................................................................................(#
Application %enter..............................................................................................................................(&
'nstalling the Application %enter mobile client.............................................................................(4
Performance......................................................................................................................................../.
Minification.................................................................................................................................../.
>ile %oncatenation........................................................................................................................./3
+ecurity.............................................................................................................................................../3
+ecure on:!evice store! !ata........................................................................................................./1
0ffline Authentication.................................................................................................................../1
Preventing tampere! apps............................................................................................................../1
irect 7p!ate................................................................................................................................./1
$emote isable............................................................................................................................../1
"orklight protecte! resources......................................................................................................./1
%ross site $-+T calls...................................................................................................................../#
Programatically authenticating with "A+..................................................................................../#
Application eployment..................................................................................................................../#
0perations.........................................................................................................................................19.
Programming $eferences.................................................................................................................19.
%lient +i!e AP' Programming.....................................................................................................193
"*.%lient................................................................................................................................193
The common ?options? ob6ect............................................................................................193
"*.%lient.a!!@lobal3ea!erAhea!erNameB hea!erCalueD.................................................193
"*.%lient.closeAD...............................................................................................................193
"*.%lient.connectAoptionsD...............................................................................................191
"*.%lient.!elete7serPrefAkeyB optionsD............................................................................191
"*.%lient.getAppPropertyApropertyNameD.......................................................................191
"*.%lient.get-nvironmentAD..............................................................................................191
"*.%lient.get*oginNameArealmD......................................................................................19#
"*.%lient.get7ser'nfoArealmB keyD...................................................................................19#
"*.%lient.get7serNameArealmD........................................................................................19#
"*.%lient.get7serPrefAkeyD..............................................................................................19#
"*.%lient.has7serPrefAkeyD..............................................................................................19#
"*.%lient.initAoptionsD......................................................................................................19&
Page 3
"*.%lient.invokeProce!ureAinvocationataB optionsD......................................................194
"*.%lient.is7serAuthenticate!ArealmD..............................................................................194
"*.%lient.logActivityAactivityTypeD.................................................................................194
"*.%lient.loginArealmB optionsD........................................................................................194
"*.%lient.logoutArealmB optionsD......................................................................................19(
"*.%lient.minimizeAD........................................................................................................19(
"*.%lient.reloa!AppAD......................................................................................................19(
"*.%lient.remove@lobal3ea!erAhea!erNameD.................................................................19(
"*.%lient.set3eart2eat'ntervalAintervalD..........................................................................19(
"*.%lient.set7serPrefAkeyB valueB optionsD......................................................................19(
"*.%lient.set7serPrefsAprefsB optionsD.............................................................................19/
"*.%lient.up!ate7ser'nfoAoptionsD...................................................................................19/
"*.2usy'n!icatorAcontainer'!B optionsD...........................................................................19/
"*.Toast.showAmessageD..................................................................................................119
"*.;+0N+tore.......................................................................................................................111
"*.;+0N+tore.a!!A!ataB optionsD.....................................................................................111
"*.;+0N+tore.changePasswor!Aol!Passwor!B newPasswor!B userNameD......................111
"*.;+0N+tore.closeAllAD..................................................................................................111
"*.;+0N+tore.countAD......................................................................................................111
"*.;+0N+tore.!estroyAD...................................................................................................111
"*.;+0N+tore.!ocumentifyAi!B !ataD...............................................................................111
"*.;+0N+tore.enhanceAnameB funcD................................................................................11.
"*.;+0N+tore.fin!A)ueryB optionsD..................................................................................11.
"*.;+0N+tore.fin!AllAoptionsD........................................................................................11.
"*.;+0N+tore.fin!2y'!Ai!D..............................................................................................11.
"*.;+0N+tore.getAcollectionNameD.................................................................................11.
"*.;+0N+tore.get-rrorMessageAerror%o!eD....................................................................113
"*.;+0N+tore.getPush$e)uire!AD....................................................................................113
"*.;+0N+tore.initAD..........................................................................................................113
"*.;+0N+tore.isPush$e)uire!A!ocD................................................................................111
"*.;+0N+tore.loa!AD........................................................................................................111
"*.;+0N+tore.pushA!ocsD................................................................................................111
"*.;+0N+tore.push$e)uire!%ountAD...............................................................................111
"*.;+0N+tore.removeA!ocB optionsD................................................................................111
"*.;+0N+tore.remove%ollectionAD..................................................................................111
"*.;+0N+tore.replaceA!ocB optionsD................................................................................11#
"*.;+0NM+tore.to+tringAD...............................................................................................11#
"*.evice...................................................................................................................................11#
"*.evice.getNetwork'nfoAcallbackD....................................................................................11#
0ther........................................................................................................................................11#
+erver +i!e AP' Programming....................................................................................................11&
"*.+erver...............................................................................................................................11&
"*.+erver.invoke+=*+tore!Proce!ureAoptionsD..............................................................11&
"*.+erver.create+=*+tatementAstatementD......................................................................11&
"*.+erver.invoke+=*+tatementAoptionsD........................................................................11&
"*.+erver.invoke3ttpAoptionsD.........................................................................................114
"*.+erver.rea!+ingle;M+MessageAoptionsD....................................................................1..
"*.+erver.rea!All;M+MessagesAoptionsD........................................................................1.3
"*.+erver.write;M+MessageAoptionsD.............................................................................1.3
"*.+erver.re)uest$eply;M+MessageAoptionsD................................................................1.1
Page 1
An!roi! evelopment......................................................................................................................1.#
'nstalling the An!roi! +,.........................................................................................................1.#
Managing the An!roi! +,........................................................................................................1.#
An!roi! -mulator........................................................................................................................1.#
;ava+cript >rameworks....................................................................................................................1.&
6=uery Mobile..............................................................................................................................1.&
o6o an! o6o Mobile.................................................................................................................1.&
+encha Touch...............................................................................................................................1.&
*ocal storage of !ata........................................................................................................................1.4
"eb Programming............................................................................................................................1.(
evelopment tools.......................................................................................................................1.(
ocument 0b6ect Mo!el 8 The 0M.........................................................................................1./
3TM*..........................................................................................................................................1./
'mages..........................................................................................................................................1./
;ava+cript.....................................................................................................................................139
;ava+cript 8 ate ob6ect..........................................................................................................139
7sing ;+3int...........................................................................................................................139
%alling ;ava+cript from ;ava..................................................................................................131
%asca!ing +tyle +heets 8 %++.....................................................................................................131
The ElessF language................................................................................................................13.
Cariables.............................................................................................................................13.
Mi<ins.................................................................................................................................13.
Nesting................................................................................................................................13.
0perations..........................................................................................................................13.
Timer base! functions..................................................................................................................13.
;+0N ata representation............................................................................................................133
;+0N within ;ava+cript..........................................................................................................133
;+0N within ;ava....................................................................................................................133
ates an! times within ;+0N.................................................................................................133
ebugging in the browser............................................................................................................133
*ogging to the browser console..............................................................................................131
console.!ebug.....................................................................................................................131
console.error.......................................................................................................................131
console.info........................................................................................................................13#
console.log..........................................................................................................................13#
console.warn.......................................................................................................................13#
o6o Programming...........................................................................................................................13&
o6o 'nformation +ources............................................................................................................13&
0ff:line !ocumentation...........................................................................................................13&
2uil!ing the AP' $eference ocumentation......................................................................13&
A!!ing @ri!G !ocumentation for off:line viewing...........................................................134
o6o @7' evelopment...............................................................................................................13(
*oa!ing o6o...............................................................................................................................13(
Asynchronous Mo!ule efinition AAMD..............................................................................13/
-vent 3an!ling............................................................................................................................119
$-+THA6a< calls..........................................................................................................................119
Testing $-+T %alls.................................................................................................................11.
o6o utility...................................................................................................................................11.
!o6oHIbaseHlang.......................................................................................................................11.
0M Access................................................................................................................................11.
Page #
!o6oH!om.................................................................................................................................113
!o6oH!om:construct.................................................................................................................113
!o6oH)uery...............................................................................................................................113
!o6oH!om:geometry.................................................................................................................11#
o6o ates an! Times..................................................................................................................11#
!o6oH!ate..................................................................................................................................11#
!o6oH!ateHlocale.......................................................................................................................11&
!o6oH!ateHstamp.......................................................................................................................11&
i6it "i!gets................................................................................................................................114
%reating a wi!get instance programatically............................................................................114
!i6itHregistry : i6it an! by'!...................................................................................................11(
i6its an! events......................................................................................................................11(
o6o style sheets an! themes..................................................................................................11(
>orm "i!gets..........................................................................................................................11/
!i6itHformH>orm...................................................................................................................11/
!i6itHformH2utton.................................................................................................................1#9
!i6itHformH$a!io2utton.......................................................................................................1#1
!i6itHfromH%ombo2o<.........................................................................................................1#.
!o6o<HformH7ploa!er..........................................................................................................1#3
!i6itHformHateTe<t2o<......................................................................................................1#3
!i6itHformHTimeTe<t2o<.....................................................................................................1#1
!i6itHformHCali!ation Te<t 2o<...........................................................................................1#1
Te<t -!itors.............................................................................................................................1##
!i6itHformHTe<tarea..............................................................................................................1##
!i6itHformHTe<t2o<..............................................................................................................1##
!i6itHformH+impleTe<tarea..................................................................................................1##
!i6itHformHNumberTe<t2o<................................................................................................1#&
!i6itHformH%urrencyTe<t2o<...............................................................................................1#&
!i6itH-!itor..........................................................................................................................1#&
*ists.........................................................................................................................................1#4
!i6itHformHMulti+elect.........................................................................................................1#4
!i6itHformH+elect..................................................................................................................1#4
Cisual Panes............................................................................................................................1#(
!i6itHTitlePane.....................................................................................................................1#(
!i6itH>iel!set........................................................................................................................1#/
ialogs....................................................................................................................................1#/
!i6itHialog..........................................................................................................................1#/
!i6itHTooltipialog..............................................................................................................1&9
Menus......................................................................................................................................1&1
!i6itHMenu...........................................................................................................................1&.
!i6itHMenu2ar.....................................................................................................................1&3
!i6itHMenu'tem....................................................................................................................1&3
!i6itHMenu+eparator............................................................................................................1&3
!i6itHropownMenu.........................................................................................................1&3
!i6itHpopup..........................................................................................................................1&3
!i6itHPopupMenu2ar'tem....................................................................................................1&1
!o6o<Hwi!getH>isheye*ist...................................................................................................1&1
*ayouts....................................................................................................................................1&&
!i6itHlayoutH%ontentPane.....................................................................................................1&&
!i6itHlayoutHAccor!ion%ontainer.........................................................................................1&&
Page &
!i6itHlayoutHTab%ontainer...................................................................................................1&4
!i6itHTitlePane.....................................................................................................................1&(
!i6itHlayoutH+tack%ontainer.................................................................................................1&(
!i6itHlayoutH2or!er%ontainer..............................................................................................1&(
!o6o<HlayoutHTable%ontainer..............................................................................................141
!o6o<HlayoutH@ri!%ontainer................................................................................................14.
-<pan!o Pane.....................................................................................................................143
%olors......................................................................................................................................143
!i6itH%olorPalette................................................................................................................141
The ata @ri!..........................................................................................................................141
+etting @ri! !ata.................................................................................................................14&
-!itable cells......................................................................................................................14&
+electing items...................................................................................................................144
A!!ing new rows................................................................................................................144
$emoving rows...................................................................................................................144
$eplacing the !ata..............................................................................................................144
>ormatting..........................................................................................................................14(
+orting columns..................................................................................................................14(
%ell events..........................................................................................................................14/
@ri!G 8 The ne<t generation o6o ata @ri!J.......................................................................14/
@ri!G "i!th an! 3eight.........................................................................................................1(9
@ri!G : A!!ing an! removing rows.......................................................................................1(9
@ri!G Mo!ules.......................................................................................................................1(1
gri!<Hmo!ulesH2ar..............................................................................................................1(1
gri!<Hmo!ulesH%ell"i!get.................................................................................................1(1
gri!<Hmo!ulesH%olumn$esizer...........................................................................................1(.
gri!<Hmo!ulesH-!it.............................................................................................................1(.
gri!<Hmo!ulesH>ilter...........................................................................................................1(1
gri!<Hmo!ulesHfilterH>ilter2ar............................................................................................1(1
gri!<Hmo!ulesHMenu..........................................................................................................1(1
gri!<Hmo!ulesHPagination2ar.............................................................................................1(#
gri!<Hmo!ulesH$ow3ea!er.................................................................................................1(#
gri!<Hmo!ulesHselectH$ow..................................................................................................1(#
gri!<Hmo!ulesH'n!irect+elect..............................................................................................1(&
gri!<Hmo!ulesH+ingle+ort...................................................................................................1(&
gri!<Hmo!ulesHTitle2ar......................................................................................................1(&
gri!<Hsupport*ink+izer.......................................................................................................1(&
@ri!G +tyling..........................................................................................................................1(4
Mouse an! keyboar! events....................................................................................................1(4
%ommon @ri!G patterns.........................................................................................................1((
A!!ing $ow +election........................................................................................................1((
"orking with $ows............................................................................................................1((
A!!ing an! processing buttons..........................................................................................1((
The !gri! 8 The ne<t generation o6o ata @ri!J.................................................................1(/
'nstalling gri!...................................................................................................................1(/
The Tree..................................................................................................................................1/9
!i6itHTree.............................................................................................................................1/9
!i6itHtreeHMo!el...................................................................................................................1/1
!i6itHtreeH0b6ect+toreMo!el................................................................................................1/1
!i6itHtreeHTree+toreMo!el 8 o Not 7se............................................................................1/.
Page 4
Progress 2ar............................................................................................................................1/3
!o6o<Hcalen!arH%alen!ar.........................................................................................................1/3
Parsing i6it in 3TM*.................................................................................................................1/(
0b6ect +tores an! ata +tores.....................................................................................................1//
!o6oHstoreHMemory...................................................................................................................99
!o6oHstoreH0bservable..............................................................................................................91
eferre! an! asynchronous processing 8 !o6oHeferre!..............................................................91
eclare : efining o6o %lasses..................................................................................................91
%reating %ustom "i!gets.............................................................................................................9.
"i!get templating....................................................................................................................91
+keleton wi!get........................................................................................................................9#
-<ten!ing a wi!get...................................................................................................................9#
7sing getters an! setters on a custom wi!get..........................................................................9#
o6o Publish an! +ubscribe..........................................................................................................9&
o6o %harting...............................................................................................................................9&
The %harting Plot.....................................................................................................................94
The %harting A<is....................................................................................................................1.
The %harting +eries..................................................................................................................13
$en!ering the chart..................................................................................................................13
o6o %harting an! Themes......................................................................................................11
o6o @auges 8 !o6o<H!gauges......................................................................................................11
%reating custom gauges...........................................................................................................1&
+ample custom circular guage.............................................................................................1(
+ample custom rectangular guage.......................................................................................1(
o6o @>G.....................................................................................................................................1(
o6o @>G Cector >onts...........................................................................................................1/
o6o an! %++................................................................................................................................1/
o6o evelopment with ''..........................................................................................................9
A!!ing the o6o Pro6ect >acet..................................................................................................9
7sing the "eb Preview +erver runtime.....................................................................................
o6o evelopment with Microsoft ''+ -<press............................................................................#
7sing a +ource o6o with ''+...................................................................................................&
o6o Mobile...................................................................................................................................4
+imple o6oG Mobile app........................................................................................................4
o6o Mobile Themes................................................................................................................(
The Ciew Mo!el.......................................................................................................................(
!o6o<HmobileHCiew.............................................................................................................../
!o6o<HmobileH+crollableCiew..............................................................................................39
!o6o<HmobileHTreeCiew.......................................................................................................31
!o6o<HmobileH+wapCiew.....................................................................................................31
"orking with o6o Mobile *ists.............................................................................................31
The o6o Mobile wi!gets........................................................................................................3.
!o6o<HmobileHAccor!ion......................................................................................................3.
!o6o<HmobileH2utton............................................................................................................33
!o6o<HmobileH%heck2o<......................................................................................................33
!o6o<HmobileH%ombo2o<....................................................................................................31
!o6o<HmobileH%ontainer.......................................................................................................31
!o6o<HmobileH%ontentPane..................................................................................................3#
!o6o<HmobileH-!geTo-!ge%ategory...................................................................................3#
!o6o<HmobileH-!geTo-!ge*ist...........................................................................................3#
Page (
!o6o<HmobileH-!geTo-!ge+tore*ist...................................................................................3&
!o6o<HmobileH-<pan!ingTe<tArea......................................................................................3&
!o6o<HmobileH>i<e!+plitter..................................................................................................34
!o6o<HmobileH>orm*ayout...................................................................................................34
!o6o<HmobileH@ri!*ayout....................................................................................................34
!o6o<HmobileH3ea!ing.........................................................................................................34
!o6o<HmobileH'con%ontainer................................................................................................3(
!o6o<HmobileH'con'tem........................................................................................................3(
!o6o<HmobileH'conMenu......................................................................................................3(
!o6o<HmobileH'conMenu'tem...............................................................................................3(
!o6o<HmobileH*ist'tem.........................................................................................................3/
!o6o<HmobileHPage'n!icator................................................................................................19
!o6o<HmobileHPane...............................................................................................................19
!o6o<HmobileHProgress2ar...................................................................................................19
!o6o<HmobileHProgress'n!icator..........................................................................................19
!o6o<HmobileH$a!io2utton..................................................................................................19
!o6o<HmobileH$ating............................................................................................................11
!o6o<HmobileH$oun!$ect.....................................................................................................11
!o6o<HmobileH$oun!$ect%ategory......................................................................................11
!o6o<HmobileH$oun!$ect+tore*ist......................................................................................11
!o6o<HmobileH$oun!$ect*ist..............................................................................................13
!o6o<HmobileH+crollablePane...............................................................................................13
!o6o<HmobileH+earch2o<.....................................................................................................11
!o6o<HmobileH+impleialog................................................................................................11
!o6o<HmobileH+li!er.............................................................................................................11
!o6o<HmobileH+pin"heelatePicker...................................................................................11
!o6o<HmobileH+pin"heelTimePicker..................................................................................1#
!o6o<HmobileH+witch...........................................................................................................1#
!o6o<HmobileHTab2ar...........................................................................................................1#
!o6o<HmobileHTab2ar2utton................................................................................................1&
!o6o<HmobileHTe<tArea.......................................................................................................14
!o6o<HmobileHTe<t2o<.........................................................................................................14
!o6o<HmobileHToggle2utton................................................................................................1(
!o6o<HmobileHTool2ar2utton..............................................................................................1(
!o6o<HmobileHTooltip...........................................................................................................1(
!o6o<HmobileHCaluePicker...................................................................................................1/
!o6o<HmobileHCaluePickeratePicker.................................................................................#9
!o6o<HmobileHCaluePicker+lot............................................................................................#9
!o6o<HmobileHCaluePickerTimePicker................................................................................#1
!o6o<HmobileHCi!eo.............................................................................................................#1
6=uery................................................................................................................................................#.
6=uery Mobile 8 !ata roles...........................................................................................................#.
button.......................................................................................................................................#.
Angular;+..........................................................................................................................................#.
+etting up -clipse.........................................................................................................................#.
%hrome Apps.....................................................................................................................................#.
2uil!ing a %hrome App................................................................................................................#3
The Manifest............................................................................................................................#3
The 2ackgroun! +cript............................................................................................................#3
;ava>G...............................................................................................................................................#3
Page /
The 3ello "orl! app....................................................................................................................#1
The ;ava>G 3igh *evel Architecture...........................................................................................#1
6avaf<.stage.+tage.....................................................................................................................##
6avaf<.J.+cene..........................................................................................................................##
6avaf<.scene.image.'mage........................................................................................................##
>GM* 8 The ;ava>G Markup *anguage.....................................................................................#&
>GM* Architecture..................................................................................................................#&
'mporting !efinitions................................................................................................................#4
The f<Kvalue attribute...............................................................................................................#4
The f<Kinclu!e instruction........................................................................................................#4
The f<K!efine attribute..............................................................................................................#4
The f<Kcontroller attribute........................................................................................................#4
The f<Ki! attribute.....................................................................................................................#(
The f<Kroot element..................................................................................................................#(
A %ontroller class.....................................................................................................................#(
+cene 2uil!er................................................................................................................................#/
'nstalling +cene 2uil!er...........................................................................................................#/
3an!ling issues with +cene 2uil!er.........................................................................................&9
;ava>G an! -clipse.......................................................................................................................&9
;ava>G %omponent +izing...........................................................................................................&1
;ava>G %++..................................................................................................................................&1
;ava>G ialogs.............................................................................................................................&.
;ava>G TasksB +ervices an! "orkers...........................................................................................&3
$unning work in the backgroun!.............................................................................................&3
;ava>G %++ an! +tylesheets .......................................................................................................&#
;ava>G eployment.....................................................................................................................&#
;ava>G ata an! 0bservables......................................................................................................&&
;ava>G %ollections..................................................................................................................&&
;ava>G 0bservable*ist............................................................................................................&&
;ava>G %ontrols...........................................................................................................................&4
;ava>G 2utton..........................................................................................................................&4
;ava>G %heck2o<....................................................................................................................&(
;ava>G %hoice2o<..................................................................................................................&(
;ava>G %olorPicker.................................................................................................................&(
;ava>G %ombo2o<..................................................................................................................&/
;ava>G 3yperlink....................................................................................................................&/
;ava>G 'mageCiew..................................................................................................................&/
;ava>G *abel...........................................................................................................................&/
;ava>G *istCiew......................................................................................................................49
;ava>G Passwor!>iel!.............................................................................................................49
;ava>G Progress2ar.................................................................................................................49
;ava>G $a!io2utton................................................................................................................41
;ava>G +eparator.....................................................................................................................41
;ava>G +li!er...........................................................................................................................41
;ava>G TableCiew...................................................................................................................41
%ell>actory..........................................................................................................................43
-!iting a table cell...............................................................................................................4#
;ava>G TableCiew 8 etecting selections..........................................................................4&
;ava>G TableCiew 8 ynamic %olumns............................................................................4&
;ava>G Te<tArea.....................................................................................................................44
Page 19
;ava>G Te<t>iel!.....................................................................................................................44
;ava>G Toggle2utton..............................................................................................................4(
;ava>G Tooltip.........................................................................................................................4(
;ava>G TreeCiew....................................................................................................................4(
;ava>G TreeTableCiew...........................................................................................................4(
;ava>G "ebCiew....................................................................................................................4(
%alling ;ava+cript in the "eb-ngine..................................................................................4/
%alling ;ava from the browser.............................................................................................4/
;ava>G Menus..............................................................................................................................4/
;ava>G Menu2ar.....................................................................................................................(9
;ava>G Menu...........................................................................................................................(9
;ava>G Menu'tem....................................................................................................................(9
;ava>G %heckMenu'tem..........................................................................................................(1
;ava>G $a!ioMenu'tem..........................................................................................................(1
;ava>G %ustomMenu'tem.......................................................................................................(1
;ava>G +eparatorMenu'tem....................................................................................................(1
;ava>G %onte<tMenu..............................................................................................................(1
;ava>G %ontainers........................................................................................................................(1
;ava>G Accor!ion....................................................................................................................(1
;ava>G AnchorPane.................................................................................................................(.
;ava>G 2or!erPane..................................................................................................................(.
;ava>G >lowPane....................................................................................................................(.
;ava>G @ri!Pane.....................................................................................................................(.
;ava>G 32o<...........................................................................................................................(.
;ava>G Pane.............................................................................................................................(.
;ava>G $egion.........................................................................................................................(.
;ava>G +crollPane...................................................................................................................(.
;ava>G +plitPane.....................................................................................................................(.
;ava>G +tackPane....................................................................................................................(.
;ava>G TabPane......................................................................................................................(.
;ava>G TilePane......................................................................................................................(3
;ava>G Title!Pane...................................................................................................................(3
;ava>G C2o<...........................................................................................................................(3
;ava>G 0ther classes....................................................................................................................(3
;ava>G Popup..........................................................................................................................(3
;ava>G Popup"in!ow............................................................................................................(3
;ava>G -vent 3an!ling................................................................................................................(3
;ava>G *amb!a functions............................................................................................................(1
%hange*istener........................................................................................................................(1
;ava>G 7tilities............................................................................................................................(1
;ava>G Multiple+electionMo!el.............................................................................................(1
;ava>G evelopment....................................................................................................................(1
+cenic Ciew.............................................................................................................................(#
+keleton ;ava>G >iles..................................................................................................................(#
+ample application...................................................................................................................(#
+ample %omponent..................................................................................................................(#
;ava>G 3r! Party Packages...........................................................................................................(&
%ontrols>G...............................................................................................................................(&
org.controlsf<.!ialog.ialogs..............................................................................................(&
org.controlsf<.!ialog.ialog................................................................................................(4
Page 11
Apache 3TTP +erver........................................................................................................................((
+etting up a pro<y.........................................................................................................................((
0l! +tuff............................................................................................................................................(/
eployment -nvironments......................................................................................................(/
+izing the +creen.................................................................................................................(/
"orklight A!apters..................................................................................................................(/
3TTP A!apter.....................................................................................................................(/
"orklight +ecurity.................................................................................................................../4
$esearch =uestions.........................................................................................................................../4
Page 1.
Mobile Applications
Applications are no longer limite! to 6ust running on a !esktop P% or laptop. 'nstea!B we now have
a plethora of !evices on which applications can live. +pecificallyB we will be thinking about smart
phones an! tablets. These !evices have something in common L they are consumer items that are
generally small enough to be carrie! with a person. 7nlike classic P% !esktops which are
physically cumbersome an! remain static in a personMs office or homeB the phone an! tablet travel
with people. 'n other wor!sB they are ?mobile?. Applications written specifically for phones an!
tablets are terme! ?mobile applications?.
3ow !oes a ?mobile application? !iffer from a ?regular application?J The answer to that is not
always so clear. There are some obvious thoughts. >irstB the phone an! the tablet !onMt commonly
have keyboar!s or mice attache!. As suchB user interaction is primarily performe! through touch
an! gestures. This changes the way in which 7' styling is built. Ne<tB the screen sizes of the
!evices an! their resolutions vary. This is typically calle! the !evices ?form factor?. +creens vary
from a few inches to a !ozen or more. Tablets an! phones often have a!!itional har!ware
technologies in them inclu!ing accelerometersB @P+ an! other sensors. The network connections
on these !evices shoul! not be consi!ere! to be ?always available? or may be too costly to maintain.
>or these reasons an! many moreB when one is consi!ering an application to be hoste! by one of
these !evicesB there are consi!erations to be taken into account which are not present for !esktop
applications that simply run "in!ows. 2ecause of the wi!e variety of new areas to be covere!B
there is the nee! for new frameworksB platforms an! tools to support such new application
!evelopment. 't is for this purpose that '2M built "orklight.
Types of Mobile App architectures
"hen looking at a Mobile appB there are number of high level architectures that can be employe!.
The first is the "eb or 3TM*# type. 'n this styleB the app is written purely as a web page using a
combination of stan!ar!ize! technologies 3TM*B 0MB ;ava+cript an! %++. A key benefit to a
web app is that it can run without mo!ification on a variety of platforms without mo!ification.
7nfortunatelyB pure web:apps typically re)uire a network connection in or!er to run as they must be
!ownloa!e! for e<ecution. 'n a!!itionB the browser environment hosting the application is not
commonly as rich in functions that are available to the native applications. >inallyB a browser
hoste! application may be slower than a native application is the logic has longer ?path lengths?
than native apps.
The ne<t type of app is what is terme! a ?native app?. These apps are written using the
programming language native to the !evice on which it will run. >or e<ampleB ;ava for An!roi!.
The user interface is also native. A native app canMt be run on a platform for which it was not
!esigne!. >or e<ampleB an An!roi! native app canMt run on i0+. The benefit of a native app is that
it is likely to perform as )uickly as possible an! will usually appear seamless to other apps on the
platform. The !own:si!e is that the time cost of !eveloping a single app that is to run on a variety
of platforms increases as very little of the co!e built for one platform can be re:use! on a !ifferent
platform.
The last type of app is calle! the ?hybri! app? which is a combination or mi< of web app
technology an! native app technology. 'n this storyB the core of the !evelopment remains web app
base! however that app is ?wrappere!? in a natively installable framework. This means that it can
installe! in e<actly the same fashion as native apps an! will be available while !isconnecte! from
the network.
Design guidelines for Mobile Apps
Page 13
The patterns for !esigning user interfaces for mobile apps takes a !ifferent style from that for
!esktop.
+ee alsoK
esigning for i0+ 4
Page 11
Worklight
'2M "orklight is a !evelopment an! runtime platform for buil!ing a variety of user interfaces
inclu!ing mobile.
Releases
There have been a number of releases of "orklightK
;une .91. 8 #.9
ecember .91. 8 #.9.#
April .913 8 #.9.&
;une .913 8 &.9
November .913 8 &.1
+ee alsoK
"orklight forum
Architecture
"orklight provi!es a set of components which work together to achieve a buil! an! run:time
environment for mobile applications. 3ere we start to un!erstan! the pieces involve!.
The architecture of "orklight is compose! of a number of partsK
Page 1#
"orklight +tu!io 8 An integrate! !evelopment environment A'-D built on -clipse use! by
a !eveloper to buil! a mobile app.
"orklight evice $untime 8 A framework supplie! with the application that provi!es
services use! by that application.
"orklight +erver 8 A back:en! server environment use! to service re)uests from a mobile
app.
"orklight %onsole 8 A web base! application use! to manage an! monitor mobile apps.
"orklight Application %enter 8 A "orklight +erver hoste! application that provi!es the
ability for users to select an! install applications onto their mobile !evices. evelopers an!
a!ministrators can also publish applications that can then be accesse!.
Adapter Components
%lient applications often have to interact with back:en! systems to retrieve or store !ata. "orklight
provi!es an abstraction of such back:en! interactions an! calls these ?A!apters?. The way a client
interacts with an a!apter is common irrespective of the implementation of that a!apter. %ommon
a!apter types inclu!e 3TTP connectionsB +0AP web servicesB +=* !atabase access an! others.
+ee alsoK
A!apters
Application Center
0n the 'nternetB mobile applications are commonly store! installe! from AppleMs iTunes store or
from @oogleMs Play +tore. >or mobile applications written for a business this may not be
appropriate. >or e<ampleB it is unlikely that Pet+upplies.com want their warehouse application to
be available to anyone other than their employees. A component of "orklight is calle!
?Application %enter? which provi!es a private ?app store? manage! an! maintaine! by a company.
>rom thisB applications can be foun! an! installe! by users. 'n its simplest termsB Application
Page 1&
%enter can be thought of as a private app store however it provi!es more function than that.
evelopers within your own company can publish new versions of the app for users to access
without being at the mercy of 3
r!
party provi!ers who may !elay publication. 'n a!!itionB the
Application %enter is common across !evice platforms meaning that you may publish it once for a
variety of !evices without having to worry about !ifferent processes to be followe!.
The Application %enter also provi!es a rich fee!back mechanism where users can post comments
that can be seen by !evelopers.
+ee alsoK
Application %enter
Page 14
Installation
The installation of "orklight can be broken !own into the installation of the !istinct components
associate! with it. These inclu!eK
"orklight +tu!io 8 evelopment tools
"orklight +erver 8 Test an! pro!uction servers for application e<ecution
Mobile Test "orkbench for "orklight
Prerequsites
2efore installing "orklightB the prere)uisites must be met. These are !ocumente! hereK
httpKHHwww:91.ibm.comHsupportH!ocview.wssJui!Nswg.49.1(3(
Parts List
'f !ownloa!e! from '2MMs image !istribution web sites. the files that make up the installation
me!ia for "orklight are liste! belowK
Part Description
%'=#P-N "orklight +tu!io &.1
%'=#N-N 'nstallation Manager repository for "orklight +erver &.1
%'=#=-N Mobile Test "orkbench
%'N97-N =uick +tart @ui!e
%',.7M* 8 =uick +tart for *iberty %ore (.#.# =uick +tart for *iberty %ore (.#.#
%',.CM* 8
"A+I*ibertyI%oreIC(.#.#I1I0>I3
There !onMt appear to be other partsO
%',.5M* 8 "A+ *iberty %ore (.#.#
+upplements 1 of 3
"A+ *iberty %ore (.#.# +upplements 1 of 3
%',.PM* 8 "A+ *iberty %ore (.#.#
+upplements . of 3
"A+ *iberty %ore (.#.# +upplements . of 3
%',39M* 8 "A+ *iberty %ore (.#.#
+upplements 3 of 3
"A+ *iberty %ore (.#.# +upplements 3 of 3
%'MT&M* 8
"A*I$untimeIArchiveI*%IC(.#.#
"eb+phere Application *iberty $untime AArchiveB for *iberty
%ore C(.#.#D
%'MT4M* 8 "eb+phere Application *iberty
-<tras AArchiveD C(.#.#
"eb+phere Application *iberty -<tras AArchiveD C(.#.#
Installing Worlight !tudio
The prere)uisite for "orklight +tu!io is an installation of -clipse ;uno 1.. +$. or -clipse 1.3.1
A,eplerD.
httpKHHwww.eclipse.orgH!ownloa!sHpackagesHreleaseH6unoHsr.
-ither the ;ava -- or %lassic version may be use!. 't is !ownloa!e! as a P'P file with a size of
about .3# Mbytes. 0nce !ownloa!e!B its content may be e<tracte!. 'n my environmentB ' create! a
fol!er calle!K
Page 1(
C:\IBM\Worklight
to serve as the root of my "orklight installations. ' then e<tracte! the -clipse !istribution into a
fol!er calle! ?eclipse?.
To launch eclipseB run the ?eclipse? e<ecutable. -clipse uses a fol!er to hol! the workspace
!ata. 'f we wish to use a specific fol!er of our ownB we can up!ate the launch shortcut for eclipse to
inclu!e ?-data <directoryPath>?. This will causes eclipse to use the name! !irectory for
the workspace settings an! !ata.
'f you nee! to specify a specific CMB e!it the eclipse.ini file an! a!!K
:vm QPathRH6avaw.e<e
To vali!ate that you have the correct version of -clipse installe!B see the Help > About !ialogK

"ith the base -clipse environment runningB we can now install the "orklight +tu!io components.
1. +elect ?Help > Istall !e" #o$t"are%%%?
Page 1/
.. A!! a new repository to install.
3. +elect the P'P file containing "orklight +tu!io. As &.1.9B this is the file CI&'P(!%)ip.
1. +elect the features to install
Page .9
Note that it is essential that the -clipse environment have 'nternet connectivity as installation of
"orklight +tu!io will also re)uire the installation of pre:re) -clipse components not !istribute!
with the base -clipse environment. This will likely mean connecting to the 'nternet to access the
-clipse framework !ownloa!s. onMt try an! install "orklight +tu!io unless you are 'nternet
connecte!.
0nce selecte!B click !e*t.
#. $eview the parts
Page .1
&. Accept the license agreement
Page ..
'2M "orklight +tu!io will now install.
4. -clipse will now restart.
+ee alsoK
"orklight +tu!io
Installing an Android !D" #clipse Plugin
'f you are going to be buil!ing An!roi! applicationsB you will likely wish to install the An!roi!
+, tools into the same -clipse environment as the "orklight +tu!io environment.
1. +tart -clipse
.. @o to Help > Istall !e" #o$t"are
3. %lick ?Add? to A!! a new source
Page .3
1. efine the AT
As of .913:11:11 8 the location for the plugin isK
httpsKHH!l:ssl.google.comHan!roi!HeclipseH
+ee the following web page for vali!ation an! !etailsK
'nstalling the -clipse Plugin
#. 'nstall the An!roi! evelopment Tools
Page .1
5ou may see a security warning similar to the followingK
This is e<pecte! an! one shoul! select ?0,?.
&. After installationB we install the An!roi! +, Tools to the file system. +eeK 'nstalling the
An!roi! +,.
Configuring the Worlight !tudio embedded Application !er$er
"orklight +tu!io launches an embe!!e! "eb+phere Application +erver A*iberty %oreD when it
starts to host a "orklight +erver instance that is to be use! for testing. This application server can
have its configuration properties change! if nee!e!.
0ne of the primary properties of this server is the T%PH'P port number on which it is listening for
incoming browser re)uests. The !efault port number it uses is 199(9. There may be a conflict on
Page .#
this port number however it is easy to change.
Installing Mobile Test Worbench for Worlight
Installing Worlight !er$er
The "orklight +erver runs on top of an Application +erver. A number of !ifferent flavors of
hosting application server are supporte!K
"eb+phere Application +erver *iberty %ore
"eb+phere Application +erver
Apache Tomcat
'n a!!itionB "orklight +erver re)uires a !atabases for its own operation. +upporte! !atabase types
areK
'2M 2.
0racle
My+=*
Apache erby Aembe!!e!D
"orklight +erver is supplie! as an '2M 'nstallation Manager repository. 0nce the package has
been !efine! as a repositoryB it can then be installe!.
The first page we are presente! with !uring the installation is the obligatory license agreement. '
Page .&
suspect that everyone simply says ?yeah yeah? an! clicks ne<t. 7se your own 6u!gment on how to
procee!.
'nstallation manager groups installe! pro!ucts into ?packages? an! !esignates a file system
!irectory for each package. 3ere we name the !irectory into which the "orklight +erver binaries
will be place! an! whether these will be 3.bit or &1bit versions.
'n my installB ' was using a &1bit version of 'nstallation Manager an! a warning message was
shown that state! only 3.bit versions of 'M were supporte!. ' installe! an! ha! no issues Aso farD.
Page .4
Ne<t we have yet another confirmation page that we are installing "orklight +erver.
Page .(
Now we are being offere! the opportunity to configure our installation. The first )uestion asks
whether or not we wish to install the Application %enter.
Page ./
"e are now aske! what kin! of !atabase we wish to use.
Page 39
"e are now aske! for information on how to connect to the !atabase of the type we previously
selecte!. This consists of entering the hostname an! port number as well as pointing to a ;2%
!river for that !atabase.
Page 31
'n or!er to access the !atabaseB we nee! to specify a user we will use to connect.
Page 3.
%$-AT- ATA2A+- APP%NT$ %0**AT- 7+'N@ +5+T-M PA@-+'P- 3.4&(
Page 33
Now we specify which kin! of application server will be use! to host the "orklight +erver.
Page 31
'f installing into a "A+ N environmentB you must select the eployment Manager profile.
Page 3#
Page 3&
Page 34
Page 3(
The servers hosting "orklight +erver shoul! be restarte!.
-<amination seems to show that the following ma6or changes have been ma!e to the App +erver as
a result of a "orklight installationK
New applicationsK
'2M Application %enter %onsole QnumR
'2M Application %enter +ervices QnumR
New resources
;2% provi!er 8 Application %enter ;2% Provi!er
;2% ata +ource 8 Application %enter !atabase
;.% authentication !ata 8 App%enterb.atabase%re!entialsIQnumR
Installing the Application Center
Installing WA! Liberty
The "A+ *iberty Profile provi!es an efficient App +erver that is a goo! can!i!ate for hosting a
"orklight server. 3ere we will !iscuss how to install the "A+ *iberty Profile environment.
*aunch '2M 'nstallation Manager an! ensure that the repository for "A+ *iberty Profile has been
a!!e! to the settings.
0nce !oneB we can re)uest an installation.
Page 3/
Ne<t we are prompte! to rea!B review an! accept the license terms.
Page 19
Now we select where on the file system we wish to install the pro!uct co!e. 'n my e<ample ' use!
C:\IBM\+iberty
Page 11
Ne<t we are aske! for options to be inclu!e! in the configuration.
Page 1.
0ne final check before install continues.
Page 13
An! at the en!B we have installe! the pro!uct.
Page 11
%ther Installation Tass
>ollowing the installation of "orklight componentsB other installation tasks may be performe!.
;ava runtime for browsers 8 A number of browser components use! by "orklight rely upon
;ava. This may be !ownloa!e! from www.6ava.com.
7serAgent switcher 8 The mobile test environment re)uires the installation of the
7serAgent switcher. +eeK
'nstalling the 7serAgent +witcher -<tension
Page 1#
Sources of Information
The InfoCenter
'2MMs 'nfo%enter is the primary source for knowle!ge on "orklight. 't is the on:line
!ocumentation for the pro!uct. 't can be freely accesse! at anytime whether or not one has
purchase! the pro!uct. 't can be foun! hereK
httpKHHpic.!he.ibm.comHinfocenterHwrklightHv&r9m9Hin!e<.6sp
I&M 'ome Page
The '2M 3ome Page for "orklight can be foun! hereK
httpKHHwww:93.ibm.comHsoftwareHpro!uctsHusHenHworklightH
Redboos
$e!books are free book form publications written by '2M an! others. 0nes of interest to
"orklight inclu!eK
+ecuring your mobile business with '2M "orklight 8 +@.1:(14/:99 : .913:19:94
-<ten!ing 5our 2usiness to Mobile evices with '2M "orklight 8 +@.1:(114:99
@etting +tarte! with '2M "orklight 8 T0P+199/ 8 .913:9(:.&
de$eloperWors
The '2M !eveloper"orks website is '2MMs portal for technology relate! items. 't has specific
sections oriente! towar!s "orklightK
Mobileevelopment
'2M "orklight
There are many "orklight oriente! articlesK
eliver an e<ceptional mobile web e<perience using "eb+phere Portal an! '2M "orklight C&.9B Part 3K 'mplementing automatic single
sign:on with "orklight an! "eb+phere Portal 8 .913:19:.3
evelop a hybri! mobile application using $ational Application eveloper C(.#.1 8 .913:19:..
eliver an e<ceptional mobile web e<perience using "eb+phere Portal an! '2M "orklightB Part #K 'ntegrating an event:base! portlet with
a hybri! mobile application 8 .913:19:9/
+erver:si!e mobile application !evelopment with '2M "orklight 8 .913:19:9.
-nable >'P+ 119:. 3TTP+ encryption for '2M "orklight mobile apps 8 .913:9/:.1
%reate a mobile 2PM application by integrating '2M "orklight an! '2M 2usiness Process Manager 8 .913:9(:.(
eliver an e<ceptional mobile web e<perience using "eb+phere Portal an! '2M "orklightB Part .K 'ntegrating multiple !evice support for
"eb+phere Portal pages 8 .913:9(:94
eliver an e<ceptional mobile web e<perience using "eb+phere Portal an! '2M "orklight C#.9B Part 3K 'mplementing automatic single
sign:on with "orklight an! "eb+phere Portal 8 .913:9(:94
eliver an e<ceptional mobile web e<perience using "eb+phere Portal an! '2M "orklight C#.9B Part 1K 'ntegrating a hybri! mobile
application with "eb+phere Portal pages 8 .913:9(:94
eliver an e<ceptional mobile web e<perience using "eb+phere Portal an! '2M "orklight C&.9B Part 1K 'ntegrating a hybri! mobile
Page 1&
application with "eb+phere Portal pages 8 .913:9(:94
Prototype mobile applications built with '2M "orklight for '2M "atson 8 .913:9(:9#
7sing the '2M "orklight optimization framework to buil! a cross:platform mobile application for multiple !evices 8 .913:94:14
+erver:si!e mobile application !evelopment with '2M "orklightK Part 1. 'ntegrate the '2M "orklight a!apter with +%A 1.1 services 8
.913:9&:1(
'2M "orklight server configuration for >'P+ 119:. vali!ation an! certificationB Part .K eploying your mobile app on "eb+phere
Application +erver 8 .913:9&:1.
'2M "orklight server configuration for >'P+ 119:. vali!ation an! certificationB Part 1K %onfiguring a server:si!e "eb+phere Application
+erver infrastructure 8 .913:9#:.(
+erver:si!e mobile application !evelopment with '2M "orklightK Part 3. 'ntegrate the '2M "orklight a!apter with $-+Tful services 8
.913:9#:.1
Automate the !eployment of an '2M "orklight customization "A$ file on '2M "eb+phere Application +erver 8 .913:9#:.9
+erver:si!e mobile application !evelopment with '2M "orklightK Part .. '2M "orklight a!apter integration with web service business
logic 8 .913:9#:94
+erver:si!e mobile application !evelopment with '2M "orklightK Part 1. '2M "orklight a!apter integration with ;ava business logic 8
.913:91:39
eliver an e<ceptional mobile web e<perience using "eb+phere Portal an! '2M "orklightB Part 1K 7sing '2M "eb -<perience >actory
with "orklight to create hybri! applications 8 .913:91:1&
evelop "orklight a!apters with ATST mobile AP's 8 .913:91:9&
-rror han!ling in '2M "orklight a!apters : .91.:1.:9#
-ight steps to '2M "orklight mobile application !evelopment 8 .913:19:.1
The basics of !eveloping an en!:to:en! mobile application using '2M "orklight an! o6o Mobile 8 .91.:9/:1.
eveloping a client an! server mashup mobile application with '2M "orklight : .91.:9/:1.
"orking with "orklightB Part 1K @etting starte! with your first "orklight application 8 .91.:9(:91
"orking with "orklightB Part .K eveloping structure! mo!ules an! using the -ncrypte! 0ffline %ache feature in '2M "orklight : .91.:
94:.#
,ey features an! capabilities of '2M "orklight to accelerate your mobile !evelopment : .91.:9(:91
Communities
!" *iveK eveloping an! Managing 5our Mobile Applications 7sing '2M "orklight
(ou Tube
There are some goo! vi!eos about "orklight to be foun! on 5ouTube
Mobile Tech Talk series : >eb 1/ .913 : '2M "orklight 8 .913:9.:.1
'2M "orklight 8 .913:9.:9# 8 NotesK @oo! overview
+imple Application 7sing '2M "orklight 8 .91.:94:1& 8 NotesK technical an! not very polishe!. ' also )uestion full correctness.
'2M "orklight : 3ybri! Applications 8 NotesK Marketingan! glitzy
Page 14
Application Development
Worlight !tudio
"orklight +tu!io is the -clipse base! '- for buil!ing "orklight pro6ects. 't can be launche! by
starting the -clipse framework into which you installe! the "orklight +tu!io environment.
"hen ' buil! "orklight pro6ectsB ' choose to create a new win!ows fol!er for each pro6ect. 'n that
fol!erB ' create a new fol!er calle! ?Work#pace?. This is where the artifacts ' will buil! will
resi!e.
Ne<t ' take a copy of the -clipse shortcut an! paste it as a sibling to my ?Work#pace? fol!er.
>inallyB ' up!ate the launch path for -clipse with the ?-data <path>? option where <path> is
the full path to the "ork+pace fol!er.
Now when ' launch -clipse from the shortcut in the fol!er of my pro6ectB ' am working with the
workspace that ' 6ust !efine!.
Although this techni)ue is not necessaryB ' fin! it helps my work flow.
Page 1(
+ee alsoK
'nstalling "orklight +tu!io
Creating a Worlight Pro)ect
0ne of the first things we will !o when buil!ing a new solution is create a new "orklight Pro6ect.
This is performe! within "orklight +tu!io.
"e are now given the choice of buil!ing one of four types of solutionK
3ybri! Application 8 An application that can be e<ecute! on a variety of platforms.
'nner Application
+hell %omponent 8 An environment in which an 'nner Application can function.
Native AP' 8 A "orklight application that targets a specific platform.
Anatomy of a Pro)ect
Page 1/
"ithin the pro6ect we have a fol!er calle! ?apps?. 't is within here that we will have a fol!er for
each in!ivi!ual app within the pro6ect. Note that this implies a single pro6ect can contain multiple
apps.
"ithin a specific app fol!erB we have another fol!er calle! ?common?. This contains artifacts that
are to be common between multiple !eployment environments. The types of artifacts we will be
working with inclu!eK
3TM*
%++
;ava+cript
'mages
"hen we create a pro6ectB a set of !efault artifacts are create! for us un!erneath the appK
Page #9
There areK
ile Description
co,,o-css-<App>%css
co,,o-i,ages-ico%pg
co,,o-i,ages-thu,bail%pg
co,,o-.s-<App>%.s
co,,o-.s-iit/ptios%.s
co,,o-.s-,essages%.s
co,,o-<App>%ht,l
legal-licese%t*t
applicatio-descriptor%*,l
%ontains application meta!ata.
build-settigs%*,l
An App fol!er will also contain fol!ers for each platform targete!. These inclu!eK
an!roi!
blackberry19
blackberry
ipa!
iphone
win!owsphone(
win!owsphone
air
!esktopbrowser
mobilewebapp
win!ows(
Page #1
Application Descriptor
The Application escriptor is an GM* file containe! within the application portion of the pro6ect
that has the file name ?applicatio-descriptor%*,l?. "orklight +tu!io provi!es a rich
e!itor for working with its content but it can also be e<amine! an! e!ite! in its source GM* format.
%ontaine! within the file are '2M !efine! elements an! attributesK
i!
platformCersion 8 The version of '2M "orklight use! to buil! the solution.
!isplayName
!escription
author
name
email
copyright
homepage
main>ile
thumbnail'mage
features 8 The set of a!!itional features that have been a!!e! to the pro6ect. >or e<ampleK
;+0N+tore
Application Architecture
A "orklight solution uses a single 0M mo!el.
The <body> of the 3TM* page must ha! an ?id? of content. >or e<ampleK
<body id01cotet1 style01display: oe21>
Towar!s the en! of the 3TM* !ocument there will be a <script> loa! of
?.s-iit/ptios%.s?.
App specific ;ava+cript co!e will be place! insi!e ?<App>%.s?. 't contains a function calle!
?"lCo,,oIit34? which will be the primary entry point to the application.
Adding targeted en$ironments
As you !evelop a solutionB you may want to a!! a!!itional target platforms on which the
application will run. To !o thisB select ?5ile > !e" > Worklight (6iro,et?K
Page #.
>rom thereB a !ialog will be presente! where one or more of the target environments can be a!!e!K
Worlight De$elopment !er$er
A copy of the "orklight +erver hoste! by the "eb+phere Application +erver *iberty %ore is
Page #3
supplie! an! configure! with "orklight +tu!io. 't can be seen within the +ervers viewK
The applications !eploye! to it are also shown.
De$eloping *I + Rich Page #ditor
The primary !evelopment component within +tu!io for buil!ing user interfaces is the ?$ich Page
-!itor?. This e!itor provi!es the ability for the programmer to buil! 3TM* either visually through
a !rag an! !rop mechanism or in an 3TM* source e!itor. 2y !efaultB the $ich Page -!itor is
starte! when an 3TM* file is re)ueste! to be opene!. 't can also be e<plicitly starte! with the
?/pe With > 7ich Page (ditor? option.
"hen an 3TM* file is opene!B the e!itor environment looks as followsK
Page #1
The e!itor is full of features an! function. *et us try an! break some of these !own. The primary
e!iting surface takes up the ma6ority of the area. 0ne can look at this area in esign mo!e Aa what:
you:see:is:what:you:get mo!eD or a +ource mo!e Araw 3TM*D or a +plit mo!e Ahalf the win!ow is
esign Mo!e an! half is +ource Mo!eD. The choice of mo!es can be selecte! at the bottom left of
the win!ow.
'n +plit Mo!eB we can choose whether to split the win!ow horizontally or vertically. 2uttons on the
menu bar select which is to be use!K
To the right of the primary e!iting area is a ?palette? of items that can be inserte! into the page in
!esign mo!e. The palette can be toggle on an! off using a menu bar buttonK
2eneath the palette area is a Properties area. This too can be toggle! on an! off using another menu
bar buttonK
"hen working with !evices that can be physically oriente! from lan!scape to portrait mo!eB a
menu bar button can be use! to show what the screen woul! like like if rotate!K
"hen mo!eling against some !evicesB the screen size of the !evice may be too large to be shown in
the esign area. "e can scale the screen to be shown in its entirety through a menu buttonK
Page ##
The implementation of the $ich Page -!itor relies on a browser being available on the 0+ running
'2M "orklight +tu!io. Not all browser types are supporte!K
"in!ows 'nternet -<plorer
>irefo<
*inu<
>irefo<
"ebkit
Mac +afari
The above !oes not mean that other browser types arenMt supporte! for use with a final applicationB
rather these browsers are the ones use! !uring !evelopment time within the $ich Page -!itor.
The "orklight client framework provi!es some a!!itions to any frameworks you may use. These
inclu!eK
"*.2usy'n!icator
"*.+impleialog
"*.Tab2ar
"*.0ptionsMenu
"hen buil!ing a mobile appB it is common for the app to contain multiple ?views? or pages of !ata.
The Mobile Navigation win!ow shows the !efine! views within the application an! which one is
currently visible in the canvasK
%licking on a !ifferent view changes the visible view in the canvas. %hanging view also changes
the source view to the start to the view !efinition.
The ?plus? button allows us to a!! a new instance of a view. "hen selecte!B a new !ialog win!ow
appears. >rom here we can select the creation of the new view from a set of pre!efine! 7' patterns
or simply create an empty view.
Page #&
The ne<t page of the wizar! allows us to set the name of the view an! specify where within the
3TM* !ocument the correspon!ing view will be inserte!.
Page #4
'f we choose to set the view as the !efaultB any previously selecte! !efault view will have its !efault
attribute remove!.
Another important win!ow in the $ich Page -!itor is the 0utline win!ow. This shows a
hierarchical tree structure of your 3TM* !ocument. >rom there you can select elements from the
list an! they become selecte! in both the visual an! source e!itors.
Page #(
Designing visually
'n the $ich Page -!itorMs visual mo!eB a palette of available 3TM* an! "i!gets can be seen in the
right han! si!e of the win!ow.
The palette is split into category fol!ers correspon!ing to the wi!get sets that you have chosen to be
part of the pro6ect.
3TM* Tags 8 The core 3TM* elements
3TM* >orm Tags 8 The core 3TM* form elements
o6o ata "i!gets 8 o6o wi!gets that rea! an! write !ata
o6o Mobile "i!gets 8 The ?!o6o<Hmobile? package of wi!gets
o6o< "i!get 8 $ich o6o wi!gets part of the o6o e<tensions package
>rom the paletteB a component can be !ragge! an! !roppe! onto the canvas. "hile !ragging an
Page #/
itemB the position within the !ocument where the item will be inserte! is shown. $eleasing the
mouse will insert the component. 'n a!!ition to !ragging a component into the visual canvasB a
component can also be !roppe! in the source.
-ach component a!!e! to the canvas may have a variety of properties associate! with it. A win!ow
title! ?Properties? provi!es an visualization of these properties inclu!ing the ability to change their
values.
Coding in the HTML source
The reality of buil!ing a 7' is that we can not buil! everything we nee! in the visual !esigner. "e
will invariably have to buil! out parts of our solution in the te<t 3TM* e!itor. 3ere is an e<ample
of some 3TM* in the e!itorK
The 3TM* is parse! as it is e!ite! to show errorsB keywor!sB matching element en! tags an! much
more. 'n or!er to use this portion of the e!itorB it is assume! that you are very familiar with 3TM*
an! any ;ava+cript frameworks that you may be wishing to use. "orklightMs ethos is that it e<poses
as much e<isting technology that you may be familiar with as possible an! minimizes the amount of
a!!itional interference.
Images and graphics
"ithin the stu!io pro6ect there is a fol!er calle! ?i,ages?. This fol!er can be use! to contain
image files in a variety of formats inclu!ing ;P-@B PN@ an! @'>. This is the recommen!e! fol!er
for hol!ing graphics components. "ithin the 3TM*B a reference to ?i,ages-<$ilea,e>?
will access the image.
"hen buil!ing out mobile appsB it is common to want to fin! images to be use! in icons an!
buttons. A goo! source for such is the 'con>in!er web site AhttpsKHHwww.iconfin!er.comH D. Always
rea! the licensing agreements for any icons use!. The web site has the ability to filter on icons to
fin! freeHunrestricte! items.
Page &9
%ff,line !torage
0ne of the core architectural concepts that !istinguish mobile apps from other types of app is that
they are only transiently connecte! to a network. There is no assurance that at any given time they
have access to a network. 'f an application is reliant on !ata this can result in the application being
unable to be use! while off:line. A solution to this is to provi!e off:line storage of !ata such that
when the application is on:lineB it can retrieve some set of !ata that the en! user can use to !o work
an! save it locally. 'f the app subse)uently becomes network isolate!B the app can still work Ato
some !egreeD using the local !ata that it previously store!.
The Worklight J!"tore
"orklight provi!es a concept calle! ;+0N+tore. This is a component that e<ecutes client:si!e
within the conte<t of a client app. 't provi!es a storage abstraction that can be use! by application
to store an! retrieve !ata.
't provi!es the following high level features each of which will be !iscusse! in more !etail in later
sections.
ata encryption
+torage space only constraine! by available storage space
"orklight a!apter integration
2y !efaultB the ;+0N+tore functions are not inclu!e! in an application an! must be e<plicitly a!!e!
to be utilize!.
"e can !o this through the application:!escriptor e!itor. 0pen the e!itor an! select ?/ptioal
5eatures?. Ne<t click the Add%%% button to a!! a featureK
0nce a!!e! it will show in the a!!e! features listK
Page &1
"ithin a ;+0N+tore one will fin! a set of ?ocuments?. This might be a confusing name as they
shoul! not be consi!ere! !ocuments such as P>B "or! or -<cel. $atherB in "orklight parlanceB
a !ocument is recor! or !ata structure. -ach !ocument consists of two primary partsK
An ' fiel! that is uni)ue to the !ocument
A ;ava+cript ob6ect that is the content of the !ocument
A secon! level of abstraction calle! a ?%ollection? is !efine!. A collection is a container of
!ocuments. 'f one thinks of a !ocument as a !atabase row then a collection can be consi!ere! as
!atabase table containing those rows.
0ne final abstraction e<ists which is that of the ;+0N+tore ?store?. The store is a set of collections.
>ollowing our !atabase analogyB the store itself can be thought of as a !atabase instance hosting all
the !ifferent collections which in turn host each of the !ocuments.
Push -otification
't is not uncommon for a mobile application to re)uest that a back:en! system perform some work
on its behalf. "hat we now wish to look at is the converse of this L namely a back:en! system
wishing to push information asynchronously to the mobile app. -<amples of this woul! be
informing the application that a stock has reache! a sell threshol! or a new transaction has occurre!
on a userMs cre!it car!.
'2M "orklight provi!es technology for han!ling such push notifications. %urrentlyB the push
technology works with An!roi!B i0+B an! "in!ows Phone (. The way the push actually happens is
a function of the !evice platform. >or an!roi! it is @oogle %lou! Messaging A@%MDB for i0+ it is
Apple Push Notification +ervice AAPN+D an! for "in!ows Phone ( it is the Microsoft Push
Notification +ervice AMPN+D.
Testing
"hen buil!ing a solutionB it is essential that it be teste! often. "orklight provi!es a component
calle! the ?Mobile browser simulator?. "hat this is is a web application which runs the web
portions of your application in a browser. The browser shows the form factor of a variety of
name! !evices allowing you to see what your app will look like on a variety of !ifferent systems.
Page &.
#sing the Mobile $ro%ser imulator
"orklight provi!es an application which runs in the browser that simulates a !evice. This can be
use! to test your application without having to !eploy it to an actual !evice or !evice supplie!
emulator.
To launch the simulatorB open the conte<t menu for your applicationMs !evice environment an!
select 7u As > Pre6ie"K
't is not yet known why there are two menu entries both labele! Preview. A new browser win!ow
will open showing a simulation of the applicationK
Page &3
"hen a browser runsB it provi!es an i!entification of what kin! of browser an! what environment it
is running upon to the hoste! ;ava+cript application. This i!entity is calle! the ?7serAgent?.
"hile working with the browser simulatorB we may wish to ?overri!e? the 7serAgent i!entity to
simulate multiple platforms. To achieve thatB we nee! to enable 7serAgent switching. 'f we !o not
enable user agent switchingB the simulator will only show iPhone styling.
Installing the UserAgent Switcher Extension
'f we wish the mobile browser simulator to be able to inform the application of a specific !evice
typeB we must install the 7serAgent +witcher -<tension.
%licking the ?(able 8serAget #"itcher? button on the menu bar will pro!uce the
following !ialogK
Page &1
%licking the ?Istall Bro"ser (*tesio? will !ownloa! the installer into the ownloa!s
fol!er of your P%.
To manually install this e<tension in @oogle %hromeK
1. 0pen the %hrome +ettings page
.. 0pen the %hrome -<tensions page
3. rag an! !rop the ?'2M Mobile 2rowser +imulator 7serAgent +witcher? plugin onto the
%hrome -<tensions page. This may be supplie! as a file calle!K
,buseraget9ratioal%ib,%co,%cr*
1. %onfirm the a!!ition of the new e<tensionK
Page &#
#. A new entry will appear in the %hrome -<tensions list
Debugging
console.logA...D
"*.*ogger.!ebugA...D
"*.*ogger.errorA...D
+ee Also
'2M "orklight Tutorial 8 *ogging 8 Cimeo 8 .913:91:91
Artifact management
"hen working in "orklight +tu!ioB you will always want to take backups of your work in case
something horrible happens. 5ou can e<port a pro6ect an! import a pro6ect as a P'P file.
>or the importB select >ile R 'mport from the menu an! then un!er the @eneral categoryB select
?-<isting Pro6ects into "orkspace?.
Page &&
5ou can now select the P'P file that was previously e<porte!.
Page &4
At the conclusion of this stepB a new pro6ect can be foun! which will be the import of the previous
e<port.
Page &(
A!apters
't is very common for a mobile app to interact with back:en! systems to retrieve informationB
re)uest actions to be performe! or store new !ata. To achieve thisB the app must make a re)uest to
the back:en!. 7nfortunatelyB this opens up a whole slew of challenges. ifferent back:en!s will
support !ifferent communication protocolsB !ifferent security re)uirements an! more. -ach of these
has to be co!e! to an! learne! an! can increase the time to buil! an! test applications.
"orklight intro!uces the mo!el of the ?A!apter?. An a!apter is a server si!e component which
listens for incoming re)uests from "orklight client applications. "hen an a!apter receives a
re)uestB it then makes contact with the back:en! system to perform the re)uest on behalf of the app.
-ffectively acting as a pro<y for the client app.
2y employing this mo!elB the client programmer nee! not learn !ifferent communication
technologiesB security technologies an! even be insulate! from a lot of low level mechanics.
'nstea! they nee! only learn how to invoke an arbitrary "orklight a!apter an! the a!apter !oes the
rest.
Notes
A!apters are implemente! in ;ava+cript. G+* is also supporte! which can be use! to buil! ;+0N
!ata to be sent back to the client app.
An a!apter can be transactional or rea!:only.
A!apters support security to provi!e a system user to the back:en! or else can propagate a client
app i!entity.
A!apters provi!e access transparency. The a!apter provi!es a consistent access pattern irrespective
of how the a!apter is implemente! or operates.
+ee alsoK
A!apter %omponents
+eries of !eveloper"ork articles on A!apters
Adapter Architecture
A client app will use client si!e AP' to make a re)uest for !ata. This will result in a re)uest being
ma!e to the "orklight server. This re)uest is ma!e passing ;+0N formatte! !ata over an 3TTP
P0+T re)uest but this is transparent to the "orklight client !eveloper. The "orklight server is
hosting the a!apters re)uire! by the client app. "hen the re)uest arrivesB the a!apter han!les the
incoming re)uest an! performs any server si!e AP' calls necessary to interact with the actual back:
en! server.
"ithin an a!apterB it e<poses a set of entry points that are terme! ?proce!ures?.
"hen the proce!ure running within the a!apter calls the back:en! systemB that system will return
response !ata. The !esire! result of the a!apter interaction is ;+0N formatte! !ata. 'f the back:en!
Page &/
returns ;+0N then that !ata is left as:is. 'f the !ata returne! is something other than ;+0N then it is
converte! into GM* an! then an G+* style sheet may be applie! to buil! ;+0N. >inallyB before
sen!ing the result back to the clientB the a!apter can manipulate the final !ata.
Creating a ne. Adapter
"hen we !esign a new mobile application that wishes to interact with a back:en! systemB we will
create a new a!apter to achieve that goal.
"ithin a "orklight pro6ect within "orklight +tu!ioB we select !e" > AdapterK
"hen we create an a!apterB we !efine which pro6ect it is going to be containe! withinB what type of
a!apter it will be an! the name of the a!apter to be create!.
The types of a!apter available to us areK
3TTP A!apter
+=* A!apter
;M+ A!apter
%ast 'ron A!apter

This will create the a!apter file system structure with the GM* configuration fileB ;ava+cript an!
G+* which can then be mo!ifie! for specific access to a back:en!.
Page 49
Adapter Implementation
An a!apter is implemente! by a set of artifacts. To be specificK
An a!apter configuration file in GM* "ithin this fileB a !escription of each of the
proce!ures supplie! by that a!apter is !efine!.
A ;ava+cript file. "ithin this file one will fin! an implementation of each of the proce!ures
offere! by the a!apter.
Pero or more G+* files use! to convert back:en! !ata to ;+0N.
An a!apter is the aggregation of each of the above an! is package! into a P'P file with a file type of
?%adapter?.
The GM* configuration file has the following general format
<adapter a,e01Adapter!a,e1 plat$or,:ersio01;1>
<descriptio>
<debugPort>
<ru/!ode>
<coecti6ity>
<-coecti6ity>
<procedure a,e01Procedure!a,e1 >
<-procedure>
%%%
<-adapter>
-ach <procedure> element can have a number of attributes.
a,e 8 The name of the proce!ure
platformCersion
coectAs 8 +ecurity i!entity use! to connect to the back:en! system. %hoices areK
server
en!7ser
respose<i,eoutI#ecods 8 3ow long to wait for a back:en! response before
timing out. The !efault is 39 secon!s.
audit 8 +houl! this a!apter be au!ite!J Calues are ?true? an! ?false?.
security<est 8 A test that can be performe! to protect the a!apter.
!ebugPort
run0nNo!e
Although the GM* configuration file can be e!ite! within a te<t e!itor or an GM* e!itorB
"orklight stu!io provi!es a first class professional e!itor that provi!es entry assist as well as
assurance of correctness of the file.
After buil!ing an a!apterB the a!apter can be copie! to other "orklight pro6ects by copying its
fol!er foun! 6ust beneath the ?a!apters? fol!er to the correspon!ing location in the target pro6ect.
&dapter Javacript implementation
"hen an a!apter is create!B a ;ava+cript file calle! QA!apterNameR:impl.6s is also create!. This is
where we implement the ;ava+cript co!e that implements the core function of the a!apter. This is
Page 41
commonly interacting with the back:en! server through some other protocol.
"hen we !efine the a!apterB we !efine one or more proce!ures that can be calle! by the client. >or
each proce!ureB we nee! to create a correspon!ing function !efinition in the ;ava+cript. >or
e<ampleB if we !efine that an a!apter will e<pose a proce!ure calle! ?get@reeting? then we nee! to
buil! a function !efinition in the ;ava+cript source file also calle! ?get@reeting?. This means that
when the client invokes the a!apterMs proce!ure the correspon!ingly name! function will be
invoke!.
A proce!ure function must return a ;ava+cript ob6ect. 't is that ob6ect that is returne! to the client
caller. The ob6ect is augmente! with a property calle! ?is+uccesful?.
Adapter Types
An a!apter use! by a client app must be of one of the following typesK
HTT' &dapter
The 3TTP A!apter provi!es the ability for a "orklight client app to connect to a back:en! system
via the 3TTP protocol. %alling back:en! systems via 3TTP outsi!e of the scope of "orklight is a
very common activity. TypicallyB this concept is calle! ?$-+T programming? or ?A;AG
programming?. There is nothing to prevent the client application from calling a target back:en!
!irectly using a ;ava+cript frameworkMs $-+T calling AP's !irectlyB howeverB !oing so will not take
a!vantage of the "orklight a!apter architecture an! all its relative values.
The high:level architectural overview of using the 3TTP A!apter is shown in the following
!iagramK
An instance of an 3TTP A!apter is create! an! !eploye! to the "orklight +erver. The %lient app
uses the "orklight %lient AP' to invoke a proce!ure e<pose! by the a!apter. This proce!ure then
makes the actual re)uest to the back:en! server using 3TTP.
"hen an instance of an 3TTP A!apter is !efine! in "orklight +tu!ioB the %onnection Policy
options look as followsK
Page 4.
protocol 8 The network protocol use! to connect to the back:en! server. The choices are
either ?http? or ?https?. 7se http for un:encrypte! network traffic an! https for
encrypte! network traffic using ++*. +ee %onfiguring the 3TTP A!apter for ++* for
!etails on a!!itional consi!erations when using ++*.
do,ai 8 The network !omain name or 'P a!!ress of the server hosting the back:en!
service.
port 8 The T%PH'P port number on which the back:en! 3TTP service is listening upon for
incoming re)uests.
cookiePolicy
ma<$e!irects
+ee alsoK
7sing '2M "orklight 3TTP A!apters with $-+TH;+0N +ervices 8 blog 8 .91.:9&:.4
HTTP Adapter Procedure implementations
The core to implementing an 3TTP A!apter proce!ure is to use the W+%#er6er%i6okeHttp
AP'. This rich an! powerful AP' makes an 3TTP re)uest. The result from making an invoke3ttp
re)uest shoul! be the result returne! from the proce!ure.
+ee alsoK
"*.+erver.invoke3ttpAoptionsD
Page 43
Configuring the HTTP Adapter for SSL
"hen the 3TTP a!apter connects to the back:en! server it can utilize the 3TTP protocol over
either plain T%P or ++*. To use ++* re)uires some setup.
1. %hange the protocol type of the A!apterMs GM* configuration to ?https?.
.. %hange the port number to be that of the back:en! serverMs port for ++*.
Example HTTP Adapter
0n the 'nternet there is an e<ample public 3TTP service that will return 7+ @overnment
representative !etails. This web site can be foun! atK
httpKHHwhoismyrepresentative.comHapi
'n this e<ampleB we will buil! an a!apter which invokes this $-+T service taking a 7+ state as
input an! returning the senators for that state.
-<amining the !ocumentation for the $-+T re)uestB we see that a call toK
httpKHHwhoismyrepresentative.comHgetallIsensIbystate.phpJstateNTG
will return the senators from Te<as. Testing this re)uest using a $-+T testing tool shows that it
returns an GM* !ocument.
"e are now at the point where we can !esign our a!apter. >or 3TTP a!aptersB we shoul! complete
the following table before we continueK
Propert" #alue
3ostname or T%PH'P a!!ress
Port Number
3TTP comman! verb
7$* Path
Parameters
+ecurity consi!erations
$eturne! !ata format
'n our e<ampleB the answers woul! beK
Propert" #alue
3ostname or T%PH'P a!!ress
http:--"hois,yrepresetati6e%co,
Port Number
=>
3TTP comman! verb
?(<
7$* Path
-getall@ses@bystate%php
Parameters
state0<8# #tate>
Page 41
+ecurity consi!erations
!oe
$eturne! !ata format
AM+
"e create a new a!apter that we call +enatorsK
"e !elete the sample proce!ures associate! with it.
Ne<t we a!! a new proce!ure calle! get+enators.
Page 4#
At this point we have a !efine! a!apter but no implementation for the server si!e proce!ure which
calls the back:en! service. "e open up the ?#eators-i,pl%.s? implementation file for the
a!apter. "e nee! none of the co!e template! by '2M. 'nstea! we co!e onlyK
$uctio get#eatorBy#tate3state4 B
6ar optios 0 B
1,ethod1: 1get1C
1path1: 1getall@ses@bystate%php1C
1returedCotet<ype1: 1*,l1C
1para,eters1: B
1state1: state
D
D2
retur W+%#er6er%i6okeHttp3optios42
D
>inallyB in the %onnection Policy of the a!apter !efinitionB we supply the connection information
for the server machineK
Page 4&
This completes our implementation. "e can now test the a!apter through +tu!io by selecting the
a!apter an! running 7u As > I6oke Worklight ProcedureK
Page 44
This shows a !ialog in which the proce!ure name an! parameters may be supplie!.
%licking the 7u button shows us the results of invoking the a!apter on the "orklight +erverK
JM &dapter
The ;M+ a!apter allows a "orklight client to sen! or receive messages from a ;ava Message
+ervice A;M+D )ueening provi!er. The ;M+ a!apter encapsulates all access to the ;M+ system so
that the client !eveloper nee! only invoke the a!apter without having to have knowle!ge of the
un!erlying mechanics of ;M+ access.
2efore we !ive !eeper into the a!apterB let us first review our un!erstan!ing of ;M+. ;M+ provi!es
an abstraction to ;ava programmers who wish to access )ueuing systems. A variety of ven!ors
provi!e )ueuing systems each of which are !ifferent. This woul! mean that a ;ava programmer
wishing to use one woul! be boun! to that ;M+ provi!er. The ;M+ specification !escribes a ven!or
neutral set of interfaces that a ;ava programmer can use. 'n or!er for a ;ava application to be able
to access the ;M+ provi!erB it nee!s two pieces of information. The first is calle! the ;M+
%onnection >actory !efinition. This is a ;N' entry that points to a ;M+ provi!er supplie!
configuration for accessing that ;M+ provi!er. The secon! !efinition is the i!entity of a ;M+ )ueue
to which messages will be rea! or written. This is again !efine! through a ;N' !efinition.
Page 4(
"hen a ;M+ a!apter is !efine!B the connection policy looks as followsK
'n the .,sCoectio settings we have entries forK
coectio5actory 8 The ;N' entry name use! to lookup the ;M+ connection
factory that will be use! to connect to the ;M+ provi!er.
user 8 The useri! use! to connect to the ;M+ provi!er.
pass"ord 8 The passwor! of the user use! to connect to the ;M+ provi!er.
'n the naming%onnection settings we have entries forK
initial%onte<t>actory
passwor!
url
user
+ee alsoK
'2M "orklight v&.9.9 @etting +tarte! 8 ;M+ A!apter 8 %ommunicating with ;M+ 8 .913:94:./
JS Adapter Procedure implementations
0nce the a!apter has been !efine!B we can create proce!ure !efinitions. These will be the e<pose!
entry points into the a!apter that implement the invocations to the back:en! ;M+ provi!er.
+ee alsoK
"*.+erver.rea!+ingle;M+MessageAoptionsD
"*.+erver.rea!All;M+MessagesAoptionsD
Page 4/
"*.+erver.write;M+MessageAoptionsD
"*.+erver.re)uest$eply;M+MessageAoptionsD
(L &dapter
The +=* a!apter allows a "orklight client to e<ecute +=* statements or store! proce!ures against
a back:en! !atabase. The +=* a!apter encapsulates the calls to the !atabase hi!ing the mechanics
of how this is achieve! from the "orklight client !eveloper.
"orklight supports 2.B 0racle an! My+=* !atabase access.
2efore we !ive !eeper into the +=* A!apterB let us spen! a little time talking about the ;ava ;2%
technology. ;2% is a ;ava specification that insulates a ;ava programmer from the mechanics of
interacting with a specific ven!orMs !atabase implementation. >or e<ampleB '2M with 2. may
choose one style of technologyB 0racle a !ifferent style an! My+=* yet another style. 'f a ;ava
programmer ha! to accommo!ate !ifferent ven!or characteristicsB the ;ava applications woul! have
to !iffer for each !atabase that coul! be use!. ;2% insulates the programmer from that chore. 't
provi!es an AP' that normalizes access. To allow for the !istinctions between the 2 provi!ersB
;2% assumes that each ven!or will provi!e a ;2% compliant ?!river?. This will be ;ava co!e
built an! !istribute! by the !atabase ven!or that allows ;2% to be able to form connections an!
use the target !atabase. +ince this ;2% !river class conforms to the ;2% specificationB it will
provi!e its half of the han!shake to the !atabase an! the ;2% caller will leverage those functions.
The ability to connect to the !atabase is only part of the insulation that ;2% provi!es. There will
also be configuration parameters that will nee! to be supplie! by a client that wishes to use the
!atabase. +uch things will inclu!e the physical location of the !atabase Alocal or networke!D an!
the name of the !atabase to be accesse! Aa machine can presumably host multiple !atabasesD. +ince
these configuration parameters are also ven!or specificB they must be supplie! when the client
wishes to connect with the target. These parameters are calle! the ?;2% %onnection 7$*? as
they typically look like a web 7$* Athough not alwaysD.
"hen a +=* A!apter is !efine!B the connection policy !efinition looks as followsK
"e notice that there are properties specific for !atabase accessK
8rl 8 The ;2% %onnection 7$* use! to connect to the target !atabase. This value will
be !atabase provi!er specific.
Eri6er class 8 The name of the ;2% !river class supplie! by the 2 ven!or.
8ser 8 The name of the user un!er which the connection to the !atabase will be performe!.
Page (9
Pass"ord 8 The passwor! for the user use! to connect to the !atabase.
The !efinitions for the a!apter are save! in its GM* configuration file calle! <Adapter>%*,l.
This will contain an GM* section calle! <data#ourceEe$iitio> un!er the
<coectioPolicy> element. >or e<ampleK
<coecti6ity>
<coectioPolicy *si:type01sFl:#&+CoectioPolicy1>
<data#ourceEe$iitio>
<dri6erClass>co,%,ysFl%.dbc%Eri6er<-dri6erClass>
<url>.dbc:,ysFl:--localhost:GG>H-,ydb<-url>
<user>,y8sera,e<-user>
<pass"ord>,yPass"ord<-pass"ord>
<-data#ourceEe$iitio>
<-coectioPolicy>
<loadCostraits ,a*CocurretCoectiosPer!ode01'1 ->
<-coecti6ity>
+ee alsoK
%reating +=* A!apter in '2M "orklight 8 .913:9(:1(
'2M "orklight v&.9.9. @etting +tarte! 8 +=* A!apter 8 %ommunicating with +=* atabase 8 .913:94:1.
!ata"ase J!#C !ri$ers
'n or!er to use the +=* A!apterB you will nee! the correspon!ing ;2% !river class file supplie!
by the !atabase ven!or. 5ou shoul! always check the appropriate ven!or !ocumentation for
!etails.
+ee alsoK
'2M 2. ;2% river Cersions
0racle ;2% rivers
My+=* %onnectorH; 8 ;2% !river for My+=*
S%L Adapter Procedure implementations
0nce the a!apter !efinition has been ma!eB the ne<t step will be to !efine the a!apter proce!ures
that are to be e<pose! to the client caller. -ach of these will be name! ;ava+cript functions an!
correspon!ing GM* configuration file !efinitions.
The bo!y of the ;ava+cript function will then make "orklight provi!e! server si!e AP' calls to
interact with the back:en! !atabase. There are three calls that are of interest to usK
W+%#er6er%i6oke#&+#toredProcedure34 : 'nvoke a !atabase store! proce!ure.
W+%#er6er%create#&+#tate,et34 : %reate a +=* prepare! statement.
W+%#er6er%i6oke#&+#tate,et34 : 'nvoke a +=* statement on the !atabase.
+ee alsoK
"*.+erver.invoke+=*+tore!Proce!ureAoptionsD
"*.+erver.create+=*+tatementAstatementD
"*.+erver.invoke+=*+tatementAoptionsD
Cast Iron &dapter
Page (1
Calling an adapter from the Client
>rom the client si!eB we can invoke an a!apter with "orklight provi!e! AP'K
W+%Cliet%i6okeProcedure3i6ocatioEataC optios4
This is !escribe! in !etail on the AP' page for that function.
+ee alsoK
"*.%lient.invokeProce!ureAinvocationataB optionsD
A!apters
Page (.
#rror 'andling for Adapters
+ee alsoK
!eveloper"orks 8 -rror han!ling in '2M "orklight a!apters : .91.:1.:9#
In$oing /a$a code from an Adapter
"hen an a!apter is invoke! by the client a ;ava+cript routine is e<ecute!. '2MMs "orklight server
runs ;ava+cript on the Mozilla $hino engine. $hino has the ability to e<ecute arbitrary ;ava co!e.
The implication of this is that an A!apter can also invoke ;ava co!e.
;ava co!e that is compile! an! place! in a ;A$ file is a!!e! to the class:path of the ;ava+cript
environment if that ;A$ is a!!e! into the pro6ectMs ser6er-lib fol!er.
3ere is an e<ample of calling ;ava through an a!apter.
1. %reate a ;ava pro6ect calle! AdapterIJa6a
.. %reate a package calle! ?co,%kolba?
3. %reate a ;ava class calle! ?AdapterIJa6a?
1. 'mplement the ;ava class as followsK
package co,%kolba2
public class AdapterIJa6a B
public #trig get?reetig3#trig a,e4 B
retur 1HelloC 1 K a,e2
D
D
"hat this class !oes is e<pose a function calle! ?get@reeting? thatB when calle!B will return a
greeting.
#. -<port the ;ava pro6ect as a ;A$ file calle! ?AdapterIJa6a%.ar?.
&. %reate a "orklight pro6ect calle! W+@AdapterIJa6a
4. %opy the ;A$ file into the pro6ects ser6er-lib fol!er
(. %reate a new a!apter calle! AdapterIJa6a
Page (3
/. efine an a!apter proce!ure calle! ?get?reetig?
19. 'n the A!apter.;ava:impl.6s ;ava+cript fileB implement the ?get@reeting? functionK
$uctio get?reetig3a,e4 B
6ar adapterIJa6aIstace 0 e" co,%kolba%AdapterIJa6a342
6ar greetig 0 adapterIJa6aIstace%get?reetig3a,e42
retur B 1resp1: greetigD2
D
11. eploy the a!apter to the "orklight server
1.. $un the a!apter test tool from +tu!io foun! in 7u As > I6oke Worklight
ProcedureK
Page (1
13. -<amine the responseK
>rom the above output we see that the response now contains the te<t from the co!e that was
e<ecute! in ;ava.
+ee alsoK
!eveloper"orks 8 +erver:si!e mobile application !evelopment with '2M "orklightK Part 1. '2M "orklight a!apter integration with ;ava
business logic 8 .913:91:39
I$M Worklight %onsole
Page (#
Application %enter
After you have built your mobile applicationB your ne<t puzzle will be how to get the application to
your users an! how to get fee!back upon it.
The Application %enter has a web base! ?console? which can be use! to access its settings. The
7$* for the console isK
httpKHHlocalhostK/9(9Happcenterconsole
0n first connectB it looks as followsK
Page (&
Installing the Application Center mobile client
Page (4
Page ((
The installer for An!roi! can be foun! in the file calle!K
Q"orklight+erverRHApplication%enterHinstallerH'2MApplication%enter.apk
Page (/
Page /9
+ee alsoK
Application %enter
$e!book 8 -nabling Mobile Apps with '2M "orklight Application %enter 8 $-P:#99#:99 : .913:9&:11
Page /1
Performance
The performance of solutions built with "orklight can be improve! via a number of !ifferent
techni)ues.
Minification
"hen a "orklight solution containing ;ava+cript an! %++ is builtB part of the ?cost? of e<ecuting
that solution may be the size of the source files containing this !ata. +ince ;ava+cript is not a
compile! language but is rather an interprete! languageB the ;ava+cript source file must be
transmitte! an! parse! in or!er to run. This can mean that content that is necessary for human
consumption such as comments an! white space have to be loa!e! an! e<amine!.
Minification is the notion that a source file can be transforme! from one set of content to another
without losing any of its semantic content. This can mean the removal of commentsB the removal of
white space an! the renaming of long variable names to ones which are much shorter. The result is
a new source file which is basically un:intelligible to a human but can result in !ecrease! loa! times
an! more efficient e<ecution.
"orklight supports minification with three optionsK
oe 8 No minification is performe!.
"hitespaces 8 0nly comments an! whitespace are transforme!.
si,ple 8 "hitespace is transforme! as well as variable name replacement.
The "orklight implementation of minification utilizes the ?@oogle %losure %ompiler?. This 0pen
+ource tool from @oogleB !espite its nameB is not a compiler but rather provi!es a transformation
from human e!ite! ;ava+cript to a minifie! representation.
The minification options can be foun! in the buil! settings of the pro6ect.
The level specifies the minification levelB they areK
None AefaultD
Page /.
$emove white spaces an! comments
@oogle %losure %ompile +imple 0ptimization
'n a!!ition you can specify while files to inclu!e an! e<clu!e from the minification process. The
synta< of inclusion an! e<clusion isK
TT matches any file.
T matches a file name Aeg. T.6sD.
A ?U? separates multiple entries.
An e<ample might be ?TTH6sHTTU TTHcssHT.css?.
Minification is only applie! to !esktop an! web pro6ects.
Minification shoul! not be applie! to files that have alrea!y ha! minification applie! Aeg. the o6o
librariesD.
0ile Concatenation
"hen an application is loa!e!B it may be comprise! of multiple ;ava+cript an! %++ source files. 'f
the app is a "eb or !esktop pro6ectB then each of these will result in another trip back to the server
to retrieve the file. To re!uce the number of trips an! hence improve over all performanceB
"orklight provi!es a feature calle! ?file concatenation? which concatenate multiple files together
into a single file. This single file is then loa!e! as a unit as oppose! to loa!ing each of the other
files one at a time.
Securit"
The features of a secure system can inclu!e the following conceptsK
Authentication 8 The notion of proving that one is who one claims to be.
Authorization 8 The notion that when a task is attempte! that one is allowe! to perform that
task.
%onfi!entiality 8 The notion that no:one can see the information passing between the sen!er
an! receiver.
'ntegrity 8 The notion that the information receive! is e<actly the information transmitte!
an! it hasnMt been tampere! with !uring transit.
Nonrepu!iation 8 The notion of proving that a !elivere! piece of information was in!ee!
!elivere!.
Access to a resource is protecte! through a name! entity that is terme! a ?+ecurity Test?. The
+ecurity Test is itself compose! of a set of security checks that must be performe!. -ach security
check is !efine! as a $ealm which !efines how the cre!entials are collecte! Aan AuthenticatorD an!
how those cre!entials are vali!ate! A*ogin mo!uleD.
The entries are !efine! in a configuration file calle! ?autheticatioCo$ig%*,l? which is
part of ever "orklight pro6ect.
+ee alsoK
re!2ook 8 +ecuring your mobile business with '2M "orklight 8 .913:19:94
Page /3
!ecure on,de$ice stored data
The nature of a mobile !evice is that L it is mobile. This means it can be carrie! aroun! with you
an!B as suchB can be lost by you. +ince mobile !evices are fre)uently lostB we have the concept that
any !ata kept on that !evice may be accesse! by unwante! parties. To solve that problemB we have
the option to encrypt sensitive !ata. This means that the !ata is converte! into an unintelligible
form an! if it became known in that stateB woul!nMt be of any use to receiver.
"orklight provi!es the ability to encrypt an! !ecrypt !ata an! have that !ata store! in either
3TM*# local storage or in the "orklight ;+0N+tore.
+ee alsoK
0ff:line +torage
%ffline Authentication
'f a mobile !evice is not network connecte! a user may still have to prove that they are who they
claim to be before using an app. This is actually )uite easy to !o. 'f information is save! encrypte!
to local storage when a userMs i!entity is prove! then when !isconnecte!B the keys to !ecrypt the
!ata will only be known by the actual user.
Pre$enting tampered apps
A concern that nee!s to be a!!resse! is the notion that an app can be tampere! with by a malicious
programmer. This coul! happen in a number of ways. Perhaps the app was replace! on the !evice
while it was out of your !irect control. Perhaps the app that you !ownloa!e! was from a fake
repository. -ither wayB you coul! be tricke! into thinking you are running a legitimate app when in
fact it is a trap.
"orklight can !etect a tampere! app by signing the original app. "hen an app tries to contact
"orklight +erver through an a!apterB it sen!s knowle!ge of whether or not it was mo!ifie! an!
"orklight can !isallow mo!ifie! apps.
Direct *pdate
>or "eb an! 3ybri! "orklight applicationsB we have the ability to push up!ates to an app to the
!evice transparently. This feature is calle! ?irect 7p!ate?.
Remote Disable
'f a version of an app is known to contain a security flawB access to "orklight server by apps of that
version can be !isable!. -ffectively !isabling that version of the app.
Worlight protected resources
"orklight can protect the following types of resourcesK
Application
A!apter Proce!ure
-vent +ource 8 A re)uest to subscribe to a push notification
+tatic $esource
Page /1
Cross site R#!T calls
'f you are using the %hrome web browserB it has a comman! line option calle! ?--disable-
"eb-security? that switches off web security A+ame 0rigin PolicyD for that instance of the
browser. This is useful for !evelopment but shoul! never be use! or suggeste! for pro!uction.
5ou will know it is working because you will see a warning messageK
+ee alsoK
3TTP access control A%0$+D
%ross:0rigin $esource +haring : .911:91:1&
Programatically authenticating .ith WA!
"hen interacting with a "A+ serverB on many occasions the "A+ server has to know who we are
in or!er to allow us to interact.
+ee alsoK
7sing the ;ava Authentication an! Authorization +ervice programming mo!el for web authentication
Application Deplo"ment
0nce you have built a "orklight applicationB you are very likely going to want to !eploy this for
e<ecution.
To !eploy "orklight applications to a "A+ serverB !atabase entries are re)uire!. 3ere is a
summary of the recipeK
1. %reate a system user calle! ?worklight?.
.. %reate the !atabase
%$-AT- ATA2A+- "$,*@3T %0**AT- 7+'N@ +5+T-M PA@-+'P- 3.4&(
%0NN-%T T0 "$,*@3T
@$ANT %0NN-%T 0N ATA2A+- T0 7+-$ worklight
=7'T
3. !!!!
!b. %0NN-%T T0 "$,*@3T 7+-$ worklight 7+'N@ passwor!
Page /#
!b. +-T %7$$-NT +%3-MA N M"$,+%3MM
!b. :vf QworklightIinstallI!irRH"orklight+erverH!atabasesHcreate:worklight:!b..s)l :t
1. %reate a !ata source for the "orklight !atabase
Page /&
Page /4
Page /(
#. %reate the "orklight $eports atasource
Page //
Page 199
&. %reate the "0$,*'@3TI'N+TA**I'$ variable
4. efine a new share! library entry
Page 191
(. !
/. !
19. !
11. !
1..
13. s
11. s
&perations
After having installe! an! configure "orklight an! built applications for !istributionB it is likely
that you will want to operate an! maintain a variety of components inclu!ing "orklight +erver.
Areas to be consi!ere! inclu!ing backing up the system for recoveryB performance tuningB security
consi!erations
Programming 'eferences
Page 19.
Client !ide API Programming
A ;ava+cript ob6ect calle! ?W+? is create! by the "orklight framework. This can then be use! as
the root or name:space for all other functions.
WL)Client
The ;ava+cript ob6ect calle! ?W+? contain a chil! ob6ect calle! ?Cliet? which acts as a container
for a set of metho!s relate! to client si!e functions. The following act as a gui!e an! notes on some
of the functions available.
The common &options& o"'ect
Many of the functions !ocumente! here accept an ?options? ob6ect. This ob6ect is common
amongst many of the asynchronous calls. This ob6ect contains the following propertiesK
o#uccess 8 A callback function that receives a ?response? ob6ect. The response ob6ect
will contain Aamongst other itemsDK
invocation%onte<t
status
o5ailure 8 A callback function that is invoke! if an errorHfailure is !etecte!. The
function is passe! a response ob6ect which will containK
invocation%onte<t
error%o!e
errorMsg
status
invocation%onte<t 8 An ob6ect which will be passe! through to the response ob6ects so that
they may have conte<tHcorrelation between a call an! a response. This is necessary since
many of the responses will be returne! asynchronously.
(L)Client)add*lo"alHeader+header,ame- header.alue/
"hen calle! this metho! a!!s an 3TTP hea!er to the network connections ma!e in all subse)uent
re)uests to the "orklight +erver.
header!a,e 8 The name of the 3TTP hea!er property to a!!.
header:alue 8 The value of the 3TTP hea!er property to a!!.
+ee alsoK
"*.%lient.remove@lobal3ea!erAhea!erNameD
(L)Client)close+/
This metho! closes a wi!get in the A!obe A'$ environment.
Page 193
(L)Client)connect+options/
This metho! forms a connection to the "orklight +erver. 't must be e<ecute! before any other AP'
calls from the client which may also wish to connect to the server.
optios 8 The options passe! into the connect re)uest. This ob6ect contains the following
!efinable propertiesK
o#uccess 8 A function that is calle! when the connection to the "orklight +erver
has been complete!.
o5ailure 8 A function that is calle! when a re)uest to connect with the "orklight
+erver fails. The function is passe! an error in!ication.
ti,eout 8 3ow many millisecon!s we shoul! wait before giving up on the
connection.
The function can cause events to occurK
"*.-vents."0$,*'@3TI'+I%0NN-%T-
"*.-vents."0$,*'@3TI'+I'+%0NN-%T-
(L)Client)deleteUserPref+0e1- options/
This metho! !eletes a user preference specifie! by the ?key? parameter.
(L)Client)getAppPropert1+propert1,ame/
This metho! retrieves a value for a specifie! property.
The properties that can be retrieve! areK
(ame Description
W+%AppProperty%AI7@IC/!@LH*LH@PA<H
W+%AppProperty%AI7@IC/!@LI=*LI=@PA<H
W+%AppProperty%E/W!+/AE@APP@+I!M
W+%AppProperty%APP@EI#P+AN@!AM(
W+%AppProperty%APP@+/?I!@<NP(
W+%AppProperty%APP@:(7#I/!
W+%AppProperty%+A!?8A?(
W+%AppProperty%+A<(#<@:(7#I/!
W+%AppProperty%MAI!@5I+(@PA<H
W+%AppProperty%#H/W@I!@<A#MBA7
>or A!obe A'$ apps onlyB shoul! the app show in the task
bar.
W+%AppProperty%<H8MB!AI+@IMA?(@87+
An absolute 7$* for the thumbnail image for the
application.
(L)Client)getEn$ironment+/
$eturns the environment in which the application is runningB possible values inclu!eK
"*.-nvironment.A02-IA'$
Page 191
"*.-nvironment.AN$0'
"*.-nvironment.-M2--
"*.-nvironment.'PA
"*.-nvironment.'P30N-
"*.-nvironment.M02'*-I"-2
"*.-nvironment.P$-C'-"
"*.-nvironment."'N0"+IP30N-I(
"*.-nvironment."'N0"+IP30N-
"*.-nvironment."'N0"+(
(L)Client)getLogin,ame+realm/
$eturns the login name the user use! !uring authentication.
realm 8 JJJ
+ee alsoK
"*.%lient.get7serNameArealmD
(L)Client)getUserInfo+realm- 0e1/
$etrieve a property of the current use! name! by the key.
realm 8 JJJ
key 8 JJJ
(L)Client)getUser,ame+realm/
$etrieve the real name of the current user.
realm 8 JJJ
+ee alsoK
"*.%lient.get*oginNameArealmD
(L)Client)getUserPref+0e1/
$etrieve a user preference by key. 'f no preference is known for that keyB null is returne!.
key 8 JJJ
+ee alsoK
"*.%lient.has7serPrefAkeyD
"*.%lient.set7serPrefAkeyB valueB optionsD
"*.%lient.set7serPrefsAprefsB optionsD
(L)Client)hasUserPref+0e1/
etermine if there is a user preference for the supplie! key
Page 19#
key 8 JJJ
+ee alsoK
"*.%lient.get7serPrefAkeyD
"*.%lient.set7serPrefAkeyB valueB optionsD
"*.%lient.set7serPrefsAprefsB optionsD
(L)Client)init+options/
'nitialize the "orklight client environment. This metho! shoul! be calle! before any other
W+%Cliet function. 't is commonly calle! in the ?iit/ptios%.s? ;ava+cript file.
optios 8 The options !efining the initialization of the "*.%lient environment
ti,eout 8 The timeout in millisecon!s for all calls to the "orklight server. 'f not
supplie!B a timeout of 39 secon!s is use!.
eable+ogger 8 %ontrols whether or not W+%+ogger%debug34 output will be
logge!. +ettings this to ?true? A!efaultD causes !ebug output to appear in the appropriate
log.
,essages 8 A !ictionary ob6ect for localizing message te<t.
autheticator 8 An ob6ect that implements the Authenticator AP'.
heartBeatIter6alI#ecs 8 3ow often the client an! the "orklight server
shoul! initiate a hear!beat re)uest. The !efault is seven minutes. +ee alsoK
"*.%lient.set3eart2eat'ntervalAintervalD
coect/#tartup 8 +houl! the client application connect to the "orklight server
at startupJ The !efault is ?false?.
oCoectio5ailure 8 A callback function calle! if the client fails to connect to
the "orklight server on startup.
o8supported:ersio 8 A callback function calle! if the client version is no
longer supporte!.
on$e)uestTimeout
on7nsupporte!2rowser
onisable!%ookies
on7ser'nstanceAccessCiolation
on-rror$emoteisableenial
on-rrorAppCersionAccessenial
vali!ateArugments 8 A flag controlling whether or not the client library shoul! vali!ate
the number an! types of parameters passe!. The !efault is ?true?.
up!ate+ilently
on@et%ustomevicePorivisioingProperties
Page 19&
(L)Client)in$o0eProcedure+in$ocation!ata- options/
'nvoke a proce!ure e<pose! by an a!apter.
i6ocatioEata 8 ata passe! in to control the re)uest to the a!apter. This ob6ect
contains the following propertiesK
adapter 8 The name of the a!apter which is to be invoke!. This is a man!atory
property.
procedure 8 The name of the proce!ure e<pose! by the a!apter that is to be invoke!.
This is a man!atory property.
para,eters 8 An optional array of parameters that is to be passe! through the a!apter
to the back:en!.
co,press7espose 8 An optional in!ication as to whether the response shoul! be
compresse!.
options 8 0ptions use! to han!le the response from the a!apater call. This ob6ect contains
the following propertiesK
ti,eout 8 The number of millisecon!s to wait before timing out the re)uest.
o#uccess 8 A function which will be invoke! when the a!apter response is available
an! the a!apter in!icates that it was successful. The response function receives an
ob6ect parameter with the following properties
i6ocatioCote*t 8 An optional invocation conte<t ob6ect that was passe! in
with the original proce!ure invocation.
status 8 The 3TTP status co!e.
i6ocatio7esult 8 A !escription of the results of performing the re)uest.
o5ailure 8 A function which will be invoke! when the a!apter returns an error
in!ication. The error response function receives the same types of parameters as the
successful response.
invocation%onte<t
(L)Client)isUserAuthenticated+realm/
etermines whether or not the client is currently authenticate!.
realm 8 JJJ
(L)Client)logActi$it1+acti$it1T1pe/
A function which when calle! will log that the client has performe! some activity. This is use! for
au!iting an! reporting.
acti6ity<ype 8 A te<t string that !escribes the activity being performe! by the client.
(L)Client)login+realm- options/
A function which when calle! will login a user.
Page 194
realm 8 JJJ
options 8 JJJ
(L)Client)logout+realm- options/
A function which when calle! will logout the user.
realm 8 JJJ
options 8 JJJ
(L)Client)minimi2e+/
Minimize a wi!get when A!obe A'$ is use! as the !eployment target.
(L)Client)reloadApp+/
$eloa! the whole application.
(L)Client)remo$e*lo"alHeader+header,ame/
$emove an 3TTP hea!er !efinition sent to the "orklight server by this client application. The
hea!er woul! previously have been a!!e! by a call to "*.%lient.a!!@lobal3ea!erAD.
header!a,e 8 The name of the hea!er property to remove.
+ee alsoK
"*.%lient.a!!@lobal3ea!erAhea!erNameB hea!erCalueD
(L)Client)setHeart#eatInter$al+inter$al/
+et the interval to be use! to check connectivity between the client an! the "orklight server. The
value is supplie! as the number of secon!s.
+ee alsoK
"*.%lient.initAoptionsD
(L)Client)setUserPref+0e1- $alue- options/
+et or change a name! property for a user to a specific value. There are a ma<imum of 199
properties that can be set per user.
key 8 The name of the property
value 8 The value of the property
options 8 JJJ
+ee alsoK
"*.%lient.get7serPrefAkeyD
"*.%lient.has7serPrefAkeyD
"*.%lient.set7serPrefsAprefsB optionsD
Page 19(
(L)Client)setUserPrefs+prefs- options/
+et multiple properties for a user in one single call.
prefs 8 A ;ava+cript ob6ect where the names of the properties in the ob6ect will be use! as
the names of the properties to be create! an! the correspon!ing values in the ob6ect use! as
the values of the properties.
options 8 JJJ
+ee alsoK
"*.%lient.get7serPrefAkeyD
"*.%lient.has7serPrefAkeyD
"*.%lient.set7serPrefAkeyB valueB optionsD
(L)Client)updateUserInfo+options/
$efreshes the !ata that will be returne! byK
"*.%lient.get7serNameArealmD
"*.%lient.get*oginNameArealmD
"*.%lient.is7serAuthenticate!ArealmD
+ee alsoK
"*.%lient.get7serNameArealmD
"*.%lient.get*oginNameArealmD
"*.%lient.is7serAuthenticate!ArealmD
(L)#us1Indicator+containerId- options/
This function will show a ?2usy? bo< on the screen which contains some te<t. 'n a!!itionB all
other interactions with the 7' will be suspen!e!. %reating the busy in!icator !oesnMt automatically
show itB use the showAD metho! to make it visible.
%heck the reference gui!e for !etails of which options are available in which 0+ versions.
Propert" Description
te*t
The te<t to show in the 2usy te<t bo<.
bouceAi,atio
opacity
te*tColor
stroke/pacity
$ull#cree
bo*+egth
duratio
,iEuratio
An instance of the in!icator can be shown with the ?sho"34? metho! an! hi!!en with the
?hide34? metho!.
A busy in!icator is commonly constructe! an! then shown. >or e<ampleK
Page 19/
6ar busy 0 e" W+%BusyIdicator3ullC B 1te*t1: 1IO, BusyP1D42
busy%sho"342
0n an An!roi! !evice this will show asK
(L)Toast)show+message/
>or An!roi! onlyB shows a ?Toast? message.
"*.%lient.init
"*.%lient.reloa!App
"*.%lient.login
"*.%lient.logout
"*.%lient.get-nvironment
"*.%lient.set7serPref
"*.%lient.set7serPrefs
"*.%lient.get7serPref
"*.%lient.!elete7serPref
Page 119
"*.%lient.has7serPref
"*.%lient.logActivity
WL)J!"tore
The "*.;+0N+tore functions provi!e access to the ;+0N+tore AP's.
(L)JS3,Store)add+data- options/
The a!!AD metho! a!!s a new !ocument into the collection.
!ata 8 A ;ava+cript ob6ect or array of ob6ects that will be a!!e! to the collection
options 8 A ;ava+cript ob6ect that provi!es options to the a!!AD metho!K
a!!itional+earch>iel!s
push
The a!!AD metho! returns a Promise.
(L)JS3,Store)changePassword+oldPassword- newPassword- user,ame/
The changePasswor!AD metho! changes the passwor! on a collection.
ol!Passwor! 8 The original passwor! of the new collection.
newPasswor! 8 The new passwor! of the collection.
userName 8 The i!entity of the user changing the passwor!.
The changePasswor!AD metho! returns a Promise.
(L)JS3,Store)closeAll+/
%lose access to all currently opene! collections.
(L)JS3,Store)count+/
etermine the number of !ocuments insi!e a given collection.
The countAD metho! returns a Promise.
(L)JS3,Store)destro1+/
$emoves all ;+0N+tore information for the application inclu!ing storesB collectionsB !ocuments
an! meta:!ata.
(L)JS3,Store)documentif1+id- data/
@iven a !ocument ' an! a ;ava+cript ob6ect representing !ataB a ;+0N+tore !ocument instance is
create!.
i! 8 The i! of a !ocument
!ata 8 A ;ava+cript ob6ect representing !ata
The !ocumentifyAD metho! returns a ;+0N+tore !ocument ob6ect.
Page 111
(L)JS3,Store)enhance+name- func/
This function will a!! a name! metho! to the prototype of %ollections effectively e<ten!ing their
capabilities.
name 8 The name of the new function to a!!.
func 8 The implementation of the new function.
The enhanceAD metho! returns a success co!e.
(L)JS3,Store)find+4uer1- options/
This function searches a collection to retrieve the set of !ocuments that match a given criteria. 'f
the )uery ob6ect is !efine! as ?EF? then all !ocuments in the collection will be returne!.
)uery 8 A ;ava+cript ob6ect with properties that will be use! as keys on the ;+0N+tore to
fin! matching !ocuments.
options
e<act 8 "hether or not fuzzy matching AfalseD or e<act matching AtrueD shoul! be use! to
locate !ocuments.
limit 8 A constraint !efining the ma<imum number of !ocuments to be returne!. The
result may be fewer than this value if the )uery woul! result in less than this.
offset 8 A zero base! offset into the results returne!. 7sing offset an! limit together can
achieve ?pagination? of results.
The fin!AD metho! returns a promise.
(L)JS3,Store)findAll+options/
$eturn all !ocuments in the collection without performing a comparison by key.
options
limit 8 A constraint !efining the ma<imum number of !ocuments to be returne!. The
result may be fewer than this value if the )uery woul! result in less than this.
offset 8 A zero base! offset into the results returne!. 7sing offset an! limit together can
achieve ?pagination? of results.
The fin!AllAD metho! returns an array of !ocuments.
(L)JS3,Store)find#1Id+id/
$eturns all !ocuments with the specifie! '!. '! may be a single !ocument i! or an array of i!s.
(L)JS3,Store)get+collection,ame/
*ookup an! retrieve a ;+0N+tore collection by name. The ob6ect returne! has metho!s on it
correspon!ing to the metho!s available for collections.
collectionName 8 The name of a collection.
The getAD metho! returns a ;ava+cript ob6ect which has metho!s on it correspon!ing to the metho!s
available on a collection.
Page 11.
(L)JS3,Store)getErroressage+errorCode/
$etrieve a string representation of a ;+0N+tore error !escribe! by the error%o!e parameter.
error%o!e 8 The error co!e for which we wish the te<tual message
The get-rrorMessageAD function returns a string representation of the message associate! with the
error co!e.
(L)JS3,Store)getPush5e4uired+/
$etrieve a list of ;+0N+tore !ocuments that are consi!ere! ?!irty? an! nee! to be pushe! back to
the back:en! for up!ate.
The getPush$e)uire!AD metho! returns an array of ;+0N+tore !ocuments.
(L)JS3,Store)init+/
'nitializes one or more ;+0N+tore collections. This is a per:re)uisite that must be performe!
before accessing the store with the getAD metho!.
'f a collection has not been initialize! before an! a passwor! is supplie! the physical !ata hosting
the collection is encrypte! using that passwor! an! a token. The token is generate! either on the
client si!e Alocalkeygen is MfalseMD or on the server si!e Alocalkeygen is MtrueMD.
collections
collectionName 8 The name of the collection to be initialize!.
search>iel!s 8 escription of which fiel!s are in!e<e! when !ocuments are a!!e! to a
collection.
a!!itional+earch>iel!s 8 escription of which fiel!s are in!e<e! when !ocuments are
a!!e! to a collection.
a!apter
name 8 The name of the a!apter which this ;+0N+tore interacts with.
a!! 8 The name of a proce!ure e<pose! by the a!apter to be use! to a!! !ocuments
to the back:en! through a call to the a!apter.
remove 8 The name of a proce!ure e<pose! by the a!apter to be use! to remove
!ocuments from the back:en! through a call to the a!apter.
loa!
proce!ure
params
key
accept
timeout
options
username 8 7se! to construct the un!erlying file name hol!ing the store.
passwor! 8 The passwor! re)uire! to access the collection.
Page 113
clear
localkeyge 8 'f a passwor! is supplie! an! encryption to be use!B a token is
obtaine! as part of the encryption process. "here the token is generate! is controlle! by
this parameter. The token can be generate! on the client AtrueD or on the server AfalseD.
The initAD metho! returns a promise.
(L)JS3,Store)isPush5e4uired+doc/
etermines whether the given !ocument has ha! changes ma!e to it which woul! be pushe! to the
server. $eturns true if it woul! be pushe! an! false otherwise.
!oc 8 -ither a !ocument ob6ect or a !ocument i!
The isPush$e)uire!AD metho! returns a promise.
(L)JS3,Store)load+/
'nvoke the associate! a!apter to loa! the content of the collection from the !ata returne! from the
a!apter.
The loa!AD metho! returns a promise.
(L)JS3,Store)push+docs/
Push the !ocuments in the collection that are flagge! as rea!y for a push to the a!apter. 0ptionallyB
an array of !ocuments or a !ocument or a !ocument i! can be supplie!.
The pushAD metho! returns a promise.
(L)JS3,Store)push5e4uiredCount+/
etermine the number of !ocuments that will be pushe! to a back:en! through an a!apter.
The push$e)uire!%ountAD metho! returns a promise.
(L)JS3,Store)remo$e+doc- options/
This function will remove a !ocument from a collection an! optionally flag it for push to remove
through the a!apter.
!oc 8 An array of !ocumentsB a single !ocument or a !ocument i!
options
push 8 shoul! the removal also be pushe! through the a!apter AtrueD or 6ust remove!
from the local collection AfalseD.
The removeAD metho! returns a Promise.
(L)JS3,Store)remo$eCollection+/
eletes all the !ocuments store! within a collection.
The remove%ollectionAD metho! returns a Promise.
Page 111
(L)JS3,Store)replace+doc- options/
$eplace !ocuments within a collection with !ifferent versions.
!oc 8 A single !ocument or an array of !ocuments
options
psuh 8 A flag that controls whether or not the replacement shoul! be pushe! through to
the back:en! through the a!apter.
The replaceAD metho! returns a Promise.
(L)JS3,Store)toString+/
*ogs the !ocuments in the collection to the !ebugger log by invoking "*.*ogger.!ebug.
WL1De$ice
WL)Device)get"et%orkInfo*callback+
$etrieves network information for i0+ or An!roi! !evices. The single parameter is a callback
function that is passe! an ob6ect that !escribes the properties. This function is only available for
An!roi! an! i0+ !evices.
The properties inclu!eK
isNetwork%onnecte! 8 's the !evice connecte! to a network AtrueD.
isAirplaneMo!e
is$oaming
et"orkCoectio<ype 8 The type of network connectionB namely how the !evice is
connecte! to the network. The choices areK
,obile 8 The !evice is connecte! via a wireless telephony link.
WI5I 8 The !evice is connecte! via "'>'.
wifiName
telphonyNetworkType
carrierName
ipA!!ress
!ther
"*.App.open7$*
"*.App.getevice*anguage
"*.App.getevice*ocale
"*.2usy'n!icator
"*.Tab2ar
"*.+impleialog
"*.0ptionsMenu
Page 11#
"*.*ogger.!ebug
!er$er !ide API Programming
+erver si!e programming is buil!ing logic that is e<ecute! when a client invokes an a!apter.
+ee alsoK
A!apter %omponents
A!apters
WL)erver
(L)Ser$er)in$o0eS%LStoredProcedure+options/
This AP' metho! invokes a 2 store! proce!ure. 't may only be invoke! from within a +=*
a!apter implementation.
optios 8 0ptions that govern how the +=* proce!ure is invoke!.
procedure 8 The name of the 2 hoste! proce!ure to invoke.
para,eters 8 Any parameters re)uire! by the proce!ure.
+ee alsoK
"*.+erver.create+=*+tatementAstatementD
"*.+erver.invoke+=*+tatementAoptionsD
+=* A!apter
(L)Ser$er)createS%LStatement+statement/
This AP' metho! creates a +=* statement. 't may only be invoke! from within a +=* a!apter
implementation.
state,et 8 A +=* statement to be e<ecute!.
The return from this function is a ?prepare! statement? that can then be submitte! for e<ecution
against the !atabase.
+ee alsoK
"*.+erver.invoke+=*+tore!Proce!ureAoptionsD
"*.+erver.invoke+=*+tatementAoptionsD
+=* A!apter
(L)Ser$er)in$o0eS%LStatement+options/
This AP' metho! invokes a +=* statement that was previously constructe! with
W+%#er6er%create#&+#tate,et34. 't may only be invoke! from within a +=* a!apter
implementation.
optios 8 0ptions that govern the e<ecution of the +=* statement.
prepared#tate,et 8 The output of a previous calle! to
W+%#er6er%create#&+#tate,et34.
Page 11&
para,eters 8 Any parameters re)uire! by the proce!ure.
+ee alsoK
"*.+erver.invoke+=*+tore!Proce!ureAoptionsD
"*.+erver.create+=*+tatementAstatementD
+=* A!apter
(L)Ser$er)in$o0eHttp+options/
This AP' metho! makes an 3TTP call from the "orklight +erver to a back:en! 3TTP service
provi!er. This AP' call is onl" meaningful to be calle! in the conte<t of an 3TTP A!apter
proce!ure invocation. Note that the host an! port of the re)uest are not supplie! as part of the
parameters to this re)uest. 'nstea! they are conte<tual an! supplie! by the 3TTP A!apter
properties of the 3TTP A!apter in which the proce!ure is being invoke!.
The signature of the AP' isK
W+%#er6er%i6okeHttp3optios4
The optios parameter is a ;ava+cript ob6ect which can have the following propertiesK
,ethod 8 The 3TTP metho! to be use! to perform the re)uest. Cali! options areK
get 8 -<ecute a $-+T re)uest with the @-T 3TTP verb
post 8 -<ecute a $-+T re)uest with the P0+T 3TTP verb
put 8 -<ecute a $-+T re)uest with the P7T 3TTP verb
delete 8 -<ecute a $-+T re)uest with the -*-T- 3TTP verb
path 8 The relative part of the 7$* to which the re)uest will be sent.
returedCotet<ype 8 The !ata type returne! by the calle! 3TTP service.
Allowable choices areK
.so 8 The !ata returne! shoul! be consi!ere! a ;+0N ob6ect
plai 8 The !ata returne! shoul! be consi!ere! un:interprete! plain te<t
*,l 8 The !ata returne! shoul! be consi!ere! an GM* !ocument
ht,l 8 The !ata returne! shoul! be consi!ere! an 3TM* page
cs6 8 The !ata returne! shoul! be consi!ere! comma separate! values
.a6ascript 8 The !ata returne! shoul! be consi!ere! a fragment of ;ava+cript
css 8 The !ata returne! shoul! be consi!ere! a %asca!ing +tyle +heet
returne!%ontent-nco!ing
para,eters 8 A ;ava+cript ob6ect whoMs properties will be use! as )uery parameters in
the 3TTP re)uest to the back:en!. The propertyMs value will be use! as the value of the
)uery parameter.
headers 8 Any 3TTP hea!ers that shoul! be a!!e! to the re)uest.
cookies
body 8 for re)uests of type P0+T an! P7T onlyB the payloa! of the 3TTP re)uest if
Page 114
supplie!.
transformation
7nusually the i6okeHttp34 metho! seems to e<ecute synchronously. The result is a
;ava+cript ob6ect that contains the response from the 3TTP re)uest.
The properties in the response areK
info
errors
warnings
is+uccessful 8 true or false
resposeHeaders 8 The 3TTP hea!ers receive! in the response from the 3TTP
re)uest.
respose<i,e 8 The 3TTP response time in millisecon!sB
total<i,e 8 The total time in millisecon!s.
result 8 A ;ava+cript ob6ect representing the result returne! from the 3TTP re)uest. 'f
the result returne! from the 3TTP re)uest is not ;+0N enco!e!B it has to be first
transforme! into a ;ava+cript ob6ect.
statusCode 8 The 3TTP status co!e. .99 means ok.
status$eason
0,

The following is an e<ample of a ;ava+cript ob6ect returne! by invoke3ttp.

B
1errors1: Q
RC
1i$o1: Q
RC
1is#uccess$ul1: trueC
1resposeHeaders1: B
1Cache-Cotrol1: 1,a*-age0>C public1C
1Coectio1: 1Meep-Ali6e1C
1Cotet-<ype1: 1te*t\-*,l1C
1Eate1: 1WedC G> /ct I>LG L=:>I:>S ?M<1C
1(*pires1: 1WedC G> /ct I>LG L=:>I:>S ?M<1C
1Meep-Ali6e1: 1ti,eout0L>C ,a*0G>1C
1#er6er1: 1Apache1C
1<ras$er-(codig1: 1chuked1C
1:ary1: 1Accept-(codigC8ser-Aget1
DC
1respose<i,e1: GG'C
1result1: B
1rep1: Q
B
1district1: 1#eior #eat1C
1lik1: 1http:\-\-"""%cory%seate%go61C
1a,e1: 1Joh Cory1C
1o$$ice1: 1'LT Hart #eate /$$ice Buildig1C
1party1: 171C
1phoe1: 1I>I-IIS-IUGS1C
1state1: 1<A1
DC
B
1district1: 1Juior #eat1C
1lik1: 1http:\-\-"""%cru)%seate%go61C
Page 11(
1a,e1: 1<ed Cru)1C
1o$$ice1: 1L=' Eirkse #eate /$$ice Buildig1C
1party1: 171C
1phoe1: 1I>I-IIS-'UII1C
1state1: 1<A1
D
R
DC
1statusCode1: I>>C
1status7easo1: 1/M1C
1total<i,e1: GSUC
1"arigs1: Q
R
D
"e have the ability to test a W+%#er6er%i6okeHttp34 e<ecution !irectly from within
"orklight +tu!io. 2efore we e<plain that it more !etailB let us think about what such a test actually
means. @iven that this metho! calls a back:en! serviceB testing this metho! will perform a call to a
back:en! service. The configuration options of the i6okeHttp function are supplie! as a rich
set of parameters to that function. The act of ?testing? this function really boils !own to testing that
we have built the options to control it correctly an! vali!ating that the back:en! service respon!s as
!esire! when actually calle!.
The way we perform the test is to buil! an 3TTP A!apter an! !eploy it to the "orklight +erver.
The implementation ;ava+cript of the a!apter !oes not nee! to be enhance! or change! beyon! its
!efault settings. $ememberB it is the a!apterMs configuration that names where the $-+T re)uest
will be sent. "hen we test an i6okeHttp34 function callB it will be the !estination settings of
the a!apter that will be use! as !estination of the $-+T re)uest. 0nce the a!apter is !eploye!B we
can right:click the a!apter within the "orklight +tu!io pro6ect an! select 7u As > I6oke
Worklight Back-ed #er6iceK
Page 11/
This will open a !ialog into which we can enter a ;ava+cript 0b6ect that will be passe! as the
parameters to the function. Note that e<perience seems to show that the names of the properties
have to be surroun!e! in )uotes.
Page 1.9
"hen the $un button is clicke!B the i6okeHttp function is e<ecute! by the "orklight server in
the conte<t of the !eploye! a!apter. A further !ialog is shown which shows the raw !ata that was
receive! by the a!apter when it ma!e the actual $-+T re)uest to the back:en! as well as a win!ow
area in which the ;ava+cript ob6ect returne! to i6okeHttp can be seen.
Page 1.1
+ee alsoK
3TTP A!apter Proce!ure implementations
(L)Ser$er)readSingleJSessage+options/
This AP' metho! rea!s a ;M+Te<t message from a ;M+ )ueue. The message is consume! from the
Page 1..
)ueue.
optios 8 A !escription of how the message is to be rea!
destiatio 8 The ;N' name of the )ueue from which the message is to be rea!.
ti,eout 8 The optional !uration in millisecon!s to wait for a message to arrive if no
message is imme!iately available. A value of 9 means wait in!efinitely while a value
less than 9 means !o not wait at all. 'f not supplie!B the !efault is not to wait.
$ilter 8 The optional message filter to be use! to choose a message. The !efault is
not to filter an! hence the ne<t available message will be returne!.
+ee alsoK
"*.+erver.rea!All;M+MessagesAoptionsD
"*.+erver.write;M+MessageAoptionsD
"*.+erver.re)uest$eply;M+MessageAoptionsD
;M+ A!apter
(L)Ser$er)readAllJSessages+options/
This AP' metho!s rea!s all ;M+Te<t messages from a ;M+ )ueue. The messages are consume!
from the )ueue.
optios 8 A !escription of how the messages are to be rea!
destiatio 8 The ;N' name of the )ueue from which the messages are to be rea!.
ti,eout 8 The optional !uration in millisecon!s to wait for a message to arrive if no
message is imme!iately available. A value of 9 means wait in!efinitely while a value
less than 9 means !o not wait at all. 'f not supplie!B the !efault is not to wait.
$ilter 8 The optional message filter to be use! to choose messages. The !efault is
not to filter an! hence the ne<t available message will be returne!.
+ee alsoK
"*.+erver.rea!+ingle;M+MessageAoptionsD
"*.+erver.write;M+MessageAoptionsD
"*.+erver.re)uest$eply;M+MessageAoptionsD
;M+ A!apter
(L)Ser$er)writeJSessage+options/
This AP' metho! writes a ;M+Te<t message to a ;M+ )ueue.
optios 8 The options use! to write the message to the )ueue.
destiatio 8 The ;N' name of the )ueue into which the message will be written.
,essage 8 The message to be written to the )ueue.
body 8 The bo!y AcontentD of the message.
properties 8 The ;M+ message hea!er properties.
ttl 8 The optional message time to live. 'f the message is not consume! from the
)ueue within this intervalB it will self !estruct. The interval is measure! in millisecon!s.
Page 1.3
'f not supplie!B the message will not e<pire.
+ee alsoK
"*.+erver.rea!+ingle;M+MessageAoptionsD
"*.+erver.rea!All;M+MessagesAoptionsD
"*.+erver.re)uest$eply;M+MessageAoptionsD
;M+ A!apter
(L)Ser$er)re4uest5epl1JSessage+options/
This AP' metho! writes a ;M+Te<t message to a !efine! )ueue an! then awaits a response on a
secon! )ueue. The secon! )ueue is !ynamically create! to receive the message an! is then
!ispose! of at the en!.
optios 8 The options use! to write the message to the )ueue an! wait for a response.
destiatio 8 The ;N' name of the )ueue into which the message will be written.
,essage 8 The message to be written to the )ueue.
body 8 The bo!y AcontentD of the message.
properties 8 The ;M+ message hea!er properties.
ti,eout 8 The optional !uration in millisecon!s to wait for a message to arrive if no
message is imme!iately available. A value of 9 means wait in!efinitely while a value
less than 9 means !o not wait at all. 'f not supplie!B the !efault is not to wait.
ttl 8 The optional message time to live. 'f the message is not consume! from the
)ueue within this intervalB it will self !estruct. The interval is measure! in millisecon!s.
'f not supplie!B the message will not e<pire.
+ee alsoK
"*.+erver.rea!+ingle;M+MessageAoptionsD
"*.+erver.rea!All;M+MessagesAoptionsD
"*.+erver.write;M+MessageAoptionsD
;M+ A!apter
Page 1.1
An!roi! Development
Installing the Android !D"
The An!roi! +, is re)uire! for buil!ing An!roi! applications. 't shoul! be !ownloa!e! an!
installe! into the same machine as +tu!io.
As of .913:11:11 the web page for !ownloa!ing the An!roi! +, isK
An!roi! +,
't is about 1(9M2ytes in total.
Managing the Android !D"
Android #mulator
The An!roi! +, comes with an An!roi! !evice emulator. This can be use! to test a "orklight
application.
An optional component calle! the ?'ntel <(& -mulator Accelerator A3AGMD? may be installe!
through the +, Manager.
After installing the packageB a new installable "in!ows program can be foun! atK
Q+,+RHe<trasHintelH3ar!wareIAccelerate!I-<ecutionIManager
Page 1.#
)avaScript rame*orks
)2uery Mobile
Do)o and Do)o Mobile
"hen creating a new appB we have the opportunity to select to inclu!e the o6o libraryK
"hen o6o is use! in an applicationB two files are a!!e! calle!K
buil!:!o6o.properties
buil!:!o6o.<ml
+ee alsoK
2log 8 The o6o *ibrary in "orklight +tu!io C&.9 8 .913:9(:93
o6o Programming
!encha Touch
Page 1.&
+ocal storage of !ata
'!eallyB a Mobile App shoul! also be able to operate when it is not currently connecte! to the
network. 'n other wor!sB it shoul! be able to operate while ?!isconnecte!?. To achieve thisB !ata
that it may nee! to work may have to be available on the !evice. To achieve thatB the application
will nee! mechanisms to both store an!s retrieve such !ata.
2y the nature of mobile appsB there is also a new problem. The !evice on which the mobile app is
hoste! may be lost or stolen. This implies that any !ata associate! with the app will no longer be
un!er control. "hen storing !ataB we nee! a mechanism to encrypt that !ata such that it canMt be
e<amine! on a compromise! !evice.
Page 1.4
Web Programming
"eb programming is the notion of writing applications that will e<clusively run within the browser.
The skills necessary for any web programming task usually consist ofK
3TM* 8 A knowle!ge of the core !eclarative language of the browser.
%++ 8 A knowle!ge of how to style elements in the browser page.
;ava+cript 8 ,nowle!ge of the ;ava+cript programming language which is the language
supporte! by all browsers.
0M 8 A knowle!ge of the programming mo!el for the web page an! how the browser
?really? sees the web page.
A ;ava+cript toolkit such as o6o.
+ee alsoK
o6o Programming
6=uery
De$elopment tools
"hen it comes to !evelopment tools for web programmingB these will consist of e!itors for the
above. %ommonly this will be an entry assist te<t e!itor for 3TM*B %++ an! ;ava+cript.
"orklight +tu!io can perform these tasks e<tremely well.
A common situation is to wish to prototype some technical test such as a ;ava+cript callB web
styling or a o6o wi!get. 'nstea! of writing a pro6ect to achieve that taskB consi!er using the
e<cellent ?;+>i!!le? web page. +eeK
httpKHH6sfi!!le.netH
At ;+>i!!le you can enter 3TM*B ;ava+cript an! %++ an! ?run it? imme!iately. 5ou can also
!eclare that you have some pre:re) ;ava+cript toolkit !epen!encies that you also wish to inclu!eK

Page 1.(

2y creating a free useri!B you can save your snippets for your own use or for sharing with others.
Document %b)ect Model + The D%M
Types of no!es foun! in the 0M
element no!es
te<t no!es
attribute no!es Anote that attribute no!es are N0T chil!ren of element no!esD
'TML
Images
"hen working with web base! programmingB it is likely you are going to make e<tensive use of
images of !ifferent formats.
A very useful website is calle! ?lorempi<el? which returns ran!om images of !ifferent sizes when
calle!. This is e<tremely useful if you nee! place hol!er images in your solution !uring
!evelopment.
Page 1./
/a$a!cript
;ava+cript is the native programming language for browsers. 't is typically e<ecute! by inclu!ing a
script tag such asK
<script type01te*t-.a6ascript1>
V your .a6ascript here %%%
<-script>
alternativelyB the ;ava+cript co!e can be written in a separate source file an! inclu!e!K
<script type01te*t-.a6ascript1 src01,y5ile%.s1>
<-script>
Javacript , Date ob-ect
The native ;ava+cript ate ob6ect hol!s !ates an! times. 't has a rich set of getters an! setters
associate! with it.
+ee alsoK
w3schools 8 ;ava+cript ate 0b6ect
o6o ates an! Times
#sing JHint
"hen entering ;ava+criptB we can use an -clipse tool calle! ?;+3int? to help us with synta< an!
best practices. 0nce installe!B it will show us notifications of where we can improve our
;ava+cript.
0ne of the warnings it gives us is that our in!enting is mi<e! spaces an! tabs. %ommonly we will
want to !isable that in!icationK
'n the ;+3int configurationB we can switch this offK
Page 139
Calling Javacript from Java
"ith the arrival of ;ava (B ;ava+cript has become a first class an! pre:supplie! a!!ition to the ;ava
environment.
To call ;ava+cript from ;avaB the following is a goo! sampleK
#cript(gieMaager ,aager 0 e" #cript(gieMaager342
#cript(gie egie 0 ,aager%get(gieBy!a,e31ashor142
egie%e6al31%%% Ja6a#cript V142
To access a ;ava package for e<ample ?co,%kolba%,ypackage?B we woul! refer to it byK
Packages%co,%kolba%,ypackage
To access a classB it is recommen! to useK
6ar MyClass 0 Ja6a%type31co,%kolba%,ypackage%MyClass142
+ee alsoK
Nashorn !ocumentation
Nashorn 7serMs @ui!e
;avaMagazine 8 ;anH>eb .911
Cascading !tyle !heets + C!!
Page 131
The .less/ language
The *ess language is a preprocessor for %++. This means that one can construct %++ much easier
than han! crafting. >or e<ampleB consi!er the following simple %++K
%classL B
color: red2
D
%classI B
color: red2
D
'f we wishe! to change our colorB we woul! have to manually change our %++ file. A simple fin!
an! replace may catch too much. 3oweverB using *essB we can specify variablesB for e<ampleK
9,yColor: red2
%classL B
color: 9,yColor2
D
%classI B
color: 9,yColor2
D
+ee alsoK
The ElessF language
.aria"les
Cariables are !efine! asK
VnameK valueU
They are reference! in %++ with ?Vname?
ixins
A class !efine! in %++ can be ?embe!!e!? or mi<e! in with another class by using the class in the
bo!y. >or e<ampleK
%,yClassL B
%%%
D
%,yclassI B
V
%,yClassL2
D
,esting
efinitions can be neste!.
3perations
A!!ition an! subtraction operations can be applie! to colors an! size units.
Timer based functions
>rom time to timeB we may have a nee! for a function to be e<ecute! either after a perio! or time or
at regular intervals. The browser environment provi!es this capability through the ?win!ow?
ob6ect. There are two functions of interest to usK
Page 13.
setIter6al3$uctioC iter6al4 : %alls a function repeate!ly every timer
perio!
set<i,eout3$uctioC iter6al4 : %alls a function once after a time perio!
The time perio!s are e<presse! in millisecon!s.
2oth these functions return a han!le which can be use! to cancel or stop the firing of events.
passing the han!le into the function ?clear<i,eout3hadle4? will cancel the previous timer.
/!%- Data representation
'n ;ava+cript source co!eB ;ava+cript ob6ects can be !eclare! using the language synta<. This
synta< is surprisingly fle<ible. "hen one wants to pass !ata from one application to anotherB an
enco!ing has been !efine! calle! ?;+0N? which is essentially enco!ing a tree of !ata into a single
string which looks like the !efinition of a ;ava+cript ob6ect in source.
J!" %ithin Javacript
J!" %ithin Java
+ee alsoK
Package 8 6ava<.6son
Dates and times %ithin J!"
;+0N !oes not provi!e any native support for !ateHtime enco!ing. As suchB a transmission of a
!ateHtime is commonly performe! enco!e! in a string.
A common format use! for this enco!ing isK
NNNN-MM-EEO<OHH:,,:ssOWO
for e<ampleK
I>LS->H-I><LS:'=:GIW
This enco!ing is known as '+0 (&91.
+ee alsoK
"ikipe!ia 8 '+0 (&91
o6o ates an! Times
Debugging in the bro.ser
+ince the ma6ority of web e<ecution occurs within the browser itselfB we nee! goo! tools an!
techni)ues for !ebugging our co!e within that environment. >ortunatelyB all the mo!ern browsers
come supplie! with !evelopment tools that assist with !ebugging.
0f the features that are availableB some are more important than others. The first ' wish to !iscuss
is the console log. Although this can be use! to log your own !iagnostics statementsB it is also
where the browser itself logs information. 'f a ;ava+cript error is encountere! !uring evaluationB it
is within the console log that we will learn this.
The secon! area that is of importance is are the ;ava+cript !ebuggers. "e can set breakpoints
within our ;ava+cript co!e such that when these breakpoints are encountere! !uring e<ecutionB the
!ebugger will kick in an! show us that we have reache! the breakpoint. 'n a!!itionB we can
Page 133
e<amine the state of variables an! conte<ts within our program.
0ne of the easiest ways to insert a breakpoint is the co!!ing of the ?!ebugger? statement. "hen
reache! an! the !ebugger is availableB !ebugging will occur.
Logging to the bro%ser console
"ithin the ;ava+cript that runs in the browserB an ob6ect calle! ?console? is available. 7sing this
ob6ectB one can log !ata to the browserMs console.
The following are availableK
unction %hrome I, irefo-
assert
5
clear
5
cout
5
debug
5
dir
5
dir*,l
5
error
5
group
5
groupCollapsed
5
group(d
5
i$o
5
log
5
pro$ile
5
pro$ile(d
5
ti,e
5
ti,e(d
5
ti,e#ta,p
5
trace
5
"ar
5
console)de"ug
This metho! is a synonym for cosole%log.
+ee alsoK
console.log
console.error
console.info
console.warn
console)error
This metho! is the same as cosole%log with the a!!ition that the stack trace of where the error
occurre! is also written.
Page 131
+ee alsoK
console.log
console.!ebug
console.info
console.warn
console)info
This metho! is a synonym for cosole%log.
+ee alsoK
console.log
console.!ebug
console.error
console.warn
console)log
This metho! logs !ata to the browser console. The input can be a list of strings or ob6ects. 'f a
string is supplie!B it may contain formatting controls that can be use! to format output. Calues
following the string in the parameters will be use! as positional replacements for the co!es. The
following format specifiers are supporte!K
ormat Specifier Description
Xs
The parameter is a string.
Xd or Xi
The parameter is an integer.
X$
The parameters is a floating point.
Xo
The parameter is e<pan!e! as a 0M no!e.
X/
The parameter is e<pan!e! as a ;ava+cript ob6ect.
Xc
The parameter is e<pan!e! as %++ styling for the output.
+ee alsoK
console.info
console.!ebug
console.error
console.warn
console)warn
This metho! is a synonym for cosole%log but shoul! be use! to log ?warning? messages.
+ee alsoK
console.log
console.info
console.error
console.!ebug
Page 13#
Do.o Programming
o6o is a completely open source ;ava+cript toolkit primarily !esigne! for web programming. 'ts
current release level is 1./ Aas of .913:11D. The source co!e is freely accessible an! has a broa!
community of support. '2M has chosen o6o as one of the key programming interfaces supporte!
by "orklight an! other '2M pro!ucts. '2M contributes heavily to the e<istence an! support of
o6o.
o6o is split into three primary packages. These are ?!o6o? which contain the primary ;ava+cript
functionsB ?!i6it? which contain the core 7' wi!gets an! finally ?!o6o<? which provi!es e<tensions
to the core functions otherwise foun! in ?!o6o? an! ?!i6it?.
+ee alsoK
eveloper"ork : 2uil! an A6a< application with the o6o Toolkit 8 .911:93:91
Do)o Information !ources
The o6o source is available for !ownloa! hereK
httpKHH!ownloa!.!o6otoolkit.orgH
't can be !ownloa!e! as a 1# Mbyte P'P file. 't is not a ba! i!ea to create an -clipse simple pro6ect
an! import the source into that pro6ect. Although we will never buil! itB it can make a very useful
reference to answer !eep )uestions if it ever comes to that.
!ff0line documentation
o6o has historically ha! poor !ocumentation for relatively new users. This is unfortunate. To
make matters worseB the !ocumentation that is available appears to be primarily able to be viewe!
on:line. The formal o6o !ocumentation is broken into two primary parts. 0ne is a Programmers
$eference which is a gui!e to using most of the o6o packages. The secon! is a !etaile! AP'
reference that is generate! from the source co!e of the o6o packages themselves.
#uilding the API 5eference !ocumentation
The AP' reference !ocumentation can be accesse! on:line on the 'nternet very easily but ' fin! there
are times when ' woul! like a local copyB especially when on a plane. The following is the recipe
for !ownloa!ing buil!ing a local copy. The recipe re)uires copies of both ?No!e.6s? an! the o6o
specific ?!api? tool for viewing. 'n a!!ition a final tool is nee!e! to parse the source co!e to
generate the !ata for ?!api?.
httpKHHwww.sitepen.comHblogH.913H91H1(Hgenerating:an!:viewing:custom:api:!ocsH
httpsKHHgithub.comHlbo!H!apiHwiki
1. ownloa! the @'T package for win!ows from here httpKHHgit:scm.comH
.. 'nstall the @'T package on "in!ows. The version use! in this e<ample was 1.(.1 but it is
e<pecte! that any version will !o.
3. ownloa! the o6o source P'P from here httpKHH!o6otoolkit.orgH!ownloa!H
1. -<tract the zip into a fol!er.
#. ownloa! the no!e app from httpKHHno!e6s.orgH
&. ownloa! the !api package. The following comman! can be use!K
git cloe --recursi6e https:--github%co,-lbod-dapi%git
Page 13&
4. %reate a ?setenv.bat? file that a!!s the @'THbin fol!er to the comman! path. 'n this e<ample
it wasK
C:\Progra, 5iles 3*=H4\?it\bi
(. A!! into the path the No!e;+ entry install !irectory. 'n this e<ample it wasK
C:\Progra, 5iles\ode.s
/. 'n the e<tracte! !api !irectory run the following comman! which will install the No!e.6s
mo!ules that are flagge! as nee!e! for the !api tool. The comman! ' use! wasK
p, -istall --productio
19. 'n the !o6o!ocs fol!er run the following comman! to !ownloa! the o6o !oc parser tool
which will be use! for parsing the source co!eK
git cloe --recursi6e https:--github%co,-"keese-.s-doc-parse%git
11. %hange into 6s:!oc:parse !irectory
1.. -!it the ?co$ig%.s? file an! fin! the entry for ?basePathM. %hange this to be the root
!irectory of the e<tracte! o6o source
13. "e are now rea!y to actually parse the source co!e to generate the !ata nee!e! for the !api
viewer. 'n my e<ampleB ' runK
parse%bat 1co$ig0%-co$ig%.s1
11. %reate the fol!er calle! ?dapi-public-data-L%U%I?. 'n my e<ampleB the o6o
source level was ?L%U%I?.
1#. %opy the files calle! ?details%.so? an! ?tree%.so? which were generate! by the
parsing to the ?dapi-public-data-L%U%I? !irectory.
1&. 'n the !api fol!erB e!it the file calle! ?co$ig%.s? an! change the entry for
?!efaultCersion? to match your !efault o6o co!eK
de$ault:ersio: OL%U%IO
V
6ersios: QOL%U%IOR
14. -!it the ?dapi-co$ig%.s? file to change the 7$* from which o6o is loa!e!. This is
the !o6o use! by the web page itself. The property to be change! is calle! ?do.oBase?.
1(. 'n the !api fol!er run the No!e.6s tool to open the application calle! ?app%.s?. This will
start the local web server listening on port 3999 Aby !efaultD. The comman! use! in this
e<ample wasK
ode app%.s
1/. 0pen a browser to ?http:--localhost:G>>>-api?.
Adding *rid6 documentation for off7line $iewing
QT2R
Page 134
Do)o 3*I De$elopment
o6o !evelopment can be performe! in 3TM* or in ;ava+cript.
0ther alternative !evelopment environments inclu!e '2MMs 'ntegration esigner an! '2MMs
"orklight +tu!io pro!ucts.
Loading Do)o
o6o !oes not automatically pull packages into the browser environment. That woul! be far too
much !ata to transmit an! woul! bloat the browser unnecessarily. 'nstea!B o6o !elegates the
choice of which packages to inclu!e to the !eveloper through the use of the reFuire34 function
call. Throughout this book we will not show the use of reFuire34 an! it is assume! that the
rea!er will remember to inclu!e the appropriate packages where necessary.
'n a web page that is going to use o6oB o6o must be bootstrappe!. An e<ample of this woul! beK
<script type01te*t-.a6ascript1 src01%%%-do.o%.s1 data-do.o-co$ig01asyc: trueC parse/+oad: true1>
<-script>
"e also have the option of loa!ing o6o from one of the public !istribution web sites such as
@oogle.
<script src01http:--a.a*%googleapis%co,-a.a*-libs-do.o-L%T%I-do.o-do.o%.s1 data-do.o-co$ig01asyc:
true1><-script>
The version of o6o currently loa!e! can be foun! with the do.o%6ersio ob6ect. This also has
a to#trig34 metho! to report the version currently in use.
An illustrative sample 3TM* file for loa!ing o6o might beK
<PE/C<NP( ht,l>
<ht,l *,ls01http:--"""%"G%org-LUUU-*ht,l1>
<head>
<title>Page <itle<-title>
<script type01te*t-.a6ascript1 src01-do.o7oot-do.o-do.o%.s1 data-do.o-co$ig01asyc: trueC
parse/+oad: true1><-script>
<lik rel01stylesheet1 hre$01-do.o7oot-do.o-resources-do.o%css1 ->
<lik rel01stylesheet1 hre$01-do.o7oot-di.it-the,es-claro-claro%css1 ->
<lik rel01stylesheet1
hre$01-do.o7oot-do.o*-grid-resources-claro?rid%css1 ->
<-head>
<body class01claro1>
<-body>
<-ht,l>
A correspon!ing ;ava+cript sample file might beK
reFuire3
Q
1do.o-ready1
RC
$uctio 3ready4 B
ready3$uctio 34 B
D42
D42
-- (d o$ $ile
"hen a page contains 3TM* an! o6oB the 3TM* is parse! by the browser an! will show in its
native form. After thisB the o6o parser can 6ump in an! the result is that the 0M will be up!ate!
to reflect the changes. This can result in a transitory perio! where ugly 3TM* that has not yet been
style! by o6o can be shown in the browser. 0ne of the easiest ways to han!le this is to surroun!
the content of the page with a <di6 id01,ai1 style016isibility: hidde1>. This
will mean the content will not be shown. "hen o6o is rea!yB it can then e<ecuteK
do,#tyle%set31,ai1C 16isibility1C 16isible142
Page 13(
to reveal the content.
&synchronous Module Definition *&MD+
o6o package loa!ing is achieve! through a technology calle! ?Asynchronous Mo!ule efinition?
or AM. This was first intro!uce! at the o6o 1.4 release.
'n or!er to use AMB the o6o loa!er must be instructe! to e<ecute in async mo!eK
<script src01%%%-do.o%.s1 data-do.o-co$ig01asyc:true1><-script>
The loa!er in this mo!e e<poses only two global functionsK
reFuire
de$ie
The reFuire function takes a list of mo!ule names to be loa!e!. -ach of these mo!ules is then
loa!e! which may in turn cause the loa! of other mo!ules. The secon! parameter of reFuire34
is a function which will be invoke! when all of the mo!ules have been loa!e!. There will be a
parameter on the function for each mo!ule name! in the list. The parameter will be mappe! to the
reference to the mo!ule loa!e!. These parameters must be supplie! in the e<act same or!er as the
correspon!ing mo!ule.
reFuire3Q1<,odule>1C 1<,odule>1C VRC $uctio3<6ar>C <6ar>C V4B%%%D42
All of the mo!ules supplie! by o6o can be accesse! this way. "e also have the ability to !efine
our own custom mo!ules.
This is performe! through the de$ie34 function. efine has the following formatK
de$ie3Q1<,odule>1C 1<,odule>1C VRC $uctio3<6ar>C <6ar>C V4
B
retur <6alue>
D42
Now let us talk about mo!ule names. A mo!ule belongs in a package an! has a name. The format
use! is the file system style of !irectory followe! by ?slash?. >or e<ample
di.it-layout-<abCotaier
,yPackage-MyModule
a-b-C
3ere is an e<ample of a mo!ule !efinitionK
The following is place! in MyModule%.s
de$ie3QRC $uctio 34 B
retur B
1test1: $uctio 34 B
cosole%log31<he dar thig "orkedP142
D
D
D42
NowB let us assume that this is place! in a fol!er calle! ?,yPackage?.
'n or!er to use this we can co!eK
reFuire3Q1,yPackage-MyModule1RC $uctio3,yModule4
B
,yModule%test34
D42
2efore the package list in the re)uire metho!B we can also provi!e a configuration ob6ect. This
ob6ect has the following propertiesK
paths
Page 13/
map
+ee alsoK
efining Mo!ules
The o6o *oa!er
sitepenK o6o >A=K 3ow !oes passing a configuration ob6ect to re)uire workJ : .911:91:..
sitepenK o6o >A=K "hat is the map config optionJ : .913:94:93
sitepenK o6o >A=K "hat is the !ifference between a packageB a path an! an aliasJ : .913:9&:.9
#$ent 'andling
The web programming mo!el of the worl! is that we set up an environment an! then wait for
e<ternal events to occur to which we respon!. Think of a web page that you may wish to work
with. 5ou enter its 7$* an! then it !isplays itself for you. 7ntil you interact with it such as
moving the mouse or clicking on a buttonB the page is usually )uite passive.
'f we are writing our own wi!getsB if we a!! the ?do.o-(6eted? package into our inheritance
chain then a wi!get instance will have an ?o34? metho! associate! with it as well as the ability to
?e,it34? events. 'n the declare34 metho! of the wi!getB a!! ?(6eted? in the array of
inherite! wi!gets where ?(6eted? is the alias for ?do.o-(6eted?.
"ithin the !o6o worl!B we set up our environment an! then register the events such thatB when they
occurB we will be notifie!.
oBlur 8 %alle! when focus is remove! from a wi!get.
oChage 8 %alle! when the !ata associate! with a wi!get has change!.
The ?e,it34? metho! has two parametersK
The name of the event to emit.
The ob6ect that is the payloa! of the event. This must be an ob6ect. A scalar will not work.
+ee alsoK
ocumentation 8 !o6oHon 8 1./
ocumentation 8 !o6oH-vente! 8 1./
-vents with o6o 8 1./
sitepen : o6o >A=K "hat properties are available to me on the event ob6ect when using !o6oHonJ : .913:91:.&
R#!T4A)a5 calls
A6a< calls are ma!e with the stan!ar! A,lHttp7eFuest ob6ect from browsers. Abbreviating
this we get G3$. +ince A6a< is a pattern of using $-+TB this story also applie! to making $-+T
calls. o6o provi!es a mo!ule calle! ?do.o-reFuest-*hr? which is commonly boun! to the
variable ?*hr?.
"hen calle!B it returns a o6o eferre! which is calle! back when the $-+T re)uest completes.
The general format of using <hr isK
*hr%get34 : make an 3TTP @-T re)uest
*hr%put34 : make an 3TTP P7T re)uest
Page 119
*hr%post34 : make an 3TTP P0+T re)uest
-ach of these metho!s takes two argumentsK
url 8 The target 7$* of the re)uest
optios 8 A ;ava+cript ob6ect which sets options on the re)uest
+ome of the more prevalent options available inclu!eK
Fuery 8 An ob6ect where the property names will be )uery parameter names an! the
property values will be the correspon!ing )uery parameter values.
hadleAs 8 3ow the return !ata shoul! be han!le!. Calues inclu!eK
?.so? 8 3an!le the response as a ;+0N enco!e! ob6ect.
?6avascript?
?<ml?
headers 8 An ob6ect where the property names will be a!!e! as 3TTP hea!ers an! the
property values as the correspon!ing value of the property hea!er.
data 8 >or P7T an! P0+TB this is the payloa! of the !ata to be transmitte!.
+ince the result from calling one of these functions is a o6o eferre!B we can use the ?the34?
metho! to han!le the response. The general form isK
the3$uctio3data4 BDC $uctio3data4 BD42
The first function is calle! when the $-+T re)uest returns goo! !ata an! the secon! function is
calle! if an error is !etecte!.
3ere is an e<ample callK
*hr%get31-rest-bp,-"le-6L-task-1 K taskId K 1-cliet#ettigs-IBM@W+(@Coach1C B
1hadleAs1: 1.so1 D4%the3$uctio3data4 BVDC $uctio3data4 BVD42
'f we wish to a!! basic authentication hea!ers to the 3TTP re)uestB we can !o that too. >or
e<ampleB the following hea!er property will achieve thisK
Authori)atio: Basic &"*hW?7pb.p6c?:uIH!lcI5tW&00
"here the 2ase&1 enco!e! te<t is ?usera,e:pass"ord?. "e can generate a base&1 enco!e!
value usingK
6ar bytes 0 QR2
6ar str 0 userid K 1:1 K pass"ord2
$or 36ar i 0 >2 i < str%legth2 KKi4
B
bytes%push3str%charCodeAt3i442
D
6ar authori)atio 0 1Basic 1 K baseHS%ecode3bytes42
The ?baseHS? package is ?do.o*-ecodig-baseHS?.
"hen sen!ing ;+0N !ata in the payloa! of a $-+T re)uestB set the hea!ers property to beK
B
OCotet-<ypeO: Oapplicatio-.so2charset08<5-=O
D2
also sen! the payloa! as a ;+0N +tring representation usingK
J#/!%strigi$y3ob.ect42
Page 111
+ee alsoK
eferre! an! asynchronous processing 8 !o6oHeferre!
A6a< with o6o
o6oToolkitK <ht@et
o6oToolkitK !o6oHre)uestH<hr A1.(D
2asic Access Authentication
sitepen : 'ntro!ucing !o6oHre)uest : .91.:9(:.1
Testing 12T Calls
There are a number of ways to test $-+T calls to a $-+T provi!er an! it is recommen!e! to !o this
before embarking on writing application co!e to ensure that the results will be as e<pecte!. My
current favorite tool is calle! ?Postman? an! can be foun!K
httpKHHwww.getpostman.comH
This is a @oogle %hrome appHplugin.
Another useful tool for $-+T client testing is ?soap7'?.
Do)o utility
do-o34base3lang
This is truly a work horse of o6o especially for ;ava+cript function calling. The first item we will
!iscuss is ?hitch?.
var func. N lang.hitchAcontextB func1DU
"hat hitch !oes is take an ob6ect that will serve as a conte<t. >or e<ample ?this?. The secon!
parameter is a reference to a function. "hat hitch returns is a new function whichB when calle!B
will invoke the passe! in function un!er the conte<t of the passe! in conte<t. 'f you un!erstan!
thatB greatOO Now you see the power of lang.hitchAD. 'f you !onMt un!erstan! thatB then it is back to
the ;ava+cript manuals for you.
A frien! to ?hitch? is its bu!!y calle! ?partial?.
var func. N lang.partialAfunc1B ?val1?B ?val.?DU
Now L if when func1AD is calle!B it N0$MA**5 e<pects a parameter calle! ?my0riginalParm1?
we can provi!e an implementation of func1AD which now acceptsK
func1 N functionAmyNewParm1B myNewParm.B my0riginalParm1D
+o what we have !one is force! the func1 to accept some a!!itional parameters beyon! the ones
that will be supplie! by its real caller.
D%M Access
+ince o6o is primarily !esigne! to run within the conte<t of a browser an! the primary means of
programming a browser environment is the manipulation of the 0MB it makes sense that a lot of
function has been a!!e! to o6o for 0M manipulation an! access.
+ee alsoK
Page 11.
o6o 0M >unctions
do-o3dom
This mo!ule provi!es some of basic 0M functions. These inclu!eK
byId3id4 8 >in! the single 0M no!e with the given i!.
isEescedat3odeC acestor4 8 $eturns true if the no!e is a !escen!ant of
ancestor.
do-o3dom0construct
toEo,3ht,l#trigC docu,et4 8 2uil!s a 0M tree from the 3TM* string an!
returns the 0M that is the root of that tree.
placeAno!eB refNo!eB positionD
before
after
replace
only
first
last
createAtagB attrsB refNo!eB positionD
e,pty3ode4 8 elete all the chil!ren of the no!e.
destroy3ode4 8 elete all the chil!ren of the no!e an! the no!e itself.
do-o35uery
The do.o-Fuery mo!ule provi!es a powerful way to search for no!es within the 0M tree. The
mo!ule itself is a single function. The synta< for the function isK
)ueryAselectorB !omTree$ootD
where
selector 8 A %++ selector pattern.
do,<ree7oot 8 An optional root in a 0M tree to start the search
The result from the )uery is a !o6o !ode+ist ob6ect representing a list of no!es that match the
selector. $ealize that the !ode+ist may be empty.
The selector is a +tring that !escribes the %++ pattern use! to !etermine which no!es to return. The
pattern is passe! to a ?pattern matching engine? that interprets the pattern an! scans the 0M tree
looking for matches. The patterns areK
Pattern Description
T Any element.
- Any element of type -.
- > An > element that is a !escen!ant of an - element.
Page 113
- R > An > element that has an imme!iate parent of type -.
-Klink
-Kvisite!
-Kactive
-Khover
-Kfocus
-WfooX An - element with an attribute calle! foo.
-WfooN?bar?X An - element with an attribute calle! foo that has a value of bar.
-WfooYN?bar?X An - element which has an attribute calle! foo that has a list of values that are space separate!
an! one of which has a value of bar.
-WhreflangZN?en?X
-KlangAfrD
-.warning
-[my'! An - element with an i! value of ?my'!?
+1B +. The results are the union of two selectors.
3ere are some sample patterns that crop upK
?> Y? 8 The imme!iate chil!ren of the root of the search tree.
No!e*ist itself is an array of 0M no!es. The No!e*ist ob6ectB in a!!ition to being a ;ava+cript
listB has a number of metho!s a!!e! to itK
atAD
concatAD
en!AD
everyAD
$or(ach3$uctio3ode44 8 -<ecute a function for each no!e in the no!e list.
in!e<0fAD
instantiateAD
last'n!e<0fAD
mapAD
onAD
sliceAD
someAD
spliceAD
+ee alsoK
ocs 8 !o6oH)uery 8 1./
sitepen : o6o >A=K oes !o6oH)uery return elements in the same or!er as they appear in the 0MJ : .913:11:91
Page 111
do-o3dom0geometry
The do.o-do,-geo,etry class provi!es accessors for working with the geometry Asizes an!
positionsD of 0M no!es. %onvention maps this package to the alias calle! ?do,?eo,?. Among
its many metho!s inclu!eK
getCotetBo*3ode4 8 $eturns an ob6ect that contains.
B
":
h:
l:
t:
D
0thers ...
Do)o Dates and Times
o6o has a number of classes for working with !ates an! times. These augment the ;ava+cript
native !ate an! time functions.
+ee alsoK
;ava+cript 8 ate ob6ect
"orking with ates in o6o 8 1./
do-o3date
This rich class contains a bunch of !ate manipulation functions.
add3dateC iter6alC a,out4 : A!!s a time value to the current !ate. +etting a
negative value subtracts time. The interval can be one of the following valuesK
?year?
?month?
?!ay?
?hour?
?minute?
?secon!?
?millisecon!?
?)uarter?
?week?
?week!ay?
di$$erece3dateLC dateIC iter6al4 : %alculate the !ifference between two
!ates in a variety of intervals. The interval can be one ofK
year
month
!ay
hour
Page 11#
minute
secon!
millisecon!
)uarter
week
week!ay
co,pare34 : %ompares two !ates an! returns 9 if they are the sameB positive if the first is
after the secon! an! negative if the first is before the secon!.
getEaysIMoth34 : The number of !ays in the month.
is+eapNear34 : $eturns true if the year is a leap year.
get<i,e)oe!a,e34 : $eturns the name of the time zone.
do-o3date3locale
This is the work horse of the o6o !ate an! time formatting.
't has the following metho!s
$or,at3dateC optios4 8 This formats a !ate to a string. The options is a rich ob6ect
containingK
datePatter 8 A formatting string !escribing how the !ate shoul! be formatte!.
+tring literals shoul! be place! insi!e single )uotes.
selector 8 3ow shoul! the !ate be formatte!. %hoices inclu!e ?date? an! ?ti,e?.
The !efault is both !ate an! time.
parseAvalueB optionsD 8 This parses a string an! returns a ate ob6ect.
is"eeken!A!ateB localeD 8 $eturns true if this is a ?weeken!?.
do-o3date3stamp
This class provi!es the conversion to an! from '+0(&91 format which is ?NNNN-MM-
EEO<OHH:,,:ss%###?.
't has the following metho!sK
$ro,I#/#trig3strig4 8 %onverts a string to a ate ob6ect.
toI#/#trig3date/b.ectC optios4 8 %onverts a ate ob6ect to a string. The
options to this metho! inclu!eK
selector 8 etermines which parts of the string to buil!. The !efault is both !ate an!
time but other options inclu!eK
!ate
time
)ulu 8 A boolean. 'f selecte!B 7T%H@MT will be use! for the timezone.
Page 11&
,illisecods 8 A boolean. 'f selecte!B millisecon!s will be inclu!e!.
+ee alsoK
ates an! times within ;+0N
Di)it Widgets
'n mo!ern 7' environmentsB we usually !o not buil! our 7' pi<el by pi<el. 'nstea!B we assume!
that there e<ist rich an! high level buil!ing blocks. These buil!ing blocks are so common to us now
that we take their e<istence for grante!. -<amples of such buil!ing blocks inclu!e buttonsB menusB
!ialogs an! select bo<es. 'n a!!itionB there are even richer buil!ing blocks such as rich te<t e!itorsB
calen!arsB charts an! many more. o6o provi!es an enviable collection of pre:!efine! buil!ing
blocks that it calls ?wi!gets?. These wi!gets areB for the most partB package! as part of the ?!i6it?
package namespace.
i6it wi!gets are re:usable components for buil!ing web pages. +ome components are supplie! by
the o6o packageB some by ven!ors an! we can also write our own wi!gets. -ach wi!get has a set
of common attributesK
id 8 The i! of the wi!get. This must be a uni)ue i! that belongs to the wi!get. No two
wi!gets on the page may have the same i!. 'f no e<plicit i! is provi!e! when the wi!get is
create!B a uni)ue i! will be generate! for it.
style 8 The 3TM* style attribute of the wi!get.
title 8 The title of the wi!get.
class 8 %++ class information to apply to the wi!get.
"i!gets can be create! either programatically or !eclaratively by 3TM* in the page.
Creating a %idget instance programatically
A wi!get can be create! programatically within ;ava+cript by creating a new instance of the ob6ect
associate! with the reference returne! when its correspon!ing package is loa!e!. This is a mouthful
so let us look at this concept closer an! by e<ample. 'magine that we wish a o6o button to be
a!!e! into our web page. 3aving familiarize! ourselves with the summary of wi!gets availableB we
see that a button is provi!e! by the wi!get calle! ?di.it-$or,-Butto?.
'n our ;ava+cript co!eB we will then loa! the mo!ule that correspon!s to that o6o function. "e
will !o this with co!e similar to the followingK
reFuire3Q1di.it-$or,-Butto1RC $uctio3Butto4 B
-- Code goes here%%%
D42
"e rea! this as ?"e re)uire the o6o mo!ule calle! Mdi.it-$or,-ButtoM so please loa! it.
"hen loa!e!B you will return me a reference to it as the first parameter of a function. That function
will store that reference in a variable that ' choose to call M2uttonM?.
There is nothing magic in the variable being calle! M2uttonM but what else shoul! we call it that
actually makes better senseJ %alling it MMenuM woul! be the height of ma!ness as what it actually is
is a reference to a template that creates 2uttons.
Now that we have a reference to the template that can create buttonsB we can create an instance of a
button with co!e such asK
6ar ,yButto 0 e" Butto342
3oorayOO L well L not )uite so fast. Although the variable ?,yButto? now contains a concrete
Page 114
instance of a buttonB nothing at all will be shown in the web page. "e havenMt tol! the button where
on the page it shoul! appear. This is a core notion. %reating a wi!get !oes not cause it to appear.
"e must also tell the wi!get where on the page it shoul! be locate!. To !o thisB we must associate
the wi!get with a 0M no!e. Think of the 0M no!e as being an anchor on the page that
!escribes where the wi!get shoul! appear.
"e have a couple of ways to associate a wi!get with the !esire! target no!e. The first is to pass the
no!e as a parameter when the wi!get is constructe!. Most wi!gets allows a no!e to be supplie! at
this time. 't is common that this is the secon! parameter on the wi!getMs constructor. >or e<ampleK
6ar ,yButto 0 e" Butto3Blabel: 1Press Me1DC 1,y!ode142
The target no!e can be supplie! either as the ?i!? of the target no!e or as a reference to a no!e
ob6ect.
'f we !onMt want to supply the no!e when the wi!get is create!B we can usually call a metho! that
will be foun! on the wi!get calle! ?placeAt34? which takes as a parameter the no!e against
which the wi!get shoul! be place!.
'n the e<ample aboveB we also snuck in a secon! new concept. -very wi!get we will work with has
properties associate! with it. These properties control how it looks an! behaves. "hen a wi!get is
constructe!B the first parameter on its constructor is a ;ava+cript ob6ect that has properties that will
be use! to set the correspon!ing name! properties of the wi!get. 'n the e<ample aboveB the 2utton
wi!get has a property calle! ?label? which !escribes the label shown on the button.
di-it3registry 0 Di-it and byId
"hen a i6it wi!get is create!B it can be supplie! an ?id? attribute than can then be use! to fin! the
reference to the wi!get by its i! value using registry%byId31<id>14. Note that the i! value
has to be uni)ue on the page. 'f no i! value ' supplie!B o6o will generate a uni)ue i!.
'f we !onMt know the i! valueB we can still retrieve a reference to the wi!get if we know the 0M
no!e against which it is attache!. A secon! function calle! ?registry%by!ode3<ode>4?
can be use! which will return us a reference to the wi!get if all we know is a 0M no!e.
Another e<tremely useful capability of the registry is to create uni)ue '!s. >or e<ampleK
registry%get8iFueId3this%declaredClass4
Di-its and events
"e can connect a i6it wi!get to its events. >or e<ampleK
coect%coect3,yButtoC 1oClick1C thisC ,y5uctio42
howeverB this techni)ue is being !eprecate!. The newer technology is to use the do.o-o
techni)ue.
+ee alsoK
!o6oHon 8 1.4
-vents with o6o 8 1.4
+itepen : !o6oHonK New -vent 3an!ling +ystem for o6o 8 .911:9(:93
Do-o style sheets and themes
o6o provi!es a number of themes an! styles that are use! to provi!e a !efault look an! feel to a
Page 11(
page.
claro
tun!ra
noir
soria
<style type01te*t-css1>
9i,port 1http:--%%%-do.o-resources-do.o%css12
9i,port 1http:--%%%-di.it-the,es-soria-soria%css12
<-style>
6orm Widgets
All i6it wi!gets inherit from their base calle! di.it%$or,%@5or,Widget. 5ou can think of
this as the ;ava 'nterface against which all other form wi!gets are !erive! meaning that they have a
consistent set of semantics.
There are some common properties associate! with each >orm wi!get. These areK
alt
base%lass
!isable!
name
tab'n!e<
value
+ome core metho!sK
setisable!AD
is>ocusableAD
focusAD
on%hangeAD
setCalueAD
getCalueAD
un!oAD
di'it8form89orm
o6o provi!es an e)uivalent for the 3TM* <$or,> element that provi!es a set of functions for
sen!ing an! receiving form !ata. 3oweverB one of the most interesting aspects of this wi!get is that
it can control vali!ation of other containe! form wi!gets.
"hen any other form wi!gets containe! within the form flip the state of the form as a whole from
vali! to invali! or visa versaB an event is triggere!. This event can be monitore! withK
"atch31state1C $uctio3propertyC old:alueC e":alue4 B
Page 11/
--- code here
D42
-<perience shows that the values can beK
?ico,plete? 8 Missing re)uire! fiel! not entere!.
?error? 8 ata in one or more fiel!s is invali!.
?? 8 This in!icates that the form is vali!.
't is important the form wi!gets startup34 metho! is e<ecute! only after all the chil!ren wi!gets
containe! within the form have been initialize!.
The property calle! ?6alue? will return an ob6ect with the current values of the fiel!s in the form.
$emember that it is the ?a,e? property of a form element that is the i!entity of the fiel! an! not
the ?id? property.
eg.
6ar ,y:alues 0 ,y5or,%get316alue142
+ee alsoK
o6o ocs 8 !i6itHformH>orm 8 1./
di'it8form8#utton
The o6o >orm wi!get calle! Butto !isplays a button on the page. A button can be create! in
co!e with the followingK
6ar ,yButto 0 e" Butto3B
label: 1clickMe1C
oClick: $uctio34 B
%%%
D
DC 1<ht,l IE>142
'ts basic !eclarative markup looks likeK
<butto data-do.o-type01di.it-$or,-Butto1 type01butto1>Butto<-butto>
"hen shownB it looks likeK
"hen the button is presse!B an oClick event is generate!. This can cause the e<ecution of a
callback functionK
<script>
$uctio callBackL34
B
cosole%debug31Callback called142
D
<-script>
<butto do.o<ype01di.it%$or,%Butto1
oClick01callBackL1
label01Butto1><-butto>
A button can also show an icon with it. The icon is specifie! by naming a %++ class in the
icoClass parameter. >or e<ampleK
<butto do.o<ype01di.it%$or,%butto1 icoClass01,yIco1><-butto>
where there is a class !efinition that looks likeK
%,yIco B
backgroud-i,age:url31url to i,age142
"idth:I'p*2
height:I'p*2
Page 1#9
te*t-alig: ceter2
backgroud-repeat: o-repeat2
D
3ere is an e<ample. 'n the <head> of the 3TM* pageB we !efine a new +tyleK
<style type01te*t-css1>
%,yIco
B
backgroud-i,age:url31i,ages-$older-ope%pg142
"idth:GIp*2
height:GIp*2
te*t-alig: ceter2
backgroud-repeat: o-repeat2
D
<-style>
To show the buttonB we co!eK
<butto do.o<ype01di.it%$or,%Butto1 label01Bro"se1 icoClass01,yIco1><-butto>
The result looks likeK
'f we wish to hi!e the labelB we can a!! the propertyK
sho"+abel: $alse
A button can be programatically a!!e! to a page with the followingK
6ar re$reshButto 0 e" di.it%$or,%Butto3Blabel: 17e$resh1C oClick: getEataD42
do.o%byId31,ytab14%appedChild3re$reshButto%do,!ode42
The wi!th of a button can be change! but it is not as simple as e<pecte!. The following recipe will
workK
do,#tyle%set3Fuery31%di.itButto!ode1C butto%do,!ode4Q>RC 1"idth1C 1L>>p*142
Another way to set the wi!th of a button is to !efine the following %++K
%"ideButto %di.itButto!ode B
"idth: L>>p*2
D
an! then a!! class01"ideButto1 to the 2utton.
'f we wish a tooltip to be shown on the buttonB set its ?title? attribute to be the te<t of the
tooltip.
The styling of a button can be overri!!en by setting the ?baseClass? attribute.
A boolean property calle! disabled can be set to true which will !isable button presses an!
change its appearance to reflect that it is !isable!.
di'it8form85adio#utton
A ra!io button is a button that can have an on or an off state. The state is available from the ra!io
buttonMs ?checked? attribute. 'n a!!ition to having a stateB each button also has a ?value? foun!
from the ?6alue? property. The buttons are usually groupe! together such that when one is
switche! onB the other is switche! off. To group ra!io buttons togetherB have them be part of the
same ?a,e? !efinition.
<iput type01radio1
data-do.o-type01di.it-$or,-7adioButto1
a,e01drik1
id01radio/e1
checked
6alue01tea1-><label $or01radio/e1><ea<-label>
Page 1#1
<br ->
<iput type01radio1
data-do.o-type01di.it-$or,-7adioButto1
a,e01drik1
id01radio<"o1
6alue01co$$ee1-><label $or01radio<"o1>Co$$ee<-label>
2e careful when using the get316alue14 metho!. The value of the ra!io button will 0N*5 be
returne! if it is checke! otherwise ?$alse? is returne!. 'f we want to get the value irrespective of
its checke! stateB get the ?6alue? property !irectly.
7sing ra!io buttons in con6unction with di.it-$or,-5or, can make their han!ling much
easier. "e can !efine a ?a,e? property on all the buttons an! use the formMs get316alue14 to
get an ob6ect back that will have the ?a,e? property set to the selecte! value.
"hen programatically creating a $a!io 2uttonB one must also create a ?label?.
6ar label 0 do,Costruct%create31label1C B
ierH<M+: 1My +abel1C
$or: ,y7adioButto%id
D42
Among the properties for $a!io2utton areK
name
value
Take care when asking a $a!io2utton for its ?value?. 'f we use its getA?value?D metho!B it will
return true or false. True if it is checke! an! false otherwise. 'f we want the value of the ?value?
propertyB we shoul! retrieve it via the normal ;ava+cript property accessor such asK
my$a!io2utton.value
+ee alsoK
!i6itHformH>orm
o6o ocs 8 !i6itHformH$a!io2utton 8 1./
sitepen : o6o >A=K 3ow !o you set a !efault selecte! $a!io2uttonJ : .911:9.:1/
i6it %heckbo<es 8 1./
di'it8from8Com"o#ox
The combo bo< is basically a cross between a te<t input fiel! an! a select !rop !own. The user can
enter any te<t they wish or they can select from the pull:!own an e<isting entry. 'f the user starts to
enter te<t which is a prefi< of one of the pull:!ownsB the set of prefi<e! pull:!owns is shown.
The entries for the pull:!own can be set from a o6o store or using 3TM* !eclaration using
<optio> elements.
The following are some of the more important attributes of the wi!getK
6alue 8 The value entere! or selecte! by the user.
store 8 A !o6o store that sets the options in the combo bo<.
searchAttr 8 The name of the property of the entries in the store that will be use! for the
value for the options.
$orce:alid/ptio 8 'f set to trueB the entere! !ata must match one of the available
items to be selecte!. 'f set to falseB the user can enter any value even if it !oesnMt match one
of the pre:!efine! possible values.
Page 1#.
autoCo,plete 8 'f set to trueB characters entere! are use! to match with the pre:!efine!
possible values as soon as possible.
hasEo"Arro" 8 "hether or not a !own arrow is shown besi!e the combo bo< to show
selectable values. The !efault is true.
<select do.o<ype01di.it-$or,-Co,boBo*1
a,e01select1
$orce:alid/ptio01$alse1
autoco,plete01true1>
<optio 6alue01gold1>?old<-optio>
<optio 6alue01sil6er1>#il6er<-optio>
<optio 6alue01bro)e1>Bro)e<-optio>
<-select>
do'ox8form8Uploader
The purpose of this wi!get is to allow the user to select one or more files an! have them uploa!e!
to a back:en! server using the 3TTP file uploa! technology.
Amongst the interesting properties of this wi!get areK
url 8 The 7$* for the en!point of the server to which the fileMs content shoul! be sent.
label 8 The label on the button use! to shown the file selection !ialog.
uploa!0n+elect 8 etermine! whether or not the file will be uploa!e! imme!iately after
selection.
+ee alsoK
The New o6o 3TM*# Multi:>ile 7ploa!er
di'it8form8!ateText#ox
This wi!get shows a !ate te<t bo< into which a !ate can be entere!. A click on the associate! !rop
!own button shows a calen!ar.
Page 1#3
The !ate is accesse! via the ?6alue? property an! is a ;ava+cript ?Eate? ob6ect with no time
component of the !ate set. 'f the !ate is remove! from the entry bo<B ull is returne!.
+ee alsoK
o6o ocs 8 !i6itHformHateTe<t2o< 8 1./
"orking with ates in o6o 8 1./
di'it8form8TimeText#ox
This wi!get shows a time bo< from which a value can be chosen. The ?value? property will contain
a ;ava+cript !ate ob6ect from which the !ate portion shoul! be ignore! L only the time is relevant.
di'it8form8.alidation Text #ox
This wi!get is a te<t input area that also provi!es vali!ation of its content.
0ptions inclu!eK
pro,ptMessage 8 The message te<t to be !isplaye! besi!e the input fiel! when input is
being entere!.
i6alidMessage 8 The message shown in the vali!ation fails. $easons that a vali!ation
may fail inclu!eK
No !ata entere! for a re)uire! fiel!
ata entere! !oes not match the regular e<pression vali!ation
lo"ercase 8 -nsures that all characters entere! are transforme! into lowercase.
propercase 8 -nsures capitalization of first letter an! lower case letters from then on.
reFuired 8 >lags the fiel! as being re)uire! an! hence !ata must be entere! into it.
tri, 8 $emove any lea!ing or trailing whitespace from the entere! !ata.
reg(*p 8 A regular e<pression applie! to the entere! !ata. 'f the !ata !oes not match that
regular e<pressionB the invali!Message is shown.
,a*+egth 8 %onstrains the entere! !ata to be no more than this number of characters.
!o6o.re)uireA?!i6it.form.Cali!ationTe<t2o<?DU
Page 1#1
Metho!sK
!isplayMessageA+tringD 8 !isplays the message associate! with the te<t bo<. 'f no parameter is
supplie!B any e<isting message that is currently being shown is remove!.
<iput do.o<ype01di.it%$or,%:alidatio<e*tBo*1
id01user!a,e1
6alue011
i6alidMessage01Proper 6alue is reFuired1
pro,ptMessage01(ter user a,e1
lo"ercase01true1
reFuired01true1
reg(*p01Qa-)RY1
,a*+egth01'1
tri,01true1 ->
Te7t 2ditors
A common !esire in a web 7' is to be able to enter te<t !ata. This may be a simple single line
entry such as a passwor! or a name or it may be a more a!vance! entry that can span multiple lines
an! inclu!e rich te<t e!iting.
di'it8form8Textarea
The di.it-$or,-<e*tarea wi!get provi!es a te<t bo< into which multiple lines of !ata may
be entere!. 't !oesnMt e<plicit state its height. 'nstea! it can e<pan! vertically to inclu!e as many
rows as nee!e!. 't is common to set its ?wi!th style? to be the wi!th that we woul! want it to be.
"hen !eclaring it in 3TM*B use the <te*tarea> 3TM* elements as its container as this will
preserve newline characters on input.
+ee alsoK
!i6itHformH+impleTe<tarea
!i6itHformHTe<t2o<
di'it8form8Text#ox
The Te<t2o< wi!get provi!es a single line te<t input area. The wi!get can be foun! in
di.it%$or,%<e*tBo*. The value of the te<t bo< can be foun! through the value attributeK
bo*%get316alue14 to get an! bo*%set316alue1C 1e"6alue14 to set.
+ome of the more interesting properties of <e*tBo* inclu!eK
read/ly 8 A boolean. 'f set to trueB the te<t bo< is rea! only an! !oes not respon! to
user input. 3oweverB it !oes not look ?greye!?.
disabled 8 A boolean. 'f set to trueB the te<t bo< is rea! only an! also has a visual
appearance of not allowing user input.
+ee alsoK
!i6itHformHTe<tarea
!i6itHformH+impleTe<tarea
di'it8form8SimpleTextarea
This wi!get provi!es a fi<e! size te<t area Aunlike Te<tarea which resizesD.
Page 1##
Amongst the properties of this wi!get areK
ro"s 8 the number of rows to show
cols 8 the number of columns to show
+ee alsoK
!i6itHformHTe<tarea
!i6itHformHTe<t2o<
di'it8form8,um"erText#ox
This wi!get provi!es numeric entry with checking.
The constraints Aprovi!e! by the ?costraits? ob6ect propertyD inclu!eK
,i 8 The minimum allowable value
,a* 8 The ma<imum allowable value
pattern
places 8 number of !ecimal places
+ee alsoK
o6o ocs 8 !i6itHformHNumberTe<t2o< 8 1./
ocs : ParsingB >ormattingB an! Cali!atingK ates an! Numbers
di'it8form8Currenc1Text#ox
This wi!get provi!es a specialization of !u,ber<e*tBo* for showing currency values. To useB
set the currency property to be the co!e of the currency to !isplay. >or e<ample M8#EM for the
7nite! +tates.
di'it8Editor
The di.it-(ditor provi!es a very sophisticate! e!itor that has many of the features associate!
with a full wor! processor.
Page 1#&
Lists
di'it8form8ultiSelect
The Multi#elect wi!get allows the user to select from a set of available options shown on a list.
't can be use! to select a single item or multiple items. 't is basically a wrapper aroun! the 3TM*
<select> element.
To programatically a!! an entry into the wi!getB use the followingK
do,Costruct%create31optio1C B
ierH<M+: 1<label>1C
6alue: 1<6alue>1
DCselectWidget%do,!ode42
To set the vertical size of the wi!get as a number of elements to showB set the ?si)e? attribute.
To provi!e single selection set the ?,ultiple? attribute to false.
An event on the wi!get calle! ?chage? is invoke! when the selection changes. The !ata passe!
into the event is an array of the values Athe 6alue property of the optio elementD of the selecte!
itemAsD. -ven is single select is in effectB an array is still passe! but will 6ust contain the single
selecte! item.
'f we wish to !elete all the entries in the listB the following will workK
Fuery31optio1C ,ulti#electWidget%do,!ode4%orpha31Y142
<select do.o<ype01di.it-$or,-Multi#elect1 id01Multi#elect1 style01"idth: L>>p*1>
<optio 6alue01red1>7ed<-optio>
<optio 6alue01gree1>?ree<-optio>
<optio 6alue01blue1>Blue<-optio>
<-select>
di'it8form8Select
The select wi!get shows a simple selection pull:!own.
The AM package for this wi!get is ?di.it-$or,-#elect? an! is commonly boun! to
?+elect?.
0ptions can be programatically a!!e! via the ?add/ptio34? metho!. This can take a single
option ob6ect or an array of option ob6ects. An option ob6ect is a ;ava+cript ob6ect with two
propertiesK
label 8 The label to show in the list. This shoul! be a string.
6alue 8 The value of the entry in the list. This shoul! also be a string.
>rom a !eclarative perspectiveB we can use the following 3TM*K
<select a,e01selectL1 data-do.o-type01di.it-$or,-#elect1>
<optio 6alue01<!1><eessee<-optio>
<optio 6alue01:A1 selected01selected1>:irgiia<-optio>
<optio 6alue01WA1>Washigto<-optio>
<optio 6alue015+1>5lorida<-optio>
Page 1#4
<optio 6alue01CA1>Cali$oria<-optio>
<-select>
2y !efaultB the +elect changes its wi!th to accommo!ate the selecte! item. This is rather unusual
AopinionD as the wi!get seems to move about. "e can set a fi<e! wi!th using the ?wi!th? %++ style
property.
Among its more important properties areK
disabled 8 A boolean. 'f set to trueB then the control is !isable!. 'f !isable!B it has a
!isable! appearance.
optios 8 An array of the options for the select.
labelAttr 8 'f the select options are provi!e! by a storeB this property is use! to set the
fiel! within an item in the store to be use! as an entry.
Among its more important metho!s areK
re,o6e/ptio34 : $emoves an option. The parameter can be a string or an or!inal
number. 't can also be a list of e<isting options. This becomes especially useful if we
combine this metho! with get/ptios34 which returns a list of all the e<isting options.
>or e<ample.
,y#elect%re,o6e/ptio3,y#elect%get/ptios3442
will remove all the e<isting options.
+ee alsoK
!i6it.form.+elect 8 1./
!i6it.form.Multi+elect 8 1./
@etting +elective with i6it 8 1./
A!vance! i6it +elects using +tores 8 1./
8isual 'anes
Cisuals panes are visible container of !ata.
+ee alsoK
di.it-layout-CotetPae
di.it-<itlePae
di.it-5ieldset
di'it8TitlePane
The di.it-<itlePae wi!get shows a panel with a title at the top. The pane can be collapse!.
The pane has a title an! content.
The key properties of this wi!get areK
title 8 The title to be shown in the hea!ing of the pane.
cotet 8 A 0M no!e to be containe! within title pane.
ope 8 A boolean which says whether or not the title pane shoul! be shown initial open or
Page 1#(
not. The !efault is true meaning that it shoul! be initially shown open.
di'it89ieldset
This wi!get places content within a fiel!set that may be collapse!.
Dialogs
A !ialog is a pop:up win!ow showing a!!itional content. This win!ow can usually be move!
aroun! within the primary parent win!ow. The win!ow can also be close!. %ommonlyB the
appearance of the !ialog means that it has to be close! before interaction with other content may be
achieve!. This is what is known as a ?mo!al? !ialog.
di'it8!ialog
The !ialog mo!ule is containe! within ?di.it-Eialog? which is commonly mappe! to the
variable calle! ?Eialog?
%onsi!er the following 3TM*K
<di6 id01dlgL1 style01display: oe1>
V /ther cotet goes here V
<-di6>
An! the following scriptK
6ar dlg 0 e" Eialog3B
title: 1HI1
DC 1dlgL142
dlg%sho"342
'n a !eclarative style we can co!eK
<di6 id01dialog/e1 data-do.o-type01di.it-Eialog1 title01My Eialog <itle1>
V /ther cotet goes here V
<-di6>
To show a !ialogB use its sho"34 metho!. To hi!e the !ialogB use its hide34 metho!.
"hen shown or hi!!enB the o#ho"34 an! oHide34 events are fire! these events are targete!
to the ialog.
The di.it-Eialog is a mo!al !ialog which means that it locks out interaction with the base
page until !ispose!. An interesting Aan! so far workingD techni)ue to make it non:mo!al is to a!!
the following %++ to the pageK
%oModal@uderlay B
display:oe
D
an! a!! the following to the ialog constructor parametersK
1class1: 1oModal1
Although this works wellB it is unknown why this works an! ' !onMt like mysteries.
+ome of the more important attributes of this wi!get inclu!eK
title 8 The title of the !ialog.
closeable 8 +houl! an W<X close button be shown on the !ialogJ
>rom an event perspectiveK
oHide34 8 %alle! when the !ialog is hi!!en.
Page 1#/
+ee alsoK
o6o !ocs 8 !i6it.!ialog 8 1.19
di'it8Tooltip!ialog
Cery similar to the di.it-EialogB the di.it-<ooltipEialog also shows a mo!al !ialog.
3oweverB unlike the other oneB di.it-<ooltipEialog has two primary !ifferencesK
%licking outsi!e the !ialog !isposes of it.
The !ialog is positione! showing a relationship to another wi!get.
The <ooltipEialog can be shown from a EropEo"Butto or through the use of the
di.it-popup mechanism. "hen using popupB the <ooltipEialog can appear 6ust about
anywhere.
't is the parent that is responsible for showing an! hi!ing the !ialog. %onsi!er using focusHblur to
know when the !ialog shoul! be !ispose!.
3ere is an e<ample of using the <ooltipEialog to launch on a no!e clickK
<di6 id01lauch1>Click here<-di6>
<di6 data-do.o-type01di.it-<ooltipEialog1 style01display: oe21 id01ttd1>
<label $or01a,eI1 style01display: ilie-block2 "idth: 'e,21>!a,e:<-label>
<iput data-do.o-type01di.it-$or,-<e*tBo*1 id01a,eI1 a,e01a,eI1 ->
<br ->
<label $or01hobbyI1 style01display: ilie-block2 "idth: 'e,21>Hobby:<-label>
<iput data-do.o-type01di.it-$or,-<e*tBo*1 id01hobbyI1 a,e01hobbyI1 ->
<br ->
<butto data-do.o-type01di.it-$or,-Butto1 type01sub,it1>#a6e<-butto>
<-di6>
reFuire3Q1do.o-ready1C 1do.o-parser1C 1di.it-<ooltipEialog1C 1di.it-$or,-<e*tBo*1C
1di.it-$or,-Butto1C 1di.it-popup1C 1do.o-Fuery1C 1do.o-o1C 1di.it-registry1RC
$uctio 3readyC parserC <ooltipEialogC <e*tBo*C ButtoC popupC FueryC oC registry4 B
ready3$uctio 34 B
6ar ttd 0 registry%byId31ttd142
6ar ode 0 Fuery31Zlauch14Q>R2
o3odeC 1click1C $uctio 34 B
cosole%log31ClickedP142
popup%ope3B
popup: ttdC
aroud: ode
D42
ttd%$ocus342
D42
ttd%o31blur1C $uctio 34 B
popup%close3ttd42
D42
D42
D42
"hen !efining a Tooltipialog in markupB make sure that the %++ ?!isplay? is set to ?none? to hi!e
it until nee!e!. Also consi!er setting its ?outline? to also be ?none? to hi!e its focus in!icator.
+ee alsoK
!i6itHpopup
Page 1&9
Menus
o6o has e<tensive menu support. 't provi!es both menu bar an! conte<t menus. *et us look first
at menu bars.
The co!e for the above looks as followsK
reFuire3Q1di.it-MeuBar1C 1di.it-PopupMeuBarIte,1C 1di.it-Meu1C 1di.it-MeuIte,1RC
$uctio3MeuBarC PopupMeuBarIte,C MeuC MeuIte,4
B
6ar pMeuBar 0 e" MeuBar3BD42
6ar p#ubMeuL 0 e" Meu3BD42
p#ubMeuL%addChild3e" MeuIte,3Blabel: 1I$o L1D442
p#ubMeuL%addChild3e" MeuIte,3Blabel: 1I$o I1D442
pMeuBar%addChild3e" PopupMeuBarIte,3Blabel: 1i$o1C popup: p#ubMeuLD442
6ar p#ubMeuI 0 e" Meu3BD42
p#ubMeuI%addChild3e" MeuIte,3Blabel: 1#tatus L1D442
p#ubMeuI%addChild3e" MeuIte,3Blabel: 1#tatus I1D442
pMeuBar%addChild3e" PopupMeuBarIte,3Blabel: 1#tatus1C popup: p#ubMeuID442
pMeuBar%placeAt31"rapper142
pMeuBar%startup342
D
442
The high level philosophy is to create a MeuBar ob6ect to represent the menu bar. Ne<t we create
as many Meu ob6ects as we wish to appear within the MeuBar. >or each Menu item we wish to
appearB we create an! a!! chil! MeuIte, ob6ects which represent the in!ivi!ual selectable parts.
-ach of the Menu items is a!!e! to the MeuBar. The MeuIte, has an oClick event that is
calle! when the menu item is selecte!.
A Menu can also be use! in the screen that is always visible. >or e<ampleK
A snippet of this can be achieve! withK
reFuire3Q1di.it-Meu1C 1di.it-MeuIte,1RC
$uctio3MeuC MeuIte,4
B
6ar pMyMeu 0 e" Meu3BD42
pMyMeu%addChild3e" MeuIte,3Blabel: 1I$o L1D442
pMyMeu%addChild3e" MeuIte,3Blabel: 1I$o I1D442
pMyMeu%placeAt31"rapperI142
D
Page 1&1
42
A menu item can be !isable! using its ?disabled? property. +etting that to true !isables the
menu item.
'mages can be a!!e! to menu items using the ?icoClass? attribute Asee also 2uttonD. This
property names a %++ class that !eclares an icon. >or e<ampleK
%Caledar@#u,,ary B
backgroud-i,age:url3te*tLH*LH%pg42
"idth:LHp*2
height:LHp*2
te*t-alig: ceter2
backgroud-repeat: o-repeat2
D
i6it provi!es a utility wi!get calle! popup that can be use! to pop:up a menu. The package is
?di.it-popup? which is commonly boun! to ?popup?.
To pop:up a menuB e<ecute
popup%ope3B<%%% par,s %%%>D42
+ee alsoK
gri!<Hmo!ulesHMenu
%reate a %onte<t Menu with o6o an! i6it
i6itHMenu 8 1./
i6it Menus 8 1./
o6o buil! sample 8 1./
di'it8enu
This wi!get represents a whole menu. The items in the menu are instances of the
di.it-MeuIte, class which are then a!!e! to the menu through the metho! calle!
addChild3,euIte,4which can be foun! on the Menu ob6ect.
'magine that we want to a!! a conte<t menu to a wi!get instance reference! by the variable calle!
?,yWidget?. "e can co!eK
6ar ,eu 0 e" Meu3B
target!odeIds: Q,yWidget%do,!odeR
D42
now when a right click occurs on my"i!getB the conte<t menu will be shown.
Among the properties for this wi!get areK
activate!
active
conte<tMenu>or"in!ow
currentTarget
left%lickTo0pen
ownerocument
targetNo!e'!s
>unctions
Page 1&.
a!!%hil!AD
bin!omNo!eAD
+ee alsoK
!i6itHMenu'tem
!i6itHpopup
di'it8enu#ar
di'it8enuItem
This wi!get represents an entry in a menu. Among its properties areK
label 8 The te<t to show within the menu item.
icoClass 8 The %++ class to use to show an image in the menu item.
The wi!get also publishes a number of useful events
?click? 8 %alle! when the menu item is clicke!.
di'it8enuSeparator
This wi!get can be use! as a chil! of the di.it-Meu or di.it-EropEo"Meu to a!! a
horizontal separator. 't has no semantics other than to provi!e a visual placehol!er.
+ee alsoK
!i6itHMenu
!i6itHropownMenu
di'it8!rop!ownenu
di'it8popup
The popup wi!get is a popup manager that will !ynamically show or hi!e another wi!get. This is
most commonly use! to show or hi!e a menu. "hen being use! to show a menuB a very goo!
practice is to give the menu ?focus? once it has been shown. 'n a!!itionB if the menu loses focus
Ai.e. a ?blur? eventDB that shoul! be an in!ication for the menu to !isappear.
The popup ob6ect is a singleton. 5ou !onMt create new instances of it. 't has two important metho!s
on it. 0ne is calle! ?ope34? which shows the !esire! wi!get while the other is calle!
?close34? which hi!es the !esire! wi!get.
The primary parameters of interest to the popup openAD function areK
*By 8 The < an! y coor!inates of where the popup shoul! appear
paret 8 The wi!get that is the parent of the popup. 't is this wi!get that is opening the
popup.
Page 1&3
popup 8 The wi!get to actually popup to the user AegB an instance of MenuD
aroud 8 The !om no!e that will be the host of the popup
oriet 8 A list of locations one of which will be chosen to show where the popup menu
will be shown. The options areK
before
after
before:centere!
after:centere!
above:centere!
above
above:alt
below:centere!
below
below:alt
+ee alsoK
!i6itHTooltipialog
ialogs S Tooltips 8 1./
di'it8Popupenu#arItem
do'ox8widget89ishe1eList
The wi!get calle! do.o*-"idget-5isheye+ist provi!es a menu that is similar to that foun!
in the Mac 0+ where an icon increases in size as you move your mouse towar!s an! over it.
+ome of the more important properties inclu!eK
ite,Width 8 The wi!th in pi<els of an item at rest. The !efault is 19.
ite,Height 8 The height in pi<els of an item at rest. The !efault is 19.
ite,Ma*Width 8 The ma<imum wi!th in pi<els of an enlarge! item. The !efault is 1#9.
ite,Ma*Height 8 The ma<imum height in pi<els of an enlarge! item. The !efault is
1#9.
orietatio 8 escribes whether the list is shown horizontally or vertically. The
!efault is ?horizontal?.
Page 1&1
hori)otal 8 +how the list horizontally.
6ertical 8 +how the list vertically.
e$$ect8its 8 The number of pi<els to scale per mouse move increment. The !efault is
..
ite,Paddig 8 The number of pi<els between each item at rest. The !efault is 19.
attach(dge 8 "hich e!ge shoul! be ?attache!? Ai.e. be the base of the imageD. The
!efault is ?center?.
top 8 The top e!ge of the wi!get is fi<e!.
botto, 8 The bottom e!ge of the wi!get is fi<e!.
le$t 8 The left e!ge of the wi!get is fi<e!.
right 8 The right e!ge of the wi!get is fi<e!.
center 8 The center of the icon is fi<e!.
label(dge 8 "here shoul! the label of the item be shown. The !efault is ?center?.
top 8 Above the image.
botto, 8 2elow the image.
le$t 8 *eft of the image.
right 8 $ight of the image.
coser6ati6e<rigger 8 +houl! the icon scale as the mouse moves towar!s the icons
or only when the mouse is over an icon. A value of ?true? means only when over an icon.
-ach item within the do.o*-"idget-5isheye+ist shoul! be an instance of
do.o*-"idget-5isheye+istIte,. This wi!get !escribes the nature of the item to be
shown. +ome of its more important properties inclu!eK
ico#rc 8 The 7$* for the image to be !isplaye!.
label 8 The label to be shown when the icon is over the image.
o 8 The o6o on event han!ler use! to !etect when the item is selecte!.
ProgramaticallyB >isheye*ist'tems are a!!e! to the >isheye*ist via its a!!%hil!AD metho!.
-<perience seems to show that before a!!ing the >isheye*ist'tem to the >isheye*istB a property on
it calle! ?parent? nee!s to be set to the >isheye*ist wi!get that contains it. This appears to be
necessary when programatically creating the >isheye*ist but not when using the 3TM* !eclaration
format.
A!!itional %++ is re)uire! for the >isheye*ist to function. This %++ can be foun! within the o6o
!istribution atK
<7oot>-do.o*-"idget-5isheye+ist-5isheye+ist%css
'f one wishes the >ish-ye*ist to be centere!B consi!er a!!ing the styleK
%do.o*5isheye+istBar B
Page 1&#
,argi: > auto2
te*t-alig: ceter2
D
Layouts
o6o provi!es some powerful layout capabilities. 'n a!!itionB we can always use the classic 3TM*
layouts such as tables.
QtableR
QtrR
Qt!R
Qt!R
QHtrR
QHtableR
+ee alsoK
*ayout with i6it 8 1./
PA%,T 8 *ayout in o6oK Part 1 : .99/:94
di'it8la1out8ContentPane
The CotetPae is a container for other wi!gets an! markup.
The function calle! ?addChild34? can be use! to a!! another i6it into the CotetPae.
PropertiesK
href
preloa!
refresh0n+how
loa!ingMessage
errorMessage
is*oa!e!
+ee alsoK
ocs 8 !i6itHlayoutH%ontentPane 8 1./
di'it8la1out8AccordionContainer
The Accor!ion %ontainer contains a series of panels where only one is shown at a time. The titles
of the other panels are also shown an! clicking one of these makes the selecte! panel shown while
hi!ing the previously selecte! panel.
Page 1&&
?AccordioCotaier? is part of di.it%layout. The ?panels? in the accor!ion are a!!e!
via the ?addChild34? metho!. TypicallyB the chil! is a CotetPae which can supply a title
as well as content.
,yAccordio%addChild3e" CotetPae3B
title: 1My <itle1C
cotet: 1My cotet1
D442
+ee alsoK
%reate a +imple o6o Accor!ion : .919:9(:14
di'it8la1out8Ta"Container
The Tab %ontainer can host a series of %ontent Panes where each pane shows in its own tab. "hen
one pane is shownB the others are hi!!en. +witching between panes is achieve! by clicking the tab
buttons. The ?title? attribute of the chil! %ontent Pane is use! as the te<t label on the tab to
show that specific content pane.
The location of the tabs can be controlle! by the ?tabPositio? property. The choices allow the
tab switching buttons to appear either on the topB bottomB left or right of the tab container.
+ome of the more interesting properties of Tab%ontainer inclu!eK
tabPositio 8 The location of the tabs. This may be one ofK
top
bottom
left:h
Page 1&4
right:h
useMenu
use+li!er
+ee alsoK
o6o ocs 8 Tab %ontainer 8 1./
!i6itHlayoutH+tack%ontainer
di'it8TitlePane
+etting the toggleable property to false will prevent the title pane from being collapse!.
di'it8la1out8Stac0Container
The +tack %ontainer can host multiple chil!ren Acalle! PanesD but only one chil! at a time is ever
shown. 't is similar in concept to the Tab%ontainer with the e<ception that the pane shown is
change! by logic an! not be user interaction with tabs.
The startup34 metho! shoul! be calle! once the wi!get is rea!y for use.
<di6 data-do.o-type01di.it-layout-#tackCotaier1>
<di6 data-do.o-type01di.it-layout-CotetPae> V <-di6>
<di6 data-do.o-type01di.it-layout-CotetPae> V <-di6>
<-di6>
The current pane can be selecte! using the selectChild3"idget4 metho!.
+ee alsoK
o6o !ocs 8 +tack%ontainer
!i6itHlayoutHTab%ontainer
di'it8la1out8#orderContainer
The 2or!er %ontainer *ayout is a layout container that splits its area up into # regions. These are
calle! ?top?B ?botto,?B ?le$t?B ?right? an! ?ceter?.
The 2or!er %ontainer can be further controlle! in with two !esign mo!es calle! ?headlie? an!
?sidebar? The choice is set in the ?desig? property. To see the !ifference between these two
mo!esB see the following two images.
The following image shows a headlie !esign mo!eK
Page 1&(
The ne<t image shows a sidebar !esign mo!eK
As you can seeB both contain the same number an! types of panels but the wi!th of top an! bottom
vs the height of left an! right are manage! !ifferently.
"hen the 2or!er %ontainer is create!B it is initially ?empty? meaning it has no content. 'ts chil!ren
are most likely going to be instances of ?CotetPae?. A chil! can be a!!e! using the
addChild34 metho! of the 2or!er %ontainer. "hen a chil! is a!!e!B the chil! tells 2or!er
%ontainer which region it shoul! live in by supplying a property calle! ?region?.
The leftB rightB top an! bottom regions can be given sizes. The center region will take what remains.
't makes sense that left an! right can have a wi!th specifier while top an! bottom can have a height
specifier.
"hen the 2or!er %ontainer is create!B it can be given a specific size or else it can be aske! to be
?199\? meaning it will be the size of the win!ow. This becomes important because if the win!ow
were resize!B 2or!er %ontainer will also resize resulting in resizing of the containers within.
An e<ample setup might beK
<ht,l style01height: L>>X21>
<body class01claro1 style01"idth: L>>X2 height: L>>X2 ,argi: >p*21>
<di6 data-do.o-type01di.it-layout-BorderPae1
style01"idth: L>>X2 height: L>>X21>
<-di6>
<-body>
<-ht,l>
The regions other than center can be !efine! with a property calle! splitter. 'f set to trueB then
Page 1&/
the region is re:sizable in a single !irection.
The following ;ava+cript will create an! a!! a 2or!er %ontainer with both left an! center regionsK
6ar borderCotaier 0 e" BorderCotaier3
B
title: 1My Border Cotaier1C
desig: 1hori)otal1C
style: 1height: I'>p*21
D42
borderCotaier%placeAt3this%cote*t%ele,etC 1$irst142
6ar le$t7egio 0 e" CotetPae3
B
style: 1"idth: GGX2 backgroud-color: Z55E(AE1C
title: 1My +e$t1C
regio: 1le$t1
D42
borderCotaier%addChild3le$t7egio42
6ar ceter7egio 0 e" CotetPae3
B
title: 1My Ceter1C
regio: 1ceter1
D42
borderCotaier%addChild3ceter7egio42
borderCotaier%startup342
"ithin 3TM* !eclaration we can co!eK
<di6 data-do.o-type01di.it-layout-BorderCotaier1
data-do.o-props01desig: OheadlieO1>
<di6 data-do.o-type01di.it-layout-CotetPae1
data-do.o-props01regio: OceterO1>
Ceter
<-di6>
<di6 data-do.o-type01di.it-layout-CotetPae1
data-do.o-props01regio: OtopO1>
<op
<-di6>
<di6 data-do.o-type01di.it-layout-CotetPae1
data-do.o-props01regio: Ole$tOC splitter:true1>
Ceter
<-di6>
<-di6>
+ome of the more interesting properties on the 2or!er %ontainer areK
desig 8 The primary !esign of the 2or!er %ontainer.
headlie 8 The top an! bottom regions will take the full wi!th.
sidebar 8 The left an! right regions will take the full height.
gutters 8 A gutter is an area aroun! a region that is empty. 't is very much like a margin.
The gutters property Atrue by !efaultD !etermines whether or not gutters are a!!e!. 'f a
region has a splitterB a gutter for resizing that region is always a!!e!.
The properties of interest on the content pane areK
regio 8 This is where the chil! content lives within the container. Cali! values areK
top 8 The top region
botto, 8 The bottom region
le$t 8 The left region
Page 149
right 8 The right region
ceter 8 The center region
splitter 8 true or false. %an be set on any region e<cept ?center?.
,i#i)e 8 The minimum size in pi<els if the size is shrunk by the splitter. +pecify 9 for
no minimum.
,a*#i)e 8 The ma<imum size in pi<els if the size is grown by the splitter. +pecify
'nfinity for ma<imum.
A particularly useful pattern for 2or!er%ontainer is to enclose a wi!get that ?wants? to be 199\ in
size but we woul! like to surroun! with other wi!gets.
>or e<ampleB imagine we have a chil! wi!get calle! ?G5P? that wants to be 199\ in size but we
want a label above it. "e can then co!e upK
<di6 data-do.o-type01di.it-layout-BorderCotaier1
data-do.o-props01desig: OheadlieO1
style01"idth: L>>X2 height: L>>X21>
<di6 data-do.o-type01di.it-layout-CotetPae1 data-do.o-props01regio: OtopO1>
<op Cotet
<-di6>
<di6 data-do.o-type01di.it-layout-CotetPae1 data-do.o-props01regio: OceterO1>
V ANW goes here V
<-di6>
<-di6>
+ee alsoK
ocs 8 !i6itHlayoutH2or!er%ontainer 8 1./
*ayout wi!th i6it 8 1./
sitepen : o6o >A=K "hy !oesn]t my 2or!er%ontainer !isplayJ : .913:9#:9.
do'ox8la1out8Ta"leContainer
This container lays out its chil!ren in a table with optional labels either above or besi!e the entries.
This makes it very useful for creating form entries.
The label is set by the chil!Ms ?label? or ?title? property.
3ere is an e<ampleK
The orietatio property can be use! to set the location of the labels relative to the fiel!. 3ere
we see the same !efinition with the orietatio set to ?6ert?K
Page 141
orietatio 8 The location of the labels relative to the fiel!. The choices areK
?6ert? 8 The label is above the fiel!.
?hori)? 8 The label is to the left of the fiel!. This is the !efault.
+ee alsoK
o6o ocs 8 !o6o<HlayoutHTable%ontainer 8 1.19
do'ox8la1out8*ridContainer
The notion behin! this wi!get is to provi!e a container into which other wi!gets can be place!. The
wi!gets containe! within can be !ragge! an! !roppe! !ynamically by the en! user into a set of
columns. This provi!es a simple ?Portal? like environment.
"hen the wi!get is inclu!e!B two new properties are a!!e! to the base class of other i6it wi!gets
Ainherite! through @WidgetBaseD. These properties areK
colu, 8 "hich column shoul! the wi!get be inJ %olumns start at 1.
drag7estrictio 8 +houl! the wi!get be allowe! to be !ragge!J
'n or!er to use this wi!getB one must inclu!e the following %++ style sheetsK
do.o*-layout-resources-?ridCotaier%css
do.o*-layout-resources-Ed?ridCotaier%css
The properties of this wi!get inclu!eK
acceptTypes
colWidths 8 A list of column wi!ths. The enco!ing is a comma separate! string.
has7esi)ableColu,s 8 %an the columns be resize!J
isAuto/rgai)ed 8 +houl! the wi!gets be organize! for usJ efault is true.
is*eft>i<e!
is$ight>i<e!
live$esize%olumns
,iColWidth 8 The minimum column wi!th as a percentage.
,ode 8 'f !ynamically a!!ing columnsB !o we a!! to the left or the rightJ
Page 14.
bWoes 8 The number of columns AzonesD in the gri!.
There are also a number of metho!s of interest on the @ri!%ontainer inclu!ingK
setColu,s34 : +et the number of columns to show. This has to be greater than or
e)ual to the number of columns that contain wi!gets. >or e<ampleB if a gri! container
contains three wi!gets with the first two being in column 1 an! the last being in column .B
then we can set the number of columns to be . or greater. "e canMt set the number of
columns to be 1 while the number of use! columns is greater than 1.
eableEd34 : -nable! rag an! !rop in the container.
disableEd34 : isable rag an! !rop in the container.
getChildre34 : $eturns a No!e*ist of chil! wi!gets container in the container. 7se
the No!e*ist accessors to work with this ob6ect. 't isnMt a simple array.
%losely associate! with the ?ridCotaier is a secon! o6o wi!get calle!
?do.o*%"idget%Portlet?. This wi!get provi!es a title pane container that is !esigne! to live
within a ?ridCotaier. 't has a relationship to ?ridCotaier in that it can be !ragge!
an! !roppe! aroun! the environment.
This wi!get also has a re)uire! style sheet calle!K
do.o*-"idget-Portlet-Portlet%css
The Portlet wi!get has the following propertiesK
closeable 8 A boolean that !efines whether or not the wi!get can be close!.
drag7estrictio 8 %an the wi!get be !ragge!.
title 8 The title of the Portlet.
To nest even furtherB a chil! of a Portlet can be an instance of
do.o*%"idget%Portlet#ettigs which will a!! a settings pop:!own to the wi!get.
+ee alsoK
!o6oocs 8 !o6o<HlayoutH@ri!%ontainer 8 1./
!o6oocs 8 !o6o<Hwi!getHPortlet 8 1./
A rich sample of @ri! %ontainer
Expando Pane
This wi!get is flagge! as e<perimental. 't is meant to be containe! within a 2or!er %ontainer.
'n or!er to use this "i!getB one must inclu!e a style sheet foun! atK
do.o*-layout-resources-(*padoPae%css
Colors
o6o provi!es a couple of wi!gets for picking colors.
Page 143
di'it8ColorPalette
Among the more interesting properties of this wi!get areK
palette 8 A string of either ?T*L>? or ?G*S? !escribing the size of the palette.
6alue 8 The currently selecte! color.
The Data 9rid
Arguably one of the most important wi!gets in the o6o set is the ata @ri! wi!get. This is a table
wi!get that !isplays !ata in rows an! columns.
The ata @ri! is containe! in the mo!ule calle! ?do.o*-grid-Eata?rid? so any page or
script which uses it shoul! inclu!eK
reFuire3Q1do.o*-grid-Eata?rid1RC $uctio3Eata?rid4 BVD42
The creation of an e<ample new ata@ri! looks likeK
6ar grid 0 e" Eata?rid3B
Fuery: B id: 1Y1 DC
structure: Q
B a,e: 1A1C $ield: 1A1C "idth: 1'>p*1 DC
B a,e: 1B1C $ield: 1B1C "idth: 1'>p*1 DC
B a,e: 1C1C $ield: 1C1C "idth: 1'>p*1 D
R
DC 1test?rid142
grid%startup342
$emember to call the grid%startup34implicitly or e<plicitlyOO it is very easy to omit.
The columns in the gri! are !efine! by the ?structure? ob6ect !escribe! in more !etail later.
After a gri! is shownB its structure can be change! at a later time using the set#tructure34
metho!.
The ata@ri! itself is !efine! with the following propertiesK
data-do.o-id 8 The name of a global variable that will hol! a reference to the "i!get.
store 8 The name of a variable use! to hol! the +tore !ata.
ro"#elector 8 A %++ wi!th selector or ?true? to show an area on the left for selection
Page 141
selectioMode
none
single
multiple
e<ten!e!
column$eor!ering
hea!erMenu
autoHeight
Not supplie! 8 the height of the Q!ivR
true 8 resize to the number of rows
QnumR : ma<imum number of rows to show
auto"i!th
single%lick-!it
loa!ingMessage
errorMessage
selectable
formatter+cope
up!ateelay
initial"i!th
escape3TM*'nata
Notice that the columns are !efine! in the structure fiel!. -ach column has the following
propertiesK
a,e 8 The column name shown in the table
$ield 8 The fiel! Aor propertyD in the !ata to be use! to show the entry
"idth 8 The wi!th of the column in the table
cell<ype 8 The type of cell in the columnB for e<ampleK
!o6o<.gri!.cells.2ool
!o6o<.gri!.cells.+elect
get 8 A function to be calle! that will retrieve the value for this cell
optios 8 7se! to provi!e allowable values for a +electH%ombobo< fiel!.
editable 8 A boolean value that !efines whether or not the fiel! is e!itable.
$or,atter 8 A function use! to return the content A3TM* or wi!getD use! to show the
cell. +eeK >ormatting.
Page 14#
hidde 8 A boolean. "hen set to trueB the column is hi!!en.
classes 8 A set of %++ class names use! to style the column
The ata@ri! also supports the following eventsK
onMouse0ver
onMouse0ut
on$ow%lick
on$owbl%lick
on$ow%onte<tMenu
on+election%hange!
L more
'n or!er to use the ata @ri!B one must also inclu!e %++ stylesK
<lik rel01stylesheet1
hre$01http:--a.a*%googleapis%co,-a.a*-libs-do.o-L%T%L-do.o-resources-do.o%css1>
<lik rel01stylesheet1
hre$01http:--a.a*%googleapis%co,-a.a*-libs-do.o-L%T%L-di.it-the,es-claro-claro%css1>
<lik rel01stylesheet1
hre$01http:--a.a*%googleapis%co,-a.a*-libs-do.o-L%T%L-do.o*-grid-resources-claro?rid%css1>
+ee alsoK
o6o Toolkit 8 !o6o<.!ata.ata@ri!
+itepen 8 'ntro!uction to the ata@ri! 8 1.4
+itepen 8 %onnecting a +tore to a atagri! 8 1.4
+itepen 8 Populating your @ri! using !o6oH!ata 8 1.4
+itepen 8 "orking with the @ri! 8 1.4
+itepen 8 New >eatures in o6o @ri! 1.. 8 .99(:19:..
o6o @ri! "i!get 7p!ate!. ata 'ntegration an! -!iting 'mprovements 8 .99(:94:1&
+itepen 8 o6o 1.. @ri! 8 .99(:94:11
+itepen 8 o6o @ri!sK iving eeper 8 .994:11:13
+itepen 8 +imple o6o @ri!s 8 .994:11:9&
Setting *rid data
The !ata supplie! to the gri! to be shown shoul! be a store supplie! via the gri!Ms
set#tore3,y#tore4 metho!.
Edita"le cells
A ata @ri!Ms cells can be e!itable. 'n or!er to allow them to be e!ite!B the column must be flagge!
as e!itable. This can be set in the <th> tag with the attribute editable01true1. >or e<ampleK
<th $ield01a1 editable01true1>Colu, A <-th>
The ata +tore associate! with the gri! must also support the do.o%data%api%Write
interface. 2y !efaultB an e!itable cell is in a view only mo!e. To e!it the cellB it must be !ouble
clicke! to place it into an e!iting mo!e. An optional attribute calle! ?al"ays(ditig? can be
a!!e! so that the fiel! can be e!ite! 6ust by typing into it.
<th $ield01a1 al"ays(ditig01true1 editable01true1>Colu, A<-th>
Page 14&
'f !ouble click for e!iting is too muchB an option calle! ?sigleClick(dit? can be a!!e! so
that only a single click will be nee!e! to e!it the cell. This shoul! be a!!e! to the QtableR tag.
Selecting items
A check:bo< or ra!io button can be a!!e! in the left column to show selection. efining the
structure asK
structure: Q
B
type: 1do.o*%grid%@CheckBo*#elector1
DC
B
cells: Q
B a,e: 1BPE !a,e1C $ield: 1bpd!a,e1C "idth: 1U>p*1 DC
B a,e: 1Istace IE1C $ield: 1istaceId1C "idth: 1U>p*1 DC
B a,e: 1<ask #tatus1C $ield: 1task#tatus1C "idth: 1U>p*1 D
R
D
RC
The selecte! items in the gri! can be obtaine! by callingK
grid%selectio%get#elected34
This will return an array of items.
't appears that grid%selectio is a do.o*%grid%Eata#electio ob6ect. This ob6ect
has a property calle! selectedIde* which is the 9 base! row of !ata. The co!e to get the
selecte! !ata isK
6ar * 0 grid%getIte,3grid%selectio%selectedIde*42
+ee alsoK
+itepen 8 "orking with the @ri! 8 1.4
Adding new rows
The ata store associate! with the ata @ri! is ?live?. This means changes to the ata +tore are
reflecte! in the ata @ri!. A!!ing a new 'tem in the ata +tore results in a new row being shown
in the table. To a!! a new rowB we can perform work such asK
6ar grid 0 di.it%byId31gridId142
6ar store 0 grid%store2
store%e"Ite,3Ba:1e" a1C b: 1e" B1D4
5emo$ing rows
$ows can also be remove! from the ata @ri! by up!ating the store. A convenience function
calle! re,o6e#elected7o"s34 will remove selecte! rows from the table.
5eplacing the data
The !ata in a !ata gri! can be replace! by calling the gri!Ms set#tore34 metho! which takes a
Page 144
!ata store as input.
eg.
6ar store 0 e" /b.ect#tore3
B
1ob.ect#tore1: e" Me,ory3
B
1data1: data%caseHistories%ite,s
D4
D42
grid%set#tore3store42
9ormatting
The ?structure? property which !efines columnsB has a fiel! calle! $or,atter that is
supplie! as a function that takes the !ata value as a parameter.
2efore going furtherB let us re:iterate where the formatter function is !efine!. 't is !efine! within a
structure column !efinition an! hence it has peer fiel!s which inclu!e ?fiel!?. The ?fiel!? property
names the fiel! within the array of ob6ects A!ataD that is use! for sourcing the value for the cell. 't is
the value of the !ata ob6ectMs property containe! in the ?fiel!? attribute that is passe! to the
formatter function.
As an alternative to supplying a single ?fiel!? nameB we can supply an array of fiel! names. 'n this
caseB the parameter passe! to the formatter function will be an array of values.
>inallyB we can !efine the fiel! name as the magic value ?Iitem? an! in this case the complete
ob6ect correspon!ing to the row will be passe! to the formatter function.
The function must return an 3TM* string that will be !isplaye! in the cell.
B
$ield: 15ailure1C
a,e: 1#tatus1C
"idth: 1L>>p*1C
$or,atter: $uctio3did5ail4
B
i$ 3did5ail 00 $alse4
B
retur 1<i,g src0Oi,ages-ok%pgO ->12
D
retur 1<i,g src0Oi,ages-$ail%pgO ->12
D
D
As an alternative to returning 3TM* stringB we can also return a i6it "i!getK
+ee alsoK
+itepen : Populating your @ri! using !o6oH!ata 8 1.4
Sorting columns
A function is !efine! on the ata@ri! calle! ?can+ortAcolumn'n!e<D? which returns true or false. 'f
it returns trueB then the column is sortable otherwise it is not. Make sure that you realize that the
Page 14(
column'n!e< coul! be negative to in!icate that the column is sorte! !escen!ing. The first column
is ?1?. %onsi!er using Math%abs3colu,Ide*4 to get the absolute value.
Cell e$ents
"hen the mouse is over a cellB the oCellMouse/6er event can be use! to !etect that. The
event passe! in has a property calle! ?cell? that is an ob6ect. This has a property calle! ?ide*?
which is the numeric in!e< of the column that the cell belongs in A9 is the first columnD. 0ther cell
relate! events inclu!eK
on%ell%lick
9rid: , The ne7t generation Do-o Data 9rid;
@ri!G is a new an! mo!ern table system for o6o.
@ri!G can be !ownloa!e! from the @ri!G home page. 't arrives as a set of ;ava+cript source files.
't is e<pecte! to be loa!e! from the package that starts with ?gri!<?.
't re)uires a style sheet calle!
grid*-resources-claro-?rid*%css
The following AM packages shoul! be inclu!e!K
Package Alias
do.o-store-Me,ory
Memory
grid*-core-,odel-cache-#yc
%ache
grid*-?rid
@ri!
3ere is a sample of @ri!GK
6ar structure 0 Q
B id: Oa,eOC $ield: Oa,eOC a,e: O!a,eOC "idth: O'>p*ODC
B id: OcityOC $ield: OcityOC a,e: OCityODC
B id: OscoreOC $ield: OscoreOC a,e: O#coreOC "idth: O=>p*OD
R2
6ar store 0 e" Me,ory3B
data: Q
B id: LC a,e: OJohOC score: LG>C city: O!e" NorkOC birthday: OLU=>-I-'ODC
B id: IC a,e: OAliceOC score: LIGC city: OWashigtoOC birthday: OLU=S-G-TODC
B id: GC a,e: O+eeOC score: LSUC city: O#haghaiOC birthday: OLU=H-L>-=ODC
B id: SC a,e: OMikeOC score: L>>C city: O+odoOC birthday: OLU==-=-LIODC
B id: 'C a,e: O<o,OC score: =UC city: O#a 5raciscoOC birthday: OLUU>-L-ILOD
R
D42
6ar grid 0 e" ?rid3B
cacheClass: CacheC
store: storeC
structure: structureC
style: 1height: '>>p*21
D42
grid%placeAt31so,e!ode142
grid%startup342
@ri!< has a property calle! ?structure? which is the column layout of the table. 't consists of an
array of ob6ects where each ob6ect has the following propertiesK
Page 14/
$ield 8 The i!entity of the fiel! in a row of !ata that shoul! be shown in cell.
a,e 8 The column name of the column
decorator 8 A function that takes A!ataB row.i!B row.visual'n!e<D as parameters an!
returns the content of the cell. 'f not supplie!B the !ata of the cell itself is returne!.
editor 8 The class name of the i6it wi!get to show for e!iting
e!itorArgs 8
"idth 8 The wi!th of the column in %++ units
editable 8 whether or not the cell is e!itable
'f we nee! to change the structure after the gri! has been create!B we can call the setColu,s34
metho! which takes an array of column ob6ects as a parameter.
"ithin the @ri!G packageB there is an ob6ect calle! ?7o"? that owns a row in the gri!. This can be
returne! by a ?,odel%byId34? function call.
"ithin the $ow there are some important functionsK
getEata34 : @et the gri! !ata of this row.
getIte,34 : @et the store item of this row.
NotesK
'f we use @ri!G insi!e a custom wi!getB !o not ?startup? @ri!G until the startup of the
enclosing wi!get itself. 'f we start it too earlyB it !oesnMt seem to remove the ?No ata?
overlay.
"e can replace the !ata associate! with a @ri! using the ?set+toreAD? metho! foun! on the
gri!.
+ee AlsoK
@ri!G at github
@ri!G home page
9rid: Width and Height
The wi!th an! height of the gri! shoul! be supplie!. +etting the property calle! ?autoWidth? to
?true? results in the wi!th of the gri! being calculate! from the wi!th of the columns.
There is also a property calle! ?autoHeight?. 'f set to trueB then the gri! will always show all of
its content.
The gri! also provi!es paging support via the mo!ules calle! ?grid*-,odules-Pagiatio?
an! ?grid*-,odules-pagiatio-PagiatioBar?.
9rid: 0 &dding and removing ro%s
A new row can be a!!e! into the @ri! by accessing the store ob6ect an! invoking the a!! metho!.
"e can !elete a row using the store associate! with the gri!.
grid%store%re,o6e3ro"%id42
Page 1(9
+ee alsoK
0b6ect +tores an! ata +tores
9rid: Modules
The architecture of @ri!G is such that it has a set of optional plugins calle! ?mo!ules?. These can
be a!!e! to the gri! through the gri!Ms ?,odule? property which is an array of mo!ules.
-ach entry in the array is the class for the mo!ule that has been loa!e!. 'f we wishB we can provi!e
parameters to the mo!ule by a!!ing a list entry which is an ob6ect of the formK
B
,oduleClass: <class>C
<para,eter>: 6alue
D
gridx8modules8#ar
This mo!ule provi!es support for top an! bottom bars. "hen a!!e! to a gri!B two new gri! level
properties become available. These properties are calle! ?bar<op? an! ?barBotto,?. -ach
property is an array an! controls that appears in the top bar an! bottom bar. "e can loosely think
of bar<op an! barBotto, as a!!ing a QtrR table row into the 3TM*. -ach element in the
bar<op an! barBotto, array can also be thought of as a!!ing a local column AQt!RD. 'f the
elements in the array are themselves arrays then we will have multiple rows.
An element can also be an arbitrary i6it wi!get.
3ere are some e<amples
bar<op:
Q
re$reshButtoC -- 3a istace o$ a di.it-$or,-Butto4
#upport#u,,aryC -- <he class grid*-support-#u,,ary
B
plugiClass: #upport+ik#i)erC
style: 1te*t-alig: right21
DC
B
cotet: 1Hello World1C
style: 1color: red21
D
R
+ee alsoK
3ow to a!! bars to gri!<J
gridx8modules8Cell(idget
The CellWidget mo!ule allows a %ell to contain a o6o "i!get Ai6itD. The !ecorator may
return 3TM* which is parse! by the i6it parser to create the wi!get. >or e<ample
decorator: $uctio34B
retur Q
O<spa data-do.o-type01di.it%$or,%CheckBo*1 OC
Odata-do.o-attach-poit01cb1 OC
Odata-do.o-props01read/ly: true1OC
O><-spa>O
R%.oi3OO42
DC
woul! create a checkbo< wi!get. Make sure that you also set the property "idgetsICell to be
true. To set a value within the wi!getB the column !escriptor has a metho! calle!
setCell:alue3gridEataC storeEataC "idget4 a!!e! to it. "hen this function is
Page 1(1
calle!B it is the responsibility of the function to set the wi!get to contain the !ata value. Notice that
in the wi!get !escriptionB we can a!! the data-do.o-attach-poit option. This creates a
variable which can be accesse! in the setCell:alue callback through
this%<6ariable!a,e>. This will be the ob6ect reference to the new wi!get.
'magine that the cell is !efine! to have a button containe! within it. This may look like the
following column !efinitionK
B $ield: 1a,e1C a,e: 1Actios1C "idgetsICell: trueC
decorator: $uctio34 B
retur 1<di6 data-do.o-type0Odi.it-$or,-ButtoO data-do.o-attach-poit0ObtO data-do.o-
props0Olabel: \1Eelete\1O><-di6>12
DC
Now suppose we want to han!le an event on a button click. "e can !o that through the
?getCellWidgetCoects34? metho! that is also a!!e! to the column !efinitionK
getCellWidgetCoects: $uctio3cellWidgetC cell4 B
retur Q
Q cellWidget%btC OoClickOC $uctio3e4 B
debugger2
cell%ro"%grid%store%re,o6e3cell%ro"%id42
DR
R2
D
The notion here is that the getCellWidgetCoects function returns an array of ?connection?
!efinitions. -ach connection !efinition !efines the wi!getB event an! callback function to be
manage!. "hen the callback function is invoke!B it has a copy of the cellWidget an! cell in
its conte<t.
gridx8modules8Column5esi2er
This mo!ule allows columns to be resize! horizontally. "hen the mouse is move! to the area
between columns on the hea!erB the columns can then be !ragge! left or right.
Among its more interesting properties areK
detectWidth 8 The wi!th Ain pi<elsD that a mouse entry to the left or right of the
separator will be !etecte! as a resize potential re)uest.
gridx8modules8Edit
The -!it Mo!ule allows for e!iting of cells within the gri!. 2e sure an! AM inclu!e
grid*-,odules-(dit.
"hen a gri! inclu!es the -!it mo!uleB this !oes not mean that all the cells are imme!iately e!itable.
'nstea!B we must tell the gri! which columns contain e!itable fiel!s. "e !o this by setting the
column property calle! editable to true. The !efault is $alse which means that cells in that
column are not e!itable.
"hen a cell is to be e!ite!B a new instance of a o6o wi!get Ai6itD is create! at the location of the
cell on the screen. This wi!get is responsible for showing the current value an! allowing the user to
change that value. 2y !efaultB the wi!get use! is an instance of di.it-$or,-<e*tBo*
however !ifferent wi!get types can be use!. The property calle! editor shoul! be set to the
String name of the i6it class to be use!. $emember to !efine an AM inclu!e of this class type
if it is use!. Another column property calle! editorArgs can be use! to supply properties to the
wi!get name! in editor. The editorArgs property is an ob6ect which the following
propertiesK
Page 1(.
props A+tringD : +et of properties !efine! on the i6it "i!get
$ro,(ditor AfunctionAstoreataB gri!ataDD 8 >unction to be calle! to return the value
from the e!itor.
to(ditor AfunctionAstoreataB gri!ataB cellB e!itorDD : >unction is calle! to populate the
e!itor wi!get. The e!itor parameter is a reference to the i6it wi!get use! to e!it the cell.
costraits A0b6ectD : A!!itional properties passe! to the e!itor.
use?ridEata A2ooleanD : +houl! the e!itor be fe! with !ata from the +tore or from the
@ri!J The !efault is false which means to use the store !ata. This property is not use! if
to-!itor is supplie!.
6alue5ield A+tringD : The property of the e!itor that hol!s the value. This is normally
value which is the !efault.
"hen the e!it of the cell has finishe!B the !ata entere! is written back into the store. "e can
change how this is achieve! by provi!ing a function to be calle! to apply the change using our own
logic. The property for this is custo,Apply(dit which is a function with the signature
functionAcellB valueD. 't is the responsibility of the co!e to set the value of the cell to be the value
passe! in as a parameter.
3ere is an e<ample of a simple e!itable gri!
6ar layout 0 Q
B
V
1editable1: true
V
D
R2
6ar grid 0 e" ?rid3B
V
1structure1: layoutC
1,odules1: Q(ditRC
V
D42
2y a!!ing -!it to your gri!B the cell ob6ect has some a!!itions inclu!e!K
editor34 : returns the i6it wi!get that is use! to !isplay the e!iting
-vents are also a!!e! inclu!ing
oBegi3cell4 : calle! when e!iting begins.
oApply3cellC apply#uccess4 : calle! after the changes ma!e by e!iting have
been applie!. apply+uccess is true if the application of the changes was successful.
oCacel3cell4 : %alle! when e!iting of the cell is cancele!.
To a!! an event han!lerB the following may be use!K
,y?rid%edit%coect3,y?rid%editC 1oBegi1C $uctio3cell4 B%%%D42
*et us now look at an e<ampleK
B $ield: OcolorOC a,e: OColorOC "idth: OL>e,OC editable: trueC
decorator: $uctio3data4B
retur Q
O<di6 style01display: ilie-block2 border: Lp* solid black2 OC
O"idth: I>p*2 height: I>p*2 backgroud-color: OC
dataCO1><-di6>O
R%.oi3OO42
Page 1(3
DC
editor: Odi.it-ColorPaletteOC
editorArgs: B
$ro,(ditor: $uctio36C cell4B
retur 6 [[ cell%data342 --I$ o color selectedC use the origial oe%
D -- (d o$ $ro,(ditor
D -- (d o$ editorArgs
D
Note the e!itor property. 't says that that the e!itor for this column will be the %olorPalette.
gridx8modules89ilter
This mo!ule a!!s the core capability to filter the rows in the gri!. 't supplies two core functionsK
set>ilterAD : +ets a function to filter the !ata.
get>ilterAD : @ets the current function use! to filter the !ata.
These functions !efine the filter algorithm use! to filter the !ata.
gridx8modules8filter89ilter#ar
This mo!ule provi!es a filter bar to select the filtering of the !ata. This mo!ule re)uires that
grid*-,odules-5ilter also be installe!.
gridx8modules8enu
The Menu mo!ule provi!es support for conte<t menus within the gri!. A conte<t menu is shown
with a right:click action upon the gri!. "hen the Menu mo!ule is a!!e! to the gri!B a new ob6ect
can be foun! at grid%,eu. This ob6ect e<poses two metho!s for working with menus. The first
is calle! bid3,euEi.itC bidArgs4. The first parameter is an instance of a menu create!
by o6o. The secon! parameter !escribes how the menu is to be boun! to the gri!. The is an ob6ect
which can containK
hookPoit A+tringD : This may be one ofK
?cell?B
?header?
?headercell?
?ro"?
?body?
?grid?.
selected A2ooleanD : +houl! the menu be boun! only to the selecte! items
"hen a menu item is fire!B the grid*%,eu%cote*t property !etermines what it is that the
menu is being applie! to. The properties containe! in this areK
cell
colu, : 0nly set when hookPoit is headercell.
gri!
ro" 8 An instance of a grid*-core-ro" representing the row that was clicke!. 0nly
set when hookPoit is ?ro"?.
Page 1(1
't is not e<pecte! that all properties are populate!. 'nstea!B the property populate! will be a function
of the hookPoit attribute set in the menu options.
The secon! metho! available is calle! ubid3,eu4 which unbin!s a previously boun! menu.
3ere is a )uick e<ample of a!!ing a menu such that when a row is conte<t clickB a menu appearsK
6ar ,eu 0 e" Meu342 -- Istace o$ di.it-Meu
,eu%addChild3e" MeuIte,3Blabel: 1testL1D442
grid%,eu%bid3,euC BhookPoit: 1ro"1D42
+ee alsoK
Menus
gridx8modules8Pagination#ar
This mo!ule shows the paging controls through the table. 't uses a!!itional mo!ules inclu!e
grid*-support-#u,,aryB grid*-support-+ikPagerB
grid*-support-+ik#i)er an! grid*-support-?otoPageButto.
To achieve the same effect using grid*-,odules-BarB we can !efine the barBotto, asK
barBotto,:
Q
#upport#u,,aryC
#upport+ikPagerC
B
plugiClass: #upport+ik#i)erC
style: 1te*t-alig: right21
DC
#upport?otoPageButto
R
gridx8modules85owHeader
A!! a hea!er in front Ato the left offD of each row in the gri!K
This mo!ule is typically use! by the grid*-,odules-Idirect#elect mo!ule.
+ee alsoK
gri!<Hmo!ulesH'n!irect+elect
gridx8modules8select85ow
A!!ing this mo!ule allows a row to be selecte!. 't is suggeste! that the AM alias be
?#elect7o"?. After a!!ing this mo!uleB the grid%select%ro" ob6ect will be foun!.
"e can attach a han!ler to the selection such asK
grid%coect3grid%select%ro"C Oo#electedOC $uctio3ro"C ro"Id4 B
debugger2
D42
Page 1(#
+ome of the more interesting properties of this mo!ule areK
,ultiple 8 A boolean. 'f falseB only single selection is allowe!. The !efault is true
which allows multiple selection.
+ome of the more interesting metho!s inclu!eK
get#elected34 : $eturns an array of all the ?i!s? of the selecte! items. 'f nothing is
selecte!B an empty array is pro!uce!. The mo!el by'!AD function can be use! to get the !ata
for the rows once we have the i!.
-vents inclu!eK
o#elected3ro"C ro"Id4 8 The row property is an ob6ect that represents the row
Asee grid*-core-7o"D. The rowMs ite,34 function can be use! to retrieve the !ata for
the row.
gridx8modules8IndirectSelect
This mo!ule a!!s a check bo< or a ra!io button in the row hea!er area. This mo!ule is !esigne! to
be use! in con6unction with ?grid*-,odules-select7o"? an!
?grid*-,odules-7o"Header?. The property calle! ?select7o"Multiple? is a boolean.
'f trueB multiple selections Acheckbo<D is shown an! if falseB only a single selection is allowe! which
means a ra!io button is shown.
+ee alsoK
gri!<Hmo!ulesH$ow3ea!er
gridx8modules8SingleSort
This mo!ules a!!s sorting capabilities to the columns.
't a!!s a property to the column !efinitions calle! ?sortable?. The type of this property is a
boolean. 'f set to $alseB then the column is not sortable an! will not respon! to sort re)uests.
This mo!ule a!!s an optional @ri!G property calle! ?sort'nitial0r!er? which allows us to choose a
column that will be use! for initial sorting. The value of this property is an ob6ect with the
propertiesK
colId 8 The i! of the column to be sorte!.
descedig 8 A boolean to !eci!e whether to sort up or !own.
>or e<ampleK
sortIitial/rder: B colId: 1,yColId1C descedig: $alse D
gridx8modules8Title#ar
This mo!ule has been !eprecate! in favor of grid*-,odules-Bar. 't shoul! not be use! in
new pro6ects an! shoul! be replace! when possible.
gridx8supportLin0Si2er
This mo!ule is !esigne! to be use! in con6unction with the gri!<Hmo!ulesH2ar mo!ule. 't provi!es
a set of clickable links that show !ifferent page sizes that can be selecte!.
3ere is an e<ample of this mo!uleMs !efault appearanceK
Page 1(&
Among its properties there areK
si)es 8 An array of numbers correspon!ing to the !ifferent sizes that can be supplie! for
paging. A negative number means ?all?.
9rid: tyling
Mouse and keyboard events
Mouse an! keyboar! events can be capture almost anywhere in the @ri!G environment.
The following regions are !etectableK
3ea!er
3ea!er%ell
$ow
%ell
$ow3ea!er3ea!er
$ow3ea!er%ell
>or each of the aboveB the following events are !etectableK
Mouse0ver
Mouse0ut
Mouseown
Mouse7p
%lick
bl%lick
%onte<tMenu
,eyown
,ey7p
,eyPress
The way to register for an event isK
grid%coect3gridC 1<e6et a,e>1C $uctio3e6t4 B
-- code here
D42
The Qevent nameR is ma!e up by the following algorithmK
1o1 K <7egio !a,e> K <(6et !a,e>
for e<ampleB to !etect a mouse over event upon a cellB we woul! useK
oCellMouse/6er
The event payloa! !efines a variety of !ifferent properties that are configure!K
Propert" When populate!
Page 1(4
row'! %ellB $owB $ow3ea!er%ell
row'n!e< %ellB $owB $ow3ea!er%ell
parent'! %ellB $owB $ow3ea!er%ell
visual'n!e< %ellB $owB $ow3ea!er%ell
column'! %ellB 3ea!er%ell
column'n!e< %ellB 3ea!er%ell
cellNo!e %ell
hea!er%ellNo!e 3ea!er%ell
row3ea!er%ellNo!e $ow3ea!er%ellB $ow
is$ow3ea!er $ow3ea!er%ellB $ow
Common 9rid: patterns
"hen working with @ri!GB there are common patterns that come about. 3ere is a list of some of
the more common recipes.
Adding 5ow Selection
To a!! row selectionB we nee! to inclu!e the following mo!ulesK
gri!<Hmo!ulesHselectH$ow
gri!<Hmo!ulesH'n!irect+elect
gri!<Hmo!ulesH$ow3ea!er
'f we wish single row selection Ara!io buttonD then set the gri! constructor property calle!
?select7o"Multiple? to be false. 'f we wish multi row selection Acheck bo<esD then set
?select7o"Multiple? to be true.
(or0ing with 5ows
'f we are given an ob6ect that represents a @ri!G rowB what can we !o with itJ The ;ava+cript
ob6ect that represents the row can be foun! !ocumente! at ?grid*-core-7o"?.
'f we are supplie! a ?cell? ob6ectB we can fin! the row that contains the cell using the ?row?
property.
0ne of the most important things is to get the !ata associate! with that row. This can be retrieve!
with the ?ite,34? metho!.
+ome of the more important metho!s inclu!eK
ite,34 : $etrieve the item from the store for this row
Adding and processing "uttons
0n occasionB we may wish to a!! a button into the gri!. "hen clicke!B this button will likely ?!o
something? against the selecte! row. The @ri! must have the ?CellWidget? mo!ule associate!
with it.
Page 1((
>irst we can create a column in the gri! to hol! the button.
B $ield: 1a,e1C a,e: 1Actios1C "idgetsICell: trueC
decorator: $uctio34 B
retur 1<di6 data-do.o-type0Odi.it-$or,-ButtoO data-do.o-attach-poit0ObtO data-do.o-
props0Otitle: \1My<itle\1C icoClass: \1,yIco\1C sho"+abel: $alseC
baseClass: \1,ii,alButto\1O><-di6>12
DC
getCellWidgetCoects: $uctio3cellWidgetC cell4 B
retur Q
Q cellWidget%btC OoClickOC $uctio3e4 B
-- OcellO cotais the cell clicked V
-- Ocell%ro"O cotais the ro"
-- Eo so,ethig here %%%
DR
R2
D --(d o$ getCellWidgetCoects
D -- (d o$ Actios colu,
The relate! %++ looks likeK
%,yIco B
backgroud-i,age:url31i,ages-,yIco%pg142
"idth: LHp*2
height: LHp*2
te*t-alig: ceter2
backgroud-repeat: o-repeat2
D
%,ii,alButto B
D
%,ii,alButto %di.itButto!ode B
border: >p*2
D
The dgrid , The ne7t generation Do-o Data 9rid;
The gri! has a colu,s property which !efines which columns are to be shown. 't can be
supplie! in a number of ways inclu!ing an array of ob6ects of ?fiel!Hlabel?K
Q
B
$ield: 1$irst1C
label: 15irst Colu,1
DC
B
$ield: 1secod1C
label: 1#ecod Colu,1
D
R
ata can be passe! to the gri! via the ?rederArray3data4? metho! which takes as a
parameter an array of ob6ects. These ob6ects will be ren!ere! in the gri!. 't has been note! that
!ata !oesnMt always !isappear if we e<ecute rederArray34 a secon! time. 'nvoking
re$resh34 before a ren!er seems to work.
The way to create a gri! is withK
6ar grid 0 e" ?rid3B
colu,s: -- Colu,s de$iitio
DC 1gridId142
grid%rederArray3,yEata42
+ee alsoK
!gri!
Installing !grid
gri! has a number of prere)sK
Page 1(/
<style
put:selector
The Tree
o6o provi!es an elegant tree "i!get that can show hierarchical !ata. The core of the tree is a i6it
wi!get calle! di.it-<ree. This provi!es the visual representation of the tree in the browser.
The tree however !oes not own the !ata. 't merely provi!es a visualization of the mo!el of the !ata.
The !ata itself is owne! by an ob6ect that implements the tree mo!el.
The !ata fol!ers shown in the tree can be opene! an! close!.
+ee also
ocs 8 !i6itHTree 8 1./
ocs 8 !i6itHTree e<amples 8 1./
%onnecting a +tore to a Tree
!eveloper"orks : %omment linesK +cott ;ohnsonK *azily loa!ing your o6o i6it tree wi!get can improve performance : .99(:9#:11
di'it8Tree
The construction of a tree merely nee!s a !ata ob6ect that contains the !ata to be shown in the tree.
This is containe! in the di.it-tree-/b.ect#toreModel.
6ar ,y<ree 0 e" <ree3B,odel: ,yModelD42
,y<ree%placeAt3,y!ode42
,y<ree%startup342
"hen an element in the tree is selecte!B its ?oClick3ite,4? metho! is invoke!. The item
passe! is the entry in the tree that was selecte!.
To only allow single selectionsB the following fragment can be use!K
,y<ree%ddCotroller%sigular 0 true2
The icons shown in the tree are create! by provi!ing a class name for the image. The class name
can be overri!!en by provi!ing your own implementation of the getIcoClass3ite,4
function. This is passe! an item as a parameter an! shoul! return the name of the class to use.
+ome of the more useful properties of di.it-<ree areK
sho"7oot 8 A boolean. 'f set to falseB the root of the tree is not shown in the tree
visualization. 0f course it still e<ists within the mo!el.
selectedIte,s 8 A list of the selecte! items in the tree.
+ome of the more useful metho!s areK
get<ooltip3ite,4 8 This metho! returns a tooltip for the item in the tree. 't shoul!
return a string.
+ee alsoK
!i6itHtreeH0b6ect+toreMo!el
%onnecting a store to a tree 8 1./
Page 1/9
di'it8tree8odel
This is an abstract interface that !escribes the metho!s an! properties provi!e! by a tree mo!el.
The di.it-tree-/b.ect#toreModel is an e<ample of a pre:built instance of this interface.
An implementation of this interface must provi!eK
!estroy
getChildre 8 0btain a list of chil!ren of the passe! in item.
getIdetity 8 $eturn the i!entity of the passe! in item.
get+abel 8 $eturn the label that shoul! be use! for the item in the tree.
get7oot3oIte,4 8 %alls a function with the root items as a parameter. (oteK This is
rather subtle. "e woul! have e<pecte! this to return the root item but take care to note that
it is a function that nee!s to be calle! which is passe! as a parameter.
is'tem
,ayHa6eChildre 8 etermine if the passe! in item may have chil!ren.
new'tem
paste'tem
an! publish the following eventsK
oClick3ite,C odeC e6et4 8 %alle! when an item in the tree is clicke!.
on%hange
on%hil!ren%hange
A template for this ob6ect might beK
6ar ,odel 0 B
destroy: $uctio34 B
DC
getChildre: $uctio3paretIte,C oCo,plete4 B
DC
getIdetity: $uctio3ite,4 B
DC
get+abel: $uctio3ite,4 B
DC
get7oot: $uctio3oIte,4 B
oIte,3root42 -- !ote
DC
isIte,: $uctio3ite,4 B
DC
,ayHa6eChildre: $uctio3ite,4 B
DC
e"Ite,: $uctio3ite,4 B
DC
pasteIte,: $uctio3childIte,C oldParetIte,C e"ParetIte,C bCopyC isertIde*C be$ore4 B
DC
oChage: $uctio3ite,4 B
DC
oChildreChage: $uctio3paretC e"Childre+ist4 B
D
D2
di'it8tree83"'ectStoreodel
The di.it-tree-/b.ect#toreModel is a provi!e! implementation of the
Page 1/1
di.it-tree-Model that owns the !ata shown in a di.it-<ree. "hat it !oes is map from a
do.o-store to the tree mo!el.
-ach element in the store must have the followingK
id 8 A uni)ue i! that is uni)ue against all other elements in the store.
a,e 8 The label shown in the tree. The name of this property is the !efault but can be
change! with the ?labelAttr? property.
type 8 The type of the item in the tree. The name of this property is the !efault but can be
change! with the ?typeAttr? property.
paret 8 The i! of the parent in the tree
The store ob6ect that hol!s the !ata shoul! have a getChildre34 metho! a!!e! to it. This
shoul! return the chil!ren of the passe! in item. This is nee!e! to obtain the chil!ren for the tree.
2y !efaultB the tree seems to show an e<pan!Hcontract for every entity in it. "e can be a bit better
about this by implementing the ,ayHa6eChildre metho! on the /b.ect#toreModel to
return true or false. "e shoul! return false only if we know that the entry will never have chil!ren.
An e<ample of creating an /b.ect#toreModel might beK
6ar store 0 e" Me,ory3B
data: Q
B id: >C a,e:O7ootOC type:O7ootOD
R
D42 -- (d o$ store
store%getChildre 0 $uctio3ite,4B
-- Add a getChildre34 ,ethod to store $or the data ,odel "here
-- childre ob.ects poit to their paret 3aka relatioal ,odel4
retur this%Fuery3Bparet: this%getIdetity3ite,4D42
D2
store 0 e" /bser6able3store42
6ar ,odel 0 e" /b.ect#toreModel3B
store: storeC
Fuery: Bid: >DC
,ayHa6eChildre: $uctio3ite,4 B
i$ 3ite,%type 00 1Metric14 B
retur $alse2
D
retur true2
D
D42
+ee alsoK
!i6itHTree
o6o ocs 8 !i6itHtreeH0b6ect+toreMo!el 8 1./
%onnecting a store to a tree 8 1./
0b6ect +tores an! ata +tores
di'it8tree8TreeStoreodel : !o ,ot Use
"e list this class here only for reference it has been !eprecate! by new do.o-store mo!el an!
architecture. 7ses the ol! do.o-data story. There is no obvious known reason to continue to use
this item.
Page 1/.
'rogress $ar
i6it provi!es a progress bar which shows a bar with optional te<t containe! within it. Associate!
with the bar is a numeric value which is visually represente! by the size of the bar.
The core properties of this control areK
6alue 8 The value of the progress.
,a*i,u, 8 The ma<imum value of the bar.
label 8 The te<t containe! within the progress bar.
ideter,iate 8 A trueHfalse value. "hen trueB the bar animates to show that the
progress is unknown.
The coloring of the Progress 2ar appears to be governe! by the %++ ?backgroud? property of
?%claro %di.itProgressBar<ile?
do-o73calendar3Calendar
The do.o*-caledar-Caledar is a super rich wi!get for working with calen!ar !ata. The
wi!get shows slots of time into which entries may be place!. An entry has a start timeB an en! time
an! a te<t summary !escribing the nature of the entry.
The following illustrates what the %alen!ar looks like on a web page. This shows the calen!ar in its
!ay view mo!eK
There are three view mo!es available. 0ne is calle! ?!ay? which shows the !etails of a !ay. The
secon! is calle! ?week? which shows the !etails of !ays in a week an! the final is calle! ?month?
which shows the !ays in the month. The views belong to one of two possible styles. The styles are
Page 1/3
column ?column? an! ?matri<?. A column style shows !ata for a perio! Aeg. a !ayD in a single
column. The matri< style shows a ?gri!? of entries.
The !ata shown in the %alen!ar is boun! to an instance of a o6o +tore. 'f the content of the store
changesB so !oes the representation of the %alen!ar. %onverselyB if a user interactively changes the
%alen!arB the store up!ates itself to reflect the change at the !ata level.
-ach of the items in the store has the following formatK
B
id: -- A uiFue id $or the store%
su,,ary: -- A te*t 6alue that "ill be sho" as the su,,ary $or the etry
start<i,e: -- A Ja6a#cript Eate ob.ect $or the start date-ti,e
ed<i,e: -- A Ja6a#cript Eate ob.ect $or the ed date-ti,e
allEay: -- A Ja6a#cript boolea $lag to ,ark this as a 1all day1 etry
D
The ?i!? property is a uni)ue i!entifier that each item must posses. This is also man!ate! by the
o6o store technology. This uni)ue
An e<ample of creating a suitable store woul! beK
6ar store 0 e" /bser6able3e" Me,ory3Bdata: so,eEataD442
This can be set !ynamically on the %alen!ar using its ?store? property.
+ince the store is re)uire! to implement the do.o-store-/bser6able mo!elB we can !efine
an observe on a )uery to be informe! when something in the mo!el changes. This might be a
change cause! by the user by !ragging an entry Afor e<ampleD.
6ar results 0 store%Fuery3BD42
results%obser6e3$uctio3ite,C re,o6ed5ro,C isertedIto4 B
--debugger2
cosole%log3ite,42
DC true42
The function passe! on the observeAD is supplie! three parametersK
ite, 8 The item that has change!.
re,o6ed5ro, 8 'f the value is :1B then this represents a new a!!ition.
isertedIto 8 'f the value is :1B then this represents a !eletion.
-ach item can be style! in!ivi!ually. "hen an item is to be shownB a function !efine! by the
?cssClass5uc? property is calle! an! is passe! the item to be shown. This function can then
return a class name A+tringD which will be applie! to the item.
"hen working with the %alen!ar wi!getB when it has focusB keyboar! events can be sent to it.
%ursor left 8 +elect previous entry
%ursor right 8 +elect ne<t entry
%lick 8 +elect clicke! entry
"ith an entry selecte!B pressing ?-nter? will enter e!it mo!e. 0nce can then use the cursor keys to
move the entry aroun!. 3ol!ing the control key with the cursor allows one to e<pan! or contract
the entry. Press ?-nter? again to commit any changes ma!e or press ?-scape? to cancel any
pen!ing changes without commiting.
At the top of a calen!ar is a set of navigation buttons.
These navigation buttons are !efine! by a piece of template 3TM*. "hen the calen!ar instance is
Page 1/1
create!B a property calle! ?te,plate#trig? can be set to a fragment of 3TM*. This fragment
!efines the buttons. The !efault te<t looks as followsK
<di6>
<di6 data-do.o-attach-poit01buttoCotaier1 class01buttoCotaier1>
<di6 data-do.o-attach-poit01toolbar1 data-do.o-type01di.it%<oolbar1 >
<butto data-do.o-attach-poit01pre6iousButto1
data-do.o-type01di.it%$or,%Butto1 >\]^<-butto>
<butto data-do.o-attach-poit01e*tButto1
data-do.o-type01di.it%$or,%Butto1 >\_`<-butto>
<spa data-do.o-type01di.it%<oolbar#eparator1><-spa>
<butto data-do.o-attach-poit01todayButto1
data-do.o-type01di.it%$or,%Butto1><oday<-butto>
<spa data-do.o-type01di.it%<oolbar#eparator1><-spa>
<butto data-do.o-attach-poit01dayButto1
data-do.o-type01di.it%$or,%Butto1 >Eay<-butto>
<butto data-do.o-attach-poit01$ourEaysButto1
data-do.o-type01di.it%$or,%Butto1 >S Eays<-butto>
<butto data-do.o-attach-poit01"eekButto1
data-do.o-type01di.it%$or,%Butto1 >Week<-butto>
<butto data-do.o-attach-poit01,othButto1
data-do.o-type01di.it%$or,%Butto1 >Moth<-butto>
<-di6>
<-di6>
<di6 data-do.o-attach-poit016ie"Cotaier1 class016ie"Cotaier1><-di6>
<-di6>
Notice that it !efines a series of ?buttons?. 0mitting these !efinitions from your own custom
template will remove the buttons from the navigation area.
The buttons areK
previous2utton
ne<t2utton
to!ay2utton
!ay2utton
fourays2utton
week2utton
month2utton
+ome of the more interesting properties of the %alen!ar ob6ect areK
date 8 The start !ate shown in the calen!ar%
dateIter6al 8 The interval of the calen!ar. This entry shows some number of items
where the number is !efine! by the dateIter6al#teps property. The choices areK
?day? 8 +how dateIter6al#teps !ays. 3ere is a !ay calen!arK
Page 1/#
?"eek? 8 +how dateIter6al#teps weeks. 3ere is a week calen!arK
?,oth? 8 +how dateIter6al#teps months. 3ere is a month calen!arK
dateIter6al#teps 8 The number of steps to show. The type of steps is !efine! by
the dateIter6al property selection.
startEate 8 A !ate at which the calen!ar entries shoul! start. This is an alternative to
the !ateH!ate'nterval option. +ee also startEate.
edEate 8 A !ate at which the calen!ar entries shoul! start. This is an alternative to the
Page 1/&
!ateH!ate'nterval option. +ee also edEate.
start<i,eAttr 8 The name of a property AattributeD of an item in the store that will
contain the start !ate of an interval in the calen!ar. The !efault is ?start<i,e?.
ed<i,eAttr 8 The name of a property AattributeD of an item in the store that will contain
the en! !ate of an interval in the calen!ar. The !efault is ?ed<i,e?.
su,,aryAttr 8 The name of a property AattributeD of an item in the store that will contain
the summary te<t of an entry. The !efault is ?su,,ary?.
decodeEate 8 A function that will be calle! that will be passe! the value of a !ate an!
return a ;ava+cript ?ate? ob6ect. This will be useful if the start an! en! time attributes are
not ate ob6ects alrea!y.
ecodeEate 8 A function that will be calle! that will be passe! a !ate an! return a
;ava+cript ob6ect or +tring representing how the !ate is kept in the store. This will be
useful if the start an! en! time attributes are not ate ob6ects alrea!y.
colu,:ie"Props 8 An ob6ect which !escribes how the column of !ay !ata is shownK
,iHours 8 The start time of a !ay entry. >or e<ampleB setting to ( means the !ay
calen!ar starts at (K99am.
,a*Hours 8 The en! time of a !ay entry. This will show up to Abut not inclu!ingD the
en! time. >or e<ampleB setting to 1( means that the calen!ar en!s showing the hour
from #K99pm to &K99pm.
hour#i)e 8 The height Ain pi<elsD of a horizontal hour slot.
ti,e#lotEuratio 8 The number of minutes that an hour slot is broken into.
Calues that seem to work are 1# A1 slotsDB 39 A. slotsD an! &9 A1 slotD.
selectioMode 8 "hat kin! of item selection is possible.
oe 8 No item in the gri! may be selecte!.
sigle 8 0nly a single item in the gri! may be selecte!.
,ultiple 8 Multiple items in the gri! may be selecte!.
selectedIte,s 8 A list of the selecte! items.
selectedIte, 8 The last item selecte!.
create/?ridClick 8 'f set to trueB we can !ynamically create new calen!ar entries.
2y !efault this has a value of false an! new !ynamic gri! entries are !isable!. +ee also
create'tem>unc
createIte,5uc 8 This is a function that will be invoke! when the gri! is clicke! to
create a new item. This will only happen when the create/?ridClick property is set
to true. The function is responsible for buil!ing an! returning a new item for insertion into
the store. The function is passe! the following parametersK
6ie" 8 The view in the calen!ar that was clicke!.
date 8 The !ate that was selecte! for a new entry.
,ouse e6et 8 The mouse event that resulte! in the function being calle!.
Page 1/4
The function shoul! return a new item that will be inserte! into the calen!ar. 'f a return
without !ata is e<ecute!B no new entry will be a!!e!.
The wi!get also has some very useful functions available upon itK
floorateAD
floorToayAD
The wi!get also respon!s to eventsK
oIte,Cote*tMeu 8 'nvoke! when a conte<t menu is re)uest. Passe! in ob6ect
containsK
ite, 8 The item that was chosen.
source 8 The ob6ect that is the source of the selection.
trigger-vent 8 The event that cause! the menu to be shown.
+ee alsoK
!o6o<.calen!ar 8 $eference info 1./
0b6ect +tores an! ata +tores
Parsing Di)it in 'TML
"ithin an 3TM* page we can insert markers in the source of the 3TM* that will be parse! when
o6o is loa!e!. These markers will be use! to !ynamically create instances of i6it wi!gets. The
purpose of this techni)ue is to allow us to !eclaratively buil! web pages that use the i6it wi!gets
without having to e<plicitly co!e those up in ;ava+cript.
i6it wi!gets can be create! automatically in pages by flagging 3TM* elements with an in!ication
of the type of i6it wi!get to be create!. The type is flagge! using the ?data-do.o-type?
attributeK
data-do.o-type01<Widget <ype>1
The "i!get Type is a package name such as ?di.it-$or,-Butto?.
Properties of the wi!get can also be supplie! withK
data-do.o-props01<properties>1
The format of these properties is ?a,e: 6alueC a,e: 6alue %%%?
A global variable can be create! an! will be assigne! as a reference to the newly create! wi!get
using the following synta<K
data-do.o-id01<6ariable!a,e>1
"e nee! to be careful if we are !efining mo!ules an! those mo!ules have an e<pectation that all
parsing has been complete! before having their core functions e<ecute!.
'n the !efinition of such mo!ulesB co!e the followingK
reFuire3Q1do.o-ready1C VRC $uctio3readyC V4 B
ready3$uctio34 B
-- Code here "ill be ru a$ter iitiali)atios%
D
D42
"hen using the parserB we typically inclu!e markup that looks as followsK
<di6 data-do.o-type01module/myWidget1>
<-di6>
Page 1/(
'f we want to e<ecute a metho! on the wi!get after it is create!B we can a!!K
<di6 data-do.o-type01module/MyWidget1>
<script type01do.o-,ethod1>
this%so,e5uctio342
<-script>
<-di6>
'f we are using a "i!get that has not been use! before in the environmentB we must take care of
AM loa!ing. 'n the <head> section a!!K
<script type01te*t-.a6ascript>
reFuire3Q
1module/MyWidget1
R42
<-script>
"e can connect co!e to to a metho! in !eclaration L
<script type01do.o-coect1 data-do.o-e6et01,ethod a,e1 data-do.o-args016ar a,e1>
code here %%%
<-script>
"e can connect co!e to an event in !eclation
<script type01do.o-o1 data-do.o-e6et01click1>
cosole%log31ClickP142
<-script>
+ee alsoK
o6o Parser
%b)ect !tores and Data !tores
Prior to 1.&B o6o use! a technology calle! ?do.o-data? to store !ata. This is now consi!ere! a
legacy AP' that has been superse!e! by the concept of o6o 0b6ect +tores. An a!apter is provi!e!
that maps from the ol! do.o-data stores to do.o-store stores. This a!apter is calle!
?do.o-data-/b.ect#tore?.
The do.o%store%Me,ory ob6ect is a !ata store wrapper for arrays of ob6ects.
store 0 e" Me,ory3B
data: <array/$Eata>
D42
"hen using the do.o-store classesB their properties inclu!eK
data 8 an Array of ;ava+cript ob6ects being house! in the store
idProperty 8 The name of a property to be use! as a search key
The resulting store ob6ect has the following metho!s upon itK
Fuery 8 +earch the store for matching recor!s
add3ob.ectC optios4 8 A!! a new recor! into the store
re,o6e3id4 8 $emove an e<isting recor! from the store
put3ob.ectC optios4 8 7p!ate an e<isting row in the store
get3id4 8 $etrieve a single ob6ect as oppose! to ?Fuery? which returns an array of
ob6ects
Page 1//
get'!entity
)uery-ngine
transaction
get%hil!ren
getMeta!ata
The )uery metho! is very interesting. 't can be use! to )uery a store which returns an array of
ob6ects that matche! the )uery. The return is actually a o6o No!e*ist. This returne! array has a
number of metho!s on it inclu!ingK
for-achAD
mapAD
filterAD
length
The )uery e<pression for the )uery is an ob6ect which has properties correspon!ing to the property
being sought. >or e<ampleK
,y#tore%Fuery3Ba,e: 1!eil1D4
will return all the ob6ects in the store which have a name property e)ual to ?!eil?. To return all
items in the listB pass in an empty ob6ect AEFD. 'f the parameter to )uery is a function then the )uery
will pass the function each item in the store an! the result will be only those items that pass a test.
The secon! parameter to )uery is an ob6ect with properties as followsK
start 8 +tarting offset
cout 8 The number of ob6ects to return
sort 8 An array of ob6ects where each ob6ect is a !efinition of how the sort is to be
performe!. An instance of one of these ob6ects will contain the following propertiesK
attribute 8 The name of the attribute to sort upon
descedig 8 A boolean in!icating whether we want ascen!ing or !escen!ing sorting
't is possible to write our own function to perform the Fuery(gie task. The Fuery(gie
property of a store must be a function that takes the same parameters as the )uery. 5our own
function !oes not !o the work imme!iately. 'nstea!B what it !oes is return a function which takes
an array as input an! performs this specialize! )uery.
The result from the )uery inclu!es a metho! calle!K
for-achAfunctionAentryD E L F D
which allows us to e<ecute a function for each entry returne! from the )uery.
+ee alsoK
+itePen 8 o6o 0b6ect +tore 8 1./
!o6oHstore 8 1./
do-o3store3Memory
The do.o-store-Me,ory implements the o6o ob6ect store AP'. 't is use! to access store
Page .99
maintaine! !ata that is hel! in memory.
"hen constructe!B it has a property calle! ?data? that hol!s the initial !ata of the store.
do-o3store3!bservable
"hen one e<ecutes a )uery on a store an! that store is an 0bservableB then a function calle!
?obser6e34? may be e<ecute! on the returne! results. This causes the results to be ?monitore!?
an! if the results woul! change as if e<ecute! againB the function passe! by ?obser6e34? is
calle!. This function is passe! three parametersK
ite, 8 The item that change!
re,o6ed5ro, 8 "here the item was remove! from
isertedIto 8 "here the item was inserte! into
The formal synta< of obser6e34 isK
obser6e3$uctio3ite,C re,o6ed5ro,C isertedIto4C iclude/b.ect8pdates4
The iclude/b.ect8pdates !efines whether or not the changes to the content of the !ata will
be flagge!. The !efault is false.
Deferred and asynchronous processing + do)o4Deferred
"ithin o6oB there are times where we wish some action to be e<ecute! an!B when complete!B to
invoke a callback with the results. This is very common with A;AG programming. o6o provi!es
assistance with this function through the ?eferre!? capabilities.
3ere is a high level skeleton
$uctio ,yAsyc34 B
6ar de$erred 0 e" Ee$erred342
do#o,ethigIBackgroud3$uctio3A4 B
de$erred%resol6e3A42
D42
retur de$erred%pro,ise2
D
-- caller
,yAsyc34%the3$uctio3N4 B
V process result2
D42
The concept is that when something may happen in the backgroun!B the provi!er of that something
returns an instance of a ?Ee$erred?. eferre! has a metho! on it calle! ?the34? which takes
a function as a parameter. "hen the backgroun! thing has complete!B the provi!er of the
backgroun! service calls the metho! calle! ?resol6e34? on the eferre! ob6ect. This is what
triggers the ?the34? function.
'f the asynchronous function shoul! failB it may issue the ?re6ectAD? metho! to in!icate that this has
happene!.
+ee alsoK
o6o Programming $eference 8 eferre! 8 1./
Declare , Defining Do)o Classes
;ava+cript can be confusing to folks skille! in other ob6ect oriente! languages such as ;ava or %^^.
The )uestion aske! is ?'s ;ava+cript 00 or notJ?. ' !onMt have enough theoretical knowle!ge to
Page .91
answer that L but it appears that ?out of the bo<?B ;ava+cript !oesnMt have the concept of classesB
inheritance or other common 00 functions. 3oweverB o6o provi!es the ability to achieve these
concepts through the o6o ?declare? function that is part of the ?do.o-@base-declare?
package.
*et us start with an e<ample. *et us assume we wish to create a new class calle! ?MyClass? that
is in a ?package? calle! ?,yPackage?. The first step is to create a !irectory tree associate! with
the package. +o we might create a !irectory calle! ?,yPackage?. 'n that !irectoryB we woul!
now create a ;ava+cript source file with the name of the class we wish to !efine. >or e<ample a file
calle! ?MyClass%.s?.
"ithin the MyClass%.sB we now co!e our classK
de$ie3Q1do.o-@base-declare1RC $uctio3declare4 B
retur declare3ullC B
costructor: $uctio3aC bC c4 B
this%a 0 a2
this%b 0 b2
this%c 0 c2
D -- (d o$ costructor
D42 -- (d o$ declare
D42 -- (d o$ de$ie
"ith this !efine!B we can now use it byK
reFuire3Q1,yPackage-MyClas1RC $uctio3MyClass4 B
6ar ,y/b.ect 0 e" MyClass31aL1C 1bL1C 1cL142
D42
+ee alsoK
o6o $eference 8 !eclare 8 1./
Creating Custom Widgets
o6o allows us to create our own custom "i!gets. The result of this are new wi!gets that can be
use! 6ust like the o6o supplie! wi!gets. After a new wi!get is written an! !ocumente!B it can be
consume! by a o6o programmer an! the !etails of its own internal implementation can then be
hi!!en from the consumer. 'n or!er to buil! custom wi!getsB we nee! to start un!erstan!ing some
of the buil!ing blocks that are involve!.
>irst there is the i!ea of a te,plate. This is an 3TM* !ocument fragment that will be inserte!
into the page to visualize the wi!get. This is optional as the wi!get coul! also use ;ava+cript to
buil! its 3TM* content. 0f courseB a hybri! approach can also be applie! where both 3TM*
templates an! ;ava+cript are use! in con6unction with each other.
Ne<t there are any %++ +tyles that nee! to be applie!.
>inallyB there is the ;ava+cript that provi!es e<ecution semantics.
A new wi!get will inclu!e co!eK
declare31e" "idget a,e1C base "idget42
eg.
declare31di.i%$or,%<e*tBo*1C di.it%$or,%@5or,Widget42
%ustom wi!gets will inherit from di.it-@WidgetBase. 2y !oing thisB a life cycle is !efine!.
constructor
postscript
Page .9.
create
postMi<'nProperties
buil!$en!ering
postCreate 8 This is where most of the wi!get specification customization will occur.
startup
The filename containing the co!e is My"i!get.6s
%heat +heet for creating a custom wi!getK
1. %reate a file calle! <MyWidget>%.s
.. %reate a fol!er relative to the current fol!er calle! ?te,plates?
3. %reate a file calle! <MyWidget>%ht, in the ?te,plates? fol!er
1. 'n <MyWidget>%.sB a!! the followingK
de$ie3Q
1do.o-@base-declare1C
1di.it-@WidgetBase1C
1di.it-@<e,platedMi*i1C
1do.o-te*tP%-te,plates-<MyWidget>%ht,1
RC
$uctio 3
declareC
@WidgetBaseC
@<e,platedMi*iC
te,plate4 B
retur declare31<Module>%MyWidget1C Q@WidgetBaseC @<e,platedMi*iRC B
--
--
build7ederig: $uctio 34 B
this%iherited3argu,ets42
DC -- (d o$ build7ederig
-- <he te,plate to use $or the i.ected H<M+
--
te,plate#trig: te,plate
D42 -- (d o$ declare
D42 -- (d o$ de$ie
0nce a custom i6it "i!get has been built it can also be use! insi!e a %oach Ciew. To achieve
thisB create a P'P file an! within that P'PB place all the pieces of the wi!get such as ;ava+cript filesB
%++ files an! 3TM* files. Place that P'P file in a toolkit or process app as a manage! file.
Now comes the interesting part. 'n the ?'n:line ;ava+cript? for the new %oach CiewB a!! the
followingK
6ar path 0 co,@ib,@bp,@coach%getMaagedAsset8rl31kolba%)ip1C co,@ib,@bp,@coach%asset<ype@W(B4 K
1-kolba12
cosole%log3path42
reFuire3B
packages: Q
B
a,e: OkolbaOC
locatio: path
DRD42
+ee alsoK
%reating Template:base! "i!gets 8 1./
Page .93
o6o ocumentation : "riting 5our 0wn "i!get
7n!erstan!ing I"i!get2ase 8 1./
%reating a custom wi!get 8 1./
%reating o6o "i!gets with 'nline Templates : .99(:9&:.1
-!uzine : %reating %ustom "i!get in o6o : Part 1 8 .99(:9&:1.
-!uzine : %reating %ustom "i!get in o6o : Part .K Template! "i!gets 8 .99(:9&:11
eveloper"orks : evelop 3TM* "i!gets with o6o 8 .994:9.:11
Widget templating
"i!get templating is a great way of !efining the 3TM* that will be generate! for a new wi!get.
Amongst the capabilities of templates is the ability to co!e the ?data-do.o-attach-poit?
attribute. %onsi!er the following 3TM* templateK
<di6 data-do.o-attach-poit01,yAttach1>
V
<-di6>
2y !efining the aboveB when the new wi!get is create!B in the co!e of the wi!getB it will have
automatically create! a new property on that wi!get calle! ?,yAttach? which can be reference!
by ?this%,yAttach?. The value of this property will be the 0M no!e for the 3TM* element
that !efines the ?data-do.o-attach-poit?. This provi!es a first class an! elegant
mechanism for fin!ing elements within the template! 3TM*. 'f this property is use! on a
template! wi!get mi<:inB then the ob6ect will be that of the "i!get itself.
>or basic templatingB inclu!e di.it-@<e,platedMi*i. To process wi!gets in the templateB
also inclu!e di.it-@WidgetsI<e,plateMi*i
eg.
de$ie3Q
1do.o-@base-declare1C
1di.it-@WidgetBase1C
1di.it-@<e,platedMi*i1C
1di.it-@WidgetsI<e,plateMi*i1C
V
RC
$uctio3declareC @WidgetBaseC @<e,platedMi*iC @WidgetsI<e,plateMi*iC V4 B
retur declare3Q@WidgetBaseC @<e,platedMi*iC @WidgetsI<e,plateMi*iRC V42
D
42
Templating also provi!es the capability to use substitution variables. >or e<ampleK
aB,yPropertyD
will replace this with the value of ?,yProperty?. 3ere is a goo! e<ample of its use. 'magine we
have a wi!get that has the following in its templateK
<iput type01radio1
data-do.o-type01di.it-$or,-7adioButto1
a,e01ti,e7ageMethod1
id01rolligPeriod1
6alue01rolligPeriod1->
<label $or01rolligPeriod1>7ollig Period<-label>
The problem with the above is that the ?i!? property must be uni)ue within a web page. 3owever if
the above is in6ecte! as:is into a wi!get an! two instances of that wi!get were place! on the screen
we woul! en! up with unwante! !uplication. 7sing the variable substitution mechanismB we can
create uni)ue i!s by using the i! of the containing wi!get. >or e<ampleK
Page .91
<iput type01radio1
data-do.o-type01di.it-$or,-7adioButto1
a,e01ti,e7ageMethod1
id01aBidD@rolligPeriod1
6alue01rolligPeriod1->
<label $or01aBidD@rolligPeriod1>7ollig Period<-label>
+ee alsoK
Parsing i6it in 3TM*
!i6itHITemplate!Mi<in 8 1./
!i6itHI"i!gets'nTemplateMi<in 8 1./
%reating Template:base! "i!gets 8 1./
keleton %idget
3ere is a useful skeleton for a wi!get. This can be copie! an! paste! into a ;ava+cript source file as
a goo! place to start buil!ing out your own wi!getK
de$ie3
Q
1do.o-@base-declare1C
1di.it-@WidgetBase1C
1di.it-@WidgetsI<e,plateMi*i1C
1di.it-@<e,platedMi*i1C
1do.o-te*tP%-te,plates-,y<e,plate%ht,1
RC
$uctio 3
declareC
@WidgetBaseC
@WidgetsI<e,plateMi*iC
@<e,platedMi*iC
te,plate4 B
retur declare3Q@WidgetBaseC @<e,platedMi*iC @WidgetsI<e,plateMi*iRC B
-- Body o$ "idget here
te,plate#trig: te,plate
D42 -- (d o$ declare
D
42 -- (d o$ de$ie
27tending a %idget
-<isting i6it wi!gets can be e<ten!e! to provi!e customize! function. >or e<ample
retur declare31kolba%"idget%<ask<able1C QEata?ridRC B%%%D42
will e<ten! a ata@ri! table.
"e can overri!e e<isting functions. 'f we wish to call the parentMs functionB we can co!eK
this%iherited3argu,ets42
#sing getters and setters on a custom %idget
'f a custom wi!get has properties associate! with itB we can !efine functions that act as custom
getters an! setters. The correct way to retrieve a property from a wi!get is
6ar 6alue 0 ,yWidget%get31property!a,e142
the correct way to set a property on a wi!get isK
,yWidget%set31property!a,e1C e":alue42
"ithin the implementation of a wi!getB we !efine a getter function as a function with the nameK
@get<Property!a,e>Attr: $uctio34 B
V
retur 6alue2
D
Page .9#
to !efine a setter functionB we create a function with the nameK
@set<Property!a,e>Attr: $uctio3e":alue4 B
V
D
The property name within the function shoul! be !efine! with an initial upper case.
Do)o Publish and !ubscribe
o6o provi!es a publish an! subscribe mechanism where events can be publishe! an! subscribers
can register to be informe! when an event is publishe!. This provi!es very loose coupling between
pro!ucers of information an! consumers.
o6o provi!es a package calle! ?do.o-topic? which is commonly boun! to ?topic?.
To subscribe to a topicB we can useK
topic%subscribe31topic1C $uctio3data4 BVD42
To publish on a topicB we can useK
topic%publish31topic1C data42
The following is pre o6o 1.( an! can be remove! laterK
AMK do.o-@base-coect b coect
To publishB we e<ecute
coect%publish3(6et !a,e 3#trig4C (6et Message 3optioal42
+ubscribers can register using
hadle 0 coect%subscribe3(6et !a,e 3#trig4C $uctio3(6et Message4 B V D42
alternativelyB a ;ava+cript conte<t Aeg. thisD can also be provi!e!K
hadle 0 coect%subscribe3(6et !a,e 3#trig4C thisC $uctio3(6et Message4 B V D42
The subscribe34 metho! returns a subscription han!le that can later be use! to unsubscribe
usingK
coect%usubscribe3hadle42
Do)o Charting
o6o has the ability to !raw various chart styles.
The o6o charting package lives in the o6o mo!ule calle! ?do.o*%chartig%ChartIE?.
At a high levelB we create a <di6> screen area with a wi!th an! height. This is the area into which
the chart will be !rawn. An e<ample of creating such a <di6> woul! beK
<di6 id01,yId1 style01"idth: I'>p*2 height: L'>p*21><-di6>
0nce create!B when the page is loa!e!B we can then create a chart attache! to this <di6>
6ar chartL 0 e" do.o*%chartig%ChartId31,yId142
Notice that the parameter to the chart is the 0M i! of the !iv.
Another way to create a chart is to be !eclarative. 3ere we can useK
<di6 data-do.o-type01do.o*-chartig-"idget-Chart1
style01"idth: S>>p*2 height: S>>p*21
data-do.o-attach-poit01@chart1>
<-di6>
Page .9&
A chart ob6ect has three sets of primary attributesK
A plot
A<is
A series 8 the !ata to be !rawn
-ach of these must be a!!e! to a chart.
The Charting 'lot
The plot !escribes what kin! of chart shoul! be !rawn. To a!! a ?plot? to a chartB we callK
chart%addPlot3a,eC args42
The first parameter is the name of the plot an! becomes important if we wish to have multiple plots
on the same chart.
The secon! parameter !efines the core attributes of the plot. These attributes inclu!eK
type Q+tringR : The type of plot. This is the core style of the chart. The values are AreasB 2arsB
%lustere!2arsB %olumnsB @ri!B *inesB MarkersB Markers0nlyB PieB +catterB +tacke!B
+tacke!AreasB +tacke!2arsB +tacke!%olumnsB +tacke!*ines
Areas
2ars
Page .94
%lustere!2ars
%olumns
Page .9(
The AM packages %hart an! %olumns must be loa!e!. +pecial properties of this chart inclu!eK
gap 8 pi<els between columns
@ri!
*ines
Markers
Markers0nly
Pie
+catter
+tacke!
+tacke!Areas
Page .9/
+tacke!2ars
+tacke!%olumns
Page .19
+tacke!*ines
Pie chart
The !ata array supplie! to the series may be either an array of numbers or an array of ob6ects. 'f
ob6ectsB these containK
y 8 Calue
te<t 8 Te<t for the segment
color 8 %olor of the segment
others L
The AM packages %hart an! plot.HPie must be loa!e!
Properties by chart type
Page .11
@
a
p
l
i
n
e
s
a
r
e
a
s
m
a
r
k
e
r
s
t
e
n
s
i
o
n
s
h
a
!
o
w
s
h
A
<
i
s
H
v
A
<
i
s
Areas 5 5 5 5 5
2ars 5
%lustere!2ars 5
%olumns
@ri!
*ines 5 5 5 5 5
Markers 5 5 5 5 5
Markers0nly 5 5 5 5 5
Pie
+catter
+tacke!
+tacke!Areas 5 5 5 5 5
+tacke!2ars 5
+tacke!%olumns 5
+tacke!*ines 5 5 5 5 5
The Charting &7is
+imilar to addPlotB the chart has a metho! calle! addA*is that takes two parametersU a name
an! an arguments ob6ect. These !raw the a<is on the chartH
chart%addA*is3a,eC argu,ets4
e<amplesK
chart%addA*is31*142
chart%addA*is31y1C B6ertical: trueD42
The options for the A<is inclu!eK
vertical 8 +et to true if this !efines a vertical a<is
icludeWero 8 either true or false to inclu!e zero in the a<is
fi<*ower 8 efines where the ticks appear. %hoices areK
ma6or
minor
micro
none
fi<7pper
,a.or+abels 8 A boolean. 'f trueB ma6or*abels are shown.
Page .1.
,ior+abels 8 A boolean. 'f trueB minor*abels are shown.
,ior<icks 8 A boolean. 'f trueB minorTicks are shown.
,icro<icks 8 A boolean. 'f trueB microTicks are shown.
,a.or<ick#tep 8 A number. The !elta between ma6or ticks.
,ior<ick#tep 8 A number. The !elta between minor ticks.
,icro<ick#tep 8 A number. The !elta between micro ticks.
rotatio 8 An angle in !egrees with which to rotate the label. A positive number is
clockwiseB a negative number is anti:clockwise.
natural
fi<e!
left2ottom
labels 8 an array of ob6ects of the form
6alue 8 The value of the column in the G a<is. >or e<ample 1 is the 1
st
columnB . is
the .
n!
column etc.
te*t 8 The te<t to show for the column
The Charting eries
>inallyB there is the add#eries34 metho!. This is where !ata is a!!e! to the chart. The
add#eries takes three parameters
chart%add#eries3a,eC array o$ dataC argu,ets4
The arguments for a series inclu!eK
$ill 8 The color to be use! to fill the !ata
stroke 8 The bor!er of the !ata
1endering the chart
>inally there is the reder34 function which causes the chart to be ren!ere!. A metho! calle!
resizeAD is available to resize the chart. This metho! has two formatsK
resizeAEwK QnumRB hK QnumRFD
resizeAwB hD
+ee alsoK
sitepen : ive 'nto o6o %harting Again : .91.:9/:13
sitepen : ive 'nto o6o %hart Theming : .91.:11:9/
sitepen : 'ntro!ucing o6oG ata%hart : .99/:93:39
sitepen : A 2eginner]s @ui!e to o6o %hartingB Part 1 of . 8 .99(:9&:9&
sitepen : A 2eginner]s @ui!e to o6o %hartingB Part . of . 8 .99(:9&:1&
sitepen : o6o %hartingK Actions an! Tooltips 8 .91.:11:9/
sitepen : o6o %hartingK -vent +upport 3as *an!e!O : .99(:9#:.4
Page .13
sitepen : PoomingB +crollingB an! Panning in o6o %harting 8 .99(:9#:1#
o6o ocs 8 !o6o<.charting
o6o tests 8 %harts
eveloper "orks 8 %ustomizing charts using o6o 8 .919:11:1&
eveloper "orks : %reate !ynamic graphs an! charts using o6o : .919:11:9.
Do-o Charting and Themes
The theme of a chart can be set with the ?setThemeAD? metho!. This takes as a parameter the ob6ect
representing the theme. A bunch of themes are pre:provi!e! by o6o.
+ee alsoK
sitepen : ive 'nto o6o %hart Theming 8 .91.:11:9/
Theme Tester 8 1.(
Do)o 3auges + do)o54dgauges
o6o provi!es an e<tremely powerful set of gauges via the ?do.o*-dgauge? package.
This packages provi!es three primary styles of gauges. These are ?%ircular? where the gauge is a
circleB ?+emi %ircular? where the gauge is a semi:circle an! ?$ectangular? where the gauge is a
rectangle.
The do.o*-dgauges package is super rich in function. This can make it !ifficult to use.
>ortunatelyB sets of pre!efine! gauges have been provi!e! that have been pre:style! an! are rea!y
to use.
These come in the following categoriesK
!efault
black
classic
grey
green
"ithin each of these stylingsB there are four pre:!efine! gauge styles. These areK
%ircular*inear@auge
+emi%ircular*inear@auge
3orizontal*inear@auge
Certical*inear@auge
-ach gauge contains ?elements? inclu!ingK
scale
3orizontal an! Certical gauges are broken into three partsK
Page .11
The gauges have common properties that !efine their operation. 3ere is a list of some of the most
important onesK
6alue 8 The value of the marker in the gauge.
,ii,u, 8 The lowest value in gauge.
,a*i,u, 8 The highest value in the gauge.
,a.or<ickIter6al 8 The value between ma6or ticks.
,ior<ickIter6al 8 The value between minor ticks.
,ior<icks(abled 8 +et to true to show minor ticks an! false to hi!e.
iteractioArea 8 A set of possible ways that a user can !irectly interact with the
guage. Possible values areK
none
in!icator
guage
area
ai,atioEuratio 8 3ow long Ain millisecon!sD the animation shoul! play when the
value changes. +etting a value of 9 !isables.
style 8 +ets the %++ style properties. This inclu!es wi!th an! height to set the size of the
gauge.
@auges can have elements on them. These inclu!e te<tB scales an! others. "e can a!! an element
with the ?add(le,et3a,eC ele,et4? metho!B retrieve an e<isting element with the
?get(le,et3a,e4? metho! an! remove e<isting elements with the
?re,o6e(le,et3a,e4? metho!.
NotesK
't seems that when creating a gaugeB it must be attache! to a !ocument 0M no!e when it
is create!. The gauge appears to claim the 0M as its own. As suchB take care when
attaching it to a container as the !eletion of the gauge will !elete the container. Putting it
another wayB it appears that the creation of a gauge claims the no!e to which it is attache! as
its own no!e.
"hen creating a circular gauge in a %ontentPaneB it seems that we nee! to a!! the gauge to
a Q!ivR that is 1 pi<els smaller in height than the content pane itself. "hy this shoul! be is
unknown but if we !onMtB then scrollbars appear. The following co!e shows us an e<ampleK
6ar si)e 0 do,?eo,%getMargiBo*3,yCotetPae%do,!ode42
6ar ode 0 do,Costruct%create31di61C Bstyle: 1height: 1 K 3si)e%h-S4 K 1p*2 "idth: 1 K si)e%" K
1p*21D42
,yCotetPae%set3ode42
6ar gauge 0 e" Circular+iear?auge3B%%%DC ode42
Page .1#
AnotherB perhaps simpler solution is to hi!e the scrollbars with the styleK
o6er$lo"-*: hidde2 o6er$lo"-y: hidde2
't is possible to remove the !efault ?lea!ing? section from a 3orizontal or Certical gauge
using the following recipesK
gauge%re,o6e(le,et31idicator<e*t142
gauge%re,o6e(le,et31idicator<e*tBorder142
Not all !efault gauges behave )uite the same.
+cale font sizeK
3orizontal 8 gauge _ font.size
+emi%ircular 8 gauge scale element _ font.size
+ee alsoK
o6o $eference 8 !o6o<H!gauges 8 1./
emos of the !o6o<H!gauges
!eveloper"orks : %reating 2ullet @raphs in o6o with the gauges package 8 .91.:9(:.3
Creating custom gauges
The o6o supplie! gauges are goo! but we can go much further. "e can create our own styles of
gauges. To !o thisB we must first look at two base classes calle! ?Circular?auge? an!
?7ectagular?auge?. -ach gauge is compose! of a series of parts that nee! to be e<plore!.
These inclu!eK
@>G !ecorations
Te<t in!icators
+cales
+cales hol! value or range in!icators that can be a!!e! to the scale using the a!!-lementAD metho!.
A scale ob6ect is responsible for !rawing tick marks an! labels. 't has two functions on it that are
calle! to !raw the appropriate itemsK
scale%tick#hape5uc 0 $uctio3groupC scaleC tick4 BVD
scale%tick+abel5uc 0 $uctio3tick4 BVD
Associate! with a gauge are value an! range in!icators. A value in!icator is responsible for
showing a marker in the gauge. Think of it as nee!le in a circular gauge or the thumb in a
rectangular gauge. A range in!icator is use! to show a ?range?.
The above range was a!!e! withK
6ar ri 0 e" Circular7ageIdicator342
Page .1&
ri%set31start1C L>42
ri%set316alue1C S>42
ri%set31radius1C H>42
this%gauge%get(le,et31scale14%addIdicator31ri1C riC $alse42
Multiple ranges can be a!!e! as !esire!.
The Circular7ageIdicator contains a number of properties inclu!ingK
start 8 The start value of the range in!icator.
6alue 8 The en! value of the range in!icator
radius 8 The outer position of the range in!icator in pi<els.
start<hickess 8 The start thickness of the in!icator in pi<els. Thickness moves the
!onut circle towar!s the center.
ed<hickess 8 The en! thickness of the in!icator in pi<els
$ill 8 A @>G fill ob6ect that is passe! to the set5ill34 metho! of @>G. >or e<ampleB
an $@2 color value such as ?ZSSGGII?.
stroke 8 A @>G stroke ob6ect that is passe! to the set#troke34 metho! of @>G.
A Circular:alueIdicator contains a number of properties inclu!ingK
6alue 8 The position of the in!icator.
't also has a callback function calle! ?idicator#hape5uc? which is calle! to !raw the
in!icator at the value. 't is passe! two parameters which areK
group 8 The @>G group
idicator 8 The in!icator ob6ect
The !efault in!icator is a simple lineK
To create our own in!icator styleB we use the @>G ?group? parameter to !raw our own shape
complete with fill an! stroke. -<perimentation shows that we shoul! use a virtual coor!inate
system with the following conceptsK
The origin is at 9B9 an! will be the center of the gauge.
The positive G:A<is is ?outwar!s? from the origin towar!s the in!icator value.
The following is an e<ample of a custom in!icatorK
6i%idicator#hape5uc 0 $uctio3groupC idicator4 B
retur group%createPolylie3Q'>C -LC HIC -LC HIC LC '>C LC '>C -LR4%set#troke3B
color: 1blue1C
"idth: >%I'
D4%set5ill3QL>>C L>>C I''C LR42
D2
Page .14
'n a!!ition to the value an! range in!icatorsB we also have the notion of a te<t in!icator. This is
responsible for showing a piece of te<t in the gauge. This can be static or !ynamically up!ate!
base! on the value or range. *ike the other componentsB a Te<t'n!icator can be a!!e! to a gauge
using the a!!-lementAD metho!.
Among the properties of the Te<t'n!icator areK
value : The te<t to be shown to the user.
align 8 3ow the te<t is aligne!. 0ptions areK
start
mi!!le
en!
color 8 The color of the te<t.
font 8 The font of the te<t.
label>unc 8 A function use! to !etermine the value of the te<t.
< 8 The ?<? origin.
y 8 The ?y? origin.
Sample custom circular guage
"e base our new wi!get upon do.o*-dguages-Circular?uage.
Ne<t we a!! elements to our gauge which can be %ircular+caleB Te<t'n!icator or a !rawing
function.
Sample custom rectangular guage
"e base our new wi!get upon do.o*-dguages-7ectagular?uage.
Do)o 306
@>G is a vector !rawing package for o6o.
The surface is the primary !rawing area. 'ts size is !efine! when create! but can later be change!
with the setEi,esios3"idthC height4 metho!.
Metho! Properties
create7ect
<B yB wi!thB heightB r
createCircle
c<B cyB r
create(llipse
c<B cyB r<B ry
create+ie
<1By1B<.By.
createPolylie
points
createPath
path
createI,age
<B yB wi!thB heightB src
create<e*t
<B yB te<tB alignB !ecorationB rotate!B kerning
create<e*tPath
pathB te<tB alignB !ecorationB rotate! kerning
Page .1(
+ee alsoK
o6o @>G !ocumentation 8 1./
Cector graphics with o6oMs @>G
ive 'nto o6o @>G
Do-o 96: 8ector 6onts
Cector fonts are fully scalable te<t items. To useB we nee! to re)uire ?!o6o<Hgf<HCectorTe<t?.
>irst we create an +C@ font !efinition. After the font !efinition has been create! we loa! the font.
A font calle! ??illius%s6g? is available in the ?do.o*-g$*-resources? fol!er.
6ar url 0 reFuire%to8rl31do.o*-g$*-resources-?illius%s6g142
6ar $ot 0 g$*%:ector5ot3url42
6ar t*tArgs 0 B
te*t: 1!o" is the ti,e $or all good ,e to co,e to a rest% PlusC the rai i #pai $alls ,aily
o the plaiP1C
*: >C y: >C
"idth: L>>C height: L>>C
alig: 1start1C
$ittig: do.o*%g$*%6ector5ot5ittig%5+/WC
leadig: L%I
D2
6ar $otArgs 0 B
si)e: 1LIpt1C $a,ily: 1?illius1
D2
6ar ,aster 0 sur$ace%create?roup342
6ar g 0 $ot%dra"3,asterC t*tArgsC $otArgsC 1ZaGHeIc142
The t<tArgs parameter of the !raw metho! contains the followingK
$ittigK 0ne of either >*0"B >'T or N0N-. 'f >'T is supplie!B this causes the te<t to fit
as best it can the group area an! hence the font size is ignore!.
+ee alsoK
%ustom fonts with !o6o<.gf<
Do)o and C!!
+ome of the i6it wi!gets supplie! with o6o provi!e their own %++ files. 'n a!!itionB any custom
wi!gets you buil! may also re)uire their own %++. Normally we inclu!e these %++ files with the
QlinkR attributeB however there are circumstances where we might not be able to !o that.
'magine that we have written a o6o wi!get that runs in a o6o environment framework we have no
control over. "e simply !onMt know the root 7$* for o6o an! hence !onMt know what to inclu!e
in our 3TM*.
0ne possible solution is to have our %++ loa!e! by knowing which mo!uleHpackage it is in. 3ere is
an e<ample fragment of co!e which will !o 6ust thatK
$uctio isertModuleC##3,oduleC##Path4 B
-- +ocate the docu,etOs <head> ode
6ar head!ode 0 Fuery31head14Q>R2
-- ?et the 87+ to the C## $ile
6ar path 0 reFuire%to8rl3,oduleC##Path42
-- Check to see i$ the <lik> already e*ists% I$ it doesC there is othig
Page .1/
-- $or us to do%
6ar e*ists 0 Fuery31likQhre$0O1 K path K 1OR1C head!ode42
i$ 3e*ists%legth > >4 B
retur2
D
-- Create the lik ad add it to the Web page%
do,Costruct%create31lik1C B
1rel1: 1stylesheet1C
1type1: 1te*t-css1C
1hre$1: path
DC head!odeC 1last142
D -- (d o$ isertModuleC##
what it !oes is take the mo!ule path to a %++ file an! convert that to a 7$* path. "e then look
within the <head> of our current !ocument to see if we have a <lik> that alrea!y loa!s this
entry. 'f we !onMt then we a!! a <lik> to loa! it.
Do)o De$elopment .ith IID
'' can be use! to !evelop o6o base! applications. 't provi!es an A6a< server that provi!es real:
time access to changes ma!e in scripts an! 3TM*. "hat this means is that a change in a source
file !oes not nee! to go through a !eployment step to test it out. This is in:line with ;ava+cript an!
o6o programming styles an! techni)ues.
To !eploy an application to the A6a< server we nee! to create a ?+tatic "eb Pro6ect?. This is as
oppose! to a ?ynamic "eb Pro6ect? which is really a ;ava -- "A$ file.
"hen it comes time to !eploy a pro6ect to a "A+ server for e<ecutionB we nee! to create a
ynamic "eb Pro6ect but this then poses a challenge. The !ynamic web pro6ect an! the static web
pro6ect appear to have !istinct source trees an! hence keeping the two pro6ects in synch can be an
issue. 0ne solution is to choose one pro6ect an! then create a "in!ows level har!:link at the file
system level linking together the two file trees.
'magine we have a !irectory calle!K
C:\My7oot\Eya,icPro.ect\WebCotet\My#ource
in which the source of our work is kept.
Now imagine we have a !irectory calle!K
C:\My7oot\#taticWebPro.ect\WebCotet
we want this to also contain the source as it is to be use! by the +tatic "eb pro6ect.
The "in!ows ?,klik? comman! can be use!K
,klik -J C:\My7oot\#taticWebPro.ect\WebCotet\My#ource
C:\My7oot\Eya,icPro.ect\WebCotet\My#ource
NotesK
Make sure that if there are spaces in the !irectory names then the !irectory is surroun!e! by
)uotes.
The first parameter is the !irectory to be create! while the secon! is the link source.
Ne<tB issue a refresh in the '' -clipse framework of the file system structure an! now we have
both pro6ects sharing the same source tree. An e!it to a file in one pro6ect will e!it the same file in
the other pro6ect Athey are the same fileD. 't is recommen!e! to take backups 6ust in case you make
a mistake.
&dding the Do-o 'ro-ect 6acet
>rom the pro6ect propertiesB we can a!! the o6o factetK
Page ..9
'n the further configuration tabB we can !efine where we get our o6o fromK
'f we select a public %N A%ontent elivery NetworkDB we get further options. "e can use
@oogleMs AP' librariesK
httpsKHH!evelopers.google.comHspee!HlibrariesH!evgui!e
"e also nee! to !ownloa! an! e<tract the source of the correspon!ing o6o buil!. "e can get
those from hereK
Page ..1
httpKHH!ownloa!.!o6otoolkit.orgH
#sing the Web 'revie% erver runtime
The '' "eb Preview +erver run:time can be thought of as a non:pro!uction "eb +erver capable
of hosting web pages an! scripts. This was previously calle! the ?A;AG Test +erver? in ol!er
releases. An instance of a "eb Preview +erver can be !efine! as a new +erver Type in ''K
Page ...
't is ?tie! in? to the '' environment an! is manageable from within ''. 0ne of the key features
that it provi!es is the notion of pro<ying re)uests. "hen a browser application runsB it is
constraine! to communicate via $-+T back to the server which supplie! the 3TM* in the first
place. This is known as the +ame 0rigin Policy A+0PD. "hen !evelopingB this can be a problem as
we often wish to make $-+T re)uests to our '2M 2PM server which L is not the same server as
the "eb Preview +erver run:time. +0P re)uires that the target of a $-+T re)uest be the same host
an! port number.
0ne solution to this !evelopment problem is the notion of a pro<y. 3ereB the $-+T re)uest is sent
to the "eb Preview +erver run:time an! it is the "eb Preview +erver run:time that sen!s the
re)uest to the target $-+T provi!er. A response from the $-+T provi!er is route! back through
the "eb Preview +erver an! finally to the browser application. This circumvents the +0P as from
the browserMs perspectiveB the $-+T re)uest was sent to the same server that serve! up the 3TM*
in the first place Ai.e. the "eb Preview +erverD.
"hen we open the properties of the "eb Preview +erver !efinitionB we are show the followingK
Page ..3
%licking the ?Co$igure Pro*y 87+s? link takes us to the pro<y e!itorK
>rom here we can !efine pro<y !efinitions. A pro<y !efinition is !efine! in two parts. The first is
the ?conte<t path? which is the path that the browser wishes to logically reach. The secon! is the
pro<ie! 7$* which is the actual !estination that will be targete!.
Pro<ies are !etecte! by a prefi< of ?-pro*y?.
3ere is an e<ample. 'magine we have a $-+T provi!er locate! atK
http:--,yser6er%co,-,y7est-,y7eFuest
"e can make a pro<y !efinition that saysK
1-,y7est-Y1 is ,apped to 1http:--,yser6er%co,-,y7est1
'f a re)uest is then ma!e to the A6a< server atK
-pro*y-,y7est-,y7eFuest
then the "eb Preview +erver will route this toK
http:--,yser6er%co,-,y7est-,y7eFuest
Page ..1
3ere are some common settings when working with '2M 2PMK
%onte-t path /arget
HteamworksHT httpKHHlocalhostK/9(9Hteamworks
NoteK as of (.#B o6o root can be foun! atK
-tea,"orks-script-coach!?-do.o-L%=%G-
+ee alsoK
httpKHHwpcertification.blogspot.comH.99/H93Ha6a<:pro<y:file:configuration.html
Do)o De$elopment .ith Microsoft II! #5press
There are times when a local "eb +erver can be useful. MicrosoftMs ''+ is a potential can!i!ateK
'f you alrea!y have Microsoft Cisual +tu!io .919 -<press installe!B ''+ is alrea!y present.
Microsoft Cisual +tu!io .919 can be instructe! to use ''+ from the applicationMs properties panelK
Page ..#
#sing a ource Do-o %ith II
To use this with o6oB consi!er the followingK
ownloa! a source !istribution of o6o. The 7$* for the !ownloa! isK
httpKHH!o6otoolkit.orgH!ownloa!H
-<tract this to some !irectory eg. C:\Eo.o#ource
NowB assuming you are running Microsoft Cisual "eb eveloperB you will alrea!y have ''+
installe!. The configuration file for this ''+ will beK
C:\8sers\<8serId>\Eocu,ets\II#(*press\co$ig\applicatiohost%co$ig
"ithin this file a!! a new virtualirectory entry atK
<syste,%applicatioHost>
<sites>
<site a,e01WebApplicatioL1>
<applicatio %%%>
<6irtualEirectory path01-do.o7oot1 physicalPath01C:\Eo.o#ource1 ->
This will make the o6o !istribution available from the 7$* ?-do.o7oot?.
Page ..&
Do)o Mobile
o6o provi!es a package specifically !esigne! for buil!ing mobile apps. This package is calle!
?do.o*-,obile?. This package provi!es wi!gets an! architecture for buil!ing applications that
are hoste! in browser frameworks but will look an! behave as though they were implemente!
natively in mobile platform.
*ike other o6o technologiesB the wi!gets can be !eclare! programatically in ;ava+cript or
!eclaratively in 3TM*.
't appears that the o6o Mobile packageB although sharing the same architecture as the rest of o6o
is actually a separate implementation an! seems to rely very little Aif at allD on the other aspects of
o6o. The !esign notes suggest that the o6o Mobile has a very small an! efficient footprint
tra!ing off function for spee! an! efficiency in the mobile space.
+ee alsoK
+howcase 8 An!roi!
+howcase 8 iPhone
@etting +tarte! with !o6o<Hmobile 8 .913
eveloper"orks : Ma)etta means mockupB Part 1K esign an 3TM*# mobile 7' : .913:91:91
eveloper"orks : "hatMs new in o6o Mobile 1.(B Part 1K New wi!gets 8 .91.:11:1/
eveloper"orks : "hatMs new in o6o Mobile 1.(B Part .K New enhancements 8 .91.:11:1/
eveloper"orks : "hatMs new in o6o Mobile 1.(B Part 3K ata:han!ler enhancements 8 .91.:11:1/
!eveloper"orks 8 Pull !own to refresh with o6o Mobile : .913:11:13
eveloper"orks : evelop lightweight mobile web applications with o6o Mobile 8 .911:1.:13
!eveloper"orks 8 @et starte! with o6o Mobile 1.4 8 .913:9(:.3
!eveloper"orks 8 @et starte! with o6o Mobile 1.& 8 .913:9&:14
imple Do-o: Mobile app
3ere is a pretty minimal o6oG Mobile appK
<PE/C<NP( H<M+>
<ht,l style01height: L>>X21>
<head>
<title>Maager 7e6ie"<-title>
<,eta http-eFui601Cotet-<ype1 cotet01te*t-ht,l2 charset0I#/-=='U-L1>
<script type01te*t-.a6ascript1
src01http:--a.a*%googleapis%co,-a.a*-libs-do.o-L%U%G-do.o*-,obile-de6ice<he,e%.s1><-script>
<script type01te*t-.a6ascript1 data-do.o-co$ig01isEebug: $alseC asyc: trueC parse/+oad: true1
src01http:--a.a*%googleapis%co,-a.a*-libs-do.o-L%U%G-do.o-do.o%.s1><-script>
<script type01te*t-.a6ascript1>
reFuire3
-- #et o$ ,odule ideti$iers
Q 1do.o1C 1do.o-parser1C 1do.o*-,obile-#crollable:ie"1 RC
-- Callback $uctioC i6oked o depedecies e6aluatio results
$uctio3do.o4 B
do.o%ready3$uctio34 B
D42
D42
<-script>
<-head>
<body>
<di6 data-do.o-type01do.o*-,obile-#crollable:ie"1>
<di6 data-do.o-type01do.o*-,obile-Headig1>Maager 7e6ie"<-di6>
<-di6>
<-body>
<-ht,l>
Page ..4
Do-o Mobile Themes
An application running on An!roi! nee!nMt Aan! probably shoul!nMtD look e<actly the same as the
same application running on i0+. 2oth operating systems provi!e native ?look an! feels? which a
user has come to e<pect to see when working with an application on a particular 0+. o6o Mobile
provi!es the capability for the same !evelope! application to appearHlook like a ?native?
application. To !o thisB it nee!s to change the appearance of the wi!gets !epen!ing on whether
they are running on one 0+ or another. This concept is generally terme! ?themeing?. o6o
supplies themes for An!roi! an! i0+.
The 8ie% Model
"hen we work with applications in the !esktop environmentB we are familiar with the notion of
new win!ows appearing as we navigate from one part of an application to another. 'n the mobile
platformB this may not be possible because of limite! screen space an!B even when screen space is
availableB the notion of a ?win!ow? is alien.
The architecture of o6o Mobile is that we have ?views? which correspon! to a full screen of !ata.
"hen a o6o view is a!!e! it consumes all the available space. A page can have multiple views
but only one view is ever visible at a time. "hat we wish to !o is to present a view an! then allow
the user to navigate between the views.
There are a number of types of views available inclu!ingK
!o6o<HmobileHCiew
!o6o<HmobileH+crollableCiew
!o6o<HmobileH+wapCiew
"hen a view is shown or hi!!enB a set of events are fire! associate! with that view. "e can
register callback functions that can !o work base! on these events. These callbacks can up!ate the
!ata in the views or other tasks in or!er to prepare the !ata for visualization or save !ata that was
previously entere!.
"e can register these with the o6o ?o? function which takes the formatK
o3"idgetC e6etC $uctio4
for e<ampleK
o3,y:ie"C 1be$oretrasitioi1C $uctio3%%%4 B V D42
The events which can be connecte! areK
on+tartCiew 8 %alle! when the view is !efault
on2eforeTransition'n
onAfterTransition'n
on2eforeTransition0ut
onAfterTransition0ut
Note for use with the o6o ?on? functionB the event names have the ?on? prefi< remove! an! are
lower:case!.
Ciews provi!e an e<plicitly callable metho! name! ?per$or,<rasitio34? which performs
a view switch from one view to another. The parameters to this metho! areK
,o6e<o 8 The name of the view that will be newly shown
Page ..(
trasitioEir 8 A value of 1 means transition forwar! an! a value of :1 means
transition backwar!s
trasitio 8 The type of transition animation L for e<ample ?sli!e?.
cote*t 8 The value that a callback function will receive as ?this?
,ethod 8 A function that will be calle! when the transition completes
A set of other wi!gets in the o6o mobile package have knowle!ge of views. They provi!e
capabilities for view transitions. +ome of these wi!gets inclu!eK
!o6o<HmobileH3ea!ing
!o6o<HmobileH'con'tem
!o6o<HmobileH'conMenu'tem
!o6o<HmobileH*ist'tem
!o6o<HmobileHTab2ar2utton
%ommon among these wi!gets are the following view relate! propertiesK
,o6e<o 8 The name of a view which will be shown upon interaction with the wi!get.
't is very common to a!! a hea!er to the top of the view. This can be achieve! using the
do.o*-,obile-Headig wi!get.
+ee alsoK
!o6o<HmobileHCiew
!o6o<HmobileH+crollableCiew
!o6o<HmobileHTreeCiew
!o6o<HmobileH+wapCiew
*istening to Transition -vents 8 1./
do'ox8mo"ile8.iew
The do.o*-,obile-:ie" is the basic Ciew container. 't can hol! other wi!gets or 3TM*.
+ome of its key properties inclu!eK
id 8 The i!entity of the view.
selected 8 True if this is the view to be shown at startup.
'f more content is a!!e! to the view than will fit in the win!ow areaB the Ciew will scroll natively
base! on browser ability.
'n the following screen shot we see a single Ciew which contains a 3ea!er an! some list content.
Notice that since the list content is taller than the browsing areaB a scrollbar has been a!!e!. This
scrollbar has been a!!e! by the browser.
Page ../
do'ox8mo"ile8Scrolla"le.iew
The do.o*-,obile-#crollable:ie" is also a Ciew container but unlike the simple
do.o*-,obile-:ie" it han!les scrolling abilities without employing the native browser
capabilities an! hence can emulate platform scrolling look an! feel.
The following is the same win!ow as shown previously but this time the content is wrappe! in a
do.o*-,obile-#crollable:ie". "e imme!iately notice the lack of a scrollbar. This is a
!eliberate 7' choice. +crolling is still possibleB but instea! of using the browser abilitiesB touch
operates as well as the look an! feel e<pecte!.
Page .39
'ts key characteristics areK
id 8 The i!entity of the view.
selected 8 True if this is the view to be shown at startup.
do'ox8mo"ile8Tree.iew
This wi!get provi!es a ?tree? like navigation between views. 't is currently Aas of 1./D consi!ere!
e<perimental.
do'ox8mo"ile8Swap.iew
This wi!get container is another instance of Ciew container. 't respon!s to horizontal swipes to
navigate to the ne<t or previous instance of a +wapCiew.
Working %ith Do-o Mobile Lists
A couple of wi!gets provi!es lists. These lists are basically sets of items wrappe! up within a list
container. There are basically two types of container. The first is an ?e!ge to e!ge? container
where the list items stretch from the left e!ge of the container all the way to the right e!ge. The
secon! type of container is calle! the ?roun!e! rectangle? container. "ith this containerB the items
in the list are containe! within a ?roun!e!? rectangle style bo<.
"e can !efine what kin! of selection the list shoul! allow. 'f not setB no selecte! in!ication is
shown. 0ther choices inclu!e ?single? an! ?multiple?.
"hen a list container has been create!B we can a!! list items to it. This can be achieve! manually
or else using a o6o +tore mechanism.
The list containers are interesting but probably the most interesting items are the entries that can be
inserte! into them. o6o provi!es an ob6ect calle! the do.o*-,obile-+istIte, that
Page .31
represents an item in the list. 't has a set of visual parameters that are use! to set its styleK
icon
label
rightTe<t
right'con.
right'con
"hen the item is clicke!B we have some choices as to what will happen. 'f the item has a
?,o6e<o? property set then there will be a view transition to the view name! in that property.
'n a!!itionB an event calle! ?oClick34? is fire! when the item is clicke!. This event is only
fire! if either the +istIte, has its ?clickable? property set to true or has a view !efine! as a
move target.
To a!! +istIte,s into the list we can use the list containerMs ?addChild34? metho!.
Above a listB a hea!ing can be inserte!. There are two o6o mobile wi!gets available for thisB one
which styles hea!ings for e!ge to e!ge lists Ado.o*-,obile-(dge<o(dgeCategoryD an!
another for roun!e! rectangle style lists Ado.o*-,obile-7ouded7ectCategoryD.
+ee alsoK
!o6o<HmobileH-!geTo-!ge*ist
!o6o<HmobileH-!geTo-!ge+tore*ist
!o6o<HmobileH$oun!$ect*ist
!o6o<HmobileH$oun!$ect+tore*ist
!o6o<HmobileH*ist'tem
!o6o<HmobileH-!geTo-!ge%ategory
!o6o<HmobileH$oun!$ect%ategory
The Do-o Mobile %idgets
o6o Mobile provi!es a rich set of pre:built wi!gets. The following is summary information on
most of them with notes about each. This shoul! not be consi!ere! by any stretch of the
imagination a replacement for the formal !ocumentation. There is both programmer gui!e an!
reference information available which is far more accurate an! comprehensive. 't shoul! always be
consulte! if there is ambiguity.
+ee alsoK
o6o Mobile Programmers @ui!e 8 1./
o6o AP' $eference
do'ox8mo"ile8Accordion
This wi!get acts as a container for other wi!gets. 't !isplays a set of panes. The label of a pane is
always shown as a hea!er but its bo!y can be open or close! either showing or hi!ing its content.
%ommonlyB the contents of the Accor!ion are instances of the do.o*-,obile-PaeB
do.o*-,obile-Cotaier or do.o*-,obile-CotetPae. Always set the ?label?
property of the chil! container so that the Accor!ion will have something to !isplay to allow the
user to open an! close the entry.
Page .3.
A close! paneMs hea!er has a visually !istinctive look than that of an open pane.
'f a close! pane is opene!B all the panes beneath it are pushe! lower !own in the page. %onverselyB
if a pane is close!B all the panes south of it will sli!e up. >or the chil! panesB if they have an
attribute! calle! ?selecte!? set to trueB then when the Accor!ion is initially shownB they will initially
be open.
An alternative move of operation of the Accor!ion forces it to have only one chil! pane open at a
time. This is controlle! by the ?sigle/pe? attribute. 'f set to true A!efault is falseD then the
opening of one pane will close all the others.
+ome of the key properties of this wi!get areK
sigle/pe 8 A boolean with a !efault of false. 'f set to trueB opening one pane causes
the closure of all the others.
$i*edHeight 8 'f set to trueB the Accor!ion has a fi<e! height. 'f this property is use!B
set the height of the Accor!ion through its style attribute AheightD.
ai,atio 8 'f set to true A!efaultDB animation will be use! to sli!e other panes aroun!.
The Accor!ion seems to have !isplay problems within the $ich Page -!itor. %hil!
panes !onMt seem to be e!itable or visual within the visual canvas area an! have to be e!ite! at the
3TM* source level.
+ee alsoK
!o6o<HmobileH%ontentPane
!o6o<HmobileHPane
do'ox8mo"ile8#utton
This wi!get !isplays a click:able button. +ome of its core properties of interest inclu!eK
label 8 The label to be shown on the button. 'f !efine! in 3TM*B the te<t element chil!
of the containing element can be use!.
oClick 8 A function callback that will be invoke! when the button is presse!.
+ee alsoK
!o6o<HmobileH%heck2o<
do'ox8mo"ile8Chec0#ox
This wi!get !isplay a check bo< which can be either checke! or not checke!. The check bo< !oes
Page .33
not have a label but normal 3TM* can a!!e! before or after it to a!! one.
+ome of the key properties of this wi!get inclu!eK
checked 8 The current checke! state of the bo<.
The wi!get can publish events which can be han!le!K
oChage 8 %alle! when the bo< changes state. The new checke! state is passe! as a
parameter to the event.
+ee alsoK
!o6o<HmobileH2utton
!o6o<HmobileH$a!io2utton
!o6o<HmobileH+witch
!o6o<HmobileHToggle2utton
do'ox8mo"ile8Com"o#ox
This wi!get provi!es the ability to select a pull:!own of available items one of which can be
selecte!. 'n a!!itionB it also allows for manual input of !ata. As !ata is entere!B it is compare!
against pre:supplie! possibilities to provi!e an entry assist capability. 't is vital to realize that the
value returne! from this wi!get nee! not be one of the pre:supplie! values. Any value entere! by
the user will be allowe!.
The values pre:!efine! for the wi!get can come from a variety of places inclu!ing a o6o store
ob6ect. 'n a!!ition to the o6o storeB the di.it-$or,-Eata+ist store ma!e from QoptionR
tags can be use!.
+ome of the key properties of this wi!get inclu!eK
store 8 A !o6o store that contains the values.
list 8 A di.it-$or,-Eata+ist that contains the values to use.
tri, 8 $emoves spaces from the start an! en! of the entere! te<t.
uppercase 8 %onvert any entere! te<t to upper case.
lo"ercase 8 %onvert any entere! te<t to lower case.
propercase 8 %onvert any entere! te<t to ?propercase?.
+ee alsoK
do'ox8mo"ile8Container
This wi!get is simply an 3TM* <di6> element wrapper. 't can be use! as a container for a
Page .31
variety of other wi!gets such as Accor!ionB >i<e!+plitter an! @ri!*ayout.
+ee alsoK
!o6o<HmobileHAccor!ion
do'ox8mo"ile8ContentPane
This wi!get acts a container for another source of 3TM* which can be !ynamically loa!e!.
+ome of the key properties of this wi!get areK
hre$ 8 The 7$* of the 3TM* to be loa!e!.
cotet 8 A specific piece of 3TM* to be loa!e!.
+ee alsoK
!o6o<HmobileHPane
do'ox8mo"ile8EdgeToEdgeCategor1
The do.o*-,obile-(dge<o(dgeCategory provi!es a label that is !esigne! to appear
imme!iately before an (dge<o(dge+ist.
The ?label? property is use! to supply the label shown on the category.
+ee alsoK
!o6o<HmobileH-!geTo-!ge*ist
do'ox8mo"ile8EdgeToEdgeList
This wi!get presents a list of items where each item occupies the wi!th of the available area. -ach
item in the list is e<pecte! to be an instance of a !o6o<HmobileH*ist'tem.
Among the interesting properties of this wi!get areK
select 8 "hat kin! of selection the list supports. %hoices inclu!e ?single? an! ?multiple?.
+ee alsoK
"orking with o6o Mobile *ists
!o6o<HmobileH*ist'tem
Page .3#
!o6o<HmobileH$oun!$ect*ist
!o6o<HmobileH-!geTo-!ge%ategory
do'ox8mo"ile8EdgeToEdgeStoreList
This wi!get provi!es a list whose content is !etermine! from a o6o +tore.
"e can !ynamically set the +tore use! by the list using the set#tore34 metho!.
This wi!get has a property calle! ?ite,Map? which appears to be )uite unusual from a
o6oH;ava+cript perspective. 't is an 0b6ect with the property names being properties in the +tore
an! the values of those properties being the properties on a +istIte, that we wish to set.
>or e<ampleB we see that +istIte, has a property calle! ?label? use! to set the label of list
item. 'f we wish to have the +tore !ata property calle! ?co,pay!a,e? be the value of the label
in a list itemB we woul! !eclareK
ite,Map: B
co,pay!a,e: 1label1
D2
This is potentially confusing to many o6o users as we are more use! to structures which set the
property we wish to set to the value. >or e<ampleK
ite,Map: B
label: 1co,pay!a,e1
D2
0ne interesting thing to note is that the ite,Map is not constraine! to supply !ata properties for
!isplay. "e can also use it to set arbitrary properties on a list item. >or e<ampleB to register a
function to be calle! when a list item is clicke!B we can !eclareK
ite,Map: B
dataIte,Click: 1oClick1
D
Then it is assume! that the !ata of the store will contain a property calle! ?dataIte,/Click?
which will be a function which will be invoke! when the list item is clicke!.
+ee alsoK
0b6ect +tores an! ata +tores
"orking with o6o Mobile *ists
do'ox8mo"ile8ExpandingTextArea
This wi!get provi!es an input te<t area into which free form te<t may be entere!. The area can
e<pan! as more !ata is entere! or it can be !ragge! to a specific size.
+ome of the key properties of this wi!get inclu!eK
6alue 8 The value of the te<t containe! within
,a*+egth 8 The ma<imum length of te<t Ain charactersD that can be entere!.
Page .3&
do'ox8mo"ile89ixedSplitter
This wi!get is a container that shows its chil!ren si!e by si!e. The chil!ren can be lai! out either
horizontally or vertically. The chil!ren of >i<e!+plitter are e<pecte! to be either
do.o*-,obile-CotaierB do.o*-,obile-Pae or do.o*-,obile-CotetPae
instances. The choice of which type of container to use is governe! byK
do.o*-,obile-Cotaier 8 %hil!ren of the container are only o6o wi!gets.
do.o*-,obile-Pae 8 %hil!ren of the container are either o6o wi!gets or 3TM*.
do.o*-,obile-CotetPae 8 %ontent is e<ternally source!.
onMt be confuse! by the name of this containerB the wi!ths of the items are fi<e! an! can not be re:
size! like some other splitter technologies on the !esktop.
"hen the chil!ren are a!!e!B they specify their wi!th Afor horizontalD our height Afor verticalD. The
last pane A!efaultD is size! to the remaining space available.
+ome of the key properties of this wi!get inclu!eK
orietatio 8 3ow the chil! panes are shown. The choices are either ?3? AefaultD for
horizontal which means that the chil!ren are lai! out horizontally. The other choice is ?C?
which means the chil!ren are lai! out vertically.
do'ox8mo"ile89ormLa1out
do'ox8mo"ile8*ridLa1out
This wi!get is a container for a set of other containers. 't specifies a number of columns. As
chil!ren are a!!e!B if a chil! e<cee!s the ma<imum column it is a!!e! as a new row at the start
column. -ffectivelyB this generates a rectangular gri! of containers.
+ome of the key properties of this wi!get inclu!eK
cols 8 The number of of chil! items in a row. This is the same as saying the number of
columns in the gri!.
do'ox8mo"ile8Heading
This wi!get provi!es a hea!ing bar which can have navigation buttons as well as toolbar buttons.
3ere is a basic 3ea!ingK
+ome of its core properties of interest inclu!eK
label 8 The label shown in the primary part of the hea!ing.
back 8 A label to show which when clicke! will return us to the previous view. "hen
a!!e!B it looks as followsK
Page .34
,o6e<o 8 The view that pressing the back button will take us to. 'f a ?back? label is
supplie! then ,o6e<o must also be specifie!.
%hil! <oolBarButto instances may be a!!e!. Note that by !efault they appear to the left of
the hea!ing te<t. To have them on the right a!! the style ?$loat: right?.
+ee alsoK
!o6o<HmobileHTool2ar2utton
do'ox8mo"ile8IconContainer
The do.o*-,obile-IcoCotaier wi!get acts as a container for icons. -ach icon within
the container is an instance of the IcoIte, wi!get.
do'ox8mo"ile8IconItem
The do.o*-,obile-IcoIte, represents an icon. This item shoul! be a!!e! insi!e an
appropriate icon container such as the IcoCotaier wi!get.
+ome of the key properties of this wi!get areK
label 8 A te<t label to be shown along si!e the icon.
ico 8 A 7$* to an image APN@B ;P-@B @'> etcD that will be use! as the icon.
,o6e<o 8 The name of a view that will be shown when the icon is clicke!.
do'ox8mo"ile8Iconenu
This wi!get pops up a visual that contains a set of icons. -ach chil! must be a
do.o*-,obile-IcoMeuIte, instance.
+ome of the key properties of this wi!get areK
cols 8 The number of columns to have in the gri! of icons.
+ee alsoK
!o6o<HmobileH'conMenu'tem
do'ox8mo"ile8IconenuItem
This wi!get supplies an icon to be shown in the do.o*-,obile-IcoMeu which is a popup
that groups together icons.
+ome of the key properties of this wi!get areK
ico 8 The 7$* of an icon to !isplay.
label 8 A te<t label to be shown besi!e the icon.
Page .3(
,o6e<o 8 The name of a view that will be shown if this icon is selecte!.
+ee alsoK
!o6o<HmobileH'conMenu
do'ox8mo"ile8ListItem
The list item is an instance of an entry in a list. 't is a chil! of a variety of list wi!gets.
'n the following we see three +istIte,s a!!e! to an (dge<o(dge+ist. The first item has a
?,o6e<o? !efine! as in!icate! by the arrow on the right. +electing that item will change the view.
't contains the following visual itemsK
icon
label 8 The primary label of the list item.
right<e*t 8 Te<t to show on the ?right? of the list item.
3ere we see some te<t on the rightK
right'con.
right'con
+ome of the key properties of this wi!get areK
,o6e<o 8 The name of the view that will be shown when the item is clicke!.
clickable 8 A boolean whichB if set to trueB will enable clicks upon the list entry.
There are also events !efine! on this "i!getK
oClick34 : %alle! when the list item is clicke! an! the entry is ?clickable? or has a
view transition associate! with it.
+ee alsoK
"orking with o6o Mobile *ists
!o6o<HmobileH$oun!$ect*ist
!o6o<HmobileH$oun!$ect+tore*ist
!o6o<HmobileH-!geTo-!ge*ist
Page .3/
do'ox8mo"ile8PageIndicator
This wi!get shows a visual in!ication of which view from a set of views is currently being shown.
%urrently it is linke! to the do.o*-,obile-#"ap:ie" container to show the view in use.
do'ox8mo"ile8Pane
This wi!get is a simple !iv:wrapper pane. 't contains a property calle! ?cotaier!ode? which
is the 0M no!e wrappe! by this wi!get.
do'ox8mo"ile8Progress#ar
This wi!get shows a horizontal progress bar. 't has a value that is use! to show the progress to a
goal.
+ome of the key properties of this wi!get areK
6alue 8 The current value of the progress.
,a*i,u, 8 The ma<imum progress value. The !efault is 199.
label 8 A te<t label shown in the center of the bar.
The wi!get e<poses the following metho!sK
start34 : +tart the in!icator spinning
stop34 : +top the in!icator from spinning.
do'ox8mo"ile8ProgressIndicator
This wi!get shows a visual in!ication that the application is busy !oing something.
+ome of the key properties of this wi!get areK
iter6al 8 The time in millisecon!s for up!ating the in!icator.
si)e 8 The size in pi<els of the in!icator.
re,o6e/#top 8 "hen the wi!get is aske! to stopB shoul! it be remove!.
do'ox8mo"ile85adio#utton
This wi!get shows a ra!io button which can be checke! or not checke!.
"hen !eclaratively creating an instance of this wi!getB use the <iput type01radio1> as the
container. This will cause the correct space for it to be allocate!. >or e<ampleK
<iput type01radio1
a,e01gauge<ype1
data-do.o-type01do.o*-,obile-7adioButto1
data-do.o-6alue01Circular1 ->
+ome of the key properties of this wi!get areK
checked 8 's this ra!io button checke!J
6alue 8 The value of this button if it is checke! an! submitte! as a form.
a,e 8 The name of a group to associate together ra!io buttons so that only one is selecte!.
Page .19
+ee alsoK
!o6o<HmobileH%heck2o<
do'ox8mo"ile85ating
This wi!get provi!es a rating icon which can be selecte!.
+ome of the key properties of this wi!get areK
image 8 The 7$* of an image which contains three icons L emptyB half full an! full.
num+tars 8 The number of ?stars? to show.
value 8 The user selecte! value of the rating.
do'ox8mo"ile85ound5ect
The do.o*-,obile-7oud7ect wi!get allows us to create a container area with roun!e!
corners. 't can contain other 3TM* or o6o wi!gets. The 0M no!e containe! in
cotaier!ode is the hol!erHhook for the content.
't has a boolean property calle! ?shado"? whichB if set to trueB will show the area with a !rop
sha!ow effectK
do'ox8mo"ile85ound5ectCategor1
The do.o*-,obile-7oud7ectCategory provi!es a label that is !esigne! to be use!
imme!iately prior to a 7oud7ect+ist. The label property supplies the label.
+ee alsoK
!o6o<HmobileH$oun!$ect*ist
do'ox8mo"ile85ound5ectStoreList
This wi!get provi!es a container for list items. The corners of the list are !isplaye! with a roun!e!
appearance. 't is strikingly similar to the wi!get calle! do.o*-,obilde-7oud7ect+ist
with one crucial !ifference. That wi!get has list items e<plicitly a!!e! to itB the
do.o*-,obile-7oud7ect#tore+ist is associate! with a do.o-store !ata structure
an! manages the list items from the !ata.
To !ynamically change the store !ata associate! with the listB use its ?set#tore3store4?
metho!. 7sing the ?set3a,eC 6alue4? style will not work.
The properties of this wi!get inclu!eK
store 8 A reference to the !ata to be !isplaye! by this list.
Page .11
)uery
)uery0ptions
labelProperty
)ueryProperty
trasitio 8 The type of animation to perform when transitioning from one selecte!
chil! item to another.
icon2ase
iconPos
select 8 "hether an! how a check mark associate! with the selection in the list will be
shown. 0ptions inclu!eK
?multiple? 8 Multiple items may be selecte!
?single? 8 0nly a single item may be selecte!
?? 8 No check mark will be shown
stateful
sync"ithCiews
e!itable
tag
Now let us look at some e<amples.
do.o%ready3$uctio34 B
storeEata 0 Q
B label: 1A1C right<e*t: 1Apple1 DC
B label: 1B1C right<e*t: 1Baaa1 DC
B label: 1C1C right<e*t: 1Catelope1 D
R2
6ar sa,ple#tore 0 e" Me,ory3Bdata:storeEataC idProperty:1label1D42
listL%set#tore3sa,ple#tore42
D42
an!
<di6 id01listL1 data-do.o-id01listL1 data-do.o-type01do.o*%,obile%7oud7ect#tore+ist1><-di6>
pro!ucesK
+ee alsoK
"orking with o6o Mobile *ists
!o6o<HmobileH$oun!$ect*ist
!o6o<HmobileH*ist'tem
Page .1.
do'ox8mo"ile85ound5ectList
The do.o*-,obile-7oud7ect+ist provi!es a container for list items. The corners of the
list are !isplaye! with a roun!e! appearance.
-ach entry in the list correspon!s to a do.o*%,obile%+istIte, instance. ProgramaticallyB a
new entry may be a!!e! with addChild34. All entries may be remove! with
destroyEescedats34.
The properties of this wi!get inclu!eK
trasitio 8 The type of animation to perform when transitioning from one selecte!
chil! item to another.
icon2ase
iconPos
select 8 "hether an! how a check mark associate! with the selection in the list will be
shown. 0ptions inclu!eK
?multiple? 8 Multiple items may be selecte!
?single? 8 0nly a single item may be selecte!
?? 8 No check mark will be shown
stateful
sync"ithCiews
e!itable
tag
+ee alsoK
"orking with o6o Mobile *ists
!o6o<HmobileH*ist'tem
!o6o<HmobileH$oun!$ect%ategory
do'ox8mo"ile8Scrolla"lePane
This wi!get provi!es a scrollable area within a view. 't supports touch oriente! scrolling. 't acts as
a container for other content.
+ome of the key properties of this wi!get inclu!eK
radius 8 The ra!ius of the roun!e! corner mask.
roudedCorerMask 8 'f trueB create a mask.
height 8 The height of the pane Aeg. ?.99p<?D. %an also take ?inherit? an! ?auto?.
Page .13
do'ox8mo"ile8Search#ox
T2
do'ox8mo"ile8Simple!ialog
This wi!get provi!es a !ialog container which can be poppe! up.
+ome of the key properties for this wi!get inclu!eK
,odal 8 'f trueB this !ialog must be !ismisse! before interaction with other items on the
!isplay can occur.
closeButto 8 'f trueB a close button is a!!e! to the !ialog in the top:right corner.
do'ox8mo"ile8Slider
This wi!get provi!es a horizontal or vertical sli!er use! to set a numeric value.
+ome of the key properties of this wi!get inclu!eK
6alue 8 The currently selecte! value.
,i 8 The minimum value of the sli!er.
,a* 8 The ma<imum value of the sli!er.
step 8 The number of sli!er units to move at a time.
$lip 8 $everse the !irection of the sli!er values.
orietatio 8 0ne of either ?3? for horizontal or ?C? for vertical.
iter,ediateChages 8 +houl! a change in the sli!er be reporte! by oChage
imme!iately or only at the en! of the moveJ The !efault is false.
The following is a visualization of a horizontal sli!erK
The oChage34 event is fire! when the sli!erMs value is change!. The new value is passe! as a
parameter to the event.
do'ox8mo"ile8Spin(heel!atePic0er
This wi!get provi!es a wheel !riven !ate selection mechanism. +ee the following image.
The monthB !ate an! year spinners may be spun in!epen!ently to select a !esire! !ate. +ome of the
key properties of this wi!get areK
Page .11
yearPatter 8 The co!ing for the year. The !efault is ?yyyy?.
,othPatter 8 The co!ing for the month. The !efault is ?MMM?.
dayPatter 8 The co!ing for the !ay. The !efault is ?!?.
6alue 8 The initial !ate to be shown in ?5555:MM:!!? format Aeg. .913:9(:.#D.
6alues 8 The initial !ate to be shown as an array of three integers in the or!er of yearB
month an! !ay Aeg. W.913B(B.#XD
+ee alsoK
!o6o<HmobileH+pin"heelTimePicker
!o6o<HmobileHCaluePickeratePicker
do'ox8mo"ile8Spin(heelTimePic0er
This wi!get provi!es a wheel !riven time selection mechanism. +ee the following image.
+ee alsoK
!o6o<HmobileH+pin"heelatePicker
!o6o<HmobileHCaluePickerTimePicker
do'ox8mo"ile8Switch
This wi!get provi!es a two state switch. +ee the followingK
+ome of the key properties of this wi!get areK
le$t+abel 8 The label for ?on?.
right+abel 8 The label for ?off?.
6alue 8 The initial value for the switch.
The +witch can generate the ?o#tateChaged? event when its state is flippe!.
+ee alsoK
!o6o<HmobileH%heck2o<
!o6o<HmobileHToggle2utton
do'ox8mo"ile8Ta"#ar
This wi!get provi!es a container that shows a series of selectable options. Think of it much like a
classic 7' Tab container. TypicallyB the <abBar contains a set of <abBarButto chil!ren.
Page .1#
The <abBar can also show itself in a variety of !ifferent styles through the ?bar<ype? propertyK
tab2ar A!efaultD
segmente!%ontrol
stan!ar!Tab
slimTab
flatTab
tallTab
+ome of the key properties of this wi!get areK
bar<ype 8 The type of task bar to createB options inclu!eK
tab2ar
segmente!%ontrol
stan!ar!Tab
slimTab
flatTab
tallTab
+ee alsoK
!o6o<HmobileHTab2ar2utton
do'ox8mo"ile8Ta"#ar#utton
This wi!get provi!es a button which is e<pecte! to be containe! within a
do.o*-,obile-<abBar container.
+ome of the key properties of this wi!get areK
label 8 A te<t label that will be shown with this button
,o6e<o 8 The name of a view that will be shown if the button is selecte!.
ico 8 A 7$* of an icon to show for the button.
Page .1&
icoL 8 A 7$* of an icon to show when unselecte!.
icoI 8 A 7$* of an icon to shown when selecte!.
badge 8 A ba!ge to show associate! with the button
+ee alsoK
!o6o<HmobileHTab2ar
do'ox8mo"ile8TextArea
This wi!get provi!es a te<tarea into which free form te<t may be entere!. 7nlike the Te<t2o<B this
wi!get allows multiple lines of te<t to be entere!.
+ome of the key properties of this wi!get areK
6alue 8 The value of the te<t
,a*+egth 8 The ma<imum length of the te<t in characters.
This wi!get publishes the following eventsK
oChage34 : %alle! when the value in the te<tarea changes.
3ere is an e<ample of a visualizationK
+ee alsoK
!o6o<HmobileHTe<t2o<
do'ox8mo"ile8Text#ox
This wi!get provi!es a single line of free form te<t to be entere!.
+ome of the key properties of this wi!get areK
6alue 8 The value of the te<t.
,a*+egth 8 The ma<imum number of characters that may be entere!.
tri, 8 $emove lea!ing an! trailing spaces from the entere! !ata.
uppercase 8 %onvert any entere! te<t to uppercase.
lo"ercase 8 %onvert any entere! te<t to lowercase.
propercase 8 %onvert any entere! te<t to propercase.
This wi!get publishes the following eventsK
oChage34 : %alle! when the value in the te<t bo< changes.
3ere is an e<ample of a visualizationK
"hen !eclaring this wi!get in 3TM*B you must use the 3TM* QinputR tag. >or e<ampleK
Page .14
Qinput !ata:!o6o:typeN?!o6o<HmobileHTe<t2o<?RQHinputR
+ee alsoK
!o6o<HmobileHTe<tArea
do'ox8mo"ile8Toggle#utton
This wi!get provi!es a button which can be toggle! between two !istinct states. +ome of the key
properties of this wi!get areK
checked 8 's this button checke! or notJ
label 8 The label that is to be shown in the button.
7nchecke!B it may look as followsK
while checke!B it may beK
+ee alsoK
!o6o<HmobileH%heck2o<
!o6o<HmobileH+witch
do'ox8mo"ile8Tool#ar#utton
A Tool2ar2utton is typically place! in the hea!ing wi!get.
Among its properties areK
moveTo 8 The name of a view to transition to.
label 8 The label of the button
do'ox8mo"ile8Tooltip
This wi!get provi!es a pop:up bubble of te<t associate! with another wi!get or 0M no!e. The
te<t of the tooltip is the 'nner 3TM* of the Tooltip. The tooltip is shown when its ?sho"34?
metho! is invoke!. #ho"34 has the following parametersK
aroud!ode Afirst parameterD 8 The no!e that will be pointe! to by the tooltip.
positios Asecon! parameterD 8 An or!ere! list of positions which shoul! be use! to
show the tooltip. 'f the first position canMt be use!B then the secon! will be trie!. 'f the
secon! canMt be use!B the thir! will be trie! etc. The possibilities areK
before
after
above:centere!
Page .1(
below:centere!
A companion metho! calle! ?hide34? will hi!e a previously shown tooltip.
't also appears that to show correctlyB a class calle! ?,bl<ooltipBubble? must be applie! to
the Tooltip wi!get.
The following is an e<ample of use which a!!s a tooltip to a button.
<butto data-do.o-type01do.o*%,obile%Butto1 data-do.o-props01label:OMy +abelIO1>
<script type01do.o-o1 data-do.o-e6et01,ouseo6er1>
ttL%sho"3thisC Q1a$ter1R42
<-script>
<script type01do.o-o1 data-do.o-e6et01,ouseout1>
ttL%hide342
<-script>
<-butto>
<di6 data-do.o-type01do.o*%,obile%<ooltip1
data-do.o-id01ttL1
class01,bl<ooltipBubble1>Hello <hereP<-di6>
"hen the button has the mouse hovere! over itB the tooltip appears as followsK
do'ox8mo"ile8.aluePic0er
This wi!get provi!es a visual for picking a value. 't is compose! of a number of ?slots? each of
which has a scroll turner A^ or :D. %licking the ^ or 8 scrolls the value in the associate! !irection.
3ere we see an e<ample CaluePicker with two slotsK
The best way to think of this control is like that of a thumb !ial.
-ach slot is !escribe! by a do.o*-,obile-:aluePicker#lot.
Page .1/
The Calue Picker seems to have !isplay problems within the $ich Page -!itor. "hen
a!!e!B it !oes not appear to show in the visual canvas.
+ee alsoK
!o6o<HmobileHCaluePicker+lot
!o6o<HmobileH%ombo2o<
do'ox8mo"ile8.aluePic0er!atePic0er
This wi!get provi!es a visual for picking a !ate.
!o6o<HmobileH+pin"heelatePicker
!o6o<HmobileHCaluePickerTimePicker
do'ox8mo"ile8.aluePic0erSlot
This wi!get inserts a slot into a CaluePicker. 2elow is an e<ample.
't is not uncommon to e<plicitly specify the style ?wi!th? to size the slot.
+ome of its key properties inclu!eK
6alue 8 The current value of the slot.
labels 8 An array of possible values for the slot. A !eclarative e<ample of labels
supplie! in 3TM* might beK
<di6 data-do.o-type01do.o*%,obile%:aluePicker#lot1
data-do.o-props01labels: QO+o"OCOMediu,OC OHighOR1>
<-di6>
"hen a!!ing labels using the properties viewB take care as the !ata entere! seems to be
Mmangle!M with )uote types replace! an!Hor escape!. -<perience seems to show that manually
e!iting the 3TM* source is the most reliable way to make changes.
ite,s 8 an array of nameHvalue pairs for the slot.
label5ro, 8 A starting value for the slot.
label<o 8 An en!ing value for the slot.
step 8 The steps from ?label5ro,? to ?label<o?.
)eroPad 8 The number of zeros to pa! left.
Page .#9
+ee alsoK
!o6o<HmobileHCaluePicker
do'ox8mo"ile8.aluePic0erTimePic0er
This wi!get provi!es a visual for picking a time.
!o6o<HmobileH+pin"heelTimePicker
!o6o<HmobileHCaluePickeratePicker
do'ox8mo"ile8.ideo
This wi!get plays a vi!eo.
Page .#1
.0uer"
The ;ava+cript library calle! ?6=uery? is an alternative to o6o Aof courseB one may also say that
?o6o? is an alternative to 6=ueryD.
As well as having a !efault packageB there are several sub pro6ects inclu!ingK
6=uery 7ser 'nterface
6=uery Mobile
+ee alsoK
6=uery home page
6=uery AP' $eference
)2uery Mobile + data roles
button
Angular)S
!etting up #clipse
+ince Angular is heavy on its typingB we want to have as much assistance as possible. To that en!
we want to configure -clipse with Angular support.
-clipseMs Angular support can be foun! hereK
httpsKHHgithub.comHangelozerrHangular6s:eclipse
The easiest way to install this is to use the -clipse Marketplace an! search for Angular.
QAs of the time of writingB the comple<ity of this environment is too heavyR
%hrome Apps
Page .#.
%hrome Apps are a @oogle provi!e! framework for buil!ing an! running %hrome base!
applications that can be e<ecute! in the same fashion as native applications.
The entry point into a %hrome App isK
chro,e%app%ruti,e%o+auched%add+isteer3$uctio34 B
-- Isert code here to do so,ethig%
D42
"e can create a win!ow withK
chro,e%app%"ido"%create3O,ai%ht,lOC B
id:
bouds: B
"idth:
height:
le$t:
top:
DC
,iWidth:
,iHeight:
D42
+ee alsoK
"hat are %hrome AppsJ
&uilding a Chrome App
The following is the high level recipeK
1. %reate the manifest
.. %reate the backgroun! script
3. %reate a win!ow page
1. %reate the icons
#. *aunch the app
The Manifest
The manifest is a file calle! ?,ai$est%.so? that contains the core !escription of your
application.
+ee alsoK
The Manifest file
The $ackground cript
+ee alsoK
%hrome App ;ava+cript AP's
)ava1
Although strictly not a mobile capabilityB it is important to un!erstan! the concept of the ;ava>G
platform. ;ava>G is the 7' technology shippe! with ;ava A1.4.9.#1 an! aboveD. >or ;ava ( onwar!s
it can be assure! to be present. ;ava>G is a ?classic? thick client technology. 't has a super rich
AP' that is available to a ;ava programmer. ArguablyB ;ava is one of the most mature languages
available to!ay with the broa!est set of functions an! skills available. 3istoricallyB ;ava has ha! a
number of 7' technologies starting with A"TB then +wing an! now ;ava>G. ;ava>G !eprecates
Page .#3
all the previous technologies.
There are many books written on ;ava>G an! we arenMt going to be e<haustive in our coverage of
the technology. $ather we will make notes on the core capabilities with illustrative e<amples where
necessary.
The 'ello World app
To create a trivial ;ava>G applicationB we can follow the instructions in this recipe to get us up an!
running.
1. %reate a ;ava pro6ect
.. A!! .$*rt%.ar to the pro6ect classpath. This ;A$ can be foun! in the lib fol!er of a
mo!ern ;ava ;$-.
3. %reate a ;ava class that implements main
1. Mo!ify the class to containK
public class YourClassName e*teds Applicatio B
public static 6oid ,ai3#trigQR args4 B
lauch3args42
D
9/6erride
public 6oid start3#tage stage4 thro"s (*ceptio B
Paret root 0 5AM++oader%load3getClass34%get7esource31<YourFXMLFile>%$*,l1442
#cee scee 0 e" #cee3rootC H>>C S>>42
stage%set#cee3scee42
stage%sho"342
D
D
#. 7sing +cene 2uil!erB create an >GM* file an! save it in the same fol!er as your ;ava class.
The /a$a06 'igh Le$el Architecture
*et us start with the mo!el. 'n ;ava>G we are in the business of buil!ing Applications an! ;ava>G
provi!es a class calle! Applicatio which we must e<ten!. This allows us to implement a
metho! calle! ?start3#tage4? which is calle! when the application is rea!y to start. Think of
?start34? as the entry point into the application.
'f the ?startAD? is the callback to say that the application has starte!B how is the application launche!
in the first placeJ
"e are familiar with the special metho! calle! ?static 6oid ,ai3#trig argsQR4? that
can be an entry point into a ;ava application. Application contains a static metho! calle!
?lauch3#trig QR4? that can be use! to launch it. As suchB the simplest ;ava>G application
will look as followsK
class MyApp e*teds Applicatio B
public 6oid start3#tage stage4 B
D
public static 6oid ,ai3#trig argsQR4 B
lauch3args42
D
D
"e can then !o work in the ?startAD? metho! to bring up the rest of our environment.
This now takes us to the ne<t topic of consi!erationB namely the ?+tage?.
Page .#1
-avaf7)stage)tage
"e can loosely think of the stage ob6ect as being a representation of the top level win!ow of the
application. The stage ties to the notion of the native operating system win!ow. "hen a stage is
shownB it will have properties inclu!ing size Awi!th an! heightD as well as others.
A stage !oesnMt actually appear until an! unless it is shown. 't can be shown using its ?sho"34?
metho!.
+ome of the more important properties of +tage areK
title 8 The title of the win!ow
>ollowing on with the metaphor of a playB containe! upon a stage is the scene being shown an!
;ava>G has the same notion. "e can think of the +tage as where the action takes place but it is the
+cene that is the ob6ect of attention.
"e can set the icon associate! with an application usingK
stage%getIcos34%add3<I,age>42
%onsi!er a!!ing multiple images of !ifferent sizes. 7se! 1&<1& an! 3.<3. as a minimum. ;ava>G
will correctly choose the appropriate sizes as nee!e!.
>or non !esktop environmentsB the stage may be an area in a browser Aan appletD or a mobile !evice
screen area.
-avaf7);)cene
+cenes can be create! in a variety of ways butB once !oneB we can associate the scene with the stage
by calling the stageMs ?set#cee3#cee4? metho!. 2efore we can talk further about +cenesB we
must now intro!uce the i!ea of a ?scene graph?. 'n ;ava>GB what the user sees is built out as a set
of ?No!es? where each no!e represents some 7' component. -<amples of No!es inclu!e the usual
suspects such as 2uttons an! *ists an! ;ava>G provi!es a rich set of a!!itions. 0ne of the notions
of a No!e is that every no!e has a parent. This means that the no!es form a relationship mo!el Aa
tree or graphD. This relationship mo!el is the key to ;ava>G. "e can have simple No!es such as
2utton which are the ?leaves? of the tree. They have no chil!ren themselves. 3owever other no!es
calle! ?containers? can have chil!ren Athe parent of these chil!ren is the container that contains
themD. 'f we follow the parentHchil! relationship upwar!s we will fin! a single no!e that is the root
of the tree. This no!e has no parent. This root no!e is what is associate! with a +cene. "hen the
+cene is shownB it is the tree represente! by the no!es that is actually use! to !escribe what is ma!e
visible to the users.
-avaf7)scene)image)Image
This class represents an image from a %pg or other graphics file. 't has a number of sources from
which the !ata of the image can be rea!.
>or e<ampleB to loa! an image from a file that is in the same !irectory as a class we can useK
I,age i,age 0 e" I,age3MyApplicatio%class%get7esourceAs#trea,31,yI,age%pg1442
This might be use! as the icon image associate! with a stage. An 'mage can also be constructe!
from an Iput#trea,. This means that if we can source the image !ata from elsewhere such as
a !atabase L we can also create an 'mage.
+ee alsoK
;ava>G 'mageCiew
Page .##
06ML + The /a$a06 Marup Language
"e can create ;ava>G applications using stan!ar! ;ava programming techni)ues such as creating
instances of ;ava>G ob6ects an! linking them together in co!e. 3oweverB an alternative techni)ue
is available to us which we will shortly see has a wealth of power. +ince a +cene @raph is a
hierarchical !escription of no!es what we can !o is e<press this relationship within an GM*
!ocument. +uch a !ocument use! to !escribe a ;ava>G application is calle! an ?>GM*? file.
>GM* files allow one to !escribe the relationship between 7' no!es in a !eclarative as oppose! to
programmatic fashion. 'nstea! of co!ing no!e after no!e within a ;ava classB we can !escribe the
no!es in the >GM* file an! have ;ava>G interpret that GM* file for us at runtime. Parsing the fileB
;ava>G will construct the correspon!ing +cene @raph as though we ha! co!e! it in ;ava.
Another important feature of >GM* is that a freely available application calle! ?+cene 2uil!er? can
be !ownloa!e! off the web. This application allows one to visually compose what the 7' will look
like. The input an! output of +cene 2uil!er is an >GM* file. This means that the construction of
;ava>G 7's 6ust became tremen!ously easier.
"hen we write a normal ;ava application that co!es the construction of the no!es by han!B we are
free to intermi< arbitrary controller logic. >or e<ampleB if we !efine a button then at the same place
we can !efine an action to be performe! when the button is presse!. "hen we are !escribing a
scene graph in >GM* we !onMt have that option. This is where we can utilize a class that we will
consi!er to be our ?%ontroller %lass?.
A controller class is a stan!ar! ;ava 2ean class with fiel!s correspon!ing to selecte! no!es within
the graph. Metho!s in the controller class can also be !efine! as invokable when certain events
happen in the 7'.
"ithing ;avaB we can parse the >GM* !ocument to create the tree of no!es using the static metho!
?5AM++oader%load34?. >or e<ampleB to loa! an >GM* file locate! besi!e the current class we
coul! co!eK
Paret root 0 5AM++oader%load3getClass34%get7esource31My5AM+%$*,l1442
+ee alsoK
Mastering >GM* 8 ;ava +- (
'ntro!uction to >GM* : .913:9/:19
6:ML &rchitecture
'mage a simple piece of >GM*
<MyClass>
<-MyClass>
The way to un!erstan! this is that the >GM* parser will instantiate a new instance of the ;ava class
calle! ?My%lass?.
Now if we pair this with ;ava>GB the >GM*K
<+abel ->
will create a new instance of a *abel ob6ect.
A ;ava>G *abel ob6ect has properties such as ?te<t? to !efine the te<t of the label. 'n ;ava we
might co!eK
+abel ,y+abel 0 e" +abel342
,y+abel%set<e*t31Hello "orld142
'n >GM* we might !eclareK
<+abel te*t01Hello World1 ->
Page .#&
to achieve the same effect. Any property of a ;ava class can be set this way. All properties must
start with a lower case letter. As an alternative to specifying a classMs property as an GM* attributeB
we can achieve the same effect by making the attribute an GM* chil! of the class element.
<+abel>
<te*t>Hello World<-te*t>
<-+abel>
Now imagine a C2o< containerK
<:Bo* layoutA01I'>%>1 layoutN01L>>%>1 pre$Height01I>>%>1 pre$Width01L>>%>1>
<childre>
<+abel te*t01+abel1 ->
<-childre>
<-:Bo*>
2y nesting tags within other tagsB we are !escribing containment an! hierarchy.
Importing definitions
"hen we !efine an >GM* elementB we can provi!e its full package name or else we can perform
an import of the class or package into the current namespace. This is the same concept as ;ava
imports. +ince an >GM* !ocument is an GM* !ocumentB we use GM* Processing 'nstructions to
achieve this. 'f we specifyK
<;i,port .a6a$*%scee%cotrol%+abel;>
"e will have the *abel element available to us. 'f we specify
<;i,port .a6a$*%scee%cotrol%Y;>
then all of the classes in that package will be in our namespace.
The f7<value attribute
>or elements that !onMt have getters an! settersB we can assign value to those elements using the
?$*:6alue? attribute.
>or e<ampleK
<#trig $*:6alue01Hello World1->
<Eouble $*:6alue01G%LSL1->
<Boolea $*:6alue01true1->
The f7<include instruction
'f we wish to inclu!e other >GM* files within our current file we can !o with the ?$*:iclude?
instruction. >or e<ampleK
<$*:iclude source01,y5ile%$*,l1->
The f7<define attribute
'f we wish to a!! elements into an >GM* that are not to be a!!e! to the scene graphB we can
inclu!e these in an ?$*:de$ie? block.
The f7<controller attribute
%ertain no!es can have an ?f*:cotroller? attribute applie!. The value of this attribute is the
fully )ualifie! name of the class that implements the controller.
Page .#4
The f7<id attribute
Most no!es can have an ?$*:id?. This attribute names a ;ava variable of the same type of the
no!e. "hen the >GM* is parse!B the variable will be up!ate! to contain the reference to the no!e.
>or e<ampleB if we !efine a label in >GM* asK
<+abel $*:id01,y+abel1 te*t01HelloWorld1 ->
then in the correspon!ing ;ava controller classK
95AM+
pri6ate +abel ,y+abel2
The variable with the same name as the ?$*:id? will be boun! to that instance of the no!e.
"hen an $*:id attribute is foun!B we can think of this as creating an >GM* name! variable with
the value of the $*:id referencing the element to which it is attache!. 'n other elements we can
refer to the element with the $*:id using the ?a<a,e>? synta<.
"e can also use an a!!itional synta< that looks like ?aB<a,e>%<property>D? to !ynamically
have an elementMs property boun! to another elements property.
The f7<root element
The $*:root element is use! to !eclare that the root element will N0T be create! but rather will
be set by a call to to set7oot34 prior to the load34 metho! being calle!.
& Controller class
A controller class fulfills the controller part of the Mo!el:Ciew:%ontroller contract. An >GM*
!escribe! application can name a controller class using the $*:cotroller attribute.
A metho! calle! ?iitiali)e34? canHshoul! be implemente! in the controller an! will be calle!
to initialize an variables or !ata.
>or e<ampleK
95AM+
pri6ate 6oid iitiali)e34 B
-- Eo so,e iitiali)atio %%%
D
The controller class can inclu!e variables that are in6ecte!Hmappe! to the $*:id references for
>GM* elements. >or e<ampleB if we !efineK
<<e*t5ield $*:id01,y<e*t1->
then in the controller classB we can specifyK
95AM+
pri6ate <e*t5ield ,y<e*t2
an! when the %ontroller is instantiate!B the ?,y<e*t? variable will be automatically set to be a
reference! to the correspon!ing ;ava>G <e*t5ield ob6ect.
>or ;ava>G wi!gets that can emit eventsB we can !efine functions within the controller class that
can be invoke! to process such events.
>or e<ampleK
95AM+
pri6ate 6oid ,yHadler3Actio(6et e6et4 B
-- do so,ethig
D
An! in the >GM*B we can map the wi!get to this function usingK
Page .#(
<Butto te*t01My Butto1 oActio01Z,yHadler1->
Note that in the >GM*B the special synta< of ?Z<$uctio a,e>? for the mapping.
The ;ava annotation ?95AM+? is use! to mark a metho! or variable as accessible by >GM*. This
allows us to mark these variables an! metho!s as private an! still be worke! against. "e can
choose to make the variables an! metho!s public an! not use 95AM+ but it is recommen!e! to get
into the habit of using 95AM+.
+ee alsoK
%ontrollers
!cene &uilder
+cene 2uil!er is a 7' !evelopment tool for e!iting >GM* files. The current release is +cene
2uil!er ..9. +cene 2uil!er constructs >GM* files in a graphical format.
;ava>G +cene 2uil!er ..9
Installing cene $uilder
To install +cene 2uil!er ..9B first !ownloa! the installation image from the 0racle web siteK
httpKHHwww.oracle.comHtechnetworkH6avaH6avaseH!ownloa!sHsb.!ownloa!:.14444&.html
The installation screens look as followsK
Page .#/
Handling issues %ith cene $uilder
-<perience has shown that from time to timeB +cene 2uil!er can get confuse!. "hen opening
>GM* filesB they have been seen ?not to show?. A solution for this is to clean the registry where
historic information about previously opene! files is kept. The registry path for this isK
3,-5I%7$$-NTI7+-$H+oftwareH;ava+oftHPrefsHcomHoracleH6avaf<Hscenebuil!erHapp
/a$a06 and #clipse
'f one is using stan!ar! -clipse to buil! ;ava>G applicationsB a little setup is re)uire! in the pro6ect.
>irstB we must a!! the ?.$*rt%.ar? file to the pro6ect buil! path. This ;A$ file can be foun!
within the !istribution of ;ava.
Another goo! i!ea is to associate the ;ava!oc with the ;A$. 0pen the properties of the ;A$ an!
Page .&9
select the ;ava!oc *ocation. "e can now enter the path to the ;ava!oc 7$* on the webK
httpKHH!ocs.oracle.comH6avaf<H.HapiH
/a$a06 Component !i7ing
"hen a component is a!!e! to the screenB it will consume some screen real estate. 2ut how much
space will it consumeJ That )uestion is the sub6ect of this part of the story.
>irst we will consi!er the notion that a component has a ?preferre! size?. This is the size of the
component so that it has ?6ust enough? space to show itself. 'n a!!itionB a component has a
ma<imum size an! a minimum size. The minimum size is the smallest size that it will allow itself
to be shown in an! the ma<imum size is the ma<imum that it will allow itself to be grown to.
+ee alsoK
"orking "ith *ayouts in ;ava>G : 9&:.913
/a$a06 C!!
Much of the visual appearance of a ;ava>G application can be customize! using a form of %++.
espite saying this an! as we will shortly fin!B even though the format of a ;ava>G %++ file is the
same as for webB !o not be foole! into thinking that any knowle!ge you may have of web %++ can
be applie! here. Although the general synta< for %++ !efinitions are the sameB the meanings an!
synta< for specific properties is completely !ifferent.
A ;ava>G style property begins with ?-$*-?. 't !oes this to ensure that there will be no confusion
between these properties an! stan!ar! "eb properties.
-very no!e within a scene graph can have a list of 9 or more class names associate! with it. "e
Page .&1
can access this list through the no!eMs ?get#tyleClass34? metho! which returns an
/bser6able+ist. "e can a!! or remove class names from this list which will have the same
effect as a!!ing or removing classes to be associate! with the no!e.
To select a no!e within a scene graph we can use the followingK
%class!a,e 8 The name of a class that the no!e belongs to
Zid!a,e 8 The %++ ' value of the no!e
A style may be e<plicit set on a no!e using the no!eMs ?set#tyle34? metho!. 0therwise the
style is taken from the !efault an! ne<t from any loa!e! style sheet an! ne<t from any e<plicitly set
style.
+tylesheets can be applie! to any container. A stylesheet can be loa!e! in a scene throughK
scene.get+tylesheetsAD.a!!AQfileNameRDU
+ome of the more interesting stylesK
:f<:te<t:fill : Te<t color
+ee alsoK
;ava>G %++ $eference @ui!e
/a$a06 Dialogs
'magine we wish to !isplay a new !ialog. >irst we will create the >GM* of the new !ialog in a
new file. Ne<t we will create its controller. These are the same steps that we woul! use to create
any new +cene.
'n the application which wishes to show the !ialogB we can now callK
#tage dialog 0 e" #tage342
dialog%iit#tyle3#tage#tyle%8<I+I<N42
dialog%iitModality3Modality%APP+ICA<I/!@M/EA+42
dialog%set<itle31(rror142
5AM++oader loader 0 e" 5AM++oader342
Paret root 0 3Paret4loader%load3getClass34%get7esource31(rrorEialog%$*,l14%ope#trea,3442
(rrorEialog@Cotroller edC 0 3(rrorEialog@Cotroller4loader%getCotroller342
edC%setMessage3e%getMessage3442
#cee scee 0 e" #cee3root42
dialog%set#cee3scee42
dialog%sho"342
>rom a high levelB the story is that we create a new stage an! set is style an! mo!ality. Ne<t we
give it a title.
Now it is time to loa! its +cene graph. 0nce !oneB we can ask the loa!er for a han!le to its
controller. "e assume that the controller e<poses a metho! to set the te<t on the !ialog. >inallyB
we can show the !ialog.
"ithin the controller of the !ialogB we may wish to provi!e a ?close? button. 't will be a button
with the following processingK
95AM+
pri6ate Butto closeButto2
95AM+
6oid closeButtoActio3Actio(6et e6et4B
Page .&.
#tage stage 0 3#tage4 closeButto%get#cee34%getWido"342
stage%close342
D
This will fin! the stage that contains the close button an! close that stage.
A potentially far better way of working with !ialogs is to use the ialog capabilities of the 0pen
+ource toolkit known as Cotrols5A.
+ee alsoK
org.controlsf<.!ialog.ialogs
/a$a06 Tass8 !er$ices and Worers
Access to ;ava>G can only be performe! from the 7' threa! also calle! the ;ava>G Application
threa!. 't is invali! to attempt to manipulate ;ava>G resources from within the conte<t of other
threa!s. Putting it another wayB ;ava>G is not threa! safe. %alling ;ava>G from other threa!s can
result in grossly unpre!ictable results.
3oweverB if we try an! follow these rules an! attempt to perform all our processing work within the
7' threa! we will fin! another problem. The application will appear sluggish an! perform ba!ly.
;ava>G provi!es a package calle! .a6a$*%cocurret which is specifically !esigne! to allow
backgroun! tasks to be performe! while keeping the 7' threa! safeB
+ee alsoK
%oncurrency in ;ava>G 8 ;ava +- (
1unning %ork in the background
'magine that we wish to !o some non 7' processing that takes some time an!B when !oneB up!ate
the 7'. An e<ample of this might be an e<pensive !atabase )uery or a "eb +ervice call. "e may
want to !o this on as the result of a button press or other 7' interaction. 'f we now look at the
!iagrams show below. The top half shows the normal flow of operation. The Main threa! has
control an! when a user clicks a buttonB the App %allback is invoke! on that threa!. The App
%allback then makes its slow call to the back:en! blocking waiting for the return. "hen the back:
en! completesB the App %allback !oes some work an! finally returns control to the main threa!. As
we can seeB the main threa! gave up control for the whole !uration.
'f we now look at the secon! !iagramB again the main threa! calls the App %allback logic but this
timeB the App %allback logic creates a new threa! that gets control. The App %allback threa!
imme!iately returns control to the Main threa! which can continue to up!ate the 7'. "e now have
two threa!s e<ecuting in parallel with each other. The worker threa! now makes the slow call to
the back en! an! when it returnsB it returns control to the worker threa!. 2ecause of contractual
rulesB the worker threa! may not up!ate any 7'. That is the e<clusive prerogative of the ;ava >G
main threa!. The worker threa! then issues a re)uest to the main threa! to run some logic at some
time later an! the worker en!s. At some later pointB the main threa! is now able to invoke the
specifie! logic that the worker threa! aske! it to call. That logic e<ecutes on the main threa! in the
App %allback co!e.
The vitally important thing to note is that the ;ava>G threa! !i! N0T have to wait anywhere near
as long as that !uration shown in the first !iagram.
Page .&3
The way to achieve this recipe can be broken !own as as followsK
"hen a re)uest to run something e<pensive arrives on the main threa! !o the followingK
1. %reate a new Task ob6ect instance
.. $un the new Task on its own threa!
"e will talk about creating a new Task in a moment which is the meat of the story. 3owever to run
the taskB we can use the following boiler plateK
<hread thread 0 e" <hread3taskIstace42
thread%setEae,o3true42
thread%start342
NowB let us look at the Task. A Task instance can be configure! to return a value. 'n our case we
!onMt care about such a value but we will keep the concept anyway an! simply use a ;ava +tring.
Page .&1
To create a new Task we woul! co!eK
<ask<#trig> taskIstace 0 e" <ask<#trig>34 B
9/6erride
protected #trig call34 thro"s (*ceptio B
-- Eo so,ethig e*pesi6e here
Plat$or,%ru+ater334 -> B
-- Code to be e*ecuted o ,ai thread goes here
D42
retur 1EoeP12
D -- (d o$ call
D2 -- (d o$ e" <ask34
/a$a06 C!! and !tylesheets
The ;ava>G controls can be style! using stylesheets. "e can loa! a stylesheet using the
?stylesheets? attribute applie! to a container. To use this attributeB we woul! co!eK
<#o,eCotaier>
<stylesheets>
<87+ 6alue019<a,e>%css1->
<-stylesheets>
<-#o,eCotaier>
The %++ properties for a control all start with ?-$*-? to in!icate that they are ;ava>G as oppose!
to web. The ;ava>G %++ reference provi!es all the !etails of the properties available. +ome of the
more common areK
-$*-te*t-$ill 8 The color of the te<t
+ee alsoK
;ava>G %++ $eference
/a$a06 Deployment
0nce an application utilizing ;ava>G has been built in -clipse or some other toolB the ne<t thought
is that of !eployment. eployment is se)uence of steps necessary to make the application available
for users to use.
The !eployment tools generate three primary artifacts.
A ;A$ file 8 This ;A$ contains the compile! co!e an! other resources necessary to e<ecute
the application.
A ;N*P file 8 This file allows the application to be !eploye! from a ;ava "eb +tart
environment.
An 3TM* file 8 This file provi!es a template to launch the app in a web page.
'f we wish to create a "in!ows ?,si? installerB we will nee! to install the "i< Toolset
AhttpKHHwi<toolset.orgHD.
'f we wish to create an -G- installerB we nee! to install 'nno +etup %ompiler D
To buil! a !eployable solution we follow three primary steps.
The first is to get our application the way we want it. "ith this !oneB we e<tract all the compile!
classes an! resources into its own !irectory L for e<ample a !irectory calle! ?bi?. -clipse !oes
this for us L there is a !irectory calle! ?bi? ne<t to our ?src? fol!er.
"ith a !irectory containing our compile! co!e an! resourcesB we now use a tool calle!
Page .&#
?.a6a$*packager? to package that co!e into a ;A$ file. This ;A$ has other artifacts in6ecte!
into it also. "e place this ;A$ an! any other !epen!ent ;A$s in its own fol!er. >or e<ampleB a
fol!er calle! ?JA7#?.
>inallyB we run one more step which again uses the ?.a6a$*packager? tool to create an
installer. This installer can then be !istribute! an! run by application users which will install the
application rea!y for e<ecution.
3ere are some e<ample scripts.
.a6a$*packager -create.ar -appclass co,%kolba%od,ci%#ed(6et -srcdir
1C:\Pro.ects\/EMCI\Widgets\WorklightWorkspace\(6et#ed\bi1 -out$ile JA7#-#ed(6etApp%.ar
-classpath /EMCI8tils%.ar
.a6a$*packager -deploy -out$ile #ed(6et -"idth =>> -height H>> -a,e App!a,e -appclass
co,%kolba%od,ci%#ed(6et -6 -srcdir JA7# -outdir Istallers -ati6e ,si -title 1#ed(6et1
-descriptio 1/EM CI (6et #eder1 -6edor 1Molba9IBM1 -a,e 1#ed(6et1
+ee alsoK
eploying ;ava>G Applications : 19:.913
/a$a06 Data and %bser$ables
;ava>G provi!es a number of specialize! !ata types an! han!lers that make working with ;ava>G
much easier. Part of the concept here is that a 7' visualization is a visualization of !ata. "ithin a
;ava environmentB !ata is built from primitive ;ava !ata types an! ;ava ob6ects. "ithin application
logicB the values of these variables can be change!. Now consi!er a te<t fiel! that is showing some
!ata. "e can manually enter !ata into the te<t fiel! or we can set new !ata into that te<t fiel! from
co!e. 3oweverB we now have two !isparate concepts. "e have a potential +tring variable that we
may want to ?hol!? the value that is shown in the te<t fiel! an! we have the te<t fiel! itself.
%hanges to one or the other !o not reflect changes in the other. The two are out of synch.
+ee alsoK
Tutorial : 7sing ;ava>G Properties an! 2in!ing 8 9&:.913
Tutorial 8 7sing ;ava>G %ollections 8 91:.913
Tutorial 8 ;ava %ollections
Java6: Collections
Java6: !bservableList
This is an interface an! not a class so we canMt instantiate instances of this !irectly. "hat it
provi!es is a list into which items can be a!!e!B remove! an! iterate! over. 3owever where it
!iffers from an or!inary list is that it can have listeners a!!e! to it which will let us know when the
list changes. +ince this class also implements 6ava.util.*istB the metho!s on that interface may also
be use!.
The 5ACollectios ob6ect provi!es static constructors for most ;ava>G !ata types inclu!ing
observable list.
"hen changes are ma!e to an /bser6able+istB we can a!! a listener to be informe! of those
changes. The interface to the listener is +istChage+isteer. "hen the list is change!B the
listener is invoke! with a +istChage+isteer%Chage ob6ect that !escribes what has
change!.
Page .&&
To a!! a listener to an /bser6able+ist we can callK
,y/bser6able+ist%add+isteer3,y+istChage+isteer42
The +istChage+isteer re)uires that you implement a metho! calle! ?oChaged? to be
calle! when the list has change!. This looks likeK
public 6oid oChaged3+istChaged+isteer%Chage chage4 B
-- hadle the chage%
D
't is important to note that a change to the list nee! not be a single change. The change parameter
can contain one or more changes. "e must iterate through these changes using the e*t34
metho! of the Chage class.
'tems can be a!!e! to the list using the lists ?add34? metho!.
'nteresting metho!s of /bser6able+ist
add34 : A!! an item to the list
si)e34 : $eturn the size of the list
/a$a06 Controls
;ava>G provi!es a wealth of prebuilt controls. 3ere we will start to look at some of those available
to us. The controls can be foun! in the .a6a$*%scee%cotrol package.
Java6: $utton
The 2utton wi!get provi!es the classic button visualization. 't can be clicke! which will generate
an action that can be caught an! han!le!.
To a!! an image to the buttonB we can use the .
n!
parameter on the constructor which can be an
instance of an I,age:ie".
>or e<ampleK
Butto butto 0 e" Butto311C e" I,age:ie"3e"
I,age3getClass34%get7esourceAs#trea,31i,ages-play%pg144442
which woul! buil! a button that looks likeK
'f the button alrea!y e<ists Aperhaps it was a!!e! by +cene 2uil!erDB the image can be a!!e! using
the ?graphic? property.
"hen the button is presse!B its action event occurs. "e can register a listener for it using the
set/Actio34 metho!.
>or e<ampleK
,yButto%set/Actio3e" (6etHadler<Actio(6et>34 B
6oid hadle3Actio(6et e6et4 B
-- Hadler code here %%%
D
D42
+ee alsoK
;ava>G 'mageCiew
Page .&4
+tyling >G 2uttons with %%+
Java6: Check$o7
The CheckBo* wi!get provi!es a selectable checkbo<. The checkbo< may be in one of three
possible statesK
selected N true 8 The checkbo< is selecte!
selected N false 8 The checkbo< is not selecte!
ideter,iate N true 8 The checkbo< is in an in!eterminate state
Java6: Choice$o7
The choice bo< allows the user to pick from one of a set of possible values. The values are shown
in a !rop !own bo<. The single value selecte! is shown in the ChoiceBo* areaK
A property of the ChoiceBo* calle! ?ite,s? contains the items that are available within the
pull:!own. A property calle! ?6alue? contains the currently selecte! item.
To !etermine when a value changesB we can use
,yChoiceBo*%6alueProperty34%add+isteer33obser6ableC old:alueC e":alue4 -> B%%%D42
Java6: Color'icker
The %olorPicker component shows a combo:bo< button that hol!s the selecte! color. %licking this
button pro!uces a pull:!own where a color value can be selecte!.
Page .&(
Java6: Combo$o7
Java6: Hyperlink
A 3yperlink wi!get behaves like a button but looks like a browser link.
Java6: Image8ie%
The I,age:ie" wi!get Awhich is in package .a6a$*%scee%i,ageD !isplays an image.
The image can be supplie! on the I,age:ie" constructor.
Take care to not share I,age:ie"s between other components. -ach component will nee! its
own instance of an I,age:ie" because the same no!e in the scene graph can not occur in
multiple places.
An e<ample of creating an 'mageCiew instance might beK
I,age:ie" i,age:ie" 0 e" I,age:ie"3e"
I,age3#plash%class%get7esourceAs#trea,31i,ages-#plash%pg14442
+ee alsoK
6avaf<.scene.image.'mage
Java6: Label
The *abel wi!get shows a piece of te<t on the screen.
The value of the label can be accesse! through the ?te*t? property.
Page .&/
Java6: List8ie%
The +ist:ie" is a container for a list of items. 'f there are more items in the list than can be
shownB the list scrolls.
The items in the list can be set through the listMs ?ite,s? property which is an instance of an
?/bser6able+ist?.
'f we want to know which item in the list is selecte!B we can ask the list of its selection mo!el an!
from that mo!el ask for the selecte! in!e< or selecte! item.
>or e<ampleK
list%get#electoModel34%get#electedIde*342
'f we want to know when a selection changesB we can use the ?selectedIte,Property? of the
selection mo!el an! a!! a listener to it.
list%get#electioModel34%selectedIte,Property34%add+isteer3e" Chage+isteer V42
The Chage+isteer has a metho! calle! change!K
chaged3/bser6able<; e*teds <> obser6ableC < old:alueC < e":alue4
The visualization for an entry in the list is controlle! by the ?Cell5actory?. This is a property
on the *ist that can be set. ;ava>G provi!es some e<isting instances inclu!ingK
%heck2o<%ell*ist
%hoice2o<%ell*ist
%ombo2o<%ell*ist
Te<t>iel!%ell*ist
The !efault visualization of a list entry is simply the string representation of the item containe!
within. "e can !efine our own visualizer using the ?setCell5actory34? metho!. This
metho! takes a Callback34 ob6ect that must return an instance of a +istCell ob6ect. 't is this
ob6ect that is the visualization an! !escribes how to show !ata.
+ee alsoK
;ava>G 0bservable*ist
;ava>G Multiple+electionMo!el : 3ow items are selecte!
;ava>G *istCiew Tutorial : (
Java6: 'ass%ord6ield
The Pass"ord5ield wi!get is a te<t entry bo< which hi!es the characters type!.
Java6: 'rogress$ar
The ProgressBar wi!get shows the progress of some activity.
Page .49
Java6: 1adio$utton
The 7adioButto provi!es a selectable button where only one from a group may be selecte! at
one time.
Java6: eparator
The #eparator wi!get provi!es either a horizontal or vertical separator that can be use! to
partition visual sections into !ifferent parts.
Java6: lider
The #lider wi!get provi!es either a horizontal or a vertical ?sli!er? that can be use! to set values.
Java6: Table8ie%
-very wi!get set has to have a table an! ;ava>G is no e<ception. The table is represente! in
;ava>G through the control calle! ?<able:ie"?. This class has companion classes to assist with
the !escription of the table. These inclu!e <ableColu, an! <ableCell. "e canMt !escribe a
<able:ie" without also inclu!ing !escriptions of these ob6ects.
A <able:ie" contains a list property calle! ?colu,s? that is the list of columns shown within
the table. -ach entry in the list is an instance of a <ableColu, ob6ect.
The !ata boun! to the table is an instance of an /bser6able+ist. The property use! to bin! the
!ata to the table is ?ite,s?. The elements in the items properties constitute the rows of the table.
"hen a <able:ie" instance is create!B it is associate! with a specific classK
<able:ie"</b.ectClass>
This shoul! be rea! as ?"e are !efining a table where each row in the table is of type
</b.ectClass>?.
Now that we have the notion that we can bin! a list of ob6ects to a tableB how then !o these ob6ects
show upJ +ince we have the notion that a table is an array of table columnsB each column is
responsible for !isplaying its own !ata. Think of each column being calle! once for each row in the
table an! being responsible for how to visualize the cell that the column maps to the row.
"hen we !efine a <ableColu,B we are responsible for calling the
setCell:alue5actory34 metho!. This metho! !escribes how a row passe! to the column
will be ?e<amine!? an! use! to populate the appropriate cell.
't will take us some thought to un!erstan! this in all of its !etailB so we will take our time.
The parameter to the setCell:alue5actory34 is an instance of the ;ava>G Callback
interface. The notion here is that when a table asks a table column to visualize a cellB the table
column will invoke some registere! ?callback? function to !o the 6ob. The Callback interface
has one metho! calle! ?call34? that will be invoke! to !o the work.
The !eclaration of a Callback interface isK
Page .41
Callback<PC 7>
where P an! $ are ;ava class types. The ?P? parameter is the type of !ata passe! ?into? the
?call34? metho!. The ?7? parameter is the !ata type to be returne! ?from? the ?call34?
metho!.
$eturning now to the setCell:alue5actory34B we now un!erstan! that it wants a %allback
ob6ect as a parameter an! we now see that a %allback ob6ect nee!s to know its ?call34? input an!
output !ata types. +o what shoul! those be for a setCell:alue5actory34J The answer is
that the input to call will be an instance of ?<ableColu,%CellEata5eatures? an! the
return will be an ?/bser6able:alue?.
5ikesOO -ven more ob6ectsOO
>irstB the <ableColu,%CellEata5eatures. This ob6ect is !eclare! with the formatK
<ableColu,%CellEata5eatures<#C<>
where ?#? an! ?<? are ;ava class types.
The ?#? is the type of ob6ect containe! in the list of items shown in the table. +o if the table is use!
to show a list of ob6ects of type ?Perso?B then ?#? will be ?Perso?.
The ?<? is the type of the ob6ect that this specific column will !isplay. +o if the current column
were showing peopleMs namesB the ?<? type might be a ?#trig?.
>rom a <ableColu,%CellEata5eatures34 ob6ectB we can get three important pieces of
informationK
The reference to the <able:ie" that contains the column
The reference to the <ableColu, that is to be visualize!
The reference to the value of the current cell
+oB bringing it together againB the <ableColu,%CellEata5eatures provi!es the tableB
table column an! value of a specific cell. +ince this is passe! into the Callback associate! with
the setCell:alue5actory34B we now have an inkling of the relationship. This
<ableColu,%CellEata5eatures owns the !ata to be shown in a specific cellOO
$ather than simply 6ust return the !ata for the cell Aeg. a stringD from the %allbackMs call34
metho!B what we !o is return an /bser6able:alue. This allows us to up!ate the value of the
cellMs !ata an! the cell will ?automatically? up!ate itself.
3ere is an e<ample of putting it all togetherK
so,eClou,%setCell:alue5actory3e" Callback<<ableColu,%CellEata5eatures<#earch7esultC #trig>C
/bser6able:alue<#trig>>34 B
9/6erride
public /bser6able:alue<#trig> call3CellEata5eatures<#earch7esultC #trig> aCellEata5eatures4 B
retur e" #i,ple#trigProperty3aCellEata5eatures%get:alue34%get<askId3442
D
D42
The recipe above pre:!ates the arrival of ;ava ( with its *amb!a capabilities. This can now be
more succinctly co!e! asK
so,eClou,%setCell:alue5actory3aCellEata5eatures -> B
retur e" #i,ple#trigProperty3aCellEata5eatures%get:alue34%get<askId3442
D42
0ne more consi!eration relating to the setCell:alue5actory34 is the utility class calle!
Property:alue5actory34. This is a really cool class. 'ts constructor takes the name of a
Page .4.
fiel! as a parameter an! uses ?getFieldNameAD? an! ?setFieldNameAD? metho!s in the rows to getHset
the value of the cell.
>or e<ampleK
taskIdColu,%setCell:alue5actory3e" Property:alue5actory<>31taskId1442
assuming that the row has a get<askId34 an! a set<askId34 pair of metho!s.
"e can create a conte<t menu on a table by creating an instance of a Cote*tMeu an! setting
the cote*tMeu property of the table to this newly create! Cote*tMeu ob6ect. >or
e<ampleK
Cote*tMeu ,eu 0 e" Cote*tMeu342
MeuIte, ite, 0 e" MeuIte,31test142
,eu%getIte,s34%add3ite,42
table:ie"%setCote*tMeu3,eu42
The selection mo!el of a table is obtaine! through the ?selectioModel? property. This
returns an instance of a <able:ie"#electioModel.
The <ableColu, has a set of interesting properties inclu!ingK
6isible 8 +houl! the column be !isplaye!J
colu,s 8 ability to nest columns
sortable 8 's this column sortableJ
te*t 8 The hea!er of the column
pre$Width 8 The preferre! wi!th of the column Ain pi<elsD
The <able:ie" has some interesting properties tooK
placeholder 8 A no!e to be shown when there is no content in the table.
Cell9actor1
+o far we have assume! that the content of a cell is a te<t string however what if we want
something !ifferentJ "hat if we want to change the te<t color or font or something biggerB for
e<ample an image or a buttonJ 3ow can we go about thatJ
Previously we looke! at the metho! calle! setCell:alue5actory34. This returns the value
to be passe! to the cell. The cell then ren!ers this value at the appropriate location. There is
another metho! of interest to us calle! setCell5actory34. "hat this metho! !oes is register
how the cell itself is to be ren!ere! Anot 6ust the value for the cellD.
Again this function takes a Callback instance as a parameter which means that we will have to
implement the call34 metho!. The input to the call metho! isK
<ableColu,<RowClassCColumnClass>
$ememberB ?RowClass? is the class type of the rows in the <able:ie" an! ?ColumnClass?
is the class type for the content for cells in this column.
an! the return from call34 is
<ableCell<RowClassCColumnClass>
The <ableCell has an important property calle! graphic which is a ;ava>G No!e. This can
Page .43
be set to any no!es you like which will then appear in the table.
AgainB a <ableColu, has a Cell5actory an! a Cell5actory returns a <ableCell an!
a <ableCell knows how to ren!er a cell.
An e<ample of co!ing a setCell5actory34 woul! then beK
actiosColu,%setCell5actory3e" Callback<<ableColu,<#earch7esultC #trig>C<ableCell<#earch7esultC
#trig>>34 B
9/6erride
public <ableCell<#earch7esultC #trig> call3<ableColu,<#earch7esultC #trig> colu,4 B
$ial <ableCell<#earch7esultC #trig> cell 0 e" <ableCell<#earch7esultC #trig>342
Butto butto 0 e" Butto31Hello142
cell%set?raphic3butto42
retur cell2
D
D42
7sing ;ava ( *amb!asB we might have something likeK
lies<ableColu,%setCell5actory3tableColu, -> e" <ableCell<#trigC #trig>34 B
9/6erride
public 6oid updateIte,3#trig ite,C boolea e,pty4 B
super%updateIte,3ite,C e,pty42
i$ 3Pis(,pty344 B
set<e*t5ill3Color%B+ACM42
set#tyle3ull42
set5ot3$ot42
set<e*t3ite,42
D -- (d Pis e,pty
D -- (d o$ updateIte,
D42 -- (d o$ setCell5actory
<ableCell ob6ects are re:use!. There is not a <ableCell ob6ect for event cell in a column.
'nstea! the <able:ie" manages to create only those that are nee!e! to show the table.
*et us take a !ifferentB but e)ually vali! pass at !escribing the nature of the Table%ell.
'magine we have an array of !ata. That is illustrate! in the following image. o not confuse this
image with a table L it is meant to say we have an array of !ata.
Page .41
NowB let us concentrate on 6ust one columnK
AgainB so far so goo!. Now let us remin! ourselves that a table is a win!ow onto the !ata an! that
it is very common for a table to show only a subset of that !ata. "hat we have is a win!ow into
that !ata.
'f we think of 6ust one columnB we see that at any given timeB the table shows a set of cells where
each cell correspon!s to a column cell in the !ata. As the user sli!es the sli!erB some cells come
into view while others now fall outsi!e the win!ow.
The <ableCell ob6ect represents a visible cell in a column. As a new entry in the table becomes
visibleB the updateIte,34 metho! of the <ableCell is calle! which contains the value to be
shown in that cell in the table. "hen calle!B the <ableCell up!ates itself to reflect the new !ata
to be shown.
Editing a ta"le cell
+o far we have spoken e<clusively about using a table to show the !ata to the en! user without
consi!ering the notion that the user may wish to e!it the !ata. The <able:ie" provi!es the
capability to e!it the !ata as well as view it. To get starte!B one of the first things we have to !o is
Page .4#
to set the table to be e!itable. 2y !efaultB it is flagge! as not e!itable. "e can callK
,y<able%set(ditable3true4
to achieve this.
There is a lifecycle associate! with cell e!iting. "hen one has finishe! e!iting the cellB the
columnMs o(ditCo,,it34 callback is invoke!. This is responsible for har!ening the change
back to the !ata when the e!it completes.
To use this we woul! !efine a lamb!a callback such asK
,yColu,%set/(ditCo,,it33Cell(dit(6et<EataClassC Colu,Class> t4 -> B
-- 8pdate Eata
D42
0k L so how !o we know what to up!ateJ "ell the Cell(dit(6et class contains a wealth of
information getters inclu!ingK
get<able:ie"34 : The table view that was e!ite!
get<ablePositio34 : A <ablePositio that !efines a row an! a column
get!e":alue34 : The new value that was the result of the e!it
+o now we can !o things likeK
it chaged7o" 0 t%get<ablePositio34%get7o"342
Perso p 0 3Perso4t%get<able:ie"%getIte,s34%get3chaged7o"42
p%set!a,e3t%get!e":alue3442
+ome convenience e!itors are provi!e!K
<e*t5ield<ableCell 8 isplay a te<t input fiel!.
CheckBo*<ableCell 8 isplay a check bo< fiel!.
ChoiceBo*<ableCell 8 isplay a choice bo< showing a fi<e! set of options
%ombo2o<Table%ell
Progress2arTable%ell
+ee alsoK
;ava>G Multiple+electionMo!el
Tutorial 8 ;ava>G TableCiew
Ja$a96 Ta"le.iew : !etecting selections
The TableCiew contains a property calle! ?selectioModel? which can be retrieve! via
?get#electioModel34?. Through thisB we can register an interest in being tol! when a
selection change is ma!e.
>or e<ampleK
table:ie"%get#electioModel34%selectedIte,Property34%add+isteer33obser6ableC old:alueC e":alue4 ->
B
-- Hadler code here
D42
Ja$a96 Ta"le.iew : !1namic Columns
0n occasion we may wish to !ynamically a!! an! remove columns. >rom an instance of a
Page .4&
<able:ie" ob6ectB we can get an /bser6able+ist of <ableColu, items using the
getColu,s34 metho!.
Java6: Te7t&rea
The Te<tArea wi!get provi!es an area into which te<t may be entere!. 7nlike a Te<t>iel! wi!getB
the te<t area can accommo!ate multiple lines of !ata.
Among the properties for this class areK
pro,pt<e*t 8 A hint or prompt for the user on what to enter if the Te<tArea is empty.
+ee alsoK
;ava>G Te<t>iel!
Java6: Te7t6ield
The <e*t5ield allows one to enter a line of te<t.
This component can fire an Action-vent which happens when the -NT-$ key is presse!. Take
care that you realize that this is not the same as a content change.
'f we want to !etect a content changeB we nee! to get the ?te*t? property of the component an!
a!! a Chage+isteer to it.
>or e<ampleK
Chage+isteer<#trig> chage+isteer 0 e" Chage+isteer<#trig>34 B
9/6erride
public 6oid chaged3/bser6able:alue<; e*teds #trig> obser6ableC #trig old:alueC #trig
e":alue4 B
#yste,%out%pritl31<e*t ChageP142
D
D2
base87+<e*t5ield%te*tProperty34%add+isteer3chage+isteer42
Among the properties for this class areK
pro,pt<e*t 8 A hint or prompt for the user on what to enter if the <e*t5ield is
empty.
Page .44
Java6: Toggle$utton
The <oggleButto wi!get provi!es a button which can be in a ?checke!? or ?unchecke!? state
with visualization of that state.
Java6: Tooltip
't isnMt clear whether the Tooltip is a component or a container L so for right nowB we will consi!er
it a component until we have a better i!ea. The notion here is that a tooltip is a popup which will
show a!!itional information about something when the user hovers over an e<isting item.
Java6: Tree8ie%
The <ree:ie" is able to !isplay hierarchical !ata. 't is compose! of <reeIte, ob6ects.
<reeIte,s can have chil!ren as provi!e! by the childre property. 0ther instances of
<reeIte, can be a!!e! as chil!ren to buil! a tree structure.
The root of the <ree:ie" can be set with the ?root? property.
A <reeIte, within a <ree:ie" is visualize! by a <reeCell instance.
'f we wish to hi!e the root no!e of the treeB we can use the ?sho"7oot? property. +etting it to
false A!efault is trueD will hi!e the root no!e.
The icon to the left of the label can be an instance of an I,age:ie". 't is essential that a new
instance of an I,age:ie" be use! for each tree no!e. 5ou can not share an I,age:ie"
instance between no!es.
+ee alsoK
;ava>G 'mageCiew
%hapter 11 8 Tree Ciew
Java6: TreeTable8ie%
>irstB rea! an! un!erstan! the <ree:ie" an! <able:ie" controls. 0nce !oneB then come back.
The <ree<ableColu, !efines the columns shown in the table. 'ts type isK
<ree<ableColu,<#C <>
where # is the class type for the generic ob6ects in the !ata an! < is the type shown in the column.
+ee alsoK
;ava>G TreeCiew
%hapter 1# 8 Tree Table Ciew
Java6: Web8ie%
The "ebCiew wi!get provi!es an in:place web browser wi!get. >rom the "ebCiew we can ask
for a reference to the un!erlying "eb engine being use!. 't is from this ob6ect that we can perform
the browser functions of interest to us such as the loa!ing of a web page.
Page .4(
Associate! with a Web:ie" component is a parallel component calle! the Web(gie. 't is the
Web(gie that actually implements the browser an! the Web:ie" becomes the face of it. The
Web(gie associate! with a Web:ie" can be obtaine! through the get(gie34 metho!.
To loa! a page into the browserB one can call the Web(gie metho! calle! load34 passing in a
+tring 7$*. 'f the 3TM* we wish to loa! within the browser is local Ai.e. a simple +tringD then we
use the loadCotet34 metho!. This metho! also wants a cotet<ype parameter which is
the M'M- type of the content. Typically this is ?te*t-ht,l?.
2ecause a page loa! in the browser occurs asynchronouslyB we may wish to know when the page is
loa!e!. "e can !o this using the get+oadWorker34 metho! which returns a Worker instance.
Through this we can be notifie! of the workerMs state changes.
+houl! we nee! to set cookies on a web siteB the following may workK
Web:ie" "eb:ie" 0 e" Web:ie"342
87I uri 0 87I%create31http:--,ysite%co,142
Map<#trigC +ist<#trig>> headers 0 e" +ikedHashMap<#trigC +ist<#trig>>342
headers%put31#et-Cookie1C Arrays%as+ist31a,e06alue1442
.a6a%et%CookieHadler%getEe$ault34%put3uriC headers42
"eb:ie"%get(gie34%load31http:--,ysite%co,142
+ee alsoK
A!!ing 3TM* %ontent to ;ava>G Applications 8 .911:1
"eb,it
Calling Ja$aScript in the (e"Engine
"e can invoke ;ava+cript in the conte<t of the browser by using the "eb-ngineMs
e*ecute#cript34 metho!.
Calling Ja$a from the "rowser
0n occasionB we may wish ;ava+cript within the browser to call back into our ;ava>G application.
"e !o this with the J#/b.ect class ANote this is ;ava+cript 0b6ect an! not ;+0ND. >or e<ampleB
we may wish to get the ;ava+cript ob6ect that represents the browserMs ?"ido"? ob6ect within the
browser. To !o this we can useK
J#/b.ect "i 0 3J#/b.ect4 "eb(gie%e*ecute#cript31"ido"142
Now that we have this J#/b.ect instance we can use its own ?setMe,ber34? metho! to !efine
the ;ava class we wish to passK
"i%setMe,ber31*y)1C this42
This now allows us to call ;ava from the browser withK
<script>
*y)%,y5uctio31HelloP142
<-script>
'f ;ava+cript passes a ;ava+cript ob6ect to the ;ava classB it manifests as an instance of ;+0b6ect.
/a$a06 Menus
+ee alsoK
;ava>G Menus
Page .4/
Java6: Menu$ar
The menu bar is a container for menus. 't is typically seen at the top of an application. A property
of this class calle! ?,eus? will hol! a list of ?Meu? ob6ects. The te<t label of each menu will be
shown on the MeuBar.
+ee alsoK
;ava>G Menu
7sing ;ava>G %ontrols : 9/:.913
Java6: Menu
A ;ava>G menu represents a single menu.
Among its properties areK
te*t 8 The name shown to open the menu.
ite,s 8 A list of MeuIte,s to be shown within the menu.
+ee alsoK
;ava>G Menu2ar
;ava>G Menu'tem
Java6: MenuItem
A ;ava>G menu item represents an item within the menu.
Among its properties areK
te*t 8 The te<t to show on the menu item.
oActio 8 An event han!ler to call if this menu item is selecte!. This can be a lamb!a
function of the formatK
action-vent :R EF
There is a correspon!ing set0nActionAD metho! to set the event han!ler.
,euIte,%set/Actio3e6et -> B-Y code Y-D42
+ee alsoK
;ava>G Menu
Page .(9
Java6: CheckMenuItem
Java6: 1adioMenuItem
Java6: CustomMenuItem
Java6: eparatorMenuItem
Java6: Conte7tMenu
The Cote*tMeu is a menu container that can be poppe! up in !ifferent places. 't can have
MeuIte,s a!!e! to it. >or e<ampleB the following will a!! a menu to a <ree<able:ie"K
Cote*tMeu cote*tMeu 0 e" Cote*tMeu342
MeuIte, ,euIte, 0 e" MeuIte,31(*pad All142
cote*tMeu%getIte,s34%add3,euIte,42
,euIte, 0 e" MeuIte,31Collapse All142
cote*tMeu%getIte,s34%add3,euIte,42
tree<able:ie"%setCote*tMeu3cote*tMeu42
+ee alsoK
;ava>G Menu'tem
/a$a06 Containers
A container is a wi!get that provi!es encapsulation for other wi!gets. @enerally a container
governs the visibility an! placement of any chil!ren that may be a!!e! to it. Most container
wi!gets live in the .a6a$*%scee%layout package.
%ontainer always inherit from 6avaf<.scene.Parent.
Java6: &ccordion
The Accordio is a container which provi!es name! containers for other wi!gets. 0nly one of
those containers will be shown at a time while the other containers will be shown to e<ist by hea!er
areas. %licking on a hea!er area will reveal that container while hi!ing the previous container.
The chil!ren of an Accor!ion must be instances of Title!Pane.
Page .(1
Java6: &nchor'ane
Java6: $order'ane
Java6: 6lo%'ane
Java6: 9rid'ane
The @ri!Pane allows us to layout components within cells. The gri! contains rows an! columns.
-very cell in a single column will have the same wi!th but !ifferent columns can have !ifferent
wi!ths. +imilarlyB every cell in a single row will have the same height but !ifferent rows can have
!ifferent heights.
"e can specify both the horizontal an! vertical gaps between rowsHcolumns as well as the internal
pa!!ing for a cell.
+ee alsoK
"orking "ith *ayouts in ;ava>G : 9&:.913
Java6: H$o7
Java6: 'ane
Java6: 1egion
Java6: croll'ane
Java6: plit'ane
Java6: tack'ane
'n other 7' environmentsB a #tackPae shows a stack of top level containers where only one
container is shown at a time. 'n ;ava>GB the #tackPae is rather !ifferent. 'nstea!B what we
have is the notion that A** the chil!ren are shown simultaneously to each other overlaye! upon
each other. ' havenMt actually foun! a great use for this however we can make the #tackPae
behave as we suppose! it might )uite easily. 'f we make the imme!iate chil!ren of #tackPae
containers then we can set the visibility property of those containers to false in all cases other than
the one container we want to make visible.
0ne useful routine to work in this are is as followsK
public static 6oid setChild:isible3#trig a,eC Pae paret4 B
$or 3!ode child: paret%getChildre344 B
child%set:isible3a,e%eFuals3child%getId34442
D -- (d o$ $or loop
D -- (d o$ setChild:isible
Java6: Tab'ane
The TabPane is a container for multiple tabs. A tab is create! by a!!ing a Tab ob6ect into the list of
tabs returne! by getTabsAD.
Page .(.
Java6: Tile'ane
Java6: Titled'ane
Java6: 8$o7
/a$a06 %ther classes
Java6: 'opup
Java6: 'opupWindo%
/a$a06 #$ent 'andling
-vent han!ling is the notion that when a user interacts with ;ava>G componentsB they can fire
events. These events can then be caught be event listeners an! acte! upon. >or e<ampleB if we a!!
a button to our solutionB then the click of the button is meant to !rive some logic. This means that
we have to register the !esire! logic as a listener upon button click events.
The core to the story is the notion of the .a6a$*%e6et%(6et class. This class represents a
generic event an! can be subclasse! to create more specialize! versions. Among the core properties
of an event areK
-vent type 8 "hat kin! of event !oes this event represent
+ource 8 "ho originate! the event
Target 8 "ho is the target of the event
"hen we wish to register an event han!ler Athe co!e that catches the eventDB we can use the
add(6etHadler34 metho!. This takes two propertiesK
The type of the event we are watching for.
An instance of an (6etHadler to be given control when the event is !etecte!.
The type of event will be a subclass of (6et<ype
A class which can receive events implements the (6et<arget interface. This inclu!es all the
e<isting atomic components.
NowB let us get practical. *et us assume we want to create a new event calle! ?My(6et?. "e
coul! buil! this as followsK
public static class My(6et e*teds (6et B
pri6ate static $ial log serial:ersio8IE 0 L+2
public My(6et3(6et<ype<; e*teds My(6et> e6et<ype4 B
super3e6et<ype42
D
public static $ial (6et<ype<My(6et> A!N 0 e" (6et<ype<My(6et>3(6et%A!NC 1MN(:(!<142
public static $ial (6et<ype<My(6et> MN(:(!<@A 0 e" (6et<ype<My(6et>3My(6et%A!NC
1MN(:(!<@A142
D
Now if we wish to fire such an eventB we can callK
$ire(6et3e" My(6et3My(6et%MN(:(!<@A442
To catch this eventB we can useK
,yClass%add(6etHadler3My(6et%MN(:(!<@AC e" (6etHadler<My(6et>34 B
Page .(3
public 6oid hadle3My(6et ,y(6et4 B
-- +ogic here %%%
D
D
An! using lamb!aB this woul! beK
,yClass%add(6etHadler3My(6et%MN(:(!<@AC e6et -> B
-- code here that ca use e6et
D
D
+ee alsoK
3an!ling ;ava>G -vents 8 19H.913
-vent +ystem "alk:through
/a$a06 Lambda functions
"ith the arrival of ;ava ( an! the lamb!a function supportB we now have the opportunity to
simplify many types of event han!lers an! other functions with lamb!a interfaces.
ChangeListener
The interface function isK
iter$ace Chage+isteer<<> B
6oid chaged3/bser6able:alue<<> obser6ableC < old:alueC < e":alue42
D
which gives us a lamb!a function ofK
3obser6ableC old:alueC e":alue4 -> BVD
/a$a06 *tilities
;ava>G provi!es a number of classes that !onMt have a visual representation but are none:the:less
vital to ;ava>G operation.
Java6: MultipleelectionModel
This ob6ect represents what is selecte! within a selectable control such as a +ist:ie" or
<able:ie". 't also !efines whether or not the selection mo!e is single Aonly one thing may be
selecte!D or multiple Amany things may be concurrently selecte!D. The single vs multiple choice is
set by the ?selectionMo!e? property which may have a value of either +electionMo!e.+'N@*- or
+electionMo!e.M7*T'P*-.
'f there is no item selecte!B the returne! single in!e< is ?-L?.
+ee alsoK
;ava>G *istCiew
;ava>G TableCiew
;ava>G TreeTableCiew
/a$a06 De$elopment
Page .(1
cenic 8ie%
This is a ;ava>G application that interrogates the !ata of a running ;ava Application.
+ee alsoK
+cenic Ciew
!eleton /a$a06 0iles
ample application
This is the core of a ;ava>G application. 't assumes that an >GM* file !escribes the content an!
that the >GM* controller is also this class. 'n or!er to use it we shoul!K
%hange the class name
%reate an >GM* file that names this class as its controller
%hange the 5AM++oader%load34 call to point to the newly create! >GM* file
'mplement any logic in the iitiali)e34 function that is calle! when the controller is
starte!
-nsure that any ;ava pro6ect that contains ;ava>G also has the .$*rt%.ar on the pro6ectMs
buil! path
package co,%kolba2
i,port .a6a$*%applicatio%Applicatio2
i,port .a6a$*%$*,l%5AM+2
i,port .a6a$*%$*,l%5AM++oader2
i,port .a6a$*%scee%Paret2
i,port .a6a$*%scee%#cee2
i,port .a6a$*%stage%#tage2
-YY
Y 9author !eil Molba 3kolba9us%ib,%co,4
Y 96ersio I>LS->'->'
Y-
-- Chage class a,e
public class #a,pleApp e*teds ApplicatioB
public static 6oid ,ai3#trigQR args4 B
lauch3args42
D
9/6erride
public 6oid start3#tage stage4 thro"s (*ceptio B
-- Chage 5AM+ $ile a,e ad locatio
Paret root 0 5AM++oader%load3getClass34%get7esource31$*,l-#a,ple%$*,l1442
#cee scee 0 e" #cee3rootC H>>C S>>42
stage%set#cee3scee42
stage%sho"342
D
95AM+
pri6ate 6oid iitiali)e34 B
D -- (d o$ iitiali)ed
D -- (d o$ class
-- (d o$ $ile
ample Component
A component is a buil!ing block in the ;ava>G architecture. 't is common for us to want to create
Page .(#
new components. 3ere is a skeleton class for 6ust a component. This class both loa!s the >GM* to
create the meat of the component as well as acting as the controller for the component. 'n or!er to
use it we shoul!K
$ename the class to be the name of the component we wish to !efine.
Point to the correct >GM* file
o not inclu!e a controller !efinition in the >GM* file
efine the root of the >GM* file as Qf<KrootR
package co,%kolba2
i,port .a6a$*%$*,l%5AM+2
i,port .a6a$*%$*,l%5AM++oader2
i,port .a6a$*%scee%layout%AchorPae2
-YY
Y
Y 9author !eil Molba 3kolba9us%ib,%co,4
Y 96ersio I>LS->'->S
Y-
public class #a,pleCo,poet e*teds AchorPae B
-YY
Y ?eeral costructor $or this co,poet%
Y-
public #a,pleCo,poet34 B
5AM++oader $*,l+oader 0 e" 5AM++oader3getClass34%get7esource31$*,l-#a,pleCo,poet%$*,l1442
$*,l+oader%set7oot3this42
$*,l+oader%setCotroller3this42
try B
$*,l+oader%load342
D catch 3(*ceptio e4 B
e%prit#tack<race342
D
D -- (d o$ #a,pleCo,poet
-YY
Y Iitiali)e the co,poet%
Y-
95AM+
pri6ate 6oid iitiali)e34 B
-- Code here
D -- (d o$ iitiali)e
D -- (d o$ class
-- (d o$ $ile
/a$a06 9
rd
Party Pacages
Controls6:
%ontrols>G is a collection of components for ;ava>G. 't can be foun! hereK
httpKHHf<e<perience.comHcontrolsf<H
org)controlsfx)dialog)!ialogs
Arguably one of the most compelling features of this package is the rich set of !ialogs that it
provi!es. To best un!erstan! the !ialogB imagine it broken into a set of partsK
title 8 The area on the title bar of the !ialog
Page .(&
,asthead 8 An area that is optional an! imme!iately below the title
graphic 8 A graphic image containe! within the masthea!
cotet 8 The primary content of the !ialog
butto bar 8 A set of buttons to close the !ialog
A set of pre:engineere! !ialogs have been buil!K
I$or,atio : show'nformationAD
Co$ir,atio : show%onfirmAD
Warig : show"arningAD
(rror : show-rrorAD
(*ceptio : show-<ceptionAD
<e*t Iput : showTe<t'nputAD
Choice Iput : show%hoicesAD
Co,,ad +ik : show%omman!*inksAD
5ot #elector : show>ont+electorAD
Progress : show"orkerProgressAD
+ee alsoK
%ontrols>G "eb +ite
org)controlsfx)dialog)!ialog
This class provi!es the base of a ialog. 't is the most general purpose an! what is commonly use!
to show user built !ialogs.
The buttons in the !ialog are not set by !efault. 5ou can a!! your own buttons by a!!ing to the list
of Actions obtaine! through ialogMs getActios34. A set of pre!efine! Actions are available
asK
Eialog%Actios%CA!C(+ 8 +hows a cancel button
Eialog%Actios%C+/#( 8 +hows a close button
Eialog%Actios%!/ 8 +hows a no button
Eialog%Actios%/M 8 +hows an ok button
Eialog%Actios%N(# 8 +hows a yes button
"hen the ialogMs sho"34 metho! is calle! it shows the !ialog an! blocks waiting for the !ialog
to be !ispose!. The return from sho"34 is an Actio instance that !escribes the reason that the
!ialog was complete!. "e can compare this Action against the possible actions to figure out which
ones were returne!.
A suggeste! recipe for buil!ing an instance of the !ialog isK
1. %reate an >GM* file that will be use! as the content of the !ialog. Make sure that it !oes
not use the ?$*:root? construct.
Page .(4
.. %reate a class that e<ten!s org%cotrols$*%Eialog.
3. %reate a !efault constructor that calls load34 Asee followingD
%all the super constructor 8 eg. super3ullC 1My Eialog <itle142
+et resi)able3$alse4.
A!! actionsK
getActios34%add3Actios%/M42
getActios34%add3Actios%CA!C(+42
1. %reate an >GM* iitiali)e34 for the >GM*
The load34 metho! will loa! an >GM* that contains the ?content? area for the ialog
private voi! loa!AD E
>GM**oa!er f<ml*oa!er N new >GM**oa!erAget%lassAD.get$esourceA?f<mlH+ettings.f<ml?DDU
f<ml*oa!er.set%ontrollerAthisDU
try E
f<ml*oa!er.loa!ADU
set%ontentAf<ml*oa!er.get$ootADDU
F catch A-<ception eD E
e.print+tackTraceADU
F
F HH -n! of loa!AD
Apache 2//P Server
The Apache 3TTP server is an open source implementation of a "eb +erver. The home page for
the pro6ect can be foun! hereK
httpKHHhttp!.apache.orgH
2inaries of the pro!uct can be foun! hereK
httpKHHwww.apachelounge.comH!ownloa!H
+ome of the core configuration options inclu!eK
#er6er7oot 8 A !irectory path on the machine where http! is installe! which is the root
of the install.
+iste 8 The T%PH'P port number on which the server is listening.
Eocu,et7oot 8 A !iretory path on the machine where httpd is installe! which is the
root of the web hoste! files.
+ee alsoK
ocumentation 8 ..1
!etting up a pro5y
The http! pro<y is configure! with the mo!ulesK
mo!Ipro<y
mo!Ipro<yIhttp
-!it the http!.conf configuration file an! remove the ?[? comment marker from the start of the lines
which rea!K
Page .((
[*oa!Mo!ule pro<yImo!ule mo!ulesHmo!Ipro<y.so
[*oa!Mo!ule pro<yIhttpImo!ule mo!ulesHmo!Ipro<yIhttp.so
$everse pro<y is controlle! by the ?Pro<yPass? !irective.
The ?Pro<y$e)uests? !irective is either ?0n? or ?0ff?.
-<ample pro<yK
Pro<yPass HrestHbpmHmonitorH httpKHHlocalhostK/9(#HrestHbpmHmonitorH
Pro<yPass H httpKHHlocalhostK(9(9H
&l! Stuff
Deployment 2nvironments
Si2ing the Screen
The size of the content within the application is governe! by %++. 'n your !eployment
environmentMs %++B consi!er setting the ?[content? styling. >or e<ampleK
Zcotet B
height: auto2
,argi: > auto2
"idth: auto2
D
Worklight &dapters
"orklight applications provi!e user interfaces that run on the mobile !evices an! are serve! by the
"orklight server. 'n or!er to allow these client applications to make calls to service provi!ersB '2M
provi!es the concept of "orklight a!apters. An a!apter is a component !efine! to run on the
"orklight server which receives re)uests from the client 7' applications an! routes them correctly
to the back:en! services.
+ee AlsoK
eveloper"orks : evelop "orklight a!apters with ATST mobile AP's : .913:91:9&
eveloper"orks : -rror han!ling in '2M "orklight a!apters : .91.:1.:9#
HTTP Adapter
PropertiesK
metho! getB postB putB !eleteB hea!
path value
returne!%ontentType 6sonB cssB csvB 6avascriptB plainB <mlB html
returne!%ontent-nco!ing enco!ing
parameters ELF
hea!ers ELF
cookies ELF
bo!y
contentType te<tH<ml or similar
content
Page .(/
transformation
type !efaultB <sl>ile
<sl>ile file name
To invoke an a!apter we create an ob6ect which contains an invocations0ptions ob6ectK
a!apter The name of the a!apter to invoke
proce!ure The name of the proce!ure to invoke
parameters An array of parameters
Ne<t we can call the "*.%lient.invokeProce!ureAinvocation0ptionsB result0ptionsD function.
on+uccess
on>ailure
invocation%onte<t
>or the callback functions the on+uccess ob6ect containsK
invocation%onte<t
status
invocation$esult
3ere is an e<ample of buil!ing an a!apter that e<ecutes a 2PM $-+T re)uest. 'n this e<ampleB we
want to get a list of Process Apps. The call to achieve this is a @-T re)uest
to?HrestHbpmHwleHv1HprocessApps?.
"e start by creating a new "orklight A!apterK
"e say that it will be an 3TTP A!apter an! give it the name ?2PM$est?K
Page ./9
The creation of a "orklight a!apter a!!s some sample Proce!ures so we !elete those. Ne<tB in the
%onnection Policy we !efine the host:name an! port on which our 2PM server will be listeningK
Now we are going to !efine some authentication parameters by a!!ing a new entry of type
?Authentication?K
Page ./1
"e can supply our security cre!entials ne<t. These will be the cre!entials use! to access the serverK
Ne<t we !efine which type of +ecurity protocol will be use!K
"e select ?2asic?. The final %onnectivity settings look as followsK
Page ./.
Now we are rea!y to a!! our first proce!ureK
"e provi!e a name an! a !isplay name for our Proce!ureK
Page ./3
"e can now implement the co!e in the ;ava+cript implementation file that will ?back? the
Proce!ure. "e e!it the file calle! ?2PM$est:impl.6s?K
An! that is the en! of our !evelopment. "e are now rea!y to test the A!apter.
Page ./1
Ne<t we select the Proce!ure calle! ?processApps? an! run itK
Page ./#
After a few momentsB we will see the result of the $-+T )ueryK
"hat we are seeing is the ;+0N result from invoking the $-+T AP' against the '2M 2PM runtime.
+ee AlsoK
!eveloper"orks : 7sing '2M "orklight 3TTP A!apters with $-+TH;+0N +ervices : .91.:9&:.4
Page ./&
Worklight ecurity
The mo!el of "orklight security is that we !efine an ?authentication realm?. Think of this as a
name! set of steps to authenticate users. -ach realm is compose! of one ?Authenticator? an! one
?*ogin Mo!ule? which are components foun! on the server.
"orklight comes with pre!efine! authenticators inclu!ingK
form base! 8 co,%"orklight%core%auth%e*t%5or,BasedAutheticator
a!apter base! 8 co,%"orklight%itegratio%auth%AdapterAutheticator
3TTP hea!er base!
%ustom authenticators can be built in ;ava. Authenticators are !efine! in the realm by class names.
The *ogin Mo!ule is use! to verify the user cre!entials an! creates a ?user i!entity? ob6ect that
hol!s the userMs properties for the remain!er of the session.
*ogin mo!ules provi!e! by '2M inclu!eK
"eb service calls
atabase look calls
"eb+phere *TPA tokens
Non vali!ating 8
co,%"orklight%core%auth%e*t%!o:alidatig+ogiModule
"orklight also intro!uces the concept of a ?+ecurity Test?. This is an or!ere! collection of
?authentication realms? that shoul! be use! to vali!ate that a user can access a resource.
uring access to a resourceB if the i!entity of the user is unknownB a ?challenge? is issue!. This is
where the user presents their claim an! proof of who they are. Typically this is a useri!Hpasswor!
combination. The challenge is performe! by a ?%hallenge 3an!ler?. The challenge han!ler gathers
these from the user an! then invokes the Authenticator. The Authenticator then passes this
information to the *ogin mo!ule which performs the actual vali!ation of the userMs i!entity an!
buil!s the ?user i!entity? ob6ect.
A challenge han!ler can be create! with
W+%Cliet%createChallegeHadler31real,-a,e14.
+ecurity is configure! in the autheticatioCo$ig%*,l file that is foun! in the pro6ectMs
ser6er-co$ fol!er. This is a plain GM* file.
An a!apter implementation can use the W+%#er6er%getActi6e8ser34 to obtain a security
user ob6ect.
<real, a,e01My7eal,1 logiModule01My+ogiModule1>
<class!a,e>co,%"orklight%itegratio%auth%AdapaterAutheticator<-class!a,e>
<para,eter a,e01logi-$uctio1 6alue01MyAdapter%oAuth7eFuired1 ->
<para,eter a,e01logout-$uctio1 6alue01MyAdapter%o+ogout1 ->
<-real,>
+ee alsoK
+ection (K Authentication an! security 8 '2M presentations an! samples
'esearch 0uestions
Page ./4
"hat is the I"i!get2ase ?ownAD? metho!J
Page ./(