cover
Front cover
Mobile Application
Development with IBM
Worklight V6 - Early
Education
(Course code WU506)
Student Notebook
ERC 1.1
Student Notebook
Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International
Business Machines Corp., registered in many jurisdictions worldwide.
The following are trademarks of International Business Machines Corporation, registered in
many jurisdictions worldwide:
AIX
Cast Iron
Domino
Lotus
Rational
AS/400
DB
FileNet
Notes
Redbooks
BigFix
DB2
Lotus Notes
PureApplication
WebSphere
Intel and Pentium are trademarks or registered trademarks of Intel Corporation or its
subsidiaries in the United States and other countries.
Lenovo and ThinkPad are trademarks or registered trademarks of Lenovo in the United
States, other countries, or both.
Linux is a registered trademark of Linus Torvalds in the United States, other countries, or
both.
Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other
countries, or both.
Java and all Java-based trademarks and logos are trademarks or registered trademarks
of Oracle and/or its affiliates.
VMware and the VMware "boxes" logo and design, Virtual SMP and VMotion are registered
trademarks or trademarks (the "Marks") of VMware, Inc. in the United States and/or other
jurisdictions.
Worklight is a trademark or registered trademark of Worklight, an IBM Company.
Other product and service names might be trademarks of IBM or other companies.
V8.1
Student Notebook
TOC
Contents
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii
Course description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv
Agenda . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvii
Unit 1. Mobile overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
1.1. Becoming a mobile enterprise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Becoming a mobile enterprise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6
Why go mobile? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7
Demand for mobility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8
Mobile platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9
1.2. Challenges of mobile application development, management and security . . . . . 1-11
Challenges of mobile application development, management and security . . . . . 1-12
Considerations for mobile (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-13
Considerations for mobile (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14
Advantages of mobile communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-15
Characteristics of mobile interactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-16
1.3. Types of mobile applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-17
Types of mobile applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-18
The choice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-19
Development approaches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-20
Native compared to hybrid applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21
Web standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-22
SOA to mobile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-23
1.4. Overview of IBM mobile strategy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-25
Overview of IBM mobile strategy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-26
IBM MobileFirst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-27
IBM MobileFirst portfolio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-28
1.5. IBM Mobile Foundation V6.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-29
IBM Mobile Foundation V6.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-30
IBM MobileFirst platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-31
IBM Mobile Foundation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-33
IBM Worklight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-34
WebSphere Cast Iron Hypervisor Edition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-36
IBM Endpoint Manager for Mobile Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-37
Checkpoint questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-38
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-39
Checkpoint answers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-40
Unit 2. Designing mobile solutions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Contents
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
iii
Student Notebook
Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-3
Three approaches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-4
Web, hybrid, native... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-5
2.1. Approaches to mobile design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-7
Approaches to mobile design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-8
Native applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-9
Creating a native application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-10
Mobile-web Applications - HTML5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-11
Mobile-web Applications - CSS3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-12
Mobile-web Applications - JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-13
Mobile web applications - mobile web sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-14
Hybrid applications (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-15
Hybrid applications (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-17
2.2. Comparison of mobile application designs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-19
Comparison of mobile application designs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-20
Native - advantages and disadvantages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-21
Web application - advantages and disadvantages . . . . . . . . . . . . . . . . . . . . . . . . .2-22
Hybrid applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-23
Comparison of features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-24
2.3. Choosing the right approach. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-25
Choosing the right approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-26
Scenario - the native approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-27
Scenario - the web approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-28
Scenario - the hybrid approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-29
Checkpoint questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-30
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-31
Checkpoint answers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-32
Unit 3. Introduction to IBM Worklight v6.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-2
Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-3
3.1. IBM Worklight component architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-5
IBM Worklight component architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-6
Worklight components - overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-7
Worklight Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-8
Worklight Studio plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-9
Worklight Studio design perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-10
Shell components and inner applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-11
Worklight server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-12
Server customization components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-13
worklight.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-14
authenticationConfig.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-15
Deploying applications and adapters to the server . . . . . . . . . . . . . . . . . . . . . . . . .3-16
Device runtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-17
Application distribution and update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-19
Push notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-20
Worklight console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-21
Worklight console - catalog tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-22
iv
V8.1
Student Notebook
TOC
3-23
3-24
3-25
3-27
3-28
3-29
3-30
3-31
3-32
3-33
3-34
3-35
3-37
3-38
3-39
3-40
3-41
3-42
3-43
3-44
3-45
3-46
3-48
3-49
3-50
3-51
3-53
3-54
3-55
3-57
3-58
3-59
3-60
3-61
3-63
3-64
3-65
3-66
3-67
3-68
3-69
3-70
Contents
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
4-1
4-2
4-3
4-5
v
Student Notebook
4.2.
4.3.
4.4.
4.5.
4.6.
vi
V8.1
Student Notebook
TOC
Contents
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
5-1
5-2
5-3
5-5
5-6
5-7
5-8
vii
Student Notebook
5.2.
5.3.
5.4.
5.5.
viii
V8.1
Student Notebook
TOC
getNetworkInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Foreground event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Worklight heartbeat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.6. String translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
String translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction to translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enabling translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Translating system messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Multi-language translation: set up the Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Multi-language translation: selecting the language . . . . . . . . . . . . . . . . . . . . . . . .
Detecting device locale and language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Checkpoint questions (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Checkpoint questions (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Checkpoint answers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exploring IBM Worklight client-side APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exercise objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5-61
5-63
5-64
5-65
5-66
5-67
5-69
5-71
5-72
5-73
5-74
5-76
5-77
5-78
5-79
5-80
5-81
Contents
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
ix
Student Notebook
V8.1
Student Notebook
TOC
7-25
7-26
7-27
7-28
7-29
7-30
7-31
7-32
7-33
7-34
Contents
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
xi
Student Notebook
V8.1
Student Notebook
TOC
Contents
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
9-43
9-44
9-46
9-47
9-48
9-49
9-50
9-51
9-52
9-53
9-55
9-56
9-57
9-58
9-59
9-61
9-62
9-63
9-64
9-65
9-66
9-67
9-68
9-69
9-70
9-71
9-72
9-73
9-74
9-75
9-77
9-78
9-79
9-80
9-82
9-84
9-85
9-87
9-88
9-89
9-91
9-92
9-93
9-94
9-95
9-96
9-97
9-98
xiii
Student Notebook
V8.1
Student Notebook
TOC
11-19
11-20
11-21
11-22
11-24
11-25
11-26
11-27
11-28
11-29
11-30
11-31
11-32
Contents
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
xv
Student Notebook
V8.1
Student Notebook
TOC
Contents
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
14-1
14-2
14-3
14-4
xvii
Student Notebook
V8.1
Student Notebook
TOC
16-14
16-15
16-16
16-17
16-18
16-19
16-21
16-22
16-23
16-24
16-25
16-26
16-27
16-28
16-29
16-31
16-33
16-34
16-35
16-36
16-37
16-38
16-39
16-40
16-41
16-42
16-43
16-44
Contents
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
xix
Student Notebook
V8.1
Student Notebook
TOC
19-1
19-2
19-3
19-4
19-5
Contents
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
xxi
Student Notebook
xxii
V8.1
Student Notebook
TMK
Trademarks
The reader should recognize that the following terms, which appear in the content of this
training document, are official trademarks of IBM or other companies:
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International
Business Machines Corp., registered in many jurisdictions worldwide.
The following are trademarks of International Business Machines Corporation, registered in
many jurisdictions worldwide:
AIX
Cast Iron
Domino
Lotus
Rational
AS/400
DB
FileNet
Notes
Redbooks
BigFix
DB2
Lotus Notes
PureApplication
WebSphere
Intel and Pentium are trademarks or registered trademarks of Intel Corporation or its
subsidiaries in the United States and other countries.
Lenovo and ThinkPad are trademarks or registered trademarks of Lenovo in the United
States, other countries, or both.
Linux is a registered trademark of Linus Torvalds in the United States, other countries, or
both.
Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other
countries, or both.
Java and all Java-based trademarks and logos are trademarks or registered trademarks
of Oracle and/or its affiliates.
VMware and the VMware "boxes" logo and design, Virtual SMP and VMotion are registered
trademarks or trademarks (the "Marks") of VMware, Inc. in the United States and/or other
jurisdictions.
Worklight is a trademark or registered trademark of Worklight, an IBM Company.
Other product and service names might be trademarks of IBM or other companies.
Trademarks
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
xxiii
Student Notebook
V8.1
Student Notebook
pref
Course description
Mobile Application Development with IBM Worklight V6 - Early
Education
Duration: 4 days
Purpose
In this 4-day instructor-led course, you learn how to use IBM Worklight
V6 to develop mobile applications that run on an Android or iOS*
environment.
Audience
This course is designed for application developers who want to create,
manage, and deploy mobile applications to Android and iOS* mobile
environments by using IBM Worklight V6.
Prerequisites
Before taking this course, you should have experience in Java or web
development with Eclipse, and a good knowledge of the following web
technologies:
HTML5
JavaScript
Cascading Style Sheets (CSS) 3
Web UI frameworks, such as Dojo or jQuery
Representational State Transfer (REST) services
Web services
A basic knowledge of a mobile web UI framework, such as Dojo
Mobile, is helpful.
Objectives
After completing this course, you should be able to:
Identify a mobile application design type suitable for your
application
Develop a mobile application to run on an Android or iOS platform
using the IBM Worklight hybrid coding approach
Copyright IBM Corp. 2013
Course description
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
xxv
Student Notebook
Curriculum relationship
VU506 Mobile Application Development with IBM Worklight V6 Early Education (online)
ZU506 Mobile Application Development with IBM Worklight V6 Early Education (self-paced)
V8.1
Student Notebook
pref
Agenda
Day 1
Welcome
Unit 1 - Mobile overview
Unit 2 - Designing mobile solutions
Unit 3 - Introduction to IBM Worklight V6
Unit 4 - Overview of Worklight Studio
Exercise 1- Installing IBM Worklight Studio and developing your first
application
Unit 5 - IBM Worklight client-side development: Core APIs
Day 2
Exercise 2 - Exploring client-side core APIs
Unit 6 - IBM Worklight client-side development: Local storage APIs
Exercise 3 - Exploring local storage APIs
Unit 7 - Working with UI frameworks
Unit 8 - Apache Cordova
Exercise 4 - Using Apache Cordova to access native device functions
Unit 9 - Worklight integration adapters
Day 3
Exercise 5 - Developing a Worklight integration adapter
Unit 10 - Native and web page integration
Exercise 6 - Combining native and web pages
Unit 11 - Using Worklight native APIs
Unit 12 - Security
Exercise 7 - Securing an application
Unit 13 - Push notification
Agenda
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
xxvii
Student Notebook
Day 4
Exercise 8 - Exploring the push notification API
Unit 14 - Device analytics reporting
Unit 15 - Direct update
Unit 16 - Migrating an application from development to production
Unit 17 - Shell development
Unit 18 - IBM Worklight Application Center
Exercise 9 - Exploring the Application Center
V8.1
Student Notebook
Uempty
References
IBM MobileFirst strategy http://www.ibm.com/mobilefirst/us/en/
Whitepaper: The New Workplace - Are you Ready?
ftp://public.dhe.ibm.com/software/info/mobile/CIW03077USEN.pdf
The 2012 IBM Tech Trends Report
ftp://public.dhe.ibm.com/common/ssi/ecm/en/xie12346usen/XIE12346
USEN.pdf
1-1
Student Notebook
Unit objectives
After completing this unit, you should be able to:
Describe what it means to become a mobile enterprise
Explain the challenges of mobile application development,
management, and security
Describe the goal of IBMs mobile solution offerings
Identify IBM Worklight V6.0 as a key part of IBMs mobile solutions
strategy
WU5061.1
Notes:
1-2
V8.1
Student Notebook
Uempty
Topics
Becoming a mobile enterprise
Challenges of mobile application development, management, and
security
Types of mobile applications
Overview of IBM mobile strategy
IBM Mobile Foundation V6.0
WU5061.1
Notes:
1-3
Student Notebook
1-4
V8.1
Student Notebook
Uempty
1-5
Student Notebook
Becoming a mobile
enterprise
WU5061.1
Notes:
1-6
V8.1
Student Notebook
Uempty
Why go mobile?
Take advantage of new opportunities present with mobile
Attract new customers through mobile
Deliver engaging apps; delight customers
Increase collaboration & productivity among employees
Provide a consistent brand experience across channels
Optimize for multiple devices and BYOD*
Use technologies to meet increased demands
Gain new insights that you can get only through mobile
WU5061.1
Notes:
Note
*BYOD: bring your own device.
1-7
Student Notebook
WU5061.1
Notes:
*The 2012 IBM Tech Trends Report
ftp://public.dhe.ibm.com/common/ssi/ecm/en/xie12346usen/XIE12346USEN.pdf
1-8
V8.1
Student Notebook
Uempty
Mobile platforms
Android emerged as the main platform for mobile development,
followed by iOS*
Android
74.4%
iOS
18.2%
Windows Phone
2.9%
BlackBerry
3%
Others
1.6%
WU5061.1
Notes:
*Gartner report - Market Share Analysis: Mobile Phones, Worldwide, 1Q13.
http://www.gartner.com/document/2482415?ref=QuickSearch&sthkw=G00252860
1-9
Student Notebook
V8.1
Student Notebook
Uempty
1-11
Student Notebook
Challenges of mobile
application
development,
management, and
security
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
1-13
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
B2E
Mobile access makes employees more productive
What do you think?
M2M
Machine to machine
For example:
Truck on the road transmits and receives information from a central point
Car sends an automatic request for assistance in case of accident or driver
illness
Airplane exchanges information with ground computers
WU5061.1
Notes:
1-15
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
1-17
Student Notebook
Types of mobile
applications
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
The choice
Web application
HTML5
CSS3
JavaScript
Native
code
HTML5
CSS3
JavaScript
Native
code
Hybrid
application
Native
application
WU5061.1
Notes:
1-19
Student Notebook
Development approaches
Web
application
Mobile web
application
Desktop and
mobile using
open standards
programming
model
Targets mobile
devices that
use open
standards web
client
programming
model
No devicespecific
function
Offline
capabilities
Hybrid mobile
application
Mobile only
Application runs
on the device
Uses of an open
web client model
with a JavaScript
bridge to access
native device
features
Native mobile
application
Mobile using
only native
languages
Native
appearance,
device
capabilities, and
performance
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Hybrid:
Uses web technologies
HTML5 for the layout
CSS3 for the style
JavaScript for functionality and to access native features of the device
For example, camera, vibrate, location, events
Some knowledge of the specific platform is needed
Distributed through an App Store
Requires a licensing agreement
WU5061.1
Notes:
1-21
Student Notebook
Web standards
HTML5
A major update from HTML 4.2
Aimed at standard web applications and offline applications
Greatly extended audio and video capabilities
Canvas
Form validation
CSS3
The focus is on putting style information into the Cascading Style Sheet rather
than into the page
Many html style attributes are deprecated in favor of using CSS
JavaScript
Standard way to define functions for an interactive web page, plus some new
features targeting mobile:
Geolocation
Web storage
Copyright IBM Corporation 2013
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
SOA to mobile
SOA
BPM
JEE
Enterprise
services
Business
services
RESTful
services
Business
process
JAX-RS
Components
Java EE
Process
data
Application
data
Mobile
web 2.0
Services
Enterprise
data
WU5061.1
Notes:
1-23
Student Notebook
V8.1
Student Notebook
Uempty
1-25
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
IBM MobileFirst
Mobile is becoming the first point of contact between an individual and
an organization
Mobile interactions must be instant, seamless, and insightful
The systems that users interact with must be designed around mobile
first
WU5061.1
Notes:
1-27
Student Notebook
Management:
IBM Endpoint Manager for Mobile Devices
Mobile Enterprise Services for Managed Mobility
Security
Analytics:
IBM Tealeaf CX Mobile
IBM Digital Analytics
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
1-29
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
IBM MessageSight
IBM Mobile Development Lifecycle Solution
IBM Rational Test Workbench
IBM Web Experience Solutions
IBM Lotus Domino Designer
IBM WebSphere MQ
WU5061.1
Notes:
IBM Mobile Foundation Enhanced
Delivers a range of application development, connectivity and management capabilities.
Bundled with IBM Worklight, IBM WebSphere Cast Iron, and IBM Endpoint Manager for
Mobile Devices.
IBM Worklight Enhanced
An open, mobile application platform for smartphones and tablets. Develop, run and
manage HTML5, hybrid, and native applications.
IBM WebSphere Cast Iron
An integration framework that enables you to rapidly connect your hybrid world of public
clouds, private clouds, and on-premise applications.
IBM MessageSight
Messaging appliance specifically designed for machine-to-machine (M2M) and mobile
environments that is optimized for message throughput.
Copyright IBM Corp. 2013
1-31
Student Notebook
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
Worklight was acquired by IBM in 2011.
BigFix was the name of a company acquired by IBM in July 2010.
Cast Iron was acquired by IBM in May 2010.
1-33
Student Notebook
IBM Worklight
Supports multiple mobile operating environments and devices by using
a single, shared code base
Standards-based platform
Build once, deploy to many platforms
Faster deployment across multiple channels
WU5061.1
Notes:
Supports multiple mobile operating environments and devices with the simplicity of
a single, shared code base
Standards-based platform allows you to leverage the growing ecosystem of third-party
libraries and frameworks
Build once, deploy to many platforms
Create mobile and omni-channel applications more quickly using any combination of
HTML5, native and hybrid development methods
Support Android, iOS, Blackberry, Windows Phone, Windows 8, Java ME, mobile Web
and desktop Web environments
Runtime skins optimize the user experience for hundreds of different devices
Easily connect and synchronize with enterprise data, applications and cloud
services
V8.1
Student Notebook
Uempty
Connect to back-end data, applications and cloud services more easily, making the
most of standards-based technologies
Transform enterprise data into mobile-friendly, JSON format that can be synchronized,
encrypted, and stored locally on mobile devices
Leverage advanced mobile middleware for caching, data synchronization, and
end-to-end encryption of data
Safeguard mobile security at the device, application, and network layer
Protect sensitive information from malware attacks and device theft
Ensure timely propagation and adoption of critical security updates to the entire install
base
Enforce multi-factor authentication, single sign-on (SSO) and device SSO while
integrating with existing authentication and security approaches
Enable secure delivery and operation of mobile apps for employee-owned devices or
device types not allowed on the corporate network
Manage approved and rejected devices for controlled mobile-application installation
and remote application disablement
Govern their mobile app portfolio from one central interface.
Govern app distribution and version management
Direct Update for enforced version upgrades
Manage push notifications through a single, central interface
Create a secure, hardened shell to enforce common branding, security and data access
standards
Monitor usage through analytics and usage reporting
High availability and private cloud deployment options (WebSphere Application Server
Network Deployment, PureApplication Systems)
1-35
Student Notebook
WU5061.1
Notes:
IBM Redbooks - Hybrid Cloud Integration and Monitoring with WebSphere Cast Iron
https://www14.software.ibm.com/webapp/iwm/web/signup.do?source=swg-castiron&S_PK
G=ov11090&S_TACT=109KA5IW&S_CMP=web_opp_ibm_ws_appint_hero_castiron-hype
r
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
IBM Endpoint Manager for Mobile Devices provides a completely integrated approach for
managing, securing, and reporting on laptops, desktops, servers, smartphones, tablets,
and even specialty devices such as point-of-sale terminals. This provides customers with
unprecedented real-time visibility and control over all devices employees use in their daily
job functions; reducing costs, increasing productivity, and improving compliance.
1-37
Student Notebook
Checkpoint questions
1. Which mobile platforms are the top 2?
2. What is the difference between a web application, a hybrid
application, and a native application?
3. List the three parts of IBM Mobile Foundation
WU5061.1
Notes:
Write your answers here:
V8.1
Student Notebook
Uempty
Unit summary
Having completed this unit, you should be able to:
Describe what it means to become a mobile enterprise
Explain the challenges of mobile application development,
management, and security
Describe the goal of IBMs mobile solution offerings
Identify IBM Worklight V6.0 as a key part of IBMs mobile solutions
strategy
WU5061.1
Notes:
1-39
Student Notebook
Checkpoint answers
1. Of the six mobile platforms that are mentioned at the beginning of this
module, which are the top 2?
Android, iOS
2. What is the difference between a web application, a hybrid
application, and a native application?
Web uses only HTML5, CSS, JavaScript; native uses coding specific
to the device; hybrid mixes the two.
3. List the three parts of IBM Mobile Foundation
Worklight, Endpoint Manager, Cast Iron
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
References
IBM Worklight V6 documentation:
http://pic.dhe.ibm.com/infocenter/wrklight/v6r0m0/index.jsp
Whitepaper - Native, web or hybrid mobile-app development ftp://public.dhe.ibm.com/software/pdf/mobile-enterpris
e/WSW14182USEN.pdf
2-1
Student Notebook
Unit objectives
After completing this unit, you should be able to:
Compare the advantages and disadvantages of different mobile
application designs
Identify a mobile application design suitable for an application
WU5061.1
Notes:
2-2
V8.1
Student Notebook
Uempty
Topics
Approaches to mobile design
Comparison of mobile application designs
Choosing the right approach
WU5061.1
Notes:
2-3
Student Notebook
Three approaches
Native
application
Web
application
Hybrid
application
100101010101
110100010100
100101011101
000100010010
Mobile
browser
WEB CODE
<!DOCTYPE ht
<html>
<head>
<title>Web App
</title></head>
<body onload =
native
container
WEB CODE
<!DOCTYPE ht
<html>
<head>
Device APIs
Device APIs
WU5061.1
Notes:
All of these approaches are commonly used, but this course concentrates on the third,
hybrid approach. This is what Worklight is principally intended to develop.
2-4
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
There is no particular order to the list given on the slide. Maybe the target audience is the
governing factor because the application is intended for employees, or is specifically
intended for BlackBerry users; maybe it is the timeframe constraint that overrides
everything else because the application must be available next week and there are no
programmers in-house with experience enough in native technologies. The choice of
strategy is going to be made on a case by case basis.
IBM Whitepaper Native, web or hybrid mobile-app development ftp://public.dhe.ibm.com/software/pdf/mobile-enterprise/WSW14182USEN.pdf
2-5
Student Notebook
2-6
V8.1
Student Notebook
Uempty
2-7
Student Notebook
Approaches to mobile
design
WU5061.1
Notes:
2-8
V8.1
Student Notebook
Uempty
Native applications
Binary executable file that is stored locally on the device
Usually downloaded from an App Store
Apple App Store
Android Market, Google Play
BlackBerry App World
And others
WU5061.1
Notes:
Native apps have binary executable files that are downloaded directly to the device and
stored locally. The installation process can be initiated by the user or, in some cases, by the
IT department of the organization. The most popular way to download a native app is by
visiting an app store, such as Apples App Store, Androids Marketplace or BlackBerrys
App World, but other methods exist and are sometimes provided by the mobile vendor.
Once the app has been installed on the device, the user launches it like any other service
the device offers. Upon initialization, the native app interfaces directly with the mobile
operating system, without any intermediary or container. The native app is free to access
all of the APIs that are made available by the OS vendor and, in many cases, has unique
features and functions that are
typical of that specific mobile OS.
IBM Whitepaper Native, web or hybrid mobile-app development ftp://public.dhe.ibm.com/software/pdf/mobile-enterprise/WSW14182USEN.pdf
2-9
Student Notebook
Objective-C, C, C++
Android:
Java
BlackBerry: Java
Windows Phone: C#, VB,.NET
Xcode
Android SDK
BlackBerry:
Windows Phone:
BB Eclipse plug-in
Visual Studio, Windows Phone Development Tools
WU5061.1
Notes:
Native apps can interact with and take advantage of operating system features and other
software that is typically installed on that platform. A native app is built for a particular
device and its operating system, so it has the ability to use device-specific hardware and
software, such as a global positioning system (GPS) and camera. This can be viewed as
an advantage for native apps over Web apps. However, there are ways of accessing native
functionality from within an hybrid app. This technique is described later.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
HTML 5 improves on its predecessors in a number of ways. It can be written with different
markup syntaxes (HTML and XML), it introduces new, simpler markup for things that were
very complex in earlier versions (audio, for example), and it is being developed specifically
with a view to being used in mobile environments.
Modern mobile devices consist of powerful browsers that support many new HTML5
capabilities, Cascading Style Sheets 3 (CSS3) and advanced JavaScript. With recent
advancements on this front, HTML5 signals the transition of this technology from a
page-definition language into a powerful development standard for rich, browser-based
applications.
A few examples of the potential of HTML5 include advanced UI components, access to rich
media types, geolocation services and off line availability. Using these features and many
more that are under development, developers are able to create advanced applications,
using nothing but web technologies.
2-11
Student Notebook
WU5061.1
Notes:
This will of course change over time. The number four is correct as of June, 2012.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
2-13
Student Notebook
Tools and
knowledge
Mobile website
Execution
URL
User experience
Interactive UI
Navigational UI between
pages that display static
data
Performance
WU5061.1
Notes:
The point here is that the mobile device gets everything it needs, then works essentially
off-line. The standard web page is generated largely on the server side, then downloaded.
V8.1
Student Notebook
Uempty
Hybrid applications (1 of 2)
There are many things in a web design that are common to renderings
on any platform
For example, a background color or image, or a particular font
It is not good design practice to repeat the coding for each platform
Maintenance becomes an issue
WU5061.1
Notes:
The hybrid approach combines native development with web technology. Using this
approach, developers write significant portions of their application in cross-platform web
technologies, while maintaining direct access to native APIs when required.
The native portion of the application uses the operating system APIs to create an
embedded HTML rendering engine that serves as a bridge between the browser and the
device APIs. This bridge enables the hybrid app to take full advantage of all the features
that modern devices have to offer.
App developers can choose between coding their own bridge or taking advantage of
ready-made solutions such as PhoneGapopen-source library that provides a uniform
JavaScript interface to selected device capabilities that is consistent across operating
systems.
Apache Cordova was previously known as PhoneGap. The code was contributed to the
Apache Software Foundation.
Apache Cordova is discussed in detail later in this course.
Copyright IBM Corp. 2013
2-15
Student Notebook
V8.1
Student Notebook
Uempty
Hybrid applications (2 of 2)
The web part of a hybrid application can be
A web page that is stored on a server and accessed like any traditional web
page
A package of files that are stored locally on a device
HTML, JavaScript, CSS, media files, text files, and so forth
Server storage allows the developer to modify the page code without
having to go through the process of submission that is required for an
App Store
However, offline availability is not an option if the page must be accessed from a
server
WU5061.1
Notes:
The native portion of the app can be developed independently, but some solutions in the
market provide this type of a native container as part of their product, thus empowering the
developer with the means to create an advanced application that utilizes all the device
features using nothing but web languages.
In some cases, a solution will allow the developer to use any native knowledge he or she
might have to customize the native container in accordance with the unique needs of the
organization.
The web portion of the app can be either a web page that resides on a server or a set of
HTML, JavaScript, CSS and media files, packaged into the application code and stored
locally on the device. Both approaches carry advantages and limitations. HTML code that
is hosted on a server enables developers to introduce minor updates to the app without
going through the process of submission and approval that some app stores require.
Unfortunately, this approach eliminates any off line availability,
as the content is not accessible when the device is not connected to the network. On the
other hand, packaging the web code into the application itself can enhance performance
Copyright IBM Corp. 2013
2-17
Student Notebook
and accessibility, but does not accept remote updates. The best of both worlds can be
achieved by combining the two approaches. Such a system is
designed to host the HTML resources on a web server for f lexibility, yet cache them locally
on the mobile device for performance.
V8.1
Student Notebook
Uempty
2-19
Student Notebook
Comparison of mobile
application designs
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Because each platform has a unique set of APIs, the developer must
be familiar with a wide range of languages
Or the company needs a wide range of specialized developers
WU5061.1
Notes:
Scenarios for the native approach include:
Existing native skills
A single mobile OS
Native functionality
Rich UI requirements
2-21
Student Notebook
WU5061.1
Notes:
The last point on the slide, the limited access to device APIs, may change in the future,
with advancements in HTML giving a better link between the web application and the
native APIs.
Scenaries for the web approach include:
Direct distribution
Pilot app
Visibility
V8.1
Student Notebook
Uempty
Hybrid applications
Multi-platform support
Medium cost of development
There might still be a need to code in a native device language
WU5061.1
Notes:
Scenarios for the hybrid approach include:
Balancing the tradeoff
In-house skills
Future considerations
2-23
Student Notebook
Comparison of features
Feature
Development
language
Native
Web
Hybrid
Native only
Web only
No
Yes
Take advantage of
web expertise
No
Yes
Advanced graphics
Yes
Some
Upgrade flexibility
Yes
Some, through
a bridge
Almost none
High
Medium (usually
App Store)
WU5061.1
Notes:
This slide has to be viewed with a certain flexibility. Some shops may indeed have existing
expertise in a particular language (for example, Objective-C). The point is that in general, a
company will need to consider hiring or retraining in order to have the necessary expertise.
Likewise, the positioning of code portability, or advanced graphics, and so on, will change
with time.
V8.1
Student Notebook
Uempty
2-25
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
The next three slides give example scenarios for different approaches. Note that these
scenarios are not necessarily better, or more common, than others. As was stated
earlier in the presentation, factors such as budget, timeframe, target audience, or
required functionality will direct the decision as to what approach is best in a given
company.
2-27
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
There will typically be in-house developers who are familiar with HTML,
CSS, and JavaScript
The development of a web application is therefore easy and efficient
Adding skills to bridge to native code is not difficult
WU5061.1
Notes:
2-29
Student Notebook
Checkpoint questions
1. What are the three approaches for creating mobile web applications?
2. Which of these statements is not correct?
a)
b)
c)
WU5061.1
Notes:
Write your answers here:
V8.1
Student Notebook
Uempty
Unit summary
Having completed this unit, you should be able to:
Compare the advantages and disadvantages of different mobile
application designs
Identify a mobile application design suitable for an application
WU5061.1
Notes:
2-31
Student Notebook
Checkpoint answers
1. What are the three approaches for creating mobile web applications?
Advanced UI components
Access to rich media types
Geolocation services
Offline availability
New audio capabilities
and others...
true
true
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
References
IBM Worklight V6 documentation:
http://pic.dhe.ibm.com/infocenter/wrklight/v6r0m0/index.jsp
3-1
Student Notebook
Unit objectives
After completing this unit, you should be able to:
Differentiate the IBM Worklight V6.0 product packages
Explain the IBM Worklight V6.0 component architecture
WU5061.1
Notes:
3-2
V8.1
Student Notebook
Uempty
Topics
Component architecture
Code optimization
Client-side development
Server-side development
Secure authentication
Push notification
Direct update
Remote server application deployment
Device analytics reporting
Shell development
Application Center
WU5061.1
Notes:
Note: this module gives a general overview of these topics. They are discussed in depth in
further units.
3-3
Student Notebook
3-4
V8.1
Student Notebook
Uempty
3-5
Student Notebook
IBM Worklight
component
architecture
WU5061.1
Notes:
The first of the pages on component architecture sums up the five different parts of
Worklight and their relationship. Each part is discussed in more detail in the subsequent
pages.
You may want to bookmark the first slide, and refer back to it throughout the course as a
reminder of where the discussion is situated.
3-6
V8.1
Student Notebook
Uempty
Backend and
Cloud services
Device
Runtime
Device
SDK
Application
Code
Worklight
Studio
Build Engine
Worklight
Console
Worklight Server
App
Center
Backend
Version
Unified push
integration management notifications
WU5061.1
Notes:
This slide shows the relationship between the five components of Worklight. Each of these
components is discussed briefly in this unit, and in depth in future units.
3-7
Student Notebook
Worklight Studio
HTML5, hybrid and native
coding
Optimization framework
Integrated device SDKs
3rd party library integration
Worklight
Studio
Build Engine
WU5061.1
Notes:
With the file structure of IBM Worklight Studio, the optimization framework enables
developers to adjust applications to different mobile environments, while maximizing code
reuse. Common application code is shared among multiple environments;
environment-specific code that can overwrite or augment the commonly shared code is
then placed in separate folders. Application logic is consistent among the different
environments, while the user interface behaves natively.
Worklight Studio V6 plugin can be installed on Eclipse Juno, Eclipse IDE for Java EE
Developers, or on Eclipse Juno, Eclipse Classic 4.2.2.
3-8
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
1. Select Install New Software
2. Click Add
3. Type a name and the URL of the download site.
The compressed file can be downloaded from
http://public.dhe.ibm.com/ibmdl/export/pub/software/mobile-solutions/wor
klight/.
To install through Eclipse, use the url
http://public.dhe.ibm.com/ibmdl/export/pub/software/mobile-solutions/wor
klight/wdeupdate/.
3-9
Student Notebook
2
3
WU5061.1
Notes:
1. An icon is added to the perspective for fast access to Worklight artifacts.
2. The Project is created with a framework of folders and files for the Worklight elements.
This framework is discussed in detail in the next slides.
3. The perspective includes a Rich Page Editor for creating and editing html pages, as
well as .
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
This course concentrates on hybrid development.
Inner applications can only be developed as a part of a shell component. The shell
component would be created first and provided to the developers of the inner application.
The intention is to create a common basis for all developers for things such as icons,
menus, placement, security requirements, and so on. The shell is populated with the things
that all developers must adhere to, and the inner application is added to the shell
component.
Shells and inner applications are discussed in a later unit.
3-11
Student Notebook
Backend and
Cloud services
Worklight server
Worklight Server
Backend
Version
Unified push
integration management notifications
Enforcement of authentication
Control of the client:
Application version management
Remote disabling
Enforced application update
WU5061.1
Notes:
The Worklight server is an application that runs on an Application server. As is discussed in
the unit on deploying applications, each project deployed to the application server has its
own Worklight server.
www.staplescopyprint.ca
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
The server that is bundled with the IDE is intended as a part of the development
environment. For production, the server is installed as separate software.
This is the topic of a later unit.
3-13
Student Notebook
worklight.properties
Contains configuration
information such as port
number, context root, and so
forth
Everything is commented out
Values are set automatically
Uncomment anything you
want to customize
WU5061.1
Notes:
This slide highlights the simplicity of Worklight development: a lot of the tasks, such as
setting a server address or a database address, default to predefined values. The
developer only needs to modify them if the predefinitions are not sufficient.
The defaults of course target the development environment, with a local server installed
with the Worklight Studio, and so forth.
V8.1
Student Notebook
Uempty
authenticationConfig.xml
Used to configure how widgets and web applications authenticate
users
Predefined security tests,
realms and login modules
are provided
You can use these
as a model for
customization
WU5061.1
Notes:
As for the properties discussed on the previous slide, authentication information also
defaults to predefined values. An added advantage of this is that the format of a definition
is provided automatically. It is therefore easy to create a new, customized definition by
referring to the default.
3-15
Student Notebook
WU5061.1
Notes:
Adapters and applications are build and deployed in the same way. The slide shows the
context menu for both.
1. The Run As sub-menu for adapters has the option to deploy the adapter, or to invoke
a Worklight backend service or a procedure.
2. The Run As sub-menu for an application allows you to build and deploy the application
common resources and any environment you have created.
Not shown on the slide is the sub-menu for a specific environment, which offers the options
to build the environment only, or to build everything (as for the application).
V8.1
Student Notebook
Uempty
Device runtime
Troubleshooting
Analytics
Skins
Device
Runtime
Authentication
Application
Code
Local security
Version control
WU5061.1
Notes:
Troubleshooting
Detection and correction of connectivity problems.
Analytics
Collection of information about application and device usage.
Skins
Optimization of look-and-feel, features, and functions of different types in a single
device family.
Authentication
Managing the authentication sequence for an application.
Local security
Encryption of data stored on a device.
Version control
Copyright IBM Corp. 2013
3-17
Student Notebook
Apply new versions, or disable old versions in accordance with the information received
from the Worklight console.
V8.1
Student Notebook
Uempty
native
shell
Web
code
Application Stores
V1.0
Worklight Server
During development
recent web
cycles, testers automatically Maintain
resources for native
get recent web resources
applications V1.0 and V1.1
through internal distribution
mechanisms, not application stores
native
shell
Web
code
V1.1
WU5061.1
Notes:
Web resources are initially packaged with the application to ensure first offline availability.
They are transferred to cache storage in the application.
The application checks for updates:
On startup
On return to foreground
Newer versions of web resources are downloaded when necessary.
3-19
Student Notebook
Push notification
Messages are pushed from the server to the mobile device
Can be received even if the application is not running
It can be an alert, a badge, or a sound
Back end
Push service
mediator
5
1
Enterprise
data source
2
3
Worklight
adapter
event source
WU5061.1
Notes:
A device obtains a token from a push service mediator (1), then send this token, together
with the request to be notified, to the Worklight server (2).
A backend data source sends a event notification to the Worklight server (3). The server
checks whether there are any subscriptions to this event, and sends the tokens to the push
service mediator (4). The mediator retrieves the device addresses associated with the
tokens and sends the notification (5).
Alert: A pop-up dialog that can be read and needs to be dismissed by clicking.
Badge: A small icon added to another icon to warn the user about some condition (this is
also very typical in Integrated Development Environments, for example when there is an
error in some code a red badge is added to the file icon).
Sound: Audio warning that, unlike an alert, does not need to be dismissed.
V8.1
Student Notebook
Uempty
Worklight console
The console is an
application running on
the Worklight server
If you are using the Worklight
Studio built-in server, Studio
needs to be running in order
to see the console
Two tabs:
Catalog
Shows a list of the
applications and the adapters
deployed to the server
Push notifications
Shows event sources, and
services and applications that
are subscribed to receive
notifications
WU5061.1
Notes:
The console opens as an internal view in Worklight Studio. Right-click on the project and
choose Open Worklight Console from the context menu.
3-21
Student Notebook
3
2
1
WU5061.1
Notes:
1. The list of available applications and adapters. There may be different versions of an
application. You can set the state for an application to active (this is the default state),
active with notification (which can be used to warn the user, for example telling them
that there is a new version, or that the application is going to be disabled), and disabled
(the version can no longer be accessed).
2. The display name and the description are set by default to the name of the application
or adapter. They can be modified to something more informative by
changing:<application ><displayName>Engadget
Reader</displayName><description>This is v1 and v1.1 of the app.</description>
3. Building and deploying automatically is only an option in the development environment.
You can also upload a built application through the console.
An application can be uploaded to the server from the console as well as from Worklight
Studio.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
What the simulator is doing is placing the image of a mobile device around a rendering of
web code. It cannot render Xcode for an iPhone, nor can it render Java for an Android
device. Nevertheless, it is very useful as a quick way to visualize the rendering of web code
and the interaction with JavaScript.
A more accurate rendering can be got by using emulators. This course talks about the
Android emulator that is a part of the Worklight Studio setup, and the associated exercises
give supplemental instructions for rendering Xcode.
3-23
Student Notebook
WU5061.1
Notes:
1. Applications native to the displayed device can be simulated by clicking Simulate
Device API. The list is displayed on the left.
2. You can calibrate the device size to give a more accurate rendering on your monitor.
The calibration can be done by comparing the display to something the size of a credit
card.
3. You can compare the rendering on different devices by adding others. The drop down
list offers a choice of BlackBerry, Android and iOS.
V8.1
Student Notebook
Uempty
Application Catalog
Service
Application Center
Console
Application Install
Service
Application
Center
Installer App
Application Feedback
Service
iOS / Android
Worklight 5
Dojo Mobile 1.7.2
HTML5 / CSS / JavaScript
iOS and Android native code
Rest Services
Database - Derby
WU5061.1
Notes:
The Application Center is composed of these main elements: a server-side component, a
repository, an administration console, and a mobile client application. The server-side
component is a Java Enterprise application that must be deployed in a web application
server such as IBM WebSphere or Apache Tomcat. The server-side component consists of
an administration console and a mobile application. This mobile application installs the
mobile applications available to the client-side component.
There is a repository, database that stores information such as which application is
installed on which devices, the feedback about applications, and the mobile application
binary files.
The administration console
A web console through which administrators can manage applications, user access rights
to install applications, user feedback about mobile applications, and details about
applications installed on devices. See The Application Center console.
Mobile client application
Copyright IBM Corp. 2013
3-25
Student Notebook
You use the mobile client to install applications on a mobile device and to send feedback
about an application to the server.
V8.1
Student Notebook
Uempty
3-27
Student Notebook
Code optimization
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Code optimization
Worklight applications can execute in several different environments
Smartphones, tablets, web
WU5061.1
Notes:
Code optimization makes the Worklight Studio development environment very efficient.
The intent is to make code as reusable as possible by placing it in a common environment
if it is used by different devices, and only putting code that is specific to an environment into
a more targeted folder structure. There are three layers to this optimization: common,
environment, and skin.
The following slides look in detail at how optimization works.
3-29
Student Notebook
WU5061.1
Notes:
Note that the folder structure is mirrored between common and environment areas. There
is one more level, that is not shown on this page, called a skin, where the same folder
structure can be found. This structure is discussed in depth in the following pages.
V8.1
Student Notebook
Uempty
Environment
CSS
Environment
images
Environment
JavaScript
Skin
CSS
Skin
images
Skin
JavaScript
WU5061.1
Notes:
This page gives the high-level view of optimization. As a general rule, you place into the
higher levels code that is general, and into the lower levels code that is specific. For
example, there may be an image that is provided for all devices (common to every device).
There may also be an Apple image for iOS devices. Since this image is not relevant to
other environments, it would be placed at a lower level. Skins follow the same logic, and
allow for fine-grained distinctions within one family of devices.
3-31
Student Notebook
Optimization CSS
Any CSS file in an environment folder is appended to the fundamental
common CSS file.
If any property name in the environment CSS is the same as in the
common CSS, the environment overrides
#content {
height: 460px;
margin: 0 auto;
width: 320px ;
}
body {
background-color: white;
}
div {
font: sans-serif;
}
common
#content {
height: 460px;
margin: 0 auto;
width: 320px ;
}
body {
background-color: white;
text-align: left;
}
div {
font: serif;
}
body {
text-align: left;
}
div {
font: serif;
}
environment
final CSS
WU5061.1
Notes:
Here you see the specifics of optimization as it works for cascading style sheets. The basic
is the common folder (to the left on the image). The environment folder then combines in
two ways:
1. If the environment information does not exist in the common file, the two are
aggregated.
2. In the event of a name/value conflict, the lower level wins out (environment wins over
common).
Not shown on the slide is the skin structure. The same principle holds between skin and
environment as between environment and common: the information is either
aggregated or the skin information replaces the environment information.
V8.1
Student Notebook
Uempty
Optimization images
New images in the environment folder are appended to the collection
of images in the common folder.
In the event of a name collision, the environment images replace the
common images
bgd.png
icon.jpg
splash.jpg
common
bgd.jpg
bgd.png
icon.jpg // environment
splash.jpg
bgd.jpg
icon.jpg
environment
final images
WU5061.1
Notes:
Images follow the same principle as cascading style sheets, except that here there is no
concept of information within the file: the comparison is at the level of the file name and
extension.
As you can see on the image, if the name is the same but the extension is different, then
the two files are different and both are added to the final list of images. In the one case
illustrated here where the file name and file extension are identical, it is the lower level
artifact (environment) that is used in the final collection of available images.
If there were the same conflict between environment and skin, it would be the image from
the skin that would win out and be added to the final collection of images.
3-33
Student Notebook
Optimization JavaScript
The main JavaScript file in an environment folder has a function,
wlEnvInit(), which invokes the function wlCommonInit() in the
common js folder
This helps ensure that common initialization happens before the more specific
environment initialization
Both the common and the environmental files have the same name:
applicationName.js.
Both files can hold any other functions that are required
If functions or variables in the environmental folder have the same
name as in the common folder, they are overridden
common
var a = "hello;
wlEnvInit(){}
function_1(){}
function_2(){}
var a = 1;
wlCommonInit(){}
function_1(){}
environment
final JavaScript
WU5061.1
Notes:
There is no conflict at the naming level between JavaScript files in the common folder
structure and the environment folder structure. On the contrary, be careful when you are
editing, because both are given a JavaScript file based on the name of the application! If
you have the two files open at the same time, it can be difficult to know which is which. For
the record, note that the common appName.js file has a function wlCommonInit(), while the
environment appName.js file has a function wlEnvInit() that calls wlCommonInit().
The resolution of potential conflicts in JavaScript follows the same process as the
cascading style sheets. The common file lays down the fundamental variables and
functions, then the environment file variables and functions are either aggregated or they
override.
V8.1
Student Notebook
Uempty
Optimization - HTML
By default, only the common folder of the application has an HTML file:
applicationName.html
An environmental folder can be given an HTML file, in which case it
simply replaces the common file
Note that this is not usual practice: typically you want a common feel
for an application between environments, and this is provided by using
a common HTML file
applicationName.html
common
applicationName.html
environment
WU5061.1
Notes:
The HTML file is a special case. In the basic project with its one application, there is an
html file automatically added to the common folder, with the application name
(appName.html). When you create an environment, folders and files are automatically
created that mirror the common structure, but there is no html file. Usually, you want your
site to have a unified look and feel over all devices, and therefore overriding the html file is
not required. If for some reason you want to have a specific environment html file, if you
give it the name of the application, it simply replaces the common html file.
3-35
Student Notebook
V8.1
Student Notebook
Uempty
3-37
Student Notebook
Client-side
development:
the Worklight
JavaScript SDK
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Example
Technology
WU5061.1
Notes:
It could be argued that most mobile development is client side, since it if for mobile devices!
It is true that the greatest variety of APIs in the Worklight Mobile environment is in the client
side coding, and server side code for Worklight mobile can essentially be summed up as
adapter.
This side gives an overview of the functionalities and corresponding technologies that are
the object of client side coding.
3-39
Student Notebook
Common controls
A common control is one that is available to all environments
Worklight automatically renders the controls natively for a particular
mobile platform
Typical examples are
WL.BusyIndicator
WL.SimpleDialog
WL.TabBar
WL.OptionsMenu
WU5061.1
Notes:
These controls are discussed in more detail in a future unit.
V8.1
Student Notebook
Uempty
Skins
Skins give an alternative look to an environment.
They are packaged with an application, and are related to their
environment as environmentName.skinName
For example, Android.mySkin
WU5061.1
Notes:
Skins have been mentioned briefly already. A device family (Android, for example) may
have many different types of device, with different screen shape and size, or different ways
of allowing user interaction. This can be accommodated by further specializing the
environment with skins. A skin has its own cascading style sheet, image folder, and
JavaScript file. These may have nothing more than the skeleton files generated by
Worklight, in which case using a skin does not change the look and feel of the environment.
However, the skin could provide smaller images for use on devices with less screen size, or
even modify the display of information radically (as is illustrated on this page).
3-41
Student Notebook
Apache Cordova
Allows developers to access native mobile device features and execute
native code using JavaScript
The framework is added by Worklight when you create an iOS or an
Android environment
It is then invoked using the JavaScript API
Example: a native alert
navigator.notification.alert(
"Native alert", null);
WU5061.1
Notes:
The complete call is navigator.notification.alert (message, alertCallback, [title],
[buttonName])
Where
Message is the Dialog message
alertCallback is the function to invoke when the alert dialog is dismissed.
Title is the dialog title (Optional; it defaults to "Alert")
buttonName is the name of the button (Optional; it defaults to "OK")
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
className: The name of the native class. For iOS this is just the name of the class. For
Android, the fully qualified package.Class is required.
Callback: A function that is called when the native page switches back to the web view.
This function is passed a single JSON object parameter when invoked.
data: A JSON object that is sent to the native class. For iOS, The data must be single string
or a flat record of strings.
3-43
Student Notebook
Offline access
Detection that an application has gone offline can be done in two ways:
Explicitly
Some Worklight server function may be invoked, and be unreachable
Implicitly
There may be an event listener
For example a foreground event may trigger a listener that checks whether
there is still a connection
WU5061.1
Notes:
With devices that are mobile, and can be travelling between base stations. Getting out of
range of a base station can happen in two ways: either you move too far away and the
signal is no longer strong enough to be detected, or you enter some structure that blocks
the signal: a tunnel, an elevator, and so on. It could also be that the signal provider stops
providing a signal
In all these scenarios, the mobile device may need to ascertain whether it has connectivity
or not. There are three times when it does this: when an application starts, when an
application is brought to the foreground, and when there is an explicit request from an
application. In the first two cases, there is an implicit check for connectivity through an
event listener. In the third case there is an explicit invocation that creates an error if there is
no connection available.
The importance of this for mobile devices is that you do not want your application to stop
working every time it loses the signal. You also do not want to lose information just because
you try to send it while there is no receiver available!
V8.1
Student Notebook
Uempty
Encrypted cache
Client side encryption implemented with HTML5 web storage using
key-value pairs
Two types of web storage: localStorage and sessionStorage
localStorage has no expiry date
sessionStorage is valid until the session ends
WU5061.1
Notes:
Encrypted cache is supported by iOS Safari, Android Browser, and Opera Mobile (from
V11).
The parameters are:
credentials: the user password
createIfNone: true=create the cache if none is found
onComplete: do this when the cache is ready for use
onError: do this if an error occurred, such as credentials mismatch, or local storage not
supported
Note that credentials are only required to open the cache. After that, reading and writing is
free to any user! You must be careful to explicitly close the cache.
3-45
Student Notebook
Globalizing strings
For globalization, anything that needs to be read by the user should be
translated into their preferred language
information strings, labels, messages, for example
WU5061.1
Notes:
In order to detect the locale of the device you can use WL.App.getDeviceLocale() and
WL.App.getDeviceLanguage().
Messages values can be overridden:
function setFrench() {
Messages.headerText = En-tte;
Messages.languageLabel = Franais;
Messages.sampleText = chantillon;
}
function setGerman() {
Messages.headerText = berschrift;
Messages.languageLabel = Deutsch;
Messages.sampleText = Beispiel;
}
V8.1
Student Notebook
Uempty
3-47
Student Notebook
UI frameworks
Using your own HTML, CSS, and JavaScript provides a highly
customizable framework for your application.
You can also use an existing framework
for example, Dojo Mobile, jQuery Mobile, or Sencha Touch
WU5061.1
Notes:
When you create a new application using the Worklight wizard, you have the option to
include three frameworks: jQuery, Dojo toolkit, and Sencha Touch. These frameworks ore
not exclusive, and you can select any combination of checkboxes to include them. The
required files are then automatically added to your application.
You can added them manually later, if you decide that you need them.
V8.1
Student Notebook
Uempty
3-49
Student Notebook
Server-side
development
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Integration adapters
Four adapter types can be developed with Worklight:
SQL
HTTP
Cast Iron
JMS
These are discussed in detail in a further module
The adapter may transform the data it retrieves (optional XSL file), or
simply return it
In both cases, the adapter returns a JSON object
WU5061.1
Notes:
After all those pages giving a high-level view of client side development, you may be
surprised that there is only one for server side development! This is not because it is
unimportant, or because there is little to do. It is simple because it can be summed up in
one word: adapters. The principle is simple: an XML file to configure the adapter, and a
JavaScript file to give it functionality. There may also be a transformation file (XSLT).
Adapters are discussed in depth in a future unit.
3-51
Student Notebook
V8.1
Student Notebook
Uempty
3-53
Student Notebook
Secure authentication
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Authentication
Worklight defines security in authentication realms
A realm describes how to authenticate uses
Realms are defined in authenticationConfig.xml
A realm consists of
an authenticator
Components used to collect credential information
a Login Module
Receives credential information from the authenticator and validates them
A securityTest then groups realms and defines the order in which the
tests should be applied
<customSecurityTest name="custom">
<test realm="realm_A" isInternalUserID="true" step="1"/>
<test realm="realm_B" isInternalDeviceID="true" step="2"/>
</customSecurityTest>
WU5061.1
Notes:
Security is applied by configuring tests called securityTests. There are three different types
of securityTest. The one illustrated here shows the structure: the securityTest contains one
or more tests that reference a security realm, which in turn references a security
loginModule (you would need to look at the realm definition to see which loginModule was
referenced). Each test may be specified as referring to a user or a device. The tests can be
ordered by using the step attribute.
3-55
Student Notebook
V8.1
Student Notebook
Uempty
3-57
Student Notebook
Application
management and
reporting capabilities
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Push notification
Push refers to a server initiating communication with a device
Notifications are information that the device user must know, or may
need to know
for example, an application must be updated, a flight has been delayed, it may
rain, and so forth
WU5061.1
Notes:
A user must first register their interest for a notification. This is a two-step process; first, the
application gets a token from a Push Service Mediator (Apple Push Notification Service or
APN, Global System for Mobile Communications or GSM, and so on). This token is then
sent to the Worklight server. The server either itself waits for a notification to be pushed to
it, or it polls a backend server. When the notification is received, the server passes the
token back to the Push Service Mediator, which looks up the user information and passes
the notification on.
3-59
Student Notebook
Direct update
Hybrid iOS applications and Android applications can receive new
versions of their web resources without the user explicitly asking for
them
This has advantages in two directions:
The user can always have the latest version of an application
Server-side control over which versions of an application are being used.
WU5061.1
Notes:
Note that this applies only to the applications web resources. Native updates are only
possible by going through the App Store.
An application can check for updates on start up, or when it is brought back to the
foreground.
The Worklight server can disable a native application, although it cannot update it.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
These values are defaults in the development environment. They are provided in
worklight.properties as an indication of what the values are but they are commented out.
3-61
Student Notebook
V8.1
Student Notebook
Uempty
3-63
Student Notebook
Mobile team
development
capabilities
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Shell development
A shell is used as a code base wrapper by inner applications
It consists of native code and web resources that are intended for any
application in the shell
The shell is not itself executable it is a framework for inner
applications
An inner test application is added when you create a shell in order to verify the
correct functioning
The shell has a fragments folder which holds html that is added to the
web page of the inner application
WU5061.1
Notes:
Shell development is intended to provide a common ground for teams engaged in
developing mobile applications. The shell is developed with the fundamental, common
code that every developer must adhere to. Inner applications then reference the shell, and
build on that basis.
This is not an absolute adhesion that is imposed! Inner applications can override anything
that is necessary.
3-65
Student Notebook
Application Center
The IBM Worklight Application Center for mobile applications is
focused on the needs of a development team
It is a private App Store
Scenario:
a developer shares a new version of an application with stakeholders, designers,
testers, and so forth
Everyone installs the new version on their device
They can send feedback to the developer from the Application Center Installer
app.
The developer can access the feedback from the Application Center Console
WU5061.1
Notes:
Application Center is installed on the application server. IBMAppCenter is installed on the
mobile device. The web console is packaged as a war file (ibmapplicationcenter.war).
A Derby database is provided, together with the scripts.
Documentation includes an installation guide and a usage guide.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
Some of these enhancements are indicated here simply for information (such as the
improved performance). Other enhancements are discussed in future units.
3-67
Student Notebook
Checkpoint
1. What are the five basic components in Worklight?
2. How does direct update work?
3. Which of these folders can be found in common resources and
environment resources:
a)
css
b)
c)
native
legal
d)
e)
js
native resources
4. true or false:
myApp.js in an Android folder overrides myApp.js in a common folder
5. What does it mean when a server marks an application version as
Active, Notifying ?
6. true or false:
a shell is an executable framework for inner applications
Figure 3-52. Checkpoint
WU5061.1
Notes:
Write your answers here:
V8.1
Student Notebook
Uempty
Unit summary
Having completed this unit, you should be able to:
Differentiate the IBM Worklight V6.0 product packages
Explain the IBM Worklight V6.0 component architecture
WU5061.1
Notes:
3-69
Student Notebook
Checkpoint answers
1. What are the five basic components in Worklight?
Worklight Studio, Server, and console; device runtime, Application Center
css, and d) js
5. true or false:
myApp.js in an Android folder overrides myApp.js in a common folder
false. Only functions with the same name override, otherwise they are merged
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
References
IBM Worklight V6 documentation:
http://pic.dhe.ibm.com/infocenter/wrklight/v6r0m0/index.jsp
4-1
Student Notebook
Unit objectives
After completing this unit, you should be able to:
Install IBM Worklight Studio using the Eclipse Update Site
Set-up an Android or iOS development environment
Explain the Worklight development framework
Describe the Worklight Studio mobile development tools
Describe the steps involved in creating, building and testing an
application in Worklight Studio
WU5061.1
Notes:
This unit shows how to install Worklight Studio and set-up an Android or iOS development
environment. It also describes the Worklight base development framework and provides
an overview of the Worklight Studio tools that facilitate mobile development.
4-2
V8.1
Student Notebook
Uempty
Topics
IBM Worklight Studio installation and configuration
Overview of mobile development steps
Creating a project and writing your code
Building your application
Previewing and testing your application
Publishing your application
WU5061.1
Notes:
4-3
Student Notebook
4-4
V8.1
Student Notebook
Uempty
4-5
Student Notebook
WU5061.1
Notes:
4-6
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
IBM Worklight Studio v6 includes the following tools and components:
Embedded Worklight Server
Rich Page Editor
Development tools
Apache Cordova 1.6.1
IBM Dojo Mobile 1.7.2
4-7
Student Notebook
WU5061.1
Notes:
For a detailed list of system requirements, visit:
https://pic.dhe.ibm.com/infocenter/prodguid/v1r0/clarity-reports/report/html/softwareReqsF
orProductByComponent?deliverableId=1343665214557&duComponent=Desktop_CBE50
E800C6611E28BB5885E0925FE36#
4-8
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
For more details, visit https://pic.dhe.ibm.com/infocenter/prodguid/v1r0/clarity-reports/report/html/softwareReqsF
orProductByComponent?deliverableId=1343665214557&duComponent=Desktop_CBE50
E800C6611E28BB5885E0925FE36#
4-9
Student Notebook
WU5061.1
Notes:
IBM Installation Manager is a tool that allows you to install and maintain IBM software
packages. It includes wizards that guide you through the steps to install, modify, update,
roll back, or uninstall your IBM products.
V8.1
Student Notebook
Uempty
Figure 4-8. Installing IBM Worklight Studio using the Eclipse Update Site (1 of 4)
WU5061.1
Notes:
4-11
Student Notebook
Figure 4-9. Installing IBM Worklight Studio using the Eclipse Update Site (2 of 4)
WU5061.1
Notes:
You can download the Worklight Studio plug-in locally as a compressed file, and then install
it as an Eclipse archive, or you can install it directly from the Eclipse Update web site.
V8.1
Student Notebook
Uempty
Click Next
Install details page displays
You must accept terms of the license
You are prompted to restart Eclipse
Figure 4-10. Installing IBM Worklight Studio using the Eclipse Update Site (3 of 4)
WU5061.1
Notes:
4-13
Student Notebook
Figure 4-11. Installing IBM Worklight Studio using the Eclipse Update Site (4 of 4)
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
4-15
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
b)
WU5061.1
Notes:
The detailed instructions for installing the Android SDK are available online at:
http://developer.android.com/sdk/installing/index.html
4-17
Student Notebook
WU5061.1
Notes:
The URL for the Android SDK download site is:
http://developer.android.com/sdk/index.html
V8.1
Student Notebook
Uempty
Figure 4-15. Installing the Android SDK: SDK platform and platform tools installation
WU5061.1
Notes:
The Android SDK uses a modular structure that separates the major parts of the SDK Android platform versions, add-ons, tools, samples, and documentation -into a set of
separately installable packages. To develop an Android application, you need to download
at least one Android platform and the associated platform tools.
4-19
Student Notebook
Click Add and enter a name for the ADT plug-in repository and its
location.
The ADT plug-in repository is located at:
https://dl-ssl.google.com/android/eclipse/
17
WU5061.1
Notes:
To develop an Android application or prepare a Worklight application to be run on the
Android platform, you need the Android Development Tools (ADT).
ADT is a plug-in for the Eclipse IDE that is designed to give developer an integrated
environment in which to build Android applications. It extends the capabilities of Eclipse to
let developers quickly set up new Android projects, create an application UI, add packages
based on the Android Framework API, debug your applications using the Android SDK
tools, and even export signed (or unsigned) .apk files in order to distribute your application.
Please follow the link at the bottom for more information on the ADT and its download
location.
For detailed instructions on installing the ADT plug-in, visit:
http://developer.android.com/sdk/eclipse-adt.html
The link at the bottom of the page provides the download location. You can use the HTTP
protocol as well. Make sure that you have an Internet connection and your firewall is not
blocking downloads.
V8.1
Student Notebook
Uempty
18
WU5061.1
Notes:
Select Developer Tools in the list of available software. Then follow the ADT installation
process to complete installing the plug-in.
4-21
Student Notebook
19
WU5061.1
Notes:
After installing the ADT Eclipse plug-in, you can open the Android SDK Manager directly
from the workbench and use the Android Virtual Device manager to create virtual devices.
V8.1
Student Notebook
Uempty
20
WU5061.1
Notes:
Once you have completed the Android SDK installation, you need to create and configure
an Android Virtual Device (AVD) on which to test your application.
An Android Virtual Device (AVD) is an emulator configuration that lets you model an actual
device by defining hardware and software options to be emulated by the Android Emulator.
An AVD consists of a hardware profile where you can define the hardware features of the
virtual device.
You can create as many AVDs as you need, based on the types of device you want to
model. To thoroughly test your application, you should create an AVD for each general
device configuration (for example, different screen sizes and platform versions) on which
your application is intended to run, and test your application on each one.
4-23
Student Notebook
WU5061.1
Notes:
Starting an Android virtual device opens the Android emulator window.
V8.1
Student Notebook
Uempty
4-25
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
Note that you can still build and preview the portion of a hybrid iOS application built with
web technologies (HTML5, JavaScript and CSS) in Worklight Studio without having Xcode.
Any native code (Objective-C), however, will require the Xcode IDE.
To develop for iOS, register as an Apple developer and download Xcode, Apples IDE for
developing iOS or Mac applications.
4-27
Student Notebook
24
WU5061.1
Notes:
Use the following link to register as an Apple developer:
http://developer.apple.com/programs/start/register/create.php
During this step, you have the choice of creating a new Apple ID or use an existing one. An
Apple ID is used to access iTunes, the Apple Online Store or a MobileMe account. It is
required to register as an Apple developer. Follow the Apple registration wizard to complete
the process.
V8.1
Student Notebook
Uempty
25
WU5061.1
Notes:
Xcode is an integrated development environment (IDE) containing a suite of software
development tools developed by Apple for developing software for OS X and iOS. First
released in 2003, Xcode is available via the Mac App Store free of charge for Mac OS X
Lion (and later) users. Xcode can only be installed on an Apple Mac machine. This means
that you do need a Mac machine to develop and test Worklight iOS applications.
For more information on how to get Xcode, visit:
https://developer.apple.com/technologies/tools/
Xcode integrates all the tools a developer needs to develop an iOS application. This
includes tools to write source code, compile and build. It also provides features such as
debugging and designing a user interface in a single window.
One of the handy tool provided by Xcode is the iOS simulator which you can use to test
most of application functions without a real device. The iOS Simulator presents the iPhone
or iPad user interface in a window on your Mac. It provides several ways to interact with it
by using the keyboard and mouse to simulate taps, device rotation, and other user actions.
4-29
Student Notebook
With the simulator, you can test your applications user interface and discover problems
early during testing.
Real device testing is also important for mobile application development. With Xcode, all
testing devices can be easily managed. You first need to provision a device before you can
deploy an application to it. Then you can install, update and uninstall the application. You
can also restore or install a new version of iOS on the device.
V8.1
Student Notebook
Uempty
26
Figure 4-25. Developing for iOS: Worklight Studio and Xcode integration
WU5061.1
Notes:
With Xcode installed, you can start to develop your Worklight application to run on the iOS
platform. Worklight Studio automatically generates an Xcode project for the application. It
also provides an easy option to launch your application in Xcode where you can compile
and run it using the iOS simulator or deploy it to a real device for testing.
4-31
Student Notebook
V8.1
Student Notebook
Uempty
4-33
Student Notebook
Overview of mobile
development steps
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
The Worklight Studio mobile application development steps consist of:
Creating a project for the application
Coding the applications user interface and business logic
Building the application and deploying it to the embedded Worklight Server
Previewing the application in the browser
If developing for iOS, building the application in Xcode
Testing the application on a simulator
Testing the application on a physical device
Publishing the application when development is complete
During the preview and test phase, you may cycle back to the construction phases to
correct any coding errors.
The next topic sections look at each of these steps in detail.
Copyright IBM Corp. 2013
4-35
Student Notebook
V8.1
Student Notebook
Uempty
4-37
Student Notebook
Creating a project
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
30
WU5061.1
Notes:
To start the Worklight Project wizard:
From the menu bar, select File > New Worklight Project. Alternatively, you can click the
Worklight icon from the tool bar, then select Worklight Project as shown in the screen
capture here.
4-39
Student Notebook
31
Figure 4-30. Worklight project creation wizard: Project name and type
WU5061.1
Notes:
In the Worklight Project page, specify the project name and application or component type
that it will contain.
A Worklight project contains at least one hybrid application, inner application or shell
component. Once the project is created, you can add as many Worklight applications
and/or components to it as you want.
A hybrid application is a standard Worklight application type where both web and native
shell components are packaged into a single unit of deployment.
An inner application contains web resources (HTML, JavaScript, and CSS) that will be run
inside of a shell component.
A shell component is used by inner applications as a code base wrapper. Usually, it
consists of native classes and shell-specific web resources that are used in inner
applications. A shell component is implemented by shell developers and sent to inner
application developers to use.
V8.1
Student Notebook
Uempty
Inner applications and shell components are discussed in detail in the Team development
unit.
4-41
Student Notebook
32
Figure 4-31. Worklight project creation wizard: Hybrid application UI framework selection
WU5061.1
Notes:
In the Hybrid Application page, specify the application name and optionally select a
JavaScript User Interface (UI) mobile framework to use.
You can package Dojo, jQuery Mobile or Sencha Touch libraries into your application. You
will learn more about this in the Working with UI frameworks unit.
A Hybrid application can contain HTML, JavaScript and CSS code along with native code,
allowing you to develop a mobile web, hybrid or pure native application.
When you click Finish, Worklight Studio generates a default project structure with an
application folder and initial skeleton code. You look at this structure next.
V8.1
Student Notebook
Uempty
Server customization
components
WU5061.1
Notes:
The main components of the Worklight project structure created by the wizard include:
A set of artifacts and core libraries used by Worklight applications, including JRE and
JavaScript libraries. These are primarily used for application development and
deployment.
A folder named adapters that contains the projects adapters. Adapters are the
server-side code of applications deployed on and serviced by the Worklight Mobile
Application Platform. Adapters connect to enterprise applications (back-end systems),
deliver data to and from mobile applications, and perform any necessary server-side
logic on this data.
A folder named apps that contains Worklight applications belonging to this project.
A folder named Server that contains the configuration and third party libraries used by
the embedded Worklight test server.
4-43
Student Notebook
A bin folder that contains generated deliverables that will be deployed to the Worklight
server, once you build your application. The contents of this folder should not be modified
manually.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
All Worklight applications are organized under the apps folder.
After the project creation wizard finishes, several folders and files automatically created
under the apps/<applicationName> folder:
1. The most important one is the common folder as it contains the default environment for
a Worklight application. A Worklight application is built to run in multiple mobile, tablet
or even desktop runtime environments. Each runtime environment differs from the
other in many aspects such as screen size, orientation, specific UI guidelines and
components, physical user interface, unique environment functionality and more.
Worklight uses the environment concept to organize application artifacts into separate
units where runtime specific customization or optimization can be applied. For
example, you can create an iPhone environment vs. Android environment.
The common environment contains all the resources that are shared between
environments. Worklight generates a default HTML page and several subfolders to
contain your web application artifacts. Specifically:
4-45
Student Notebook
- A skeleton HTML file, named after your application is created. This HTML file is
often referred as the main HTML file. It loads all the web resources (scripts and style
sheets) necessary to define the general components of the application, and to hook
to required document events.
- A css folder is created to store application style sheets. Two skeleton css files are
generated in this folder. The one named after your application contains your main
application style sheets. A reset.css is also provided to bring all rendering engines
such as the mobile Webkit browser or the desktop browser to one common ground.
- Worklight also creates a js folder for JavaScript code that implements interactive
user interface components, business logic, backend query integration, and message
dictionary for localization purposes. Three default JavaScript files are created during
the application creation process. The one named after your application acts as the
main JavaScript file for your application. Worklight also creates a message.js file to
define JSON objects to hold all application messages. This is primarily used for
localization. Another generated JavaScript file is named auth.js and allows the
developer to add Worklight authentication logic when needed. All three JavaScript
files are loaded from the default main HTML page.
- Finally, an images folder is created to store application images.
1. The legal folder contains license documents for the application or third-party software
used in the application.
2. application-descriptor.xml file: The application descriptor is a mandatory XML file
containing application metadata, located in the apps root directory. This file is
auto-generated by the Worklight Studio application creation wizard and can then be
manually edited to add custom properties. Every application has an application
descriptor.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
You will learn more about the relationship between additional environments and the
common environment when discussing Code Optimization in a later unit.
4-47
Student Notebook
WU5061.1
Notes:
Worklight Studio contains an embedded Worklight Server to use for development and
testing. Its configuration is controlled by the contents of the server folder. Specifically:
The conf folder contains the authenticationConfig.xml file which allows you to define
security and authentication information, and the worklight.properties file which specifies
server configuration information, such as the server hostname and port number.
The lib folder contains third party libraries used by your project. For example, you can
put JAX-RS jar files here if you are building RESTful services.
The Java folder houses custom Java code that you develop for components like a
Worklight adapter or a Worklight custom authenticator.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
The bin folder contains generated Worklight project artifacts such as the application
package file that is deployed to the Worklight Server (similar to a deployable EAR or WAR
file in Java EE).
Worklight applications and adapters are packaged as .wlapp and .adapter files that
essentially jar compatible zip files, respectively.
The bin folder is empty until you build the application for the first time.
4-49
Student Notebook
WU5061.1
Notes:
The Worklight application descriptor, named application-descriptor.xml, is a metadata file
that is used to define various aspects of the application.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
In the <application> tag, id defines the unique identifier of the application. It must be an
alphanumeric string that starts with a letter.
The application descriptor allows you to specify the application name, its description and
the authors name and contact e-mail address. This information is displayed in the
Worklight Console.
4-51
Student Notebook
iPhone
environment
Android
environment
WU5061.1
Notes:
As mentioned before, the environment concept is an important building block of a Worklight
application. Environment specific information is defined in the application descriptor.
Each environment on which the application can run must be declared with a dedicated XML
element. Each such element has one mandatory attribute, version. The value of this
version is a string of the form x.y, where x and y are numeric.
When you create an environment, a new entry is be automatically added to the application
descriptor for you to further customize.
V8.1
Student Notebook
Uempty
4-53
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
The main HTML file is created to comply with HTML5 standard markup as indicated by the
DOCTYPE definition. You may change this, but the HTML5 standard is highly
recommended. During the runtime of an application, the main HTML document cannot be
replaced by another HTML document.
At top of the file, a meta tag named viewport controls the rendering layout of the page on a
mobile browser. For example, it defines the devices width and how HTML content should
scale on the device.
4-55
Student Notebook
WU5061.1
Notes:
Add a <script> tag to the body section, to define and load any additional business logic
JavaScript files that your application uses.
V8.1
Student Notebook
Uempty
Palette
WU5061.1
Notes:
Worklight Studio 6.0 contains a new rich page editor for building UI of mobile apps. The
editor enables developers to create HTML files by dragging HTML5 components and Dojo
Mobile components from a built-in palette to the HTML canvas, and using property sheets
to control HTML and CSS properties of the components. At the same time, the editor
allows direct editing of HTML and CSS files, automatically updating the graphical canvas
so that developers can immediately see the result of their changes. The editor is integrated
with the Worklight optimization framework, allowing developers to view a specific
application environment or skin.
You will learn more about the Rich Page Editor in a subsequent unit.
4-57
Student Notebook
You can also add business logic to the main JavaScript file or put it in
separate files that you can declare in the main HTML file
WU5061.1
Notes:
The <appName>.js file is the applications main JavaScript file and contains the application
logic.
By default, an empty JavaScript function named wlCommonInit() is defined in it. This
function is invoked automatically once when the Worklight framework initializes. This is the
place where you can add your applications initialization logic, such as making any
necessary backend connections, checking device features, and so on.
Also, this function is used in environment-specific JavaScript files to have a common
initialization starting point. You will learn more about this feature when you discuss Code
Optimization in a subsequent unit.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
Alternatively, you can right-click the application folder and select New > Worklight
Environment. This launches the Worklight environment creation wizard.
4-59
Student Notebook
WU5061.1
Notes:
The Worklight Environment window allows you to select the different platforms for which
you want to create an environment in your application.
V8.1
Student Notebook
Uempty
Maps to
WU5061.1
Notes:
After adding an Android environment, two new folders are automatically created in your
application folder:
A folder name android at the same level as the common folder
An Android project folder named <yourProjectNameYourApplName>Android in your
workspace. This auto-generated folder does not contain a copy of the code, but is
mapped to the native folder in the android folder of the application.
4-61
Student Notebook
WU5061.1
Notes:
Worklight studio automatically creates three folders for the newly created Android
environment:
The css folder contains style properties that you want to override from css files in the
common folder. So, if you want to design a different look and feel for your Android user
interface, you can add or modify css files in this folder.
In the images folder, you can add Android specific images. If an image with the same
file name exists in the common folder, it will be overwritten in the Android application.
The js folder is created to allow you to add JavaScript that can extend or override
JavaScript code in the common folder.
The native folder created in the android environment folder contains automatically
generated Android application code and artifacts. These consist of the Android native code
that you compile and run on the Android emulator or a real device, and configuration files.
In this folder, Worklight packages its own native shell, Apache Cordova framework libraries
and all of the applications web content required to run it on an Android device.
4-62 Mobile Application Development with IBM Worklight V6
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V8.1
Student Notebook
Uempty
The assets sub-folder contains the entire web application resources including HTML,
JavaScript, CSS and image files. These are generated artifacts with optimization applied
for the Android environment. Do not directly edit the files in this folder, as they are
re-generated each time the application is built.
The contents of the native folder are packaged and automatically imported into the Eclipse
workspace as an Android project named yourProjectNameYourApplNameAndroid.
4-63
Student Notebook
The iphone folder contains the following subfolders, similarly found in the common folder:
css
images
js
WU5061.1
Notes:
After adding an iPhone environment, a folder named iPhone is automatically created in
your application folder at the same level as the common folder.
Worklight studio automatically creates three folders for the newly created iPhone
environment:
The css folder contains style properties that you want to override from css files in the
common folder. So, if you want to design a different look and feel for your Android user
interface, you can add or modify css files in this folder.
In the images folder, you can add iOS specific images. If an image with the same file
name exists in the common folder, it will be overwritten in the iOS application.
The js folder is created to allow you to add JavaScript that can extend or override
JavaScript code in the common folder.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
The native folder contains automatically generated iPhone application code that you can
compile and run in the Apple Xcode IDE. In this folder, Worklight packages its own native
shell, Apache Cordova framework libraries and all of the applications web content required
to run it on an iOS device.
The www sub-folder under native contains the entire web application resources including
HTML, JavaScript, CSS and image files. These are generated artifacts with optimization
applied for the iOS environment. Do not directly edit the files in this folder, as they are
re-generated each time the application is built.
The nativeResources folder hosts resources that are used by the native code.
The package folder contains a packaged (zipped) application that is ready to be transferred
to an Xcode environment to compile and build. This is useful when you are developing
your Worklight application on a Windows machine, and later want to transfer the code to a
Mac machine to compile and build.
4-65
Student Notebook
V8.1
Student Notebook
Uempty
4-67
Student Notebook
Building your
application
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Building an application
Select an application folder to build and
right-click it
Click Run As > Build All and Deploy
After the build completes, the application
is available for preview in the Worklight
Console
WU5061.1
Notes:
You can choose to build for all environments or a specific one.
The build process creates a set of .wlapp files the bin folder of your Worklight project:
If you build for all environments, a file named <app-name>.wlapp is created, containing
the code and resources of all environments supported by your application (For
example: HelloWorklight.wlapp).
If you build only for specific environments, a file named <app-name>-<env><version>.wlapp is created for each environment (For example:
HelloWorklight-android-1.0.wlapp).
When the build process is finished, it deploys the application to the embedded Worklight
Server. You can then for preview it in the Worklight console.
4-69
Student Notebook
V8.1
Student Notebook
Uempty
4-71
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
Previewing is normally the first step in your application testing, followed by a more thorough
test using a device simulator, and finally a complete test on a physical device.
4-73
Student Notebook
V8.1
Student Notebook
Uempty
4-75
Student Notebook
Previewing your
application in the
browser
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
The Worklight Console is a web-based administration tool used to manage the Worklight
Server, installed applications and adapters, and push notification services.
The consoles Catalog tab lists all deployed applications and allows you to preview them.
4-77
Student Notebook
WU5061.1
Notes:
Click the preview icon or active link text to open the application in the Mobile Browser
Simulator for the specific environment.
V8.1
Student Notebook
Uempty
59
WU5061.1
Notes:
The Mobile Browser Simulator mimics a real device from a general look and feel
perspective. It allows you to emulate a number of Apache Cordova functions and alter the
device skins to see how your application renders on different devices. It also allows you to
customize the User Agent header value which is often used to detect a device type such as
iOS or Android.
In addition, because the Mobile Browser Simulator runs your application in a browser, you
can leverage the browsers debugging and development tools to do advanced debugging.
For example, you can use Firefoxs firebug tool to analyze the HTML DOM elements or set
breakpoints and step through JavaScript execution.
You will learn more about the Mobile Browser Simulator in a subsequent unit.
4-79
Student Notebook
60
WU5061.1
Notes:
You will learn more about the Mobile Browser Simulator in a subsequent unit.
V8.1
Student Notebook
Uempty
4.10.Testing on a simulator
4-81
Student Notebook
Testing on a simulator
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
Worklight Studio simplifies the development and test of application for the Android platform.
When you build a Worklight application using Worklight Studio, the build process generates
a separate Android project that will automatically appear in your workspace. There are no
extra processes required to convert your Worklight application into an Android application.
Worklight Studio also take cares of application updates for the generated Android project.
This build process does require that you have the Android ADT and SDK installed prior to
the build.
To test and run your Worklight application on the Android emulator, you simply right click
your application, and select Run As > Android Application from the context menu as shown
in the figure here. You need to have at least one Android AVD created before you can run
your application as an Android Application.
4-83
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
The Eclipse IDE, where Worklight studio runs, does not support iOS application
development, therefore your application needs to be opened in Apples native Xcode IDE
to compile and run.
For developers running Eclipse on a Mac, Worklight studio simplifies this process by
integrating the Xcode launch process right in Eclipse. You can right-click iPhone project
and select Run as > Xcode project. The Worklight plug-in automatically opens the
application in Xcode. Alternatively, you can open a Mac Finder window, locate the iPhone
environments native folder, and double-click the applications .xcodeproj file.
4-85
Student Notebook
WU5061.1
Notes:
If you are running a Windows version of Eclipse, copy and unzip the applications iPhone
archive file generated in the package folder to a folder on your Mac. Then, double-click the
applications .xcodeproj file from this folder to open it in Xcode.
V8.1
Student Notebook
Uempty
Figure 4-65. Testing on the iPhone simulator: Building and running an application (1 of 2)
WU5061.1
Notes:
Once in xCode IDE, simply click the Build and Run button to preview your application in
iOS simulator. Depends on the environment you are testing, you need to select the correct
simulator, either iPhone or iPad simulator.
4-87
Student Notebook
Figure 4-66. Testing on the iPhone simulator: Building and running your application (2 of 2)
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Testing on a device
WU5061.1
Notes:
4-89
Student Notebook
Once the pre-requisites are met, you can select to run your application
on the device in the Android Device Chooser window.
For more information on how to set up your development environment
and Android-powered device for on-device testing and debugging, visit:
http://developer.android.com/guide/developing/device.html
Copyright IBM Corporation 2013
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
As set by Apple, in order to deploy an application on a physical device or preparing it for
distribution, you need to enroll in the Apple iOS Developer Program. During this step, you
may invite other developers to the development group if you register as company. Then,
developers need to manage the devices to be used for testing the application (for example,
create and install a provisioning profile).
4-91
Student Notebook
Figure 4-70. Testing on an iOS device pre-requisite: Enroll in the iOS Developer Program
WU5061.1
Notes:
Use the following link to enroll in the iOS Developer Program:
https://developer.apple.com/programs/start/standard/
With the iOS simulator, you can start developing iOS applications without using an real
device. However, you must always test your applications on an actual devices before
publishing them to ensure that they run as intended and to performance tune them.
Before you can test an application on a real iOS device or distribute it to the Apple App
store, you need to enroll in as paid subscriber in the iOS Developer Program. During this
process, you can choose to register as an individual or as a company.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
The process of preparing an iOS device to use for application deployment and testing
involves:
Creating a public/private key pair using the Mac KeyChain program on the developers
machine.
Submitting a Certificate Signing Request using the generated key on the iPhone
Developer Program Portal.
Downloading and storing the created development certificate on the developers
machine.
Registering the iOS devices Unique Device Identifier (UDID) to the Developer Program
Portal. You can usually find out a devices UDID either from iTunes or Xcode Organizer.
Creating a unique ID for your application (App ID).
Creating a Provisioning Profile with the development certificate, device identifier and
App ID in the iPhone Developer Program Portal.
4-93
Student Notebook
Downloading the Provisioning Profile to the local development machine and installing it
on the device.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
4-95
Student Notebook
Publishing your
application
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
When you have successfully completed application development and on-device testing,
you can distribute your application for public access. Prior to doing so, prepare it as
indicated in this slide.
4-97
Student Notebook
WU5061.1
Notes:
To distribute your Android application for public use, use Google Play.
Publishing on Google Play takes a few simple steps: register, configure, upload, and
publish.
During the registration process you will need to create a developer profile, pay a
registration fee, and agree to the Google Play Developer Distribution Agreement.
After you register you can access the Developer Console, where you can upload
applications, configure publishing options, and monitor publishing data.
When you have configured your application information and publishing options, you can
upload the Android application .apk file and publish it in Google Play for public access.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
To distribute your iPhone application for public use, use the Apple App Store.
4-99
Student Notebook
Checkpoint
1. True or False: For iOS development, you need the Xcode IDE in
addition to Worklight Studio in order to compile an application and
test it on an iOS simulator.
2. What is default structure of a Worklight application?
a)
b)
c)
d)
c)
Define an additional Worklight Server where you can deploy the application.
Copyright IBM Corporation 2013
WU5061.1
Notes:
Write your answers here:
V8.1
Student Notebook
Uempty
Checkpoint answers
1. True or False: For iOS development, you need the Xcode IDE in
addition to Worklight Studio in order to compile an application and
test it on an iOS simulator.
True
b)
c)
d)
WU5061.1
Notes:
4-101
Student Notebook
Unit summary
Having completed this unit, you should be able to:
Install IBM Worklight Studio using the Eclipse Update Site
Set-up an Android or iOS development environment
Explain the Worklight development framework
Describe the Worklight Studio mobile development tools
Describe the steps involved in creating, building and testing an
application in Worklight Studio
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Exercise 1
WU5061.1
Notes:
4-103
Student Notebook
Exercise objectives
After completing this exercise, you should be able to:
Install IBM Worklight Studio from an IBM Worklight V6.0 Developer
Edition package
Configure an Android development environment
Develop a simple Hello Worklight mobile application
Test the simple application in the browser and on an Android or iOS
virtual device
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
References
IBM Worklight V6 documentation:
http://pic.dhe.ibm.com/infocenter/wrklight/v6r0m0/index.jsp
5-1
Student Notebook
Unit objectives
After completing this unit, you should be able to:
Identify essential Worklight client-side APIs including those that enable
cross-platform portability and localization
Explore the syntax of the JavaScript functions supporting the APIs
WU5061.1
Notes:
5-2
V8.1
Student Notebook
Uempty
Topics
Client-side basics
Building a multi-page application
Common controls
Skins
Offline access
String translation
WU5061.1
Notes:
5-3
Student Notebook
5-4
V8.1
Student Notebook
Uempty
5-5
Student Notebook
Client-side basics
8.0
WU5061.1
Notes:
5-6
V8.1
Student Notebook
Uempty
Application sources
Main HTML file:
For example, HelloWorklight.html
HelloWorklight.html
HelloWorklight.js
Messages.js
initOptions.js
wljq.js
wlclient.js
wlcommon.js
wlfragment.js
worklight.js
busy.js
WU5061.1
Notes:
The main HTML file is the ultimate loader for all application and Worklight client API
JavaScripts. Worklight client runtime depends on this HTML file to define and actually load
the necessary APIs. Some of JavaScript loading only shows up on generated environment
specific main HTML file.
The main JavaScript file contains application logic including initialization, back-end data
access and loading of other application logic modules.
Messages.js is used for storing application strings, primarily used for localization.
Normally, the application developer works with the main HTML and JavaScript files.
The main HTML and main JavaScript files are available under the application common
folder when a new Worklight application is created. These are application specific
components that are developed and owned by your development team.
Another core library used by Worklight client API (not shown on slide) is the jQuery library.
Worklight comes bundled with an encapsulated jQuery, which can be added to developers
project with a single line of code. jQuery is discussed in a later unit.
Copyright IBM Corp. 2013
5-7
Student Notebook
Worklight initialization
Defines application initialization options
HelloWorklight.html
HelloWorklight.js
Messages.js
initOptions.js
wljq.js
wlclient.js
wlcommon.js
wlfragment.js
worklight.js
busy.js
WU5061.1
Notes:
The initOptions.js file is included in the project template. It is used to initialize the Worklight
JavaScript framework. It contains a number of tailoring options, which you can use to
change the behavior of the JavaScript framework. These options are commented out in the
supplied file. To use them, uncomment and modify the appropriate lines.
The initOptions.js file calls WL.Client.init, passing an options object that includes any
values you have overridden.
5-8
V8.1
Student Notebook
Uempty
HelloWorklight.html
HelloWorklight.js
Messages.js
initOptions.js
wljq.js
wlclient.js
wlcommon.js
wlfragment.js
worklight.js
busy.js
WU5061.1
Notes:
In IBM Worklight V6, the jQuery library that is used as part of the product is upgraded to
version 1.9. If you are using other JavaScript libraries such as jQuery Mobile, you should
upgrade the version.
Note carefully the reference for the encapsulated jQuery in Worklight that is shown on this
page. It should be placed in the appName.js file. There is no error message, or problem
indicated if you do not include this line. But you may find that you get strange results (such
as an empty view) if you forget it!
5-9
Student Notebook
HelloWorklight.html
HelloWorklight.js
Messages.js
initOptions.js
wljq.js
wlclient.js
wlcommon.js
wlfragment.js
worklight.js
busy.js
WU5061.1
Notes:
There are several reference to these APIs, as well as to the WL namespace, throughout
this course.
V8.1
Student Notebook
Uempty
The WL namespace
To use Worklight API, a WL namespace is used
WL.Client, WL.Utils, and so on
WU5061.1
Notes:
The WL namespace is fundamental to the Worklight API (WL.Client, WL.Utils, and so on).
The application HTML page is initialized with WL.Client.init() in the body onload attribute.
The namespace is automatically available when the application is initialized.
5-11
Student Notebook
WL.Client
WL.Client.init (options) initializes the WL.Client object
onSuccess
onFailure
connectOnStartup
busyOptions
WU5061.1
Notes:
The onSuccess function is used to initialize the application.
If an onFailure function is not passed, a default onFailure function is called. If onFailure is
passed, it overrides any specific failure-handling function.
connectOnStartup: Whether to connect to the IBM Worklight Server. The default if no value
is specified is true. However, the value as set in the initOptions.js file is false. The value
false is appropriate if your application does not retrieve any corporate data on startup.
Note, though, that any server features such as Remote Disable or Direct Update are only
available after the application connects to the server.
The value true is appropriate if your application must receive data from the server when it
starts. However, the application might start more slowly.
WL.Client.reloadApp() - reloads the application. It can be used to recover an application
from errors. It is preferable to avoid using it and to use alternative error handling
mechanisms instead. The method is mainly available for compatibility with earlier versions.
V8.1
Student Notebook
Uempty
WL.Logger
A part of the WL.Client library
To enable the logger you must set the option on WL.Client.init(options)
WL.Client.init({showLogger:true})
WU5061.1
Notes:
The WL.Logger.debug and WL.Logger.error methods output a specified debug or error
message to the environments log.
For iPhone and iPad, these methods print the message to the debugger console of Xcode,
the development environment for iPhone and iPad.
For Android, these methods print the message to the Android LogCat, accessible in the
Android development environment. Error messages are displayed in red; debug messages
are displayed in the default log line color.
For BlackBerry 6 and 7, these methods print the message to the BlackBerry event log. The
event log can be viewed on the device and in the BlackBerry Eclipse simulator and
debugger by pressing the key sequence Alt+LGLG.
To disable logging, include enableLogger: false in the object wlInitOptions in the
initOptions.js file.
var wlInitOptions = {enableLogger: false }
5-13
Student Notebook
WL.Logger - example
Use to troubleshoot environments without debugging tools
WL.Logger.debug(message)
WL.Logger.error(message)
WU5061.1
Notes:
The Logger API is intended as a development tool. If there is a need to inform the user
about a problem, there are other more appropriate ways to display the information (an alert,
for example). There is also WL.Client.logActivity (activityType). This stores custom log lines
for auditing and reporting purposes in special database tables, and is the API to use for
production-level auditing.
V8.1
Student Notebook
Uempty
5-15
Student Notebook
Building a multi-page
application
8.0
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
id=loginPage>
id=loginPage>
id=Page1>
id=Page1>
id=Page2>
id=Page2>
id=Page3>
id=Page3>
id=Page4>
id=Page4>
id=Page5>
id=Page5>
.......
.......
loginPage.html
loginPage.html
Page1.html
Page1.html
Page2.html
Page2.html
Page3.html
Page3.html
Page4.html
Page4.html
Page5.html
Page5.html
WU5061.1
Notes:
Worklight multi-page applications can be built in two ways:
You can host your entire application content in a single HTML file. Different components of
an application or mobile pages can be grouped under a unique div block. The application
developer can control which div page to show and programmatically handle the transition
between pages. This is good for very simple application.
A single HTML file is the preferred model for a simpler applications. However, large
applications present a challenge:
- The developer has to take full responsibility of which <div> elements are shown and
which are hidden at any given moment.
- If you want to add some new content to a page, e.g. a table, you cannot load a
prepared template but must generate it manually.
- Single large HTML files with lots of divs take longer to load.
- It is easy to get lost in a single HTML file containing multiple pages. Separate files
are easier to manage.
Copyright IBM Corp. 2013
5-17
Student Notebook
A Worklight hybrid application uses the single DOM model, which means that you must
never navigate between various HTML files by using hyperlinks or changing
window.location property
Instead, multi page interfaces must be implemented by loading external HTML file content,
using Ajax requests and injecting it into existing DOM. This is because the main application
HTML file loads the Worklight client side JavaScript framework files, and when the browser
navigates from one HTML file to another, the JavaScript context and loaded scripts are lost.
Most JavaScript UI frameworks (for example, jQuery Mobile, Sencha Touch, Dojo Mobile)
available today provide extensive APIs to achieve required multi-page navigation.
In this module, you learn how to build a multi-page Worklight application by using built-in
functionality only.
Important you must not use the built-in functionality that is described in this module if you
are using a JavaScript UI framework. You should use the framework APIs instead.
V8.1
Student Notebook
Uempty
<link
<link href="css/page1.css"
href="css/page1.css" />
/>
<script
src="js/page1.js"
type="text/javascript"></script>
<script src="js/page1.js" type="text/javascript"></script>
<div
<div id="page1div">
id="page1div">
This
This is
is page1
page1
</div>
</div>
WU5061.1
Notes:
For more information, see http://pic.dhe.ibm.com/infocenter/wrklight/v6r0m0/index.jsp, and
search for Splitting Your Code between HTML Pages (URL correct as of July 2013).
5-19
Student Notebook
Design considerations
Building a rich dynamic application with multiple pages can be easier
with dynamic pages loading
You can use built-in jQuery APIs to dynamically load, update and insert
DOM elements in your application
HTML pages with CSS and JavaScript can be inserted on the fly.
Possible to implement navigation history
JavaScript code can be executed when pages are loaded or unloaded
In the following slides you learn and implement a simple multi page
navigation interface
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
$(containerSelector).load(filePath,
$(containerSelector).load(filePath, callbackFunction);
callbackFunction);
WU5061.1
Notes:
Here is a definition of the elements of the code on the slide:
- containerSelector jQuery css selector of element to host the loaded content
- filePath Relative path to an HTML file. Always relative to main HTML file
- callbackFunction - a JavaScript function to execute when loading completes
5-21
Student Notebook
WU5061.1
Notes:
MainPage.html does not replace MulitPageApp.html its contents is added to the div that
has the id pagePort. The load function takes two arguments: what to load, and what to do
after the load has completed. In the example on the image, an alert will be displayed once
the contents of MainPage.html is added to the pagePort div element.
V8.1
Student Notebook
Uempty
Application
Application
HTML
HTML file
file
MainPage.html
MainPage.html
MainPage.js
MainPage.js
Page1.html
Page1.html
Page1.js
Page1.js
var
var == pagesHistory
pagesHistory == [];
[];
var
var == currentPage
currentPage == {};
{};
WU5061.1
Notes:
This page shows the general scenario that is discussed over the next three pages. The two
problems to address are: What do you want to see next, and where did you come from to
get to this view. Therefore, you need to add the correct page to the application html, and
keep navigation history so that you can return.
5-23
Student Notebook
MainPage.html
MainPage.html
MainPage.js
MainPage.js
WU5061.1
Notes:
1. On application start MainPage.html is loaded from the application code and injected into
the #pagePort div
2. As a part of MainPage.html, MainPage.js is loaded
3. The currentPage object is declared
4. The currentPage.init function is declared
5. When the MainPage.html loading completes, currentPage.init method is called
V8.1
Student Notebook
Uempty
Page1.html
Page1.html
Page1.js
Page1.js
WU5061.1
Notes:
1. MainPage.html is pushed into pagesHistory stack
2. Page1.html is loaded and injected into #pagePort div
3. Page1.js is loaded as a part of Page1.html
4. currentPage object is declared (overriding the old one)
5. currentPage.init function is declared
6. When Page1.html loading completes, a new currentPage.init method is called
5-25
Student Notebook
Page1.html
Page1.html
Page1.js
Page1.js
WU5061.1
Notes:
1. Previous html file name is popped from the pagesHistory stack (MainPage.html).
2. It is loaded and injected into #pagePort <div>
3. MainPage.js is loaded as a part of MainPage.html
4. currentPage object is declared (overriding the old one)
5. currentPage.init function is declared
6. When MainPage.html loading completes, the currentPage.init method is called
V8.1
Student Notebook
Uempty
5-27
Student Notebook
Common controls
8.0
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Busy indicator
Tab bar
Simple dialog
WU5061.1
Notes:
Worklight common controls are sets of pre-built client side libraries or UI widgets for
frequently used UI functions such as modal popup, loading screens, tab bars, and so on.
These UI components are common to most device environments. Worklight provides a
JavaScript API to invoke these controls regardless of environment, and automatically
renders them in a native way for each platform.
Developers can therefore save a lot of time, since they so not have to build these UI
component controls. They customize them to render in a native fashion for each supported
device environment.
In this section, you explore 4 different types of common controls.
5-29
Student Notebook
WL.BusyIndicator (1 of 3)
WL.BusyIndicator implements a common API to display a modal
activity indicator
Uses native implementation on Android, iPhone and Windows Phone
platforms
WU5061.1
Notes:
The WL.BusyIndicator object can be used to display a modal, dynamic graphical image
when the application is temporarily busy, that is, not responsive to user input. This is
important from user experience perspective.
WL.BusyIndicator is implemented natively on iOS, Android, BlackBerry, and Windows
Phone as shown from the images on this page. In other environments it is implementing
using JavaScript with Busy.js.
One of the benefit of using this common control is that application developers dont need to
develop a native look and feel indicator for all the supported platforms, but rather accesses
a single unified Worklight API.
V8.1
Student Notebook
Uempty
WL.BusyIndicator (2 of 3)
Must be initialized before use
The parent element ID for WL.BusyIndicator is ignored in iOS,
Android, Windows Phone and BlackBerry environments
Available options are:
text: set the modal text
color: set the modal text
fullScreen: use if modal message should be displayed full screen (iOS only)
Options
WU5061.1
Notes:
The application initializes the BusyIndicator by creating a new WL.BusyIndicator object.
The first parameter specifies the parent element ID where the WL.BusyIndicator is
placed. This parameter is ignored in iOS, Android, Windows Phone and BlackBerry
environments.
The second parameter specifies the look and feel and general behavior of the
BusyIndicator. For example, the text message to be displayed in the BusyIndicator and
color of the text etc. These options varies for different device platform. For example.
Android supports only text property. For detail information about additional options, refer to
the Developers Guide.
5-31
Student Notebook
WL.BusyIndicator (3 of 3)
WL.BusyIndicator provides the following API:
Initialization
void myBusyIndicator.show(): displays busy indicator
void myBusyIndicator.hide(): hides busy indicator
boolean myBusyIndicator.isVisible(): returns whether busy indicator is currently
visible
WU5061.1
Notes:
Once a BusyIndicator is created, you can issue show() and hide() method to either display
or hide the defined busy indicator.
To test whether the busy indicator is currently visible, you can use isVisible() method.
V8.1
Student Notebook
Uempty
WL.SimpleDialog (1 of 3)
WL.SimpleDialog implements a common API for showing a modal dialog window with
buttons
Uses native implementation on mobile platforms
WU5061.1
Notes:
WL.SimpleDialog implements a common API for showing a dialog with buttons for the
application. This technology is useful in constructing informational popups or getting users
attention.
The implementation of Worklight SimpleDialog depends on the environment. On iPhone,
Android, and BlackBerry as shown in the images in this slide, WL.SimpleDialog opens a
native dialog box; on other environments it opens an HTML dialog box. The goal is to
provide a native look and feel dialog box with a single unified API.
WL.SimpleDialog supports up to three buttons.
5-33
Student Notebook
WL.SimpleDialog (2 of 3)
Invocation syntax is:
Parameters: title, text, and buttons as an array of up to three button objects
The dialog is closed when any of the buttons is clicked
WU5061.1
Notes:
To display the SimpleDialog, call WL.SimpleDialog.show() function anywhere in your code.
With this common control, the dialog is displayed without blocking the JavaScript thread.
Worklight SimpleDialog takes four parameters:
The first parameter defines the title of the dialog box. It is mandatory.
The second parameter defines the text to show in the dialog box. It is also mandatory.
The third parameter represents the buttons to be placed in the dialog. You can add up
to three buttons.
The options parameter is ignored by iPhone and Android. It has the form { title: string,
text: string}.
The active Dialog is closed when any of the buttons is pressed.
V8.1
Student Notebook
Uempty
WL.SimpleDialog (3 of 3)
Each button object has two properties:
text: the text that is displayed on the button
handler: function to invoke if button is clicked
WU5061.1
Notes:
You can add up to 3 buttons to the simple Dialog. They are defined in an array of JSON
Objects, each array item represents a button on the dialog.
An button object can contain two properties: he text that is displayed on the button and
a callback handler function to invoke if button is pressed. This is where application logic
can respond to decisions from the Dialog actions.
5-35
Student Notebook
WL.TabBar (1 of 5)
Both Android and iOS environments support tabbed application
navigation with a tab bar component
WU5061.1
Notes:
The Android and iPhone tab bars are graphical element which look and work very much
like tab bars of regular web or desktop applications. They provide an simple navigation
mechanism for users to easily browse through the application on a mobile device.
Worklight provides a client-side API for managing the tab bar. On iPhone, this API serves
as a proxy to the native iPhone tab bar object; on Android, it is implemented as an HTML
element.
The screens captures depict an iPhone tab bar (on the left) and an Android tab bar (on the
right).
V8.1
Student Notebook
Uempty
WL.TabBar (2 of 5)
iOS implementation takes
advantage of a native
component, while Android uses
an HTML generated tab-bar
The syntax is very similar,
although there are some minor
differences
Not here!
WU5061.1
Notes:
WL.TabBar implementation for iOS and Android are slightly different. Thus, the Worklight
JavaScript libraries for Tab bar component is not packaged under common folder, but
stored under iPhone and Android environment js folder respectively. Even with some minor
differences, the API syntax are very similar for both platforms.
Like most of Worklight common controls, you need to initialized the Tab bar before using it
on both platforms. The API you use is WL.TabBar.init(). It is recommended to initialize
WL.TabBar in a designated JavaScript file. Normally, the high level main JavaScript file of
your application.
The init function Initializes the tab bar by creating necessary JavaScript objects and
enabling it, but keeping it invisible.
5-37
Student Notebook
WL.TabBar (3 of 5)
Use the following syntax to add a tab bar item:
itemID: Internal reference for this tab
callback: JavaScript function to run when tab item is pressed
title: The text to display on tab bar item
options: Varies on iOS and Android platform, see next slide
WU5061.1
Notes:
Before displaying a tab bar on the device, application needs to add tab items. A tab item
represents a navigation entry for your application.
Note, you can only add tab bar items after Tab bar is initialized.
You use WL.TabBar.addItem to add a tab item. This API takes four parameter:
First is the item id that uniquely identifies this tab item.
The callback function that should be invoked when the user touches this tab item. For
example, load a new page or bring up a Dialog box when this tab item is touched.
The third parameter specifies title text for this tab item for display.
The fourth parameter is an option object that contains device specific information of
how to render the tab item.
V8.1
Student Notebook
Uempty
WL.TabBar (4 of 5)
iOS options
Android options
tabButton:More
tabButton:Favorites
tabButton:Featured
tabButton:TopRated
tabButton:Recents
tabButton:Contacts
tabButton:History
tabButton:Bookmarks
tabButton:Search
tabButton:Downloads
tabButton:MostRecent
tabButton:MostViewed
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
On iPhone, you can specify the badge and image options. iPhone Badge is a string to
display in the optional circular badge on the item. The image property defines the filename
or path with a PNG image for the tab or an internal identifier for standard tabs. Worklight
allows application place some default iPhone tab item images such as defined in the list
here.
If the supplied image name is one of the labels listed here, then a tab button is constructed
using the standard system buttons. Note that if you use one of the system images, the title
you supply is ignored.
Similar to iPhone, the image property for Android defines a filename or path with a PNG
image for the tab in unselected mode. The imageSelected property defines filename with
an image for the tab in selected mode.
5-39
Student Notebook
WL.TabBar (5 of 5)
iOS example:
Android example:
WU5061.1
Notes:
The example here illustrates how to add an tab item on iOS and Android devices using
Worklight addItem API. Review the code in order to become familiar with API used here.
V8.1
Student Notebook
Uempty
WL.OptionsMenu (1 of 4)
Android and Windows Phone environments have
the ability to display an options menu
WU5061.1
Notes:
Option menu is available on Android and Windows phones as shown in the images on this
slide.
On Android, The Options menu contains primary functionality that applies globally to the
current activity or starts a related activity. It is typically invoked by a user pressing a button,
often labeled Menu.
Worklight provides a client-side API for managing the menu and application bar.
5-41
Student Notebook
WL.OptionsMenu (2 of 4)
Initialize WL.OptionsMenu in the
appropriate JavaScript file
The syntax is very similar to that of the
tab bar with some minor changes
Not here!
WL.OptionsMenu.init();
Not here!
WU5061.1
Notes:
You need to initialize the Worklight OptionsMenu before you can use it. To do this, use
WL.OptionsMenu.init. It is recommended to initialize WL.TabBar in the main JavaScript file
of your application.
Worklight OptionsMenu syntax is very similar to that of the TabBar. WL.OptionsMenu is
packaged under the same Worklight library JavaScript CommonControl.js as TabBar.
V8.1
Student Notebook
Uempty
WL.OptionsMenu (3 of 4)
Use the following syntax to add an options menu:
itemID: Internal reference for this menu option
callback: JavaScript function to run when menu option is pressed
title: The text of the menu item
options: An options object with the following properties:
image: A path to a designated image, relative to resources root directory.
48x48px black and white .png file
enabled: Boolean stating if the item is enabled or disabled
WU5061.1
Notes:
To add an option menu, use the API WL.OptionsMenu.addItem . This API can be called
only after initializing the Options menu. Items are placed in the menu in the order in which
they were added. If you add an item with an existing ID, the new item replaces the existing
one.
It can take up to 4 parameters:
ItemID represents the unique identifier of a menu item
Second parameter defines callback function that should be invoked when the user
selects the item in the options menu.
You can specify the Menu title text via the third parameter.
The Options parameter allows the application to customize the menu item and set it to
enabled or disabled.
5-43
Student Notebook
WL.OptionsMenu (4 of 4)
WL.OptionsMenu.addTab example
WU5061.1
Notes:
The example here illustrate how to add a Worklight OptionMenu item. It adds a menu item
named as First item with callback function that shows an alert popup indicating that the
first item is selected.
This menu item displays an image file from images/tabicon.png. The code sets this menu
item to show as enabled when menu button is pressed, if this is on Android device.
V8.1
Student Notebook
Uempty
5.4. Skins
5-45
Student Notebook
Skins
8.0
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Skins
Provide support for multiple form factors in a single executable file for
devices of the same OS family
A sub-variant of an environment
Packaged together in one App
The decision on which skin to use is made automatically at runtime
WU5061.1
Notes:
Worklight Skins are provided to support multiple form factors in a single executable file for
devices of the same OS family. An application skin is a set of web resources that govern
the application look and feel, and behavior. Skins are used to adjust the application to
different devices of the same family.
They are sub-variants of an environment. For example, your application may require a
different look and feel for Android phones and Android tablets. In this case, you can create
a android.tablet skin to host all the code required for this unique device type.
All application skins are packaged together in one Worklight application along with the
associated environment. You can package multiple skins in your application and decide in
run time, upon application startup, which skin to apply to the application.
5-47
Student Notebook
WU5061.1
Notes:
This slide looks at some of typical use case where you can apply Worklight Skins. First, you
may want to design applications for devices with different screen sizes under same OS
family; for example, develop Android phones application and android tablets application.
You can also use skins to specify the handling for different screen densities. Screen density
is the measurement of the resolution of particular devices. For example, create skins for
HTC vs. Samsung devices that have different screen densities.
Besides look and feel, you can also create different skins to handle different device input
methods. For example, touch vs. Keyboard based input method.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
Worklight Studio provides a wizard to create an application skin. You select the target
application, right click it to bring up the context menu, then select Worklight Application
Skin Wizard.
In the new skin wizard, the application developer needs to specify the skin name. The
wizard automatically prefixes your skin name with the OS family it associated with, for
example Android or iPhone.
Upon creating the new skin, Worklight generates a folder for the skin resources under the
name you specified in the wizard, for example android.phone. This folder is placed
adjacent to the environment directory.
The example screen capture on the left shows the wizard for a skin called android.phone.
The screen capture on the right shows the directories where the skin is packaged.
5-49
Student Notebook
WU5061.1
Notes:
When a skin is added, a JavaScript file named skinLoader.js is created under the js folder
of the environment.
The application developer implements the function getSkinName() of the skinLoader.js file.
There, you define the rules and policy on how to load a particularly skin based on your use
case. For example, you can add logic to check device manufacture model, and then apply
associated skin to this runtime.
V8.1
Student Notebook
Uempty
Skin Registration
Skins are automatically registered in the application descriptor
Determines the hierarchy between the common folder, environment
and skin
Modify the application
descriptor manually
when a skin is deleted
WU5061.1
Notes:
When adding a new application skin, Worklight studio adds a <skin> element in the
application descriptor. This element includes the name of the skin and a list of resource
folders. When the Studio builds the application, it applies the optimization rules on the
resource folders in the order they appear within the <skin> element.
The <skin> element includes the name of the skin and a list of resource folders. When the
Studio builds the application, it applies the optimization rules on the resource folders in the
order they appear within the <skin> element.
In the example here, two skins are packaged with the Android application: the default skin
and another two skins called android.phone and android.tablet.
To delete a skin, remove the element defining the skin from the apps descriptor. This is a
manual process.
5-51
Student Notebook
V8.1
Student Notebook
Uempty
5-53
Student Notebook
Offline access
8.0
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Developers can define custom application behavior for off- and on-line
status
WU5061.1
Notes:
Unlike traditional desktop web applications, mobile device are likely to lose connectivity to
the internet or any backend connections, for example, when there is very weak or no
wireless signal, or when user is on an airplane or in a tunnel. So, enable application to
continue operating even without any connectivity becomes a frequent requirement when
constructing mobile application in order to provide best user experience. We generally
referring application working without connectivity as Working in offline mode.
There are three ingredients to enable application to work in offline mode:
1. The application code and supporting binary should be made available during offline
mode.
2. Application needs to be able to detect connectivity status in order to switch application
processing to either online or offline mode.
3. Application and supporting environment need to be able to persist key application data
to local device in offline mode.
5-55
Student Notebook
Worklight provides a framework to address all three requirement in order to build a true
offline-enabled application.
First, for mobile application built with web technologies, Worklight either package it as a
hybrid application so that all web artifacts such as HTML and CSS files are downloaded to
local device along with application download process. For pure mobile web app, Worklight
uses HTML5 App cache feature to allow web artifacts to be downloaded and stored locally
on mobile device.
The Worklight client frameworks provides a set of APIs that application can use to detect
network connectivity status to decide go offline or online.
In the Worklight environment, application going off and online can be detected in two ways
Explicitly or Implicitly.
Explicitly detects occurs when your application launches or tries to invoke Worklight server
based procedures.
Implicitly detection is basically an event driven programming model. Your application
registered to certain network connectivity events then react to it.
In both case, application developer can define custom application logic to handle off and
online status. For example, retrieve application data from local storage when application
goes offline, and save and update local storage when application comes back online.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
There are two locations in your application code where connectivity loss can be detected:
The first place is during the application initialization phase. Worklight invokes a
WL.Client.init() method to initialize application. This method is normally invoked from the
main HTML body onload. The other place where you can detect connectivity is when
application invokes adapter procedure via API WL.Client.invokeProcedure.
Both API can take an option parameter that you can specify the connectivity detection
logic.
To add connectivity failure detection in either of them, add onConnectionFailure property
instead of onFailure and specify a callback function to be invoked in case connectivity fails.
Application developer often focus on implementing the callback function to react to offline
condition.
5-57
Student Notebook
Developers can add event listeners to these events and specify the
callback functions that handle them
WU5061.1
Notes:
Note that both WL.Events.WORKLIGHT_IS_DISCONNECTED and
WL.Events.WORKLIGHT_IS_CONNECTED are namespace constants, not strings.
Implicit detection helps to handle unexpected connectivity loss and allow application to
react to the offline mode.
Each time the Worklight framework attempts to access the Worklight Server, it might detect
that the application has switched from offline to online status or vice versa. This is handled
completely by Worklight framework such as heartbeat (discussed later).
In both cases, one of two JavaScript events can be fired
- WL.Events.WORKLIGHT_IS_DISCONNECTED event is fired in case connectivity
to the Worklight Server fails
- WL.Events.WORKLIGHT_IS_CONNECTED event is fired in case connectivity to
the Worklight Server is restored
As application developer, you need to add event listeners for these two events and
specify the callback functions so that your application can react accordingly.
5-58 Mobile Application Development with IBM Worklight V6
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V8.1
Student Notebook
Uempty
You add this event registration process using the JavaScript function
Document.addEventLister(), and pass the Worklight event constants and callback
function name to this registration function. The third parameter, capture, is a boolean
value that specifies whether the event needs to be captured or bubbled. A value of false
indicates that the event is bubbled (a discussion of capture, target, and bubble is
outside of the scope of this course. You can find detailed information on the web).
5-59
Student Notebook
WU5061.1
Notes:
Another useful API Worklight provided is WL.Client.connect.
This call attempts to establish a connection to the Worklight Server and return to online
mode. It takes a Worklight options parameter which contains the following keys:
onSuccess is the Callback function to invoke in case server connection is
established
Likewise, onFailure defines Callback function to invoke in case server
connection fails
Timeout can be used to define Number of milliseconds to wait for the server
response before failing with request timeout
Often, this API is used when application goes back online or returns to device
foreground, where connectivity needs to restored.
V8.1
Student Notebook
Uempty
getNetworkInfo()
WL.Device.getNetworkInfo() method is available for iOS and
Android environments
A callback must be specified as a function parameter
WU5061.1
Notes:
For applications running on iOS and Android devices, you can use the
WL.Device.getNetworkInfo API to fetch network information from the device, and return it
to the specified callback function.
The callback function receives a JSON structure with these properties:
isAirplaneMode: true/false
carrierName: string (for example, AT&T, VERIZON, and so on)
telephonyNetworkType: string (for example, UMTS or GPRS)
isRoaming: true/false
networkConnectionType: mobile/WIFI
ipAddress: string
isNetworkConnected: true/false
5-61
Student Notebook
V8.1
Student Notebook
Uempty
Foreground event
When the Worklight Application returns to foreground, a foreground
JavaScript event is fired
Developers can add a listener to this event and specify the callback
functions to handle it
WU5061.1
Notes:
A mobile application may be frequently put into the background when user works on
another application, ortakes a phone call. When the mobile application comes back to the
foreground, the developer may want to want to add some initialization and sanity check
logic; for example, to ensure that connection is available.
To accomplish this, Worklight fires a foreground event when the application comes back
to foreground. It is easy for application developers to add a listener to this event and
specify the callback functions that can handle it.
This technique is particularly useful for cases in which the user has left the application to
restart connectivity on the device, expecting the application to connect when they return. In
this case, the developer can use the document.addEventListener API to registered the
foreground event as shown in the code snippet in this slide, then attempt to reconnect to
server if it detects that server connectivity is not available.
5-63
Student Notebook
Worklight heartbeat
Worklight heartbeat is designed to periodically ping the server to verify
connectivity
Use the heartbeat to verify that the application remains connected to
the server
You can set a heartbeat interval on application initialization, or at any
point during execution
WU5061.1
Notes:
The heartbeat interval is set by default to 420 seconds (7 minutes). You can specify the
heartbeat interval by using WL.Client.setHeartBeatInterval(intervalSeconds)
A value of -1 disables the heartbeat.
V8.1
Student Notebook
Uempty
5-65
Student Notebook
String translation
8.0
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Introduction to translation
You can use the Worklight framework to enable translation of
applications into other languages
You can set up translations for
Application strings
System messages
WU5061.1
Notes:
Translation is part of the overall Globalization or localization process of computing
systems. Globalization normally refers to the process of designing and developing a mobile
application that functions in multiple cultures and locales. The globalization process
normally includes identifying the culture and locale that must be supported, Designing
features which support them, and writing code that functions equally well in any of the
supported cultures/locales.
Under IBM Worklights globalization system, the main focus is on translating the mobile
application to languages other than English. The specific items or software components
that can be translated are application Strings, and system messages.
Application strings are essentially static UI texts displayed or used in your mobile
application. Examples include the title of a page, menu labels, and so on. System
messages are messages your mobile application uses to communicate information, either
to the end user or among application components themselves. These tend to be low level
messages. Examples include error messages to warn user that network connection has
lost, and so on.
Copyright IBM Corp. 2013
5-67
Student Notebook
V8.1
Student Notebook
Uempty
Enabling translation
The messages.js file, which is designated for application strings,
is in the common/js folder
Application messages stored in messages.js can be referenced
in two ways:
As a JavaScript object property, for example, Messages.sampleText
As an ID of an HTML element
with class=translate
WU5061.1
Notes:
Application String translation is often applied to the UI texts that are either defined in the
HTML file or dynamically generated using JavaScript.
Worklight translation is handled by a designated file under common/js folder named
message.js. It contains a dictionary object for localizing texts. If not specified, the default
object Messages (located in the same file) is used. Remember, you can also customize the
globalization by providing message.js file in your environment or skin folders.
The default message.js contains language a name:value pair dictionary for the default
locale or language.
There are two usage scenarios for applying globalized application strings. One is using
JavaScript to apply predefined messages using a JavaScript object property. For example,
under message.js you have a Messages dictionary defined in which you have a property
defined as header. In the JavaScript code, you can uses the JavaScript objective property
Messages.header to represent the text you want to use or display. Worklight replaces the
string with the message defined in message.js.
5-69
Student Notebook
You can also use message.js declaratively. This is used primarily for static HTML content.
You define an HTML element with class=translate and an element id that can be mapped
in message.js. Worklight uses the HTML element id field to find the matching string
definition in the Message.js file and replace the HTML element content with it. For example,
if you have a HTML div tag with id sampleText and a class attribute translate, the content is
replaced by Worklight if you have a sampleText property under the Messages object
defined in your message.js file. This is illustrated in the screen captures.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
You can also globalize system messages that the application shows, for example Internet
connection not available, or invalid user name or password. These tend to be messages
used by low level application logic often implemented in JavaScript component.
System messages are located under the environment folder, in wlclient/js, under the name
message.js.
To translate a system message, override it in your application JavaScript, normally in a
global level JavaScript component because some parts of the code are executed only after
successful application initialization.
For example, if you want to localize the message which warns users when a
requestTimeOut event occurs, you can overwrite the message
WL.ClientMessage.requestTimeout to a value you specify.
5-71
Student Notebook
WU5061.1
Notes:
To enable multi-language support, you can use JavaScript to override a specific string to
target the language you want to support.
For example, you start with defining a default language translation dictionary in
message.js. Then, override the string in a JavaScript function, as shown here.
You should implement this override in a global level JavaScript component so that it can be
used throughout your application.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
As a common practice, you might want to apply locale detection before applying translation
to your application.
Worklight allows you to do so easily using two APIs:
WL.App.getDeviceLocale() which returns the locale code according to user's device
settings, for example: en_US.
WL.App.getDeviceLanguage() which returns the language of the users device.
5-73
Student Notebook
WU5061.1
Notes:
Example (refer to the previous page):
assume Messages = {header: Default header, actionsLabel: Default action}
The locale is detected as fr. getLang() is called with the String french (it may be simpler
to pass the detected locale identifier, but this is for the demonstration!).
The case that corresponds to the language calls the setFrench() function, which sets
Messages.header = Traduction. The message values are now:
{header: Traduction, actionsLabel: Default action}
Note that actionsLabel has not been changed. The function reset the header value, but any
String that is not reset has its original value.
The example shown on this page has been simplified for clarity. You would need
$("#AppBody").css({direction : ltr'}) as the first line of the function, since if you change to
Hebrew (right to left), then back to French, you would need to change the direction back
also! You also require a setEnglish() function. Although English is the default language in
V8.1
Student Notebook
Uempty
this example, you should provide the possibility of reverting to it if you change, for example,
to French.
5-75
Student Notebook
Checkpoint questions (1 of 2)
1. What is messages.js used for?
A. This file contains the texts of application prompts
B. This file contains the texts of error messages that the application can show
C. An internal framework file, it is used to store system messages for debugging
purposes
D. This file contains strings that can be used for application elements
WU5061.1
Notes:
Write your answers here:
V8.1
Student Notebook
Uempty
Checkpoint questions (2 of 2)
1. A tab bar is an example of
A. A busy indicator
B. A simple dialog
C. An options menu
D. A common control
WU5061.1
Notes:
5-77
Student Notebook
Unit summary
Having completed this unit, you should be able to:
Identify essential Worklight client-side APIs including those that enable
cross-platform portability and localization
Explore the syntax of the JavaScript functions supporting the APIs
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Checkpoint answers
1. D. This file contains strings that can be used for application elements
2. C. WL.Logger.debug
3. D. A common control
4. B. WL.BusyIndicator
WU5061.1
Notes:
5-79
Student Notebook
Exercise 2
8.0
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Exercise objectives
After completing this exercise, you should be able to:
Use Worklight client-side functions to access device environment
information, and use common controls and skins
WU5061.1
Notes:
5-81
Student Notebook
V8.1
Student Notebook
Uempty
References
IBM Worklight V6 documentation:
http://pic.dhe.ibm.com/infocenter/wrklight/v6r0m0/index.jsp
6-1
Student Notebook
Unit objectives
After completing this unit, you should be able to:
Identify the Worklight client-side APIs that support storing data locally on a
device in an encrypted cache or a JSON data store.
Explore the syntax of the JavaScript functions supporting the APIs
WU5061.1
Notes:
6-2
V8.1
Student Notebook
Uempty
Topics
Encrypted cache
JSON data store
WU5061.1
Notes:
6-3
Student Notebook
6-4
V8.1
Student Notebook
Uempty
6-5
Student Notebook
Encrypted cache
8.0
WU5061.1
Notes:
6-6
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
Encrypted cache is a mechanism for storing sensitive data on the client side so that
application can continue operating even without server connection where normally
application data is retrieved from.
Under the cover, Worklight Encrypted cache is implemented using HTML5 local storage
technology which allows data to be saved locally as key-value pair.
Beyond the HTML5 Local Storage, Worklight encrypts the data persisted under the local
storage so that it makes your application more secure. Worklight uses a combination of
user-provided key and server-retrieved randomly generated token to encrypt the data.
Once application creates and opens an encrypted cache, it will remain open until
application closes it. So, one of best practices is to also clean and close your local cache
once you are done working with it.
6-7
Student Notebook
Show all
versions
iOS Safari
3 versions
back
3.2
2 versions
back
Opera Mini
Opera Mobile
Android
browser
4.0-4.1
10.0
2.1
Previous
version
4.2-4.3
11.0
2.2
Current
version
5.0
11.1
2.3-3.0
5.0-6.0
Near future
4.0
Supported=
Not supported=
WU5061.1
Notes:
Worklight encrypted cache support on browsers and mobile devices are driven by the
support for HTML5 Web storage technology.
Majority of the mobile devices are currently supporting HTML5 Web storage technology.
Please reference this chart for device supporting detail.
As a general development best practice, development may want to add web storage
feature detection logic in application JavaScript file before creating and using Encrypted
cache.
Additional information can be obtained at http://caniuse.com
6-8
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
Note that the application must be able to connect to Worklight server in order to create a
new encrypted cache.
Worklight API WL.EncryptedCache.Open: opens an existing cache, or creates a new
cache, that will be encrypted using the provided credentials. This method runs
asynchronously because the key generation process is a lengthy process.
The process of creating a new cache involves obtaining a random number from the
Worklight Server. Hence, the action of creating a new cache requires that the app is
connected to the Worklight Server. Once a cache has been created, it can subsequently be
opened without a connection.
This API take three parameters when creating or opening a local cache:
Credentials, this first parameter is the string value representing user-provided password
The second parameter is a Boolean value specifying whether new encrypted cache should
be created in case none is found
6-9
Student Notebook
Lastly, you can provide call back function to be invoked when cache opening/creating is
complete
In your callback function, check the status of creating or opening an encrypted cache.
Application can get three possible status,
When an encrypted cache is successfully created or opened,
WL.EncryptedCache.OK status code will be returned to your call back function.
Normally, your application logic of storing or retrieving data should happen only when
successful status is detected.
WL.EncryptedCache.ERROR_CREDENTIALS_MISMATCH status will be returned
when an attempt was made to open existing encrypted cache using wrong credentials.
Finally, if the call is used to create a new local cache, worklight needs to contact
worklight server component to get the random security token. If worklight is
unable to generate random token due to Worklight Server unavailability, a
WL.EncryptedCache.ERROR_SECURE_RANDOM_GENERATOR_UNAVAILABLE
status will be returned.
Your application can catch WL.EncryptedCache.ERROR_NO_EOC exception to
handle the case where application could not open encrypted cache because it was not
previously created.
When a particularly device doesnt support HTML5 local storage, an Exception will be
thrown when you try to invoke Worklight open API. Use this in conjunction with the
HTML5 local storage feature detection logic we mentioned before can prevent
unexpected behavior when using Worklight Encrypted Cache.
Finally, if current application already issued to open or changeCredential call and still
waiting those procedure to complete, another attempt to open the same local cache will
results in an Exception being thrown by Worklight , this Exception is
WL.EncryptedCache.ERROR_KEY_CREATION_IN_PROGRESS
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
6-11
Student Notebook
WU5061.1
Notes:
The sample code here shows how to evaluate the Cache open or create status.
V8.1
Student Notebook
Uempty
10
WU5061.1
Notes:
6-13
Student Notebook
To remove data from the encrypted cache use the following API:
WL.EncryptedCache.remove(key, onSuccess, onFailure);
11
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
12
WU5061.1
Notes:
6-15
Student Notebook
13
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
14
WU5061.1
Notes:
6-17
Student Notebook
V8.1
Student Notebook
Uempty
6.2. JSONStore
6-19
Student Notebook
JSONStore
8.0
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
What is JSONStore?
JSONStore is a JavaScript API for data storage and manipulation, based on
JavaScript Object Notation (JSON)
Similar to local storage or DOM storage, but with some advantages
It provides the following key features:
Storage of new and existing data that you can search, update, and delete without
network connectivity
Ability to pull and push data to your back-end system
Encryption for stored data
Tooling for you to get started
WU5061.1
Notes:
You can write an application that maintains a local copy of its data and, on request, pushes
the local updates to a back-end service.
The local copy is a JSON data store. IBM Worklight supplies an API for working with a
JSON Store through the methods of the JavaScript class WL.JSONStore.
Using the JSONStore API, you can extend the existing adapter connectivity model to store
data locally and push changes from the client to a server. You can search the local data
store and update and delete data within it. You can secure the local data store by using
password-based encryption.
6-21
Student Notebook
WU5061.1
Notes:
(1): These features are further described in the module JSONStore Common
JSONStore usage.
(2): Reliable Storage means that your data is not deleted unless the application is removed
from the device or one of the
methods that removes data is called.
(3): Dev. Only means that it is designed only for development. There are no security
features and a ~5 MB storage space
limit.
If you are developing Worklight hybrid apps that target iOS and Android, consider working
with JSONStore instead of Encrypted. CacheThe key reason for this statement is Apples
position that HTML5 local storage is not guaranteed to be persistent on future iOS
versions. JSONStore uses the same encryption form and security mechanisms (PBKDF2
for key derivation from user password and AES 256) as current Encrypted Cache. For
V8.1
Student Notebook
Uempty
more information, search the IBM Worklight Information Center for the class
WL.JSONStore http://pic.dhe.ibm.com/infocenter/wrklight/v6r0m0/index.jsp
6-23
Student Notebook
WU5061.1
Notes:
JSONStore is not a relational database, but this unit uses relational database terminology
to explain some basic concepts. For example, the way data is structured through schemas
when using a relational database differs to the JSONStore approach, where you can store
any JSON content, and index what you need to search on.
Document: A JavaScript object that has an _id key that holds an integer and a json key that
holds a JavaScript object. Document is an internal structure we generate when you add or
store data, _id should not be modified. It is similar to a record or to a row in database
terminology.
V8.1
Student Notebook
Uempty
Example:
var doc = {
_id: 1,
json: {
name: 'carlos',
age: 99
}
};
You can also have an array of documents. Example:
var doc = [{_id : 0, json : {fn : 'carlos', age : 99, active : false}}];
6-25
Student Notebook
Internal storage
Customer collection
Document:
{_id: 1, json:
{name: carlos,
age: 99}}
Document:
{_id: 2, json:
{name: 'tim',
age: 100}}
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Additional search fields are keys that are indexed, but are not part of the
JSON data that is stored
These fields define the key whose values (in a given JSON collection) are
indexed, and therefore used to search faster
These fields can be of the following data types: string, boolean, number and
integer
These types determine how indexable fields are stored
For example: defining {age: 'number'} indexes 1 as 1.0, while defining{age:
'integer'} indexes 1 as 1.
Examples:
var searchField = {name: 'string', age: 'integer'};
var additionalSearchField = {key: 'string'};
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
searchFields: defines the keys in JavaScript objects that are indexed, thus determining
what you can query in a collection. The keys in the searchFields object must correspond to
paths in the stored JSON object. Search field keys will be applied to the JSON objects in a
style similar to object['keyPart1]['keyPart2']. When a searchField is located in the
JavaScript object, it will only be indexed if the value is a simple type (integer, number,
boolean, or string). The values for search fields are type hints and must be one of 'string',
'integer', 'number', or 'boolean'. The type declared in the searchField does not have to
match the type of the item matched at runtime, but the better the match the better the
optimization that can be done.
In the example below, the fields fn, age, gpa and active will only match keys found at the
top level of the JavaScript object: var myObj = { age: 42 }, and would not match var myObj2
= { person : {age : 18 } }, the search field would have to be person.age to match this case.
Example:
var searchfields = { fn : 'string',
age : 'integer',
Copyright IBM Corp. 2013
6-27
Student Notebook
V8.1
Student Notebook
Uempty
Customer collection
carlos
Document:
{_id: 1, json:
{name: carlos}}
tina
Document:
{_id: 1, json:
{name: tina}}
WU5061.1
Notes:
Queries are JavaScript objects that use search fields or additional
search fields to look for documents.
?? The following example presumes that name and age are search
fields, of types string and integer respectively.
?? Examples:
Find documents with name that matches carlos:
var query1 = {name: 'carlos'};
Find documents with name that matches carlos and age that
matches 99:
var query2 = {name: 'carlos', age: 99};
6-29
Student Notebook
Store internals
Example: the people table
When you search the people table with one or a combination of the
following queries, the retrieved document is {_id: 1, json: {name:
'carlos', age: 99} } :
{_id : 1}
{name: 'carlos'}
{age: 99}
{key: 'c'}
WU5061.1
Notes:
In this example, the key elements are:
_id is the unique identifier (example: AUTO INCREMENT
PRIMARY KEY).
json contains an exact representation of the stored JSON object.
name and age are search fields.
key is an additional search field.
people is the collection name.
V8.1
Student Notebook
Uempty
Error object
The Error object is a JavaScript object that is returned when a JSONStore operation
(such as find or add) fails.
The Error object provides information about the cause of the failure.
Example:
var errorObject = {
src: 'find', //operation that failed
err: -50, //error code
msg: 'PERSISTENT_STORE_FAILURE', //error message
col: 'people', //collection name
usr: 'jsonstore', //username
doc: {_id: 1, {name: 'carlos', age: 99}}, //document that
the failure relates to
res: {...} //response from the server
}
Not all the key-value pairs are part of all Error objects
For example, the response from the server is available only when operations that use
the network fail, such as push
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
6-31
Student Notebook
JSONStore architecture
1. JSONStore requests data from a Worklight adapter
2. The adapter requests data from the enterprise service
3. The enterprise service returns data
4. The adapter returns data in JSON format
5. Data is stored on the device
Enterprise systems
Worklight
Web layer
2
Adapter
JSONStore
JavaScript API
5
REST, SOAP, SQL or
Cast Iron
Internal
storage
Native layer
WU5061.1
Notes:
The JSONStore can be used to create a collection either from an adapter or otherwise.
When tied to an adapter, the API supports a convention of tying the various sync
operations (pushing to server) based on the action the user can perform on the local
collection in the JSONStore.
V8.1
Student Notebook
Uempty
Enterprise systems
Worklight
Web layer
Adapter
JSONStore
JavaScript API
1
REST, SOAP, SQL or
Cast Iron
Internal
storage
Native layer
WU5061.1
Notes:
6-33
Student Notebook
JSONStore API
API is only in JavaScript, and mostly asynchronous
You can use it only when you develop Worklight hybrid applications, and you
must wait for callbacks to get results
var
var
var
var
var
var
win
win == function
function (data)
(data) {{ };
};
fail
fail == function
function (data)
(data) {{ };
};
options
=
{onSuccess:
win,
options = {onSuccess: win, onFailure:
onFailure: fail};
fail};
WU5061.1
Notes:
options: a JavaScript object that contains the failure and success callback functions.
Additional parameters may be accepted and will be documented in their respective
methods. These success and failure callbacks are specific to the function you're calling, for
example the onSuccess function passed to initCollection will only be called when
initCollection is successful.
V8.1
Student Notebook
Uempty
Initialization
Use init to start one or more JSONStore collections
Starting or provisioning a collection means creating the persistent storage that
contains collections and documents, if it does not exist
Example:
var
var collectionName
collectionName == 'people';
'people';
The sample app has a button
to initialize a collection.
//Object
//Object that
that defines
defines all
all the
the collections
collections
var
var collections
collections == {};
{};
//Object
//Object that
that defines
defines the
the 'people'
'people' collection
collection
collections[collectionName]
collections[collectionName] == {};
{};
//Object
//Object that
that defines
defines the
the Search
Search Fields
Fields for
for the
the 'people'
'people' collection
collection
collections[collectionName].searchFields
collections[collectionName].searchFields == {name:
{name: 'string',
'string', age:
age: 'integer'}
'integer'}
WL.JSONStore.init(collections)
WL.JSONStore.init(collections)
.then(function
.then(function ()
() {{
//handle
//handle success
success
})
})
.fail(function
.fail(function (errorObject)
(errorObject) {{
//handle
//handle failure
failure
});
});
WU5061.1
Notes:
Creates a new object to interact with a single collection. If local storage for the collection
does not exist, it is provisioned with the searchFields. Otherwise, the searchFields is
validated against the searchFields used to originally provision the collection.
Use init to start one or more JSONStore collections.
?? Starting or provisioning a collection means creating the persistent
storage that contains collections and documents, if it does not exist.
?? If the persistent storage is encrypted and a correct password is
passed, the necessary security procedures to make the data
accessible are run.
?? For optional features that you can enable at initialization time, see
Security, Multiple user support, and Worklight adapter
integration, in the second part of this module.
Copyright IBM Corp. 2013
6-35
Student Notebook
V8.1
Student Notebook
Uempty
Get
Use get to create an accessor to the collection
You must call init before you call get, otherwise the result of get is undefined
Example:
var collectionName = 'people';
var people = WL.JSONStore.get(collectionName);
The variable people can now be used to perform operations on the people
collection such as:
add
find
replace
WU5061.1
Notes:
6-37
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Add
Use add to store data as documents inside a collection
Example:
var
var
var
var
var
var
data
data == {name:
{name: 'carlos',
'carlos', age:
age: 99};
99};
collectionName
collectionName == 'people';
'people';
options
options == {};
{}; //default
//default
WL.JSONStore.get(collectionName)
WL.JSONStore.get(collectionName)
.add(data,
.add(data, options)
options)
.then(function
.then(function ()
() {{
//handle
//handle success
success
})
})
.fail(function
.fail(function (errorObject)
(errorObject) {{
//handle
//handle failure
failure
});
});
WU5061.1
Notes:
6-39
Student Notebook
Find
Use find to locate a document inside a collection by using a query.
Use findAll to retrieve all the documents inside the collection.
Use findById to search by the document unique identifier.
The default behavior for find is to do a fuzzy search
var
var query
query == {name:
{name: 'carlos'};
'carlos'};
var
var collectionName
collectionName == 'people';
'people';
var
options
=
{
var options = {
exact:
exact: false,
false, //default
//default
limit:
limit: 10
10 //returns
//returns aa maximum
maximum of
of 10
10 documents,
documents, default:
default: return
return every
every match
match
};
};
WL.JSONStore.get(collectionName)
WL.JSONStore.get(collectionName)
.find(query,
.find(query, options)
options)
.then(function
.then(function (arrayResults)
(arrayResults) {{
//arrayResults
//arrayResults == [{_id:
[{_id: 1,
1, json:
json: {name:
{name: 'carlos',
'carlos', age:
age: 99}}]
99}}]
})
})
.fail(function
.fail(function (errorObject)
(errorObject) {{
//handle
//handle failure
failure
});
});
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
6-41
Student Notebook
Replace
Use replace to modify documents inside a collection.
The field that you use to perform the replacement is _id, the document unique
identifier.
var
var document
document == {_id:
{_id: 1,
1, json:
json: {name:
{name:
'carlitos',
'carlitos', age:
age: 99}};
99}};
var
var collectionName
collectionName == 'people';
'people';
var
var options
options == {};
{}; //default
//default
WL.JSONStore.get(collectionName)
WL.JSONStore.get(collectionName)
.replace(document,
.replace(document, options)
options)
The sample app has a button
to data in a collection.
.then(function
.then(function ()
() {{
//handle
//handle success
success
})
})
.fail(function
.fail(function (errorObject)
(errorObject) {{
//handle
//handle failure
failure
});
});
WU5061.1
Notes:
This example assumes that the document
{_id: 1, json: {name: 'carlos',
age: 99}} is in the collection, and shows
how to replace it with one where the name is
'carlitos'.
V8.1
Student Notebook
Uempty
Remove
Use remove to delete a document from a collection
Documents are not erased from the collection until you call push
var
var query
query == {_id:
{_id: 1};
1};
var
var collectionName
collectionName == 'people';
'people';
var
options
=
{exact:
var options = {exact: true};
true}; //default:
//default:
false
false
WL.JSONStore.get(collectionName)
WL.JSONStore.get(collectionName)
.remove(query,
.remove(query, options)
options)
.then(function
.then(function ()
() {{
//handle
//handle success
success
})
})
.fail(function
.fail(function (errorObject)
(errorObject) {{
//handle
failure
//handle failure
});
});
WU5061.1
Notes:
6-43
Student Notebook
Remove collection
Use removeCollection to delete all the documents that are stored inside a
collection
This operation is similar to dropping a table in database terms
var
var collectionName
collectionName == 'people';
'people';
WL.JSONStore.get(collectionName)
WL.JSONStore.get(collectionName)
.removeCollection()
.removeCollection()
.then(function
.then(function ()
() {{
//handle
success
//handle success
})
})
.fail(function
.fail(function (errorObject)
(errorObject) {{
//handle
//handle failure
failure
});
});
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Destroy
Use destroy to remove all documents, collections, stores, and JSONStore
metadata and security artifacts
var
var collectionName
collectionName == 'people';
'people';
WL.JSONStore.destroy()
WL.JSONStore.destroy()
.then(function
.then(function ()
() {{
//handle
//handle success
success
})
})
.fail(function
.fail(function (errorObject)
(errorObject) {{
//handle
//handle failure
failure
});
});
WU5061.1
Notes:
6-45
Student Notebook
The store is encrypted with a 256-bit Advanced Encryption Standard (AES) key
Use closeAll to lock access to all the collections until you call init again.
If you think of init as a login function, you can think of closeAll as the
corresponding logout function.
WU5061.1
Notes:
All keys are strengthened with Password-Based Key Derivation Function 2 (PBKDF2).
V8.1
Student Notebook
Uempty
var
var options
options == {{
password:
password: '123'
'123'
};
};
WL.JSONStore.init(collections,
WL.JSONStore.init(collections, options)
options)
.then(function
.then(function ()
() {{
//handle
//handle success
success
})
})
.fail(function
.fail(function (errorObject)
(errorObject) {{
//handle
//handle failure
failure
});
});
WU5061.1
Notes:
6-47
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
.then(function
.then(function ()
() {{
//handle
//handle success
success
})
})
.fail(function
.fail(function (errorObject)
(errorObject) {{
//handle
//handle failure
failure
});
});
WU5061.1
Notes:
6-49
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
from
from
from
from
from
from
JSONStore
JSONStore to
to REMOVE:
REMOVE: '' ++ data);
data);
}}
WU5061.1
Notes:
First, create a Worklight adapter, and define its procedures to get, add, replace, and
remove data (such as getPeople, addPerson, replacePerson, and removePerson).
Next, implement these procedures:
The following example only returns hard-coded data and logs for simplicity.
For more information about how to create a Worklight adapter, see the modules under
category 4, Worklight server-side development, in the IBM Worklight Information Center, at
http://pic.dhe.ibm.com/infocenter/wrklight/v6r0m0/
topic/com.ibm.worklight.help.doc/start/c_gettingstarted.html.
6-51
Student Notebook
var
var collections
collections == {{
people:
people: {{
searchFields:
searchFields: {{
name:
name: 'string',
'string',
age:
age: 'integer'},
'integer'},
//Initialize
//Initialize
WL.JSONStore.init(collections)
WL.JSONStore.init(collections)
//-//-- Start
Start adapter
adapter metadata
metadata
adapter
adapter :: {{
.then(function
.then(function ()
() {{
//handle
//handle success
success
name:
name: 'people',
'people',
add:
add: 'addPerson',
'addPerson',
})
})
remove:
remove: 'removePerson',
'removePerson',
replace:
replace: 'replacePerson',
'replacePerson',
load:
load: {{
.fail(function
.fail(function (errorObject)
(errorObject) {{
//handle
//handle failure
failure
});
});
procedure:
procedure: 'getPeople',
'getPeople',
params:
params: [],
[],
key:
key: 'peopleList'
'peopleList'
}}
}}
//-//-- End
End adapter
adapter metadata
metadata
}}
};
};
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
Start the people collection by calling init and passing adapter
metadata (adapter name, procedure names).
?? In the example, the key is peopleList because the goal is to
store {name: 'carlos', age: 100} and {name: 'tim',
age: 99} as two separate documents.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
6-53
Student Notebook
WU5061.1
Notes:
push: pushes the collection with an Adapter. For every document marked requiring push,
call the corresponding Adapter procedure linked to the collection. The Documents will be
processed on the client by order of their last modification date. To check the number of
records to push, see WL.JSONStore.getPushRequired.
Example
collection.push(options);
pushSelected: pushes only the selected Documents. See WL.JSONStore.push. The
document passed will not be sent to the Adapter (pushed) if it is not marked unpushed.
Example
var doc = {_id : 0, json: {fn : 'carlos', age : 99, active : false}}; collection.pushSelected(doc,
options); collection.pushSelected([doc], options);
load: gets data defined in load portion of the adapter.
Example
6-54 Mobile Application Development with IBM Worklight V6
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V8.1
Student Notebook
Uempty
customers.load(options)
6-55
Student Notebook
Example: getPushRequired
Calling getPushRequired returns an array of dirty documents, which are
documents that have local modifications that do not exist on the enterprise
system
These documents are sent to the Worklight adapter when push is called
To stop JSONStore from marking the documents as dirty, pass the option
{push:false} to add, replace, and remove
WL.JSONStore.get('people').getPushRequired
WL.JSONStore.get('people').getPushRequired
()
()
.then(function
.then(function ()
() {{
//handle
//handle success
success
})
})
.fail(function
.fail(function (errorObject)
(errorObject) {{
//handle
failure
//handle failure
});
});
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Example: push
push sends the document that changed to the correct Worklight adapter
procedure (for example, addPerson is called with a document that was added
locally)
This mechanism is based on the last operation that is associated with the
document that changed and the adapter metadata that is passed to init
WL.JSONStore.get('people').push()
WL.JSONStore.get('people').push()
.then(function
.then(function (res)
(res) {{
//handle
//handle success
success
//res
//res is
is an
an empty
empty array
array if
if all
all documents
documents
reached
reached the
the server
server
//res
//res is
is an
an array
array of
of error
error responses
responses if
if some
some
documents
documents failed
failed
to
to reach
reach the
the server
server
})
})
.fail(function
.fail(function (errorObject)
(errorObject) {{
//handle
//handle failure
failure
});
});
WU5061.1
Notes:
6-57
Student Notebook
Example: enhance
Use enhance to extend the core API to fit your needs, by adding functions to a collection prototype
The example shows how use enhance to add the function getValue that works on the keyvalue
collection
It takes a key (string) as its only parameter and returns a single result
//Definition:
var collectionName = 'keyvalue';
WL.JSONStore.get(collectionName).enhance(
'getValue', function (key) {
var deferred = $.Deferred(),
collection = this;
//Do an exact search for the key
collection.find({key: key}, {exact:
true, limit: 1})
.then(deferred.resolve,
deferred.reject);
return deferred.promise();
//Usage:
var key = 'myKey';
WL.JSONStore.get(collectionName).getValue
(key)
.then(function (res) {
//res contains an array of documents
//with the results from the find
))
.fail(function () {
//handle failure
});
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Unit summary
Having completed this unit, you should be able to:
Identify the Worklight client-side APIs that support storing data locally on a
device in an encrypted cache or a JSON data store.
Explore the syntax of the JavaScript functions supporting the APIs
WU5061.1
Notes:
6-59
Student Notebook
Checkpoint questions
1. Which of the following sentences correctly describes the encrypted cache?
A. Encrypted cache is stored in the device native storage. Its size is limited by the
free space on a device, therefore large amounts of data can be stored.
B. HTML5 WebStorage is used for storing encrypted cache; therefore the amount of
data stored in it is limited to several megabytes
C. Encrypted cache is stored on Worklight server. Its size is limited by the free
space in the Worklight Server database, therefore large amounts of data can be
stored
D. Encrypted cache is stored in virtual memory. Its size is limited by the device
RAM and it is erased each time the user quits the application.
2. Which of the following APIs is synchronous and does not require callbacks to
be set up?
A. WL.EncryptedCache.open
B. WL.EncryptedCache.read
C. WL.EncryptedCache.destroy
D. All encrypted cache APIs are asynchronous and require setting up callbacks for
success and failure
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
Write your answers here:
V8.1
Student Notebook
Uempty
Checkpoint answers
1. B. HTML5 WebStorage is used for storing encrypted cache; therefore the
amount of data stored in it is limited to several megabytes
2. D. All encrypted cache APIs are asynchronous and require setting up
callbacks for success and failure
WU5061.1
Notes:
6-61
Student Notebook
Checkpoint questions
1. Why would you consider using JSONStore instead of encrypted cache?
A. You need special encryption that is only available with JSONStore
B. If you are developing Worklight hybrid apps that target iOS and Android
C. You need to use HTML5 local storage
WU5061.1
Notes:
Write your answers here:
V8.1
Student Notebook
Uempty
Checkpoint answers
1. B. If you are developing Worklight hybrid apps that target iOS and Android
WU5061.1
Notes:
6-63
Student Notebook
Exercise 3
8.0
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Exercise objectives
After completing this exercise, you should be able to:
Use an encrypted cache and the JSON data store in a mobile application
WU5061.1
Notes:
6-65
Student Notebook
V8.1
Student Notebook
Uempty
References
IBM Worklight V6 documentation:
http://pic.dhe.ibm.com/infocenter/wrklight/v6r0m0/index.jsp
7-1
Student Notebook
Unit objectives
After completing this unit, you should be able to:
Include the jQuery Mobile, Sencha Touch or Dojo Mobile UI
frameworks in a Worklight mobile application
WU5061.1
Notes:
7-2
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
HTML Document Object Model (DOM) Provides a standard, cross-platform manner
through which HTML documents can be accessed and traversed
Developers need frameworks and toolkits that provide value beyond core JavaScript APIs.
There are many reasons for this:
- JavaScript APIs, especially DOM-related APIs, behave differently across different
browsers. A unifying, consistent API improves application portability and developer
productivity
- Common activities like drag-and-drop and animation effects are not supported in the core
JS API. Thus, developers have to implement their own approach using the core JavaScript
API even though these problems have been solved many times. Toolkits like Dojo radically
simplify these common needs via APIs and configuration
- HTML and JavaScript do not provide a set of pre-built UI components with data
integration. Even though there are common needs for web and mobile applications, such
7-3
Student Notebook
as tabbed views, content panes, tree views, etc., HTML and JS do not do anything to make
constructing those UI views easier.
7-4
V8.1
Student Notebook
Uempty
Topics
Working with UI frameworks
Using jQuery Mobile
Using jQuery to build a multi-page application
Sencha Touch
Dojo Mobile
WU5061.1
Notes:
Designing and implementing the UI of your application is a vital part of the development
process. Writing your own CSS style for each component from scratch allows a very high
level of customization, but can use a large amount of resources. Sometimes it is better to
use existing JavaScript UI frameworks. This unit describes the development of Worklight
applications using different JavaScript UI frameworks: jQuery Mobile, Sencha Touch, and
Dojo Mobile.
7-5
Student Notebook
7-6
V8.1
Student Notebook
Uempty
7-7
Student Notebook
Working with UI
frameworks
8.0
WU5061.1
Notes:
7-8
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
7-9
Student Notebook
V8.1
Student Notebook
Uempty
7-11
Student Notebook
8.0
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
jQuery Mobile
jQuery Mobile is a touch-optimized web framework for smart phones
and tablets
Simplifies HTML document traversing, event handling, animating, and
Ajax interactions for rapid web development
You can create mobile application screens in a few lines of code
For more information and documentation, see
http://jquerymobile.com/demos
WU5061.1
Notes:
jQuery mobile is built on top of jQuery JavaScript framework. When using jQuery mobile,
you must include jQuery.js core library in your project.
Worklight client-side framework itself uses the jQuery 1.8 library for internal functions. By
default, the $ char is assigned to the internal jQuery in the application main JavaScript file.
This is reflected in the JavaScript file. For example, the application main JavaScript is
generated from the Worklight Studio application creation wizard.
This means that you do not have to separately include the jQuery.js library. If your
application does not require jQuery, you can remove or comment out this line.
7-13
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Add the jQuery Mobile components to your application and reference them in the main
HTML file in order as follows:
1. Add jQuery Mobiles CSS file before any other CSS and JavaScript files
2. Add the jQuery Mobile framework
WU5061.1
Notes:
You can download the jQuery mobile minified CSS file, and then copy the file
jquery.mobile.min.css into the application under the common/css folder.
In your application, in the main HTML file, define the jQuery mobile CSS file before any
other CSS and JavaScript file so that its style does not override or interfere with your
application styling.
7-15
Student Notebook
You can create your own styles and themes using ThemeRoller tool at
http://jquerymobile.com/themeroller/
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
7-17
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
7-19
Student Notebook
Sencha Touch
8.0
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
7-21
Student Notebook
WU5061.1
Notes:
Place the sench-touch.css file under your Worklight application common/css folder, and
place sencha-touch.js file under the application common/js folder.
In the application main HTML file, include both files, as shown in the picture.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
7-23
Student Notebook
V8.1
Student Notebook
Uempty
7-25
Student Notebook
Dojo Mobile
8.0
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
What is Dojo?
You can use Dojo Mobile to rapidly develop mobile web applications on
iPhone, iPod Touch, iPad, Android, and BlackBerry touch devices, with
the appearance of the native device
Dojo Mobile is part of the Dojo Toolkit, which is developed and
maintained by the Dojo Foundation
For more information about the Dojo Toolkit, go to the Dojo Toolkit
website at http://dojotoolkit.org/documentation/
Worklight Studio includes a Dojo Toolkit package and tools that you
can use to develop your mobile web applications
WU5061.1
Notes:
Dojo is a toolkit used to create modern web and mobile applications.
Started back in 2004. Eight major releases since its inception and over 1 million downloads
of the toolkit.
IBM uses Dojo extensively internally, contributes to the toolkit and even co-leads some
areas (such as Dojo Mobile).
More information along with tutorials, API documentation, and reference material can be
found here: http://dojotoolkit.org/
Dojo Base and Dojo Core are the foundational elements of the toolkit. Dijit builds on a layer
of widgets and DojoX is a series of sub-projects built on Dojo Base/Core that are
considered experimental in nature. These sub-projects vary in their degree of maturity from
very new to mature and robust.
7-27
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
7-29
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
7-31
Student Notebook
Unit summary
Having completed this unit, you should be able to:
Include the jQuery Mobile, Sencha Touch or Dojo Mobile UI
frameworks in a Worklight mobile application
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
Write your answers here:
7-33
Student Notebook
Checkpoint answers
1. A. $
2. B. Only two files: sencha-touch.js and sencha-touch.css
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
References
IBM Worklight V6 documentation:
http://pic.dhe.ibm.com/infocenter/wrklight/v6r0m0/index.jsp
8-1
Student Notebook
Unit objectives
After completing this unit, you should be able to:
Use the Apache Cordova framework to access native device functions
Develop an Apache Cordova plug-in
Develop a WebViewOverlay plug-in to integrate server generated
pages in an application
WU5061.1
Notes:
This unit explains the capabilities of the Apache Cordova framework and describes the
APIs that support them. It also shows how to create a plug-in and how to use the
WebViewOverlay plug-in to integrate server generated pages in an application.
8-2
V8.1
Student Notebook
Uempty
Topics
Apache Cordova overview
Creating a plug-in
WebViewOverlay plug-in
WU5061.1
Notes:
8-3
Student Notebook
8-4
V8.1
Student Notebook
Uempty
8-5
Student Notebook
Apache Cordova
overview
WU5061.1
Notes:
8-6
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
Apache Cordova is developed by Nitobi Software. It was previously known as PhoneGap.
Cordova has been accepted into the Apache Software Foundation for incubation as
Apache Cordova, where it remains free and open source.
The Cordova framework is designed to bridge the gap between web based mobile
applications and pure native applications by allowing access device native features or
APIs, such as the camera and compass, in a platform independent way.
Using Apache Cordova, you can develop mobile applications using JavaScript, HTML5 and
CSS3, instead of using lower-level platform specific languages such as Objective-C to
access native features. This hybrid application approach renders the UI via a webview
instead of the native platforms specific UI framework, and enables access to part of the
devices APIs.
The Cordova framework is integrated into Worklight generated iOS and Android projects.
8-7
Student Notebook
WU5061.1
Notes:
The Apache Cordova framework is tightly integrated into Worklight. When you build an
application, the main HTML file in its generated project automatically includes the
cordova.js framework. This allows you to invoke the Cordova APIs directly without having
to worry about loading the framework.
8-8
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
Apache Cordova is comprised of two components:
A Cordova JavaScript API which exposes native functionality to the JavaScript code
running in the browser
Platform-specific native code which is invoked by the Cordova JavaScript API
Worklight Studio automatically includes all of the Cordova framework library files in the
generated Android and iOS projects, including:
Cordova web components defined in the cordova.js file that provide JavaScript APIs
Environment specific native libraries
For Android, the libraries are provided in cordova.jar in the generated Android project,
while for iOS, they are included in the Cordova.framework sub-folder of the native folder.
8-9
Student Notebook
WU5061.1
Notes:
Lifecycle events are fired when something happens to the application, such as being put in
the background or when a button is pressed. You attach an event listener for whichever
event you are interested in, for example:
document.addEventListener(pause", yourCallbackFunction, false);
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
This slide provides an example of the code used to display a native alert on an iOS and
Android device using the Cordova notification API.
The displayed alert is a native implementation, not a JavaScript web based alert. There are
four parameters:
message: The message that is displayed. String, required.
alertCallback: The callback function to invoke when the button is pressed. Function,
required, but can be null if there is no callback function.
title: The title shown at the top of the dialog. String, optional. If no title is given, it
defaults to "Alert, as in the slide.
buttonName: The value to display on the button. String, optional. If no value is given, it
defaults to "OK, as in the slide.
8-11
Student Notebook
10
WU5061.1
Notes:
Here is another example of using the Cordova API to get the devices hardware and
software information.
In this case, you use the device object to get the value of different device properties:
device.name: Returns the device's model name
device.cordova: Returns the version of Cordova running on the device
device.platform: Returns the device's operating system name
device.uuid: Returns the device's Universally Unique Identifier (UUID)
device.version: Returns the version number of the operating system
V8.1
Student Notebook
Uempty
8-13
Student Notebook
Creating a plug-in
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
12
WU5061.1
Notes:
Cordova's standard API makes the most commonly used device functions available to
JavaScript code. Occasionally, however, you might not find an available API that supports
a device function that you need to use. In such a case, you have to write native code to
implement it, and invoke this code via JavaScript. This is supported by the Cordova Plugin
technology.
In fact, since PhoneGap 1.0, all of the core Cordova APIs such as for the Camera and
Contacts functions are implemented as Cordova plugins. Plugins have become a
fundamental programming model in the Cordova framework.
Limitation:
Note that, as a best practice, tasks that involve complex business logic, intensive
background processing or heavyweight data processing should not be implemented in
JavaScript, as it may significantly slow down your application. These are not good
candidates for Cordova plugin implementation (for example: Communicating with a
Dropbox client, which requires continues background listening for possible file changes).
8-15
Student Notebook
V8.1
Student Notebook
Uempty
The plugin calls the native code and returns a callback invocation
using cordova.exec()
cordova.exec();
or
callback
Native code
13
WU5061.1
Notes:
A Cordova plugin has two components: Native code and JavaScript wrapper.
The native code component is platform specific. For Android, it is written in Java, while for
iOS, it is written in Objective-C. The native code is developed to implement the desired
platform specific native function or provide a native library implementation for it.
The JavaScript wrapper wraps the native code so that it can be invoked in your application
as a JavaScript functions.
The next topics show how to create a Cordova plugin native class for Android and iOS, and
how to create a plugin JavaScript wrapper.
8-17
Student Notebook
V8.1
Student Notebook
Uempty
8-19
Student Notebook
Creating a native
plugin class for
Android
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
15
WU5061.1
Notes:
To create an Apache Cordova plugin for Android:
1. Create a Java class that natively implements the plugins function. It should extend
org.apache.cordova.api.CordovaPlugin and implement its execute() method. Make sure
you organize imports in Worklight Studio to bring in all of the Cordova framework class
dependencies.
2. Define the plugin in the Cordova Android plugin definition file located in
res/xml/plugins.xml. Add an entry with the name of the plugin and the name of the class
that implements it.
8-21
Student Notebook
16
WU5061.1
Notes:
Implement the execute() method of the plugin class. It is called by the Cordova plugin
framework on a new thread when a plugin action is invoked by the web caller.
This code is placed in android > native > src > package > plugin class.
The JavaScript wrapper calls the execute() method, passing it an action string and action
parameters.
In the code example above, if any other action but sayHello is invoked, the return is false,
which means that the action was not recognized. If the action is sayHello, the data is
retrieved from the input argument array and passed back to the JavaScript calling function.
If the data cannot be retrieved, and error message is passed back.
V8.1
Student Notebook
Uempty
8-23
Student Notebook
Creating a native
plugin class for iOS
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
18
WU5061.1
Notes:
To implement the plugins native class, create an Objective-C class that extends
CDVPlugin. Make sure to import the header file, CDVPlugin.h, which contains all of the
Cordova plugin APIs.
Then, add a property for a callbackId and the actual method or functionality that you want
to expose to the web component (action method).
8-25
Student Notebook
19
Figure 8-18. Plugin class method: Input parameters
WU5061.1
Notes:
The argument command is the equivalent of the Android JSONArray argument for the
execute() method. You can reference an element by position, or by name. The variable
called responseString is given the value of the command object at position 0.
The variable called pluginResult is then populated with a status value, indicating whether
the invocation succeeded, and the name of the function for the callback, taken from the
command argument.
Finally, pluginResult is returned to the calling JavaScript function.
V8.1
Student Notebook
Uempty
8-27
Student Notebook
Creating a plugin
JavaScript wrapper
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
21
WU5061.1
Notes:
DOM = Document Object Model
After you have developed the native code for the plugin, you need to create a JavaScript
wrapper for it so that it can be exposed to a web caller and declare the plugin in the DOM
object.
In this example, the empty function serves as a wrapper for the plug-in.
A sayHello function is created in the HelloWorldPlugin prototype and is provided with the
names of the functions to call on success or on failure, together with any parameters that
need to be sent to the plug-in. The single line of code in the function is a call to the exec()
method on cordova. This call takes five arguments: the two callback function names, the
name of the plug-in, the name of the action on the plug-in, and an array that holds the
parameters.
The addConstructor() function is invoked to add the new plug-in to the plugins object of the
DOM. The condition checks whether there is a plugins object. If not, it creates one. It then
associates the name helloWorldPlugin with your new plugin object.
Copyright IBM Corp. 2013
8-29
Student Notebook
You can now invoke the plug-in. The code is show on the next slide.
V8.1
Student Notebook
Uempty
22
WU5061.1
Notes:
In the example above, the plugin client invokes the sayHello action of the
HelloWorldPlugin in the greetMe() function. It passes a sayHelloSuccess() and
sayHelloFailure() method as a success and failure callback method, respectively. It also
passes the string John Smith (hard-coded on the html page) as a parameter for the plugin
action.
The success callback and failure callback functions are shown. For the demonstration,
they simply pop up an alert.
The plugin name is the one declared in config.xml.
The arguments are passed as an array. In this case, there is only one argument, but there
can be as many as required. This is picked up as the second input argument for the plugin
execute() method.
8-31
Student Notebook
23
WU5061.1
Notes:
The screen shots above show the execution of the HelloWorldPlugin code example on an
Android emulator.
The string John Smith passed from the JavaScript code is passed to the native code, and
the native code simply passes back the string Hello World, John Smith which is displayed
in an alert by the success callback function.
V8.1
Student Notebook
Uempty
8-33
Student Notebook
WebViewOverlay
plugin
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
25
WU5061.1
Notes:
8-35
Student Notebook
26
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
This Page is
implemented in HTML
and bundled with the
mobile application
27
WU5061.1
Notes:
8-37
Student Notebook
28
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
29
WU5061.1
Notes:
Use static references for the sake of simplicity.
The variable thisApp is created here as a reference to this WebViewOverlayApp object. It is
not used here though, but in the plugin. You see this further on.
8-39
Student Notebook
30
WU5061.1
Notes:
The WebViewOverlay is initially invisible. It is set to visible at the moment an action is
invoked that requires the page to be seen. The code for this is shown further on in this unit.
The setMargins() method is used to control the positioning of the webViewOverlay
component. The method here includes a top margin of 65 pixels in order to leave the
buttons visible.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
8-41
Student Notebook
32
WU5061.1
Notes:
This code is a part of the execute method in the WebViewOverlayPlugin class. Here, for
reference, is the complete class. This code is repeated on the next 4 slides for easy
reference.
Note that the previous version Plugin superclass is replaced by CordovaPlugin as of
Apache Cordova 2.2
package com.WebViewOverlayApp;
import org.apache.cordova.api.Plugin;
import org.apache.cordova.api.PluginResult;
import org.json.JSONArray;
import android.util.Log;
import android.view.View;
public class WebViewOverlayPlugin extends Plugin {
V8.1
Student Notebook
Uempty
8-43
Student Notebook
V8.1
Student Notebook
Uempty
33
WU5061.1
Notes:
Here is where you can see the use of the static variable thisApp that was declared but not
used in the previous class you saw.
This code is a part of the execute method in the WebViewOverlayPlugin class. Here, for
reference, is the complete class. This code is repeated on the next 3 slides for easy
reference:
package com.WebViewOverlayApp;
import org.apache.cordova.api.Plugin;
import org.apache.cordova.api.PluginResult;
import org.json.JSONArray;
import android.util.Log;
import android.view.View;
public class WebViewOverlayPlugin extends Plugin {
8-45
Student Notebook
V8.1
Student Notebook
Uempty
8-47
Student Notebook
34
WU5061.1
Notes:
Note that UI related actions should be performed on a dedicated UI thread.
This code is a part of the execute method in the WebViewOverlayPlugin class. Here, for
reference, is the complete class. This code is repeated on the next 2 slides for easy
reference:
package com.WebViewOverlayApp;
import org.apache.cordova.api.Plugin;
import org.apache.cordova.api.PluginResult;
import org.json.JSONArray;
import android.util.Log;
import android.view.View;
public class WebViewOverlayPlugin extends Plugin {
private final String ACTION_OPEN_URL = "open";
8-48 Mobile Application Development with IBM Worklight V6
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V8.1
Student Notebook
Uempty
8-49
Student Notebook
V8.1
Student Notebook
Uempty
35
WU5061.1
Notes:
The three methods are open, close, and goBack (this last method was not shown in the
previous slides. You can of course add as many methods as you need). These are created
as a part of the prototype. The WebViewOverlayPlugin object is then created and added to
window.plugins.
8-51
Student Notebook
function tabClicked(id){
$(".tab").addClass('hidden');
if (id=="3"){
openWebViewOverlay();
} else {
$("#tab" + id).removeClass('hidden');
closeWebViewOverlay();
}
}
function openWebViewOverlay(){
busyIndicator.show();
setTimeout(busyIndicator.hide, 5000);
window.plugins.webViewOverlay.open();
}
function closeWebViewOverlay(){
window.plugins.webViewOverlay.close();
}
36
WU5061.1
Notes:
Determine which UI tab was clicked and show or hide the webViewOverlay accordingly.
Loading external content can be time consuming, so it is a good idea to also add a
busyIndicator to improve the user experience.
This code is a part of the WebViewOverlayApp.js JavaScript file in the Android
environment.
V8.1
Student Notebook
Uempty
37
WU5061.1
Notes:
8-53
Student Notebook
38
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Checkpoint
1. True or False: In order to use the Apache Cordova API in Worklight,
you must manually add the Cordova library files to your project folder.
2. True or False: All of the Apache Cordova standard APIs are
accessible through the navigator namespace.
3. Which step is required to develop an Apache Cordova plugin?
a)
b)
c)
d)
WU5061.1
Notes:
Write your answers here:
8-55
Student Notebook
Unit summary
Having completed this unit, you should be able to:
Use the Apache Cordova framework to access native device functions
Develop an Apache Cordova plug-in
Develop a WebViewOverlay plug-in to integrate server generated
pages in an application
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Checkpoint answers
1. True or False: In order to use the Apache Cordova API in Worklight,
you must manually add the Cordova library files to your project folder.
False. The Apache Cordova framework is integrated into Worklight and is
immediately available for use by Worklight applications.
WU5061.1
Notes:
8-57
Student Notebook
Exercise
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Exercise objectives
After completing this exercise, you should be able to:
Use the Apache Cordova API to access the devices native Contacts
application and display native alerts
Use the Dojo Mobile toolkit to display various user interface elements
including views and buttons
Use to Rich Page Editor to visually construct an applications user
interface
WU5061.1
Notes:
8-59
Student Notebook
44
WU5061.1
Notes:
You can get more information about Apache Cordova by visiting the web sites listed here.
V8.1
Student Notebook
Uempty
References
IBM Worklight V6 documentation:
http://pic.dhe.ibm.com/infocenter/wrklight/v6r0m0/index.jsp
9-1
Student Notebook
Unit objectives
After completing this unit, you should be able to:
Describe the types of integration adapters that Worklight supports
Use integration adapters to access enterprise resources
WU5061.1
Notes:
9-2
V8.1
Student Notebook
Uempty
Topics
Adapters overview
SQL adapters
HTTP adapters
Using HTTP adapters with SOAP services
Cast Iron adapters
JMS adapters
Invoking Java code from an adapter
The InvocationData object
Invoking an adapter procedure from Java code
Server side scripting
WU5061.1
Notes:
9-3
Student Notebook
9-4
V8.1
Student Notebook
Uempty
9-5
Student Notebook
Adapters overview
WU5061.1
Notes:
9-6
V8.1
Student Notebook
Uempty
Adapters: overview
An adapter is a transport layer used by the Worklight Platform to
connect to back-end systems
Adapters are used to:
Retrieve information
Perform actions
WU5061.1
Notes:
Adapters are sever side artifacts (components) that are meant to interface with various
types of back-end systems like database, web-services, messaging systems etc. Client
applications, specifically Worklight mobile applications, connect to these adapters in a
uniform and simple manner. For example, with just a few lines of JavaScript code. The
purpose is to retrieve data from the back-end systems in a format that is adequately
lightweight for rendering on the mobile device. The adapters could also be used to save
user provided information within back-end systems. As indicated, some adapters, like
HTTP and SQL adapters, are available out-of-the-box such and these are discussed as
part of this module. Adapters must be deployed on the IBM Worklight Server.
9-7
Student Notebook
WU5061.1
Notes:
Here are some of the benefits of adapters in mobile solution-deployment:
Adapter deployments insulates the mobile application from having to deal with multiple
protocol and data formats associated with the back-end systems. The use of adapters
allows the mobile application to not only be able to read data from the back-end systems
but also initiate transactional data processing and just use the end results. Transactions
are performed by adapters and mobile applications do not have to deal with handling
transactional processing issues.
Worklight Adapter uses flexible authentication facilities provided by Worklight
authentication framework to create secure connections with back-end systems and it also
offers control over the identity of the connected server.
Use of adapters help scaling an application by reducing the number of transactions
performed on back-end systems by using cache to store retrieved back-end data
9-8
V8.1
Student Notebook
Uempty
Worklight Server
Procedure
Procedure call
JSON/
HTTP
Application
Back-end
format
JavaScript
Response
JSON
XML
XSLT
(optional)
Back-end
Application
Auto-conversion
To JSON
(if necessary)
JSON
Auto-conversion
To XML
(if necessary)
WU5061.1
Notes:
The adapter framework mediates between the mobile apps and the back-end services. A
typical flow is depicted in the diagram.
An adapter exposes a set of services, called procedures. Mobile apps invoke procedures
by issuing Ajax requests.
The procedure retrieves information from the back-end application.
The back-end application returns data in some format.
If this format is JSON, the Worklight Server keeps the data intact.
If this format is not JSON, the Worklight Server automatically converts it to JSON.
Alternatively, the developer can provide an XSL transformation to convert the data to
JSON. In such case, the Worklight Server first converts the data to XML (if it is not in
XML already) that serves as input for the XSL transformation.
The procedures JavaScript implementation receives the JSON data, performs any
additional processing, and returns it to the calling app.
9-9
Student Notebook
Worklight uses Rhino as the engine for running the JavaScript script used to implement
adapter procedures. Rhino is an open source JavaScript container developed by Mozilla. In
addition to being part of Java 6, Rhino has two other advantages:
? It compiles the JavaScript code into byte code, which runs faster than interpreted code.
? It provides access to Java code directly from JavaScript.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
Every adapter has a similar internal structure. There are three files that get created by the
Worklight Studio wizard for a new adapter. These are as indicated above. The XML file
describes the connectivity options and the lists all procedures that are available as part of
the adapter. Authentication related information for access to the adapter and the
procedures are also included in this file. The second file is the JavaScript file. This is where
the logic associated with the adapter is encoded in the form of JavaScript code. The code
could invoke Worklight server-side API to perform the overall functionality. The third is the
XSL file that is used to transform result obtained as XML from the back-end systems before
being sent to the mobile application running on a device. It is possible to specify more than
one XSL file for use in the transformation. By default, the Worklight server converts data
from the backed systems to a JSON object. Adapters could also be designed and
configured so as to have the back-end data returned without any transformation.
9-11
Student Notebook
Adapter procedures
Adapter functionality is available to the application by using procedures
Procedures call back-end services to retrieve data or to perform actions
Procedures are declared using XML
They are implemented using server-side JavaScript
A procedure can process the data before or after calling the service by
using server-side JavaScript
Additional filtering can be applied to retrieved data by using simple
XSLT
It is possible to use Java snippets in the adapter code
An adapter is a server side entity and can therefore integrate Java methods
WU5061.1
Notes:
Adapter functionality, exposed via procedures, is developed in the JavaScript files and is
available to be invoked by mobile applications. Typically procedure is implemented as a
JavaScript function. Mobile applications use client-side Worklight API to invoke the adapter
procedures. The code that makes up a procedure is essentially server-side JavaScript.
This runs within the RHINO container on the Worklight Server when deployed. A
procedure, can both process the data to the back-end server as well as process data from
the back-end service before sending a response to the mobile application. Post processing
could also include filtering of data received from the back-end by applying XSL transforms
on any XML information returned by the back-end systems.
V8.1
Student Notebook
Uempty
Creating an adapter (1 of 3)
In the Worklight project, right-click
Worklight Adapter
Select New Worklight Adapter
WU5061.1
Notes:
An adapter is created using the Worklight wizard. The invocation of this wizard is shown in
the slide above. Select the New, Other option by from the pop-menu upon right-click on
the adapter folder of an already created Worklight project. Then select the Worklight
Adapter under the Worklight folder in the Select a Wizard dialog box that pops up.
9-13
Student Notebook
Creating an adapter (2 of 3)
Select the project
Choose an adapter type
Enter a name for the adapter
Applications access the adapter using this name
Click Finish
WU5061.1
Notes:
In the Worklight Adapter dialog, select the Worklight Project under which this adapter is to
be created. Then choose the adapter type. There are two types of adapters that can be
created namely, the SQL adapter that is meant for interfacing with a Database or a HTTP
Adapter that is meant to interface with a back-end using HTTP.
Specify the name of the adapter. This is the name that the mobile application should use to
access the adapter. Once all of this information is provided, click Finish.
V8.1
Student Notebook
Uempty
Creating an adapter (3 of 3)
Files are created and added to the project:
XML files to declare procedures and connection properties
JavaScript file to define procedures and adapter logic
WU5061.1
Notes:
At this point, the Worklight Adapter wizard creates a new folder with the adapter name
provided and creates the files mentioned earlier. The slide above shows the adapter
directory content when a SQL type adapter is created. Note the adapter XML file and the
adapter JavaScript file. The XSL transformation file is not applicable in the case of SQL
type adapters is so is not created.
9-15
Student Notebook
Adapter deployment (1 of 2)
Right-click the adapter to deploy
Select Run As > Deploy Worklight Adapter
Worklight Studio archives the adapter code and deploys it onto the
Worklight Server
WU5061.1
Notes:
Adapter deployment in development environment is integrated in Worklight Studio
Right-click on the adapter to be deployed. Select the Run As and Deploy Worklight
Adapter from the respective context menus. This deploys the adapter to the embedded
Worklight test server. You can review the console message within the eclipse for the results
of the deployment.
In cases, where an adapter has to be deployed to a remote Worklight server, running on a
different system, the adapter can be exported from the local Worklight server, via its
console, for deployment on a remote system. Or using the generated adapter .wladapter
file to deploy to remote server. You learn remote server deployment in later training
module.
V8.1
Student Notebook
Uempty
Adapter deployment (2 of 2)
You can see the deployed adapter in the Worklight Console
WU5061.1
Notes:
The deployed adapter can be seen in the Worklight server Console, under the catalog tab
as shown in the screenshot here.
9-17
Student Notebook
WU5061.1
Notes:
This is the same context menu you saw a couple of slides ago. This time, it is the third
option that is chosen.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
In the resulting dialog that pops-up, select the procedure that is to be tested and provide
the input to the procedure as a comma separated list of values. These values is provided
as arguments to the procedure function running in the RHINO container in the Worklight
Server. Click the Run button to execute and exercise the adapter. The response (typically
in JSON) is displayed in the default (external) browser configured in eclipse IDE.
9-19
Student Notebook
connectivity:
Defines the connection properties and
load constraints of the back-end system
When the back end requires user
authentication, this element defines how
user credentials are obtained
<displayName
<displayName />
/>
<description
<description />
/>
<connectivity>
<connectivity>
<connectionPolicy>
<connectionPolicy>
<loadConstraints>
<loadConstraints>
</connectivity>
</connectivity>
<procedure
<procedure />
/>
<procedure
<procedure />
/>
</wl:adapter>
</wl:adapter>
WU5061.1
Notes:
The sample code in this slide shows the XML definition for an SQLAdapter. The root tag is
the <wl:adapter> tag. The name attribute of this tag is mandatory and is the name of the
adapter that was provided at the time the adapter was created.
Another attribute can be specified is the authenticationRealm that is to be used to
authenticate a user when this adapter is invoked via the mobile application. The
authenticationRealm attribute is optional.
displayName is a deprecated tag. Its purpose is to provide a readable name for the adapter
on the Worklight console. In its absence the <adapter> tag's name attribute is used for the
display in the Worklight Server console.
description is an optional tag and is meant to capture additional information that is to be
displayed in the Worklight Console.
The <connectivity> tag is a mandatory tag that is used to provide information regarding the
connection between the adapter running on the Worklight Server and the back-end system.
V8.1
Student Notebook
Uempty
There are two child-elements tags that can be specified for this tag. These are
<connectionPolicy> tag and the <loadConstraints> tag.
The <connectionPolicy> tag is a mandatory tag that is used to configure the connection
with the back-end system. This tag has sub-elements that are dependent on the nature of
the protocol that is used to connect to the back-end system. These sub-elements are
covered in later sections.
The <loadConstraints> tag is also a mandatory tag. It is used to control the load from the
adapter to the back-end system. Typically, it is used to define the number of concurrent
connections to the back-end system. The name of the attribute is
maxConcurrentConnectionsPerNode. If the number of connections that is established
with the back-end system is already at the specified number, the incoming requests from
the mobile applications are queued until a connection is available for forwarding the
request to the back-end. These queued requests are cleaned up upon timeout.
The <procedure> tag is used to declare a procedure. There can be any number of
<procedure> tags associated with an <adapter>. The <procedure> tag can have four
attributes, namely: name, connectAs, requestTimeoutInSeconds and audit.
name which is a mandatory attribute that indicates the name of the procedure.
connectAs, an optional attribute, indicates whether the connection to the back-end is to
be done as server, meaning Worklight server, or as endUser.
requestTimoutInSeconds, also an optional attribute, indicates the time in seconds to wait
for a response from the back-end system. The time specified here includes the time taken
to setup the connection.
audit, takes values of true or false. This is meant to indicate if the access to the
adapter from the mobile application instances should be logged in the Worklight server's
audit.log file. The audit attribute is an optional attribute.
9-21
Student Notebook
JavaScript file
18
WU5061.1
Notes:
The JavaScript file that is also generated as part of the adapter creation via Worklight
Studio, this file is where your business or integration logic should be implemented.
As mentioned before, integration logic is handled as a procedure. In this implementation
file, a procedure is defined as a JavaScript function since adapter uses Server side
JavaScript as programming language.
The function name defined here has to match the procedure declaration in the XML file
under the procedure tag. Name attribute. For example, the procedure name procedure1
matches the function name procedure1.
V8.1
Student Notebook
Uempty
9-23
Student Notebook
SQL adapters
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Download the JDBC connector driver for a specific database type and
add to the lib directory of Worklight project
WU5061.1
Notes:
An SQL Adapter, that is available out-of-the-box, is capable of interfacing with a back-end
relational database with minimum configuration. The required configuration is reviewed in
the following slides. The adapter may either use an SQL Query or an SQL
Stored-procedure to perform database transactions on user data.
Worklight Version 6 supports MySQL, Derby, Oracle 11g and IBM DB2 databases.
9-25
Student Notebook
WU5061.1
Notes:
Creating the SQL Adapter only requires selecting the SQL Adapter as the adapter type
when creating an Adapter in Worklight Studio as shown the screen shots here. The
creation of an adapter in the Worklight studio was covered previously. You may recall that
in the case of SQL Adapters only two files are created for the adapter, namely, the XML file
that defines the adapter information such as authentication and procedures and the
JavaScript file that provides integration function or business logic via JavaScript code.
After SQLAdapter is created, you need to add the specific JDBC connector files to projects
server lib folder. For example, Db2 JCC JDBC driver jar file or mySQL connector jar file etc.
Worklight runtime relies on these library to establish connect with associated backend
database.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
As discussed in adapter introduction module, every adapter has an XML file that is used to
store adapters setting and metadata. For SQLAdapters, this file is used to configure the
database connection information. You can open and Edit this XML file in Eclipse based
Worklight studio either in Design or Source mode.
Connect to backend database server is configured via the ConnectionPolicy element under
the connectivity tag.
There are four important information you need to provide to Worklight server runtime in
order to connect to backend database.
You need to specify the JDBC driver class as defined by the DriverClass element. For
different database, specify their JDBC driver class name with full package name. For
example, com.mysql.jdbc.Driver to connect to MySQL server.
The second configuration entry is the URL to the backend server. This might be different
depending on database you are connecting to. In a MySQL example, the connection URL
to the MySQL server would be jdbc:mysql://localhost:3306/worklight_training. You need to
Copyright IBM Corp. 2013
9-27
Student Notebook
supply valid credential to access the database. They are specified via the user and
password elements. You can define the SQL connection attribution such as concurrent
connection numbers via the loadConstraints property.
V8.1
Student Notebook
Uempty
Important:
The same name declared in
the XML file should be used
for the JavaScript function
There are two ways
to invoke SQL
statements:
SQL statement query
SQL Stored Procedure
WU5061.1
Notes:
An example of a procedure declaration is shown here.
The procedures for the SQL Adapter must be declared in the XML file. As mentioned
previously, SQL adapter's procedure is implemented as JavaScript function in adapter's js
file which well introduce later. As application developer, you need to ensure that The same
name declared in the XML file should be used for the procedures JavaScript function.
Depending on the database used and implementation requirement, the procedures could
use direct SQL Query to interact with the back-end database or could use a database
stored-procedure. Application developer need to work with data architect or database
developers to agree on the implementation type.
9-29
Student Notebook
3
2
WU5061.1
Notes:
The example query shown here highlights steps 1-3 from the procedure.
In the JavaScript implementation file, developer needs to implement the SQL adapter
procedures. As mentioned previous, you can use standard SQL query to interact with
backend data to retrieve, update or delete database records.
Define a JavaScript function as Adapter procedure.
To use Adapter SQL query, start with defining the SQL query using the
WL.Server.createSQLStatement API. Assign the this statement to a JavaScript variable.
Note, this variable definition and createSQLStatement should always be executed or
defined outside of the adapter procedure function thats going to use this SQL query. This is
shown as step 1 in the sample code provided in the slide.
Then, inside of your procedure JavaScript implementation function, use the
WL.Server.invokeSQLStatement API to execute the SQL Query created earlier as shown
as Step 4 in the sample code.
V8.1
Student Notebook
Uempty
Inside of the invokeSQLStatement, you can provide the parameters to replace variables
defined the SQL query, this is essentially the same programming model as Java Prepared
Statement for database query.
Finally, the call returns on invocation result object to the caller of the procedure, in this
case, the mobile client application. All query results are wrapped under this object.
9-31
Student Notebook
procedure.
2. Specify an SQL stored procedure name as an invocation parameter.
3. Add parameters if required.
1
2
3
WU5061.1
Notes:
This slides shows how to invoke a database stored procedure using Worklight SQL
adapter.
There is no need to define the SQL query since the logic is implemented in the database
stored procedures. To invoke the procedure, pass the database stored procedure as a
parameter to the Worklight API: WL.Server.invokeSQLStoredProcedure as shown in the
sample code step 1 in the slide.
Note, this API needs to be executed inside of the SQL adapter procedure or inside the
function block.
Again, you can pass optional parameters that required by the database stored procedure.
Similar as SQL query invocation, the stored procedure execution result is returned via the
invocation result object, and further returned to the caller of the adapter procedure, either
mobile client or another adapter procedure.
V8.1
Student Notebook
Uempty
resultSet
An array of returned records
WU5061.1
Notes:
This slide shows a typical result object of SQL adapter procedure invocation. The result is
always retuned in JSON format.
The JSON object that is returned by the adapter, consists of a isSuccessful flag that is
used to indicate whether the adapter invocation such as database query or stored
procedure execution was successful.
, the resultSet is an array of records retrieved from the database. In another words, these
are the records or information returned from the execution of SQL query or database stored
procedure. As you can see, Worklight SQL adapter automatically converted them to JSON
data for easy access by mobile or web clients.
9-33
Student Notebook
V8.1
Student Notebook
Uempty
9-35
Student Notebook
HTTP adapters
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
A HTTP Adapter uses either HTTP GET or HTTP POST method to interact with the
back-end system REST or SOAP based services.
With HTTP adapter, developer can access structured HTTP resources such as RSS or
ATOM feeds easily with minimum coding.
Using Worklight HTTP Adapter and associated server side API, you can send HTTP
request via the standard GET or POST call, in the mean time, HTTP adapter can retrieve
data from the response HTTP headers and body in order to exchange data.
HTTP adapters can be extended and modified to implement server side functionality.
This can be done by using server-side JavaScript. As indicated in our overview section for
adapters, data retrieved from back-end system can be filtered / post-processed, as
required, and the resulting data can be sent back to the mobile application in any desired
format with the XML and JSON being the more convenient and popular choices.
9-37
Student Notebook
WU5061.1
Notes:
HTTP Adapters can be created, as explained before, by choosing the HTTP Adapter type
in the Worklight Adapter creation wizard as shown on the screen. This wizard can be
launched from the Menu bar New Others. Then select Worklight Adapter or by using the
context menu of adapters folder. Please refer to previous training module for details on
launching the Worklight Adapter wizard.
After an HTTP adapter is created, three files are generated in the adapter directory. They
are the adapter XML file containing adapter metadata, the JavaScript implementation file
and the XSL filter file.
V8.1
Student Notebook
Uempty
domain
the domain part of the HTTP URL
port
TCP port
WU5061.1
Notes:
The protocol, domain, and port for the HTTP adapter must be set in the XML file.
Worklight Adapter uses an XML to define adapter configuration information and
procedures. Some of HTTP adapter unique connection configuration is defined in this XML
file.
You can open and Edit the adapter xml definition file in Eclipse editor using either source or
design view.
The important connection for an HTTP adapter is defined by the connectionPolicy element
under the connectivity tag.
The <connectionPolicy> element Defines the back-end endpoint information to establish a
connection between the Worklight server hosting the adapter and the back-end service
either RESTful or SOAP based service end point. The endpoint information includes:
<protocol> - which is typically HTTP or HTTPS,
<domain> - which is meant to specify the fully qualified domain name of the back-end
server that is hosting the HTTP service
Copyright IBM Corp. 2013
9-39
Student Notebook
<port> - which is meant to specify the port to be used to establish the connection to the
back-end server
Optionally, the following could also be specified:
<authentication> - The authentication configuration for the HTTP adapter
<proxy> - The proxy system to be used to access the back-end system
These values are common and are used for all invocation of the back-end from each
procedure declared for the adapter.
The <connectionPolicy> tag itself can have a number of attributes to further specify the
nature of the connection to the back-end systems. These are:
xsi:type - this is mandatory and is to have a value of HTTPConnectionPolicyType
cookiePolicy - This attribute sets how the HTTP adapter handles cookies arriving from the
back-end application. This can take values such as: RFC_2966, IGNORE_COOKIES,
NETSCAPE. The default is RFC_2109
maxRedirects: - this is to indicate the number of HTTP redirects to be processed by the
adapter.
proxy: - which takes a value of true or false; indicates whether proxy information
specified in the worklight.properties files should be used to access back-end.
V8.1
Student Notebook
Uempty
Query string
http://example.com/rest/customers?custid=12
Path elements
WU5061.1
Notes:
See adapter documentation for advanced options such as cookies, headers, encoding.
HTTP adapter implementation relies on the service URL to access the backend system.
The connectionPolicy properties provided in the adapter XML files is used in Adapter
implementation file to fully construct the HTTP URL that is used to access the back-end
resource/service. These are the constant part of the URL.
The remaining parts of the URL are to be specified in the respective procedures depending
on the specific service or resource that is required to be accessed. These parts include the
path elements where the resource / service is exposed and any additional input parameters
to the retrieve the resource state or to the service itself.
Developer can specify these URL components as either path elements such as the
/rest/customers in the sample URL provide in the slide. You can also provide the query
string parameters as part of the HTTP end point URL such as custid=1 shown in the
example here.
9-41
Student Notebook
These URL parts are specified in the JSON object that forms the input to the Worklight
server-side API that is actually used to access the back-end service. This JSON object can
also be used to specify some of the optional inputs such as cookies, headers, encodings
etc.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
The implementation file can have several more functions than are declared in the
configuration file. These are functions that should not be called externally, but only from
other functions. In the example on this slide, the configuration XML declares two
procedures, getFeeds and getFeedsFiltered. Therefore these two names must have
corresponding functions in the implementation file. The implementation file also has a
function called getPath() that is not mentioned in the configuration. It can therefore only be
called from one of the other functions, not directly as an adapter procedure.
Note that there is no error generated by having functions with no procedure declaration.
However, there is an error generated if you have a procedure declaration with no
implementation function!
Procedure and function are synonymous. The terminology is different between the two
files because the implication is different.
9-43
Student Notebook
WU5061.1
Notes:
The example shows the JSON object that is constructed and used for input into the
Worklight server-side API call to invoke an HTTP based backend service. There are three
items included in the input JSON object. These indicate the HTTP Method to be used
either Get or POST, the format of the returned data and the service endpoint URL path
information described previously.
To invoke backend RESTful or HTTP service in HTTP adapter, you use the Worklight
server-side API WL.Server.invokeHTTP. This method can only be used in a HTTP
adapter type. This API transforms any resulting data returned from the associated
back-end service to JSON. In addition to the list of items shown in the input object
mentioned before, other items that could have been optionally provided include:
parameters a list of parameters to be sent to the HTTP end-point
headers a list of name-value pairs of HTTP header that are to be transmitted
cookies a list of cookies to be transmitted
body the request body. This is only used with the POST method.
9-44 Mobile Application Development with IBM Worklight V6
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V8.1
Student Notebook
Uempty
9-45
Student Notebook
WU5061.1
Notes:
The output from the XML can be filtered by adding a criterion to the procedure invocation
input parameters.
You process the received HTTP service data by applying XSL transformation before
sending data back to the adapter procedure invocator (for example, a mobile client).
This slide shows how to specify the transformation as part of the input object to the
invokeHTTP method. Data received from the back-end resource or web-service is
transformed according to the specified XSL. The transformation is typically used to either
filter the data or to mash it with other data specified/computed within the adapter, or simply
convert to a data format can be easily consumed by the client application. The type such as
xslFile and the XSL file name needs to be specified in the transformation object as
highlighted in the slide.
Note: If the back-end returns HTML, the built-in transformation capability converts it to
XHTML before applying the XSL transform on it.
V8.1
Student Notebook
Uempty
9-47
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
To invoke a SOAP based web-service, You can directly create and send the SOAP
envelope using the Worklight API WL.Server.invokeHTTP.
Unlike a standard HTTP like RESTful service invocation, you need to encode the SOAP
XML envelope within the HTTP request body in order to invoke SOAP based service using
Worklight HTTP Adapter. Worklight Adapter uses JavaScript E4X standard to handle the
SOAP XML encoding.
E4X is an official JavaScript standard that adds direct support for XML. With E4X, you can
declare an XML object variable the same way as you declare a Date or an Array object
variable:
In Eclipse editor, If you receive error messages for SOAP envelopes, disable the
JavaScript validator.
You can Select Project > Properties > Builders and clear JavaScript Validator
9-49
Student Notebook
WU5061.1
Notes:
The soap:Envelope is the root element of the SOAP message.
Here is an example of the SOAP Envelope XML being assigned to a request JavaScript
variable. A request variable is defined that has the value of a SOAP envelope structure that
targets a SOAP based service called conversionRate.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
The messageHeader element contains application-specific information about the SOAP
message. If the header element is present, it must be the first child element of the
Envelope element.
With E4X support, you can insert JavaScript code into the SOAP Envelope XML. This
convenient method allows easy manipulation of the SOAP envelope. For example you can
dynamically specify the originating IP address of the SOAP messageHeader using a
Worklight configuration item by replacing the XML element with a Worklight JavaScript API
Wl.Server.configuration.
9-51
Student Notebook
WU5061.1
Notes:
Like any other HTTP adapter usage, SOAP service invocation is handled via Worklight API
WL.Server.invokeHTTP().
The options object passed to the invokeHTTP method specifying important information for
the service invocation.
You can define the invocation HTTP method, normally, it is HTTP POST method.
You can specify the End port service path under the same rules as described in HTTP
adapter section.
IN body attribute, you specify the SOAP envelope that is assigned to the request variable
as described in previous slide using the content attribute. When sending it using
invokeHTTP method, you need convert the SOAP envelope to a string using the JavaScript
toString method to encode.
And you can specify the contentType for the invocation normally text/xml; charset=utf-8 for
SOAP based services.
V8.1
Student Notebook
Uempty
SOAP
envelope
Options
Request
invocation
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
This sample in the slide shows the complete code and steps to a SOAP based back-end
web-service.
Again, start by defining the SOAP envelope, then define the input options object that
specify the invocation detail such as service end point URL path and context type etc.
Finally, use the Worklight API WL.Server.invokeHttp with input object as parameter to
execute the invocation.
When SOAP service invocation returns, Worklight Server converts the response XML
payload into a JSON object use the element as is. This might not be that use for client
application to consume. So, its recommended to use XSL transformation post-processing
in your HTTP Adapter to convert to mobile/web friendly JSON before sending response
back to the mobile client.
9-53
Student Notebook
V8.1
Student Notebook
Uempty
9-55
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Enterprise
apps
42
WU5061.1
Notes:
To integrate a Worklight mobile solution with Cloud including SaaS (Software as a Service)
and Enterprise cloud, Worklight provides a Worklight Cast Iron adapter that developer can
create to simply integrate with Cast Iron platform.
Like other Worklight adapter types, Worklight Cast Iron Adapter sits in between the mobile
application and back end cloud or Enterprise applications. It provides Worklight server side
features such as session management.
A request from a mobile client can be processed by the Worklight Cast Iron adapter which
in turn invokes and iinitiates orchestrations in Cast Iron to retrieve and return data to mobile
clients. This is shown in the architecture diagram here.
For more information about Cast Iron, see
http://www.redbooks.ibm.com/redpapers/pdfs/redp4840.pdf
and
http://www.redbooks.ibm.com/abstracts/sg248004.html?Open
9-57
Student Notebook
43
WU5061.1
Notes:
Worklight Studio provides unified tools for creating Worklight Cast Iron Adapter.
In Worklight Adapter creation wizard, select the Adapter type as Cast Iron Adapter from the
drop down and click finish.
Worklight Studio creates the Cast Iron Adapter folder structure and skeleton files including
the Adapter definition xml file and implementation JavaScript placeholder.
The integration logic with Cast Iron is defined in the CastIronAdapter implementation
JavaScript file as shown in the slide.
V8.1
Student Notebook
Uempty
44
WU5061.1
Notes:
For a full list of invocation options see the Developers Reference Guide.
Optionally, you can leverage XSL transformation to process returned data from Cast Iron
component; for example, converting backend XML data to JSON or another form of XML
file.
This approach can also be used to filter returned backend data; for example, retrieve only
data relevant to current logged in user.
To apply XSL transformation, define an optional property in Cast Iron invocation input
object. This attribute is defined as under transformation in the input object.
You need to specify the type of the transformation, for example xslFile, which indicates the
transformation should be handled by an XSL file.
9-59
Student Notebook
V8.1
Student Notebook
Uempty
9-61
Student Notebook
JMS adapters
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
The Java Message Service (JMS) is the messaging standard defined by the Java
Enterprise Edition (JEE) APIs. It allows application components to send and receive
information asynchronously, without the other party being online, and without waiting for a
response. Communication between components of a distributed application can therefore
be loosely coupled.
9-63
Student Notebook
WU5061.1
Notes:
Creating a JMS adapter is the same process as for any other adapter. The generated files
are often very similar also. It is interesting to create different adapters and compare the
structure. The files are the same, but there are significant differences in the default code
that Workloight generates.
V8.1
Student Notebook
Uempty
Implementing procedures
Procedure names in the JavaScript file must be the same as in the
XML file
DESTINATION is the target for messages that are produced by the
client and the source for messages that are used by the client
WU5061.1
Notes:
This is minimal coding. In reality, you would want to verify that there was an id for the
JMSMessage, and either print out that the message was not sent correctly, or print a
confirmation message with the id to show that that it was sent correctly.
9-65
Student Notebook
Connection properties
Connection properties are configured in the adapter XML file
JMS Connection
connectionFactory: the classname for JMS Connection Factory that
contains JMS configuration properties
user, password: the credentials as set up by JNDI administrator
WU5061.1
Notes:
If you want to use an external JNDI repository you use a <namingConnection> property, as
follows:
<namingConnection url="MY_JNDI_URL"
initialContextFactory="providers_intial_context_factory_class_name"
user="JNDI_UserName"
password="JNDI_Password"/>
V8.1
Student Notebook
Uempty
var result =
WL.Server.readSingleJMSMessage({
destination : "jms/MyQ",
timeout : 60,
filter : "NewsType = 'Opinion'"
});
readAllJMSMessages
var result =
Accepts the same parameters WL.Server.readAllJMSMessage({
destination : "jms/MyQ",
as the readSingleJMSMessage
method
timeout : 60
});
Returns a list of JMS
messages in the same format
as the readSingleJMSMessage
method
The result is contained in a
messages object
WU5061.1
Notes:
readAllJMSMessages returns a list of JMS messages in the same format as the
readSingleJMSMessage method. The result is contained in a messages object:
messages:[
{
body: Hello World,
properties : {
JMSCorrelationID: null,
}
},
{
9-67
Student Notebook
var result =
WL.Server.writeJMSMessage({
destination : DESTINATION,
message: {
body: My text message,
properties: { }
}
});
requestResponseJMSMessage
Waits for a response on a dynamic destination
Designed for services that use the replyTo destination from the originating
message
WU5061.1
Notes:
The JMSMessageID is a JSON object with the form
{
JMSMessageID : ID:414d5,
isSuccessful: true
}
The requestResponseJMSMessage method takes the same parameter as the
writeJMSMessage method, a JSON object that contains the destination and a
message. Like the writeJMSMessage, it writes a JMSText message to the
destination. The JMS message that is returned is in the same format as
the readSingleJMSMessage method.
V8.1
Student Notebook
Uempty
9-69
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Overview
An adapter is a server side entity, implemented using JavaScript
Complex functionality can be performed by an adapter, for example:
encrypting and decrypting data
generating and validating security tokens
and so on
WU5061.1
Notes:
There may be an existing Java application that has tried and proven functionality, and
those methods could be used for the Worklight adapter. It may also be that there is more
complexity in the business logic than can easily be handled by a JavaScript function. These
are the typical scenarios where it is useful to be able to call a Java method from a
JavaScript adapter.
It should be noted that Java is, in both cases, an extension to the functionality of the
adapter. It does not replace the adapter JavaScript file.
9-71
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
com.worklight.customcode
WU5061.1
Notes:
Make sure that the package name starts with com. This way Worklight is able to find the
package. This is a requirement in Worklight version 6 that going forward will be modified to
allow any package name.
9-73
Student Notebook
If there are any other dependencies, put the required JAR files in the
server\lib directory of the Worklight project
WU5061.1
Notes:
There is no logical reason to make one method static in the code on this slide it is only
included to show the different calling structures, on the next slide.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
The code on the previous slide showed the method addTwoIntegers() declared as static.
The fully qualified package class method is therefore sufficient to invoke the method.
The method subtractTwoIntegers() was not declared static, therefore it is necessary to
create an instance of the class first (in this case, the variable calcInstance holds the
reference to this instance). The invocation and return of the calculated value is then
identical for subtractTwoIntegers() as for addTwoIntegers().
9-75
Student Notebook
V8.1
Student Notebook
Uempty
9-77
Student Notebook
The InvocationData
object
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
invocationData object
The invocationData object is used to provide invocation
configuration and procedure parameters
It consists of a JSON block of properties
Required parameters:
adapter
procedure
parameters
59
WU5061.1
Notes:
adapter (mandatory)
A string containing the name of the adapter as specified in the adapters <wl:adapter>
element.
procedure (mandatory)
Procedure name as defined in the XML file.
parameters (mandatory)
An array of parameters that are passed to the backend JavaScript procedure. Leave empty
if no parameters are required
9-79
Student Notebook
Options object
Success and failure behavior can be defined in an options
object
onSuccess: The function to be invoked on successful completion of
the asynchronous call.
onFailure: The function to be invoked on failure.
invocationContext: Optional parameter. An object that is returned to
the success and failure handlers.
WU5061.1
Notes:
onSuccess: The function to be invoked on successful completion of the asynchronous
call.
The response typically contains the following properties:
invocationContext: The invocationContext object that was originally passed in the
options object, or undefined if no invocationContext object was passed.
status: The HTTP response status.
invocationResult: An object containing the data returned by the invoked procedure,
and additional information about the procedure invocation.
onFailure: The function to be invoked on failure.
Includes both server-side errors, and client-side (such as server connection failure or timed
out calls). The response typically contains the following properties:
invocationContext
V8.1
Student Notebook
Uempty
errorCode: An error code string. All error codes that can be returned are defined as
constants in the WL.ErrorCode object in worklight.js.
errorMessage: This message is for the developer's use only, and should not be
displayed to the end-user. It is not translated to the user's language.
status: The HTTP response status
invocationContext: Optional parameter. An object that is returned to the success and
failure handlers.
The invocationContext object is used to preserve the context of the calling asynchronous
service upon returning from the service.
9-81
Student Notebook
1. Invocation data
5. Failure handler
61
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
The onSuccess and onFailure functions are more complex than shown! Here is one
possible code sample:
The loadFeedsSuccess() function :
busyIndicator.hide();
if (result.invocationResult.Items.length>0)
displayFeeds(result.invocationResult.Items);
else
loadFeedsFailure();
And for loadFeedsFailure():
busyIndicator.hide();
WL.SimpleDialog.show("RSSFeedApp",
"Cannot retrieve feed. Check internet connectivity.",
9-82 Mobile Application Development with IBM Worklight V6
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V8.1
Student Notebook
Uempty
[{
text : 'Reload App',
handler : WL.Client.reloadApp
}]);
There is also a function to create the HTML code for the display.
9-83
Student Notebook
Invocation result (1 of 2)
62
WU5061.1
Notes:
isSuccessful property:
- true if the procedure invocation succeeded (even if no data was retrieved)
- false otherwise
Records
An array of records retrieved from the backend. Each array entry is an object containing
the fields of the single record. If the procedure call returns no records, an empty array is
returned. If not specified otherwise in the XSL file, default property name is recordSet.
Error, Warn, Info Messages
An optional array of strings containing error messages. If no error messages are
provided, this object is NULL.
V8.1
Student Notebook
Uempty
Invocation result (2 of 2)
Function
Function loadFeedsSuccess
loadFeedsSuccess (result){
(result){
WL.Logger.debug
WL.Logger.debug ("Feed
("Feed retrieve
retrieve successful");
successful");
if
if (result.invocationResult.Items.length
(result.invocationResult.Items.length >> 0)
0)
this.displayFeeds
this.displayFeeds ((
result.invocationResult.Items);
result.invocationResult.Items);
}}
63
WU5061.1
Notes:
9-85
Student Notebook
V8.1
Student Notebook
Uempty
9-87
Student Notebook
Invoking adapter
procedures from Java
code
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
65
WU5061.1
Notes:
DataAccessService is an interface that provides methods to invoke procedures, subscribe
and unsubscribe notifications, and update device tokens. All the methods return an
InvocationResult object. WorklightBundles has the method getDataAccessService() that
returns a DataAccessService instance.
Any required parameters are assembled in an array and a ProcedureQName object is
created with the references for the adapter and the function to be called.
The DataAccessService invokeProcedure() method is used to call the JavaScript function
with the adapter name, function name, and parameters. The result is converted into a
JSON object with the InvocationResult method toJSON().
9-89
Student Notebook
V8.1
Student Notebook
Uempty
9-91
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Server-side scripting
Enhances adapter capabilities
Pre and post processing logic
All processing can be done with only one call to the server and in one
transaction
Enables data mashups from different sources
PreProcessing
Invoke procedure
Procedure
Logic
PostProcessing
67
WU5061.1
Notes:
The point here is that the procedure logic is usually split over several functions, potentially
in different adapters (and even in Java). This, the logic is structured, easily maintained, and
reusable, while the user only needs to make one request to the server. There is nothing
new in such a process! Here, it allows for mashup of information.
9-93
Student Notebook
Server-side API
WL.Server.InvokeProcedure (invocationData)
Procedure invocation from current or other adapter
Same syntax as a client-side WL.Client.invokeProcedure()
WL.Logger.debug (msg)
Sends messages to the console
Used for debugging
WL.Server.configuration object
A map containing all the server properties defined in the worklight.properties
file
Syntax
WL.Server.configuration[property-name]
WL.Server.configuration.property-name
Example
Var addr = WL.Server.configuration[local.IPAddress];
68
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Mashups
A mashup is an aggregation of data or functionality from different sources
You can mash up different data sources and return the data stream to the
application as a single invocationResult object
Can be implemented in the same way for any number of data sources and
across different adapter types
Server-side
JavaScript
Yahoo Weather
(RSS)
City Weather
(MySQL)
SQL
CityWeather app
HTTP
69
WU5061.1
Notes:
The example takes data from the following sources:
- SQL :
Extract a list of cities from the weather table. The result contains list of several
cities around the world, their Yahoo! Weather identifier and some description
- HTTP:
Connect to Yahoo! Weather Service
Extract updated weather forecast for each of the cities retrieved with SQL
The mashed-up data is returned to the application for display.
9-95
Student Notebook
Checkpoint
1. What are adapters most typically used for?
A. Authenticate users
B. Retrieve data or perform actions
C. Export and deploying applications
D. Convert from one protocol to another
WU5061.1
Notes:
Write your answers here:
V8.1
Student Notebook
Uempty
Checkpoint
You can invoke an adapter procedure with this call:
WL.Client.invokeProcedure (invocationData, options)
3.
4.
5.
6.
What is a mashup?
WU5061.1
Notes:
Write your answers here:
9-97
Student Notebook
Unit summary
Having completed this unit, you should be able to:
Describe the types of integration adapters that Worklight supports
Use integration adapters to access enterprise resources
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Checkpoint answers
1. B. Retrieve data or perform actions
2. D. Communicating with any SQL data source
3. Name one of the 3 name/value pairs for invocationData
6. What is a mashup?
WU5061.1
Notes:
9-99
Student Notebook
Exercise
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Exercise objectives
After completing this exercise, you should be able to:
Develop an adapter
Invoke an adapter from a client application
WU5061.1
Notes:
9-101
Student Notebook
V8.1
Student Notebook
Uempty
References
IBM Worklight V6 documentation:
http://pic.dhe.ibm.com/infocenter/wrklight/v6r0m0/index.jsp
10-1
Student Notebook
Unit objectives
After completing this unit, you should be able to:
Combine native and web pages in a mobile application
Use transition effects to animate the navigation between a native and
web page
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Topics
Overview of native and web page integration
Combining native and web pages on Android
Combining native and web pages on iOS
WU5061.1
Notes:
10-3
Student Notebook
V8.1
Student Notebook
Uempty
10-5
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
This slides explains the need for combining web and native pages.
Web technologies like HTML5 and CSS3 are powerful and capable of delivering highly
interactive mobile applications. In addition, with the Apache Cordova framework, mobile
web applications can access native phone features that traditionally only native
applications could. This further closes down the gap between web and native applications
on a mobile device.
However, there are still cases where native applications do better than their web
counterpart. For example, accessing hardware sensors such as the gyroscope or
microphone is still a limitation for web applications. Or if you want to build a highly
interactive Map application using a native toolkit such as the iOS MapKit framework, you
have to write a native page.
Therefore, some portions of your mobile application need to be developed as native pages.
How then are you going to seamlessly integrate your web and native pages? Worklight
provides a solution which is described in the next slides.
10-7
Student Notebook
WU5061.1
Notes:
It may also be that a visible native page is not required, but the native functionality of the
device needs to be invoked. Examples of this are: retrieving certificates from the keystore,
native third party libraries, or complex computation that would be too slow in JavaScript.
Worklight allows you to include pages developed in the native operating system language
in your applications. The natively developed pages can be invoked from your web-based
pages and can then return control to the web view. You can pass data from the web page
to the native page, and return data in the opposite direction. You can also animate the
transition between the pages in both directions. Both web and native pages can share a
single server session maintained by Worklight Server.
Worklight provides a native API to communicate with the Worklight server from native
page. Information, including cookies, can be shared between the web environment and the
native environment.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
To develop a combined native and web page mobile application:
Develop the web pages using the standard HTML5, CSS3 and JavaScript technologies
in Worklight Studio. When you need to invoke a native page from a web page, use the
Worklight web API, WL.NativePage.show(), to navigate to the native page and back,
passing any desired parameters. This method takes three parameters:
- The first parameter specifies the name of the native class. In example on the slide,
it is the Android Java class named com.demo.NativePage. Note, that the syntax for
iOS and Android is different, as for the former you only need to specify the class
name, while for the latter, you need to specify the package name and class name.
You can use Worklights environment optimization feature to easily handle both
situations.
- The second parameter defines a callback function that is called when the native
page switches back to the web view. This function is passed a single JSON object
parameter when invoked which can be used to pass back data from the native page.
10-9
Student Notebook
- The last parameter is a JSON object that is sent to the native class.
Develop the native pages using a platform specific language such as Objective-C for
iOS and Java for Android. For Android, you can develop native pages in Worklight
Studio, while for iOS, you develop them in Xcode. If desired, you can use Worklight
native API to communicate with backend Worklight server so that both web and native
pages can share the same server session and exchange information via cookies.
Package the web and native pages in the same Worklight project in Worklight Studio.
The web and native page communication is handled by Worklight client side web
containers which act as a shell program between the two layers.
V8.1
Student Notebook
Uempty
10-11
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
You can develop an Android native page in Worklight Studio if you have an Android
development environment set-up (Android SDK and Android Development Tools Eclipse
plug-in).
The page must be implemented as an Activity object must be declared the applications
Android manifest file.
10-13
Student Notebook
Native code
Figure 10-9. Native on Android: Receiving data from the web page
WU5061.1
Notes:
In the activity, you can receive data passed from the web view using the activitys Intent
object. The Worklight client framework makes the data available to the activity in a Bundle.
Notice that the argument of the getStringExtra() method is the name of the JSON
parameter to retrieve (nameParam in the example shown).
V8.1
Student Notebook
Uempty
JavaScript code
WU5061.1
Notes:
The sample code shown here passes the phoneNumber string back to the web page.
10-15
Student Notebook
WU5061.1
Notes:
You can implement any transition effect supported by Android when switching the display
from the web view to the native page and in the opposite direction:
To implement a transition animation when switching the display from the web view to
the native page, invoke the overridePendingTransition() method inside the onCreate()
method.
To implement a transition animation from the native page to the web view to, invoke the
overridePendingTransition() method inside the onActivityResult() method.
In the sample code above, the Android transition effect requested is a fade-in and fade-out.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
The class name parameter is the full package and class name of the activity implementing
the native page.
The data passed to the native page is a JSON object. The data passed back from the
native page is also a JSON object. In this sample code shown, the data parameter of the
backFromNativePage callback function contains the data sent from the native page.
10-17
Student Notebook
V8.1
Student Notebook
Uempty
10-19
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Subclass UIViewController
WU5061.1
Notes:
In Xcode, create your applications native pages in the same Worklight project that also
hosts the web artifacts.
In iOS, a native page must be implemented as an Objective-C class that extends the
UIViewController class in order to use the Worklight native navigation features. This class
must be able to initialize through the init method alone. The initWithNibName:bundle:
method is never called on the class instance.
10-21
Student Notebook
Native code
Figure 10-15. Native on iOS: Receiving data from the web page
WU5061.1
Notes:
You can access the data passed from the web page by implementing the
setDataFromWebView method. The web data is packaged in an Objective-C NSDictionary
object and passed to the method as a parameter.
Notice that the argument of the valueForKey method is the name of the JSON parameter to
retrieve (nameParam in the example shown).
V8.1
Student Notebook
Uempty
JavaScript code
WU5061.1
Notes:
When the native page needs to switch back to the web view, it calls the NativePage
showWebView: method and passes it a NSDictionary object. This dictionary can be
structured in any hierarchy or can be an empty. The Worklight runtime framework encodes
it in a JSON format, and then sends it as the first argument of the JavaScript callback
function.
In order to access all of the Worklight native to web navigation features, you need to
include the NativePage.h header file in your class definition.
The sample code shown above passes the phoneNumber string back to the web page.
10-23
Student Notebook
WU5061.1
Notes:
You can implement any transition effect supported by iOS when switching the display from
the web view to the native page. To do so, write the animation code in the onBeforeShow
and onAfterShow methods. These methods are called before the display switches from the
web view to the native page, and after the transition, respectively.
In the sample code above, the iOS transition effect implemented rotates the screen to the
right as the web page is replaced by the native page.
You can also implement any transition effect supported by iOS when switching the display
from the native page to the web view. To do so, write the animation code before you return
control to the web page, i.e., before calling NativePage showWebView.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
The first parameter of the WL.NativePage.show() function is the class name of the
Objective-C class that implements the native page.
The data passed to the native page is a JSON object.
Compare this code block with the code shown on slide 13, Web page on Android:
10-25
Student Notebook
Figure 10-19. Web page on IOS: Receiving data from the native page
WU5061.1
Notes:
The data passed back from the native page is also a JSON object. Here, the data
parameter of the backFromNativePage callback function contains the data sent from the
native page, exactly as for the Android code.
V8.1
Student Notebook
Uempty
Checkpoint
1. The Worklight function used to invoke a native page from a web page
is:
a) WL.Client.connect
b) WL.Page.load
c) WL.NativePage.show
d) WL.Native.show
2. True or False:
On the Android platform, the native page must be implemented as a
subclass of UIViewController.
3. True or False:
Data passed from and received by the web page is in JSON format.
WU5061.1
Notes:
Write your answers here:
10-27
Student Notebook
Unit summary
Having completed this unit, you should be able to:
Combine native and web pages in a mobile application
Use transition effects to animate the navigation between a native and
web page
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Checkpoint answers
1. The Worklight function used to invoke a native page from a web page
is:
a) WL.Client.connect
b) WL.Page.load
c) WL.NativePage.show
d) WL.NativeShow
c) WL.NativePage.show
3. True or False: Data passed from and received by the web page is in
JSON format.
True
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
10-29
Student Notebook
Exercise
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Exercise objectives
After completing this exercise, you should be able to:
Combine a native and a web page in a mobile application
Exchange data between a native and web page
WU5061.1
Notes:
10-31
Student Notebook
V8.1
Student Notebook
Uempty
References
IBM Worklight V6 documentation:
http://pic.dhe.ibm.com/infocenter/wrklight/v6r0m0/index.jsp
11-1
Student Notebook
Unit objectives
After completing this unit, you should be able to:
Create a Worklight Native API application
Configure the native application
Invoke an adapter procedure
Manage a procedure response
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
Typically, native applications do not have communication with the Worklight server. The
Worklight server is connected to the web part of an application, not to the native part. The
Worklight server is therefore not aware of the native application. However, there is now a
Worklight native API that can allow communication between the Worklight server and the
device native application. This unit looks at how this communication is achieved.
11-3
Student Notebook
WU5061.1
Notes:
There are a number of advantages to doing using native API capabilities. You have seen
already how the Worklight server can send notifications, or even disable an application.
With native API, this is possible even with native applications. You may want your native
code to communicate with server-side adapters, or use authentication on the client side.
You may also want to combine analytics with your native application.
V8.1
Student Notebook
Uempty
2.
3.
Right-click the Worklight native API folder and select Build and
Deploy
WU5061.1
Notes:
To create the Worklight native API you start with a standard Worklight project. Up to this
point, you have seen the creation of hybrid applications. This time, it is the native API that
is selected. For the next step, you need to specify an application, and to define which
environment you are using Android, iOS, or JavaME.
11-5
Student Notebook
V8.1
Student Notebook
Uempty
11-7
Student Notebook
8.0
WU5061.1
Notes:
The following slides discuss the Android native API. If your interest is in iOS, move on to
the topic entitled iOS native API.
V8.1
Student Notebook
Uempty
worklight-android.jar
A Worklight API library that must be copied
to the native Android project
WU5061.1
Notes:
This slide shows the structure of an application. The application is called
NativeAPIforAndroidApp. It includes an XML file called application descriptor, a properties
file called wlclient, and a jar file called worklight-android. The properties file and the jar file
are copied to the native Android project. The application descriptor XML file is copied to the
worklight server.
11-9
Student Notebook
WU5061.1
Notes:
wlServerProtocol
The communication protocol to the Worklight Server. Either http or https
wlServerHost
Hostname of the Worklight Server
wlServerPort
Port of the Worklight Server
wlServerContext
Context root path of the application on Worklight server
wlAppId
Application ID as defined in the application-descriptor.xml file
wlAppVersion
Application version
wlEnvironment
Target environment of the native application
11-10 Mobile Application Development with IBM Worklight V6
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V8.1
Student Notebook
Uempty
11-11
Student Notebook
WU5061.1
Notes:
There are several steps that need to be accomplished in order to configure an Android
native application. This slide summarizes the steps. On the previous slides you saw that a
native Android application is created which contains files called worklight-android.jar and
wlclient.properties. These files are copied to the native application, as shown here. You
also need to open the AndroidManifest.XML file and add three tag elements. First, you
need to add a user-permission tag for the Internet, and another user-permission for WIFI.
Then you need to add an activity tag for a UIActivity.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
WLClient is a JavaScript client library that provides access to IBM Worklight capabilities
such as initializing an application, managing sessions, retrieving information, writing to a
logger window, and much more. You use this instance to create a connection using
MyConnectListener.
This class is discussed in more detail on the following slides.
11-13
Student Notebook
MyConnectListener Android
The WLClient instance connects to a Worklight server according to
properties of the wlclient.properties file
After the connection is established, it invokes one of the methods of the
MyConnectListener class
This class must implement the WLResponseListener interface
public class MyConnectionListener implements
WLResponseListener {}
WU5061.1
Notes:
WLClient finds information about where to try and establish a connection in the properties
file wlclient. MyConnectListener provides the necessary methods once the connection is
established. The class implements the interface WLResponseListener, which defines the
methods onSuccess and onFailure used to process connection success or connection
failure.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
1. Create a WLProcedureInvocationData object with the adapter and procedure names.
2. Add the required parameters as an object array and set request options (for example:
timeout).
3. Get existing the WLClient instance and use it to invoke adapter procedure. Specify the
MyInvokeListener class instance as a parameter.
11-15
Student Notebook
WU5061.1
Notes:
The interface WLResponseListener defines only two methods, onFailure and onSuccess.
These methods are invoked in response to calls to WLClient.connect or
WLClient.invokeProcedure; in other words, user code does not call them directly, it just
defines when (and how) they should be called.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
Assuming the response is a success response, the onSuccess method is invoked and the
response is passed in as argument. The response data can be extracted using the method
getResponseText, and the view can be updated accordingly. Likewise, in the event of
failure, the onFailure method is invoked and the response object is handed in as argument.
Again, the view would be updated accordingly.
11-17
Student Notebook
V8.1
Student Notebook
Uempty
11-19
Student Notebook
8.0
WU5061.1
Notes:
The next slides discuss the same topics as the previous, but this time from the point of view
of the iOS application.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
This slide shows the structure of the application that was generated earlier in this
presentation. It includes an XML file called application descriptor, a folder called
WorklightAPI that is copied to the iOS project, and the file called worklight.plist, which is
also copied to the native iOS project. This file is discussed on the next slide.
11-21
Student Notebook
WU5061.1
Notes:
- protocol
Communication protocol to the Worklight server. Either http or https
- host
Hostname of the Worklight server
- port
- Port of the Worklight server
- wlServerContext
Context root path of the application on the Worklight server
- application id
Application ID as defined in application-descriptor.xml
- application version
The application version
V8.1
Student Notebook
Uempty
- environment
Target environment of the native application
11-23
Student Notebook
WU5061.1
Notes:
To configure a native application for iOS you must first create a new Xcode project. There
are two objects that we have already seen in the Eclipse Worklight project that need to be
copied here the WorklightAPI folder and the worklight.plist file. You copy these to the root
of your iSO application. Then there are number of libraries that you must link. These are
shown on the slide.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
The next three slides show the initializing of WLClient.
First, you create an instance of WLClient. This communicates through
WLConnectWithDelegate with the worklight server. The slide
11-25
Student Notebook
WU5061.1
Notes:
The next step in initializing the WLClient is to create a delegate that receives the response
passed back from the Worklight server. Here it is called MyConnectListener. It is through
WLDelegate that the onSuccess and onFailure methods are implemented.
These methods are discussed next.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
After wlConnectWithDelegate finishes, the onSuccess method or the onFailure method of
the supplied MyConnectListener instance is invoked. In both cases, the response object is
sent as an argument. Use this object to work with data retrieved from the server.
11-27
Student Notebook
The code requests the delegate to take care of the invocation result
WU5061.1
Notes:
In order to invoke a procedure, you need to create an object with the name of the adapter,
and the name of the procedure that you want to invoke. These pieces of information are
wrapped in a WLProcedureInvocationData object. Finally, the procedure is invoked by
using a shared instance of the WLClient and passing in the WLProcedureInvocationData
object. The invokeListener object is passed in to handle the result.
This is discussed next.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
In fact, you would probably want to check that there was something in the response before
trying to execute code in it! For example, you can add a simple test that the value of the
returned object is not nil:
if ( [response responseText] != nil) {}
11-29
Student Notebook
Checkpoint questions
1. "Defines application meta data and security configuration
Which file is this defining?
2. In an Android application, you need to add an internet permission.
Which file do you edit?
1. AndroidManifest.xml
2. application_descriptor.xml
3. worklight.properties
4. android_config.xml
3. On iOS, you have created a WLProcedureInvocationData object and
specified the adapter name. What else must be specified?
WU5061.1
Notes:
Write your answers here:
V8.1
Student Notebook
Uempty
Unit summary
Having completed this unit, you should be able to:
Create a Worklight Native API application
Configure the native application
Invoke an adapter procedure
Manage a procedure response
WU5061.1
Notes:
11-31
Student Notebook
Checkpoint answers
1. "Defines application meta data and security configuration
Which file is this defining?
application_descriptor.xml
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
References
IBM Worklight V6 documentation:
http://pic.dhe.ibm.com/infocenter/wrklight/v6r0m0/index.jsp
12-1
Student Notebook
Unit objectives
After completing this unit, you should be able to:
Describe the different authentication approaches supported by
Worklight
Use server-side APIs to secure a mobile application
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Topics
Authentication concepts and entities
Adapter-based authentication
Custom login modules
WebSphere LTPA-based authentication
WU5061.1
Notes:
12-3
Student Notebook
Authentication
Worklight entities, such as applications and adapter procedures, can
be protected from unauthorized access
Entities are protected by authentication realms
Security rules are defined by a security test that contains one or
more authentication realms.
An authentication realm defines the process to be used to
authenticate users
Each authentication realm consists of:
A Challenge Handler component on the client slide
An Authenticator: client and server components which are used to collect
credentials (e.g. login form)
A Login module: server component that receives credentials from the
authenticator, validates them and builds the user identity object
The following slides look at these entities in detail
4
WU5061.1
Notes:
The same authentication realm can be used to protect several resources.
Worklight runtime framework provides the ability to authenticate mobile application users
before access is granted to protected resources, namely: application itself or to the
information on back-end systems. Mobile applications are designed to use adapters to
access back-end systems. Mobile apps and adapters are referred as Worklight entities.
When required, an entity could be protected by defining and associating an authentication
realm with it. An authentication realm is a reference to the configuration that can be put in
place so that the Worklight runtime can enforce the checks required before access is
provided to a the mobile application entities. Once defined, an authentication realm can be
used to protect several entities.
An authentication realm definition references two other artifacts that are part of the
Worklight runtime framework, namely, authenticators and login-modules.
An authenticator can be a combination of both client and server side components. It is
essentially used to retrieve user credentials.
12-4 Mobile Application Development with IBM Worklight V6
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V8.1
Student Notebook
Uempty
12-5
Student Notebook
Authentication sequence
Client
Unauthenticated
Unauthenticated user
user tries
tries to
to
access
access the
the resource
resource protected
protected
by
by an
an authentication
authentication realm
realm
Challenge
Challenge Handler
Handler :: detects
detects
the
the challenge,
challenge, collects
collects the
the
credentials,
and
sends
credentials, and sends them
them to
to
the
the Authenticator
Authenticator
Server
The
The server
server asks
asks the
the client
client to
to
provide
provide credentials
credentials (a
(a
challenge)
challenge)
Authenticator
Authenticator collects
collects the
the user
user
credentials
credentials
IfIf the
the supplied
supplied credentials
credentials pass
pass
validation,
Login
Module
validation, Login Module
creates
creates the
the User
User Identity
Identity
object
object and
and flags
flags session
session as
as
authenticated
in
a
given
realm
authenticated in a given realm
The
The client
client application
application autoautomatically
matically resends
resends the
the request
request
Authentication
Authentication success
success
message
returned
message returned to
to user
user
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
Here is the high level flow for end-user authentication process in Worklight: The Worklight
run-time determines if a request is being made t to the protected entity, it checks whether
the session is already authenticated. If not, Worklight invokes the authenticator associated
with the authentication realm the protected resource belongs to. The authenticator collects
the user credentials sends it to the Worklight Server. The server run-time passes these
credentials to the login-module associated with the realm, which then validates them
against the configured authentication service. Once the end-user is validated, the request
is handled.
In case the user is authenticated for a entity, all subsequent requests to that entity are
handled without request for end-user credentials as far as the session is still valid.
Worklight could be configured automatically grant access to all entities protected by a
specific authentication realm.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
The challenge comes from the server. The challenge handler therefore has functions that
are called when a server responds to a client request.
12-7
Student Notebook
Authenticator
Login module
WU5061.1
Notes:
In addition to predefined authenticators, you can create your own custom authenticator by
using the Java code.
An authenticator can be designed to be either inter-active or non-interactive. Typically,
non-interactive authenticators can be just server-side implementations.
Interactive authenticator could be realized either with just server-side implementation or
with both client and server implementation. The Worklight run-time provides the server
side jsp files in order to capture user credentials.
Implementation wise, developer needs to provide the client-side authentication logic such
as building UI to gather user credentials like userid and password.
An authenticator could be customized if required. This is covered later in the course.
V8.1
Student Notebook
Uempty
Authenticator
Login module
WU5061.1
Notes:
A session may be terminated by the user logging out, or through a timeout.
Login-modules are always implemented on the server. The login-module validates user
credentials using one of several options, some of which includes accessing a web-service
or an LDAP based user registry. Once a user is authenticated, the login-module sets up a
user identity object which remains valid as long as the associated session is valid. The
contents of the user identity object are determined by the login module.
As part of the configuration that defines the login-module, it is possible to have the
Worklight runtime keep track of the number of attempts to login.
A login-module could be customized if required. This is covered later.
12-9
Student Notebook
Authenticator
Login module
WU5061.1
Notes:
Each authentication realm defined in the server authentication configuration should have a
corresponding challenge handler in the client application.
V8.1
Student Notebook
Uempty
Realm
Security test
Authenticator
Login module
10
WU5061.1
Notes:
The IBM Worklight framework provides default security tests definitions for mobile and web
environments as well as the ability to create custom security tests. There is further
discussion of this in the following slides.
12-11
Student Notebook
Security test 1
Login module 1
Realm 2
Authenticator 1
Security test 2
Login module 2
Realm 3
Authenticator 2
Security test 3
Login module 3
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
11
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Security test 1
Login module 1
Realm 2
Authenticator 1
Security test 2
Login module 2
Realm 3
Authenticator 2
Security test 3
Login module 3
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
12
WU5061.1
Notes:
12-13
Student Notebook
Security test 1
Login module 1
Realm 2
Authenticator 1
Security test 2
Login module 2
Realm 3
Authenticator 2
Security test 3
Login module 3
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
13
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Security test 1
Login module 1
Realm 2
Authenticator 1
Security test 2
Login module 2
Realm 3
Authenticator 2
Security test 3
Login module 3
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
14
WU5061.1
Notes:
12-15
Student Notebook
Defining realms
Authentication settings are configured in the
server/conf/authenticationConfig.xml file of the project
Each realm has a name, a loginModule specification, a className of
an authenticator implementation and optional parameters
WU5061.1
Notes:
The key component that holds the configuration of authentication realms is the
authenticationConfig.xml file. This file is located in the server/conf directory located in the
Worklight server home in the Worklight installation directory or in your Studio project. A
sample snippet of the contents of the authenticationConfig.xml file is shown above. You
learn the details in the coming slides.
V8.1
Student Notebook
Uempty
16
WU5061.1
Notes:
The second stanza in the authenticationConfig.xml file is the login-module. The tag
<loginModules> defines the login-modules that are setup for use of end-user
authentication. Each login module defined under the <loginModules> tag is encapsulated
in the <loginModule> tag. This tag has one mandatory attribute, name, which is a unique
name to identify the login module. This is used in defining the login module associated with
a realm. The optional audit attribute defines whether the login module usage should be
logged in the Worklight server audit.log file.
The XML sub-elements that can be specified for <loginModule> are <className> which is
the Java class name of the module and <parameter> which is meant to specify initialization
parameter for the module. The list of parameters are implementation dependent.
12-17
Student Notebook
Defining authenticators
Worklight provides several authenticators that are ready for
immediate use:
Form-based authenticator: presents a login form to the user containing
user name and password fields
Header authenticator: non-interactive, used with a Header login module
Adapter-based authenticator: fully customizable authenticator that is
implemented using the adapter. Can be used with any login module
WU5061.1
Notes:
Worklight provides several authenticators out-of-the-box the slide provides a list of these.
Each authenticator requires a different parameter to be specified as part of the
configuration in the authenticatorConfig.xml file. This has been indicated against each
authenticator listed.
The basic authenticator implements basic HTTP authentication. The <basic-realm-name>
is a string that is sent to the client as a realm name, to be presented by the browser in the
login dialog.
The form-based authenticator presents a login form to the user. The <login-page>
parameter allows a login page URL to be specified. This URL must be relative to the web
application context. The <error-page> similarly allows an error page URL to be specified.
Typically the out-of-the-box jsp files are used for these two URL parameters. In case
custom pages are used, the login form must contain fields named j_username and
j_password, and the submit action should be j_security_check. If the login fails, the user is
redirected to an error page.
V8.1
Student Notebook
Uempty
The header authenticator is not interactive. The header authenticator must be used with
the Header login module.
The persistent cookie authenticator looks for a specific cookie in any request that is sent to
it. If the request doesnt contain the cookie, the authenticator creates a new cookie, and
sends it in the response. This authenticator is not interactive, that is, it doesnt ask the user
for credentials, and is mainly used in environment realms. The <cookie-name> parameter
allows the name of the persistent cookie to be specified. The default <cookie-name> is
WL_PERSISTENT_COOKIE.
The Adapter authenticator enables you developing custom authentication logic in
JavaScript within an adapter. This is mostly useful for multi-step login processes that
cannot be implemented by merely configuring the authenticators defined above. This
authenticator can be used with any login module. The parameters allow the login and
logout functions to be specified.
In case of interactive authenticators, the client side auth.js must be defined appropriately.
12-19
Student Notebook
18
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
12-21
Student Notebook
webSecurityTest
The webSecurityTest is used to protect web applications
By default the webSecurityTest includes a protection against XSRF
attacks
See the IBM Worklight Info Center for details on this
WU5061.1
Notes:
Cross-site request forgery (XSRF) attacks occur when an unauthorized command seems
to be sent from a browser that the website trusts. For example, the browser is pointed to a
malicious site, which responds with an HTML page that silently retrieves banking
information from a cookie on the browser, then calls the bank using the genuine users
identity information.
V8.1
Student Notebook
Uempty
mobileSecurityTest
The mobileSecurityTest is used to protect mobile applications
By default the mobileSecurityTest includes:
A protection against XSRF attacks
An application authenticity test
For more information on both of these, see the IBM Worklight Info Center
The ability to remotely disable mobile application from the Worklight console
WU5061.1
Notes:
12-23
Student Notebook
customSecurityTest
The customSecurityTest defines custom security preferences
The developer defines realms
WU5061.1
Notes:
The developer decides what security preferences are associated with the test. The order in
which tests are applied can be set by the test attribute step. If there is no property given,
all tests are executed as a single step. Two other attributes can be defined: isInternalUserId
and isInternalDeviceId. The isInternalUserID attribute indicates that the test realm is
applied for reporting and push subscriptions as a user identification. the isInternalDeviceID
attribute indicates that the realm is used for device identification in reporting, push
subscriptions, and device single sign on.
V8.1
Student Notebook
Uempty
Protecting adapters
Authentication is required when the adapter procedure is invoked
A separate securityTest can be defined for each adapter procedure in
the adapter XML file
WU5061.1
Notes:
The authentication realm that is to be used to protect an adapter procedures needs to be
specified in the adapter's declaration XML file as a attribute to the <adapter> tag. The n
attribute is securityTest. See the slide for an example of an adapter XML file with the
attribute specified.
12-25
Student Notebook
Protecting applications
Authentication is required immediately when an application connects
to the Worklight server
A separate securityTest can be defined for each application
environment
WU5061.1
Notes:
Mobile applications can be configured in three ways with respect to protection from user
access:
- In case the application uses data that is publicly available and this data is modified
just for a specific user without impacting others, then such mobile applications can
be configured with no protection at all.
- In case the application displays user sensitive information and allows actions that
permanently impact user data, then such mobile applications can be configured to
be protected upon startup.
- In case the mobile application can start with needing protection but at some point,
based on usage, results in an attempt to access or modify user sensitive
information, then such mobile applications can be configured to be protected on
demand. In such cases, the user is required to provide credentials only when
required by the application.
V8.1
Student Notebook
Uempty
12-27
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
12.1.Adapter-based authentication
12-29
Student Notebook
Adapter-based
authentication
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Adapter-based authentication
Adapter-based authentication is the most flexible type to implement
With adapter-based authentication, the entire authentication logic,
including the credentials validation, can be implemented in
JavaScript in an adapter
Any login module can be used in the adapter-based authentication as
an additional authentication layer
In this unit, a simple username/password adapter-based authentication
mechanism is described
WU5061.1
Notes:
Among various choices Worklight authentication framework provides, Adapter based
authentication is probably the easiest one to implement, but it contains all the features and
benefits of the Worklight server authentication framework.
Adapter based authentication provides a flexible framework to authenticate users. Its entire
logic, including gathering user credentials and validate against user repository for the
credential, can be implemented in an adapter, using using plain JavaScript without writing
custom login modules in Java. This simplifies the implementation and speeds up the
development.
Still, if you have complex or custom login logic, you can easily integrate with Adapter based
authentication framework by providing it a custom login module as an additional
authentication layer.
The remaining discussion for adapter based authentication illustrates implementing a
simple username and password adapter based authentication.
12-31
Student Notebook
YES
NO
Authentication process
YES
Success
NO
WU5061.1
Notes:
Before diving into the implementation, it is important to understand how Worklight handles
the authentication process for adapter based authentication.
The process starts with a request made to a protected resource, such as invoking a
protected adapter procedure from a mobile client. Worklight server checks whether user is
already authenticated using techniques such as persistent cookie. If user is already
authenticated, allow user to access protected resource, business logic is executed.
If not, authentication process is started. The calling application such as mobile client
receives a response that contains authentication required. Then, the client and side
component engages in authentication process such as providing user credential and
validate username and password until the process success. Then, Worklight grant the
access to invoked Worklight resource, business logic is executed.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
Under the new SingleStepAuthRealm definition, specify a Worklight built-in authenticator
used for adapter based authentication for Worklight server. This component is defined by a
className element with value com.worklight.integration.auth.AdapterAuthenticator. This
component is a Java class that provides adapter based authenticator.
Define two parameters for SingleStepAuthRealm. There parameters specify the adapter
which provides the authentication implementation and also defines the mapping of login
and logout function to the adapter procedures. The SingleStepAuthRealm uses an adapter
named SimpleAuthAdapter to implement the login and logout function, through its
procedures onAuthRequired and onLogout.
When the Worklight authentication framework detects an attempt to access a protected
resource, an adapter function that is defined in a login-function parameter is invoked
automatically. When logout is detected (explicit or session timeout), a logout function is
invoked automatically. In both cases, the parameter value syntax is
adapterName.functionName.
12-33
Student Notebook
WU5061.1
Notes:
Now you have the realm and authenticator defined, need to add the definition loginModule
used by SimpleAuthRealm.
Worklight login module is defined with a LoginModule element under loginModules section
in authenticationConfig.xml file.
The className element specifies how the login is handled, this component normally is a
JavaClass either provided by Worklight out-of-the-box or a custom built one.
The built in loginModule com.worklight.core.auth.ext.NonValidatingLoginModule is used in
the example on the slide.
Because all authentication-related actions are done in the adapter code, using
NonValidatingLoginModule is a mandatory requirement for adapter-based
authentication.
V8.1
Student Notebook
Uempty
Configuring authenticationConfig.xml
Add a security test to the <securityTests> section of the
authenticationConfig.xml file
This security test is used to protect the adapter procedure, therefore it
is a <customSecurityTest>
Remember the security test name: you see it in the following slides
WU5061.1
Notes:
12-35
Student Notebook
Application
Authentication is required
Worklight
Server
submitAuthentication
You are authenticated now
getSecretData
Here is your secret data
WU5061.1
Notes:
What happens for the sample app is illustrated in the diagram here, following the
authentication process discussed earlier.
The mobile application invokes the protected getSecretData procedure for the first time.
Worklight detects that the user is not authenticated, it send an authentication required
message back to the client. A client side component such a custom login form asks the
user to input username and password, then the client code invokes adapter procedure
submitAuthentication and pass in username and password.
Once Adapter receives valid username password and validate them successfully, it marks
user authenticated and creates a user object in session. This returns back to the client
code, it can completes the invocation for the getSecretData procedure and gets the data
needed from backend adapter.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
Functions are made publicly visible in an adapter by defining a procedure tag in the
configuration. There are two forms of the tag: either the function can be directly accessed
(only its name is listed), or it requires the user to be logged in (its name is listed together
with a securityTest). An unauthenticated user who sends a request to the requestForData
function is redirected to an authentication mechanism. An authenticated user is able to
access both of the functions.
12-37
Student Notebook
WU5061.1
Notes:
The returned JSON information is a custom Authentication is required object.
Here is a break down of the flow into implementation detail.
In the first step the Worklight framework detects an unauthenticated attempt at access to a
protected resource. The framework therefore invokes the adapter onAuthRequired function
(as previously set up in authenticationConfig.xml).
This function receives response headers and an optional errorMessage parameter. The
object returned by this function is sent to the client application.
In the return message, the property authRequired:true is critical because client
authentication code uses this attribute to launch the login procedure.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
The second implementation in the adapter is the actual procedure that receives the
username and password supplied by the user, and validates them against a user registry to
complete the authentication process. This procedure is invoked by the client side
authentication logic.
Note that for simplicity the conditional logic is hardcoded in the example on the slide. In a
real-world implementation, you need to provide a validation implementation, such as
validating against database or invoking a web service to validate the login credentials.
If validation is successful, the WL.Server.setActiveUser API is called to create an
authenticated session for the realm with user data stored in a userIdentity object. Note that
you can add your own custom properties to the user identity attributes. An object is
returned to the application stating that the authentication screen is no longer required
(authRequired:false).
If validation fails, onAuthRequired is invoked to create an object that is returned to the
application with an error message.
12-39
Student Notebook
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
Finally, when authentication process completes successfully, the client application can
invoke the protected adapter procedure getSecretData just as any other procedure.
In the same adapter, you can implement the logout function via the onLogout procedure.
For example, destroying a user object or writing a log message.
12-41
Student Notebook
WU5061.1
Notes:
For this simple application, a custom login form is built that captures user name and
password. This is wrapped in an AuthDiv HTML element.
The AppDiv represents the application user interface. When authentication is required, the
application hides the AppDiv and shows the AuthDiv. When authentication is complete, it
does the opposite. Buttons are used to invoke the getSecretData procedure and log out.
<div id=ResponseDiv> is used to display the getSecretData response.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
The AuthDiv provides text fields for the user to enter the values required by the
authentication mechanism in this case, a simple id and password combination. Typically,
when the Submit button is clicked, there would be client-side JavaScript to verify that there
is some information in the fields, and that it is of the correct format (for example, it only
includes the characters that make up a decimal number, in a field used to enter a money
value).
12-43
Student Notebook
WU5061.1
Notes:
The isCustomResponse function of the challenge handler is called each time a response is
received from the server. It is used to detect whether the response contains data that is
related to this challenge handler. It returns true or false.
If isCustomResponse returns true, the framework calls the handleChallenge() function.
This function is used to perform required actions, for example, hide the application screen
and show the login screen.
V8.1
Student Notebook
Uempty
myChallengeHandler.submitSuccess()
Notifies the Worklight framework that the authentication finished successfully
The Worklight framework then automatically issues the original request that
triggered the authentication
myChallengeHandler.submitFailure()
Notifies the Worklight framework that the authentication completed with failure
The Worklight framework then destroys the original request that triggered the
authentication
WU5061.1
Notes:
You see these functions used for the implementation of the challenge handler further on.
12-45
Student Notebook
WU5061.1
Notes:
The authRequired property was defined in the adapter JavaScript implementation. It is
used here
to determine whether authentication is required or not. The function returns true if the
authRequired
property is found, otherwise it returns false.
The function also checks whether the response is in a format that can be understood by the
condition that looks at the value of authRequired. If not, it is assumed that authentication is
not required.
From this, you can see that if authentication is required the adapter must return a clear
authRequired statement to the application.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
The view is switched according to whether authentication is required or not. If
authRequired is true, it shows the login screen, empties the password field and AuthInfo,
and shows an errorMessage (if present).
If the authRequired is false, it hides AuthDiv and shows AppDiv, and it notifies the Worklight
framework that the authentication completed successfully.
12-47
Student Notebook
WU5061.1
Notes:
There is no need to specify the callbacks because the response is checked by the
Worklight framework.
V8.1
Student Notebook
Uempty
12-49
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
12-51
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Configuring authenticationConfig.xml (1 of 2)
Add authentication information to the authenticationConfig.xml
Define a new realm called CustomAuthenticatorRealm.
Define its login module as CustomLoginModule
WU5061.1
Notes:
Again, all authentication is defined under server/conf/authenticationConfig.xml file.
In here, you create a new authentication realm CustomAuthenticationRealm and make
sure that this realm uses CustomLoginModule.
Unlike the adapter based authentication, this realm uses a custom Java implementation as
authenticator, this is defined under the className section of the realm.
Then in the loginModule definition, again, specify the custom implementation Java class
name in the className section as shown in the slide.
12-53
Student Notebook
Configuring authenticationConfig.xml (2 of 2)
Add a new security test in authenticationConfig.xml
This security test is used to protect the adapter procedure, therefore it
is defined as <customSecurityTest>
WU5061.1
Notes:
The LoginModule is referenced in the realm definition, then the realm definition serves to
built a securityTest definition.
Note the security test name. It is used in the following slides.
V8.1
Student Notebook
Uempty
Authenticator API (1 of 2)
Here is a summary of the Authenticator API:
void init(Map<String, String> options)
AuthenticationResult processRequest(HttpServletRequest request,
HttpServletResponse response, boolean isAccessToProtectedResource)
AuthenticationResult processAuthenticationFailure(HttpServletRequest
request, HttpServletResponse response, String errorMessage)
AuthenticationResult processRequestAlreadyAuthenticated
(HttpServletRequest request, HttpServletResponse response)
WU5061.1
Notes:
The init() method is invoked when an Authenticator instance is created. It is passed the
options map specified in realm definition in the authenticationConfig.xml.
processRequest () is invoked for each request from an unauthenticated session.
processAuthenticationFailure() is invoked when the login module returns a credentials
validation failure.
processRequestAlreadyAuthenticated() is invoked for each request from a session that
has already been authenticated.
12-55
Student Notebook
Authenticator API (2 of 2)
Map<String, Object> getAuthenticationData()
HttpServletRequest getRequestToProceed(HttpServletRequest request,
HttpServletResponse response, UserIdentity userIdentity, LoginExtension...
loginExtension)
WU5061.1
Notes:
getAuthenticationData() is used by a login module to get credentials collected by an
Authenticator.
getRequestToProceed() is invoked after a login module successfully validates credentials
collected by an Authenticator.
The changeResponseOnSuccess() method is called after authentication success. It is used
to add data to the response after the authentication is successful.
clone() creates a deep copy of class members.
V8.1
Student Notebook
Uempty
private
private Map<String,
Map<String, Object>
Object> authenticationData
authenticationData == null
null ;;
WU5061.1
Notes:
The authenticator Java class you write must implement the interface
com.worklight.server.auth.api.WorklightAuthenticator. This interface defines the signatures
for the methods you have seen: getRequestToProceed, processRequest, and so on. It
extends java.lang.Cloneable, and therefore you can create deep copies of authentication
objects.
12-57
Student Notebook
WU5061.1
Notes:
Unless you have other servers on your system, you only see one option for the server
runtime: Worklight Development Server, the Worklight Server that is installed as a part of
your Worklight plug-in.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
There are several key methods your custom authenticator needs to implement. Here is a
look at some of the core APIs.
The first is the init() method of Authenticator that is invoked when Authenticator instance is
created. It receives options map specified in realm definition in the
authenticationConfig.xml
Clone is a routine Java method to create a deep copy of the members of a class.
12-59
Student Notebook
WU5061.1
Notes:
This slide is intended to give an overview of the code. The following slides show this same
code, broken into smaller pieces, and discussed in detail.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
The processRequest() method is invoked for each request from an unauthenticated
session. This method is called by Worklight server side authentication framework.
This is where you can add logic to gather credential and decide whether to invoke the
custom login module.
The Authenticator collects the credentials for a login module; it does not validate them.
12-61
Student Notebook
if (request.getRequestURI().contains(
"my_custom_auth_request_url")) {
String username = request.getParameter("username");
String password = request.getParameter("password");
WU5061.1
Notes:
The String is not in itself any particular URL; it does not even have to be a URL. Its use is
simply to verify that the request did come from a given client.
It is recommended to have a different URL component in every Authenticator.
V8.1
Student Notebook
Uempty
HashMap<String, Object>();
WU5061.1
Notes:
Basic validity is here a simple check that the arguments exist and have some content. You
can expand this to verify whether the format of the argument is correct, or whether it falls
within a certain range, and so on, but this would be better done on the client side, before
the call is made to the server. Assuming some client side JavaScript has determined that
the arguments are correctly formatted, the Authenticator need only do basic checking in
order to avoid potential Java problems with nulls.
SUCCESS is a static final field defined in the AuthenticationStatus class. It indicates that
all the login data was received correctly. If this were not the case then FAILURE would be
returned, indicating that the client did not provide correct login data.
Note that in previous versions this was returned directly as return
AuthenticationResult.STATUS. From Worklight version 5.0.6 this was changed to an
indirect call, and the STATUS values were placed in a separate class.
12-63
Student Notebook
The code on the slide shows how the argument values are gathered into a HashMap.
Remember that this is only a successful collection of credentials; the login module is
invoked to validate them.
V8.1
Student Notebook
Uempty
} else {
response.setContentType("application/json; charset=UTF-8");
response.setHeader(
"Cache-Control", "no-cache, must-revalidate");
response.getWriter().print(
"{\"authRequired\":true, \"errorMessage\":"
+ "\"Please enter username and password\"}");
return AuthenticationResult.createFrom(
AuthenticationStatus.CLIENT_INTERACTION_REQUIRED);
}
WU5061.1
Notes:
The comments on the previous slide about the AuthenticationStatus class apply here also.
CLIENT_INTERACTION_REQUIRED indicates that the request cannot be fulfilled until the
client has provided credentials for authentication.
12-65
Student Notebook
if (!isAccessToProtectedResource)
return AuthenticationResult.REQUEST_NOT_RECOGNIZED;
WU5061.1
Notes:
See the comments on the previous two slides about AuthenticationResult.
The value of isAccessToProtectedResource was passed in as the third argument to the
method. A value of false indicates that the resource does not have security protection
and therefore Authenticator treatment is not required. Worklight can process the
request without user credentials.
V8.1
Student Notebook
Uempty
response.setContentType("application/json; charset=UTF-8");
response.setHeader(
"Cache-Control", "no-cache, must-revalidate");
response.getWriter().print(
"{\"authRequired\":true, \"errorMessage\":"
+ "\"Please enter username and password\"}");
return AuthenticationResult.CLIENT_INTERACTION_REQUIRED;
}
WU5061.1
Notes:
This situation is similar to what you saw two slides ago. On that previous slide, the check
on the URL returned true and the credentials were formatted correctly, but then something
was incorrect and therefore the request was returned to the client. This slide shows that the
same situation arises if the check on the URL returned false, but the request is for a
protected resource.
12-67
Student Notebook
WU5061.1
Notes:
The init() method is invoked when Login Module instance is created. It receives the
options map specified in login module definition of the authenticationConfig.xml.
The login() method is used to validate credentials collected by the Authenticator.
The createIdentity () method is used to create a userIdentity object once credential
validation succeeds.
The logout() and abort() methods are used to clean up cached data once logout or
authentication abort occur.
The clone() method is used to create a deep copy of class members.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
In previous versions of Worklight the interface implemented by the login module was
WorklightLoginModule.
12-69
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
The authenticationData HashMap that was created in the Authenticator is passed to this
method (see the previous slide processRequest: authenticationData object).
The coding is reduced to a minimum here for the demonstration. You need to provide
try/catch blocks in case there is a problem extracting the values from the map, and of
course the validation of the values would be much more complex! You can implement your
own validation rules. The method returns true if the credentials are valid.
In the case of credential validation failure, the login() method throws a RuntimeException
with text that is returned to Authenticator as an errorMessage parameter.
12-71
Student Notebook
WU5061.1
Notes:
You can store you own custom attributes in the Useridentity to use later in Java or adapter
code.
The UserIdentity object constructor is passed six pieces of information:
1. loginModule (the String passed in to the method) indicates the name to set the user for
2. USERNAME is a unique identifier for the user
3. The third value is a display name, which may not be the same as the username
4. The fourth value is a String Set of Java security roles associated with the user
5. customAttributes has been created and populated in this method
6. The last argument is self-evident!
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
12-73
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
12-75
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
Both of these options are discussed in the following slides.
12-77
Student Notebook
YES
Worklight
checks user authentication:
LTPA token?
Protected
Protected resource
resource access
access is
is
granted.
granted. Application
Application receives
receives
the
the requested
requested data
data
NO
Authentication
Authentication process
process starts.
starts.
Application
Application receives
receives the
the
authentication
required
message
authentication required message
Authentication
Authentication process
process
Set
Set LTPA
LTPA
token
token as
as
HTTP
HTTP
Cookie
Cookie
YES
Success?
NO
WU5061.1
Notes:
You can recognize this flow chart from earlier in the unit during the discussion of the
Adapter-based authentication process. The main difference here is that once the
authentication process has completed successfully an LTPA token is set as a cookie.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
If the application server security mechanism validates the provided credentials, it creates
an LTPA token as was shown on the previous slide. Upon subsequent access, this LTPA
token is used, thus avoiding a challenge on each request.
12-79
Student Notebook
The user provides user name and password on initial login, then this
data is used to authenticate the user against the underlying registry
that the application server is configured against
WU5061.1
Notes:
If the enterprise policy requires WAR files to be protected on secured application servers,
then this option can be used to handle the situation.
The pros and cons of these two options are discussed in the following slides.
V8.1
Student Notebook
Uempty
Authentication is enforced by
WebSphere Application server
WebSphere
Application
Server
User
Registry
WebSphere
Application
Server
User
Registry
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
12-81
Student Notebook
Worklight
Server
getSecretData
Authentication required by Worklight server
Application
submitAuthentication
Authentication successful, LTPA set
getSecretData (passing in LTPA)
Secret data returned to application
WU5061.1
Notes:
Worklight invokes WebSphere Application Server security by using the loginmodule to
authenticate the user against the User Registry of WebSphere Application Server. This was
the first option discussed previously.
V8.1
Student Notebook
Uempty
Worklight
Server
getSecretData
Authentication required by app.server
Application
submitAuthentication
Authentication successful, LTPA set
WebSphere
Application
Server
WU5061.1
Notes:
WebSphere Application Server authenticates the user against the User Registry. Based on
successful authentication, Worklight loginmodule sets the Worklight user and provides an
LTPA token. On the subsequent request to get the secret data, this token is passed back to
the server, which recognizes that the user is authenticated and responds with the
requested information.
This was the second option discussed previously.
12-83
Student Notebook
Application server
Benefits
Usage
WU5061.1
Notes:
The multi-step authenticity checking that is built into IBM Worklight platform ensures denial
of services to jail-broken devices, rogue applications, and unauthorized users.
In general, it is preferable to use Worklight to enforce the security, unless there is a
business policy that requires the application server to be responsible for security.
V8.1
Student Notebook
Uempty
Checkpoint
1.
The server component that receives credentials from the authenticator, validates
them and builds the user identity object is
A. The authentication realm
B. A basic web form
C. The LTPA token
D. The login module
2.
3.
True or False:
Any login module can be used in the adapter-based authentication as an
additional authentication layer
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
Write your answers here:
12-85
Student Notebook
Unit summary
Having completed this unit, you should be able to:
Describe the different authentication approaches supported by
Worklight
Use server-side APIs to secure a mobile application
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Checkpoint answers
1. D. The login module
2. A. authenticationConfig.xml
3. True
WU5061.1
Notes:
12-87
Student Notebook
V8.1
Student Notebook
Uempty
References
IBM Worklight V6 documentation:
http://pic.dhe.ibm.com/infocenter/wrklight/v6r0m0/index.jsp
13-1
Student Notebook
Unit objectives
After completing this unit, you should be able to:
Describe push notification architecture and API
Create an application that uses push notifications
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
Push notification allows to push the message directly to the device from a server. It is a
short message sent by an application that is installed in the device. The information could
be a message, an impending calendar event, or new data on a remote server. Often the
size and number of such messages varies by Platform (iOS, Android, BlackBerry,
Windows Phone)
Until such Push notifications are turned off, the applications continue to receive them
irrespective of the state of the application whether it is running in foreground ,background
or even when it is not running.
Push notifications can be sent in any form. A pop-up Alert, a small badge that appears
next to the application icon, a sound alert are some of the forms that are widely used.
Some of the leading mobile platforms such as Android and iPhone provide centralized
management interface for Push Notification where device users can manage the
subscriptions, turn on and off notification for apps, configure how to be notified and other
notification configurations.
13-3
Student Notebook
All the Push Notifications messaged are delivered to this central place and furthered
handled from here.
this component is normally referred to as Notification center. The screen shots show the
notification configuration on both Android and iPhone.
V8.1
Student Notebook
Uempty
Device support
Worklight supports push notifications for mobile platforms:
Android 2.2 or later
iOS
Windows Phone 8
WU5061.1
Notes:
Currently Worklight supports push notifications for iOS and Android version 2.2 or later
mobile platforms.
Android device users must have a valid Google account set up in order to subscribe to the
push notification requests with GCM service.
13-5
Student Notebook
Device token
A unique identifier, obtained from the push mediator (Google or Apple), which identifies the
request of a specific mobile device to receive notifications from the Worklight server.
User ID
A unique identifier for a Worklight user. Obtained through authentication or other unique identifier
such as a persistent cookie.
Application ID
Worklight application ID that dentifies a specific Worklight application on the mobile market.
WU5061.1
Notes:
There are 4 important terms needed in order to understand Worklight push notification
implementation.
First, Event Source It is a push notification channel that the applications can register to.
For developers know traditional messaging put/sub programming model, Worklight event
source is similar as Topic in sub/pub. Event source is normally defined within a Worklight
Adapter.
Device Token It is a unique identifier supplied by the push mediators (such as APN or
GCM) which uniquely identifies a device. Worklight server maintains the device token with
associated user information so that device token can be provided to the push mediators to
send message to the target device.
Userid is a unique identifier for a Worklight user. Often, userid is obtained via Worklight
authentication such as creating user object or via other techniques like persistent cookie.
Finally, application ID Identifies a specific Worklight application on the mobile market such
as Apple App store or Google Play.
13-6 Mobile Application Development with IBM Worklight V6
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
Push notification starts with device subscribes to an event source. This process also know
as Subscription.
Event Source is declared in the Worklight Adapter and maintained by Worklight server to
allow application to subscribe to this event source. Worklight provides API to create an
event source. You will learn about APIs in coming slides.
Before server or service provider can send any notification to a user. It must first obtain
users approval whether allows push notification for this application or not.
After the user approves push notification, the device registers with Apple/Google push
server to obtains a token, which is used to identify the device and sends a subscription
request to the Worklight Server all this is performed automatically by the Worklight
framework via the client side unified API in JavaScript.
Worklight Server, in turn, stores the device token information in database along with user
information.
13-7
Student Notebook
Push services
mediators
Worklight
adapter
event source
WU5061.1
Notes:
The diagram here further explains the push notification subscription process.
When a user initiates the subscription using Worklight Client side push notification API, the
device registers itself with the Push Service Mediators (APN, GSM) and a device token is
obtained.
V8.1
Student Notebook
Uempty
Worklight
adapter
event source
WU5061.1
Notes:
Once a device token is obtained, Worklight client side API then automatically forwards the
device token to backend Worklight server to register to an event source thats defined in an
Adapter. This process also saves the device token to the Worklight repository.
Again, this process and previous step are all done via the Worklight unified API.
13-9
Student Notebook
WU5061.1
Notes:
Now, lets review the process of sending a push notification in Worklight.
Again, You will use the Worklight supplied push APIs to send a notification irrespective of
the mobile platforms that the target devices belong to. The APIs for sending notification
consists of client and server side.
On the server side, Worklight push API allows developer to managing subscriptions such
as getting subscription detail including user name and device token. The API allows your
application to use either Pushing or polling mechanism to get the message or initiate the
push notification from back-end enterprise system.
On the client side, besides subscribing and unsubscribing push notification as we
discussed previously, developer can define how to handling the arriving notification and
retrieve notification data using the client side push API.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
Message or attempt to send a message to mobile users have to be retrieved or initiated
from backend-enterprise system. For example, a transaction complete statement or system
admin wants to send a message some users via an admin program.
Worklight Event Sources defined within the Adapter can either pull the messages or wait
for the back end systems to push the messages.
On receiving the messages, Worklight push notification APIs will send it to the platform
specific push service mediators such as APN or GCM using the supported transmission
protocols.
Additionally, you can add any pre-processing logic in the Adapter before sending the
notification such as write an audit entry about the notification, process the notification
message payload etc..
13-11
Student Notebook
Sending notifications (1 of 4)
1. Notifications are retrieved by the
Worklight adapter event source either by
poll or push from the back end
Back end
Push services
mediators
Enterprise
data source
Worklight
adapter
event source
WU5061.1
Notes:
In step Notifications are retrieved by the Worklight adapters event source by either poll or
push from the back end Enterprise Data source.
V8.1
Student Notebook
Uempty
Sending notifications (2 of 4)
2. A Worklight adapter processes the
notification and sends it to a push
services mediator
Back end
Push services
mediators
Enterprise
data source
Worklight
adapter
event source
WU5061.1
Notes:
Step 2, Adapter processes that information and sends it to push service mediators using
Worklight unified push API. In this case, server side push API.
13-13
Student Notebook
Sending notifications (3 of 4)
3. The push service mediator sends a push
notification to the device
Back end
Push services
mediators
2
3*
Enterprise
data source
Worklight
adapter
event source
WU5061.1
Notes:
Step 3, Push service mediators such as Apple APN or Google GCM sends the notification
to the device. At the point, the process is actually taking place at those cloud service
provider end. Worklight has little control the message delivery.
V8.1
Student Notebook
Uempty
Sending notifications (4 of 4)
4*
4. The device processes the received
notification
Back end
Push services
mediators
2
3
Enterprise
data source
Worklight
adapter
event source
WU5061.1
Notes:
Last step, step 4, notification is delivered to the device. Any client side notification handler
registered during subscription time will be fired at this time, by the Worklight unified push
API, client side API.
This completes a notification delivery using Worklight push notification framework.
13-15
Student Notebook
Creation
The user subscription for an event source is created when the user subscribes to that event
source for the first time from any device
Deletion
A user subscription is deleted when the user unsubscribes from that event source from all of his
or her devices
Notification
As long as the user subscription exists, the Worklight server can produce push notifications for
the subscribed user. These notifications can be delivered by the adapters code to all or some of
the devices the user has subscribed from
WU5061.1
Notes:
Worklight push notification allows applications to easily manage notification subscription
using a set of built-in API both on client and server side.
In Worklight, subscription is represented as a User Subscription object that contains
user ID, device ID and event source ID. It represents the intent of the user to receive
notification from a specific event source.
Worklight allows application to manage the lifecycle of a subscription. A subscription is
created when the user subscribes to that event source for the first time from any device.
User or application can delete or unsubscribe from an event source using Worklight API.
As far as the user subscription existing, the Worklight server can produce push notifications
for the subscribed user. These notifications can be delivered by the adapters code to all or
some of the devices the user has subscribed from.
V8.1
Student Notebook
Uempty
User subscription
Device
subscription
Device
subscription
Event source
WU5061.1
Notes:
13-17
Student Notebook
WU5061.1
Notes:
If you recall, Worklight push notification starts with creation of an event source. You can
easily create an event source in Adapters JavaScript code on a global level using API:
WL.Server.createEventSource .
This API takes three parameters:
name name of the event source that the device user will subscribe to.
OnDeviceSubscribe An adapter function that will be invoked when a subscription
request from mobile device is received.
OnDeviceUnsubscribe An adapter function that will be invoked when a unsubscribe
request is received.
V8.1
Student Notebook
Uempty
Poll: a method used for notification retrieval. The following parameters are
required:
Interval: polling interval in seconds
onPoll: polling implementation an adapter function to be invoked at specified intervals
WU5061.1
Notes:
To implement the polling notification, or poll the request to send a notification from backend
enterprise system,
You need to specify a poll property as an optional parameter when creating event source.
It has two additional parameters, interval and onPoll.
interval Mandatory. The interval in seconds between the polls
onPoll Mandatory. The name of JavaScript function which is called on each poll
13-19
Student Notebook
In this example, a
submitNotifications()
adapter function is invoked
by a back end service as an
external API to send
notifications
WU5061.1
Notes:
As discussed before, notifications can either be polled from the back end or pushed by the
back end. In this example, a submitNotifications() adapter function is invoked by a back
end service as an external API to send notifications.
V8.1
Student Notebook
Uempty
The submitNotification()
function receives a userId
to send notification to, and
the notificationText.
WU5061.1
Notes:
The submitNotification() function receives a userId to send notification to, and the
notificationText. These arguments are provided by a back end service, which invokes this
function.
Before sending notification to push mediator such as APN or GCM, its developers
responsibility to obtain the notification data such as message text.
You can get the necessary data from the backend system either by using Push
mechanism or Pull mechanism.
13-21
Student Notebook
WU5061.1
Notes:
Notification has to be sent to a specific user subscription which contains the important
information device token that the push mediator uses to locate the physical device. So, you
need to get that information before sending notification.
Worklight provide a simple API to do that. You call
WL.Server.getUserNotificationSubscription by passing the event source and userId.
This call returns a subscription object for the user with the specified ID subscribed to event
source passed as parameter.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
If the user has no subscriptions, the API will return a null object. You can use this
information to decide whether you need to send notification to a user.
13-23
Student Notebook
WU5061.1
Notes:
There are cases that a user may have multiple devices. For example, one user owns both
iPhone and iPad. In case you want to know about these devices or send notification to only
some of the devices, Worklight allows to call userSubscription.getDeviceSubscriptions()
The method returns an array of the device subscriptions. The device subscriptions contain
the device token, the application ID, the platform, and the options passed by the client in
the subscribe call.
V8.1
Student Notebook
Uempty
Payload
Badge number
Text to be pushed to the device
Copyright IBM Corporation 2013
WU5061.1
Notes:
Finally, the core of Worklight push notification is sending the notification.
WL.Server.createDefaultNotification API creates and returns a default notification JSON
block for the supplied values.
notificationText: the text to be pushed to the device.
Badge number that will be displayed on the application icon or tile (in environments that
support it.
Payload is a JSON object that is transferred to the application and that can contain custom
properties.
13-25
Student Notebook
WL.Server.notifyAllDevices
API sends notification to all
the devices that are
subscribed to the user.
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
Depending on usage scenarios, you can use different Worklight APIs to send notifications.
WL.Server.notifyAllDevices is used to submit a notification to all the device subscriptions of
the given user.
WL.Server.notifyDevice is used to submit a notification to the specified user with the
specified device ID.
WL.Server.notifyDeviceSubscription is used to submit notification to the specified device
of a subscribed user
13-27
Student Notebook
WU5061.1
Notes:
Now let us discuss about the Client Side Push notification APIs.
An application has to register itself to an event source to start subscribing for notifications.
Registering to an event source is handled by a client side API
WL.Client.Push.registerEventSourceCallback which specifies the event source, adapter
implementation and a register callback function.
The registration process can be managed by Worklight internal object
WL.Client.Push.onReadyToSubscribe. You need to define this function at a global
JavaScript level.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
The registration process can be managed by Worklight internal object
WL.Client.Push.onReadyToSubscribe. You need to define this function at a global
JavaScript level.
13-29
Student Notebook
WU5061.1
Notes:
An user must be authenticated in order to use Worklight push notification since Worklight
serve ties the subscription information to a particularly identified user.
After user is authenticated and event source registration completed, application can now
allow users to subscribe or unsubscribe to the event source.
You do this using the API WL.Client.Push.Subscribe. It takes two parameters.
:
First, the alias is mandatory field representing The event source, as defined in the API
WL.Client.Push.registerEventSourceCallback.
onFailure - A JavaScript function is called when a registration fails. The default value is a
function that prints to the log the failure reason.
onSuccess - A JavaScript function is called when a registration succeeds. Default value is
an empty function
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
WL.Client.Push.unsubscribe is used to unsubscribe to receive push notification.
Similar as Subscribe call, this API passes the alias as a mandatory parameter. This is the
event source defined in WL.Client.Push.registerEventSourceCallback API we
discussed earlier.
Then, you define the unsubscribe success and failure handling callback functions.
Besides subscribe and unsubscribe, there are couple of other useful APIs that you can
leverage to manage and get status of the application subscription.
WL.Client.Push.isPushSupported returns true if the Worklight JavaScript API supports
push notifications in the current environment and false otherwise. You can use this API to
check the device and environment support for push notification.
WL.Client.Push.isSubscribed returns whether the currently logged in user is subscribed
to the specified event source.
13-31
Student Notebook
V8.1
Student Notebook
Uempty
Setup: Android
To send push notifications to Android devices, you must use Android
Google Cloud Messaging (GCM)
You need a valid Gmail account to register to Googles GCM. To get a
GCM key and senderId, refer to:
http://developer.android.com/guide/google/gcm/gs.html
WU5061.1
Notes:
Android push notification is sent and managed via Google Could-to-Device messaging
GCM.
You need to use a valid Gmail account to register to the Google Cloud Messaging system.
This is used by Worklight server to communicate with GCM provider. It is recommended to
use your organization or company Gmail account instead of a personal Gmail account.
On iOS side, The push notification service for iOS is provided via Apple Push Notification
Service. To send the notification, you need to be to a registered Apple iOS developer and
request a APNS certificate.
From Worklight server configuration perspective, loginExtension parameter must be added
to an authentication realm protecting the application that uses push notifications.
13-33
Student Notebook
Setup: iOS
To send push notifications to iOS devices, you must use Apple Push Notifications
Service (APNS).
You must be a registered Apple iOS Developer in order to obtain an Apple APNS
certificate for your application. An APNS certificate must have a non-blank
password.
Rename you certificate file to apns-certificate-sandbox.p12 and put it in the application root
folder.
When you are in development, rename your certificate file to apnscertificatesandbox.p12 and place it in the application root folder.
When you move to production, rename your certificate file to apnscertificateproduction.p12 and place it in the application root folder.
The following servers must be accessible from the Worklight Server:
Sandbox servers:
gateway.sandbox.push.apple.com:2195
feedback.sandbox.push.apple.com:2196
Production servers:
gateway.push.apple.com:2195
Feedback.push.apple.com:2196
Copyright IBM Corporation 2013
WU5061.1
Notes:
Eventually, message are sent to push mediator such as APN or GCM.
So, you need to make sure that your Worklight server has access to the follower servers to
send the notifications:
For iOS development Sandbox servers: they are
gateway.sandbox.push.apple.com:2195
feedback.sandbox.push.apple.com:2196
For Production servers: you use
gateway.push.apple.com:2195
Feedback.push.apple.com:2196
For Android: the servers locations are:
https://www.google.com
https://android.apis.google.com
13-34 Mobile Application Development with IBM Worklight V6
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
13-35
Student Notebook
Edit application-descriptor.xml (1 of 2)
To set up push notifications in an app, add the following lines to the
application-descriptor.xml file
The Apple APNS certificate file must be placed in the root of the
applications folder
Replace pushSender settings values with your credentials
Android
iOS
WU5061.1
Notes:
Lastly, you need to specify Apple APNS certificate and Android push sender Gmail account
to your Worklight application-descriptor file.
For iOS, The certificate issued by APNS should be placed in the applications root folder.
V8.1
Student Notebook
Uempty
Edit application-descriptor.xml (2 of 2)
Windows Phone 8:
To set up non-authenticated push:
For more information about how to use the certificate file in the
Worklight project, follow the instructions that are provided in the IBM
Worklight Information Center under the Windows Phone 8 push
notifications topic.
Copyright IBM Corporation 2013
WU5061.1
Notes:
13-37
Student Notebook
PushBackendEmulator
The sample for this training module comes with a backend emulator
that you can use to simulate push notification submissions by a backend system.
To run the backend emulator, open the PushBackendEmulator folder
of the sample project in a command prompt, and then run the supplied
JAR file by using the following syntax:
java jar PushBackendEmulator.jar <userId>
<notificationText> <context_root> <serverPort>
userId is the user name you used to login to the sample application.
contextRoot is the context root of your Worklight project
For example:
java jar PushBackendEmulator.jar JohnDoe My first
push notification myContextRoot 10080
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Unit summary
Having completed this unit, you should be able to:
Describe push notification architecture and API
Create an application that uses push notifications
WU5061.1
Notes:
13-39
Student Notebook
Checkpoint questions
1. Which of the following connections are mandatory for push
notifications to work?
A. Client application must be able to connect to an APNS/GCM server
B. Client application must be able to connect to a Worklight server
C. Worklight server must be able to connect to an APNS/GCM server
D. All of the above
WU5061.1
Notes:
Write your answers here:
V8.1
Student Notebook
Uempty
Checkpoint answers
1. D. All of above
WU5061.1
Notes:
13-41
Student Notebook
WU5061.1
Notes:
Write your answers here:
V8.1
Student Notebook
Uempty
Checkpoint answers
1. False
2. True
3. B. Subscribe to a push notification event source
WU5061.1
Notes:
13-43
Student Notebook
Exercise 8
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Exercise objectives
After completing this exercise, you should be able to:
Use the Push Notification API to:
WU5061.1
Notes:
13-45
Student Notebook
V8.1
Student Notebook
Uempty
References
IBM Worklight V6 documentation:
http://pic.dhe.ibm.com/infocenter/wrklight/v6r0m0/index.jsp
14-1
Student Notebook
Unit objectives
After completing this unit, you should be able to:
Set up the Worklight Server and Eclipse environment to enable
reporting
Produce and view device analytics reports
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Topics
Device Analytics introduction
Setup before viewing reports
Configuring BIRT
Viewing Reports
WU5061.1
Notes:
14-3
Student Notebook
Device analytics
introduction
8.0
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Worklight
DB
Worklight
server
Raw
data
BIRT
reports
Aggregated
data
Other
reporting
tools
WU5061.1
Notes:
BIRT: Business Intelligence Reporting Tool
You can find sample reports at
https://www.ibm.com/developerworks/mobile/worklight/getting-started/
14-5
Student Notebook
WU5061.1
Notes:
Uncomment reports.exportRawData property in worklight.properties and set it's value to
true (by default, it is false).
Uncomment the wl.reports.db properties and add values for your database settings.
Make sure that the wl.reports.db.url property contains URL of the database you're
planning to use for Raw Data reports!
For these settings to take effect, you must stop the application server and restart it.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
OLAP: online analytical processing, an approach to the analysis of business data that
allows the analyst to view information rapidly from several different points of view. It is often
referred to as a cube, although that implies three dimensions and OLAP is more accurately
described as multi-dimensional. As an example, for a cube, one dimension could be
software components completed, another dimension geography of the teams writing the
software, and another dimension date. Other dimensions can be added. Data can be
consolidated (software can be viewed as individual components, or rolled up into groups or
types), you can drill down into the data (for example, analyze software components as
connectivity, authentication, and so on), slice the data (take a specific sub-set) and dice it
(view the sub-set in different ways).
Worklight analytics is based on this OLAP approach to data analysis.
14-7
Student Notebook
APP_ACTIVITY_REPORT table
The raw reports table includes the following information:
Column
Description
ACTIVITY
ACTIVITY_TIMESTAMP
ENVIRONMENT
ADAPTER
PROC
IP_ADDRESS
DEVICE_MODEL
GADGET_NAME
Application name
WU5061.1
Notes:
Other report elements include information about the Worklight application version number
(GADGET_VERSION), the user agent (from the HTTP header of the client device), a
unique device id, and the device operating system.
V8.1
Student Notebook
Uempty
Activity
Description
Init
Application initialization
Login
Query
Logout
User logout
WU5061.1
Notes:
Other report elements include information about the Worklight application and its version
number (GADGET_NAME, GADGET_VERSION), the user agent (from the HTTP header
of the client device), a unique device id, and the device operating system.
14-9
Student Notebook
WU5061.1
Notes:
The fact_activities table contains a total activity count (number of logged actions) per
application, application version, device, and environment.
V8.1
Student Notebook
Uempty
activities_cube table
The fact_activities data is also processed and put into a table called
activities_cube
This table has the same structure as the fact_activities table, but
contains records for the last 30 days only
WU5061.1
Notes:
The raw data of the fact_activities table is also processed and stored in the activities_cube
table.
This table is so named because of the online analytical processing concept of
multi-dimensional data analysis. As was mentioned earlier in this unit, cube does not imply
three dimensions here.
Since the table is intended for consolidation, drill-down, slicing, and dicing (analysis of
current data) it only contains records for the last 30 days.
It has the same structure as the fact_activities table.
14-11
Student Notebook
Notification_report table
The raw data reports engine also
populates the notification_report
table
This table contains information about
notifications sent from all event
sources
SMS, GCM, APNS
WU5061.1
Notes:
The notification_report table data is also processed to populate the notification_activities
table with consolidated data. In other words, the two tables have the same relationship as
the app_activity_report and fact_activities tables. The difference is that these tables hold
reports about SMS text messages, Google Cloud Messaging (GCM), and Apple Push
Notification Service (APNS).
Every time the notification_report table data is processed, an entry is added to the
notification_proc_report table, which is similar to the proc_report table.
V8.1
Student Notebook
Uempty
proc_report table
Each time data processing is performed for fact_activities a timestamp
is added to a proc_report table with the processing result
timestamp, number of processed entries
WU5061.1
Notes:
The process report table is one of the simplest. It is in a sense a report on the reports! Each
time the data processing is done, a new time stamp is added to a proc_report table with
information about the number of entries that were processed.
14-13
Student Notebook
APP_ACTIVITY_REPORT
APP_ACTIVITY_REPORT
FACT_ACTIVITY
FACT_ACTIVITY
PROC_REPORT
PROC_REPORT
ACTIVITIES_CUBE
ACTIVITIES_CUBE
NOTIFICATION_REPORT
NOTIFICATION_REPORT
NOTIFICATION_PROC_REPORT
NOTIFICATION_PROC_REPORT
NOTIFICATION_ACTIVITIES
NOTIFICATION_ACTIVITIES
WU5061.1
Notes:
The 24-hour interval is a default. The next page shows how to modify this.
V8.1
Student Notebook
Uempty
Processing interval
Processing this quantity of information can be intensive
The default interval is 1 day
WU5061.1
Notes:
The property is set in seconds. It is a default and is therefore commented out. You can find
it, not as you may expect in the Raw Reports properties, but at the bottom of the DB
settings properties.
14-15
Student Notebook
BIRT reports
8.0
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
BIRT reports
The Business Intelligence Reporting Tool is used to generate and
render report content.
The tool can be installed
as an eclipse plug-in
as an application on the server
WU5061.1
Notes:
There is comprehensive information about how to set up BIRT reports viewer on an
application server on the IBM Worklight V6 Information Center at
http://pic.dhe.ibm.com/infocenter/wrklight/v6r0m0/index.jsp?topic=%2Fcom.ibm.help.doc%
2Fwl_home.html (URL verified July 2013).
14-17
Student Notebook
Installing BIRT
You can install Eclipse with BIRT as an all-in-one package
You can install it from http://www.eclipse.org/downloads/packages/
eclipse-ide-java-and-report-developers/indigosr2
WU5061.1
Notes:
This slide describes how to install the BIRT environment in Eclipse. For production, you
need to follow these steps:
1. From your Worklight administrator or operator, get:
The WLREPORT database type and location
The library for the specific database type
- Typically a JAR file, for example mysql-connector-java-5.1.20-bin.jar
The credentials for connecting to the WLREPORT database from BIRT
2. Open the Report Design perspective
3. In the Data Sources tab, select the wl_analytics data source
4. Configure the JDBC driver
V8.1
Student Notebook
Uempty
You can examine the table contents in the SQL Results view
WU5061.1
Notes:
If you install documentation, examples, and source features (source code for BIRT) you
can explore the Eclipse BIRT environment without installing an external database. The
image shows the database that is created when you install the BIRT environment.
14-19
Student Notebook
Viewing reports
8.0
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
14-21
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
14-23
Student Notebook
Checkpoint questions
1. What is BIRT?
2. What kind of information are reports based on?
3. One of the types of information that the app_activity_reports
table provides is ACTIVITY_TIMESTAMP. Name another.
4. Name one of the report types discussed in the module
WU5061.1
Notes:
Write your answers here:
V8.1
Student Notebook
Uempty
Unit summary
Having completed this unit, you should be able to:
Set up the Worklight Server and Eclipse environment to enable
reporting
Produce and view device analytics reports
WU5061.1
Notes:
14-25
Student Notebook
Checkpoint answers
1.
What is BIRT?
Business Intelligence Reporting Tool
2.
3.
4.
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
References
IBM Worklight V6 documentation:
http://pic.dhe.ibm.com/infocenter/wrklight/v6r0m0/index.jsp
15-1
Student Notebook
Unit objectives
After completing this unit, you should be able to:
Define what direct update is
Use the Direct Update feature to automatically update deployed
applications with new versions
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
You have seen how applications are deployed from the development environment to the
production environment. But what about the user? If they have downloaded an application
which is subsequently updated, who do they find out that there is a newer version, or that
their current version may soon be deprecated? This is the philosophy behind direct
updates.
15-3
Student Notebook
The time for the application store review process is cut down
This is not a new application, just a new version of something which has already
been sanctioned
WU5061.1
Notes:
Note that the first bullet says always use. The mobile device can display an alert stating
that it is about to update the application not asking whether the user wants to update it!
V8.1
Student Notebook
Uempty
iOS-specific restrictions:
B2C: Per company's terms of service
Usually at least bug fixes are allowed
B2E: Through the enterprise developer program
WU5061.1
Notes:
Android does not have the restrictions shown in the second bullet. Direct updates for iOS
have some restrictions due to Apple policy.
15-5
Student Notebook
Version detection
Detection upon startup and when an application is brought into the
foreground
Dialog for easy user selection
Application download progress bar
WU5061.1
Notes:
As you saw on the previous slides, direct update refers to the Worklight application
environment. There is no dialog for the update of the web artefacts: it happens silently after
an update.
V8.1
Student Notebook
Uempty
Application Stores
Web
code
V1.0
Worklight Studio
Develop
Native applications
Web resources
Worklight Server
Maintain recent web
resources for native
applications V1.0 and V1.1
native
shell
Web
code
V1.1
WU5061.1
Notes:
An application is downloaded from an App Store and becomes a part of the cached
resources on the device. A request to check for updates is sent to the server when the
application starts up or when the application is brought to the foreground. If there is a
newer version available on the server it can be downloaded, and the device informs the
user of the newer version, or warns the user that the current version is deprecated and
should no longer be used.
Note that direct update only refers to the web contents. While the server can inform the
user about new native contents, it cannot provide it to the user. It can however block the
native application so that the user must go to an app store and obtain the new version.
15-7
Student Notebook
WU5061.1
Notes:
The server cannot provide a complete new version of a hybrid application. Any updates to
the native part of an application must go through the app store distribution process again.
The server can however provide direct updates to web parts of the application, which do
not require approval from the app store.
The server can disable a native application on a device. When an application is started (or
brought to the foreground), it can communicate with the server automatically (this is
configurable). In the example on this page, when an Android device calls this server, and
the server detects that the device is running Version 1.0 of the application, it can respond
with the message that the version is disabled, and provide notification so that the user is
aware of what is happening. This notification usually includes a URL so that the user can
go the app store and obtain the new version (for example, 1.1). When this has been
installed on the device, the application automatically calls the server, which detects that the
application version is 1.1 and notes that it is the active version. No action is taken.
V8.1
Student Notebook
Uempty
Checkpoint questions
1. Where are native resources deployed?
2. Where are web resources deployed?
3. On the Worklight console, versions can be marked as active,
disabled, or?
WU5061.1
Notes:
Write your answers here:
15-9
Student Notebook
Unit summary
Having completed this unit, you should be able to:
Define what direct update is
Use the Direct Update feature to automatically update deployed
applications with new versions
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Checkpoint answers
1. Where are native resources deployed?
Application store
WU5061.1
Notes:
15-11
Student Notebook
V8.1
Student Notebook
Uempty
References
IBM Worklight V6 documentation:
http://pic.dhe.ibm.com/infocenter/wrklight/v6r0m0/index.jsp
16-1
Student Notebook
Unit objectives
After completing this unit, you should be able to:
Prepare an application for deployment
Deploy an application to a remote server
Use the Ant utility with Worklight
Install IBM Worklight Server in a WebSphere Application Server and
DB2 environment.
Migrate applications from a development to a production environment
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
16-3
Student Notebook
Overview of application
management
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Overview
A Worklight project contains various components, such as applications,
adapters, configuration files, custom Java code and libraries
In development stages these components are deployed to a local
server which resides on the developers computer
The deployment is automated by Worklight Studio
WU5061.1
Notes:
The deployment environment may be configured in several different ways: There may be
one or several environments (Android, iOS, and so forth), there may be adapters (Cast
Iron, http, and so forth) and there may be purely web artifacts in a .war file.
16-5
Student Notebook
WU5061.1
Notes:
The application descriptor file is under the application folder and includes information such
as the display name of the application, author information, authentication requirements,
and server root information.
The worklight properties file is in the conf folder under server and initially includes a large
number of properties that are all commented out; for example, database-related values,
raw report values, and bit.ly credentials.
Some of these properties are highlighted in the following slides.
V8.1
Student Notebook
Uempty
Architecture of deployment (1 of 6)
A Java web application server is required to run Worklight
WebSphere, Tomcat or Liberty
Application server
project-name.war
Worklight applications and adapters
Database
WU5061.1
Notes:
worklight-jee-library.jar is a part of the Worklight Server package. When you install the
server (for example, using IBM Installation Manager), the file can be found in the Worklight
> WorklightServer folder. You copy it over to the application server.
16-7
Student Notebook
Architecture of deployment (2 of 6)
A Worklight project contains various server related settings under
\server\conf folder
For example, worklight.properties and AuthenticationConfig.xml
It is possible to add custom Java code and libraries to the java and lib
folders under server
These files are compiled to the project-name.war file under the bin folder
Application server
worklight-jee-library.jar
project-name.war
Worklight applications and adapters
Database
WU5061.1
Notes:
Everything required for the administration of the project by the application server is
deployed in the .war file, including a Worklight console instance that will be used to
manage the web potions of the application or applications associated with the project. This
is covered in detail further on.
V8.1
Student Notebook
Uempty
Architecture of deployment (3 of 6)
Database connection properties are defined in the
worklight.properties file
You can use either application server level JNDI or Worklight server level JDBC
connections.
Application server
worklight-jee-library.jar
project-name.war
Worklight applications and adapters
Database
WU5061.1
Notes:
As you have already seen, there are several options commented out in the
worklight.properties file pertaining to database connectivity. For development, you do not
need to uncomment anything, because the connectivity is automatic, and the developer
does not have to install or configure anything. For remote deployment, you must
uncomment the relevant properties and give the required values.
16-9
Student Notebook
Architecture of deployment (4 of 6)
Build and deploy project-name.war to the application server
Worklight Console is bundled within this .war file
In Worklight terms this .war file is called a Server customization bundle.
There is only one .war file for a project, deployed per application server
Application server
worklight-jee-library.jar
project-name.war
project-name.war
Worklight applications and adapters
Database
WU5061.1
Notes:
Although the built project file is called a war, it is more sccurate to refer to it as a server
customization bundle. The information that is bundled and sent to the server is not simply
an application or an adapter. It is a server configuration file that gives access to the
configuration of the applications and adapters through the Worklight console. This is
discussed in a few slides.
V8.1
Student Notebook
Uempty
Architecture of deployment (5 of 6)
When the .war file has been deployed to the server you can open
Worklight Console at http://server:port/context/console
The .war file functionality is using worklight-jee-library.jar
This was previously copied to the lib folder of the application server
Application server
worklight-jee-library.jar
project-name.war
Worklight applications and adapters
Database
WU5061.1
Notes:
The worklight-jee-library.jar file was provided with the Worklight server installation. It has to
be copied over to the application server.
Note the URL that is used to call the console. By default, the name of the project becomes
the context root, and the console for a particular project is bundled with the project in the
server customization bundle.
16-11
Student Notebook
Architecture of deployment (6 of 6)
The Worklight Console is now accessible, so you can deploy
applications and adapters
There is no limit to the number of applications/adapters deployed
However, they all share same Server customization bundle
Application server
worklight-jee-library.jar
project-name.war
Worklight applications and adapters
Database
WU5061.1
Notes:
The point made on this page is an important one: it is the Worklight console that is
accessible after deployment, and it is through the console that you manage the
applications and adapters. This is in fact identical to the system you have been using
throughout the exercises: when you right click on a project and select Run on Worklight
Console, you are given a browser view of the console, and from there you manage your
applications and adapters.
V8.1
Student Notebook
Uempty
16-13
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
Apache Ant can be downloaded at http://ant.apache.org/
More documentation about Apache Ant can be found at
http://ant.apache.org/manual/index.html
16-15
Student Notebook
WU5061.1
Notes:
Install Apache Ant and make sure that its binaries are in the path variable of your operating
system
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
The first sub-element added in the <target> element is a <taskdef> reference to the IBM
Worklight Ant utility. This addition ensures that Ant recognizes the IBM Worklight tasks and
has a default configuration for performing them.
The <taskdef> resource reference states what it is that is required in the Worklight ANT jar
file: defaults.properties. This properties file holds references for configuring a database or
an application server, building applications and adapters, or deploying them.
<classpath> gives the location of the worklight ANT jar file that holds the properties file.
This is the default location that was set up when the Worklight server was installed.
16-17
Student Notebook
WU5061.1
Notes:
app-builder is one of the tasks in worklight-ant.jar. It references the class
ApplicationBuilderTask, which has methods to create an apps backup folder, static final
strings for BUILD_SUCCEED and BUILD_FAILED, and so on.
To invoke the ANT build, you need to state where everything is, what you want to build, and
where you want the result to be placed.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
Deploying an application with ANT is an app-deployer task, and it really underlines the
simplicity of using an ANT process. You say where you want the Worklight application
deployed to, and where the task should look for the .wlapp file to deploy.
Note a small but important point: there is no provision here for a console password. If your
Worklight console is protected by a password, the ANT task will not be able to respond to
the challenge.
16-19
Student Notebook
V8.1
Student Notebook
Uempty
16-21
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Push notification
Security
Back-end integration
Version management
WU5061.1
Notes:
IBM Worklight Servers capabilities include:
Adapter technology to allow a mobile application to connect to a variety of back-end
resources using SQL or protocols such as HTTP/SOAP and HTTP/REST.
Data mashup capabilities to efficiently integrate several data streams into one and
serve it to the mobile application.
Security functions that integrate with the corporate authentication infrastructure to help
secure application and data access.
Application deployment and version control features that are managed and accessed
through the IBM Worklight Console.
Collection of a mobile applications user adoption and usage data for auditing and
reporting purposes.
16-23
Student Notebook
WU5061.1
Notes:
This diagram illustrates the following key points:
Worklight Server is a Java EE web application that is deployed to an application server.
It uses two databases, WRKLGHT, the core database and WLREPORT, the reporting
database.
A separate customized instance of Worklight Server is deployed for each application,
and each application communicates with its own customized instance of Worklight
Server at runtime.
Each instance of Worklight Server has its own Worklight Console used to deploy the
corresponding applications .wlapp and .adapter files.
V8.1
Student Notebook
Uempty
Worklight Server v6 can use the following database systems to store its
internal database:
Apache Derby 10.8 or later
DB2 Enterprise Server Edition version 9.7, 10.1 or later
MySQL 5.5 or 5.6
Oracle Database 11g Standard/Enterprise Editions release 1 or later
WU5061.1
Notes:
For a detailed list of system requirements for Worklight Server v6, visit:
http://www-01.ibm.com/support/docview.wss?uid=swg27024838
16-25
Student Notebook
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
16-27
Student Notebook
Application migration:
Overview
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
While the deployment of Worklight applications in Studios embedded server is almost
transparent and very convenient for development and unit testing, for integration testing
(and other similar higher levels of testing) as well as for production environments,
deployment to a remote and dedicated Worklight server is essential.
The full Worklight application package consists of various components, such as
applications, adapters, authentication modules, custom modules, and third party libraries.
During the development phase, all of these components are on the developers workstation
in a Worklight Studio workspace under a Worklight project.
When its time for integration and QA testing, as well as production release, these
application artifacts need to be transferred and deployed to the remote test or production
Worklight server.
Because each environment (production, pre-production, QA, Dev) has its own unique
Worklight-specific settings, for example, database connectivity parameters, an application
must be prepared or configured prior to deployment to a specific remote environment.
Copyright IBM Corp. 2013
16-29
Student Notebook
The next slides describe how to prepare and package an application in order to deploy it to
a remote server.
V8.1
Student Notebook
Uempty
25
WU5061.1
Notes:
In general, deploying a Worklight application entails two steps:
First, the developer or build master configures the Worklight application for deployment.
This includes adjusting the application properties in application-descriptor.xml, for
example, to specify the remote servers URL and define the appropriate Push
Notification subscription ID.
Another configuration file that needs to be prepared is the worklight.properties file in the
server/conf location of the Worklight project where you need to supply the target
environment server and database properties.
After the two files are configured, re-build the application in Worklight Studio.
The second step deals with transferring and deploying the application artifacts to the
target remote server. The System Administrator gets the Worklight project files from
the developer and deploys it to the remote server runtime such as WebSphere
Application Server as a Java EE artifact. This installs the Worklight server for the
application.
Copyright IBM Corp. 2013
16-31
Student Notebook
Once the project-specific Worklight sever is installed and configured, the System
Administrator deploys the projects applications and adapters using the Worklight
Console.
V8.1
Student Notebook
Uempty
16-33
Student Notebook
Application migration:
Preparing your
application
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
In addition to the application configuration, the developer or build master also needs to
prepare the Worklight Server configuration defined in the worklight.properties file in the
projects server/conf directory.
There are two important settings you need to define prior to deployment: Database
configuration and server access settings (the latter is discussed in the next slide).
Worklight server uses the database configuration properties to connect to the products
database. In Worklight Studios development environment, the embedded test server uses
a file based lightweight database. In a higher level environment, such as QA or production,
Worklight server is configured to use a full-fledged database system, such as DB2 or
Oracle. Therefore, you need to change the database properties contained in
worklight.properties to match the database used on the target server.
Note that the default worklight.properties file provides template configuration lines which
you can easily modify with real database value.
16-35
Student Notebook
WU5061.1
Notes:
Another important configuration information defined in the worklight.properties file is the
Worklight server access settings which specify how the Worklight server can be accessed
by a client. This is controlled by three properties:
publicWorklightProtocol: Defines the communication protocol used to access Worklight
server. Normally, it is HTTP.
publicWorklightPort: Defines the port number on which Worklight server can be
reached.
publicWorklightContext: Defines the context root of the Worklight server Java EE web
application.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
By creating a different configuration file for each target environment, you can quickly copy
and set the main configuration file with the desired version prior to re-building the
application.
16-37
Student Notebook
WU5061.1
Notes:
Once you have made all the required modifications to your Worklight projects configuration
as described in the previous slides, build your application and adapter(s) to generate the
deployable Worklight war file and application artifacts.
V8.1
Student Notebook
Uempty
16-39
Student Notebook
Application migration:
Deploying your
application
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
Deploy the generated Worklight server .war file to the target runtime following the standard
procedure for deploying a Java EE Web Archive file in the target application server:
For WebSphere Application Server, use the WebSphere Integrated Solutions Console
to deploy the WAR file.
For Tomcat server, copy the WAR file to the webapps directory and restart the server.
For detailed information on deploying the Worklight server .war file to the supported
environments, refer to the IBM Worklight V6.0 Administration Guide.
16-41
Student Notebook
Checkpoint
1. True or false:
Each Worklight application has its own Worklight server WAR file
2. Which of the following types of component can be deployed using the
Worklight console?
a) .adapter files
b) .war files
c) .wlapp files
d) .jar files
WU5061.1
Notes:
Write your answers here:
V8.1
Student Notebook
Uempty
Unit summary
Having completed this unit, you should be able to:
Prepare an application for deployment
Deploy an application to a remote server
Use the Ant utility with Worklight
Install IBM Worklight Server in a WebSphere Application Server and
DB2 environment.
Migrate applications from a development to a production environment
WU5061.1
Notes:
16-43
Student Notebook
Checkpoint answers
1. True or false:
Each Worklight application has its own Worklight server WAR file.
True
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
References
IBM Worklight V6 documentation:
http://pic.dhe.ibm.com/infocenter/wrklight/v6r0m0/index.jsp
17-1
Student Notebook
Unit objectives
After completing this unit, you should be able to:
Develop a Shell component
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Topics
shell component concepts
Creating and using a shell component
Android shell development
iOS shell development
WU5061.1
Notes:
17-3
Student Notebook
V8.1
Student Notebook
Uempty
17-5
Student Notebook
8.0
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Overview
The main idea of the shell component methodology is to create two
levels of development inside the organization:
Developers skilled in native development: implement native and web code
base that can be used as a starting point for applications. For example,
Native functionality to be invoked from JavaScript (Cordova plug-ins)
Authentication framework
Security configuration
Web resources shared between applications: logotypes, themes, and so on
Developers who are more focused on web development: receive ready to
use shell component and use it as a wrapper to create the organization
applications. For example,
Business logic
UI development
Data integration
5
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
The Worklight applications you have studied and built were primarily Hybrid application
types that contain both web and native code in a single application package or unit. It is a
standard Worklight application type that can be tested and deployed to mobile devices
directly with everything packaged in a single artefact.
Sometimes, certain organizations or development teams might want to create two levels of
development for the mobile application. Developers skilled in native development such as
Objective-C and Java programming can focus on implement native and web code base
that can be used as a starting point in single or several mobile applications. The type of
work might fall under native development include developing Apache Cordova plug-in code
that exposes native functionality to Web JavaScript component, developing and configuring
Security configuration such as Custom Java authenticator and Login modules, and
potentially also developing the web resources that are shared between applications like
logotypes and themes. In another words, these are the foundational enterprise core
libraries that built to be shared by maybe multiple mobile apps. In Worklight terminology,
the code or application typed developed by native development team is called a shell
Component.
Copyright IBM Corp. 2013
17-7
Student Notebook
The second level of development is targeted to developers who are less skilled in native
development, but have more web expertise: HTML, JavaScript and CSS programming.
The Web developers can focus on developing the mobile application to meet the business
requirement such as business logic, user interface development and data integration
between mobile client and backend. They can use the shell component developed by the
native development team as a wrapper for their mobile application. In Worklight, this web
resource or web application developed by web team is called an inner application.
Development skills and asset reuse are two main driving factors behind the Worklight shell
component concept. Obviously, there are some other benefits as well such as easier
source control management, and so on.
V8.1
Student Notebook
Uempty
Customizable native
shell code
Mobile browser
inner
application
Web code
Customizable
web shell code
Device APIs
WU5061.1
Notes:
The chart here illustrates the architecture of the Worklight shell component and the
relationship among the various building blocks of the shell based application model.
The outer contains or code base is the Customizable Native shell code or shell component
developed by the native development team. It can be either an iOS or an Android shell
created in Worklight Studio. This components uses Worklight client side runtime and may
interact with device native APIs directly to provide native services to the inner application.
This includes exposing native functionality though the Apache Cordova plug-in, and native
mobile pages built with a native programming language such as Java or Objective-C. One
of the important function carried by the shell component is to launch a mobile device
browser instance such as a WebKit instance on iOS or Android platform, and load the Web
resources packaged as an inner application. From the development perspective, shell
components consist of code auto generated by Worklight studio together with custom
developed native artifacts.
17-9
Student Notebook
From a packaging perspective, the shell component development team sends or source
control the shell component to the inner Web application development team to wrap their
code under the shell component. You see how this work in the coming slides.
V8.1
Student Notebook
Uempty
Customizable native
shell code
Mobile browser
inner
application
Web code
Customizable
web shell code
Device APIs
WU5061.1
Notes:
The inner component of the overall architecture is the Web code that developed by Web
team. This is the standard Web code, and consists of HTML, JavaScript and CSS files that
run under a device mobile browser instance launched by the shell component.
In order to create an inner application, a web development team first needs the shell
component from the native team or from a source control system.
Unlike a standard Worklight hybrid application, the shell component itself is not deployable.
In order to test the shell component and any libraries built, Worklight introduces a test
application concept. When a shell component is created, an inner application is
automatically added to the project by Worklight Studio. The application is used by the shell
developer to launch the application either in a device or a device simulator to test the shell
component. The test application is only for unit testing.
17-11
Student Notebook
8
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
Regardless of whether the type is hybrid, shell or inner application, they are all managed
under a Worklight project that is the development unit in Worklight Studio.
Create a Worklight shell component using Worklight Studio. You can right click the
components folder and select New -> Worklight shell Component. This launches new shell
component creation wizard as shown on this page.
Specify the Worklight project to add the shell component to and name the shell component,
for example Myshell.
In this wizard, you can also add the UI frameworks to be packaged with the shell
component so that later the inner applications can use that framework.
V8.1
Student Notebook
Uempty
9
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
After clicking finish Worklight studio creates two components under the project. The first
one is created under the project components folder as shown in the lower part of the
screen shot. The folder name Myshell matches the component name. This folder is the
central place for native development team to work on the shell component.
A MyshellTest application is automatically created under the project applications folder as
shown on the upper portion of the screen shot. This is a test application, as described in
the terminology section. It is used to test/debug shell components.
17-13
Student Notebook
10
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
Like hybrid or standard Worklight applications, there is a common folder created for the
shell component. This is used to host all the artefacts shared by different device platforms
such as iOS and Android.
Under the common folder, folders for CSS, images and JS are used to host web resources
that are added automatically to inner applications at build time. If you are developing
reusable web widgets, or mobile client-side data binding component to be reused by inner
applications, this is where the code is managed.
The fragments folder contains html fragments that are added to the inner applications main
HTML file in predefined locations.
A shell component is primarily dealing with native code, thus it is often tested in a native
device or simulator environment. If you want to pre-view the web portion of the shell
component using desktop-based browser application preview feature, you can stub out
some of the native functions using this preview folder. Replace a native function or data
with stub UI or data defined under the preview folder.
V8.1
Student Notebook
Uempty
17-15
Student Notebook
shell-descriptor.xml
The shell-descriptor.xml file contains shell component information
and application-specific properties
Application-specific properties set in the shell descriptor are used in
all inner applications
Can be edited in
Design or Source
mode
11
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
Like the applicationDescriptor.xml file for a standard hybrid application, the shell
component uses a file named shell-descriptor.xml to define shell component information
and application specific properties. For example, a native shell environment such as
Android shell or iPhone shell are defined under this file.
Application-specific properties set in the shell descriptor are used in all inner applications
that wrapped under this shell component.
V8.1
Student Notebook
Uempty
17-17
Student Notebook
8.0
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
13
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
A test application is created for shell component developers for unit testing tasks. It is
automatically created by Worklight Studio. You can add testing logic to the test application
to validate your shell component. In this section, you see some simple examples to
illustrate how to use a test application to test your shell component.
Under the shell component, create a dummy shell function to say hello in a JavaScript
alert. You create a new myshell.js file under the Myshell\common\js folder.
In this file, create a simple JavaScript method sayHelloFromshell as shown in the screen
capture.
Expanding the shell/fragments folder, you see the file named body-top.wlfragment file. Edit
it and add the code shown in the side. The shell fragment loads the JavaScript myshell.js
just created. Save the file.
17-19
Student Notebook
14
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
The sayHelloFromshell() function is not a part of the inner application, but a part of the shell
component. Edit the generated test application to test the code added on the previous
page.
Modify the MyshellTest.js file under apps/MyshellTest/common/js folder. In the application
initialization function wlCommonInit, add the statement to invoke the sayHelloFromshell
function.
Note that sayHelloFromshell is not defined in the Test application. The Worklight shell
component handles the code injection.
Build and deploy the MyshellTest application. Open the Worklight console and you find
your application listed as a regular hybrid application.
Preview the MyshellTest as Common Resource, which renders the test application in a new
browser tab or window.
V8.1
Student Notebook
Uempty
15
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
Under application preview window, you can see the HTML text added to the shell fragment
and shell JavaScript function executed. Also, the inner test applications own HTML is also
rendered.
This simple test case illustrates how the Worklight shell component works, and how you
can test the shell component in Worklight studio.
17-21
Student Notebook
16
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
Most of the bundle creation process is handled by Worklight studio. You start with a build
shell component. This can be started using the context menu by right-clicking the shell
component, for example myshell that was created here. Once the shell developer builds
the shell component a .wlshell file is created under projects bin\ folder. This file is called a
shell bundle and can be sent to inner application developers.
While the shell developers are working with the Test application they are not required to
explicitly create a shell bundle because the test application references the shell
components source code directly, as specified in the application-descriptor. However, once
a shell developer wants to send the shell component to the inner application developer,
they need to create a shell bundle.
V8.1
Student Notebook
Uempty
17
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
The shell bundle creation process is easy and is handled by Worklight studio. To create a
shell bundle right click on a shell components folder (in this case myshell) and select Run
? Build shell Component. The.wlshell file is created under bin\ folder of your project. In the
sample test component, it is Myshell-1.0.wlshell file.
17-23
Student Notebook
shell
Component
shell Bundle
(.wlshell file)
WU5061.1
Notes:
Here is a review of how the inner application developer can bundle the web code under the
shell bundle.
The inner application developers must first copy the shell bundle file to a Worklight Project
they are working on. This can be copied into the project bin folder as well. Once inner
application developer creates a new inner application they must specify the location of a
shell bundle file. When the shell bundle file is received from shell component developers,
the inner application developer need to replace the existing shell bundle file and rebuild the
application. When building the inner application, Worklight Studio packages the shell
component and inner application to generate the final deployable mobile application as an
APK for Android application or an IPA file for iOS app. The process is highlighted in the
diagram on the right.
V8.1
Student Notebook
Uempty
17-25
Student Notebook
8.0
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
20
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
Just like regular application environment optimization, preparing a shell component for an
Android environment starts with adding a new Android environment to a shell component.
The process is exactly the same as adding an Android environment for a regular hybrid
Worklight application.
From either the shell component folder context menu or Eclipse toolbar Worklight short cut,
select New Worklight Environment to bring up the wizard. Specify the Worklight project and
the shell Component you want to add environment to. Then, under Create Folders, check
Android phones and tables.
The difference from the regular application new environment wizard is that the shell
component can only have three types of Environment: iPhone, iPad and Android phones
and tablets.
17-27
Student Notebook
21
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
Once an Android environment is added to the shell component, a set of folders and files
are automatically generated. Similar to regular applications, a new folder named android is
created under the Myshell shell component application, as the same level as the common
folder.
The relationship between the environment specific artefacts and the ones under common
folders are similar to the rules used in regular Worklight application.
Android environment specific web code goes in the css, images, fragments, and js folders.
The native folder contains the native application template that is used when creating an
Android project from an inner application. This is where native developers work most of the
time such as adding new Apache Cordova plugins, or developing native Android pages
using Java.
The nativeEmptyApp folder contains an application built from the shell component and
an empty inner application. It is created for testing purposes.
V8.1
Student Notebook
Uempty
22
WU5061.1
Notes:
The files that reside under the native folder are templates that are used to create the inner
applications Android project.
You can define a Java native Android page implementation template under the native/src
folder. You can add Android User interface artefacts such as a UI definition and native
images under the res folder.
To be easily customized by the inner applications, two of the folder and file names under
the native folder contain placeholder elements which are populated during build time.
The ${packageDirectory} placeholder is populated with a real Java package name used
in the application. The ${appName} placeholder is populated with the applications
name, thus creating the main applications activity. All these placeholders allows a
single shell component be shared by multiple inner apps that may have different
configuration and attributes.
These placeholders are normally populated or generated by the Worklight studio build
process.
Copyright IBM Corp. 2013
17-29
Student Notebook
Files that end with .wluser are user editable templates, which can be modified by a shell
developer. These files contain the business specific implementation such as a custom
built Android native page implemented in Java.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
The Android/native folder is simply a placeholder used by Worklight shell component
framework, it is not a real Android project as the one under a regular Worklight application
is. So, Eclipse does not provide advanced features such as auto-complete when working
on it directly.
To continue getting support from these Eclipse feature, one of the solutions is adding an
Android environment to Test application added during the shell component creation time,
and using the Test Application Android environment to create, modify and debug Java
code.
To illustrate the concept, the following slides look at the process of building a simple
Android component called customToaster using Java.
You start by adding an Android environment for the Test Application. For the Myshell
sample, it is MyshellTest application. Once the new Android Environment is added, you can
work on the generated Android project.
17-31
Student Notebook
24
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
From here, normal Android native development can be carried on, and all Eclipse support
feature like code assistant can be used.
A new package com.mycustomcode is created under the generated Android project, under
the src folder. A new Java class, MyCustomToaster.java, is added under this package.
Define a static Java method to invoke the Android Toast API to show a custom message.
In the application main activity, the Java class MyshellTest, the custom Toaster message is
invoked using MyCustomToast.showToastAlert().
V8.1
Student Notebook
Uempty
25
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
To test the shell component, run the Build and Deploy and then run the MyshellTest
Android project in an Android emulator or a real Android device.
The JavaScript alert (not discussed on the previous slides) is implemented in ShellProject.
The alert at the bottom of the screen capture is the custom toaster message implemented
in native Java code in ShellProjectMyShellTestAndroid.
17-33
Student Notebook
26
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
Copying the Java code is done in two steps:
Custom code is copied as-is, including the packages. The class
com.mycustomcode.MyCustomToaster is copied to the shell component source folder as
com/mycustomcode/MyCustomToaster.
For modifications made to artifacts that are predefined, or generated files created by
Worklight studio, the code content has to be copied manually to the corresponding
template files. In this specific case the code add to MyshellTest.java
(MyCustomToaster.showAlert(this, txt);) must be copied to the file
${appName}.java.wltemplate.wluser.
V8.1
Student Notebook
Uempty
27
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
In order to take in the changes made in the shell component native artifact, delete the
native folder in the Test application and perform a Build and Deploy to recreate it
automatically.
17-35
Student Notebook
28
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
NativeEmptyApp is used primarily for inner application developers to test native functions.
It is not intended to deliver a final deployable native or hybrid application.
The NativeEmptyApp project can be deployed to an Android device or Device emulator.
Once NativeEmptyApp is installed on the device, inner application developer can specify
the URL of Worklight Server to load the inner application from. This helps inner application
developers to test their code without a need to have native SDKs installed, e.g. develop
and test iPhone application without a Mac.
To use NativeEmptyApp in the development environment, developers import the entire
nativeEmptyApp folder as a generic project in Eclipse. It has all the necessary folder
structure and configuration to be treated as an Android application.
V8.1
Student Notebook
Uempty
29
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
When deployed to an Android device or Android emulator, developers and testers can load
the inner application they want to test by performing some simple actions.
The NativeEmptyApp provides the instruction on the default page, as shown in the left
screen capture.
You need to Press the Android menu button, send select the setting. This brings up the
application setting screen as shown on the right screen capture.
In here, you change the URL that the inner application content is loaded from. The empty
shell then loads the inner application remote artifact to the device and render it as regular
Worklight hybrid application.
17-37
Student Notebook
V8.1
Student Notebook
Uempty
17-39
Student Notebook
8.0
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
31
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
Just like regular application environment optimization, preparing a shell component for iOS
development starts with adding a new iPhone or iPad environment to a shell component.
The process is exactly the same as adding an iOS environment for a regular hybrid
Worklight application.
From either the shell component folder context menu or Eclipse toolbar Worklight short cut,
select New Worklight Environment to bring up the wizard. Specify the Worklight project and
the shell Component you want to add environment to. Then, under Create Folders, check
iPhone or iPad.
The difference from the regular application new environment wizard is that the shell
component can only have three types of Environment: iPhone, iPad and Android phones
and tablets. If there is already an environment created, it is greyed out here.
17-41
Student Notebook
32
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
Once an iOS environment is added to the shell component, a set of folders and files are
automatically generated. Similar to regular applications, a new folder named iPhone or
iPad is created under the Myshell shell component application, as the same level as the
common folder.
The relationship between the environment specific artefacts and the ones under common
folders are similar to the rules used in regular Worklight application.
The native folder contains the native application template that is used when creating an
iOS project from an inner application. This is where native developers work most of the
time such as adding new Apache Cordova plugins, or developing native iOS pages.
The nativeEmptyApp folder contains an application built from the shell component and
an empty inner application. It is created for testing purposes.
V8.1
Student Notebook
Uempty
${XcodeProjectName}.
info.plist.wltemplate.
wluser is populated with the
application name; creates the main
application activity
WU5061.1
Notes:
The files that reside under the native folder are templates that are used to create the inner
applications iOS project.
example, you can add iPhone User interface artefact such as UI definition and native
images under the Resources folder.
To be easily customized by the inner applications, some of the folder and file names under
the native folder contain placeholder elements which are populated at build time:
${XcodeProjectName}.Xcodeproj.wluser and
${XcodeProjectName}-Info.plist.wltemplate.wluser.
All these placeholders allows a single shell component be shared by multiple inner
apps that may have different configuration and attributes.
These placeholders are populated or generated by Worklight studio build process.
Files that end with .wluser are user editable templates, which can be modified by a
shell developer. These files tend to contain the business specific implementation such
as a custom built iPhone native page implemented in Objective-C.
Copyright IBM Corp. 2013
17-43
Student Notebook
V8.1
Student Notebook
Uempty
34
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
The iPhone/native folder is simply a placeholder used by Worklight shell component
framework, it is not a real iPhone project as the one under a regular Worklight application
is. So, Eclipse does not provide advanced features such as auto-complete when working
on it directly.
To continue getting support from these Eclipse feature, one of the solutions is adding an
iPhone environment to Test application added during the shell component creation time,
and using the Test Application iPhone environment to create, modify and debug
Objective-C code.
To illustrate the concept, the following slides look at the process of building a custom alert
iPhone component using Objective-C.
You start by adding a iPhone environment for the Test Application. For the Myshell sample,
it is MyshellTest application. Once new iPhone Environment is added, you can work on the
generated iPhone project.
17-45
Student Notebook
35
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
Create a new Objective-C class called MyshellTest under the Classes folder. This is your
custom iPhone component.
Add a static method to the newly create class. The method raises an alert using the
Objective-C UIAlertView API.
Modify the Worklight studio generated iPhone main class of your application ViewController
and invoke the custom Alert class you created earlier.
This completes the native development work, all done in the iPhone environment of the test
application MyshellTest.
V8.1
Student Notebook
Uempty
36
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
To test the shell component, you need to run the Build and Deploy.
Build and Deploy all or iPhone environment for the MyshellTest Test application. Then, run
MyshellTest iPhone project in iPhone simulator or a real iPhone device from Xcode.
You see the custom alert message MyCustomClasss alert you have implemented in native
Objective-C code in previous slides.
This completes your testing, youve validated that the custom Objective-C alert
implementation is working properly. Now, its time to get the native code back into the shell
component.
17-47
Student Notebook
2
37
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
1. The custom Objective-C classes added to the iPhone project can be copied as-is,
keeping the folder structure intact. These files are under the Classes folder, as shown in
the screen capture here.
2. Xcode keeps its project structure stored in project.pbxproj. Therefore the content of
this file should also be copied from Test application to shell component.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
When you make changes to the shell component, you need to synchronize the code with
the generated Test Application iPhone project.
17-49
Student Notebook
39
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
WU5061.1
Notes:
The nativeEmptyApp project can be built as an APK or IPA by the shell developer and sent
to inner application developers to use for debugging applications.
The ability to specify the URL of the Worklight Server from which to load the inner
application helps inner application developers to test their code without a need to have
native SDKs installed, (for example develop and test iPhone application without a Mac).
Important: nativeEmptyApp cannot load a remote inner application that has the device
provisioning enabled. NativeEmptyApp can only be used in the development environment.
Its used primarily for inner application developer to test the native function rather than
delivering a final deployable native or hybrid application.
You can deploy the NativeEmptyApp project to an iOS device or Device emulator. Once
nativeEmptyApp is installed on the device, inner application developer can specify the URL
of Worklight Server to load the inner application from. This helps inner application
developers to test their code without a need to have native SDKs installed, e.g. develop
and test iPhone application without a Mac.
17-50 Mobile Application Development with IBM Worklight V6
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V8.1
Student Notebook
Uempty
17-51
Student Notebook
Checkpoint questions
1. When a shell developer completes developing the shell components,
what is the correct way to distribute it to inner application
developers?
A. Compressing the Worklight project and emailing it to inner application
developers
B. Committing the Worklight project to a source control management system and
telling inner application developers to use source code from it
C. The shell developer should not distribute the shell component to inner
application developers. They should send their inner applications to the shell
developer in order to build them
D. Sending the .wlshell shell bundle file to inner application developers
WU5061.1
Notes:
Write your answers here:
V8.1
Student Notebook
Uempty
Unit summary
Having completed this unit, you should be able to:
Develop a Shell component
WU5061.1
Notes:
17-53
Student Notebook
Checkpoint answers
1. D. Sending the .wlshell shell bundle file to inner application
developers
2. C. Application UI components
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
References
Enabling Mobile Apps with IBM Worklight Application Center (An IBM
Redpaper publication)
http://www.redbooks.ibm.com/abstracts/redp5005.htm
l
IBM Worklight V6 documentation:
http://pic.dhe.ibm.com/infocenter/wrklight/v6r0m0/index.jsp
18-1
Student Notebook
Unit objectives
After completing this unit, you should be able to:
Configure Application Center users
Use the Application Center to manage and share mobile applications
within a development team.
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
The Application Center is composed of these main elements: a server-side component, a
repository, an administration console, and a client mobile application.
18-3
Student Notebook
Typical scenario
As part of the development process of an application, a development
team creates a new version of an Android or iOS application
A developer uploads the new version of the application to the
Application Center
The developer enters a description that mentions elements that the team
added or fixed from the previous version
The new version of the application is available to other members of the team
for testing and review
WU5061.1
Notes:
You can use the Application center as part of the development process of an application. A
typical scenario of the Application Center is a team building a mobile application; the
development team creates a new version of an Android or iOS application. The
development team wants this new version to be reviewed and tested by the extended
team. A developer goes to the Application Center console and uploads the new version of
the application to the Application Center. As part of this process, the developer can enter a
description of the application version. For example, the description could mention the
elements that the development team added or fixed from the previous version. The new
version of the application is then available to the other members of the team.
Another person, for example, a beta tester, can launch the Application Center installer
application, the mobile client, to locate this new version of a mobile application in the list of
available applications and install it on his mobile device. After testing the new version, the
beta tester can rate the application and submit feedback. The feedback is visible to the
developer from the Application Center console.
V8.1
Student Notebook
Uempty
Application Catalog
Service
Application Center
Console
Application Install
Service
Application
Center
Installer App
Application Feedback
Service
iOs / Android
Rest Services
Database - Derby
WU5061.1
Notes:
The Application Center is composed of these main elements: a server-side component, a
repository, an administration console, and a mobile client application.
Server-side component
The server-side component is a Java Enterprise application that must be deployed in a web
application server such as IBM WebSphere or Apache Tomcat.
The server-side component consists of an administration console and a mobile application.
This mobile application installs the mobile applications available to the client-side
component.
The web console and the installer application communicate through REST services with
the server component.
Several services compose the Application Center server-side component; for example, a
service that lists available applications, a service that delivers the application binary files to
the mobile device, or a service that registers feedback and ratings.
Repository
Copyright IBM Corp. 2013
18-5
Student Notebook
A database that stores information such as which application is installed on which devices,
the feedback about applications, and the mobile application binary files. The Application
Center application is associated with the database when you configure the Application
Center for a particular web application server and a supported database.
Administration console
A web console through which administrators can manage applications, user access rights
to install applications, user feedback about mobile applications, and details about
applications installed on devices. See The Application Center console.
Mobile client application
You use the mobile client to install applications on a mobile device and to send feedback
about an application to the server.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
18-7
Student Notebook
You must map the roles to the corresponding sets of users in your
organization
WU5061.1
Notes:
If you choose to use an authentication method through a user repository such as LDAP,
you can configure the Application Center so that you can use users and groups with the
user repository to define the Access Control List (ACL) of the Application Center. This
procedure is conditioned by the type and version of the web application server that you
use.
After you configure authentication of the users of the Application Center, which includes
configuring LDAP if you plan to use it, you can, if necessary, define the endpoint of the
application resources. You must then build the Application Center mobile client. The mobile
client is used to install applications on mobile devices.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
18-9
Student Notebook
Applications view
1.
2.
WU5061.1
Notes:
In the Applications view you can add applications to the Application Center. Initially the list
of applications is empty and you must upload an application file.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
Application details:
Description: used to describe the application to the mobile user.
Recommended: select to indicate that you recommend users to install this
application. Recommended applications appear in a special list of applications in
the mobile client.
Installer: Administrator only; indicates that the application is used to install other
applications on the mobile device.
Active: indicates that an application can be installed on a mobile device. If you
do not select this property, the application is inactive and grayed on the list of
applications in Application Management.
For Android applications:
Package: the package name of the application; package attribute of the
manifest element in the manifest file of the application.
18-11
Student Notebook
V8.1
Student Notebook
Uempty
Version number
Access control setting
Rating
WU5061.1
Notes:
To edit application properties, click the version number of the application > Application
details.
To view feedback details, click the version number of the application.
To set access control, click the unrestricted or restricted links of the application.
18-13
Student Notebook
Stakeholders and
testers submit
feedback directly from
the Application Center
mobile client
WU5061.1
Notes:
Users of mobile applications can rate an application and send feedback through the
Application Center mobile client. The feedback is available in the Application Center
console. Individual feedback is always associated with a particular version of an
application.
The rating is an average of all recorded feedback. It consists of one to five stars, where one
star represents the lowest level of appreciation and five stars represents the highest level
of appreciation. If no stars are selected, no feedback is recorded.
V8.1
Student Notebook
Uempty
1.
2.
3.
WU5061.1
Notes:
Select Applications > Available Applications.
Click unrestricted or restricted state of an application.
To add a user, enter a user ID and click Add User.
There are different ACLs for installation (for example, testers) and administration (fellow
developers).
18-15
Student Notebook
WU5061.1
Notes:
The devices that are connected to the Application Center are listed under Device
Management > Registered Devices.
You can edit the Name of a device. Click OK or Apply to save the changes.
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
18-17
Student Notebook
Nothing is installed
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
18-19
Student Notebook
Unit summary
Having completed this unit, you should be able to:
Configure Application Center users
Use the Application Center to manage and share mobile applications
within a development team.
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Exercise 9
8.0
WU5061.1
Notes:
18-21
Student Notebook
Exercise objectives
After completing this exercise, you should be able to:
Configure the Application Center
Manage applications in the Application Center
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
19-1
Student Notebook
Unit objectives
After completing this unit, you should be able to:
Explain how the course met its learning objectives
Submit an evaluation of the class
Identify other WebSphere Education courses that are related to this
topic
Access the WebSphere Education website
Locate appropriate resources for further study
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
WU5061.1
Notes:
19-3
Student Notebook
References
IBM Worklight V6 documentation:
http://pic.dhe.ibm.com/infocenter/wrklight/v6r0m0/index.jsp?topic=%2Fcom.ibm.
help.doc%2Fwl_home.html
WU5061.1
Notes:
V8.1
Student Notebook
Uempty
Unit summary
Having completed this unit, you should be able to:
Explain how the course met its learning objectives
Submit an evaluation of the class
Identify other WebSphere Education courses that are related to this
topic
Access the WebSphere Education website
Locate appropriate resources for further study
WU5061.1
Notes:
19-5
Student Notebook
V8.1
Student Notebook
AP
20-1
Student Notebook
V8.1
backpg
Back page