ABNFP Wu506 Instructorguide

Mobile Application
Development with IBM

Worklight V6 - Early
Education

(Course code WU506)
Instructor Guide
ERC 1.0

V8.1
cover
Front cover
Instructor Guide
June 2013 edition
The information contained in this document has not been submitted to any formal IBM test and is distributed on an as is basis without
any warranty either express or implied. The use of this information or the implementation of any of these techniques is a customer
responsibility and depends on the customers ability to evaluate and integrate them into the customers operational environment. While
each item may have been reviewed by IBM for accuracy in a specific situation, there is no guarantee that the same or similar results will
result elsewhere. Customers attempting to adapt these techniques to their own environments do so at their own risk.

Copyright International Business Machines Corporation 2013.
This document may not be reproduced in whole or in part without the prior written permission of IBM.
US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
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:
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.
AIX AS/400 BigFix
Cast Iron DB DB2
Domino FileNet Lotus Notes
Lotus Notes PureApplication
Rational Redbooks WebSphere
Instructor Guide
V8.1
TOC
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Copyright IBM Corp. 2013 Contents iii
Contents
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii
Instructor course overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv
Course description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvii
Agenda . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxix
Unit 1. Mobile overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
1.1. Becoming a mobile enterprise. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7
Becoming a mobile enterprise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8
Why go mobile? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10
Demand for mobility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-12
Mobile platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14
1.2. Challenges of mobile application development, management and security . . . . . 1-17
Challenges of mobile application development, management and security . . . . . 1-18
Considerations for mobile (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-20
Considerations for mobile (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-22
Advantages of mobile communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-24
Characteristics of mobile interactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-26
1.3. Types of mobile applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-29
Types of mobile applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-30
The choice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-32
Development approaches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-34
Native compared to hybrid applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-36
Web standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-38
SOA to mobile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-40
1.4. Overview of IBM mobile strategy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-43
Overview of IBM mobile strategy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-44
IBM MobileFirst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-46
IBM MobileFirst portfolio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-48
1.5. IBM Mobile Foundation V6.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-51
IBM Mobile Foundation V6.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-52
IBM MobileFirst platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-54
IBM Mobile Foundation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-57
IBM Worklight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-59
WebSphere Cast Iron Hypervisor Edition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-62
IBM Endpoint Manager for Mobile Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-64
Checkpoint questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-66
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-68
Checkpoint answers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-70
Instructor Guide
iv Mobile Application Development with IBM Worklight V6 Copyright IBM Corp. 2013
Unit 2. Designing mobile solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-2
Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-4
Three approaches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-6
Web, hybrid, native... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-8
2.1. Approaches to mobile design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-11
Approaches to mobile design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-12
Native applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-14
Creating a native application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-16
Mobile-web Applications - HTML5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-18
Mobile-web Applications - CSS3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-20
Mobile-web Applications - JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-22
Mobile web applications - mobile web sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-24
Hybrid applications (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-26
Hybrid applications (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-29
2.2. Comparison of mobile application designs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-33
Comparison of mobile application designs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-34
Native - advantages and disadvantages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-36
Web application - advantages and disadvantages . . . . . . . . . . . . . . . . . . . . . . . . .2-38
Hybrid applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-40
Comparison of features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-42
2.3. Choosing the right approach. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-45
Choosing the right approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-46
Scenario - the native approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-48
Scenario - the web approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-50
Scenario - the hybrid approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-52
Checkpoint questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-54
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-56
Checkpoint answers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-58
Unit 3. Introduction to IBM Worklight v6.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-2
Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-4
3.1. IBM Worklight component architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-7
IBM Worklight component architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-8
Worklight components - overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-10
Worklight Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-12
Worklight Studio plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-14
Worklight Studio design perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-16
Shell components and inner applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-18
Worklight server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-20
Server customization components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-22
worklight.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-24
authenticationConfig.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-26
Deploying applications and adapters to the server . . . . . . . . . . . . . . . . . . . . . . . . .3-28
Device runtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-30
Application distribution and update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-33
Push notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-35
Instructor Guide
V8.1
TOC
Copyright IBM Corp. 2013 Contents v
Worklight console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-37
Worklight console - catalog tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-39
Worklight console - mobile browser simulator . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-41
Mobile browser simulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-43
Application Center architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-45
3.2. Code optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-49
Code optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-50
Code optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-52
The basis of optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-54
How does optimization work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-56
Optimization - CSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-58
Optimization - images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-60
Optimization - JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-62
Optimization - HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-64
3.3. Client-side development:
the Worklight JavaScript SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-67
Client-side development: the Worklight JavaScript SDK . . . . . . . . . . . . . . . . . . . . 3-68
Overview of client-side development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-70
Common controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-72
Skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-74
Apache Cordova . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-76
Calls between native and web pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-78
Offline access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-80
Encrypted cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-82
Globalizing strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-84
UI frameworks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-87
3.4. Server-side development. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-89
Server-side development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-90
Integration adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-92
3.5. Secure authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-95
Secure authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-96
Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-98
3.6. Application management and reporting capabilities . . . . . . . . . . . . . . . . . . . . . . 3-101
Application management and reporting capabilities . . . . . . . . . . . . . . . . . . . . . . 3-102
Push notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-104
Direct update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-106
Remote server application deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-108
3.7. Mobile team development capabilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-111
Mobile team development capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-112
Shell development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-114
Application Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-116
Enhancements to Worklight in version 6.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-118
Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-120
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-122
Checkpoint answers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-124
Unit 4. Overview of Worklight Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
Instructor Guide
vi Mobile Application Development with IBM Worklight V6 Copyright IBM Corp. 2013
Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-4
4.1. IBM Worklight Studio installation and configuration . . . . . . . . . . . . . . . . . . . . . . . . .4-7
IBM Worklight Studio installation and configuration . . . . . . . . . . . . . . . . . . . . . . . . .4-8
IBM Worklight Studio: Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-10
IBM Worklight Studio installation: Prerequisites (1 of 2) . . . . . . . . . . . . . . . . . . . . .4-12
IBM Worklight Studio installation: Prerequisites (2 of 2) . . . . . . . . . . . . . . . . . . . . .4-14
IBM Worklight Studio installation methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-16
Installing IBM Worklight Studio using the Eclipse Update Site (1 of 4) . . . . . . . . . .4-18
4.2. IBM Worklight Studio installation and configuration . . . . . . . . . . . . . . . . . . . . . . . .4-27
IBM Worklight Studio installation and configuration . . . . . . . . . . . . . . . . . . . . . . . .4-28
Android development environment setup steps . . . . . . . . . . . . . . . . . . . . . . . . . . .4-30
Installing the Android SDK: Core tools installation . . . . . . . . . . . . . . . . . . . . . . . .4-32
Installing the Android SDK: SDK platform and platform tools installation . . . . . . .4-34
Installing the ADT plug-in for Eclipse (1 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-36
Creating an Android Virtual Device (AVD) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-42
Starting an Android Virtual Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-44
4.3. IBM Worklight Studio installation and configuration . . . . . . . . . . . . . . . . . . . . . . . .4-47
IBM Worklight Studio installation and configuration . . . . . . . . . . . . . . . . . . . . . . . .4-48
iOS development environment setup steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-50
Developing for iOS: Register as an Apple developer . . . . . . . . . . . . . . . . . . . . . . .4-52
Developing for iOS: Download and install Xcode . . . . . . . . . . . . . . . . . . . . . . . . . .4-54
Developing for iOS: Worklight Studio and Xcode integration . . . . . . . . . . . . . . . . .4-57
4.4. Overview of mobile development steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-59
Overview of mobile development steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-60
Worklight Studio mobile application development lifecycle . . . . . . . . . . . . . . . . . .4-62
4.5. Creating a project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-65
Creating a project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-66
Worklight project creation wizard: Invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-68
Worklight project creation wizard: Project name and type . . . . . . . . . . . . . . . . . . .4-70
Worklight project creation wizard: Hybrid application UI framework selection . . . .4-73
Worklight project structure overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-75
Worklight project structure: Application folder . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-78
Worklight project structure: Application folder additional environments . . . . . . . . .4-81
Worklight project structure: Server folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-83
Worklight project structure: bin folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-85
Worklight application descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-87
Worklight application descriptor: Basic information . . . . . . . . . . . . . . . . . . . . . . . .4-89
Worklight application descriptor: Environments . . . . . . . . . . . . . . . . . . . . . . . . . . .4-91
4.6. Writing your code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-93
Writing your code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-94
Constructing the UI: Main HTML document (1 of 3) . . . . . . . . . . . . . . . . . . . . . . . .4-96
Constructing the UI: Main HTML document (3 of 3) . . . . . . . . . . . . . . . . . . . . . . . .4-98
Constructing the UI: Rich Page Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-100
Instructor Guide
V8.1
TOC
Copyright IBM Corp. 2013 Contents vii
Coding the business logic: Main JavaScript document . . . . . . . . . . . . . . . . . . . . 4-102
Adding a new environment (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-104
Adding a new environment (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-106
Android environment generated folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-108
Android environment folder structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-110
iPhone environment generated folders (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . 4-113
iphone environment folder structure (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-115
4.7. Building your application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-117
Building your application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-118
Building an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-120
4.8. Previewing and testing your application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-123
Previewing and testing your application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-124
Application preview and test tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-126
4.9. Previewing your application in the browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-129
Previewing your application in the browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-130
Previewing as a common resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-132
Previewing in the Mobile Browser Simulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-134
Mobile Browser Simulator: Android device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-136
Mobile Browser Simulator: iPhone device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-138
4.10. Testing on a simulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-141
Testing on a simulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-142
Testing on the Android emulator (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-144
Testing on the Android emulator (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-146
Testing on the iPhone simulator: Pre-requisites (1 of 2) . . . . . . . . . . . . . . . . . . . 4-148
Testing on the iPhone simulator: Pre-requisites (2 of 2) . . . . . . . . . . . . . . . . . . . 4-150
Testing on the iPhone simulator: Building and running an application (1 of 2) . . 4-152
Testing on the iPhone simulator: Building and running your application (2 of 2) 4-154
Testing on a device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-156
Testing on an Android device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-158
Testing on an iOS device: Pre-requisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-160
Testing on an iOS device pre-requisite: Enroll in the iOS Developer Program . . 4-162
Testing on an iOS device pre-requisite: Provision your device . . . . . . . . . . . . . . 4-164
Testing on an iOS device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-167
Publishing your application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-169
Publishing your application: Preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-171
Publishing your Android application in Google Play . . . . . . . . . . . . . . . . . . . . . . 4-173
Publishing your iPhone application in the App Store . . . . . . . . . . . . . . . . . . . . . . 4-175
Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-177
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-181
Exercise 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-183
Exercise objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-185
Unit 5. Client-side core APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
5.1. Client-side basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Client-side basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8
Instructor Guide
viii Mobile Application Development with IBM Worklight V6 Copyright IBM Corp. 2013
Application sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-10
Worklight initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-12
jQuery JavaScript framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-14
Worklight client JavaScript API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-16
The WL namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-18
WL.Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-20
WL.Logger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-22
WL.Logger - example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-24
5.2. Building a multi-page application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-27
Building a multi-page application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-28
Working with pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-30
Splitting code between HTML pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-33
Design considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-35
Loading an external HTML file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-37
Loading an external HTML file - example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-39
Implementing page navigation with history (1 of 4) . . . . . . . . . . . . . . . . . . . . . . . .5-41
5.3. Common controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-49
Common controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-50
What is a common control? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-52
WL.BusyIndicator (1 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-54
WL.SimpleDialog (1 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-60
WL.TabBar (1 of 5) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-66
WL.TabBar (2 of 5) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-68
WL.TabBar (3 of 5) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-70
WL.TabBar (4 of 5) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-72
WL.TabBar (5 of 5) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-74
WL.OptionsMenu (1 of 4) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-76
5.4. Skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-85
Skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-86
Skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-88
Skin use cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-90
Skin creation and packaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-92
Applying skins at run time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-94
Skin Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-96
5.5. Offline access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-99
Offline access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-100
Working in Offline Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-102
Explicit detection: using methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-105
Instructor Guide
V8.1
TOC
Copyright IBM Corp. 2013 Contents ix
Implicit Detection: offline/online events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-107
isConnected() and connect() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-110
getNetworkInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-112
Foreground event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-115
Worklight heartbeat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-117
5.6. String translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-119
String translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-120
Introduction to translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-122
Enabling translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-125
Translating system messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-128
Multi-language translation: set up the Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-130
Multi-language translation: selecting the language . . . . . . . . . . . . . . . . . . . . . . . 5-132
Detecting device locale and language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-134
Checkpoint questions (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-137
Checkpoint questions (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-139
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-141
Exploring IBM Worklight client-side APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-145
Unit 6. Local storage APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2
Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4
6.1. Encrypted cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7
Encrypted cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-8
What is encrypted cache? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10
Supported Browsers and Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12
Creating or opening encrypted cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-14
Encrypted cache status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-17
Opening encrypted cache example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-19
Reading and writing data with encrypted cache . . . . . . . . . . . . . . . . . . . . . . . . . . 6-21
Reading and removing data from encrypted cache . . . . . . . . . . . . . . . . . . . . . . . . 6-23
Closing encrypted cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-25
Destroying encrypted cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-27
Changing the encryption key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-29
6.2. JSONStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-31
JSONStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-32
What is JSONStore? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-34
Comparison of storage technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-36
JSONStore terminology: document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-39
JSONStore terminology: collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-42
JSONStore terminology: search field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-44
JSONStore terminology: query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-47
Store internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-49
Error object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-51
JSONStore architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-53
Sending data back . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-55
JSONStore API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-57
Instructor Guide
x Mobile Application Development with IBM Worklight V6 Copyright IBM Corp. 2013
Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-59
Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-62
Handling data locally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-64
Add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-66
Find . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-68
Sample app Find buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-70
Replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-72
Remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-74
Remove collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-76
Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-78
Advanced features: Security (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-80
Advanced features: Security (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-82
Advanced features: multiple user support (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . .6-84
Advanced features: multiple user support (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . .6-86
Advance features: adapter integration (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-88
Pushing and pulling changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-96
Example: getPushRequired . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-99
Example: push . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-101
Example: enhance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-103
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-105
Checkpoint questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-107
Checkpoint answers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-109
Exercise 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-115
Exercise objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-117
Unit 7. Working with UI frameworks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-2
The need for an application toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-4
Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-7
7.1. Working with UI frameworks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-9
Working with UI frameworks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-10
Working with UI frameworks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-12
7.2. Using jQuery Mobile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-15
Using jQuery Mobile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-16
jQuery Mobile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-18
Working with jQuery Mobile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-20
Adding jQuery to the Worklight application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-22
jQuery Mobile basic structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-24
jQuery Mobile widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-26
jQuery Mobile application screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-28
7.3. Sencha Touch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-31
Sencha Touch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-32
Working with Sencha Touch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-34
Instructor Guide
V8.1
TOC
Copyright IBM Corp. 2013 Contents xi
Adding Sencha Touch components to an application . . . . . . . . . . . . . . . . . . . . . . 7-36
Working with Sencha Touch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-38
7.4. Dojo Mobile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-41
Dojo Mobile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-42
What is Dojo? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-44
Addind Dojo Toolkit package to a project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-46
Deployment configuration with Ant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-48
Creating custom layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-50
Using a Dojo Mobile HTML template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-52
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-54
Checkpoint (objective only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-56
Checkpoint answers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-58
Unit 8. Apache Cordova. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2
Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4
8.1. Apache Cordova overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7
Apache Cordova overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-8
What is Apache Cordova? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-10
Apache Cordova referenced in the HTML file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-12
Apache Cordova library files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-14
Apache Cordova API basics: Cordova objects . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-16
Apache Cordova usage example: Displaying a native alert . . . . . . . . . . . . . . . . . 8-18
Apache Cordova usage example: Retrieving information . . . . . . . . . . . . . . . . . . . 8-20
8.2. Creating a plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-23
Creating a plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-24
Apache Cordova Plugin Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-26
Apache Cordova plugin architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-29
8.3. Creating a native plugin class for Android. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-31
Creating a native plugin class for Android . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-32
Implementing a plugin: Java class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-34
Plugin class execute() method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-36
8.4. Creating a native plugin class for iOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-39
Creating a native plugin class for iOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-40
Implementing the plugin: Objective-C class creation . . . . . . . . . . . . . . . . . . . . . . 8-42
Plugin class method: Input parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-44
8.5. Creating a plugin JavaScript wrapper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-47
Creating a plugin JavaScript wrapper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-48
Implementing the plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-50
Invoking the plugin from JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-53
HelloWorldPlugin example screen shots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-55
8.6. WebViewOverlay plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-57
WebViewOverlay plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-58
WebViewOverlay plugin: Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-60
WebViewOverlay plugin: Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-62
WebViewOverlay case study: Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-64
WebViewOverlay plugin: Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-66
WebViewOverlay Java implementation (1 of 4) . . . . . . . . . . . . . . . . . . . . . . . . . . 8-68
Instructor Guide
xii Mobile Application Development with IBM Worklight V6 Copyright IBM Corp. 2013
WebViewOverlay Java implementation (2 of 4) . . . . . . . . . . . . . . . . . . . . . . . . . . .8-70
WebViewOverlay Java implementation (4 of 4) . . . . . . . . . . . . . . . . . . . . . . . . . . .8-72
WebViewOverlay Cordova plugin (1 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-74
WebViewOverlay JavaScript implementation (1 of 2) . . . . . . . . . . . . . . . . . . . . . . .8-86
WebViewOverlay JavaScript implementation (2 of 2) . . . . . . . . . . . . . . . . . . . . . . .8-88
Modification to the code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-90
WebViewOverlay case study: Examining the result . . . . . . . . . . . . . . . . . . . . . . . .8-92
Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-94
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-96
Checkpoint answers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-98
Exercise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-100
Apache Cordova additional resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-104
Unit 9. Integration adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-2
Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-4
9.1. Adapters overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-7
Adapters - overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-8
Adapters: overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-10
Benefits of using adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-12
IBM Worklight Adapter Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-14
Anatomy of a Worklight adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-17
Adapter procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-19
Creating an adapter (1 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-21
Adapter deployment (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-27
Adapter deployment (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-29
Testing adapter procedures (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-31
Testing adapter procedures (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-33
Adapter structure: XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-35
Adapter structure: JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-38
9.2. SQL adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-41
SQL adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-42
Worklight SQL adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-44
Creating a Worklight SQL adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-46
XML file database connectivity settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-48
JavaScript file procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-51
JavaScript file SQL query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-53
JavaScript file stored SQL procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-56
WL adapters invocation result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-58
9.3. HTTP adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-61
HTTP adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-62
Worklight HTTP adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-64
Create an HTTP adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-66
Instructor Guide
V8.1
TOC
Copyright IBM Corp. 2013 Contents xiii
XML file connectivity settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-68
JavaScript file procedure implementation overview . . . . . . . . . . . . . . . . . . . . . . . 9-71
Procedure declarations in the XML file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-74
JavaScript file procedures implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-76
XSL transformation filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-79
9.4. Using HTTP adapters with SOAP services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-81
Using HTTP adapters with SOAP services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-82
Creating a SOAP-based Service Request overview . . . . . . . . . . . . . . . . . . . . . . . 9-84
Creating a SOAP-based Service Request (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . 9-86
Creating a SOAP-based Service Request (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . 9-88
Service request invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-90
Full SOAP-based service invocation procedure example . . . . . . . . . . . . . . . . . . . 9-92
9.5. Cast Iron adapters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-95
Cast Iron adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-96
Worklight Cast Iron adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-98
Creating a Cast Iron adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-100
JavaScript file procedures implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-102
9.6. JMS adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-105
JMS adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-106
Java Message Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-108
Worklight JMS adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-110
Implementing procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-112
Connection properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-114
JMS adapter methods: reading messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-116
JMS adapter methods: writing messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-118
9.7. Invoking Java code from an adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-121
Invoking Java code from an adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-122
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-124
Adding custom Java classes to a project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-126
Adding custom Java classes to a project (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . 9-128
Adding a custom Java class to your project (2 of 2) . . . . . . . . . . . . . . . . . . . . . . 9-130
Invoking custom Java classes from adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-132
9.8. The InvocationData object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-135
The InvocationData object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-136
invocationData object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-138
Options object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-140
Bringing it all together . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-143
Invocation result (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-146
Invocation result (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-148
9.9. Invoking adapter procedures from Java code . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-151
Invoking adapter procedures from Java code . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-152
Invoking from Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-154
9.10. Server side scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-157
Server side scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-158
Server-side scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-160
Server-side API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-162
Mashups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-164
Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-166
Instructor Guide
xiv Mobile Application Development with IBM Worklight V6 Copyright IBM Corp. 2013
Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-168
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-170
Exercise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-174
Unit 10. Native and web page integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-2
Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-4
10.1. Overview of native and web page integration. . . . . . . . . . . . . . . . . . . . . . . . . . . .10-7
Overview of native and web page integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-8
Limitations of web technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-10
Combining native and web pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-12
How does it work? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-14
10.2. Combining native and web pages on Android . . . . . . . . . . . . . . . . . . . . . . . . . .10-17
Combining native and web pages on Android . . . . . . . . . . . . . . . . . . . . . . . . . . .10-18
Native on Android: Activity class and manifest definition . . . . . . . . . . . . . . . . . . .10-20
Native on Android: Receiving data from the web page . . . . . . . . . . . . . . . . . . . . .10-22
Native on Android: Returning control to the web page . . . . . . . . . . . . . . . . . . . . .10-24
Native on Android: Animating transitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-26
Web page on Android: Invoking the native page . . . . . . . . . . . . . . . . . . . . . . . . .10-28
10.3. Combining native and web pages on iOS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-31
Combining native and web pages on iOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-32
Native on iOS: UIViewController subclass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-34
Native on iOS: Receiving data from the web page . . . . . . . . . . . . . . . . . . . . . . . .10-36
Native on iOS: Returning control to the web page . . . . . . . . . . . . . . . . . . . . . . . .10-38
Native on iOS: Animating web to native transitions . . . . . . . . . . . . . . . . . . . . . . .10-40
Web page on iOS: Invoking the native page . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-42
Web page on IOS: Receiving data from the native page . . . . . . . . . . . . . . . . . . .10-44
Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-46
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-48
Exercise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-52
Unit 11. Using Worklight native APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-2
Worklight native API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-4
Why use native API capabilities? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-6
Creating a Worklight native API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-8
11.1. Android native API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-11
Android native API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-12
Android native API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-14
Editing wlclient.properties (Android) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-16
Configure an Android native application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-19
Initializing the WLClient - Android . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-21
MyConnectListener - Android . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-23
Invoking a procedure - Android . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-25
Instructor Guide
V8.1
TOC
Copyright IBM Corp. 2013 Contents xv
Processing a response: Android - MyInvokeListener . . . . . . . . . . . . . . . . . . . . . 11-27
Processing a response: Android - MyConnectListener . . . . . . . . . . . . . . . . . . . . 11-29
11.2. iOS native API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-31
iOS native API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-32
iOS native API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-34
Editing worklight.plist (iOS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-36
Configure an iOS native application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-39
Initializing the WLClient - iOS (1 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-41
Invoking a procedure - iOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-47
Processing a response: iOS - MyInvokeListener . . . . . . . . . . . . . . . . . . . . . . . . 11-49
Checkpoint questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-51
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-53
Unit 12. Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2
Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-4
Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-6
Authentication sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-9
Authentication entities: challenge handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-11
Authentication entities: authenticator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-13
Authentication entities: login module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-15
Authentication entities: authentication realms . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-17
Authentication entities: security tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-19
Authentication concepts and entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-21
Defining realms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-29
Defining login modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-31
Defining authenticators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-33
Defining security tests (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-36
Defining security tests (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-38
webSecurityTest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-40
mobileSecurityTest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-42
customSecurityTest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-44
Protecting adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-46
Protecting applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-48
Protecting static resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-51
12.1. Adapter-based authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-53
Adapter-based authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-54
Adapter-based authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-56
Adapter-based authentication process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-58
Configuring a realm on authenticationConfig.xml . . . . . . . . . . . . . . . . . . . . . . . . 12-60
Configuring a login module on authenticationConfig.xml . . . . . . . . . . . . . . . . . . 12-62
Configuring authenticationConfig.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-64
Instructor Guide
xvi Mobile Application Development with IBM Worklight V6 Copyright IBM Corp. 2013
Server-side authentication: components overview . . . . . . . . . . . . . . . . . . . . . . . .12-66
Server-side authentication components (1 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . .12-68
Invoking the protected function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-75
Client-side authentication : HTML AppDiv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-77
Client-side authentication : HTML AuthDiv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-79
Client-side authentication : challengeHandler . . . . . . . . . . . . . . . . . . . . . . . . . . .12-81
More challengeHandler functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-83
Creating client-side authentication components (8 of 11) . . . . . . . . . . . . . . . . . . .12-85
Create the Handler function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-87
Binding the AuthSubmitButton to a function . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-89
12.2. Custom login modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-91
Custom login modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-92
Session scope and additional modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-94
Custom authenticator overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-96
Configuring authenticationConfig.xml (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-98
Configuring authenticationConfig.xml (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . .12-100
Authenticator API (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-102
Authenticator API (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-104
Creating a custom Java authenticator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-106
Server library dependency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-108
Custom Java Authenticator: init() and clone() . . . . . . . . . . . . . . . . . . . . . . . . . . .12-110
Creating a custom Java Authenticator: overview . . . . . . . . . . . . . . . . . . . . . . . .12-112
Custom Java Authenticator: processRequest . . . . . . . . . . . . . . . . . . . . . . . . . . .12-114
processRequest: verify URL and credentials . . . . . . . . . . . . . . . . . . . . . . . . . . .12-116
processRequest: authenticationData object . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-118
processRequest: problem response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-121
processRequest: authentication not needed . . . . . . . . . . . . . . . . . . . . . . . . . . .12-123
processRequest: credentials required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-125
The login module API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-127
Creating a custom Java login module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-129
Login module: init and clone methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-131
Login module: login method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-133
Login module: createIdentity method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-135
Login module: logout and abort methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-137
Examining the Result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-139
12.3. WebSphere LTPA-based authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-141
WebSphere LTPA-based authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-142
WebSphere LTPA-based authentication introduction . . . . . . . . . . . . . . . . . . . . .12-144
Understanding server-side authentication options . . . . . . . . . . . . . . . . . . . . . . .12-146
Server-side authentication options: option 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-148
Server-side authentication options: option 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-150
Understanding server-side authentication options . . . . . . . . . . . . . . . . . . . . . . .12-152
Worklight invokes WAS security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-154
Authentication through WebSphere Application Server . . . . . . . . . . . . . . . . . . .12-156
Server-side authentication options: summary . . . . . . . . . . . . . . . . . . . . . . . . . . .12-158
Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-160
Instructor Guide
V8.1
TOC
Copyright IBM Corp. 2013 Contents xvii
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-162
Checkpoint answers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-164
Unit 13. Push notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-2
What are push notifications? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4
Device support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-7
Notification architecture terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-9
Notification architecture: subscription (1 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-11
Sending notifications: overview (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-17
Sending notifications: overview ( of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-19
Sending notifications (1 of 4) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-21
Subscription management: user subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-29
Subscription management: device subscription . . . . . . . . . . . . . . . . . . . . . . . . . 13-31
Notification API: server side (1 of 10) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-33
Notification API: server side (10 of 10) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-51
Notification API: client side (1 of 4) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-53
Setup: Android . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-62
Setup: iOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-64
Setup: Windows Phone 8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-66
Edit application-descriptor.xml (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-68
Edit application-descriptor.xml (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-70
PushBackendEmulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-72
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-74
Checkpoint questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-76
Checkpoint (objective only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-80
Exercise 8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-84
Instructor Guide
xviii Mobile Application Development with IBM Worklight V6 Copyright IBM Corp. 2013
Unit 14. Device analytics reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-2
Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-4
Device analytics introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-6
Introducing reports and analytics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-8
Enabling raw data reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-10
Device analytics: raw data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-12
APP_ACTIVITY_REPORT table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-14
APP_ACTIVITY_REPORT ACTIVITY column . . . . . . . . . . . . . . . . . . . . . . . . . . .14-16
Device usage reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-18
activities_cube table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-20
Notification_report table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-22
proc_report table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-24
Summary: relationship of the tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-26
Processing interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-28
BIRT reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-30
BIRT reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-32
Installing BIRT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-34
Exploring BIRT in Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-36
Viewing reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-38
Report types: environment access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-40
Report types : daily visits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-42
Report types : unique devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-44
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-48
Unit 15. Direct update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-2
What is direct update? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-4
The advantages of direct update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-6
The restrictions of direct update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-8
Version detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-10
Direct update: distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-12
Disabling old app versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-14
Checkpoint questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-16
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15-18
Unit 16. Migrating an application from development to production . . . . . . . . . . . .16-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-2
16.1. Overview of application management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-5
Overview of application management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-6
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-8
Steps in the process of remote deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-10
Architecture of deployment (1 of 6) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-12
Instructor Guide
V8.1
TOC
Copyright IBM Corp. 2013 Contents xix
Architecture of deployment (4 of 6) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-18
16.2. Worklight Apache Ant utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-25
Worklight Apache Ant utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-26
Worklight Apache Ant utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-28
Apache Ant basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-30
Adding a reference to Worklight Ant jar file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-32
Ant task: application builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-34
Ant task: application deployer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-36
16.3. IBM Worklight Server installation and configuration overview. . . . . . . . . . . . . . 16-39
IBM Worklight Server installation and configuration overview . . . . . . . . . . . . . . . 16-40
Worklight Server overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-42
Worklight Server runtime architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-44
IBM Worklight Server installation: Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . 16-46
Configuring Worklight Server resources in WebSphere Application Server . . . . 16-48
16.4. Application migration: Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-51
Application migration: Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-52
Application migration overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-54
Application migration process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-57
16.5. Application migration: Preparing your application . . . . . . . . . . . . . . . . . . . . . . . 16-61
Application migration: Preparing your application . . . . . . . . . . . . . . . . . . . . . . . . 16-62
Adjusting the worklight.properties file: Database settings . . . . . . . . . . . . . . . . . . 16-64
Adjusting the worklight.properties file: Server access settings . . . . . . . . . . . . . . 16-66
Adjusting configuration files: Best practice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-68
Building the project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-70
16.6. Application migration: Deploying your application. . . . . . . . . . . . . . . . . . . . . . . 16-73
Application migration: Deploying your application . . . . . . . . . . . . . . . . . . . . . . . . 16-74
Deploying the applications Worklight server WAR file . . . . . . . . . . . . . . . . . . . . 16-76
Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-78
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-80
Unit 17. Shell development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-2
Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-4
17.1. shell component concepts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-7
shell component concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-8
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-10
Architecture of a shell-based application (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . 17-13
Architecture of a shell-based application (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . 17-16
Creating a shell component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-18
shell component file structure (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-20
shell component file structure (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-22
shell-descriptor.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-25
17.2. Creating and using a shell component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-27
Creating and using a shell component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-28
Using the shell component in a test application (1 of 3) . . . . . . . . . . . . . . . . . . . 17-30
Instructor Guide
xx Mobile Application Development with IBM Worklight V6 Copyright IBM Corp. 2013
Using the shell component in a test application (2 of 3) . . . . . . . . . . . . . . . . . . . .17-32
Using the shell component in a test application(3 of 3) . . . . . . . . . . . . . . . . . . . .17-34
Creating and using a shell bundle (1 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17-36
Creating and using a shell bundle (2 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17-38
Creating and using a shell Bundle (3 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17-40
17.3. Android shell development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17-43
Android shell development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17-44
Adding an Android environment to the shell component . . . . . . . . . . . . . . . . . . .17-46
Android shell component file structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17-48
Adding an Android environment to shell component . . . . . . . . . . . . . . . . . . . . . .17-50
Adding custom Java code to shell component (1 of 5) . . . . . . . . . . . . . . . . . . . . .17-53
Using the NativeEmptyApp Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17-63
Using the NativeEmptyApp Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17-65
17.4. iOS shell development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17-67
iOS shell development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17-68
Adding an iOS environment to shell component . . . . . . . . . . . . . . . . . . . . . . . . . .17-70
Adding Objective-C code to shell component (1 of 5) . . . . . . . . . . . . . . . . . . . . .17-77
Using the nativeEmptyApp Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17-87
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17-92
Unit 18. IBM Application Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-2
What is IBM Worklight Application Center? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-4
Typical scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-6
Application Center architecture (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-8
Application Center architecture (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-11
Application Center configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-13
Application Center user configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-15
Applications view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-17
Application details view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-19
Available applications view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-22
Feedback and rating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-24
Setting access control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-26
Registered devices view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-28
Application Center client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18-30
Installing an application from the mobile client (1 of 2) . . . . . . . . . . . . . . . . . . . . .18-32
Instructor Guide
V8.1
TOC
Copyright IBM Corp. 2013 Contents xxi
Installing an application from the mobile client (2 of 2) . . . . . . . . . . . . . . . . . . . . 18-34
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-36
Exercise 9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-38
Unit 19. Course summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-1
Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-2
Course learning objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-4
References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-6
Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-8
Appendix 20. List of abbreviations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-1
Instructor Guide
xxii Mobile Application Development with IBM Worklight V6 Copyright IBM Corp. 2013
Instructor Guide
Copyright IBM Corp. 2013 Trademarks xxiii
V8.1
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:
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.
AIX AS/400 BigFix
Cast Iron DB DB2
Domino FileNet Lotus Notes
Lotus Notes PureApplication
Rational Redbooks WebSphere
Instructor Guide
xxiv Mobile Application Development with IBM Worklight V6 Copyright IBM Corp. 2013
Instructor Guide
Copyright IBM Corp. 2013 Instructor course overview xxv
V8.1
pref
Instructor course overview
This course enables the students to acquire the skills necessary to use
IBM Worklight V6 to develop mobile applications that run on an
Android or iOS* environment.
The lab environment for this course uses the Google Android platform,
running on a Microsoft Windows virtual machine.
Course strategy
Teaching strategy
Each classroom session uses a combination of facilitated lecture,
discussions, group exercises, and demonstrations to convey the
material.
Introduce the material
Inform the students of the objectives of the unit and topic. Give them a
brief scenario that helps them understand how the presented material
helps them do their jobs.
Facilitate the learning experience
Involve the students in the learning process. Ask them questions and
present classroom scenarios in which students use the available
resources to solve situations that involve process, procedure, or
content on the job.
Review the material
Review objectives at the conclusion of each unit to ensure that the
students have a thorough understanding of the material.
Group exercises and labs are used to reinforce knowledge and skills
that the students learned in the previous classroom topics. The
instructor serves as a mentor in checking results, answering
questions, and providing constructive feedback and evaluation.
Course evaluation
Evaluation measures the quality, effectiveness, and impact of the
course. It enables students to answer the question, "Does the course
meet its requirements and objectives?"
For all classes, students will provide feedback on course quality by
completing an end-of-course questionnaire.
Measurement plan
Instructor Guide
xxvi Mobile Application Development with IBM Worklight V6 Copyright IBM Corp. 2013
No formal tests are administered in the class.
Course materials
Student Notebook
Instructor Guide
PowerPoint visuals in PDF form
Student Exercises
Instructor Exercises Guide
Lab Setup Guide
Instructor Preparation document
Summary of changes in this edition
This is a new course.
Instructor Guide
Copyright IBM Corp. 2013 Course description xxvii
V8.1
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
Instructor Guide
xxviii Mobile Application Development with IBM Worklight V6 Copyright IBM Corp. 2013
Use IBM Worklight client-side APIs for cross-platform portability
Use the Apache Cordova framework to access native device
functions
Use IBM Worklight server-side APIs for back-end integration
Include the Dojo Mobile, jQuery Mobile or Sencha Touch UI
frameworks in an application
Secure a mobile application using different IBM Worklight
authentication techniques
Manage application updates and versions
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)
Instructor Guide
Copyright IBM Corp. 2013 Agenda xxix
V8.1
pref
Agenda
Day 1
(00:30) Welcome
(00:30) Unit 1 - Mobile overview
(00:45) Unit 2 - Designing mobile solutions
(01:00) Unit 3 - Introduction to IBM Worklight V6
(01:00) Unit 4 - Overview of Worklight Studio
(01:30) Exercise 1- Installing IBM Worklight Studio and developing
your first application
(01:15) Unit 5 - IBM Worklight client-side development: Core APIs
Day 2
(01:15) Exercise 2 - Exploring client-side core APIs
(01:00) Unit 6 - IBM Worklight client-side development: Local storage
APIs
(01:00) Exercise 3 - Exploring local storage APIs
(00:30) Unit 7 - Working with UI frameworks
(01:00) Unit 8 - Apache Cordova
(01:00) Exercise 4 - Using Apache Cordova to access native device
functions
(01:00) Unit 9 - Worklight integration adapters
Day 3
(01:15) Exercise 5 - Developing a Worklight integration adapter
(00:30) Unit 10 - Native and web page integration
(01:00) Exercise 6 - Combining native and web pages
(00:30) Unit 11 - Using Worklight native APIs
(00:30) Unit 12 - Security
(01:30) Exercise 7 - Securing an application
(01:00) Unit 13 - Push notification
Instructor Guide
xxx Mobile Application Development with IBM Worklight V6 Copyright IBM Corp. 2013
Day 4
(01:00) Exercise 8 - Exploring the push notification API
(00:30) Unit 14 - Device analytics reporting
(00:30) Unit 15 - Direct update
(01:00) Unit 16 - Migrating an application from development to
production
(00:45) Unit 17 - Shell development
(00:45) Unit 18 - IBM Worklight Application Center
(01:00) Exercise 9 - Exploring the Application Center
Instructor Guide
Copyright IBM Corp. 2013 Unit 1. Mobile overview 1-1
V8.1
Uempty
Unit 1. Mobile overview
Estimated time
00:30
What this unit is about
This unit explains the challenges of mobile development and
describes how IBM mobile solution offerings address them. In
particular, you learn about the IBM Mobile Foundation offering, which
has IBM Worklight V6.0 at its core, and its value-proposition.
What you should be able to do
After completing this unit, you should be able to:
Explain the challenges of mobile application development,
management, and security
Describe the goal of IBM mobile solution offerings
Identify IBM Worklight V6 as a key part of the mobile solutions
strategy that IBM offers
How you will check your progress
Checkpoint
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
Instructor Guide
1-2 Mobile Application Development with IBM Worklight V6 Copyright IBM Corp. 2013
Figure 1-1. Unit objectives WU5061.0
Notes:
Copyright IBM Corporation 2013
Unit objectives
Identify IBM Worklight V6 as a key part of the mobile solutions strategy
that IBM offers
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose List the unit objectives
Details
Additional information
Transition statement
Instructor Guide
Figure 1-2. Topics WU5061.0
Notes:
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose List the topics in this unit
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 1.1. Becoming a mobile enterprise
Instructor topic introduction
Instructor Guide
Figure 1-3. Becoming a mobile enterprise WU5061.0
Notes:
Becoming a mobile
enterprise
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Introduce the topic
Details
Instructor Guide
Figure 1-4. Why go mobile? WU5061.0
Notes:
Note
*BYOD: bring your own device.
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*
Leverage technologies to meet increased demands
Gain new insights that you can only get through mobile
*Bring your own device
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Additional information IBM MobileFirst begins with a mindset: Innovative enterprises
see the opportunities gained by bringing all resources together to strengthen customer
engagement-whenever and wherever the customer wants, and on the customer's favorite
device, which is often mobile.
Whether transforming your customer acquisition strategies, streamlining your
business process, or boosting product and service innovations, you can accomplish more
by focusing on mobile computing environments first.
IBM MobileFirst offers you true end-to-end mobile solutions. Some providers specialize
in service offerings; some focus on platform and application development; some offer only
mobile security; while others focus just on mobile device management. We bring it all.
We help your customers initiate transactions at the moment of awareness. You can
encourage customer-building touchpoints and deepen relationships with your
customers with realtime, one-to-one engagements. Learn what they want with powerful
mobile analytics and usage data, then create more compelling interactions.
We can also help you increase workforce productivity through mobile apps that enhance
collaboration, improve knowledge sharing, and speed responses. Gain efficiency by
extending existing business capabilities and applications to mobile workers, partners, and
customers.
Instructor Guide
Figure 1-5. Demand for mobility WU5061.0
Notes:
*The 2012 IBM Tech Trends Report
ftp://public.dhe.ibm.com/common/ssi/ecm/en/xie12346usen/XIE12346USEN.pdf
Demand for mobility
As of 2013, there are 4 billion mobile phones; 9.6
billion connected devices (the Internet of things)
1 billion smart phones
3 billion SMS enabled
90 percent of all phones in Africa are mobile
18 million people use mobile phones as a bank
Mobility can be business to consumer (B2C) or
business to employee (B2E)
As well as B2B, C2C, and many others
B2C: Offers easier purchase and support options, online
banking, and so forth
B2E: Provides access to internal systems for employees
Over the next two years, nearly 70 percent of
organizations are increasing their investments in
mobile technology*
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Additional information These stats are taken from IBM Impact 2013 general sessions
keynote presentations. The last bullet is from the IBM Tech Trends report.
Instructor Guide
Figure 1-6. Mobile platforms WU5061.0
Notes:
*Gartner report - Market Share Analysis: Mobile Phones, Worldwide, 1Q13.
http://www.gartner.com/document/2482415?ref=QuickSearch&sthkw=G00252860
Mobile platforms
Android has 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%
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 1.2. Challenges of mobile application development,
management and security
Instructor Guide
Figure 1-7. Challenges of mobile application development, management and security WU5061.0
Notes:
Challenges of mobile
application
development,
management and
security
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 1-8. Considerations for mobile (1 of 2) WU5061.0
Notes:
Considerations for mobile (1 of 2)
User experience
Different mobile platforms have different capabilities
It is tempting to use a highest-common-factor approach where only those
elements common to all platforms are used
Native, Web, hybrid: which can be developed in the least time?
Native gives the best performance but
It limits the results to one platform
Development requires specialized knowledge
Authentication and security
Smaller devices are more portable and therefore can be lost or stolen more
easily
The device may be logged on to a secure internal company area
The device may have sensitive data that has been decrypted at the moment the
device is lost
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 1-9. Considerations for mobile (2 of 2) WU5061.0
Notes:
Considerations for mobile (2 of 2)
Manage mobile applications
The applications sit on remote devices: how to update them to new versions?
An application may no longer have backend support: how to warn the user?
If a business to employee application is the preferred way for the
employee to interact with the company who pays for, and owns, the
device?
Traditionally, the company owns the laptop the employee uses
The latest trend is BYOD: bring your own device
Development lifecycles are more complicated
There are now new issues to deal with:
The number of platforms that must be accommodated is greater than before
The download of given information may depend on the geographic location of
the device
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 1-10. Advantages of mobile communication WU5061.0
Notes:
Advantages of mobile communication
B2C
Increased ease for the customer to do business such as banking, or stock
trading
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 1-11. Characteristics of mobile interactions WU5061.0
Notes:
Characteristics of mobile interactions
Usually short and focused
Get on, get information, get off
Screen display is compact, and so the user interface must be intuitive
Minimal typing should be necessary
Devices are most often touch based, and so conveniences such as
hover and the pointing finger are not available
Many applications need to be function even when the user is out of
wireless coverage
A cell phone can operate even if the user is moving, but not if they move out of
range
A wireless laptop connection is specific to one location (which may be an entire
building)
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 1.3. Types of mobile applications
Instructor Guide
Figure 1-12. Types of mobile applications WU5061.0
Notes:
Types of mobile
applications
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 1-13. The choice WU5061.0
Notes:
Native
code
Native
code
The choice
HTML5
CSS3
JavaScript
HTML5
CSS3
JavaScript
Web application
Hybrid
application
Native
application
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 1-14. Development approaches WU5061.0
Notes:
Development approaches
Web
application
Mobile web
application
Hybrid mobile
application
Native mobile
application
Desktop and
mobile using
open standards
programming
model
No device-
specific
function
Targets mobile
devices that
use open
standards web
client
programming
model
Offline
capabilities
Mobile only
Application runs
on the device
Uses of an open
web client model
with a JavaScript
bridge to access
native device
features
Mobile using
only native
languages
Native
appearance,
device
capabilities, and
performance
<--Mobile browser execution--> <--App store download-->
Richer presentation possibilities
Increasing maintenance costs
Greater portability
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 1-15. Native compared to hybrid applications WU5061.0
Notes:
Native compared to hybrid applications
Native:
Available only through the App Store for a particular platform
Development technologies specific to the device
Requires a licensing agreement
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 1-16. Web standards WU5061.0
Notes:
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 have been 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
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 1-17. SOA to mobile WU5061.0
Notes:
SOA to mobile
Business
process
Components
JAX-RS
Java EE
Services
SOA BPM JEE
Mobile
web 2.0
Enterprise
services
Business
services
RESTful
services
Enterprise
data
Process
data
Application
data
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 1.4. Overview of IBM mobile strategy
Instructor Guide
Figure 1-18. Overview of IBM mobile strategy WU5061.0
Notes:
Overview of IBM mobile
strategy
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 1-19. IBM MobileFirst WU5061.0
Notes:
IBM MobileFirst
Mobile is becoming the first point of contact between an individual and
an organization
Mobile interactions need to be instant, seamless, and insightful
The systems that users interact with must be designed around mobile
first
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 1-20. IBM MobileFirst portfolio WU5061.0
Notes:
IBM MobileFirst portfolio
Provides end-to-end solutions
Strategy and design services
Platform:
IBM Worklight
IBM Mobile Development Lifecycle Solution
Management:
IBM Endpoint Manager for Mobile Devices
Mobile Enterprise Services for Managed Mobility
Security
Analytics:
IBM Tealeaf CX Mobile
IBM Digital Analytics
Development and integration services
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 1.5. IBM Mobile Foundation V6.0
Instructor Guide
Figure 1-21. IBM Mobile Foundation V6.0 WU5061.0
Notes:
IBM Mobile Foundation
V6.0
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 1-22. IBM MobileFirst platform WU5061.0
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.
IBM MobileFirst platform
IBM Worklight
IBM WebSphere Cast Iron
IBM MessageSight
IBM Rational Test Workbench
IBM Web Experience Solutions
IBM Lotus Domino Designer
IBM WebSphere MQ
Instructor Guide
V8.1
Uempty
Deliver faster and improve team productivity with collaborative, integrated capabilities for
mobile app development.
IBM Rational Test Workbench
Automated testing for high-quality mobile apps.
IBM Web Experience Solutions
Create personalized, content-rich multichannel experiences for customers and employees
easily and cost-effectively.
IBM Lotus Domino Designer
Provides a Web and mobile app development platform that enables IBM Lotus Notes
applications to be used with browser clients on mobile devices.
IBM WebSphere MQ
A universal messaging backbone, enables rapid, reliable, and secure transport of
messages and data between applications, systems, services and extended devices.
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 1-23. IBM Mobile Foundation WU5061.0
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.
Brings together key mobile capabilities into a single integrated package
that includes:
IBM Worklight: An application platform for smartphones and tablets that helps
organizations to develop, run and manage HTML5, hybrid and native mobile
applications
IBM Endpoint Manager: Built on BigFix
*
technology that addresses the issues of
security, complexity and BYOD policies required to support an increasingly
mobile workforce
WebSphere Cast Iron Hypervisor Edition: An integration framework that enables
companies to rapidly connect their hybrid world of public clouds, private clouds,
and on-premise applications
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 1-24. IBM Worklight WU5061.0
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
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
Eases connectivity and synchronization with enterprise data,
applications and cloud services
Provides security at the device, application and network layer
Allows governance of mobile app portfolio from a central interface
Application distribution and version management
Direct update
Manage push notifications
Monitor usage through analytics and reporting
High availability and private cloud deployment options (WebSphere Application
Server, PureApplication Systems)
Instructor Guide
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)
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 1-25. WebSphere Cast Iron Hypervisor Edition WU5061.0
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
WebSphere Cast Iron Hypervisor Edition
Cloud and Software as a Service (SaaS) to on-premise application and
mobile application integration in days
Installation on your organization's preferred hardware to conform to
your data center's virtualization strategy
A graphical, configuration-not-coding interface approachrather than
custom coding, on-demand tooling or traditional middlewareto help
you integrate applications quickly and simply
Reduced error recovery procedures (ERP) licensing costs by
eliminating the need for cloud users to log into back-office applications
Available in Development, Enterprise and Standard editions, with fixed
term or license options
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 1-26. IBM Endpoint Manager for Mobile Devices WU5061.0
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.
IBM Endpoint Manager for Mobile Devices
Helps you address the issues of security, complexity and bring your
own device (BYOD) policies that challenge support for an increasingly
mobile workforce
Safeguards enterprise data with advanced security and compliance
features
Provides enterprise visibility with a consolidated inventory of employee-
and corporate-owned devices
Provides a unified management infrastructure by using a single
platform to manage all your enterprise devices
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 1-27. Checkpoint questions WU5061.0
Notes:
Write your answers here:

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
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Checkpoint questions to verify understanding
Details These questions should be multiple choice, true/false or sequencing only so
they can be repurposed in SPVC e-learning.
Instructor Guide
Figure 1-28. Unit summary WU5061.0
Notes:
Unit summary
Having completed this unit, you should be able to:
Identify IBM Worklight V6 as a key part of the mobile solutions strategy
that IBM offers
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Summarize the learning points in the unit
Details This can either be a repeat of the unit objectives or another form of summary of
the learning points
Instructor Guide
Figure 1-29. Checkpoint answers WU5061.0
Notes:
Checkpoint answers
1. Of the six mobile platforms 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 only uses HTML5, CSS, JavaScript; native only uses coding
specific to the device; hybrid mixes the two.
3. List the three parts of IBM Mobile Foundation
Worklight, Endpoint Manager, Cast Iron
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
Copyright IBM Corp. 2013 Unit 2. Designing mobile solutions 2-1
V8.1
Uempty
Unit 2. Designing mobile solutions
Estimated time
00:45
This unit describes the different approaches used for building mobile
applications. It explains the available technology and design options,
and identifies the situations appropriate for each option.
Compare the advantages and disadvantages of different mobile
application designs
Identify a mobile application design suitable for an application
Checkpoint
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
Instructor Guide
Notes:
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013
Unit objectives
application designs
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Notes:
Topics
Approaches to mobile design
Comparison of mobile application designs
Choosing the right approach
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 2-3. Three approaches WU5061.0
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.
Three approaches
100101010101
110100010100
100101011101
000100010010
Device APIs
Mobile
browser
<!DOCTYPE ht
<html>
<head>
<title>Web App
</title></head>
<body onload =
native
container
Device APIs
Native
application
Web
application
Hybrid
application
WEB CODE
<!DOCTYPE ht
<html>
<head>
WEB CODE
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 2-4. Web, hybrid, native... WU5061.0
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
Web, hybrid, native
The decision as to which mobile strategy to develop is based on many
parameters:
Budget
Timeframe
Target audience
Required functionality
Each approach has advantages and disadvantages
The challenge is to balance the pros and cons
This module does not identify any recommended approach but looks at
the reasons for each, and lists the good and the less good
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 2.1. Approaches to mobile design
Instructor Guide
Figure 2-5. Approaches to mobile design WU5061.0
Notes:
Approaches to mobile
design
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 2-6. Native applications WU5061.0
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
Native applications
Binary executable file stored locally on the device
Usually downloaded from an App Store
Apple App Store
Android Market, Google Play
BlackBerry App World
And others
Specific to a type of device
After downloading, the application interfaces directly with the device
operating system
The application can access all native APIs of the device
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 2-7. Creating a native application WU5061.0
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.
Creating a native application
The source code for the application is written in a high level language:
Apple iOS Objective-C, C, C++
Android: Java
BlackBerry: Java
Windows Phone: C#, VB,.NET
The source is compiled into an executable binary file
The OS vendor usually provides the tools to do this
Called the Software Development Kit (SDK)
The SDK is platform specific
Apple iOS: Xcode
Android: Android SDK
BlackBerry: BB Eclipse plug-in
Windows Phone: Visual Studio, Windows Phone Development Tools
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 2-8. Mobile-web Applications - HTML5 WU5061.0
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.
Mobile-web Applications HTML5
While HTML4.2 was a page display language, HTML5 is a more
complete environment for browser-based applications
Some new things available in HTML5:
Advanced UI components
Access to rich media types
Geolocation services
Offline availability
New audio capabilities
A mobile-optimized web site can detect when the client is a
Smartphone and respond with an appropriate page
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 2-9. Mobile-web Applications - CSS3 WU5061.0
Notes:
This will of course change over time. The number four is correct as of June, 2012.
Mobile-web Applications CSS3
Cascading Style Sheets were originally intended to separate
presentation elements from content elements
CSS3 divides the specification into modules. Four have been published
as formal recommendations:
Media Queries
Used to tailor output to a device or range of devices
Namespaces
Selectors can be defined by namespace and local name
Selectors
Query the DOM by tag name, attributes, id
Color
Including transparency
Level 3 is still in the process of being defined
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 2-10. Mobile-web Applications - JavaScript WU5061.0
Notes:
Mobile-web Applications JavaScript
Client-side JavaScript adds behavior to web content
Typically works with the Document Object Model in order to interact
with the presentation of a page
Worklight Studio automatically creates a JavaScript file with the same
name as the application
There are a number of frameworks that use JavaScript libraries and
target mobile applications:
jQuery
Sencha
Dojo Mobile
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 2-11. Mobile web applications - mobile web sites WU5061.0
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.
Mobile web applications mobile web sites
Feature Mobile web app Mobile web site
Tools and
knowledge
HTML, CSS, JavaScript
Execution
Installed shortcut, launched
like a native app.
URL
User experience Interactive UI
Navigational UI between
pages displaying static data
Performance
UI logic is local. Responsive
and accessible offline
Code executed on server:
network-dependent
performance
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 2-12. Hybrid applications (1 of 2) WU5061.0
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.
Hybrid applications (1 of 2)
There are many things in a web design that will be 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
The hybrid approach combines native development and web
technology
This approach requires a bridge between the native environment and
the web environment
Apache Cordova is one solution that is readily available developers
can use it instead of creating their own bridge
Instructor Guide
V8.1
Uempty
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 2-13. Hybrid applications (2 of 2) WU5061.0
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
Hybrid applications (2 of 2)
The web part of a hybrid application can be
A web page stored on a server and accessed like any traditional web page
A package of files stored locally on a device
HTML, JavaScript, CSS, media files, text files, and so forth
Server storage allows the developer to make modifications to the page
code without having to go through the process of submission required
for an App Store
However, offline availability is not an option if the page must be accessed from a
server
Local storage is more flexible and can offer better performance
However, remote update is not an option
Instructor Guide
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.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 2.2. Comparison of mobile application designs
Instructor Guide
Figure 2-14. Comparison of mobile application designs WU5061.0
Notes:
Comparison of mobile
application designs
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 2-15. Native - advantages and disadvantages WU5061.0
Notes:
Scenarios for the native approach include:
Existing native skills
A single mobile OS
Native functionality
Rich UI requirements
Native - advantages and disadvantages
Native code performs fast
Complete access mean that all device functions can be included in an
application
The critical disadvantage of pure native development is that the code is
not portable across platforms
Development effort may have to be repeated for each platform
Costly, time-consuming
Because each platform has a unique set of APIs, the developer needs
to be familiar with a wide range of languages
Or the company needs a wide range of specialized developers
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 2-16. Web application - advantages and disadvantages WU5061.0
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
Web application advantages and disadvantages
Multi-platform support
Low cost of development
Runs in the browser, but only has very limited access to the APIs of the
device through the browser
Scenaries for the web approach include:
Direct distribution
Pilot app
Visibility
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 2-17. Hybrid applications WU5061.0
Notes:
Scenarios for the hybrid approach include:
Balancing the tradeoff
In-house skills
Future considerations
Hybrid applications
Multi-platform support
Medium cost of development
There may still be need to code in a native device language
Not all device functionality will be available
A bridge is needed to access native mobile device features and
execute native code using JavaScript
Typically, Apache Cordova
Scenarios for the hybrid approach include:
Balancing the tradeoff
In-house skills
Future considerations
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 2-18. Comparison of features WU5061.0
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.
Comparison of features
Feature Native Web Hybrid
Development
language
Native only Web only
Native and web,
or web only
Code portability and
optimization
No Yes
Access to device-
specific features
Yes Almost none
Some, through
a bridge
Take advantage of
web expertise
No Yes
Advanced graphics Yes Some
Upgrade flexibility Low (App Store) High
Medium (usually
App Store)
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 2.3. Choosing the right approach
Instructor Guide
Figure 2-19. Choosing the right approach WU5061.0
Notes:
Choosing the right
approach
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 2-20. Scenario - the native approach WU5061.0
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.
Scenario the native approach
An organization may have in-house expertise for a particular platform
For example, a company may issue an Android device to all
employees, and have developers who can code in Java for the Android
platform
The company would have a policy that the employee must use the issued
device. There is therefore no need to develop code for other platforms, or to
have common code
Some applications target a specific functionality that cannot be
accessed in any other way than natively
For example, Skype (VoIP)
For real-time responsiveness and complex user interface requirements,
the native approach is the only adequate solution
Games, for example
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 2-21. Scenario - the web approach WU5061.0
Notes:
Scenario the web approach
An organization may want to control the distribution of its applications
internally, without having to submit them for approval through an App
Store
The application may begin as a pilot, simply to prove a concept
A fully native application will be more difficult to develop
Therefore it will take longer and be more expensive
Once the concept has been finalized the existing application can be
either adapted to native (rewritten) or can form the basis of a hybrid
application
This would build on the proven concept by adding native functionality
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 2-22. Scenario - the hybrid approach WU5061.0
Notes:
Scenario the hybrid approach
An organization needs to create a mobile web presence rapidly
There is no particular need for fast response within the application
Native functionality is not required, or very little required
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
The application can rapidly be distributed to all platforms, giving a good
return on investment
It can also be maintained very easily
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Notes:

1. What are the three approaches for creating mobile web applications?
2. Which of these statements is not correct?
a) A native application is specific to a platform
b) A web application is specific to a platform
c) A hybrid application may be specific to a platform
3. Name some of the new features of HTML5
4. True of false: A web page stored on a server can be part of a mobile
web application
5. True or false: A hybrid application combines HTML, JavaScript and a
native language
Instructor Guide
V8.1
Uempty
Instructor notes:
Instructor Guide
Notes:
Unit summary
application designs
Instructor Guide
V8.1
Uempty
Instructor notes:
the learning points
Instructor Guide
Notes:
Checkpoint answers
1. What are the three approaches for creating mobile web applications?
Native, web, hybrid
2. Which of these statements is not correct?
b) A web application is specific to a platform
3. Name some of the new features of HTML5
Advanced UI components
Access to rich media types
Geolocation services
Offline availability
New audio capabilities
and others...
4. True of false: A web page stored on a server can be part of a mobile
web application
true
5. True or false: A hybrid application combines HTML, JavaScript and a
native language
true
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
Copyright IBM Corp. 2013 Unit 3. Introduction to IBM Worklight v6.0 3-1
V8.1
Uempty
Unit 3. Introduction to IBM Worklight v6.0
Estimated time
01:00
This unit introduces IBM Worklight V6 by describing its packaging and
component architecture. It also provides an overview of the
development and management capabilities of IBM Worklight.
Differentiate the IBM Worklight V6 product packages
Explain the IBM Worklight V6 component architecture
Describe the development and management capabilities of IBM
Worklight V6
Checkpoint
References
Instructor Guide
Notes:
Unit objectives
Worklight V6
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Notes:
Note: this module gives a general overview of these topics. They are discussed in depth in
further units.
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Details Do not spend much time or do into much detail in this unit. As the student note
says, this is a high-level view of Worklight in general, intended to give an idea of the scope
of the software.
The two parts you may want to call out are component architecture and code optimization.
For component architecture, it is important that students get a feel for how things fit
together. You may want to refer back to this slide as you go through the course, in order to
position the discussion.
For code optimization, this is the only place that it is explained in detail. However,
throughout the course the students see over and over how code optimization works without
it being specifically called out.
Instructor Guide
Instructor Guide
V8.1
Uempty 3.1. IBM Worklight component architecture
Instructor Guide
Figure 3-3. IBM Worklight component architecture WU5061.0
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.
IBM Worklight
component
architecture
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 3-4. Worklight components - overview WU5061.0
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.
Worklight components - overview
Device
Runtime
A
p
p
l
i
c
a
t
i
o
n
C
o
d
e
B
a
c
k
e
n
d

a
n
d
C
l
o
u
d

s
e
r
v
i
c
e
s
Worklight Server
Backend
integration
Version
management
Unified push
notifications
Worklight
Console
B
u
i
l
d

E
n
g
i
n
e
Worklight
Studio
Device
SDK
Public/private App Stores
App
Center
Instructor Guide
V8.1
Uempty
Instructor notes:
Details Spend
Instructor Guide
Figure 3-5. Worklight Studio WU5061.0
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.
Worklight Studio
Plugin for Eclipse
HTML5, hybrid and native
coding
Optimization framework
Integrated device SDKs
3
rd
party library integration
B
u
i
l
d

E
n
g
i
n
e
Worklight
Studio
Device
SDK
Public/private App Stores
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 3-6. Worklight Studio plug-in WU5061.0
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/.
Worklight Studio plug-in
There are two ways to install the plug-in:
Download it as a compressed file and install it as an archive
Install it directly from the web through Eclipse
1
2
3
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 3-7. Worklight Studio design perspective WU5061.0
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 .
Worklight Studio design perspective
1
2
3
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 3-8. Shell components and inner applications WU5061.0
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.
Shell components and inner applications
Architecture:
The shell consists of native and web code
Inner applications consist of web code only
The shell provides access
to native device capabilities
The shell can restrict inner
applications from accessing
unsanctioned functions
Both native and JavaScript
functions
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 3-9. Worklight server WU5061.0
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
Worklight server
Distribution of mobile web
applications
Secure connection between
client and server
Direct access to enterprise
backend data and transaction
capabilities
Enforcement of authentication
Control of the client:
Application version management
Remote disabling
Enforced application update
Unified push notification
Aggregation of statistics regarding the use of the application
B
a
c
k
e
n
d

a
n
d
C
l
o
u
d

s
e
r
v
i
c
e
s
Worklight Server
Backend
integration
Version
management
Unified push
notifications
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 3-10. Server customization components WU5061.0
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.
Server customization components
The server is bundled with
Worklight Studio
No need for a separate installation
The project in Worklight Studio has
a server folder which includes:
Server configuration files
authenticationConfig.xml and
worklight.properties
A basic login page
Folders for Java code and jar files
used for customizing the server
Java, lib
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 3-11. worklight.properties WU5061.0
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.
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
Values for databases, bit.ly
credentials, WS-Security,
and so forth
Bit.ly is a way of referencing
long URLs by giving abbreviated
addresses and using a redirect
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 3-12. authenticationConfig.xml WU5061.0
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.
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 3-13. Deploying applications and adapters to the server WU5061.0
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).
Deploying applications and adapters to the server
1
2
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 3-14. Device runtime WU5061.0
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
Device runtime
Device runtime includes these capabilities:
Troubleshooting
Analytics
Skins
Authentication
Local security
Version control
Each of these is discussed in future units.
Device
Runtime
A
p
p
l
i
c
a
t
i
o
n
C
o
d
e
Instructor Guide
V8.1
Uempty
Apply new versions, or disable old versions in accordance with the information received
from the Worklight console.
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 3-15. Application distribution and update WU5061.0
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.
Application distribution and update
Native resources are deployed to the Application Store
Web resources are deployed to both the Application Store
and the server
The server has resources
for V1.0 and V1.0
After loading, the device
asks for updates
During development
cycles, testers automatically
get recent web resources
through internal distribution
mechanisms, not application stores
Worklight Server
Maintain recent web
resources for native
applications V1.0 and V1.1
Application Stores
Web
code
native
shell
V1.0
Web
code
native
shell
V1.1
Instructor Guide
Instructor notes:
Purpose Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 3-16. Push notification WU5061.0
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.
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
Push service
mediator
Back end
Enterprise
data source
Worklight
adapter
event source
1
2
3
4
5
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 3-17. Worklight console WU5061.0
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.
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
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 3-18. Worklight console - catalog tab WU5061.0
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.
Worklight console - catalog tab
Applications may be deployed on the server in several versions
The latest version should be used. Earlier versions can be marked
as notifying or disabled
1
2
3
Notifying: give a message
that a version is deprecated
Disabled: the version
cannot be used. The
message may include
a URL where the user can
find a new version.
The display shows
description and display
name.
You can modify these in
application-descriptor.xml
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 3-19. Worklight console - mobile browser simulator WU5061.0
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.
Worklight console - mobile browser simulator
The Mobile Browser
Simulator provides a
quick way to view what
an environment should
look like
Open it from the
catalog tab by clicking
the name or the icon of
an environment
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 3-20. Mobile browser simulator WU5061.0
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.
Mobile browser simulator
1
2
3
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 3-21. Application Center architecture WU5061.0
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
iOS / Android
Application
Center
Installer App
Dojo 1.7.2 / HTML
/CSS/JavaScript
Rest Services
Database - Derby
Worklight 5
Dojo Mobile 1.7.2
HTML5 / CSS / JavaScript
iOS and Android native code
Application Center architecture
Application Server
Application Center
Application Catalog
Service
Application Install
Service
Application Feedback
Service
Application Center
Console
Instructor Guide
You use the mobile client to install applications on a mobile device and to send feedback
about an application to the server.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 3.2. Code optimization
Instructor Guide
Figure 3-22. Code optimization WU5061.0
Notes:
Code optimization
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 3-23. Code optimization WU5061.0
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.
Code optimization
Worklight applications can execute in several different environments
Smartphones, tablets, web
Environments are distinguished by many aspects:
Screen size
Orientation
UI components
Physical interface
Functionality specific to an environment
Worklight provides an optimization framework for more efficient code
development
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 3-24. The basis of optimization WU5061.0
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.
The basis of optimization
A Worklight application is divided into environmental folders
iPhone, Android, and so forth
Each folder holds a number of sub-folders that hold code specific to
that environment.
There are sub-folders for
Cascading Style Sheets
Images
JavaScript
Native
Native resources
The application itself has a folder called common,
which holds resources that are shared by all
environments
The common folder also has a structure of sub-folders
including css, images and JavaScript
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 3-25. How does optimization work WU5061.0
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.
How does optimization work
The process of optimization combines resources
The fundamental resources (common folder) are the basis for all
environments
Any extra resources in the environment folders are combined with the
common resources
The process continues if there are skin folders
Common CSS, images, JavaScript
Environment
CSS
Environment
images
Environment
JavaScript
Skin
CSS
Skin
images
Skin
JavaScript
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 3-26. Optimization - CSS WU5061.0
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.
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;
}
body {
text-align: left;
}
div {
font: serif;
}
#content {
height: 460px;
margin: 0 auto;
width: 320px ;
}
body {
background-color: white;
text-align: left;
}
div {
font: serif;
}
common + environment = final CSS
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 3-27. Optimization - images WU5061.0
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.
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
bgd.jpg
icon.jpg
bgd.jpg
bgd.png
icon.jpg // environment
splash.jpg
common + environment = final images
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 3-28. Optimization - JavaScript WU5061.0
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.
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
var a = 1;
wlCommonInit(){}
function_1(){}
var a = "hello;
wlEnvInit(){}
function_1(){}
function_2(){}
var a = "hello"; // env.
wlCommonInit(){}
wlEnvInit(){}
function_1(){} //env.
function_2(){}
common + environment = final JavaScript
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 3-29. Optimization - HTML WU5061.0
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.
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
common environment
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 3.3. Client-side development:
the Worklight JavaScript SDK
Instructor Guide
Figure 3-30. Client-side development: the Worklight JavaScript SDK WU5061.0
Notes:
Client-side
development:
the Worklight
JavaScript SDK
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 3-31. Overview of client-side development WU5061.0
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.
Overview of client-side development
Desired functionality Example Technology
1
Standard screens and graphics Lists, forms, images JavaScript, HTML, CSS, 3
rd
-
party JavaScript libraries
2
Use UI controls rendered as
native
Busy indicator, Dialog, Options
menu, Tab bar
Worklight JavaScript API
3
Optimize UI to specific device
type
Utilize larger form-factor of iPad,
adapt to OS UI standards
Create a Worklight environment
optimization, use JavaScript,
HTML CSS
4
Access device features Camera, GPS, accelerometer,
contacts, media player
Use Apache Cordova
JavaScript API
5
Incorporate 3
rd
-party native
libraries
Native encryption library Write an Apache Cordova
plugin
6
Combine native and web-based
UI within the same application
Bar code scanning, augmented
reality
Use Worklight native page API
to combine native and web
pages, with shared session
7
Develop a full-native application
using Worklight server
Migrate existing native
applications to the Worklight
platform
Use Worklight native SDK
(Objective-C, Java)
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 3-32. Common controls WU5061.0
Notes:
These controls are discussed in more detail in a future unit.
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 3-33. Skins WU5061.0
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).
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
Reasons for creating skins include
Accommodating different screen sizes
Allowing for different input methods
Creating different screen density
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 3-34. Apache Cordova WU5061.0
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")
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);
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 3-35. Calls between native and web pages WU5061.0
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.
Calls between native and web pages
The WL.NativePage API allows you to
call native pages from web pages
Share a single server session
Share data from one page to another
For example, to switch from a web page to a native page:
WL.NativePage.show(className, callback, data);
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 3-36. Offline access WU5061.0
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!
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
Connection is checked at initialization
var wlInitOptions = {
connectOnStartup : true,
onConnectionFailure ; function (data) {
someFunction(data);
}
};
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 3-37. Encrypted cache WU5061.0
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.
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
Encryption is done using a randomly generated token and a user key
Creating and opening encrypted cache uses the same mechanism:
WL.EncryptedCache.open(
credentials, createIfNone, onComplete, onError);
The cache must be explicitly closed. Once open, reading from
and writing to the cache is not challenged!
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 3-38. Globalizing strings WU5061.0
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;
}
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
Worklight provides messages.js in the common folder
The Message element holds the default list of name-value pairs, for
example:
Messages = { headerText: "Default header",
languageLabel: English",
sampleText: Sample Text }
Each message can be accessed
as a property, for example Messages.headerText
as an HTML element id, for example <div id=headerText>
Instructor Guide
V8.1
Uempty
Element texts can then be updated:
setFrench();
$(sampleText).html(Messages.sampleText);
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 3-39. UI frameworks WU5061.0
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.
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
The Worklight client-side framework already
uses jQuery. The $ character is by default
assigned to jQuery calls in applicationName.js
window.$ = WLJQ
To use a framework, add the components
to the application and reference them in
the HTML page
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty 3.4. Server-side development
Instructor Guide
Figure 3-40. Server-side development WU5061.0
Notes:
Server-side
development
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 3-41. Integration adapters WU5061.0
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.
Integration adapters
Four adapter types can be developed with Worklight:
SQL
HTTP
Cast Iron
JMS
These are discussed in detail in a further module
Adapters are server side components that are used to connect to
backend systems
Adapters have
an XML file describing the connectivity options
a JavaScript file that holds the functions described
in the XML file
The adapter may transform the data it retrieves (optional XSL file), or
simply return it
In both cases, the adapter returns a JSON object
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 3.5. Secure authentication
Instructor Guide
Figure 3-42. Secure authentication WU5061.0
Notes:
Secure authentication
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 3-43. Authentication WU5061.0
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.
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>
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 3.6. Application management and reporting capabilities
Instructor Guide
Figure 3-44. Application management and reporting capabilities WU5061.0
Notes:
Application
management and
reporting capabilities
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 3-45. Push notification WU5061.0
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.
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
The notification can be
a pop-up alert
a badge, or small icon added to the application icon
a sound
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 3-46. Direct update WU5061.0
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.
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.
The server can mark an application version as Active, Notifying
There would be a more recent version that the user can upload
The server can also disable a version
A URL can be provided where the user can download another version
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 3-47. Remote server application deployment WU5061.0
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.
Remote server application deployment
In a development environment the resources are usually local
To prepare an application for deployment, you must modify some
definitions to point to the new environment
application-descriptor.xml has these definitions
For example, by default <worklightServerRootURL> points to
http://${local.IPAddress}:8080
You change this to the remote server address
In worklight.properties you change the Worklight server access
information
For example
publicWorkLightProtocol=http
publicWorkLightPort=8081
publicWorkLightContext=/theApp/
would create a URL of http://<server>:8081/theApp/
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 3.7. Mobile team development capabilities
Instructor Guide
Figure 3-48. Mobile team development capabilities WU5061.0
Notes:
Mobile team
development
capabilities
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 3-49. Shell development WU5061.0
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.
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 3-50. Application Center WU5061.0
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.
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 3-51. Enhancements to Worklight in version 6.0 WU5061.0
Notes:
Some of these enhancements are indicated here simply for information (such as the
improved performance). Other enhancements are discussed in future units.
Enhancements to Worklight in version 6.0
Automated functional testing for accelerated delivery cycles of native
and hybrid, cross-platform mobile applications
New advanced IT analytics for application usage insight, triggering of
actions based on analytics events, and location-based services such as
geo-fencing
Improved application development and testing abilities to record and
run tests of mobile applications on devices and emulators
Expanded mobile operating system support, including support for new
levels of iOS, Android, BlackBerry, Windows 8 and RT, and Windows
Phone 8 in addition to third-party software support updates for JQuery
Mobile and Dojo Mobile
Easier, more guided, hybrid application development, with tools and
building blocks such as improved Dojo Mobile setup and screen
templates
Improved application startup performance
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 3-52. Checkpoint WU5061.0
Notes:

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) native
c) legal
d) js
e) 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
Instructor Guide
V8.1
Uempty
Instructor notes:
Instructor Guide
Notes:
Unit summary
Worklight V6
Instructor Guide
V8.1
Uempty
Instructor notes:
the learning points
Instructor Guide
Notes:
Checkpoint answers
1. What are the five basic components in Worklight?
Worklight Studio, Server, and console; device runtime, Application Center
2. How does direct update work?
Download an application from an Application Store, then check Worklight Server
for updates. There is also a check when an application gets focus.
3. What is a push notification?
The server sends data to a device without first receiving a request
4. Which of these folders can be found in common resources and
environment resources:
a) 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
6. What does it mean when a server marks an application version as
Active, Notifying ? A more recent version of the application is available
7. true or false: a shell is an executable framework for inner applications
False. A shell is not executable in itself
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Purpose
Details NOTE! The last question may provoke debate. It could in fact be argued that the
answer is "true", because the shell is executable when it is used with an inner application.
The question is worded to imply that the shell, in itself, is executable, which is of course
false. If students do not themselves point this out, you may want to point it out to them! It
helps to make the concept clearer.
Instructor Guide
Instructor Guide
Copyright IBM Corp. 2013 Unit 4. Overview of Worklight Studio 4-1
V8.1
Uempty
Unit 4. Overview of Worklight Studio
Estimated time
01:30
This unit shows you how to install Worklight Studio and how to 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.
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
Checkpoint
Exercise
References
Instructor Guide
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.
Unit objectives
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Notes:
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 4.1. IBM Worklight Studio installation and configuration
Instructor Guide
Figure 4-3. IBM Worklight Studio installation and configuration WU5061.0
Notes:
IBM Worklight Studio
installation and
configuration
Installing the Worklight Studio plug-in
Setting up an Android development
environment
Setting up an iOS development environment
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 4-4. IBM Worklight Studio: Introduction WU5061.0
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
IBM Worklight Studio: Introduction
Worklight Studio is an Eclipse-base IDE that allows developers to
perform all the coding and integration tasks required to develop mobile
applications.
Contains an embedded version of Worklight Server and an embedded database
to facilitate the development process.
Worklight Studio allows you to easily:
Create and modify applications
Deploy applications to the embedded Worklight Server
Preview and manage applications by using the Worklight Console
Create custom server-side Java code that can be used by Worklight adapters
Create and modify Worklight adapters
Deploy Worklight adapters to the embedded Worklight Server
Test Worklight adapter procedures
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-5. IBM Worklight Studio installation: Prerequisites (1 of 2) WU5061.0
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#
IBM Worklight Studio installation: Prerequisites (1 of 2)
Worklight Studio v6.0 is an Eclipse plug-in and can be installed in the
following Eclipse editions and versions:
Eclipse Classic or Eclipse for Java Enterprise Edition (Java EE) Developers
Version 4.2.2 (Juno)
Worklight Studio runs on operating systems where Eclipse is supported
(32 and 64-bit editions):
Microsoft Windows 7, Windows 8
Mac OS X 10.7 and above
Linux
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-6. IBM Worklight Studio installation: Prerequisites (2 of 2) WU5061.0
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#
IBM Worklight Studio installation: Prerequisites (2 of 2)
Eclipse requires a JDK or JRE:
IBM Runtime Environment, Java Technology Edition 6.0, 7.0
Oracle Java SDK/JRE/JDK 7.0
Worklight Studio v6.0 supports the following mobile Software
Development Kits (SDKs) and tools:
iOS: Xcode version 4.5 and above
Android: Android Development Tools (ADT) latest version
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-7. IBM Worklight Studio installation methods WU5061.0
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.
IBM Worklight Studio installation methods
Worklight Studio can be installed in one of two ways depending on the
target operating system and product packaging:
Eclipse Update Site
Supported on all operating systems
Supported on all IBM Worklight product editions
Uses an Eclipse P2 archive location for source of plug-in
> Accessed directly from the web or downloaded locally first
IBM Installation Manager
Supported on non-Mac operating systems only
Not applicable to IBM Worklight Developer Edition
Uses an IBM Installation Manager repository for source of plug-in
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-8. Installing IBM Worklight Studio using the Eclipse Update Site (1 of 4) WU5061.0
Notes:
Installing IBM Worklight Studio using the Eclipse Update
Site (1 of 4)
In Eclipse:
Select Help > Install New Software.
Click Add to add a new location.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
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.
Site (2 of 4)
Specify the location of the Worklight Studio plug-in source (Eclipse
Update web site or local archive)
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Notes:
Site (3 of 4)
Select the options to install:
IBM jQuery Mobile Tools
IBM Dojo Mobile Tools
Click Next
Install details page displays
You must accept terms of the license
You are prompted to restart Eclipse
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Notes:
Site (4 of 4)
After Eclipse restarts:
The Create a Worklight Artifact icon is displayed on the tool bar.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Instructor Guide
Notes:
installation and
configuration
environment
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 4-13. Android development environment setup steps WU5061.0
Notes:
The detailed instructions for installing the Android SDK are available online at:
http://developer.android.com/sdk/installing/index.html
Android development environment setup steps
The steps to set-up an Android development environment in Worklight
Studio are as follows:
1.Install the Android Software Development Kit (SDK)
a) Install the Android SDK core tools
b) Install the Android SDK platform and platform tools
2.Install the Android Development Tools (ADT) plug-in for Eclipse
3.Create an Android Virtual Device
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-14. Installing the Android SDK: Core tools installation WU5061.0
Notes:
The URL for the Android SDK download site is:
http://developer.android.com/sdk/index.html
Installing the Android SDK: Core tools installation
The Android SDK core tools are required to download the rest of the SDK components.
Download the installer or zip file package from the Android SDK download site
Package varies by operating system platform
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-15. Installing the Android SDK: SDK platform and platform tools installation WU5061.0
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.
Installing the Android SDK: SDK platform and platform
tools installation
Once the core tools are installed, the
Android SDK Manager can be used to
install:
SDK platforms
SDK platform tools
Extras (for example, Google USB Driver)
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-16. Installing the ADT plug-in for Eclipse (1 of 3) WU5061.0
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.
Installing the ADT plug-in for Eclipse (1 of 3)
The ADT (Android Development Tools) plug-in for Eclipse is designed
to provide a powerful, integrated environment in which rich Android
applications can be built.
To install the ADT, select Help > Install New Software in Eclipse.
Launches the plug-in installation wizard.
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Notes:
Select Developer Tools in the list of available software. Then follow the ADT installation
process to complete installing the plug-in.
Select Developer Tools and click Next to proceed with the installation.
Proceed with the ADT installation sequence.
18
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
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.
After the ADT plug-in installation
completes and Eclipse restarts, the
Window menu shows two new items:
Android SDK Manager
AVD Manager
If you dont see these items, make sure
that you are in the Java Perspective
19
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-19. Creating an Android Virtual Device (AVD) WU5061.0
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.

Creating an Android Virtual Device (AVD)
To create a virtual device (emulator):
Select Window > AVD Manager.
Click New in the Android Virtual Device
Manager window.
Enter a name and select a target in the
Create new Android Virtual Device window.
Click Create AVD.
20
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-20. Starting an Android Virtual Device WU5061.0
Notes:
Starting an Android virtual device opens the Android emulator window.
Starting an Android Virtual Device
In the Android Virtual Device Manager window, select the virtual device
and click Start.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Instructor Guide
Notes:
installation and
configuration
environment
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 4-22. iOS development environment setup steps WU5061.0
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.
iOS development environment setup steps
Since Eclipse does not support iOS application development, Worklight
Studio requires the Apple Xcode IDE to compile an iOS application and
test it on an iOS simulator.
You can download and install Xcode as follows:
1. Register as an Apple developer.
2. Download and install the latest Xcode IDE from the Mac App Store.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-23. Developing for iOS: Register as an Apple developer WU5061.0
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.
Developing for iOS: Register as an Apple developer
You first need to register as an Apple developer at the Apple Developer
Registration web site.
Requires an Apple ID
24
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-24. Developing for iOS: Download and install Xcode WU5061.0
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.
Developing for iOS: Download and install Xcode
Download and install Xcode from the Mac App Store.
Xcode is a complete, full-featured IDE. It allows you to:
Develop, compile and build native iOS applications
Use an iPhone or iPad Simulator
Manage your testing devices
Install applications on an
iPhone or iPad device
25
Instructor Guide
V8.1
Uempty
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.
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 4-25. Developing for iOS: Worklight Studio and Xcode integration WU5061.0
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.
Developing for iOS: Worklight Studio and Xcode
integration
Worklight Studio automatically generates an Xcode project for your
application and can open it directly in Xcode to compile and run on the
iOS simulator.
26
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty 4.4. Overview of mobile development steps
Instructor Guide
Figure 4-26. Overview of mobile development steps WU5061.0
Notes:
Overview of mobile
development steps
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 4-27. Worklight Studio mobile application development lifecycle WU5061.0
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.
Worklight Studio mobile application development lifecycle
Instructor Guide
V8.1
Uempty
Instructor Guide
Instructor notes:
Purpose
Details Spend some time here to describe each phase of the lifecycle and to make sure
that students understand the big picture.
Instructor Guide
V8.1
Uempty 4.5. Creating a project
Instructor Guide
Figure 4-28. Creating a project WU5061.0
Notes:
Creating a project
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-29. Worklight project creation wizard: Invocation WU5061.0
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.
Worklight project creation wizard: Invocation
The Worklight Project wizard allows you to quickly create a project for
your application.
30
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-30. Worklight project creation wizard: Project name and type WU5061.0
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.
Worklight project creation wizard: Project name and type
Name your project.
Select a Project Template for it:
Hybrid Application
Combines web and native code
Inner Application
Web resources that will be run inside a
shell component
Native API
Shell Component
Wrapper component for a inner
application
31
Instructor Guide
V8.1
Uempty
Inner applications and shell components are discussed in detail in the Team development
unit.
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 4-31. Worklight project creation wizard: Hybrid application UI framework selection WU5061.0
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.
Worklight project creation wizard: Hybrid application UI
framework selection
Name your application.
Optionally, select a JavaScript
mobile user interface framework to
use in.
In order to use jQuery Mobile or
Sencha Touch, you need to
manually download their library
files prior to adding them to the
application.
32
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 4-32. Worklight project structure overview WU5061.0
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.
Worklight project structure overview
References required for
application development
and deployment
Projects applications and
adapters
Server customization
components
Instructor Guide
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.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-33. Worklight project structure: Application folder WU5061.0
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:
Worklight project structure: Application folder
The default environment is called common and
contains all the resources that are shared between
environments:
HelloWorklight.html
The main HTML file
css
HelloWorklight.css - main applications CSS file
reset.css - bringing all rendering engines to one common
ground
images
Default Worklight images for the common environment
js
HelloWorklight.js
The main JavaScript file for the application
messages.js
JSON object holding all app messages. Can be used for
localization
auth.js
Applications custom authentication mechanism
implementation
legal folder should hold all legal related docs
application-descriptor.xml file contains applications
meta data
Instructor Guide
V8.1
Uempty
- 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.
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 4-34. Worklight project structure: Application folder additional environments WU5061.0
Notes:
You will learn more about the relationship between additional environments and the
common environment when discussing Code Optimization in a later unit.
Worklight project structure: Application folder additional
environments
You can add new environments for
different runtime platforms (for
example, Android or iOS).
The new environments resources will have
the following relationship with the common
resources:
images - override the common images in
case both share the same name
css extend and/or override the
common CSS files
js - extends the common application
instance JS object (The environment
class extends the common app class)
HTML - override the common HTML
code in case both share the same name
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 4-35. Worklight project structure: Server folder WU5061.0
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.
Worklight project structure: Server folder
The server folder contains files used for
server-side customization.
The conf folder contains:
worklight.properties: Contains server
configuration properties
authenticationConfig.xml: Defines
authentication realms
The Java folder is used to hold Java classes that
are compiled and deployed to a Worklight Server
once the application is built. You can put your
custom Java code here.
The lib folder is used for JARs that should be
deployed to the Worklight Server.
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 4-36. Worklight project structure: bin folder WU5061.0
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.
Worklight project structure: bin folder
The bin folder contains project artifacts that should be deployed to a
Worklight Server
Evaluation version of Worklight Studio deploys the artifacts to the
embedded Worklight Server as a part of Build process
.wlapp files: application bundles
.adapter files: adapters
.jar and .war files: server
customization files containing
worklight.properties,
authenticationConfig.xml and
custom Java code
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 4-37. Worklight application descriptor WU5061.0
Notes:
The Worklight application descriptor, named application-descriptor.xml, is a metadata file
that is used to define various aspects of the application.
Worklight application descriptor
An application descriptor is an XML file that stores the metadata for a
Worklight application.
Based on the W3C widget packaging and configuration
Can be edited using the editors Design or Source tab
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 4-38. Worklight application descriptor: Basic information WU5061.0
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.
Worklight application descriptor: Basic information
Specifies the application name, description and author details to be displayed in the
Worklight Console
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 4-39. Worklight application descriptor: Environments WU5061.0
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.
Worklight application descriptor: Environments
Environment specific information is inserted automatically as new
environments are added to projects.
iPhone
environment
Android
environment
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty 4.6. Writing your code
Instructor Guide
Figure 4-40. Writing your code WU5061.0
Notes:
Writing your code
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-41. Constructing the UI: Main HTML document (1 of 3) WU5061.0
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.
Constructing the UI: Main HTML document (1 of 3)
Default application HTML template complies with HTML5 standard
markup
Any other DOCTYPE can be specified.
During the runtime of an application, the main HTML document cannot
be replaced by another HTML document
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-42. Constructing the UI: Main HTML document (3 of 3) WU5061.0
Notes:
Add a <script> tag to the body section, to define and load any additional business logic
JavaScript files that your application uses.
Constructing the UI: Main HTML document (3 of 3)
Insert the HTML code for your user interface right after the opening
<body> tag.
The main HTML file also takes the responsibility of loading your
application logic JavaScript files, authentication logic and localization
implementation if any.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-43. Constructing the UI: Rich Page Editor WU5061.0
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.
Constructing the UI: Rich Page Editor
The Rich Page Editor allows you to construct your application user interface in a
WYSIWYG fashion
Drag HTML5 components from Palette view and drop on to the editor
Customize HTML and CSS properties in Properties view
Split view shows both source and design view
Palette
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-44. Coding the business logic: Main JavaScript document WU5061.0
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.
Coding the business logic: Main JavaScript document
The applications main JavaScript file, <appName>.js, contains its
JavaScript functions
It has a wlCommonInit() function that is automatically invoked once
when the Worklight framework initializes
You can add your applications initialization code here
This function is used in environment-specific JavaScript files to have a common
initialization starting point
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-45. Adding a new environment (1 of 2) WU5061.0
Notes:
Alternatively, you can right-click the application folder and select New > Worklight
Environment. This launches the Worklight environment creation wizard.
Adding a new environment (1 of 2)
A new environment definition allows you
to write code customized to a particular
mobile platform.
To add a new environment:
Select the application folder.
Select Worklight Environment
from the Worklight drop-down
menu.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-46. Adding a new environment (2 of 2) WU5061.0
Notes:
The Worklight Environment window allows you to select the different platforms for which
you want to create an environment in your application.
Adding a new environment (2 of 2)
In the Worklight Environment
window, select the check boxes for
the platforms that you wish to add
and click Finish.
The wizard generates an environment
folder in your application folder for each
platform selected.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-47. Android environment generated folders WU5061.0
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.
Android environment generated folders
Two folders are automatically added:
android folder inside the application folder
Android project folder named
<yourProjectNameYourAppName>Andro
id in your workspace
This folder does not contain a copy of the
code, but is mapped to the native folder
in the android folder of the application.
Maps to
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-48. Android environment folder structure WU5061.0
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.
Android environment folder structure
The android folder contains the following sub-
folders, similarly found in the common folder:
css
Properties specified here override CSS files from the
common folder
images
Android specific images can be added here. If an image
with same file name exists in the common folder, it will
be overwritten by the one in the android folder
js
JavaScript functions defined here extend or override
similarly name functions in the common folder
The native folder contains automatically generated
android application code that is mapped to the
Android project created for the application.
Do not edit files in the assets folder directly, as they are re-
generated each time the application is built
Instructor Guide
V8.1
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.
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 4-49. iPhone environment generated folders (1 of 2) WU5061.0
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.
iPhone environment generated folders (1 of 2)
A new folder named iphone is automatically
added to the application folder.
The package sub-folder appears only after you build
and deploy the application
The iphone folder contains the following sub-
folders, similarly found in the common folder:
css
Properties specified here override CSS files
from the common folder.
images
iOS specific images can be added here. If
an image with same file name exists in the
common folder, it will be overwritten by the
one in the iphone folder.
js
JavaScript functions defined here extend or
override similarly name functions in the
common folder
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 4-50. iphone environment folder structure (2 of 2) WU5061.0
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.
iphone environment folder structure (2 of 2)
The native folder contains automatically
generated iphone application code.
Do not edit files in the www sub-folder directly, as
they are re-generated each time the application is
built
The nativeResources folder contains
resources that is used by the native code.
The package folder contains a packaged
(zipped) application.
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty 4.7. Building your application
Instructor Guide
Figure 4-51. Building your application WU5061.0
Notes:
Building your
application
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 4-52. Building an application WU5061.0
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.
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 4.8. Previewing and testing your application
Instructor Guide
Figure 4-53. Previewing and testing your application WU5061.0
Notes:
Previewing and testing
your application
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-54. Application preview and test tools WU5061.0
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.
Application preview and test tools
A variety of tools are available to preview and test your application.
Preview tools allow to quickly test your applications look and basic functions.
Test tools can either be a virtual device simulator or a physical device.
Allow you to test more completely, particularly native functions.
To preview your application, use the Worklight Consoles:
Preview as common resources feature
Good for verifying the look and feel of your application
Mobile Browser Simulator
Can emulate Cordova functionality and previewing using different device
skins.
To test your application, use a:
Virtual device simulator (for example: Android Virtual Device (AVD) or iPhone
Simulator)
Physical device
Mandatory step before publishing your application
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 4.9. Previewing your application in the browser
Instructor Guide
Figure 4-55. Previewing your application in the browser WU5061.0
Notes:
Previewing your
application in the
browser
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-56. Previewing as a common resource WU5061.0
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.
Previewing as a common resource
Open the Worklight Console in
the browser at:
http://<host
name>:8080/console
On the Catalog tab, click
Preview as Common
Resources.
The application is loaded and
rendered in a separate tab or
page.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-57. Previewing in the Mobile Browser Simulator WU5061.0
Notes:
Click the preview icon or active link text to open the application in the Mobile Browser
Simulator for the specific environment.
Previewing in the Mobile Browser Simulator
Requires that you add an environment to your application
For each added environment, the Worklight Consoles Catalog view
shows a preview icon and active text link to preview the application in
the corresponding browser simulator.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-58. Mobile Browser Simulator: Android device WU5061.0
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.
Mobile Browser Simulator: Android device
59
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-59. Mobile Browser Simulator: iPhone device WU5061.0
Notes:
You will learn more about the Mobile Browser Simulator in a subsequent unit.
Mobile Browser Simulator: iPhone device
60
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 4.10.Testing on a simulator
Instructor Guide
Figure 4-60. Testing on a simulator WU5061.0
Notes:
Testing on a simulator
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-61. Testing on the Android emulator (1 of 2) WU5061.0
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.
Testing on the Android emulator (1 of 2)
When you build a Worklight application
with an Android environment, Worklight
Studio generates a separate Android
project for it in the workspace.
You are then be able to run the application
on the Android simulator by right clicking
the Android project and selecting Run As
> Android Application.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-62. Testing on the Android emulator (2 of 2) WU5061.0
Notes:
Testing on the Android emulator (2 of 2)
The Android emulator window allows you to test your application on an
Android virtual device.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-63. Testing on the iPhone simulator: Pre-requisites (1 of 2) WU5061.0
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.
Testing on the iPhone simulator: Pre-requisites (1 of 2)
Testing an application on the iPhone
simulator requires building and running it
in Xcode.
If you are running Worklight Studio in
Eclipse on a Mac OS machine, open your
application directly in Xcode from within the
workbench:
Right-click the
apps/HelloWorklight/iphone folder
Select Run As -> Xcode Project.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-64. Testing on the iPhone simulator: Pre-requisites (2 of 2) WU5061.0
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.
Testing on the iPhone simulator: Pre-requisites (2 of 2)
Testing an application on the iPhone simulator requires building and
running it in Xcode.
If you are running Worklight Studio in Eclipse on a non-Mac OS machine:
Transfer the applications Xcode project zip file to the Mac OS machine.
Extract the zip file.
Open the applications Xcode project file in Xcode.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-65. Testing on the iPhone simulator: Building and running an application (1 of 2) WU5061.0
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.
Testing on the iPhone simulator: Building and running an
application (1 of 2)
Select a device simulator type and version to use (Scheme) .
Click Run to build and launch your application in the simulator.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-66. Testing on the iPhone simulator: Building and running your application (2 of 2) WU5061.0
Notes:
Testing on the iPhone simulator: Building and running your
application (2 of 2)
The iPhone simulator allows you to test your application on a virtual
device.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-67. Testing on a device WU5061.0
Notes:
Testing on a device
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-68. Testing on an Android device WU5061.0
Notes:
Testing on an Android device
When building a mobile application, it's important that you always test
your application on a real device before releasing it to end users.
Testing on an Android physical device requires:
Installing an USB driver on your computer to recognize your device if it is not
supported by the generic Google USB Driver provided in the SDK
Enabling USB debugging on the device
Connecting the device to your computer using an USB cable
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details

Instructor Guide
Figure 4-69. Testing on an iOS device: Pre-requisites WU5061.0
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).
Testing on an iOS device: Pre-requisites
Before you can deploy to an iOS device, you need to:
Enroll in the iOS Developer Program
Requires a paid subscription
Can register as an individual or a company
Provision the device for development. This process involves:
Obtaining a developer certificate that allows you to sign applications.
Obtaining a provisioning profile that identifies your developer certificate, your
device, and the applications you can run on the device.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-70. Testing on an iOS device pre-requisite: Enroll in the iOS Developer Program WU5061.0
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.
Testing on an iOS device pre-requisite: Enroll in the iOS
Developer Program
Before you can deploy and test on a physical device, you must enroll in
the iOS Developer Program.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 4-71. Testing on an iOS device pre-requisite: Provision your device WU5061.0
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.
Testing on an iOS device pre-requisite: Provision your
device
Before you can deploy and test an application on a physical device,
you must first build and install a Provisioning Profile on it. This involves
the multi-step process depicted below.
Instructor Guide
V8.1
Uempty
Downloading the Provisioning Profile to the local development machine and installing it
on the device.

Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 4-72. Testing on an iOS device WU5061.0
Notes:
Testing on an iOS device
Once you have met the pre-requisites, you can follow the instructions
below to test your application on the device.
Connect your device to your computer using an USB cable.
In Xcode, select an actual device in the Scheme drop-down menu.
Click Run. After your code compiles successfully, Xcode uploads and runs your
application on the device.
More info can be obtained at the Apple iOS Development Center:
http://developer.apple.com/devcenter/ios/index.action
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 4-73. Publishing your application WU5061.0
Notes:
Publishing your
application
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 4-74. Publishing your application: Preparation WU5061.0
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.
Publishing your application: Preparation
Prior to building a production version of your application, set the
worklightSettings property in of your application-descriptor.xml to
false.
This disables the ability of the user to change the address of the Worklight
Server with which the application communicates via the devices settings screen.
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 4-75. Publishing your Android application in Google Play WU5061.0
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.
Publishing your Android application in Google Play
To distribute your Android application for public access, use Google
Play.
Google Play (rebranded from Android Market in March 2012) is a
hosted service that:
Simplifies the download and installation process of applications to Android-
powered devices.
Makes it easy for developers to publish their applications for Android users.
Google Play requires that you create an account to use it.
To sign-up, visit: http://market.android.com/publish/signup
For more Information on Google Play, visit: https://play.google.com/
For a publishing checklist for Google Play, visit:
http://developer.android.com/distribute/googleplay/publish/preparing.html/
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 4-76. Publishing your iPhone application in the App Store WU5061.0
Notes:
To distribute your iPhone application for public use, use the Apple App Store.
Publishing your iPhone application in the App Store
iOS application deployment is done via the Apple App Store.
The deployment process is defined by Apple and involves:
Signing up for the iOS Developer Program if you havent already done so.
Submitting a certificate signing request.
Downloading the certificate and creating a distribution provisioning profile.
Submitting the application for App Store approval.
Normally takes about a week or so.
For detailed information on how to prepare an application for
submission and the App Store approval process, visit:
https://developer.apple.com/appstore/index.html
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Notes:

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
2. What is default structure of a Worklight application?
a) A single HTML file, and a number of CSS and JS files
b) A number of HTML and JS files, and a single CSS file
c) A number of HTML, JS, and CSS files
d) A single HTML, single CSS, and a single JS file
3. The purpose of adding an environment to an application is to:
a) Import a specific platform SDK into Worklight Studio.
b) Allow you to write customized code for a specific platform on which you intend
to run the application.
c) Define an additional Worklight Server where you can deploy the application.
Instructor Guide
Instructor notes:
Instructor Guide
V8.1
Uempty
Notes:
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
True
2. What is default structure of a Worklight application?
b) A number of HTML and JS files, and a single CSS file
c) A number of HTML, JS, and CSS files
d) A single HTML, single CSS, and a single JS file
3. The purpose of adding an environment to an application is to:
a) Import a specific platform SDK into Worklight Studio.
b) Allow you to customize the application for a specific target platform.
c) Define an additional Worklight Server where you can deploy the application.
b) Allow you to customize the application for a specific target platform.
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Notes:
Unit summary
Instructor Guide
Instructor notes:
the learning points
Instructor Guide
V8.1
Uempty
Figure 4-80. Exercise 1 WU5061.0
Notes:
Exercise 1
Installing IBM Worklight Studio
and developing your first
application
Instructor Guide
Instructor notes:
Purpose Introduce the exercise.
Details This slide provides an introduction to an exercise (such as a hands-on lab
exercise, or team exercise).
Instructor Guide
V8.1
Uempty
Figure 4-81. Exercise objectives WU5061.0
Notes:
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
Instructor Guide
Instructor notes:
Purpose List the exercise objectives.
Details
Instructor Guide
Copyright IBM Corp. 2013 Unit 5. Client-side core APIs 5-1
V8.1
Uempty
Unit 5. Client-side core APIs
Estimated time
01:30
This unit provides a deep-dive look into key client-side mobile
development APIs provided by Worklight. These APIs include those
that enable cross-platform portability, device type customization, and
application globalization.
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
Checkpoint
Exercise
References
Instructor Guide
Notes:
Unit objectives
Identify essential Worklight client-side APIs including those that enable
cross-platform portability and localization
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Notes:
Topics
Client-side basics
Building a multi-page application
Common controls
Skins
Offline access
String translation
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 5.1. Client-side basics
Instructor Guide
Figure 5-3. Client-side basics WU5061.0
Notes:
Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
8.0
Client-side basics
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 5-4. Application sources WU5061.0
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.
Application sources
Main HTML file:
For example, HelloWorklight.html
Main JavaScript file:
For example, HelloWorklight.js
messages.js: used for storing application
strings; primarily used for localization.
HelloWorklight.html
HelloWorklight.js
Messages.js
initOptions.js
wljq.js
wlclient.js
wlcommon.js
wlfragment.js
worklight.js
busy.js
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 5-5. Worklight initialization WU5061.0
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.
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 5-6. jQuery JavaScript framework WU5061.0
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!
jQuery JavaScript framework
Worklight includes an encapsulated
jQuery, which can be added to the
developer project with a single line of
code:
window.$ = window.jQuery = WLJQ;
HelloWorklight.html
HelloWorklight.js
Messages.js
initOptions.js
wljq.js
wlclient.js
wlcommon.js
wlfragment.js
worklight.js
busy.js
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 5-7. Worklight client JavaScript API WU5061.0
Notes:
There are several reference to these APIs, as well as to the WL namespace, throughout
this course.
Worklight client JavaScript API
Worklight Client API uses WL namespace
Provides bridging to native mobile
platform APIs, dynamic HTML load, and
so on
HelloWorklight.html
HelloWorklight.js
Messages.js
initOptions.js
wljq.js
wlclient.js
wlcommon.js
wlfragment.js
worklight.js
busy.js
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 5-8. The WL namespace WU5061.0
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.
The WL namespace
To use Worklight API, a WL namespace is used
WL.Client, WL.Utils, and so on
Exposes the API objects, methods, and constants (usually enums)
Automatically added to the application main HTML file
wlcommon.js
wlclient.js
worklight.js
WL Namespace is automatically available on application initialization
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 5-9. WL.Client WU5061.0
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.
WL.Client
WL.Client.init (options) initializes the WL.Client object
onSuccess
onFailure
connectOnStartup
busyOptions
WL.Client.reloadApp() - reloads the application
WL.Client.login (realm, options) triggers login
WL.Client.logout (realm, options) triggers logout
General application information can be obtained by using:
WL.Client.getEnvironment ()
WL.Environment.ADOBE_AIR
WL.Client.invokeProcedure (invocationData, options) retrieves and
updates enterprise data
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 5-10. WL.Logger WU5061.0
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 }
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})
A troubleshooting tool, it should only be used in the development
environment
Delete the code for production
Output can be directed to an environment console
Xcode console, Adobe AIR, Android Logcat, for example
WL.Logger.debug (msg, exc)
WL.Logger.error (msg, exc)
msg is the string to be displayed
exc is a JavaScript exception reference (optional)
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 5-11. WL.Logger - example WU5061.0
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.
WL.Logger - example
Use to troubleshoot environments without debugging tools
WL.Logger.debug(message)
WL.Logger.error(message)
The output is sent to the console
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 5.2. Building a multi-page application
Instructor Guide
Figure 5-12. Building a multi-page application WU5061.0
Notes:
8.0
Building a multi-page
application
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 5-13. Working with pages WU5061.0
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.
Working with pages
Applications with multiple pages can be built in two ways
Single HTML file
containing all
application pages
Separate HTML file
for each application
page
Application.html
<div id=loginPage>
<div id=Page1>
<div id=Page2>
<div id=Page3>
<div id=Page4>
<div id=Page5>
.......
Application.html
<div id=loginPage>
<div id=Page1>
<div id=Page2>
<div id=Page3>
<div id=Page4>
<div 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
Instructor Guide
V8.1
Uempty
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.
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 5-14. Splitting code between HTML pages WU5061.0
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).
Splitting code between HTML pages
To split code between pages, use the fragment implementation of
JavaScript frameworks such as jQuery Mobile, Sencha, and Dojo
Mobile
Fragments are files that contain html tags that can be appended to a
parent element. Fragments can include JavaScript files by adding a
<script> tag and style sheets by adding a <link> tag. For example:
Inline JavaScript and CSS are not supported in fragments.
<link href="css/page1.css" />
<script src="js/page1.js" type="text/javascript"></script>
<div id="page1div">
This is page1
</div>
<link href="css/page1.css" />
<script src="js/page1.js" type="text/javascript"></script>
<div id="page1div">
This is page1
</div>
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 5-15. Design considerations WU5061.0
Notes:
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
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 5-16. Loading an external HTML file WU5061.0
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
Loading an external HTML file
An external HTML file is a segment of HTML code that can be injected
into any location in the existing DOM
May include JavaScript by using <script> tag
May include CSS files by using <link> tag
Injected into parent element, usually <div>, but not mandatory
Implemented using jQuery $().load() API
To load an HTML file, use the following syntax:
$(containerSelector).load(filePath, callbackFunction);
$(containerSelector).load(filePath, callbackFunction);
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 5-17. Loading an external HTML file - example WU5061.0
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.
Loading an external HTML file example
This code loads MainPage.html file and inserts its content into the
pagePort <div> element
JavaScript and CSS from MainPage.html are loaded to DOM
When MainPage.html load completes alert(loaded!) is executed
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 5-18. Implementing page navigation with history (1 of 4) WU5061.0
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.
Implementing page navigation with history (1 of 4)
By using the technique described previously, you can implement a
navigation interface with history
You keep the navigation history as a stack in an array object
You also keep a reference to a currently loaded page functionality by
using a JavaScript object variable
Application
HTML file
Application
HTML file
MainPage.html
MainPage.js
MainPage.html
MainPage.js
Page1.html
Page1.js
Page1.html
Page1.js
var = pagesHistory = [];
var = currentPage = {};
var = pagesHistory = [];
var = currentPage = {};
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
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
Application
HTML file
Application
HTML file
MainPage.html
MainPage.js
MainPage.html
MainPage.js
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
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
MainPage.html
MainPage.js
MainPage.html
MainPage.js
Page1.html
Page1.js
Page1.html
Page1.js
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
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
MainPage.html
MainPage.js
MainPage.html
MainPage.js
Page1.html
Page1.js
Page1.html
Page1.js
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty 5.3. Common controls
Instructor Guide
Figure 5-22. Common controls WU5061.0
Notes:
8.0
Common controls
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 5-23. What is a common control? WU5061.0
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.
What is a common control?
Some controls are common to most environments, such as modal pop-
up windows, loading screens, tab bars, and so on.
Worklight provides a JavaScript API to invoke these controls
regardless of the environment. It automatically renders them in a native
way for each mobile platform.
Busy indicator
Simple dialog
Tab bar
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 5-24. WL.BusyIndicator (1 of 3) WU5061.0
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.

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
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
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.
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)
Parent element ID (web only) Options
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
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.
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 5-27. WL.SimpleDialog (1 of 3) WU5061.0
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.
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
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.
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
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.
Each button object has two properties:
text: the text that is displayed on the button
handler: function to invoke if button is clicked
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 5-30. WL.TabBar (1 of 5) WU5061.0
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).
WL.TabBar (1 of 5)
Both Android and iOS environments support tabbed application
navigation with a tab bar component
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
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.
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
WL.TabBar must be initialized
before use
Initialize WL.TabBar in a
designated JavaScript file
Not here!
WL.TabBar.init();
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
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.
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
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.
WL.TabBar (4 of 5)
iOS options
badge: string to display on items
badge
image: file name of an image to use
or native iOS button identifier:
tabButton:More
tabButton:Favorites
tabButton:Featured
tabButton:TopRated
tabButton:Recents
tabButton:Contacts
tabButton:History
tabButton:Bookmarks
tabButton:Search
tabButton:Downloads
tabButton:MostRecent
tabButton:MostViewed
Android options
image: file name of an image to use
for an unselected state
imageSelected: file name of an
image to use for a selected state
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
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.
WL.TabBar (5 of 5)
Android example:
iOS example:
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 5-35. WL.OptionsMenu (1 of 4) WU5061.0
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.
WL.OptionsMenu (1 of 4)
Android and Windows Phone environments have
the ability to display an options menu
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
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.
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!
Not here!
WL.OptionsMenu.init();
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
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.
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
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.
WL.OptionsMenu.addTab example
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 5.4. Skins
Instructor Guide
Notes:
8.0
Skins
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
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.
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 5-41. Skin use cases WU5061.0
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.
Skin use cases
Different screen sizes (for example, iPhone versus iPad)
Different input methods (for example, touchpad versus keypad)
Different screen densities
Support for HTML5
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 5-42. Skin creation and packaging WU5061.0
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.
Skin creation and packaging
Create skins by using the Worklight Skin Wizard
Skin directories are created next to environment directory
Directories contain HTML, CSS, JavaScript files
All skins for a specific environment are packaged within the app
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 5-43. Applying skins at run time WU5061.0
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.
Applying skins at run time
A developer-written JavaScript file is run at application startup
Determines which skin to load
The default skinLoader.js contains samples
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 5-44. Skin Registration WU5061.0
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.
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 5.5. Offline access
Instructor Guide
Figure 5-45. Offline access WU5061.0
Notes:
8.0
Offline access
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 5-46. Working in Offline Mode WU5061.0
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.
Working in Offline Mode
The Worklight Platform allows developers to detect application
connectivity failures and determine course of action
Applications going off- and on-line can be detected in two ways:
Explicitly, upon invoking server-based procedures
Implicitly, using JavaScript event listeners
Developers can define custom application behavior for off- and on-line
status
Instructor Guide
V8.1
Uempty
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.
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 5-47. Explicit detection: using methods WU5061.0
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.
Explicit detection: using methods
There are two locations where connectivity loss can be detected:
Application initialization: WL.Client.init() method, usually called from initOptions.js
Adapter procedure invocation: WL.Client.invokeProcedure() method
To use connectivity failure detection add onConnectionFailure, and
specify a callback function to be invoked if connectivity fails
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 5-48. Implicit Detection: offline/online events WU5061.0
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.
Implicit Detection: offline/online events
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
In each case, JavaScript events are fired
WL.Events.WORKLIGHT_IS_DISCONNECTED event is fired when connectivity
to the Worklight Server fails
WL.Events.WORKLIGHT_IS_CONNECTED event is fired when connectivity to
the Worklight Server is restored
Developers can add event listeners to these events and specify the
callback functions that handle them
Instructor Guide
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).
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 5-49. isConnected() and connect() WU5061.0
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.
isConnected() and connect()
Additional methods are provided by the Worklight framework to simplify
online/offline development:
WL.Client.isConnected (): Returns Boolean value for latest known
connectivity state; True for online; False for offline
WL.Client.connect (options): Attempts to connect to the Worklight
Server and return to online mode; options is an object containing the following
keys:
onSuccess: Callback function to invoke in case server connection is
established
onFailure: Callback function to invoke in case server connection fails
Timeout: Number of milliseconds to wait for the server response before
failing with request timeout
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 5-50. getNetworkInfo() WU5061.0
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

getNetworkInfo()
WL.Device.getNetworkInfo() method is available for iOS and
Android environments
A callback must be specified as a function parameter
Instructor Guide
V8.1
Uempty
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 5-51. Foreground event WU5061.0
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.
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
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 5-52. Worklight heartbeat WU5061.0
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.
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
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty 5.6. String translation
Instructor Guide
Figure 5-53. String translation WU5061.0
Notes:
8.0
String translation
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 5-54. Introduction to translation WU5061.0
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.
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
The Worklight Platform can automatically translate the application
strings according to a designated file
Multi-language translation can be implemented using JavaScript
Instructor Guide
V8.1
Uempty
Worklight platform simplifies the translation process by automatically matching and
translating the text Strings based on a designated file. This file is the message.js file that is
discussed later.
For other advanced mutli-language support, developers can also use JavaScript to extend
the function of the Worklight translation framework.
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 5-55. Enabling translation WU5061.0
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.
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
Instructor Guide
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.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 5-56. Translating system messages WU5061.0
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.
Translating system messages
It is also possible to translate system messages that the application shows, for
example Internet connection is not available or Invalid user name or password
System messages are stored in WL.ClientMessages object
A full list of system messages can be found in wlclient/js/messages.js file inside
Worklight-generated projects (iOS, Android, and so on)
To enable translation for a system message, override it in your application
JavaScript
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 5-57. Multi-language translation: set up the Strings WU5061.0
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.
Multi-language translation: set up the Strings
It is possible to implement multi-language translation for your
applications by using JavaScript
Set up default application strings in messages.js
Override specific strings when required
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 5-58. Multi-language translation: selecting the language WU5061.0
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.
Multi-language translation: selecting the language
Bind a change in the value of the element id languages to the function
getLang()
Get the device locale and extract the locale String
Check the locale and call getLang()
The getLang() function is shown on the next slide
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 5-59. Detecting device locale and language WU5061.0
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
Detecting device locale and language
Switch language Strings by calling on of the set<Language>() functions
If the chosen language flows from right to left, switch the direction
Instructor Guide
V8.1
Uempty
this example, you should provide the possibility of reverting to it if you change, for example,
to French.
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 5-60. Checkpoint questions (1 of 2) WU5061.0
Notes:

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
2. Which API can be used across all environments to debug the
Worklight application?
A. console.log
B. console.debug
C. WL.Logger.debug
D. WL.Debugger.log
Instructor Guide
Instructor notes:
Instructor Guide
V8.1
Uempty
Figure 5-61. Checkpoint questions (2 of 2) WU5061.0
Notes:
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
2. To display a modal activity indicator, you can use
A. WL.SimpleDialog
B. WL.BusyIndicator
C. WL.OptionsMenu
D. WL.TabBar
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Notes:
Unit summary
Identify essential Worklight client-side APIs including those that enable
cross-platform portability and localization
Instructor Guide
Instructor notes:
the learning points
Instructor Guide
V8.1
Uempty
Notes:
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
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 5-64. Exploring IBM Worklight client-side APIs WU5061.0
Notes:
8.0
Exploring IBM Worklight
client-side APIs
Exercise 2
Instructor Guide
Instructor notes:
Instructor Guide
V8.1
Uempty
Notes:
Exercise objectives
Use Worklight client-side functions to access device environment
information, and use common controls and skins
Instructor Guide
Instructor notes:
Details
Instructor Guide
Copyright IBM Corp. 2013 Unit 6. Local storage APIs 6-1
V8.1
Uempty
Unit 6. Local storage APIs
Estimated time
01:00
This unit provides a detailed look into the encrypted cache and
JSONStore local storage APIs provided by Worklight.
Identify the Worklight client-side APIs that support storing data
locally on a device in an encrypted cache or a JSON data store.
Checkpoint
Exercise
References
Instructor Guide
Notes:
Unit objectives
Identify the Worklight client-side APIs that support storing data locally on a
device in an encrypted cache or a JSON data store.
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Notes:
Topics
Encrypted cache
JSON data store
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 6.1. Encrypted cache
Instructor Guide
Figure 6-3. Encrypted cache WU5061.0
Notes:
8.0
Encrypted cache
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 6-4. What is encrypted cache? WU5061.0
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.
What is encrypted cache?
Encrypted cache is a mechanism for storing sensitive data on the client side
Implemented by using HTML5 local storage technology, which allows data to
be saved locally and retrieved on subsequent application use or re-launch
Data is encrypted with a combination of a user-provided key and server-
retrieved randomly generated token, which makes it more secure
Data is stored using key-value pairs
Encrypted cache is just like a security deposit box - it remains open until you
close it, so it is important to close the cache once you are done working with it
5
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 6-5. Supported Browsers and Devices WU5061.0
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
Supported Browsers and Devices
6
Show all
versions
iOS Safari Opera Mini Opera Mobile Android
browser
3 versions
back
3.2
2 versions
back
4.0-4.1 10.0 2.1
Previous
version
4.2-4.3 11.0 2.2
Current
version
5.0 5.0-6.0 11.1 2.3-3.0
Near future 4.0
Supported= Not supported=
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 6-6. Creating or opening encrypted cache WU5061.0
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
Creating or opening encrypted cache
To create or open a previously created encrypted cache, use the following API:
WL.EncryptedCache.Open(credentials, createIfNone,
onComplete);
credentials: string value representing user-provided password
createIfNone: Boolean value specifying whether new encrypted cache should
be created in case none is found
onComplete: a callback function to be invoked when cache opening/creating
is complete
onError: a callback function to be invoked when cache is not successfully
opened/created
7
Instructor Guide
V8.1
Uempty
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
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 6-7. Encrypted cache status WU5061.0
Notes:
Encrypted cache status
A callback function can receive one of the following statuses:
WL.EncryptedCache.OK Encrypted cache was successfully opened or
created
WL.EncryptedCache.ERROR_CREDENTIALS_MISMATCH an attempt was
made to open existing encrypted cache using wrong credentials
WL.EncryptedCache.ERROR_SECURE_RANDOM_GENERATOR_UNAVAIL
ABLE unable to generate random token due to Worklight Server unavailability
WL.EncryptedCache.ERROR_NO_EOC could not open encrypted cache
because it was not previously created
WL.EncryptedCache.ERROR_LOCAL_STORAGE_NOT_SUPPORTED device
does not support HTML5 local storage
WL.EncryptedCache.ERROR_KEY_CREATION_IN_PROGRESS an open()
or changeCredentials() request is already running
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 6-8. Opening encrypted cache example WU5061.0
Notes:
The sample code here shows how to evaluate the Cache open or create status.
Opening encrypted cache example
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 6-9. Reading and writing data with encrypted cache WU5061.0
Notes:
Reading and writing data with encrypted cache
When the encrypted cache is open, you can perform operations on it such as
reading, writing and removing data
To store data in encrypted cache use the following API:
WL.EncryptedCache.write(credentials, value, onSuccess, onFailure);
10
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 6-10. Reading and removing data from encrypted cache WU5061.0
Notes:
Reading and removing data from encrypted cache
To read data from the encrypted cache use the following API:
WL.EncryptedCache.read(credentials, onSuccess, onFailure);
To remove data from the encrypted cache use the following API:
WL.EncryptedCache.remove(key, onSuccess, onFailure);
11
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 6-11. Closing encrypted cache WU5061.0
Notes:
Closing encrypted cache
To avoid possible undesired access to encrypted cache, close it
After encrypted cache is closed, access to its data is not possible without the
encryption key that was used to create it
Use the following API to close the encrypted cache
WL.EncryptedCache.close(onComplete, onFailure);
12
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 6-12. Destroying encrypted cache WU5061.0
Notes:
Destroying encrypted cache
Encrypted cache can be wiped from the local storage
After encrypted cache is destroyed there is no way to return the data that was
stored in it
Destroy encrypted cache only if you are sure that data stored in it will never be
required again, or as a last measure if the encryption key is lost
To destroy an encrypted cache use the following API:
WL.EncryptedCache.destroy(onComplete, onError);
13
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 6-13. Changing the encryption key WU5061.0
Notes:
Changing the encryption key
While encrypted cache is in the open state, it is possible to change the
encryption key
To do so, use the following API:
WL.EncryptedCache.changeCredentials(credentials, onComplete, onError)
credentials new user password to be used.
onComplete a callback function to be invoked when complete.
onError a callback function to be invoked in case of an error.
Callback receives a status object with same structure as
WL.EncryptedCache.open()
14
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty 6.2. JSONStore
Instructor Guide
Figure 6-14. JSONStore WU5061.0
Notes:
8.0
JSONStore
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 6-15. What is JSONStore? WU5061.0
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.
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details Why use JSONStore? You can store data on a device securely with encryption,
and have the ability to access it offline, keep it in sync with the enterprise system, and
index it for searching.
Additional information It can be used with iOS and Android, ARM architecture or
simulator, NOT preview, mobile browser simulator.
Instructor Guide
Figure 6-16. Comparison of storage technologies WU5061.0
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
Comparison of storage technologies
Instructor Guide
V8.1
Uempty
more information, search the IBM Worklight Information Center for the class
WL.JSONStore -
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 6-17. JSONStore terminology: document WU5061.0
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.
JSONStore terminology: document
Document: JavaScript object with an auto-generated identifier (_id) and data in JSON format, similar to a
record or row in database terminology
Example:
var doc = {
_id: 1,
json: {
name: 'carlos',
age: 99
}
};
Instructor Guide
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}}];
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 6-18. JSONStore terminology: collection WU5061.0
Notes:
JSONStore terminology: collection
A collection is a named logical grouping of related documents, similar to a
table in the database terminology
Example -- Customer Collection
[
{ _id: 1, json: {name: 'carlos', age: 99} },
{ _id: 2, json: {name: 'tim', age: 100} },
]
Internal storage
Customer collection
Document: Document:
{_id: 1, json:
{name: carlos,
age: 99}}
{_id: 2, json:
{name: 'tim',
age: 100}}
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 6-19. JSONStore terminology: search field WU5061.0
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',
JSONStore terminology: search field
A search field is a JavaScript object with a key and a data type.
These keys are indexed for fast look-up times.
It is like column fields or attributes in the database terminology.
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'};
Instructor Guide
V8.1
Uempty
gpa : 'number', //floating point or int
active : 'boolean',
'address.state' : 'string' };
Query: a JavaScript object that does not contain nested objects or arrays. Keys must be
specified in the search fields or be the special _id identifier. Example:
var query = {_id : 0};
var query = {fn : 'carlos'};
var query = {age : 99};
var query = {active : false};
var query = {'address.state' : 'TX'};
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 6-20. JSONStore terminology: query WU5061.0
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};
JSONStore terminology: query
query: JavaScript object that use search fields or additional search fields to
look for documents
Example: in the figure, the search field is the string name. When you query the
collection for name equals carlos, it identifies what document to return
Internal storage
Customer collection
Document:
{_id: 1, json:
{name: carlos}}
Document:
{_id: 1, json:
{name: tina}}
Search field name (string)
carlos tina
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 6-21. Store internals WU5061.0
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.
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'}
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 6-22. Error object WU5061.0
Notes:
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
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 6-23. JSONStore architecture WU5061.0
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.
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
Worklight
Enterprise systems
Adapter
1 2
3 4
REST, SOAP, SQL or
Cast Iron
Native layer
Internal
storage
JSONStore
JavaScript API
Web layer
5
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 6-24. Sending data back WU5061.0
Notes:
Sending data back
1. JSONStore requests data from the internal storage
2. The internal storage returns JSON documents
3. JSONStore sends those documents to an adapter
4. The Worklight adapter sends data to the enterprise service
Worklight
Enterprise systems
Adapter
3 4
REST, SOAP, SQL or
Cast Iron
Native layer
Internal
storage
JSONStore
JavaScript API
Web layer
2 1
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 6-25. JSONStore API WU5061.0
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.
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
options: an object that contains onSuccess and onFailure keys
These keys might have functions as values that execute after the operation
finishes
var win = function (data) { };
var fail = function (data) { };
var options = {onSuccess: win, onFailure: fail};
var win = function (data) { };
var fail = function (data) { };
var options = {onSuccess: win, onFailure: fail};
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 6-26. Initialization WU5061.0
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.
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 collectionName = 'people';
//Object that defines all the collections
var collections = {};
//Object that defines the 'people' collection
collections[collectionName] = {};
//Object that defines the Search Fields for the 'people' collection
collections[collectionName].searchFields = {name: 'string', age: 'integer'}
WL.JSONStore.init(collections)
.then(function () {
//handle success
})
.fail(function (errorObject) {
//handle failure
});
//Object that defines all the collections
var collections = {};
//Object that defines the 'people' collection
collections[collectionName] = {};
//Object that defines the Search Fields for the 'people' collection
collections[collectionName].searchFields = {name: 'string', age: 'integer'}
.then(function () {
//handle success
})
//handle failure
});
The sample app has a button
to initialize a collection.
Instructor Guide
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 6-27. Get WU5061.0
Notes:
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 people = WL.JSONStore.get(collectionName);
The variable people can now be used to perform operations on the people
collection such as:
add
find
replace
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 6-28. Handling data locally WU5061.0
Notes:
Handling data locally
When your local store is initialized, you can start handling the data by using the
JSONStore API
You can perform many functions on the local data, including:
Add
add (data, [options]) OnSuccess
Remove
remove (doc, {options]) OnSuccess
Count
([options]) OnSuccess
Replace
replace (doc, [options]) OnSuccess
Find
Find (query, [options]) OnSuccess
Store
(data, [options]) OnSuccess
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 6-29. Add WU5061.0
Notes:
Add
Use add to store data as documents inside a collection
Example:
var data = {name: 'carlos', age: 99};
var options = {}; //default
WL.JSONStore.get(collectionName)
.add(data, options)
.then(function () {
//handle success
})
//handle failure
});
var data = {name: 'carlos', age: 99};
.add(data, options)
.then(function () {
//handle success
})
//handle failure
});
to add data to a collection.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 6-30. Find WU5061.0
Notes:
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 query = {name: 'carlos'};
var options = {
exact: false, //default
limit: 10 //returns a maximum of 10 documents, default: return every match
};
.find(query, options)
.then(function (arrayResults) {
//arrayResults = [{_id: 1, json: {name: 'carlos', age: 99}}]
})
//handle failure
});
var query = {name: 'carlos'};
var options = {
exact: false, //default
limit: 10 //returns a maximum of 10 documents, default: return every match
};
.find(query, options)
.then(function (arrayResults) {
//arrayResults = [{_id: 1, json: {name: 'carlos', age: 99}}]
})
//handle failure
});
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 6-31. Sample app Find buttons WU5061.0
Notes:
Sample app Find buttons
The sample app has buttons to demonstrate each type of search
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 6-32. Replace WU5061.0
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'.
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 document = {_id: 1, json: {name:
'carlitos', age: 99}};
.replace(document, options)
.then(function () {
//handle success
})
//handle failure
});
var document = {_id: 1, json: {name:
'carlitos', age: 99}};
.replace(document, options)
.then(function () {
//handle success
})
//handle failure
});
to data in a collection.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 6-33. Remove WU5061.0
Notes:
Remove
Use remove to delete a document from a collection
Documents are not erased from the collection until you call push
var query = {_id: 1};
var options = {exact: true}; //default:
false
.remove(query, options)
.then(function () {
//handle success
})
//handle failure
});
var query = {_id: 1};
var options = {exact: true}; //default:
false
.remove(query, options)
.then(function () {
//handle success
})
//handle failure
});
to remove a document.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 6-34. Remove collection WU5061.0
Notes:
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
.removeCollection()
.then(function () {
//handle success
})
//handle failure
});
.removeCollection()
.then(function () {
//handle success
})
//handle failure
});
to remove a collection.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 6-35. Destroy WU5061.0
Notes:
Destroy
Use destroy to remove all documents, collections, stores, and JSONStore
metadata and security artifacts
WL.JSONStore.destroy()
.then(function () {
//handle success
})
//handle failure
});
WL.JSONStore.destroy()
.then(function () {
//handle success
})
//handle failure
});
to destroy everything.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 6-36. Advanced features: Security (1 of 2) WU5061.0
Notes:
All keys are strengthened with Password-Based Key Derivation Function 2 (PBKDF2).
Advanced features: Security (1 of 2)
You can secure all the collections in a store by passing a password to the init
function
If no password is passed, the documents of all the collections in the store are
not encrypted
Data encryption is only available on Android and iOS environments
Some security metadata are stored:
In the Keychain, on iOS
In Shared Preferences, on Android
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.
Use changePassword to change the password
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 6-37. Advanced features: Security (2 of 2) WU5061.0
Notes:
Advanced features: Security (2 of 2)
Example:
var collections = {
people: {
searchFields: {name: 'string'}
}
};
var options = {
password: '123'
};
WL.JSONStore.init(collections, options)
.then(function () {
//handle success
})
//handle failure
});
var collections = {
people: {
}
};
var options = {
password: '123'
};
.then(function () {
//handle success
})
//handle failure
});
The sample app has buttons
for logging in, changing the
password and logging out.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 6-38. Advanced features: multiple user support (1 of 2) WU5061.0
Notes:
Advanced features: multiple user support (1 of 2)
You can create multiple stores that contain different collections in a single
Worklight application
The init function can take an options object with a user name
If no user name is given, the default user name is jsonstore
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 6-39. Advanced features: multiple user support (2 of 2) WU5061.0
Notes:
Advanced features: multiple user support (2 of 2)
Example:
var collections = {
people: {
}
};
var options = {
username: 'carlos'
};
.then(function () {
//handle success
})
//handle failure
});
var collections = {
people: {
}
};
var options = {
username: 'carlos'
};
.then(function () {
//handle success
})
//handle failure
});
The sample app has buttons
for logging in.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 6-40. Advance features: adapter integration (1 of 2) WU5061.0
Notes:
Advance features: adapter integration (1 of 2)
Worklight adapter integration is optional, and provides ways to:
Send data from a collection to a Worklight adapter.
Get data from a Worklight adapter into a collection.
You can achieve these goals by using functions such as
WL.Client.invokeProcedure or jQuery.ajax if you need more flexibility.
In Worklight Studio, you can use a new wizard to create a template JavaScript
file.
This creation is based on search fields that are selected from the back-end
system that you used to communicate with the adapter.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
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.
Example
function getPeople () {
return { peopleList : [{name: 'carlos',
age: 100},
{name: 'tim', age: 99}] };
}
function addPerson (data) {
return WL.Logger.debug('Got data from
JSONStore to ADD: ' + data);
}
function replacePerson (data) {
JSONStore to REPLACE: ' + data);
}
function removePerson (data) {
JSONStore to REMOVE: ' + data);
}
function getPeople () {
return { peopleList : [{name: 'carlos',
age: 100},
{name: 'tim', age: 99}] };
}
function addPerson (data) {
JSONStore to ADD: ' + data);
}
function replacePerson (data) {
JSONStore to REPLACE: ' + data);
}
function removePerson (data) {
JSONStore to REMOVE: ' + data);
}
After creating the adapter in
Worklight Studio, you see it in
the project navigation.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
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.
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
var collections = {
people: {
searchFields: {
name: 'string',
age: 'integer'},
//-- Start adapter metadata
adapter : {
name: 'people',
add: 'addPerson',
remove: 'removePerson',
replace: 'replacePerson',
load: {
procedure: 'getPeople',
params: [],
key: 'peopleList'
}
}
//-- End adapter metadata
}
};
var collections = {
people: {
searchFields: {
name: 'string',
age: 'integer'},
//-- Start adapter metadata
adapter : {
name: 'people',
add: 'addPerson',
remove: 'removePerson',
replace: 'replacePerson',
load: {
procedure: 'getPeople',
params: [],
key: 'peopleList'
}
}
//-- End adapter metadata
}
};
// (continued from the left column)
//Initialize
.then(function () {
//handle success
})
//handle failure
});
// (continued from the left column)
//Initialize
.then(function () {
//handle success
})
//handle failure
});
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Notes:
When load is called, JSONStore uses some metadata about the adapter (such
as name and procedure), which you previously passed to init, to determine
what data to get from the adapter and eventually store it
WL.JSONStore.get('people').load()
.then(function () {
//handle success
})
//handle failure
});
WL.JSONStore.get('people').load()
.then(function () {
//handle success
})
//handle failure
});
to load data from an adapter.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 6-44. Pushing and pulling changes WU5061.0
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
Pushing and pulling changes
If your application is connected to an enterprise system by using an adapter,
then you can use the data push function that is included in JSONStore
With the API, you can:
Push all or selected documents to the back-end system
Load data from the back-end system into the local store initially, or refresh the
local copy from the server
Local collection data is pushed or loaded by using a Worklight adapter
Instructor Guide
V8.1
Uempty
customers.load(options)
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 6-45. Example: getPushRequired WU5061.0
Notes:
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
()
.then(function () {
//handle success
})
//handle failure
});
WL.JSONStore.get('people').getPushRequired
()
.then(function () {
//handle success
})
//handle failure
});
to call getPushRequired.
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 6-46. Example: push WU5061.0
Notes:
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()
.then(function (res) {
//handle success
//res is an empty array if all documents
reached the server
//res is an array of error responses if some
documents failed
to reach the server
})
//handle failure
});
WL.JSONStore.get('people').push()
//handle success
//res is an empty array if all documents
reached the server
//res is an array of error responses if some
documents failed
to reach the server
})
//handle failure
});
to push changes to the
adapter.
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 6-47. Example: enhance WU5061.0
Notes:
Example: enhance
//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)
//res contains an array of documents
//with the results from the find
))
.fail(function () {
//handle failure
});
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
to add a key/value pair to a
collection.
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Notes:
Unit summary
Identify the Worklight client-side APIs that support storing data locally on a
device in an encrypted cache or a JSON data store.
Instructor Guide
Instructor notes:
the learning points
Instructor Guide
V8.1
Uempty
Notes:

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
Instructor Guide
Instructor notes:
Instructor Guide
V8.1
Uempty
Notes:
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
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Notes:

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
Instructor Guide
Instructor notes:
Instructor Guide
V8.1
Uempty
Notes:
Checkpoint answers
1. B. If you are developing Worklight hybrid apps that target iOS and Android
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Notes:
8.0
Exercise 3
Exploring local storage APIs
Instructor Guide
Instructor notes:
Instructor Guide
V8.1
Uempty
Notes:
Exercise objectives
Use an encrypted cache and the JSON data store in a mobile application
Instructor Guide
Instructor notes:
Details
Instructor Guide
Copyright IBM Corp. 2013 Unit 7. Working with UI frameworks 7-1
V8.1
Uempty
Unit 7. Working with UI frameworks
Estimated time
00:30
This unit shows how to use the jQuery Mobile, Sencha Touch and Dojo
Mobile UI frameworks in a mobile application.
Include the jQuery Mobile, Sencha Touch or Dojo Mobile UI
frameworks in a Worklight mobile application
Checkpoint
References
Instructor Guide
Notes:
Unit objectives
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 7-2. The need for an application toolkit WU5061.0
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
The need for an application toolkit
JavaScript provides APIs to manipulate the DOM on a web page, but
those APIs are not consistent across environments
CSS provides a means to separate page style from page content, but
CSS syntax and behavior varies across environments
Core JavaScript lacks efficient support for common web/mobile
application needs
Drag and drop, array handling, animation, and so on
HTML and JavaScript do not provide pre-built UI components and data
integration; each developer must build their own
Instructor Guide
V8.1
Uempty
as tabbed views, content panes, tree views, etc., HTML and JS do not do anything to make
constructing those UI views easier.
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
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.
Topics
Working with UI frameworks
Using jQuery Mobile
Using jQuery to build a multi-page application
Sencha Touch
Dojo Mobile
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty 7.1. Working with UI frameworks
Instructor Guide
Figure 7-4. Working with UI frameworks WU5061.0
Notes:
8.0
Working with UI
frameworks
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 7-5. Working with UI frameworks WU5061.0
Notes:
Working with UI frameworks
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
you a very high level of customization, but requires a large amount of
resources
Sometimes it is better to use the existing JavaScript UI frameworks
This module describes the development of Worklight applications
using three JavaScript UI frameworks:
JQuery Mobile 1.1
jQuery 1.8
Sencha Touch 1.1 or 2
Dojo Mobile
Dojo Toolkit 1.8
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 7.2. Using jQuery Mobile
Instructor Guide
Figure 7-6. Using jQuery Mobile WU5061.0
Notes:
8.0
Using jQuery Mobile
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 7-7. jQuery Mobile WU5061.0
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.
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 7-8. Working with jQuery Mobile WU5061.0
Notes:
Working with jQuery Mobile
jQuery is a fast and concise JavaScript framework that simplifies HTML
document flow, event handling, animating, and Ajax interactions for
rapid web development
Worklight client side framework uses jQuery library for internal
functionality
By default, the $ char is assigned to the internal jQuery in the
application main HTML file
If your application does not require jQuery, or if you want to use a
different version of jQuery, you can remove this line
For more information about jQuery, see http://jquery.com/
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 7-9. Adding jQuery to the Worklight application WU5061.0
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.
Adding jQuery to the Worklight application
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 7-10. jQuery Mobile basic structure WU5061.0
Notes:
jQuery Mobile basic structure
The basic structure of a screen in a jQuery Mobile application is:
Header and footer elements are optional
The page is rendered by jQuery Mobile at runtime
All the required styles are automatically applied
You can create your own styles and themes using ThemeRoller tool at
http://jquerymobile.com/themeroller/
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 7-11. jQuery Mobile widgets WU5061.0
Notes:
jQuery Mobile widgets
WYSIWYG editor is provided for jQuery Mobile widgets
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 7-12. jQuery Mobile application screen WU5061.0
Notes:
By using jQuery Mobile, you can create mobile application screens
in a few lines of code
For more information and documentation, see
http://jquerymobile.com/demos/
jQuery Mobile application screen
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 7.3. Sencha Touch
Instructor Guide
Figure 7-13. Sencha Touch WU5061.0
Notes:
8.0
Sencha Touch
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 7-14. Working with Sencha Touch WU5061.0
Notes:
Working with Sencha Touch
Sencha Touch allows developers to build mobile web apps that look
and feel native on iPhone, Android and BlackBerry touch devices
To download the Sencha Touch package, visit
http://www.sencha.com/products/touch/
Although the Sencha Touch package consists of many files, you only
need two of them to begin development - sencha-touch.js and
sencha-touch.css
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 7-15. Adding Sencha Touch components to an application WU5061.0
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.
Adding Sencha Touch components to an application
Add the Sencha Touch components to your application and add the
references to the <head> section of the main HTML
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 7-16. Working with Sencha Touch WU5061.0
Notes:
Working with Sencha Touch
When working with the Sencha Touch framework, build your
application UI using JavaScript
Visit Sencha Touch resources and learning center at
http://www.sencha.com/learn/touch/ to learn more
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 7.4. Dojo Mobile
Instructor Guide
Figure 7-17. Dojo Mobile WU5061.0
Notes:
8.0
Dojo Mobile
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 7-18. What is Dojo? WU5061.0
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.
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 7-19. Addind Dojo Toolkit package to a project WU5061.0
Notes:
Addind Dojo Toolkit package to a project
To add the Dojo Toolkit to your application place the Dojo Toolkit
package into your project root
This package contains compressed layers
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 7-20. Deployment configuration with Ant WU5061.0
Notes:
Deployment configuration with Ant
IBM Worklight Studio automatically uses
the build-dojo.xml file to specify which
parts of the Dojo Toolkit package, such as
compressed layers and resources, must
be deployed with your application
Note: The build-dojo.xml file stores the
configuration that must be deployed to run
a basic Dojo Mobile application. You can
modify this build file to add other layers to
deploy with your application.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 7-21. Creating custom layers WU5061.0
Notes:
Creating custom layers
To create custom layers, you can replace the provided Dojo Toolkit
package in your project with a Dojo Toolkit SDK.
To obtain a Dojo Toolkit SDK, go to the Dojo Toolkit website at
http://dojotoolkit.org/download/ and download the version that you want
to use
Update the build-dojo.properties file to indicate where to pick up the
Dojo Toolkit files from
Update the dojo.workspaceRoot property value to pick up the files from another
directory in your project, or from another project in your workspace
Use the dojo.root property instead if the directory is not in your workspace
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 7-22. Using a Dojo Mobile HTML template WU5061.0
Notes:
Using a Dojo Mobile HTML template
You can create mobile web
pages with a predefined Dojo
Mobile HTML template.
Using this template prepares the
web page to use Dojo Mobile
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Notes:
Unit summary
Instructor Guide
V8.1
Uempty
Instructor notes:
the learning points
Instructor Guide
Figure 7-24. Checkpoint (objective only) WU5061.0
Notes:

Checkpoint (objective only)
1. By default, what character is assigned to the internal jQuery in an
application's main JavaScript file?
A. $
B. !
C. @
D. #
2. To begin working with Sencha Touch, you need?
A. To write your own CSS style for each component from scratch
B. Only two files: sencha-touch.js and sencha-touch.css
C. All the files in the Sencha Touch package
D. Properly formatted header and footer elements
Instructor Guide
V8.1
Uempty
Instructor notes:
Instructor Guide
Notes:
Checkpoint answers
1. A. $
2. B. Only two files: sencha-touch.js and sencha-touch.css
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
Copyright IBM Corp. 2013 Unit 8. Apache Cordova 8-1
V8.1
Uempty
Unit 8. Apache Cordova
Estimated time
01:00
This unit explains the capabilities of the Apache Cordova framework
and describes the APIs that support them. It also shows you how to
create a Cordova plug-in, and it provides you with an example of a
WebViewOverlay plug-in that can be used to integrate server
generated pages in an application.
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
Checkpoint
Exercise
References
Instructor Guide
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.
Unit objectives
Use the Apache Cordova framework to access native device functions
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Notes:
Topics
Apache Cordova overview
Creating a plug-in
WebViewOverlay plug-in
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 8.1. Apache Cordova overview
Instructor Guide
Figure 8-3. Apache Cordova overview WU5061.0
Notes:
Apache Cordova
overview
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 8-4. What is Apache Cordova? WU5061.0
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.
What is Apache Cordova?
An open source mobile development framework.
It provides a JavaScript API that allows developers to access native
mobile device features and even execute native code using JavaScript.
The framework is integrated into Worklight-generated iOS and Android
projects.
5
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Purpose
Details
Instructor Guide
Figure 8-5. Apache Cordova referenced in the HTML file WU5061.0
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.
Apache Cordova referenced in the HTML file
Worklight automatically references the Cordova JavaScript library in
the main HTML of the generated project file to allow applications to use
the API directly
6
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 8-6. Apache Cordova library files WU5061.0
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.
Apache Cordova library files
The Cordova library files are automatically
added to iOS and Android projects
7
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Purpose
Details
Instructor Guide
Figure 8-7. Apache Cordova API basics: Cordova objects WU5061.0
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);
Apache Cordova API basics: Cordova objects
Various Cordova objects provide support for other device related
functions:
Device hardware and software information
device.<propertyName>
Lifecycle events
deviceready, pause, resume, online, offline, backbutton,
batterycritical, batterylow, batterystatus, menubutton,
searchbutton, startcallbutton, endcallbutton,
volumedownbutton, volumeupbutton
File related objects to read, write and navigate file system hierarchies
DirectoryEntry, DirectoryReader, File, FileEntry,
FileError, FileReader, FileSystem, FileTransfer,
FileTransferError, FileUploadOptions, FileUploadResult,
FileWriter, Flags, LocalFileSystem, Metadata
Media object to record and play back audio files
Media
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Purpose
Details
Instructor Guide
Figure 8-8. Apache Cordova usage example: Displaying a native alert WU5061.0
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.
Apache Cordova usage example: Displaying a native alert
Calling a native alert notification from JavaScript on iOS and Android
devices:
navigator.notification.alert(I am a native alert!!!!, null);
9
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Purpose
Details
Instructor Guide
Figure 8-9. Apache Cordova usage example: Retrieving information WU5061.0
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
Apache Cordova usage example: Retrieving information
Getting device hardware and software information:
10
This information is gathered using Cordova
JavaScript API
Device Name: iPhone Simulator
Device Cordova: 2.2.0
Device Platform: iPhone Simulator
Device UUID: 1234567890
Device Version: 6.0
This information is gathered using Cordova
JavaScript API
Device Name: SGH-1987
Device Cordova: 2.2.0
Device Platform: Android
Device UUID: 1234567890
Device Version: 2.2
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Purpose
Details
Here is another example of using Cordova API to get current running devices hardware
and software information.
All you need is get the device object from your JavaScript code, then you can access
variety of device information via its property For example.
device.nameReturns the name of the device's model or product
device.CordovaReturns the version of Cordova running on the device
device.platformReturns the device's operating system
device.uuidReturns the device's Universally Unique Identifier (UUID)
device.versionReturns the version of the operating system
Again, very simple API and easy to use.
Instructor Guide
Instructor Guide
V8.1
Uempty 8.2. Creating a plug-in
Instructor Guide
Figure 8-10. Creating a plug-in WU5061.0
Notes:
Creating a plug-in
Apache Cordova plugin overview
Creating a native plugin class for Android
Creating a native plugin class for iOS
Creating a plugin JavaScript wrapper
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Introduce the topic.
Details Mention the sub-topic outline listed at the bottom of the slide.
Instructor Guide
Figure 8-11. Apache Cordova Plugin Overview WU5061.0
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).
Apache Cordova Plugin Overview
Developers may need to use a specific 3rd party native library or a
device function
Cordova allows developers to create custom native code blocks and
invoke them via JavaScript
This technique is called a Cordova Plugin
12
Instructor Guide
V8.1
Uempty
Instructor Guide
Instructor notes:
Purpose Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 8-12. Apache Cordova plugin architecture WU5061.0
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.
Apache Cordova plugin architecture
13
An Apache Cordova plug-in consists of two parts:
Native code which runs on the devices operating system
For Android: Java code
For iOS: Objective-C code
A JavaScript wrapper
The plugin calls the native code and returns a callback invocation
using cordova.exec()
Native code
cordova.exec();
or
callback
Instructor Guide
Instructor notes:
Purpose Purpose
Details
Instructor Guide
V8.1
Uempty 8.3. Creating a native plugin class for Android
Instructor Guide
Figure 8-13. Creating a native plugin class for Android WU5061.0
Notes:
Creating a native
plugin class for
Android
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 8-14. Implementing a plugin: Java class WU5061.0
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.
Implementing a plugin: Java class
Create a Java class for the plugin
Extend org.apache.cordova.api.CordovaPlugin and add the
required imports:
public class HelloWorldPlugin extends CordovaPlugin {
Implement the execute() method
15
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Purpose
Details
Instructor Guide
Figure 8-15. Plugin class execute() method WU5061.0
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.
Plugin class execute() method
16
action input parameter indicates which plugin action to execute
Parameters for action are passed in a JSONArray
callbackContext specifies how to call back to JavaScript
public boolean execute(String action, JSONArray args,
CallbackContext callbackContext)
throws JSONException {
if (action.equals("sayHello")){
try {
String responseText = "Hello world, " + args.getString(0);
callbackContext.success(responseText);
} catch (JSONException e){
callbackContext.error("Failed to parse parameters");
}
return true;
}
return false;
}
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 8.4. Creating a native plugin class for iOS
Instructor Guide
Figure 8-16. Creating a native plugin class for iOS WU5061.0
Notes:
Creating a native
plugin class for iOS
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 8-17. Implementing the plugin: Objective-C class creation WU5061.0
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).
Implementing the plugin: Objective-C class creation
Create an Objective-C class for the plug-in
Import Cordova/CDV.h and inherit the CDVPlugin class
Add a property for the callbackId
Declare the method signature for the plugin
18
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 8-18. Plugin class method: Input parameters WU5061.0
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.
Plugin class method: Input parameters
The sayHello method takes one argument, command
This contains references to all the parameters of the invocation
The result is returned to the callback function of the calling JavaScript
object
19
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 8.5. Creating a plugin JavaScript wrapper
Instructor Guide
Figure 8-19. Creating a plugin JavaScript wrapper WU5061.0
Notes:
Creating a plugin
JavaScript wrapper
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 8-20. Implementing the plugin WU5061.0
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.
Implementing the plugin
The second step in implementing a plug-in is to create a JavaScript
wrapper for it and declare it in the DOM
Applies both to Android and iOS
21
Instructor Guide
V8.1
Uempty
You can now invoke the plug-in. The code is show on the next slide.
Instructor Guide
Instructor notes:
Purpose Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 8-21. Invoking the plugin from JavaScript WU5061.0
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.
Invoking the plugin from JavaScript
Invoke the plug-in by using:
window.plugins.<pluginFunctionName>.<pluginMethodName>(<parameters>)
22
Instructor Guide
Instructor notes:
Purpose Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 8-22. HelloWorldPlugin example screen shots WU5061.0
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.
HelloWorldPlugin example screen shots
23
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty 8.6. WebViewOverlay plugin
Instructor Guide
Figure 8-23. WebViewOverlay plugin WU5061.0
Notes:
WebViewOverlay
plugin
Motivation and overview
Java Implementation
JavaScript implementation
Examining the result
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 8-24. WebViewOverlay plugin: Motivation WU5061.0
Notes:
25
WebViewOverlay plugin: Motivation
Many enterprises today decide to develop their own customer or
employee facing mobile application.
Some of those companies already have mobile facing web-sites
(mobile web).
An important decision must be made by companies:
Should all of the mobile web features be implemented from scratch in the mobile
application, which is great from user experience perspective but very time and
money consuming?
Should the new mobile application contain only new features and the old
applications remain accessible by a mobile browser, which is easier to implement
but results in a poor user experience?
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Purpose
Details
Instructor Guide
Figure 8-25. WebViewOverlay plugin: Overview WU5061.0
Notes:
26
WebViewOverlay plugin: Overview
The WebView overlay approach allows reusing and integrating existing
mobile web sites within a new mobile application.
Navigation is smooth and seamless between the components that are
internal to the mobile application and the content that is on the external
mobile web site.
Web resources bundled
inside the application
External web content
This Page is implemented in
HTML and bundled with the
mobile application
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Purpose
Details
Instructor Guide
Figure 8-26. WebViewOverlay case study: Description WU5061.0
Notes:
27
WebViewOverlay case study: Description
The case study applications UI displays three tab bars:
Two tabs contain internal content.
The third tab shows an external IBM mobile web site
First and second tabs
contain internal web
resources
Third tab looks
exactly like another
application page
But technically, it has
an additional WebView
component on top
This Page is
implemented in HTML
and bundled with the
mobile application
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Purpose
Details
Instructor Guide
Figure 8-27. WebViewOverlay plugin: Implementation WU5061.0
Notes:
28
WebViewOverlay plugin: Implementation
WebViewOverlay is implemented using the Apache Cordova plugin
functionality
You can easily create your own protocol between internal web
components and the WebViewOverlay control
The next slides provide a case study example that shows how to create
a WebViewOverlay plugin
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Purpose
Details
Instructor Guide
Figure 8-28. WebViewOverlay Java implementation (1 of 4) WU5061.0
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.
29
WebViewOverlay Java implementation (1 of 4)
Declare a WebView object to display external content
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Purpose
Details
Instructor Guide
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.
30
Instantiate the WebViewOverlay object, set its properties and add it as
a view to a root element
public void onWLInitCompleted(Bundle savedInstanceState){
...
webViewOverlay = new WebView(this);
webViewOverlay.setVisibility(View.INVISIBLE);
webViewOverlay.setWebViewClient(webViewClient);
RelativeLayout.LayoutParams webViewOverlayLayoutParams =
new RelativeLayout.LayoutParams(
RelativeLayout.LayoutParams.FILL_PARENT,
RelativeLayout.LayoutParams.FILL_PARENT);
webViewOverlay LayoutParams.setMargins(0, 65, 0, 0);
webViewOverlay.setLayoutParams(webViewOverlayLayoutParams);
webViewOverlay.getSettings().setJavaScriptEnabled(true);
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Purpose
Details
Instructor Guide
Notes:
Set up the content view for the webViewOverlay
The steps are:
Create a RelativeLayout object to function as a root layout
Remove the root instance from its original parent
Add root and webViewOverlay to rootRelativeLayout
Set the content view to rootRelativeLayout
public void onWLInitCompleted(Bundle savedInstanceState){
...
RelativeLayout rootRelativeLayout =
new RelativeLayout(this);
((FrameLayout)root.getParent()).removeAllViews();
rootRelativeLayout.addView(root);
rootRelativeLayout.addView(webViewOverlay);
setContentView(rootRelativeLayout);
}
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Purpose
Details
Instructor Guide
Figure 8-31. WebViewOverlay Cordova plugin (1 of 3) WU5061.0
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 {
32
WebViewOverlay Cordova plugin (1 of 3)
Implement the Java code for the Cordova plugin
First, declare the actions that the plug-in supports
public class WebViewOverlayPlugin extends CordovaPlugin {
private final String ACTION_OPEN_URL = "open";
private final String ACTION_CLOSE_WEBVIEWOVERLAY = "close";
Instructor Guide
V8.1
Uempty
private final String ACTION_GO_BACK = "goBack";
@Override
public PluginResult execute(String action, JSONArray args, String callbackId) {
PluginResult result;
if (action.equals(ACTION_OPEN_URL)) {
WebViewOverlayApp.thisapp.runOnUiThread(new Runnable() {
public void run() {
WebViewOverlayApp.clearWebViewOverlayHistory();
WebViewOverlayApp.loadWebViewOverlay("http://m.ibm.com/");
WebViewOverlayApp.setWebViewOverlayVisibility(View.VISIBLE);
WebViewOverlayApp.requestWebViewOverlayFocus();
}
});
result = new PluginResult(PluginResult.Status.OK, PuginResult :: opened");
} else if (action.equals(ACTION_CLOSE_WEBVIEWOVERLAY)) {
public void run() {
WebViewOverlayApp.loadWebViewOverlayContent("");
WebViewOverlayApp.setWebViewOverlayVisibility(View.INVISIBLE);
}
});
result = new PluginResult(PluginResult.Status.OK, "PluginResult :: closed");
} else if (action.equals(ACTION_GO_BACK)) {
result = new PluginResult(PluginResult.Status.OK, "PluginResult :: back");
} else
result = new PluginResult(PluginResult.Status.INVALID_ACTION);
return result;
}
Instructor Guide
}
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Purpose
Details
Instructor Guide
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.
reference:
33
If an open request is received from the web part of the application,
load the external content and make the webViewOverlay visible.
public boolean execute(String action, JSONArray args, CallbackContext callbackContext) {
public void run() {
}
});
return true;
Instructor Guide
V8.1
Uempty
@Override
public void run() {
}
});
public void run() {
}
});
} else
return result;
}
Instructor Guide
}
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Purpose
Details
Instructor Guide
Notes:
Note that UI related actions should be performed on a dedicated UI thread.
reference:
34
If a close request is received from the web part of the application,
clean up the webViewOverlay and hide it
} else if (action.equals (ACTION_CLOSE_WEBVIEWOVERLAY)) {
WebViewOverlayApp.thisapp.runOnUiThread (new Runnable() {
public void run() {
WebViewOverlayApp.loadWebViewOverlayContent ("");
WebViewOverlayApp.setWebViewOverlayVisibility (View.INVISIBLE);
WebViewOverlayApp.clearWebViewOverlayHistory ();
}
});
Instructor Guide
V8.1
Uempty
@Override
public void run() {
}
});
public void run() {
}
});
} else
return result;
}
}
Instructor Guide
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Purpose
Details
Instructor Guide
Figure 8-34. WebViewOverlay JavaScript implementation (1 of 2) WU5061.0
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.
35
WebViewOverlay JavaScript implementation (1 of 2)
In JavaScript, create a WebViewOverlayPlugin object and populate it
with the required methods
function WebViewOverlayPlugin() {};
WebViewOverlayPlugin.prototype.open = function() {
cordova.exec (null, null, 'WebViewOverlayPlugin', 'open', []);
};
WebViewOverlayPlugin.prototype.close = function() {
cordova.exec (null, null, 'WebViewOverlayPlugin', 'close', []);
};
window.webViewOverlay = new WebViewOverlayPlugin();
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Purpose
Details
Instructor Guide
Figure 8-35. WebViewOverlay JavaScript implementation (2 of 2) WU5061.0
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.
36
WebViewOverlay JavaScript implementation (2 of 2)
Determine which tab was clicked
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();
}
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Purpose
Details
Instructor Guide
Figure 8-36. Modification to the code WU5061.0
Notes:
37
Modification to the code
In order to implement the WebViewOverlay technique on the Android
platform, the following changes are required to the Cordova code:
In the DroidGap.java file, the root element must be RelativeLayout and not
LinearLayout.
In the LinearLayoutSoftKeyboardDetect.java file, the class should extend
RelativeLayout instead of LinearLayout.
Make sure to use a Worklight certified Cordova version only when
applying these changes.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Purpose
Details
Instructor Guide
Figure 8-37. WebViewOverlay case study: Examining the result WU5061.0
Notes:
WebViewOverlay case study: Examining the result
38
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Purpose
Details
Instructor Guide
Notes:

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) Define the plugin in a Cordova configuration or properties file.
b) Create a native class to implement the plugin functionality.
c) Create a JavaScript wrapper to access the native code.
d) All of the above
Instructor Guide
V8.1
Uempty
Instructor notes:
Instructor Guide
Notes:
Unit summary
Instructor Guide
V8.1
Uempty
Instructor notes:
the learning points
Instructor Guide
Notes:
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.
2. True or False: All of the Apache Cordova standard APIs are
accessible through the navigator namespace.
False. Most of the standard APIs are accessible through the navigator
namespace, but a few a accessed through special Cordova objects. For
example, the device object is used to retrieved hardware and software
information.
3. Which step is required to develop an Apache Cordova plugin?
a) Define the plugin in a Cordova configuration or properties file.
b) Create a native class to implement the plugin functionality.
c) Create a JavaScript wrapper to access the native code.
d) All of the above
d) All of the above
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 8-41. Exercise WU5061.0
Notes:
Exercise
Using Apache Cordova to
access native device functions
Instructor Guide
V8.1
Uempty
Instructor notes:
Instructor Guide
Notes:
Exercise objectives
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 8-43. Apache Cordova additional resources WU5061.0
Notes:
You can get more information about Apache Cordova by visiting the web sites listed here.
Apache Cordova additional resources
Apache Cordova website:
http://incubator.apache.org/cordova/
Apache Cordova API Reference:
http://docs.phonegap.com/en/1.6.1/index.html
Apache Cordova Wiki:
http://wiki.apache.org/cordova/
44
4
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Purpose
Details
Instructor Guide
Instructor Guide
Copyright IBM Corp. 2013 Unit 9. Integration adapters 9-1
V8.1
Uempty
Unit 9. Integration adapters
Estimated time
01:00
This unit describes the types of integration adapters that Worklight
supports and how to use them to access enterprise resources.
Describe the types of integration adapters that Worklight supports
Use integration adapters to access enterprise resources
Checkpoint
Exercise
References
Instructor Guide
Notes:
Unit objectives
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Notes:
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 9.1. Adapters overview
Instructor Guide
Figure 9-3. Adapters - overview WU5061.0
Notes:
Adapters overview
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 9-4. Adapters: overview WU5061.0
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.
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
There are 4 adapter types:
SQL adapter
HTTP adapter (supports both REST and SOAP)
Cast Iron adapter
JMS adapter
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 9-5. Benefits of using adapters WU5061.0
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
Benefits of using adapters
Support multiple integration technologies and back-end information
systems
Support read-only and transactional access modes to back-end
systems
Defined with simple XML syntax
Easily configured with JavaScript API
Flexible authentication facilities used to create connections with back-
end systems (provide control over the identity of the connected user)
Reduced number of transactions performed on back-end systems by
using cache to store retrieved back-end data
Transparency: data retrieved from back-end applications is exposed in
a uniform manner regardless of the adapter type
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 9-6. IBM Worklight Adapter Framework WU5061.0
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.
Worklight Server
Procedure
JSON
JSON/
HTTP
IBM Worklight Adapter Framework
Application
Procedure call
Response
JavaScript
XSLT
(optional)
XML
Auto-conversion
To JSON
(if necessary)
Auto-conversion
To XML
(if necessary)
JSON
Back-end
format
B
a
c
k
-
e
n
d
A
p
p
l
i
c
a
t
i
o
n
Instructor Guide
V8.1
Uempty
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.
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 9-7. Anatomy of a Worklight adapter WU5061.0
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.
Anatomy of a Worklight adapter
Each Worklight adapter consists of:
An XML file, describing the connectivity options and listing the procedures
exposed to the application or other adapters
A JavaScript file, containing the implementation of procedures declared in the
XML file
Zero or more XSL files, containing a transformation scheme for retrieved raw
XML data
Data retrieved by an adapter can be returned raw or preprocessed by
the adapter itself
The data is presented to the application as a JSON object
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 9-8. Adapter procedures WU5061.0
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.
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
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 9-9. Creating an adapter (1 of 3) WU5061.0
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.
Creating an adapter (1 of 3)
In the Worklight project, right-click
Worklight Adapter
Select New Worklight Adapter
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
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.
Select the project
Choose an adapter type
Enter a name for the adapter
Applications access the adapter using this name
Click Finish
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
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.
Files are created and added to the project:
XML files to declare procedures and connection properties
JavaScript file to define procedures and adapter logic
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 9-12. Adapter deployment (1 of 2) WU5061.0
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.
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
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 9-13. Adapter deployment (2 of 2) WU5061.0
Notes:
The deployed adapter can be seen in the Worklight server Console, under the catalog tab
as shown in the screenshot here.
Adapter deployment (2 of 2)
You can see the deployed adapter in the Worklight Console
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 9-14. Testing adapter procedures (1 of 2) WU5061.0
Notes:
This is the same context menu you saw a couple of slides ago. This time, it is the third
option that is chosen.
Testing adapter procedures (1 of 2)
To perform a procedure test, select Invoke Worklight Procedure
from the Run As menu
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 9-15. Testing adapter procedures (2 of 2) WU5061.0
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.
Testing adapter procedures (2 of 2)
Select the procedure you want to test
The signature is displayed so that you know how many parameters to enter
Enter procedure parameters as a comma-separated list
Click Run
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 9-16. Adapter structure: XML WU5061.0
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.
Adapter structure: XML
wl:adapter name: mandatory attribute
displayName: the name to be displayed in the Worklight console
optional
description: additional information to be displayed in the Worklight
console
optional
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
procedure: declares a service for
accessing a back-end application
One entry for each adapter procedure
<wl:adapter name=>
<displayName />
<description />
<connectivity>
<connectionPolicy>
<loadConstraints>
</connectivity>
<procedure />
<procedure />
</wl:adapter>
<wl:adapter name=>
<displayName />
<description />
<connectivity>
<connectionPolicy>
<loadConstraints>
</connectivity>
<procedure />
<procedure />
</wl:adapter>
Instructor Guide
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.
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 9-17. Adapter structure: JavaScript WU5061.0
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.
Adapter structure: JavaScript
Each procedure declared in the adapter XML file must have a
corresponding function in the .js file
Procedure logic is defined in JavaScript by using WL.Server
API
18
XML file
JavaScript file
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 9.2. SQL adapters
Instructor Guide
Figure 9-18. SQL adapters WU5061.0
Notes:
SQL adapters
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 9-19. Worklight SQL adapters WU5061.0
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.
Worklight SQL adapters
A Worklight SQL adapter is designed to communicate with any SQL
data source
Plain SQL queries or stored procedures can be used
Worklight supports the following databases:
MySQL
Oracle 11g
Derby
DB2
Download the JDBC connector driver for a specific database type and
add to the lib directory of Worklight project
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 9-20. Creating a Worklight SQL adapter WU5061.0
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.
Creating a Worklight SQL adapter
Select SQL adapter type
A standard SQL adapter structure
consists of
an XML description file
a JavaScript implementation file
Place the JDBC connector file in the
project lib directory
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 9-21. XML file database connectivity settings WU5061.0
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
XML file database connectivity settings
There are four parameters declared in the adapter XML file:
Driver Class
Database URL
User name
Password
Instructor Guide
V8.1
Uempty
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.
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 9-22. JavaScript file procedure WU5061.0
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.
JavaScript file procedure
A procedure must be declared in the adapter XML file
The procedure logic is implemented in the adapter JavaScript file
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
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 9-23. JavaScript file SQL query WU5061.0
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.
JavaScript file SQL query
To execute an SQL query:
1. Prepare an SQL query using WL.Server.createSQLStatement
This API must always be called outside the function
2. Add parameters, if required
3. Use WL.Server.invokeSQLStatement to invoke prepared queries
Return results to the procedure invocator
Application, or another procedure
1
2
3
Instructor Guide
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.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 9-24. JavaScript file stored SQL procedure WU5061.0
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.
JavaScript file stored SQL procedure
To execute a stored SQL procedure
1. Use the WL.Server.invokeSQLStoredProcedure API to execute a stored
procedure.
2. Specify an SQL stored procedure name as an invocation parameter.
3. Add parameters if required.
Return invocation result to procedure invocator (application or another
procedure)
1
2
3
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 9-25. WL adapters invocation result WU5061.0
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.
WL adapters invocation result
Result retrieved as a JSON object
isSuccessful
Defines whether invocation was successful
resultSet
An array of returned records
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 9.3. HTTP adapters
Instructor Guide
Figure 9-26. HTTP adapters WU5061.0
Notes:
HTTP adapters
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 9-27. Worklight HTTP adapter WU5061.0
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.
Worklight HTTP adapter
Works with RESTful and SOAP-based services
Can read structured HTTP sources
For example, RSS feeds
Allows sending an HTTP request
GET or POST requests are supported
Retrieves data from the response headers and body
Customizable by server-side JavaScript
Optional server-side filtering
Retrieved data can be in the following formats:
XML
HTML
JSON
Plain text
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 9-28. Create an HTTP adapter WU5061.0
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.
Create an HTTP adapter
Basic adapter structure:
The properties and procedures of the adapter are defined in XML
Procedures are created in JavaScript
Optionally, use XSL to filter received records and fields
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 9-29. XML file connectivity settings WU5061.0
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
XML file connectivity settings
protocol
HTTP or HTTPS
domain
the domain part of the HTTP URL
port
TCP port
Instructor Guide
V8.1
Uempty
<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.
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 9-30. JavaScript file procedure implementation overview WU5061.0
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.
JavaScript file procedure implementation overview
Service URL is used for procedure invocation
Some parts of the URL are constant
For example, protocol and host name
They are declared in the XML file
Other parts of the URL can be parameterized
values provided at runtime to the Worklight procedure
URL parts that can be parameterized are:
Path elements
Query string parameters
http://example.com/rest/customers?custid=12
Path elements
Query string
Instructor Guide
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.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 9-31. Procedure declarations in the XML file WU5061.0
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.
Procedure declarations in the XML file
Any adapter function that should be publicly visible must be declared in
the configuration file
The name of the procedure in the configuration file must match the
name of the function in the JavaScript file.
The JavaScript file can have other functions that are not declared in the
configuration file
They are not visible outside of the adapter
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 9-32. JavaScript file procedures implementation WU5061.0
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.
JavaScript file procedures implementation
Required invocation parameters are:
method, returnedContentType and path
Procedure can be parameterized at runtime
Instructor Guide
V8.1
Uempty
returnedContentEncoding defines the encoding of the returned content. The default is
utf-8
Transformation when defined, transforms the output from the adapter before it reaches
the mobile application based on the XSL specified here.
Refer to the development reference guide for more details on specifics associated with
each of the items listed above.
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 9-33. XSL transformation filtering WU5061.0
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.
XSL transformation filtering
XSL transformation can be applied to the received data
Specify the transformation options in the procedure invocation input
parameters
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty 9.4. Using HTTP adapters with SOAP services
Instructor Guide
Figure 9-34. Using HTTP adapters with SOAP services WU5061.0
Notes:
Using HTTP adapters
with SOAP services
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 9-35. Creating a SOAP-based Service Request overview WU5061.0
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
Creating a SOAP-based Service Request overview
SOAP envelope can be created and sent directly using the
WL.Server.invokeHttp method
To invoke a SOAP-based service in an HTTP adapter:
encode the SOAP XML envelope within the request body
Use E4X, which is officially part of JavaScript 1.6
This technology can be used to encode any type of XML document, not
necessarily SOAP envelopes
If you receive error messages concerning the SOAP envelope, disable the
JavaScript validator by going to Project > Properties >Builders and unchecking
the JavaScript Validator
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 9-36. Creating a SOAP-based Service Request (1 of 2) WU5061.0
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.
Creating a SOAP-based Service Request (1 of 2)
Use JavaScript to create a SOAP Envelope
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 9-37. Creating a SOAP-based Service Request (2 of 2) WU5061.0
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.
Creating a SOAP-based Service Request (2 of 2)
You can insert JavaScript code and variables into SOAP XML.
They are evaluated at runtime.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 9-38. Service request invocation WU5061.0
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.
Service request invocation
WL.Server.invokeHttp(options) method is used to invoke a
request for a SOAP service
Options object must include the following properties:
method
usually POST
returnedContentType
usually XML
path
a service path
body
content
SOAP XML as a string
contentType
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 9-39. Full SOAP-based service invocation procedure example WU5061.0
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.
Full SOAP-based service invocation procedure example
SOAP
envelope
Options
Request
invocation
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 9.5. Cast Iron adapters
Instructor Guide
Figure 9-40. Cast Iron adapters WU5061.0
Notes:
Cast Iron adapters
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 9-41. Worklight Cast Iron adapter WU5061.0
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
42
Worklight Cast Iron adapter
A Worklight Cast Iron adapter initiates orchestrations in Cast
Iron to retrieve and return data to mobile clients
Worklight
Cast
Iron
Cloud apps
Enterprise
apps
Invoke procedure
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 9-42. Creating a Cast Iron adapter WU5061.0
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.
43
Creating a Cast Iron adapter
Create a new Worklight Adapter
Select Cast Iron Adapter type
A standard HTTP adapter structure is created
Procedures are implemented in the adapter JavaScript file
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 9-43. JavaScript file procedures implementation WU5061.0
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.
44
JavaScript file procedures implementation
To invoke a Cast Iron request, use the
WL.Server.invokeCastIron method
It expects an input object
You can specify:
HTTP method (get or post)
Application name
Request type
Service path
Returned content type
(XML, JSON, HTML, plain)
Transformation type
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 9.6. JMS adapters
Instructor Guide
Figure 9-44. JMS adapters WU5061.0
Notes:
JMS adapters
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 9-45. Java Message Service WU5061.0
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.
Java Message Service
Standard messaging API in Java
With JMS, you can read and write messages from any messaging
provider that supports the API
With the JMS adapter, you can read and write messages to any
messaging provider that supports JMS
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 9-46. Worklight JMS adapter WU5061.0
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.
Worklight JMS adapter
Select JMS from the adapter wizard
This generates two files:
an xml descriptor, used to configure connection properties
a JavaScript implementation
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 9-47. Implementing procedures WU5061.0
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.
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 9-48. Connection properties WU5061.0
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"/>
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
- url: the url of JNDI repository
- initialContextFactory: the classname for factory used for JNDI property
configuration
- user, password: the credentials as set up by the JNDI administrator
namingConnection is only necessary if you are using an external JNDI repository.
Instructor Guide
Figure 9-49. JMS adapter methods: reading messages WU5061.0
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,

}
},
{
JMS adapter methods: reading messages
readSingleJMSMessage
Gets the next message from
the destination
Waits for timeout in
milliseconds
Optional: a JMS message
selector
readAllJMSMessages
Accepts the same parameters
as the readSingleJMSMessage
method
Returns a list of JMS
messages in the same format
as the readSingleJMSMessage
method
The result is contained in a
messages object
var result =
WL.Server.readSingleJMSMessage({
destination : "jms/MyQ",
timeout : 60,
filter : "NewsType = 'Opinion'"
});
var result =
WL.Server.readAllJMSMessage({
destination : "jms/MyQ",
timeout : 60
});
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 9-50. JMS adapter methods: writing messages WU5061.0
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.
JMS adapter methods: writing messages
writeJMSMessage
writes a JMSText message
to the destination
User properties can be set
Returns the JMSMessageID of
the message that has been sent
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 9.7. Invoking Java code from an adapter
Instructor Guide
Figure 9-51. Invoking Java code from an adapter WU5061.0
Notes:
Invoking Java code
from an adapter
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 9-52. Overview WU5061.0
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.
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
In cases where JavaScript is not enough to implement this functionality
or a Java class that implements it already exists, it is possible to use
Java code in the adapter
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 9-53. Adding custom Java classes to a project WU5061.0
Notes:
Adding custom Java classes to a project
To use an existing Java library, add the JAR file to server\lib
directory of the Worklight project
After building and deploying the Worklight
Adapter, this JAR is automatically
deployed to the Worklight server
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 9-54. Adding custom Java classes to a project (1 of 2) WU5061.0
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.
Adding custom Java classes to a project (1 of 2)
To add custom Java code to a project, right-click the server/java
directory of the Worklight project and add a Java class file.
In this example, it is named Calculator1.java
Be sure to put this file inside a package
In this example, the package is
com.worklight.customcode
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 9-55. Adding a custom Java class to your project (2 of 2) WU5061.0
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.
Adding a custom Java class to your project (2 of 2)
Add two methods to the Java class:
In this example, one method is static, and therefore does require the creation of
a new instance of a class
This is just for the demonstration
If there are any other dependencies, put the required JAR files in the
server\lib directory of the Worklight project
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 9-56. Invoking custom Java classes from adapter WU5061.0
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().
Invoking custom Java classes from adapter
After creating custom Java code or adding JAR files, you can create
references from the Worklight Adapter JavaScript just as if it was
written in Java
The static Java method is evoked by direct reference with the full class
name
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 9.8. The InvocationData object
Instructor Guide
Figure 9-57. The InvocationData object WU5061.0
Notes:
The InvocationData
object
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 9-58. invocationData object WU5061.0
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
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
WL.Client.invokeProcedure (invocationData, options)
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 9-59. Options object WU5061.0
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
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.
The object is passed for all asynchronous calls to the server
60
var options = {
onSuccess : loadFeedsSuccess,
onFailure : loadFeedsFailure,
invocationContext : {}
};
Instructor Guide
V8.1
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.
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 9-60. Bringing it all together WU5061.0
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.",
Bringing it all together
61
1. Invocation data
2. Invoking the procedure
3. Setting the
success/failure handlers
4. Success handler
5. Failure handler
Instructor Guide
[{
text : 'Reload App',
handler : WL.Client.reloadApp
}]);
There is also a function to create the HTML code for the display.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 9-61. Invocation result (1 of 2) WU5061.0
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.
Invocation result (1 of 2)
A JSON object containing the data and additional information about
the procedure invocation is returned
Object is returned to a corresponding success/failure handler
62
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 9-62. Invocation result (2 of 2) WU5061.0
Notes:
Function loadFeedsSuccess (result){
WL.Logger.debug ("Feed retrieve successful");
if (result.invocationResult.Items.length > 0)
this.displayFeeds (
result.invocationResult.Items);
}
Function loadFeedsSuccess (result){
WL.Logger.debug ("Feed retrieve successful");
if (result.invocationResult.Items.length > 0)
this.displayFeeds (
result.invocationResult.Items);
}
Invocation result (2 of 2)
63
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 9.9. Invoking adapter procedures from Java code
Instructor Guide
Figure 9-63. Invoking adapter procedures from Java code WU5061.0
Notes:
Invoking adapter
procedures from Java
code
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 9-64. Invoking from Java WU5061.0
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().
Invoking from Java
JavaScript functions in adapters can be called from Java methods
Create an instance of the DataAccessService
DataAccessService is in worklight-extension-api.jar
Create a parameter array and a ProcedureQName instance
ProcedureQName holds the names of the adapter to be invoked and the procedure
Invoke the function and process the result
65
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 9.10.Server side scripting
Instructor Guide
Figure 9-65. Server side scripting WU5061.0
Notes:
Server side scripting
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 9-66. Server-side scripting WU5061.0
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.
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
67
Pre-
Processing
Procedure
Logic
Post-
Processing
Invoke procedure
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 9-67. Server-side API WU5061.0
Notes:
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 9-68. Mashups WU5061.0
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.
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
69
City Weather
(MySQL)
Server-side
JavaScript
Yahoo Weather
(RSS)
SQL
HTTP
CityWeather app
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Notes:

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
2. What is a Worklight SQL adapter designed for?
A. Translating actions into plain SQL queries
B. Working with RESTful and SOAP-based services
C. Implementing JavaScript
D. Communicating with any SQL data source
Instructor Guide
V8.1
Uempty
Instructor notes:
Instructor Guide
Notes:

Checkpoint
You can invoke an adapter procedure with this call:
3. Name one of the 3 name/value pairs for invocationData
4. Name one of the 3 name/value pairs for options
5. Which of the following may hold an array of messages about the
result of an invocation:
errors, isSuccessful, info, response, items, warnings
6. What is a mashup?
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Notes:
Unit summary
Instructor Guide
V8.1
Uempty
Instructor notes:
the learning points
Instructor Guide
Notes:
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
Adapter, procedure, parameters
4. Name one of the 3 name/value pairs for options
onSuccess, onFailure, invocationContext
5. Which of the following may hold an array of messages about the
result of an invocation:
errors, isSuccessful, info, response, items, warnings
6. What is a mashup?
An aggregation of data or functionality from different sources
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Notes:
Exercise
Developing an integration adapter
Instructor Guide
V8.1
Uempty
Instructor notes:
Instructor Guide
Notes:
Exercise objectives
Develop an adapter
Invoke an adapter from a client application
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Instructor Guide
Copyright IBM Corp. 2013 Unit 10. Native and web page integration 10-1
V8.1
Uempty
Unit 10. Native and web page integration
Estimated time
00:30
This unit describes the Worklight APIs that support the combination of
both native and web pages inside a mobile application.
Combine native and web pages in a mobile application
Use transition effects to animate the navigation between a native
and web page
Checkpoint
Exercise
References
Instructor Guide
Notes:
Unit objectives
Use transition effects to animate the navigation between a native and
web page
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Notes:
Topics
Overview of native and web page integration
Combining native and web pages on Android
Combining native and web pages on iOS
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 10.1.Overview of native and web page integration
Instructor Guide
Figure 10-3. Overview of native and web page integration WU5061.0
Notes:
Overview of native and
web page integration
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 10-4. Limitations of web technologies WU5061.0
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.
Limitations of web technologies
You can do a lot with web technologies only
Apache Cordova provides greater flexibility by allowing
JavaScript to access native device features
However, there are still cases where web technologies are not
enough
Augmented reality
Barcode scanner
Opening a native contacts page
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 10-5. Combining native and web pages WU5061.0
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.
Combining native and web pages
Worklight provides a simple way to augment your web application with
native pages.
Using Worklights hybrid coding approach you can:
Navigate freely between web and native pages
Share data between pages
Share a single server session
Implement your own functions by creating Cordova plug-ins
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 10-6. How does it work? WU5061.0
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.
How does it work?
Developer writes one or more native pages and web pages
Worklight JavaScript API allows navigation to native pages and back
including the passing of data back and forth
WL.NativePage.show(className, callback, data);
The web page invokes the native class, className, with the parameters, data.
Upon return, the callback function is invoked.
Instructor Guide
V8.1
Uempty
- 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.
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty 10.2.Combining native and web pages on Android
Instructor Guide
Figure 10-7. Combining native and web pages on Android WU5061.0
Notes:
Combining native and
web pages on Android
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 10-8. Native on Android: Activity class and manifest definition WU5061.0
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.
Native on Android: Activity class and manifest definition
An Android page must be implemented as an Android activity
Either extend the base Activity class or an existing subclass
Like any other activity, you must declare it in the
AndroidManifest.xml file
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 10-9. Native on Android: Receiving data from the web page WU5061.0
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).
Native on Android: Receiving data from the web page
When the activity is invoked, arguments passed from the web view can
be retrieved using an Intent object
JavaScript code
Native code
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 10-10. Native on Android: Returning control to the web page WU5061.0
Notes:
The sample code shown here passes the phoneNumber string back to the web page.
Native on Android: Returning control to the web page
When the native page needs to switch back to the web view, it call the
activitys finish() method.
You can pass data back to the web view by creating an Intent object.
JavaScript code
Native code
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 10-11. Native on Android: Animating transitions WU5061.0
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.
Native on Android: Animating transitions
You can animate page transitions with supported Android transition
effects in both direction
Use the overridePendingTransition() method
// Transition animation from the web view to the native page
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
overridePendingTransition(android.R.anim.fade_in,
android.R.anim.fade_out);
}
// Transition animation from the native page to the web view
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
//your code goes here....
finish();
}
// Transition animation from the web view to the native page
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
}
// Transition animation from the native page to the web view
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
//your code goes here....
finish();
}
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 10-12. Web page on Android: Invoking the native page WU5061.0
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.
Web page on Android: Invoking the native page
Use the WL.NativePage.show() API to invoke the native page
First parameter is the name of the activity to be started
Second parameter is the name of the callback function to be invoked when the
native activity is finished
Third parameter contains data to be passed to the native code
Data passed back by the native page is received in the callback
functions single argument
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 10.3.Combining native and web pages on iOS
Instructor Guide
Figure 10-13. Combining native and web pages on iOS WU5061.0
Notes:
Combining native and
web pages on iOS
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 10-14. Native on iOS: UIViewController subclass WU5061.0
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.
Native on iOS: UIViewController subclass
Create the native page in Xcode:
Add it to your projects Classes folder
Subclass UIViewController
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 10-15. Native on iOS: Receiving data from the web page WU5061.0
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).
Native on iOS: Receiving data from the web page
Custom data parameters passed from the web view can be retrieved by
using setDataFromWebView:(NSDictionary *)data
JavaScript code
Native code
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 10-16. Native on iOS: Returning control to the web page WU5061.0
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.
Native on iOS: Returning control to the web page
To switch back to the web view from the native page, call
NativePage showWebView
Make sure to import NativePage.h
Use a NSDictionary object to pass data back to the web view
Native code
JavaScript code
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 10-17. Native on iOS: Animating web to native transitions WU5061.0
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.
Native on iOS: Animating web to native transitions
You can animate transitions from the web to the native page with
supported iOS transition effects.
Implement the animation in the onBeforeShow and onAfterShow methods.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 10-18. Web page on iOS: Invoking the native page WU5061.0
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:
Web page on iOS: Invoking the native page
Use the WL.NativePage.show() API to invoke the native page
First parameter is the name of the UIViewController subclass that implements
the native page
Second parameter is the name of the callback function to be invoked when the
native page is finished
Third parameter contains data to be passed to the native code
functions single argument.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 10-19. Web page on IOS: Receiving data from the native page WU5061.0
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.
Web page on IOS: Receiving data from the native page
functions single argument.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Notes:

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.
Instructor Guide
V8.1
Uempty
Instructor notes:
Instructor Guide
Notes:
Unit summary
Use transition effects to animate the navigation between a native and
web page
Instructor Guide
V8.1
Uempty
Instructor notes:
the learning points
Instructor Guide
Notes:
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
d) WL.NativeShow
2. True or False: On the Android platform, the native page must be
implemented as a subclass of UIViewController.
False. On Android, the native page is implemented as an Activity
3. True or False: Data passed from and received by the web page is in
JSON format.
True
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Notes:
Exercise
Combining web and native pages
Instructor Guide
V8.1
Uempty
Instructor notes:
Instructor Guide
Notes:
Exercise objectives
Combine a native and a web page in a mobile application
Exchange data between a native and web page
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Instructor Guide
Copyright IBM Corp. 2013 Unit 11. Using Worklight native APIs 11-1
V8.1
Uempty
Unit 11. Using Worklight native APIs
Estimated time
01:00
This unit shows you how to use the application management features
of IBM Worklight. This unit describes the Worklight APIs that enable a
native Android or iOS client application to invoke an adapter procedure
running on Worklight Server.
Create a Worklight Native API application
Configure the native application
Invoke an adapter procedure
Manage a procedure response
Checkpoint
References
Instructor Guide
Notes:
Unit objectives
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 11-2. Worklight native API WU5061.0
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.
Worklight native API
IBM Worklight provides the ability for native applications to
communicate with a Worklight server by using the Worklight native API
library
In order to serve a native application the Worklight server needs to be
aware of it
A Worklight native API is located under apps folder of your Worklight
project
A Worklight native API folder serves two purposes:
It contains a native API library and a configuration file that must be copied to
your native project
It contains an application-descriptor.xml file, which can be deployed to
a Worklight Server to serve as an entry point, similar to a Worklight application
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 11-3. Why use native API capabilities? WU5061.0
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.
Why use native API capabilities?
iOS and Android applications can communicate with the Worklight
server and benefit from features such as
Application Management
Native APIs for remote disable and Notify on Start up
Backend Integration
Native API to invoke adapter procedures
Authentication
Native APIs for custom client-side authentication
Analytics
Native API for Reporting
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 11-4. Creating a Worklight native API WU5061.0
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.
Creating a Worklight native API
1. In Worklight Studio, create a Worklight project, and add a Worklight
Native API
2. In the New Worklight Native API dialog, enter your application
name, and select Android or iOS for the Environment field
3. Right-click the Worklight native API folder and select Build and
Deploy
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 11.1.Android native API
Instructor Guide
Figure 11-5. Android native API WU5061.0
Notes:
The following slides discuss the Android native API. If your interest is in iOS, move on to
the topic entitled iOS native API.
8.0
Android native API
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 11-6. Android native API WU5061.0
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.
Android native API
Defines application meta data and security
configuration
wlclient.properties
Contains connectivity settings to be used by
a native Android application.
This file must be copied to the native Android
project
This file is discussed in detail further on
worklight-android.jar
A Worklight API library that must be copied
to the native Android project
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 11-7. Editing wlclient.properties (Android) WU5061.0
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
Editing wlclient.properties (Android)
Edit wlclient.properties, which holds the server configuration
Instructor Guide
V8.1
Uempty
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 11-8. Configure an Android native application WU5061.0
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.
Configure an Android native application
Create a native Android application
Copy two files from the Worklight native API folder to the new native
Android application:
worklight-android.jar goes to /libs
wlclient.properties goes to/assets
Add two permissions and an activity to AndroidManifest.xml :
Internet permission
<uses-permission
android:name="android.permission.INTERNET"/>
WIFI permission
< uses-permission
android:name="android.permission.ACCESS_WIFI_STATE"/>
Worklight UI activity
<activity
android:name="com.worklight.wlclient.ui.UIActivity"/>
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 11-9. Initializing the WLClient - Android WU5061.0
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.
Initializing the WLClient Android
Create an instance of the WLClient
It requires a reference to the activity in which it is running
final WLClient client = WLClient.createInstance(this);
To connect to a Worklight Server, use the connect method by
specifying the MyConnectListener class instance as a parameter
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 11-10. MyConnectListener - Android WU5061.0
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.
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 {}
This interface defines two methods:
public void onSuccess (WLResponse response)
public void onFailure (WLFailResponse response)
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 11-11. Invoking a procedure - Android WU5061.0
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.
Invoking a procedure Android
use the WLClient instance to invoke adapter procedures
1
2
3
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 11-12. Processing a response: Android - MyInvokeListener WU5061.0
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.
Processing a response: Android MyInvokeListener
The WLClient instance calls one of the methods of the
MyInvokeListener class
MyConnectListener class implements the WLResponseListener
interface
public class MyInvokeListener
implements WLResponseListener{
The onSuccess and onFailure methods are invoked by the
WLClient
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 11-13. Processing a response: Android - MyConnectListener WU5061.0
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.
Processing a response: Android MyConnectListener
If the procedure invocation is successful, the onSuccess method of
MyInvokeListener is invoked
Use it to get data that are retrieved from the adapter
The response object contains the response data
Use its methods and properties to retrieve the required information
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty 11.2.iOS native API
Instructor Guide
Figure 11-14. iOS native API WU5061.0
Notes:
The next slides discuss the same topics as the previous, but this time from the point of view
of the iOS application.
8.0
iOS native API
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 11-15. iOS native API WU5061.0
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.
iOS native API
WorklightAPI
A Worklight API library that must be copied
to the native iOS project
Defines application meta data and security
configuration
Worklight.plist
Contains connectivity settings to be used
by a native iOS application.
This file must be copied to the native iOS
project
This file is discussed in detail further on
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 11-16. Editing worklight.plist (iOS) WU5061.0
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
Editing worklight.plist (iOS)
Edit the worklight.plist file that holds the server configuration
Instructor Guide
V8.1
Uempty
- environment
Target environment of the native application
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 11-17. Configure an iOS native application WU5061.0
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.
Configure an iOS native application
Create a new Xcode project (or use an existing one)
Copy the WorklightAPI folder and the worklight.plist file from the eclipse
Worklight native API to the root of your native project
Link the following libraries in your native iOS application
CFNetwork
SystemConfiguration
MobileCoreServices
CoreData
Security
libz.dylib
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 11-18. Initializing the WLClient - iOS (1 of 3) WU5061.0
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
Initializing the WLClient iOS (1 of 3)
Create an instance of the WLClient to communicate with the Worklight
server by using the wlConnectWithDelegate
Make sure to import the WLClient.h and the WLDelegate.h in the
header file
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
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.
Create a delegate called MyConnectListener for
wlConnectWithDelegate to receive the response from the server
The header file must specify that it implements the WLDelegate
protocol.
WLDelegate specifies that the class implements these methods:
onSuccess (WLResponse *)response
onFailure (WLFailResponse *)response
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
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.
The onSuccess and onFailure methods are coded as follows:
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 11-21. Invoking a procedure - iOS WU5061.0
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.
Invoking a procedure iOS
Create a WLProcedureInvocationData object and specify the
adapter name and the procedure name
Invoke the procedure using a shared instance of WLClient
The code requests the delegate to take care of the invocation result
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 11-22. Processing a response: iOS - MyInvokeListener WU5061.0
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) {}
Processing a response: iOS MyInvokeListener
When the procedure invocation is completed, it sends a message to an
instance of the MyInvokeListener class
A delegate header must comply with a WLDelegate protocol
If the procedure invocation was successful, the onSuccess method
from MyInvokeListener is invoked
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Notes:

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?
Instructor Guide
Instructor notes:
Instructor Guide
V8.1
Uempty
Notes:
Unit summary
Instructor Guide
Instructor notes:
the learning points
Instructor Guide
V8.1
Uempty
Notes:

Checkpoint answers
1. "Defines application meta data and security configuration
Which file is this defining?
application_descriptor.xml
2. In an Android application, you need to add an internet permission.
Which file do you edit?
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?
Procedure name
Instructor Guide
Instructor notes:
Instructor Guide
Copyright IBM Corp. 2013 Unit 12. Security 12-1
V8.1
Uempty
Unit 12. Security
Estimated time
01:30
This unit describes the authentication techniques provided by
Worklight to secure a mobile application and the server-side APIs that
support them.
Describe the different authentication approaches supported by
Worklight
Use server-side APIs to secure a mobile application
Checkpoint
Exercise
References
Instructor Guide
Notes:
Unit objectives
Worklight
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Notes:
Topics
Authentication concepts and entities
Adapter-based authentication
Custom login modules
WebSphere LTPA-based authentication
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 12-3. Authentication WU5061.0
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.
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
Instructor Guide
V8.1
Uempty
A login-module is a server-side component and is used to validate the user credentials
received from the authenticator.
To integrate and use WebSphere Application Servers security service, you can use the
predefined realm IBMWebSphereLTPARealm.
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 12-4. Authentication sequence WU5061.0
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.
Authentication sequence
5
Authenticator collects the user
credentials
Authenticator collects the user
credentials
The server asks the client to
provide credentials (a
challenge)
The server asks the client to
provide credentials (a
challenge)
Challenge Handler : detects
the challenge, collects the
credentials, and sends them to
the Authenticator
Challenge Handler : detects
the challenge, collects the
credentials, and sends them to
the Authenticator
The client application auto-
matically resends the request
The client application auto-
matically resends the request
If the supplied credentials pass
validation, Login Module
creates the User Identity
object and flags session as
authenticated in a given realm
If the supplied credentials pass
validation, Login Module
creates the User Identity
object and flags session as
authenticated in a given realm
Authentication success
message returned to user
Authentication success
message returned to user
Client
Unauthenticated user tries to
access the resource protected
by an authentication realm
Unauthenticated user tries to
access the resource protected
by an authentication realm
Server
Instructor Guide
Instructor notes:
Details When a request is made to the protected entity, Worklight checks whether the
session is already authenticated. If not, Worklight automatically triggers a process of
verifying the users identity:
a. Unauthenticated request tries to access the protected application, or invokes a
protected adapter procedure.
b. Authenticator is invoked automatically. User credentials (for example, user name
and password) are collected on the client side and sent to a server.
c. Login module receives collected credentials, validates them, and builds user identity
in case validation passes.
d. The original request is handled.
Instructor Guide
V8.1
Uempty
Figure 12-5. Authentication entities: challenge handler WU5061.0
Notes:
The challenge comes from the server. The challenge handler therefore has functions that
are called when a server responds to a client request.
Authentication entities: challenge handler
A client side entity that controls the authentication process
Used to detect and handle authentication challenges in the server responses
A separate challenge handler instance should be created for each
realm an application needs to authenticate in
It can be used to detect and handle Worklight-related and external
authentication challenges (authentication proxies, gateways)
Upon detecting an authentication challenge returned from the server, it
is responsible for collecting and returning the required credentials
After the authentication flow completes, the challenge handler can send
notification back to the Worklight framework about success or failure
Created with a predefined set of methods
used to submit credentials
to the built-in authentication
types of the Worklight Server
6
Instructor Guide
Instructor notes:
Purpose
Details Details
Instructor Guide
V8.1
Uempty
Figure 12-6. Authentication entities: authenticator WU5061.0
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.
Authentication entities: authenticator
A server-side entity responsible for collecting credentials from the client
application
An authenticator can collect any type of information accessible from an HTTP
request object cookies, headers, body, or any other properties
The Worklight server includes a set of predefined authenticators:
Form-based authenticator. Returns a challenge in the form of an HTML login
form, making it useful for web environments as well as mobile applications
Adapter-based authenticator. Uses the Worklight adapter procedure to collect
and validate the credentials from the client application.
A header-based authenticator. Does not require interactive credentials collection,
but instead checks a specific HTTP header
7
Security test
Realm
Login module
Authenticator
Instructor Guide
Instructor notes:
Purpose
Details Details
Instructor Guide
V8.1
Uempty
Figure 12-7. Authentication entities: login module WU5061.0
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.
Authentication entities: login module
A server-side entity responsible for verifying user credentials, and for
creating a user identity object to hold user properties for the session.
Credential validation can be done in one of the following ways:
Using a web service
Looking up the user in a users table in a database
Using the WebSphere LTPA token
It is possible to add custom user properties according to the enterprise
needs
The user identity object is destroyed on session termination
It can be configured to automatically record login attempts for audit
purposes
In addition to predefined login modules, you can create your own
custom login module using Java code
8
Security test
Realm
Login module
Authenticator
Instructor Guide
Instructor notes:
Purpose
Details Details
Instructor Guide
V8.1
Uempty
Figure 12-8. Authentication entities: authentication realms WU5061.0
Notes:
Each authentication realm defined in the server authentication configuration should have a
corresponding challenge handler in the client application.
Authentication entities: authentication realms
A combination of one authenticator and one login module
Each authentication realm defines its authentication flow:
What should happen after the authentication process is triggered?
What is the form of challenge that should be sent to the client application?
Which credentials should be collected?
How and when should credentials be collected?
How should credentials be sent to server?
How should credentials be validated by server?
What is the result of the credentials validation?
What are the properties of the user identity object?
Worklight provides predefined authentication realms for security
features (remote application disable, application authenticity)
9
Security test
Realm
Login module
Authenticator
Instructor Guide
Instructor notes:
Purpose
Details Details
Instructor Guide
V8.1
Uempty
Figure 12-9. Authentication entities: security tests WU5061.0
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.
Authentication entities: security tests
A security test is an ordered set of authentication realms that is used to
protect a resource such as an adapter procedure, an application, or a
static URL
A security test defines the realms that the user must authenticate
against in order to get access to the protected resource
A developer can define the order in which the authentication should be
performed
For example, execute request authentication in realm2 only if realm1
authentication has succeeded
10
Security test
Realm
Login module
Authenticator
Instructor Guide
Instructor notes:
Purpose
Details Details
Instructor Guide
V8.1
Uempty
Figure 12-10. Authentication concepts and entities WU5061.0
Notes:
The same Authenticator type can be used for several realms.
11
Security test 3
Realm 3
Login module 3
Authenticator 2
Security test 2
Realm 2
Login module 2
Authenticator 1
Security test 1
Realm1
Login module 1
Authenticator 1
Instructor Guide
Instructor notes:
Purpose
Details Details
Instructor Guide
V8.1
Uempty
Notes:
A realm has one authenticator and one login module
12
Security test 3
Realm 3
Login module 3
Authenticator 2
Security test 2
Realm 2
Login module 2
Authenticator 1
Security test 1
Realm1
Login module 1
Authenticator 1
Instructor Guide
Instructor notes:
Purpose
Details Details
Instructor Guide
V8.1
Uempty
Notes:
A security test can use one or more realms
13
Security test 3
Realm 3
Login module 3
Authenticator 2
Security test 2
Realm 2
Login module 2
Authenticator 1
Security test 1
Realm1
Login module 1
Authenticator 1
Instructor Guide
Instructor notes:
Purpose
Details Details
Instructor Guide
V8.1
Uempty
Notes:
A realm can be used by one or more security tests
14
Security test 3
Realm 3
Login module 3
Authenticator 2
Security test 1
Realm1
Login module 1
Authenticator 1
Security test 2
Realm 2
Login module 2
Authenticator 1
Instructor Guide
Instructor notes:
Purpose
Details Details
Instructor Guide
V8.1
Uempty
Figure 12-14. Defining realms WU5061.0
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.
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
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 12-15. Defining login modules WU5061.0
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.
16
Defining login modules
Each login module has a name attribute and a tag with the className
of the implementation
There may be an audit attribute
Some login modules have parameters
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 12-16. Defining authenticators WU5061.0
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.
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
Worklight allows writing custom login modules and authenticators
when the default ones are not sufficient
Worklight contains all necessary libraries to support WebSphere
Application Server security
For more information about Worklight authentication concepts, see
the Developer Reference Guide and Administration Guide
Instructor Guide
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.
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 12-17. Defining security tests (1 of 2) WU5061.0
Notes:
18
Defining security tests (1 of 2)
The IBM Worklight platform allows setting up multiple realms for a
security test
As a part of the security test setup, you must tell IBM Worklight which
of the realms are considered a user realm and a device realm
An identity that is taken from a realm that is defined as a user realm is
used by IBM Worklight as a user identity for features that require one,
such as the push notification or the application usage reports
An identity that is taken from a realm that is defined as a device realm
is used by IBM Worklight as a device identity for features that require
one, such as the device provisioning, the push notification, and the
SMS notification
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 12-18. Defining security tests (2 of 2) WU5061.0
Notes:
Defining security tests (2 of 2)
After you set up your authentication realms, you must define the
security tests used to protect your applications, adapter procedures,
and static resources
There are three types of security tests that can be defined in the
authenticationConfig.xml file:
The webSecurityTest a test that has default web security-related realms
enabled.
The mobileSecurityTest a test that has default mobile security-related realms
enabled.
The customSecurityTest a custom security test. Does not contain any default
realm.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 12-19. webSecurityTest WU5061.0
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.
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
Each webSecurityTest must contain one <testUser> element with a
realm definition
This realm is considered a user realm
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 12-20. mobileSecurityTest WU5061.0
Notes:
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
Each mobileSecurityTest must contain one <testUser> element with
realm definition
This realm is
considered a user
realm
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 12-21. customSecurityTest WU5061.0
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.
customSecurityTest
The customSecurityTest defines custom security preferences
The developer defines realms
Any number of tests can be defined
User or device realms can be defines
Authentication order can be defined
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 12-22. Protecting adapters WU5061.0
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.
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 12-23. Protecting applications WU5061.0
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.
Protecting applications
Authentication is required immediately when an application connects
to the Worklight server
A separate securityTest can be defined for each application
environment
Instructor Guide
V8.1
Uempty
If no securityTest is defined for a specific environment, only a minimal set of default
platform tests is performed.
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 12-24. Protecting static resources WU5061.0
Notes:
Protecting static resources
A static resource is a URL loaded from a Worklight server:
For example: the Worklight console or mobile web application.
Protecting a static resource means that the Worklight server
requires authentication when an attempt to browse to the
specified URL is made.
The static resources and their protection can be defined in the
authenticationConfig.xml file.
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty 12.1.Adapter-based authentication
Instructor Guide
Figure 12-25. Adapter-based authentication WU5061.0
Notes:
Adapter-based
authentication
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 12-26. Adapter-based authentication WU5061.0
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.
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 12-27. Adapter-based authentication process WU5061.0
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.
Adapter-based authentication process
Application tries to access a
protected resource
Worklight platform checks whether
user is already authenticated
Protected resource access is
granted. Application receives the
requested data.
Authentication process is started. Application
receives the authentication required payload
as defined by the developer.
Success
YES
YES
NO
NO
Authentication process
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Provide a high-level overview of this section.
Details This section goes through the process of configuring adapter-based
authentication, step-by-step.
Instructor Guide
Figure 12-28. Configuring a realm on authenticationConfig.xml WU5061.0
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.
Configuring a realm on authenticationConfig.xml
Add a new authentication realm to authenticationConfig.xml
This realm uses SingleStepAuthLoginModule login module, defined later
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 12-29. Configuring a login module on authenticationConfig.xml WU5061.0
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.
Configuring a login module on authenticationConfig.xml
NonValidatingLoginModule means that no additional validation is
performed by the Worklight Platform, and the developer takes
responsibility for credential validation within the adapter
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 12-30. Configuring authenticationConfig.xml WU5061.0
Notes:
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 12-31. Server-side authentication: components overview WU5061.0
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.
Server-side authentication: components overview
The flow to be implemented:
getSecretData
Authentication is required
submitAuthentication
You are authenticated now
Application
Worklight
Server
getSecretData
Here is your secret data
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 12-32. Server-side authentication components (1 of 3) WU5061.0
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.
Server-side authentication components (1 of 3)
SimpleAuthAdapter defines two procedures that are publicly visible
submitAuthentication: No security constraint
requestForData: Requires the user to be logged in
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
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.
Whenever the Worklight framework detects an unauthenticated
attempt at access to a protected resource, the onAuthRequired
function is invoked (as previously set up in the
authenticationConfig.xml file)
This function receives response headers and an optional
errorMessage parameter. The object returned by this function is
sent to the client application.
Note the authRequired: true property. The client application uses
this property to detect the request for authentication
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
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.
submitAuthentication is invoked by a client
Instructor Guide
V8.1
Uempty
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 12-35. Invoking the protected function WU5061.0
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.
Invoking the protected function
getSecretData function returns a hardcoded value in this example
The onLogout function is defined in the authenticationConfig.xml file to be
invoked automatically on logout
To perform a cleanup, for example
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 12-36. Client-side authentication : HTML AppDiv WU5061.0
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.
Client-side authentication : HTML AppDiv
The common HTML consists of two main <div> elements
<div id=AppDiv> element is used to display the application content
<div id=AuthDiv> element is used for authentication form purposes
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 12-37. Client-side authentication : HTML AuthDiv WU5061.0
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).
Client-side authentication : HTML AuthDiv
AuthDiv contains the following elements
AuthInfo to display error messages
AuthUsername and AuthPassword input elements
AuthSubmitButton button
AuthDiv is styled as display:none, because it must not be displayed
before authentication is requested by the server
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 12-38. Client-side authentication : challengeHandler WU5061.0
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.
Client-side authentication : challengeHandler
Create a challenge handler
Use WL.Client.createChallengeHandler() to create a challenge
handler object
A realm name must be supplied as a parameter
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 12-39. More challengeHandler functions WU5061.0
Notes:
You see these functions used for the implementation of the challenge handler further on.
More challengeHandler functions
myChallengeHandler.submitAdapterAuthentication()
Used to send credentials to a specific adapter procedure. It has the same
signature as the WL.Client.invokeProcedure() API
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
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 12-40. Creating client-side authentication components (8 of 11) WU5061.0
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.
Creating client-side authentication components (8 of 11)
The isCustomResponse function detects whether the server
response contains the challenge object previously defined
The challenge object was defined
in the adapter
Adapter code
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 12-41. Create the Handler function WU5061.0
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.
Create the Handler function
Handler prepares the authentication view
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 12-42. Binding the AuthSubmitButton to a function WU5061.0
Notes:
There is no need to specify the callbacks because the response is checked by the
Worklight framework.
Binding the AuthSubmitButton to a function
Clicking a login button triggers a function that collects the user name
and password from the HTML input fields, and submits them to the
adapter
The challenge handler submitAdapterAuthentication method is
used to bind the click to the function
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty 12.2.Custom login modules
Instructor Guide
Figure 12-43. Custom login modules WU5061.0
Notes:
Custom login modules
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 12-44. Session scope and additional modules WU5061.0
Notes:
Session scope and additional modules
Authenticator, Login Module and User Identity instances are stored in a
session scope. They exist as long as the session exists
You can write custom login modules and authenticators when the
default ones do not suffice
The previous topic described how to implemented an adapter-based
authentication without using additional login modules
You used a non-validating login module and performed credentials validation
manually using an adapter
In some cases, when credential validation cannot be performed on the
adapter level and requires more complex code, an additional login
module can be implemented, for example:
Enterprise custom credentials validation is required
Additional information must be retrieved from each client request, such as
cookie, header, user-agent, and so forth
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 12-45. Custom authenticator overview WU5061.0
Notes:
Custom authenticator overview
Implement a custom authenticator that collects user name and
password by using a request to a predefined URL.
Implement a custom login module that checks credentials received
from the authenticator.
Define a realm that uses your custom authenticator and login module.
Write a simple application that is protected by this realm. It runs the
authenticator and is used to authorize users with the custom login
module
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 12-46. Configuring authenticationConfig.xml (1 of 2) WU5061.0
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.
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
Specify MyCustomAuthenticator as className
In the loginModules section add a new loginModule called
CustomLoginModule with class MyCustomLoginModule
<realm name="CustomAuthenticatorRealm"
loginModule="CustomLoginModule">
<className>com.mypackage.MyCustomAuthenticator</className>
</realm>
<realm name="CustomAuthenticatorRealm"
loginModule="CustomLoginModule">
<className>com.mypackage.MyCustomAuthenticator</className>
</realm>
<loginModule name ="CustomLoginModule" canBeResourceLogin="true
isIdentityAssociationKey="false">
<className>com.mypackage.MyCustomLoginModule</className>
</loginModule>
<loginModule name ="CustomLoginModule" canBeResourceLogin="true
isIdentityAssociationKey="false">
<className>com.mypackage.MyCustomLoginModule</className>
</loginModule>
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 12-47. Configuring authenticationConfig.xml (2 of 2) WU5061.0
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.
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>
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 12-48. Authenticator API (1 of 2) WU5061.0
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.
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)
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 12-49. Authenticator API (2 of 2) WU5061.0
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.
Authenticator API (2 of 2)
Map<String, Object> getAuthenticationData()
HttpServletRequest getRequestToProceed(HttpServletRequest request,
HttpServletResponse response, UserIdentity userIdentity, LoginExtension...
loginExtension)
Boolean changeResponseOnSuccess (HttpServletRequest request,
HttpServletResponse response)
WorklightAuthenticator clone()
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 12-50. Creating a custom Java authenticator WU5061.0
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.
Creating a custom Java authenticator
Create a new class in server\java folder. Call it
MyCustomAuthenticator
Make sure it implements the WorklightAuthenticator interface
Add the authenticationData object to your Authenticator to hold
the credentials information. This object is retrieved by a login module
public class MyCustomAuthenticator implements WorklightAuthenticator {
public class MyCustomAuthenticator implements WorklightAuthenticator {
private Map<String, Object> authenticationData = null ;
private Map<String, Object> authenticationData = null ;
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 12-51. Server library dependency WU5061.0
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.
Server library dependency
Add a Server runtime library dependency in order to use server related
classes, e.g. HttpServletRequest. The steps are:
Right-click the Worklight project and select Properties
Select Java Build Path Libraries and click Add Library
Select Server Runtime and click Next
You see a list of Server Runtimes installed in your Eclipse
Select the required library
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 12-52. Custom Java Authenticator: init() and clone() WU5061.0
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
Clone is a routine Java method to create a deep copy of the members of a class.
Custom Java Authenticator: init() and clone()
The init(..) method is invoked when Authenticator instance is created. It
receives options map specified in a realm definition in the
clone() creates a deep copy on the members of the object
public void init(Map<String, String> options)
throws MissingConfigurationOptionException {
logger.info(init);
}
public void init(Map<String, String> options)
throws MissingConfigurationOptionException {
logger.info(init);
}
@Override
public WorklightAuthenticator clone() throws CloneNotSupportedException {
MyCustomAuthenticator otherAuthenticator =
(MyCustomAuthenticator ) super.clone();
otherAuthenticator.authenticationData =
new HashMap<String, Object>(authenticationData);
return otherAuthenticator;
}
@Override
public WorklightAuthenticator clone() throws CloneNotSupportedException {
MyCustomAuthenticator otherAuthenticator =
(MyCustomAuthenticator ) super.clone();
otherAuthenticator.authenticationData =
new HashMap<String, Object>(authenticationData);
return otherAuthenticator;
}
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 12-53. Creating a custom Java Authenticator: overview WU5061.0
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.
Creating a custom Java Authenticator: overview
Here is the
code that is
discussed
over the
following
slides
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 12-54. Custom Java Authenticator: processRequest WU5061.0
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.
Custom Java Authenticator: processRequest
Invoked for each unauthenticated request. Used to collect credentials
This function receives request, response and
isProtectedResource arguments.
It may retrieve data from a request and write data to a response
It must return a specific AuthenticationResult status
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 12-55. processRequest: verify URL and credentials WU5061.0
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.
processRequest: verify URL and credentials
The application sends an authentication request to a specific URL. This
contains my_custom_auth_request_url, which the Authenticator
uses to make sure that this is an authentication request.
The Authenticator retrieves username and password credentials which
are passed as request parameters
if (request.getRequestURI().contains(
"my_custom_auth_request_url")) {
String username = request.getParameter("username");
String password = request.getParameter("password");
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 12-56. processRequest: authenticationData object WU5061.0
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.

if (null!=username && null!=password && username.length()>0
&& password.length() > 0) {
authenticationData = new HashMap<String, Object>();
authenticationData.put ("username", username);
authenticationData.put ("password", password);
return AuthenticationResult.createFrom(
AuthenticationStatus.SUCCESS);
processRequest: authenticationData object
The authenticator checks credentials for basic validity, creates an
authenticationData object and returns SUCCESS
Instructor Guide
V8.1
Uempty
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.
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 12-57. processRequest: problem response WU5061.0
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.
} 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);
}
processRequest: problem response
If there was a problem with the credentials, errorMessage is added to
the response and CLIENT_INTERACTION_REQUIRED is returned
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 12-58. processRequest: authentication not needed WU5061.0
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.
if (!isAccessToProtectedResource)
return AuthenticationResult.REQUEST_NOT_RECOGNIZED;
processRequest: authentication not needed
The isAccessToProtectedResource argument specifies whether
an access attempt was made to a protected resource
If not, the method returns REQUEST_NOT_RECOGNIZED
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 12-59. processRequest: credentials required WU5061.0
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.
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;
}
processRequest: credentials required
If the request is made to a protected resource but it does not contain authentication
data, the authenticator adds an authRequired:true property to the
response
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 12-60. The login module API WU5061.0
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.
The login module API
void init(Map<String, String> options)
boolean login(Map<String, Object> authenticationData)
UserIdentity createIdentity(String loginModule)
void logout()
void abort()
WorklightLoginModule clone()
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 12-61. Creating a custom Java login module WU5061.0
Notes:
In previous versions of Worklight the interface implemented by the login module was
WorklightLoginModule.
Creating a custom Java login module
Create a new class called MyCustomLoginModule in the server\java
folder
Make sure it implements WorklightAuthLoginModule interface
Add two private class members USERNAME and PASSWORD
They hold user credentials
public class MyCustomLoginModule implements WorklightAuthLoginModule {
private String USERNAME;
private String PASSWORD;
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 12-62. Login module: init and clone methods WU5061.0
Notes:
Login module: init and clone methods
The init(..) method is invoked when the Login Module instance is
created. It receives the options map specified in a login module
definition in authenticationConfig.xml
The clone() method of the Login Module creates a deep copy of the
objects members
public void init(Map<String, String> options) throws
MissingConfigurationOptionException {
//initialize the login module
}
public CustomLoginModule clone() throws CloneNotSupportedException {
return (CustomLoginModule) super.clone();
}
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 12-63. Login module: login method WU5061.0
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.
Login module: login method
The login() method is invoked when the Authenticator has returned
SUCCESS status
the login() method gets an authenticationData object from
Authenticator
public boolean login (Map<String, Object> authenticationData)
{
logger.info ("MyCustomLoginModule :: login");
USERNAME = (String) authenticationData.get ("username");
PASSWORD = (String) authenticationData.get ("password");
if (USERNAME.equals("wluser") && PASSWORD.equals("12345"))
return true;
else
throw new RuntimeException ("Invalid credentials"));
}
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 12-64. Login module: createIdentity method WU5061.0
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!
public UserIdentity createIdentity(String loginModule) {
logger.info ("MyCustomLoginModule :: createIdentity");
HashMap<String, Object> customAttributes =
new HashMap<String, Object>();
customAttributes.put ("AuthenticationDate", new Date());
UserIdentity identity = new UserIdentity(loginModule,
USERNAME, null, null, customAttributes, PASSWORD);
return identity;
}
Login module: createIdentity method
Once the login() method returns true, the createIdentity() method
is invoked
It is used to create a UserIdentity object
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 12-65. Login module: logout and abort methods WU5061.0
Notes:
Login module: logout and abort methods
The logout() and abort() methods are used to clean up class members
once user logs out or aborts the authentication flow
public void logout()
{
USERNAME = null;
PASSWORD = null;
}
@Override
public void abort()
{
USERNAME = null;
PASSWORD = null;
}
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 12-66. Examining the Result WU5061.0
Notes:
Examining the Result
Upon application start, an authentication form is displayed as required
Enter wluser and 12345 as user credentials
If the specified credentials are correct, authentication is saved for the
users session and the application screen is displayed
Click GetLoginName and verify that the correct login name is displayed
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty 12.3.WebSphere LTPA-based authentication
Instructor Guide
Figure 12-67. WebSphere LTPA-based authentication WU5061.0
Notes:
WebSphere LTPA-
based authentication
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 12-68. WebSphere LTPA-based authentication introduction WU5061.0
Notes:
Both of these options are discussed in the following slides.
WebSphere LTPA-based authentication introduction
WebSphere Application Server uses a secure token in a Lightweight
Third Party Authentication cookie to authenticate
This mechanism is used to trust users across a secure WebSphere
Application server domain, thereby providing single sign-on across
various resources protected on these servers
When running IBM Worklight on the WebSphere Application server,
you can use the WebSphereFormBasedAuthenticator and the
WebSphereLoginModule to authenticate to the Worklight application
using an LTPA token
There is a default option for configuring this authentication and an
alternate option to accomplish support of WebSphere LTPA based
authentication for the Worklight applications
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 12-69. Understanding server-side authentication options WU5061.0
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.
Understanding server-side authentication options
The WebSphere LTPA-based authentication process:
Application tries to access a protected resource
Application tries to access a protected resource
granted. Application receives
the requested data
granted. Application receives
the requested data
Authentication process starts.
Application receives the
authentication required message
Authentication process starts.
Application receives the
authentication required message
Set LTPA
token as
HTTP
Cookie
Set LTPA
token as
HTTP
Cookie
YES
YES
NO
NO
Worklight
checks user authentication:
LTPA token?
Success?
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 12-70. Server-side authentication options: option 1 WU5061.0
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.
Server-side authentication options: option 1
Worklight security configuration handles user authentication at the
Worklight platform level
It uses the security configuration of the underlying application server
The Worklight project deployed as WAR file on the WebSphere
Application Server is not secured
The web.xml of this WAR file does not reference any security constraints
protecting the web resources
The authenticator and login module defined as part of this configuration
authenticate the user (based on the provided credential) using the
underlying WAS Security API
If the user provides username/password upon initial login, then this is
used to authenticate against the underlying registry of the WebSphere
Application Server configuration
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 12-71. Server-side authentication options: option 2 WU5061.0
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.
Server-side authentication options: option 2
The application server security configuration handles authentication
The Worklight project deployed as a WAR file on the Application Server is not
secured. The web.xml references all security constraints protecting the
resources
Web resources are secured in the Worklight project WAR file by
specifying the resource and the user role
The authenticator and loginmodule that are defined as part of this
configuration authenticate the user by using the underlying application
server security API
Authentication based on the provided credentials
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 12-72. Understanding server-side authentication options WU5061.0
Notes:
Understanding server-side authentication options
Worklight Server enforces the
authentication relying on application
server configuration
User
Registry
User
Registry
WebSphere
Application
Server
Authentication is enforced by
WebSphere Application server
User
Registry
User
Registry
WebSphere
Application
Server
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 12-73. Worklight invokes WAS security WU5061.0
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.
Worklight invokes WAS security
Application
Worklight
Server
getSecretData
Authentication required by Worklight server
Authentication successful, LTPA set
getSecretData (passing in LTPA)
Secret data returned to application
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 12-74. Authentication through WebSphere Application Server WU5061.0
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.
Authentication through WebSphere Application Server
getSecretData
Authentication successful, LTPA set
Application
getSecretData (passing in LTPA)
Secret data returned to application
WebSphere
Application
Server
Worklight
Server
Authentication required by app.server
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 12-75. Server-side authentication options: summary WU5061.0
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.
Server-side authentication options: summary
The default option and the alternate option both present benefits and has different usages:
Worklight invokes WAS Application server
Benefits
Uses traditional WAS authentication and trust
model without the impact of modifying the
Worklight project WAR. The container enforces
all security and can use existing investments in
securing the JEE container using third-party
SSO products. The layered authentication of
device, application, application instance and user
function as intended. Flexibility in configuring
Worklight runtime security settings without being
hindered by the underlying container security.
Uses traditional WAS
authentication and
trust model. Container
enforces all security
and can use existing
investments in
securing the JEE
container using third-
party SSO products
Usage
Suitable for scenarios where the devices or the
applications on the device cannot be trusted.
The multi-step authenticity checking built into the
IBM Worklight platform ensure denial of service
to jail-broken devices, rogue applications and
unauthorized users.
Suitable for scenarios
where the devices can
be trusted and rogue
access is restricted.
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Notes:

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. Authentication settings are configured in which file?
A. authenticationConfig.xml
B. sas.client.props
C. application-descriptor.xml
D. plugin-cfg.xml
3. True or False:
Any login module can be used in the adapter-based authentication as an
additional authentication layer
Instructor Guide
V8.1
Uempty
Instructor notes:
Instructor Guide
Notes:
Unit summary
Worklight
Instructor Guide
V8.1
Uempty
Instructor notes:
the learning points
Instructor Guide
Notes:
Copyright IBM Corporation 2013 Copyright IBM Corporation 2013 Copyright IBM Corporation 2012
Checkpoint answers
1. D. The login module
2. A. authenticationConfig.xml
3. True
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
Copyright IBM Corp. 2013 Unit 13. Push notification 13-1
V8.1
Uempty
Unit 13. Push notification
Estimated time
01:00
This unit shows how to use the push notification mechanism to send
notifications to a mobile device.
Describe push notification architecture and API
Create an application that uses push notifications
Checkpoint
Exercise
References
Instructor Guide
Notes:
Unit objectives
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 13-2. What are push notifications? WU5061.0
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.
What are push notifications?
Push notification is the ability of a mobile
device to receive messages that are
pushed from a server
Notifications are received regardless of
whether the application is currently running
Notification can take several forms:
Alert: a pop-up text message
Badge: a small badge mark appearing next
to the application icon
Banner or Toast: a disappearing pop-up
text message at the top of the device display
Sound alert
Instructor Guide
V8.1
Uempty
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.
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 13-3. Device support WU5061.0
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.
Device support
Worklight supports push notifications for mobile platforms:
Android 2.2 or later
iOS
Windows Phone 8
Android devices must be logged into a Google account
For information about push notifications for BlackBerry, contact IBM
Worklight customer support
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 13-4. Notification architecture terminology WU5061.0
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.
Notification architecture terminology
Event source
A push notification channel to which mobile applications can register. An event source is defined
within a Worklight adapter.
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.
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 13-5. Notification architecture: subscription (1 of 3) WU5061.0
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.
Notification architecture: subscription (1 of 3)
In order to start receiving push notifications, an application must first
subscribe to a push notification event source
An event source is declared in the Worklight adapter that is used by
the application for push notification services
The user must approve the push notification subscription
When the user approves, the device registers with an Apple, Google, or
Microsoft push server to obtain a token, which is used to identify the
device
For example, Allow notifications for application X on device Y - sends a
subscription request to the Worklight Server
Performed automatically by the Worklight framework
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
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.
When the subscribe API is called, a
device registers with a push services
mediator and obtains a device token (done
automatically by Worklight)
Push services
mediators
Worklight
adapter
event source
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
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.
When the token is obtained, the
application subscribes to an event source
Both actions are done automatically using
a single API call as described later
Push services
mediators
Worklight
adapter
event source
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 13-8. Sending notifications: overview (1 of 2) WU5061.0
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.
Sending notifications: overview (1 of 2)
Worklight provides a unified push notifications API
Adapter API allows:
Managing subscriptions
Pushing and polling notifications from backend
Sending push notifications to devices
Application API allows:
Subscribing to and unsubscribing from push notifications event sources
Handling arriving notifications
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 13-9. Sending notifications: overview ( of 2) WU5061.0
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..
Sending notifications: overview ( of 2)
In order to send a notification, it must first be retrieved from the back
end
An event source can either poll notifications from the back end or wait
for the back end to explicitly push a new notification
When a notification is retrieved by the adapter, it is processed and sent
via the corresponding push services mediator (Apple or Google)
Additional custom logic can be added in the adapter to pre-process
notifications
The push services mediator receives the notification and sends it to a
device
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 13-10. Sending notifications (1 of 4) WU5061.0
Notes:
In step Notifications are retrieved by the Worklight adapters event source by either poll or
push from the back end Enterprise Data source.
Back end
Sending notifications (1 of 4)
1. Notifications are retrieved by the
Worklight adapter event source either by
poll or push from the back end
Push services
mediators
Worklight
adapter
event source
Enterprise
data source
1
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
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.
Back end
2. A Worklight adapter processes the
notification and sends it to a push
services mediator
Push services
mediators
Worklight
adapter
event source
Enterprise
data source
1
2
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
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.
Back end
3. The push service mediator sends a push
notification to the device
Push services
mediators
Worklight
adapter
event source
Enterprise
data source
1
2
3*
*User must subscribe to push notification with the push service
mediators before steps 3 and 4 can happen.
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
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.
Back end
4. The device processes the received
notification
Push services
mediators
Worklight
adapter
event source
Enterprise
data source
1
2
3
4*
*User must subscribe to push notification with the push service
mediators before steps 3 and 4 can happen.
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 13-14. Subscription management: user subscription WU5061.0
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.
Subscription management: user subscription
User subscription
An entity containing user ID, device ID and event source ID. It represents the intent of the user to
receive notification from a specific event source.
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
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 13-15. Subscription management: device subscription WU5061.0
Notes:
User subscription
Subscription management: device subscription
A device subscription belongs to a user subscription, and exists in the scope of a specific
user and event source. A user subscription can have several device subscriptions.
The device subscription is created when the application on a device calls the
WL.Client.Push.subscribe() function
The device subscription is deleted either by an application calling
WL.Client.Push.unsubscribe() or when the push mediator informs the Worklight server
that the device is permanently not accessible
Device
subscription
Device
subscription
Event source
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 13-16. Notification API: server side (1 of 10) WU5061.0
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.
Notification API: server side (1 of 10)
Start by creating an event source
Declare a notification event source in the adapter JavaScript code on a global level
name: a name that the Event Source is referenced by
onDeviceSubscribe: an adapter function that is invoked when user subscription request is
received
onDeviceUnsubscribe: an adapter function that is invoked when user unsubscribe request is
received
securityTest a security test from authenticationConfig.xml file used to protect the event source
Notifications are pushed
by the backend
Notifications are polled
from the backend
Instructor Guide
Instructor notes:
Details This is where you can point out that Google is making some changes in their
notification mediation which will be available in a more recent release of WL.
Instructor Guide
V8.1
Uempty
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
Start by creating an event source
Declare a notification event source in the adapter JavaScript code at a global level (outside any
JavaScript function)
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
Notifications are polled
Notifications are pushed
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
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.
Sending a notification
In this example, a
submitNotifications()
adapter function is invoked
by a back end service as an
external API to send
notifications
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
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.
Obtain notification data
The submitNotification()
function receives a userId
to send notification to, and
the notificationText.
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
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.
Retrieve the active user and use it to get user subscription data
A user subscription object contains
the information about all of the
users subscriptions. Each
user subscription can have several
device subscriptions.
The object structure is as follows:
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
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.
Retrieve the user subscription data
If the user has no subscriptions
for the specified event source,
a null object is returned.
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
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.
Retrieve the user subscription data
Separate subscription data
for each of the users devices
can be obtained by using the
getDeviceSubscriptions API.
The result is an array of objects
with the following structure:
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
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.
Send notification to the users devices
WL.Server.createDefaultNotification
API creates and returns a default
notification JSON block for the supplied
values.
Text to be pushed to the device
Badge number
Payload
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Notes:
WL.Server.notifyAllDevices
API sends notification to all
the devices that are
subscribed to the user.
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
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
Several APIs exist for notification sending:
WL.Server.notifyAllDevices(userSubscription, options): used to send
notification to all a users devices (see previous slide).
WL.Server.notifyDevice(userSubscription, device, options): used to send
notification to a specific device belonging to a specific userSubscription.
WL.Server.notifyDeviceSubscription(deviceSubscription, options): used to
send the notification to a specific device.
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 13-26. Notification API: client side (1 of 4) WU5061.0
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.
Notification API: client side (1 of 4)
Event Source registration
First, register an event source within the application
Worklight provides the customizable onReadyToSubscribe function to register an event source
Always set up your onReadyToSubscribe function on a global JavaScript level
onReadyToSubscribe is invoked when the authentication finishes
API is WL.Client.Push.registerEventSourceCallback(alias, adapterName,
eventSourceName, callbackFunction)
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
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.
Event Source subscribing and unsubscribing
A user must be authenticated in order to subscribe
Use the following API to subscribe to the event source
WL.Client.Push.subscribe() receives the following parameters:
An alias declared in WL.Client.Push.registerEventSourceCallback
(Optional) onSuccess callback
(Optional) onFailure callback
Callbacks receive a response object if one is required
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
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
Event Source subscribing and unsubscribing
Use the following API to unsubscribe from the event source
WL.Client.Push.unsubscribe() receives the following parameters:
An alias declared in WL.Client.Push.registerEventSourceCallback
Optional onSuccess callback
Optional onFailure callback
Callbacks receive a response object if one is required
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
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.
Additional client side APIs:
WL.Client.Push.isPushSupported() returns true if push notifications are
supported by the platform, and false otherwise
WL.Client.Push.isSubscribed(alias) returns whether the currently logged-in
user is subscribed to a specified event source alias
When push notification is received by a device, the callback function
defined in WL.Client.Push.registerEventSourceCallback is invoked.
It receives the following arguments:
If the application was in background mode (or inactive) when the push
notification arrived, this callback is invoked upon the applications
return to foreground.
Instructor Guide
WL.Client.Push.registerEventSourceCallback registers a callback method whenever a
notification arrives from the specified event source. If the notification arrives while the
application is not running, the mobile OS will start the application at the specified callback.
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 13-30. Setup: Android WU5061.0
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.
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
Android OS 2.2.x/2.3.x devices must be synchronized with a Gmail
account.
Android OS 4.x does not impose Gmail account synchronization.
The following servers must be accessible from the Worklight Server:
https://www.google.com
https://android.apis.google.com
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 13-31. Setup: iOS WU5061.0
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
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 apnscertificate-
sandbox.p12 and place it in the application root folder.
When you move to production, rename your certificate file to apnscertificate-
production.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
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 13-32. Setup: Windows Phone 8 WU5061.0
Notes:
Setup: Windows Phone 8
To send push notifications to Windows Phone 8 devices, you must use
the Microsoft Push Notifications Service (MPNS).
Non-authenticated push notification does not require any setup from
the developer.
Authenticated push notification requires a Windows Phone Dev Center
account.
To use authenticated push, you must use a certificate that is issued by
a Microsoft-trusted root certificate authority.
For production, consider using authenticated push notification to
ensure that your information is not comprised.
Consider using non-authenticated push only for development-time.
No specific ports needs to be open in your server configuration MPNS
uses regular http or https requests.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 13-33. Edit application-descriptor.xml (1 of 2) WU5061.0
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.
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 13-34. Edit application-descriptor.xml (2 of 2) WU5061.0
Notes:
Edit application-descriptor.xml (2 of 2)
Windows Phone 8:
To set up non-authenticated push:
To set up 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.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 13-35. PushBackendEmulator WU5061.0
Notes:
PushBackendEmulator
The sample for this training module comes with a backend emulator
that you can use to simulate push notification submissions by a back-
end 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
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Notes:
Unit summary
Instructor Guide
V8.1
Uempty
Instructor notes:
the learning points
Instructor Guide
Notes:

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
Instructor Guide
V8.1
Uempty
Instructor notes:
Instructor Guide
Notes:
Checkpoint answers
1. D. All of above
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 13-39. Checkpoint (objective only) WU5061.0
Notes:

Checkpoint (objective only)
1. (True/False) Push notifications are received only if the application is
currently running.
2. (True/False) For push notifications to work, Android devices must be
logged into a Google account.
3. To start receiving push notifications, what must an application first
do?
A. Start up.
B. Subscribe to a push notification event source.
C. Log in to Gmail.
D. Obtain an authentication ID.
Instructor Guide
V8.1
Uempty
Instructor notes:
Instructor Guide
Notes:
Checkpoint answers
1. False
2. True
3. B. Subscribe to a push notification event source
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Notes:
Exercise 8
Exploring the push notification
API
Instructor Guide
V8.1
Uempty
Instructor notes:
Instructor Guide
Notes:
Exercise objectives
Use the Push Notification API to:
Test if a device supports push notification
Test if the currently logged-in user is subscribed to a specified event
source alias
Subscribe a user to an event source
Un-subscribe a user from an event source
Send a notification to a device
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Instructor Guide
Copyright IBM Corp. 2013 Unit 14. Device analytics reporting 14-1
V8.1
Uempty
Unit 14. Device analytics reporting
Estimated time
00:30
This unit shows you how to set-up, produce, and view reports that
reflect the device activity in your environment.
Set up the Worklight Server and Eclipse environment to enable
reporting
Produce and view device analytics reports
Checkpoint
References
Instructor Guide
Notes:
Unit objectives
reporting
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Notes:
Topics
Device Analytics introduction
Setup before viewing reports
Configuring BIRT
Viewing Reports
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 14-3. Device analytics introduction WU5061.0
Notes:
8.0
Device analytics
introduction
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 14-4. Introducing reports and analytics WU5061.0
Notes:
BIRT: Business Intelligence Reporting Tool
You can find sample reports at
https://www.ibm.com/developerworks/mobile/worklight/getting-started/
Introducing reports and analytics
IBM Worklight provides analytics capabilities
to help understand device usage across the
Worklight servers
Basic set of reports viewable by using
the BIRT Eclipse plug-ins
BIRT: Business Intelligence
Reporting Tool
Flexible architecture to support access
to the data for consumption from other
reporting tools
Worklight
server
Raw
data
Aggregated
data
BIRT
reports
Other
reporting
tools
Worklight
DB
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 14-5. Enabling raw data reports WU5061.0
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.
Enabling raw data reports
Create a separate database for reports as the raw data table is rapidly
populated
Edit worklight.properties file
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 14-6. Device analytics: raw data WU5061.0
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.
Device analytics: raw data
IBM Worklight emits raw data that enables an OLAP system to extract
the required information and present it through corporate reporting
mechanisms
With the Raw Data reports feature collections of analytics information
can be created about your applications and adapters usage
For example: activity type, device info, app version
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 14-7. APP_ACTIVITY_REPORT table WU5061.0
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.
APP_ACTIVITY_REPORT table
The raw reports table includes the following information:
Column Description
ACTIVITY Activity type. See next slide
ACTIVITY_TIMESTAMP Time of entry (UTC)
ENVIRONMENT Application environment (iPhone, android,)
ADAPTER The Worklight adapter name
PROC The procedure name in the adapter
IP_ADDRESS IP address of the client
DEVICE_MODEL Manufacturer model (for example, iPhone 6)
GADGET_NAME Application name
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 14-8. APP_ACTIVITY_REPORT ACTIVITY column WU5061.0
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.
APP_ACTIVITY_REPORT ACTIVITY column
Activity Description
Init Application initialization
Login Successful authentication using the application
Query Procedure call to an adapter
Logout User logout
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 14-9. Device usage reports WU5061.0
Notes:
The fact_activities table contains a total activity count (number of logged actions) per
application, application version, device, and environment.
Device usage reports
Device Usage reports are default
aggregations that are based on the Raw
Data and are provided for the benefit of
organizations that do not have OLAP
systems or choose not to integrate IBM
Worklight with an OLAP system
The Worklight server runs an analytics
data processor task with a default
24-hour interval
This allows simple and fast access to the
reports data
This task retrieves the raw entries for
the specified time interval from
app_activity_report table, processes
them, and fills the fact_activities table
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 14-10. activities_cube table WU5061.0
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.
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 14-11. Notification_report table WU5061.0
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.
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 14-12. proc_report table WU5061.0
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.
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
In addition, notification_report table data is also processed, filling the
notification_activities table with consolidated data. This is done
similar to filling fact_activities table. Every time notification_report table
data is processed an entry is added to notification_proc_report table,
similar to proc_report
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 14-13. Summary: relationship of the tables WU5061.0
Notes:
The 24-hour interval is a default. The next page shows how to modify this.
Summary: relationship of the tables
APP_ACTIVITY_REPORT
APP_ACTIVITY_REPORT
24-hour interval
FACT_ACTIVITY
FACT_ACTIVITY
ACTIVITIES_CUBE
ACTIVITIES_CUBE
PROC_REPORT
PROC_REPORT
NOTIFICATION_REPORT
NOTIFICATION_REPORT
NOTIFICATION_ACTIVITIES
NOTIFICATION_ACTIVITIES
NOTIFICATION_PROC_REPORT
NOTIFICATION_PROC_REPORT
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 14-14. Processing interval WU5061.0
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.
Processing interval
Processing this quantity of information can be intensive
The default interval is 1 day
You may not require one report every day
It may be that once a week is sufficient
It may be that a report is needed every hour
The processing interval can be modified by changing the value of the
factProcessingInterval property in worklight.properties
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 14-15. BIRT reports WU5061.0
Notes:
8.0
BIRT reports
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 14-16. BIRT reports WU5061.0
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).
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
The IBM Worklight installation contains a number predefined BIRT
Reports
Configurable XML files designed to retrieve and present data from
Worklight reports database tables
These files have the extension .rptdesign
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 14-17. Installing BIRT WU5061.0
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
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
If you already have Worklight Studio or Eclipse version 4.2 or later
installed, you can install the BIRT plug-in as follows:
Click Help > Install New Software > Juno -
http://download.eclipse.org/releases/juno
Expand Business Intelligence, Reporting, and Charting in the list.
Select BIRT Framework from the list
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 14-18. Exploring BIRT in Eclipse WU5061.0
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.
Exploring BIRT in Eclipse
The BirtSample database is added to Eclipse
Open the Database Development perspective
You can examine the table contents in the SQL Results view
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 14-19. Viewing reports WU5061.0
Notes:
8.0
Viewing reports
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 14-20. Report types: environment access WU5061.0
Notes:
Report types: environment access
Environments accessing the application version in the last 30 days
environment_usage.rptdesign
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 14-21. Report types : daily visits WU5061.0
Notes:
Report types : daily visits
Daily visits seen for a specific application version in the last 30 days
daily_visits.rptdesign
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 14-22. Report types : unique devices WU5061.0
Notes:
Report types : unique devices
Unique devices seen in the last 90 days by the platform
LICENSE_total_device_count.rptdesign
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Notes:

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
Instructor Guide
V8.1
Uempty
Instructor notes:
Instructor Guide
Notes:
Unit summary
reporting
Instructor Guide
V8.1
Uempty
Instructor notes:
the learning points
Instructor Guide
Notes:
Checkpoint answers
1. What is BIRT?
Business Intelligence Reporting Tool
2. What kind of information are reports based on?
Raw data
3. One of the types of information that the app_activity_reports
table provides is ACTIVITY_TIMESTAMP. Name another.
ENVIRONMENT, ADAPTER, PROC, IP_ADDRESS, DEVICE_MODEL,
ACTIVITY
4. Name one of the report types discussed in the module
Environments accessing the application version in the last 30 days
Daily visits seen for a specific application version in the last 30 days
Unique devices seen in the last 90 days by the platform
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
Copyright IBM Corp. 2013 Unit 15. Direct update 15-1
V8.1
Uempty
Unit 15. Direct update
Estimated time
01:00
This unit shows you how to use the application management features
of IBM Worklight.
Define what direct update is
Use the Direct Update feature to automatically update deployed
applications with new versions
Checkpoint
References
Instructor Guide
Notes:
Unit objectives
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 15-2. What is direct update? WU5061.0
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.
What is direct update?
With Direct Update, hybrid iOS and Android apps can automatically be
updated with new versions of their web resources, without the active
involvement of the user
Hybrid applications are written in HTML and can access native device
features
The web resources of an application can be downloaded to the users
device, like mobile web apps
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Purpose
Details
Instructor Guide
Figure 15-3. The advantages of direct update WU5061.0
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!
The advantages of direct update
Organizations can ensure that users always use the latest version of an
application web resources
This provides better control of application versions
Users are notified of pending updates, or access to obsolete versions is blocked
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Purpose
Details
Instructor Guide
Figure 15-4. The restrictions of direct update WU5061.0
Notes:
Android does not have the restrictions shown in the second bullet. Direct updates for iOS
have some restrictions due to Apple policy.
The restrictions of direct update
Direct update of application web resources
Support for iOS and Android only
Update is only for the web resources of the application
Native resources require uploading a new version to the application stores
iOS-specific restrictions:
B2C: Per company's terms of service
Usually at least bug fixes are allowed
B2E: Through the enterprise developer program
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Purpose
Details
Instructor Guide
Figure 15-5. Version detection WU5061.0
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.
Version detection
Detection upon startup and when an application is brought into the
foreground
Dialog for easy user selection
Application download progress bar
The web part of the application is automatically reloaded after update
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Purpose
Details
Instructor Guide
Figure 15-6. Direct update: distribution WU5061.0
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.
Direct update: distribution
Native resources are
deployed to the Application Store
Web resources are deployed to both the
Application Store and the server
The server has resources for V1.0 and V1.1
After loading, the device asks for updates
Worklight Server
Maintain recent web
resources for native
applications V1.0 and V1.1
Application Stores
Worklight Studio
Develop
Native applications
Web resources
Web
code
native
shell
V1.0
Web
code
native
shell
V1.1
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 15-7. Disabling old app versions WU5061.0
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.
Disabling old app versions
Use the Worklight Console to disable obsolete versions
Notify users about the state of the application
You can indicate that a version is soon going to be disabled
active, notifying
You can disable a version
Provide information that is sent to the device
Indicate where the new version can be obtained
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Purpose
Details
Instructor Guide
Notes:

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?
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Notes:
Unit summary
Instructor Guide
V8.1
Uempty
Instructor notes:
the learning points
Instructor Guide
Notes:

Checkpoint answers
1. Where are native resources deployed?
Application store
2. Where are web resources deployed?
Application store and Worklight server
3. On the Worklight console, versions can be marked as active,
disabled, or?
Active, notifying
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Instructor Guide
Copyright IBM Corp. 2013 Unit 16. Migrating an application from development to production 16-1
V8.1
Uempty
Unit 16. Migrating an application from
development to production
Estimated time
01:00
This unit shows you how to use the application migration features of
IBM Worklight.
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
Checkpoint
References
Instructor Guide
Notes:
Unit objectives
Install IBM Worklight Server in a WebSphere Application Server and
DB2 environment.
Migrate applications from a development to a production environment
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 16.1.Overview of application management
Instructor Guide
Figure 16-2. Overview of application management WU5061.0
Notes:
Overview of application
management
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
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.
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
Each environment (production, pre-production, QA, Development) has
its own unique settings
Locations of backend services, public URL, database connectivity parameters,
logging, and so forth
These settings and components eventually need to be transferred to
the remote server
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 16-4. Steps in the process of remote deployment WU5061.0
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.
Steps in the process of remote deployment
Prepare the application for deployment
Adjust application properties in application-descriptor.xml
Adjust server and database properties in worklight.properties
Build the application
Rename the generated .war file
Deploy the application
Deploy the .war file to the remote server
Deploy applications and adapters using the Worklight Console
The next slides look in detail at this process
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 16-5. Architecture of deployment (1 of 6) WU5061.0
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.
Architecture of deployment (1 of 6)
A Java web application server is required to run Worklight
WebSphere, Tomcat or Liberty
Copy the supplied worklight-jee-library.jar file to the lib folder of the
application server
Application server
project-name.war
Worklight applications and adapters
worklight-jee-library.jar
Database
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Transition statement Transition statement
Instructor Guide
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.
Application server
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
Database
project-name.war
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
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.
Application server
Database connection properties are defined in the
worklight.properties file
You can use either application server level JNDI or Worklight server level JDBC
connections.
Database
project-name.war
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
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.
Application server
9
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
Database
project-name.war
project-name.war
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
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.
Application server
project-name.war
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
Database
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
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.
Application server
project-name.war
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
Database
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 16.2.Worklight Apache Ant utility
Instructor Guide
Figure 16-11. Worklight Apache Ant utility WU5061.0
Notes:
Worklight Apache Ant
utility
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 16-12. Worklight Apache Ant utility WU5061.0
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
Worklight Apache Ant utility
Apache Ant is a project developed and maintained by the Apache
Software Foundation
It provides command line tools that can be used for tasks such as
building applications and copying files
Worklight provides an Apache Ant utility
It can be used to automate build and deploy processes of Worklight artifacts
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 16-13. Apache Ant basics WU5061.0
Notes:
Install Apache Ant and make sure that its binaries are in the path variable of your operating
system
Apache Ant basics
Apache Ant is run by invoking the following syntax from a command
line
ant buildfile build-script-name.xml
build-script-name.xml has the following structure template
<project base=. default=target-name>
<target name=target-name>
<echo message=messageText/>
<taskdef>...</taskdef>
</target>
</project
<target> is a set of tasks which are performed one by one
<echo> can be used to output messages for debugging or for
information on the task
<taskdef> is discussed on the next slide
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 16-14. Adding a reference to Worklight Ant jar file WU5061.0
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.
Adding a reference to Worklight Ant jar file
A <taskdef> adds a task or a data type definition
A Task is any class that extends org.apache.tools.ant.Task
Two attributes are required:
the name that identifies this data type uniquely
The name of the class that implements this type
Including its package name
<taskdef resource=com/worklight/ant/defaults.properties>
<classpath>
<pathelement location=
C:\IBM\Worklight\WorklightServer\worklight-ant.jar/>
</classpath>
</taskdef>
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 16-15. Ant task: application builder WU5061.0
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.
Ant task: application builder
To build an application add <app-builder> with the following syntax:
<app-builder
applicationFolder = "C:\TestProject\TestApp"
environments = "common"
nativeProjectPrefix = "com.mycompany.TestApp"
outputFolder = "C:\TestProject\bin"
/>
applicationFolder: the root folder of the application
environments: comma separated list of environments to build
Optional parameter; omitting it means build all environments found
in application-descriptor.xml
nativeProjectPrefix: mandatory parameter when building iOS
applications
outputFolder the folder for the generated .wlapp files
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 16-16. Ant task: application deployer WU5061.0
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.
Ant task: application deployer
To deploy an application add <app-deployer> with the following
syntax:
<app-deployer
worklightServerHost = http://localhost:8080/"
deployable=C:\TestProject\bin\TestApp-common.wlapp"
/>
worklightServerHost: full URL of your Worklight server.
Deploy fails if the Worklight console is protected by a password
deployable: the .wlapp file to deploy
To deploy several .wlapp files add <app-deployer> entries
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 16.3.IBM Worklight Server installation and configuration
overview
Instructor Guide
Figure 16-17. IBM Worklight Server installation and configuration overview WU5061.0
Notes:
IBM Worklight Server
installation and
configuration overview
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 16-18. Worklight Server overview WU5061.0
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.
Worklight Server overview
IBM Worklight Server provides the runtime and administrative services
required by a Worklight mobile application to support:
Push notification
Security
Back-end integration
Version management
Worklight Server is packaged as a Java EE web application (WAR file) that
is deployed to an application server.
WAR file is application-specific:
It contains properties, libraries, security settings and other server-side resources that
are specific to a mobile application.
Each mobile application created using IBM Worklight Studio connects at runtime to its
own customized instance of Worklight server.
WAR file is environment-specific:
A different Worklight server WAR file is typically required for each higher-level
deployment environment (for example, QA and production) to specify environment-
specific properties such as the public access URL and the database user ID and
password.
WAR file contains an instance of the Worklight Console.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 16-19. Worklight Server runtime architecture WU5061.0
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.
Worklight Server runtime architecture
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 16-20. IBM Worklight Server installation: Prerequisites WU5061.0
Notes:
For a detailed list of system requirements for Worklight Server v6, visit:
http://www-01.ibm.com/support/docview.wss?uid=swg27024838
IBM Worklight Server installation: Prerequisites
Worklight Server v6 can be installed on the following application
servers:
Apache Tomcat 7.0
WebSphere Application Server version 7.0, 8.0, 8.5 and 8.5.5
WebSphere Application Server Network Deployment version 7.0, 8.0, 8.5 and
8.5.5
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
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 16-21. Configuring Worklight Server resources in WebSphere Application Server WU5061.0
Notes:
Configuring Worklight Server resources in WebSphere
Application Server
Define the database resources and configure the runtime components
used by Worklight Server using the WebSphere Integrated Solutions
Console. This includes:
Creating a data source for the Worklight core database and for the reports
database
Defining worklight-jee-library.jar as a shared library
Installing the Worklight sample customization WAR file to use for testing the
installation
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 16.4.Application migration: Overview
Instructor Guide
Figure 16-22. Application migration: Overview WU5061.0
Notes:
Application migration:
Overview
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 16-23. Application migration overview WU5061.0
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.
Application migration overview
The Worklight project contains various components such as
applications, adapters, configuration files, custom Java code and
libraries.
In the early development stages, all of these components are deployed
to a local server which resides on the developers computer.
Deploying those components to a local development server is automated by
Worklight studio.
Each environment (production, pre-production, QA, Dev) has its own
unique Worklight-specific settings, for example: locations of back-end
services, public URLs, database connectivity parameters, and logging
settings
Eventually a need to transfer these settings and components to the
remote server arises.
Instructor Guide
V8.1
Uempty
The next slides describe how to prepare and package an application in order to deploy it to
a remote server.
Instructor Guide
Instructor notes:
Purpose Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 16-24. Application migration process WU5061.0
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.
Application migration process
The process consists of two main steps:
Prepare the application for deployment:
Adjust application properties in application-descriptor.xml
Adjust server and database properties in worklight.properties
Build the application
Deploy the application:
Deploy the .war file to the remote server.
Deploy the applications .wlapp and .adapter files using the Worklight
Console
25
Instructor Guide
Once the project-specific Worklight sever is installed and configured, the System
Administrator deploys the projects applications and adapters using the Worklight
Console.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 16.5.Application migration: Preparing your application
Instructor Guide
Figure 16-25. Application migration: Preparing your application WU5061.0
Notes:
Preparing your
application
Instructor Guide
V8.1
Uempty
Instructor notes:
Details Lets first take a look at what needs to prepared from the applications
perspective.
Instructor Guide
Figure 16-26. Adjusting the worklight.properties file: Database settings WU5061.0
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.
Adjusting the worklight.properties file: Database settings
For a remote server, set
elements to describe the
connection to a database
the Worklight Server uses
Select the database type
used by the target
Worklight server,
for example, DB2, Oracle
or MySQL
Enter the JDBC connection
or data source information
Enter the database
user name and password
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 16-27. Adjusting the worklight.properties file: Server access settings WU5061.0
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.
Adjusting the worklight.properties file: Server access
settings
Adjust the properties describing the public Worklight Server access:
Protocol
Port
Context root
The project-specific Worklight server is available at
http://remoteServerURL:8181/MyContext/
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 16-28. Adjusting configuration files: Best practice WU5061.0
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.
Adjusting configuration files: Best practice
As a best practice, when adjusting properties in the configuration files:
Create a copy of the configuration file with different names for each environment.
When ready to build the application, copy the contents of the desired version to
the main configuration file.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 16-29. Building the project WU5061.0
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.
Building the project
When you have made all the required modifications to the configuration
of your Worklight project, build your application, adapter, or both.
This creates a projectName.war file in the \bin folder which
contains the console application used to deploy the projects
application and adapter files to the remote server.
This .war file also contains classes built from Java code in the server\java
folder.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 16.6.Application migration: Deploying your application
Instructor Guide
Figure 16-30. Application migration: Deploying your application WU5061.0
Notes:
Deploying your
application
Instructor Guide
V8.1
Uempty
Instructor notes:
Details Once the applications deployment artifacts have been generated, you can
deploy them to the remote runtime server, such as WebSphere Application Server.
Instructor Guide
Figure 16-31. Deploying the applications Worklight server WAR file WU5061.0
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.
Deploying the applications Worklight server WAR file
Deploy the generated .war file to the remote server.
For WebSphere Application Server, use the WebSphere Integrated Solutions
Console.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Notes:

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
3. Which project configuration file contains the Worklight server root
URL definition?
Instructor Guide
V8.1
Uempty
Instructor notes:
Instructor Guide
Notes:
Unit summary
Install IBM Worklight Server in a WebSphere Application Server and
DB2 environment.
Migrate applications from a development to a production environment
Instructor Guide
V8.1
Uempty
Instructor notes:
the learning points
Instructor Guide
Notes:
Checkpoint answers
1. True or false:
Each Worklight application has its own Worklight server WAR file.
True
2. Which of the following types of files can be deployed using the
Worklight console?
a) .adapter files
b) .war files
c) .wlapp files
d) .jar files
a) and c)
3. Which project configuration file contains the Worklight server root
URL definition?
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
Copyright IBM Corp. 2013 Unit 17. Shell development 17-1
V8.1
Uempty
Unit 17. Shell development
Estimated time
01:00
In this unit, you learn how to use the Shell component feature of IBM
Worklight to improve the development process and facilitate sharing
application components during development.
Develop a Shell component
Checkpoint
References
Instructor Guide
Notes:
Unit objectives
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Notes:
Topics
shell component concepts
Creating and using a shell component
Android shell development
iOS shell development
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 17.1.shell component concepts
Instructor Guide
Figure 17-3. shell component concepts WU5061.0
Notes:
8.0
shell component concepts
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
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.
5
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
Instructor Guide
V8.1
Uempty
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.
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 17-5. Architecture of a shell-based application (1 of 2) WU5061.0
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.
6
Architecture of a shell-based application (1 of 2)
A shell component is a building
block that is used to create inner
applications
Used by inner applications as a code
base wrapper
Usually consists of native classes and
shell-specific web resources that are
used in inner applications
Implemented by shell developers and
sent to inner application developers to
use
6
Customizable native
shell code
Mobile browser
Customizable
web shell code
inner
application
Web code
Device APIs
Instructor Guide
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.
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 17-6. Architecture of a shell-based application (2 of 2) WU5061.0
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.
7
Architecture of a shell-based application (2 of 2)
inner application: web
resources (HTML, JavaScript,
CSS) that run inside the shell
component
Test application: shell
component is not executable by
itself. Once it is created, an inner
application is automatically added
to the project by Worklight Studio.
This application is used by the
shell developer to test shell
component functionality.
7
Customizable native
shell code
Mobile browser
Customizable
web shell code
inner
application
Web code
Device APIs
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 17-7. Creating a shell component WU5061.0
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.
8
Creating a shell component
Create a Worklight project of type shell Component
Create the shell component
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 17-8. shell component file structure (1 of 2) WU5061.0
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.
9
shell component file structure (1 of 2)
A shell component is a building
block that is used to create
inner applications
The MyshellTest application is
automatically created
This is a test application as
described in the Overview
section
You can use it to test and debug
the shell component
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 17-9. shell component file structure (2 of 2) WU5061.0
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.
10
shell component file structure (2 of 2)
The common folder of the
shell component includes the
following subfolders:
css, images, js: contain web
resources that are added
automatically to inner applications
in build time
fragments: contains HTML
fragments that are added to various
parts of the inner application main
HTML file in predefined locations
preview: can be used to implement
native functionality stubs for
simulation in the Worklight Console
preview instead of receiving
exceptions
Instructor Guide
V8.1
Uempty
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 17-10. shell-descriptor.xml WU5061.0
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.
11
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
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty 17.2.Creating and using a shell component
Instructor Guide
Figure 17-11. Creating and using a shell component WU5061.0
Notes:
8.0
Creating and using a shell
component
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 17-12. Using the shell component in a test application (1 of 3) WU5061.0
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.
13
Using the shell component in a test application (1 of 3)
Using the Myshell example, create a myshell.js file under
Myshell\common\js folder
Add the following function to it:
Modify body-top.wlfragment and add the following:
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 17-13. Using the shell component in a test application (2 of 3) WU5061.0
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.
14
Using the shell component in a test application (2 of 3)
Modify MyshellTest.js in apps/MyshellTest/common/js
Invoke the function added in the shell component:
Build and deploy
MyshellTest
Once deployed, the it is
listed in the Console as a
regular hybrid application
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 17-14. Using the shell component in a test application(3 of 3) WU5061.0
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.
15
Using the shell component in a test application(3 of 3)
Preview of the test application
The browser includes web resources from both the shell component
and the inner application
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 17-15. Creating and using a shell bundle (1 of 3) WU5061.0
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.
16
Creating and using a shell bundle (1 of 3)
When a shell developer builds a shell component, a .wlshell file
is created under the project bin folder
This file is called a shell bundle
It can be sent to inner application developers to use.
shell developers are not required to explicitly create a shell bundle;
the test application references the shell component source code
directly as specified in the application-descriptor.xml
If a shell developer wants to send a shell component to an inner
application developer, a shell bundle must be created
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 17-16. Creating and using a shell bundle (2 of 3) WU5061.0
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
Creating and using a shell bundle (2 of 3)
To create a shell bundle, right-click a shell component folder and
select Run > Build shell Component
The .wlshell file is created under the project bin folder
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 17-17. Creating and using a shell Bundle (3 of 3) WU5061.0
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.
18
Creating and using a shell Bundle (3 of 3)
shell
Component
APK or IPA file
containing
resources from
both shell and
inner components
The inner application
developer must:
Copy the shell bundle file to a
Worklight project
Specify the location
If necessary, replace the existing
shell bundle file
Rebuild the application
shell Bundle
(.wlshell file)
inner
Application
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Instructor Guide
V8.1
Uempty 17.3.Android shell development
Instructor Guide
Figure 17-18. Android shell development WU5061.0
Notes:
8.0
Android shell development
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 17-19. Adding an Android environment to the shell component WU5061.0
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
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.
20
Adding an Android environment to the shell component
Start by adding an Android environment to the shell component
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 17-20. Android shell component file structure WU5061.0
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.
21
Android shell component file structure
The following folder
structure is created:
css, images, fragments
and js: contain resources
that override/extend
resources from the shell
components common
folder
native: contains an
application template to be
used when creating an
Android project from an
inner application
nativeEmptyApp:
contains an application
built from the shell
component and an empty
inner application
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 17-21. Adding an Android environment to shell component WU5061.0
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.
22
Adding an Android environment to shell component
The files that reside under the
native folder are templates used
to create the inner application
Android project
Some of the folder and file names
contain placeholder elements,
which are populated during build
For example:
${packageDirectory}
placeholder is populated with a
package name used in the
application
${appName} placeholder is
populated with the application name;
creates the main application activity
Files that end with .wluser are
user-editable templates, which can
be modified by a shell developer
Instructor Guide
V8.1
Uempty
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.
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 17-22. Adding custom Java code to shell component (1 of 5) WU5061.0
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.
23
Adding custom Java code to shell component (1 of 5)
Since the android\native
folder of a shell component is
not an Android project, Eclipse
does not provide advanced
features such as auto-complete
when working on it directly
Use an Android environment to
create, modify and debug Java
code
1. Add an Android environment to
the test application
2. Build and deploy the test
application
3. The generated Android project
is then added to Workspace
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
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().
24
Add the package com.mycustomcode to the generated Android project
Add MyCustomToaster.java class under this package
Add a static method
Open the main
application class
Invoke MyCustomToast.showToastAlert()
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
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.
25
Run the application to see the implemented functionality
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
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.
26
Copy the Java code from the Android project to the shell component
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
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.
27
The native folder of the test application is not rebuilt from the shell
component each time you build the Android application
This is done to prevent overwriting of the test application native code
with the one residing in the shell component on each build, thus
allowing the shell developer to debug code conveniently
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 17-27. Using the NativeEmptyApp Project WU5061.0
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.
28
Using the NativeEmptyApp Project
nativeEmptyApp is a native application project that uses the
shell component, but has an empty inner application. This project
can be built as an APK or IPA by a shell developer and sent to
inner application developers to use for debugging applications
Once nativeEmptyApp is installed on a device, the developer
can specify the URL of the Worklight Server from which to load
the inner application. This helps developers test their code without
needing native SDKs installed
or example, develop and test iPhone
applications without a Mac
To use nativeEmptyApp import its folder
as a Generic Project in Eclipse
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 17-28. Using the NativeEmptyApp Project WU5061.0
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.
29
Using the NativeEmptyApp Project
The native empty application is automatically recognized as an
Android project
When built and deployed to an Android device, the application allows
you to change the URL from which the inner application content is
loaded by clicking Menu and going to Settings
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty 17.4.iOS shell development
Instructor Guide
Figure 17-29. iOS shell development WU5061.0
Notes:
8.0
iOS shell development
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 17-30. Adding an iOS environment to shell component WU5061.0
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
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.
31
Adding an iOS environment to shell component
Start by adding a new iPhone or iPad environment to the shell
component
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
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.
32
The following folder structure is
created
css, images, fragments and js:
contain resources that override
or extend resources from the
shell component common folder
native: contains an application
template to be used when
creating an iOS project from an
inner application
nativeEmptyApp: contains
application built from shell
component and an empty inner
application
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
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.
33
The files under the native folder
are templates used to create the
inner application
Some of the names contain
placeholder elements, which are
populated during build:
${XcodeProjectName}.
Xcodeproj.wluser is populated
with a package name used in the
application
${XcodeProjectName}.
info.plist.wltemplate.
wluser is populated with the
application name; creates the main
application activity
Files that end with .wluser are
user-editable templates, which can
be modified by a shell developer
Instructor Guide
V8.1
Uempty
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 17-33. Adding Objective-C code to shell component (1 of 5) WU5061.0
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.
34
Adding Objective-C code to shell component (1 of 5)
The iphone\native folder of a
shell component is not an iOS
project, so features such as
auto-complete are not provided
when working on it directly
The solution is to add an iPhone
environment to the application
and use it to create, modify and
debug Objective-C code
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
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.
35
Open the generated iOS project in Xcode
Add a new Objective-C class called MyshellTest under Classes folder
Add a static method to this class
Invoke this method from viewDidLoad of the application ViewController
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
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.
36
Run your application to see the implemented functionality
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
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.
37
Copy the Objective-C code from the iPhone project to the shell
component
1
2
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Notes:
When you make changes to the shell component, you need to synchronize the code with
the generated Test Application iPhone project.
38
The native folder of the Test
application is not being rebuilt
from the shell component each
time you build the iOS
application
This is done in order not to
overwrite the Test applications
native code with the shell
component on each build
This allows the shell Developer to
debug code conveniently
To fully recreated the native
code from a shell component
erase it in the Test application
and perform a Build and
Deploy
Instructor Guide
Instructor notes:
Details
Instructor Guide
V8.1
Uempty
Figure 17-38. Using the nativeEmptyApp Project WU5061.0
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.
39
Using the nativeEmptyApp Project
nativeEmptyApp is a native
application project that uses the shell
component, but has an empty inner
application.
When nativeEmptyApp is installed on
the device, the inner application
developer can specify the URL of the
Worklight Server from which to load the
inner application.
To use nativeEmptyApp, open it as an
Xcode project
Instructor Guide
To use the NativeEmptyApp in development environment, developers can open it as an
Xcode project. To open it in Xcode, it follows the same process as a regular application
iphone environment. Right click the NativeEmptyApp and select Run As Xcode project.
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Notes:

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
2. Which of the following should not be a part of the shell component?
A. Authentication module
B. Native functionality JavaScript wrapper
C. Application UI components
D. Company logotype that should be shared between several applications
Instructor Guide
V8.1
Uempty
Instructor notes:
Instructor Guide
Notes:
Unit summary
Instructor Guide
V8.1
Uempty
Instructor notes:
the learning points
Instructor Guide
Notes:
Checkpoint answers
1. D. Sending the .wlshell shell bundle file to inner application
developers
2. C. Application UI components
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
Copyright IBM Corp. 2013 Unit 18. IBM Application Center 18-1
V8.1
Uempty
Unit 18. IBM Application Center
Estimated time
00:45
In this unit, you learn about the IBM Application Center, which is like a
private "app store" that you can use to manage and share mobile
applications within your organization.
Configure Application Center users
Use the Application Center to manage and share mobile
applications within a development team.
Exercise
References
Enabling Mobile Apps with IBM Worklight Application Center (An IBM
Redpaper publication)
http://www.redbooks.ibm.com/abstracts/redp5005.htm
l
Instructor Guide
Notes:
Unit objectives
Use the Application Center to manage and share mobile applications
within a development team.
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 18-2. What is IBM Worklight Application Center? WU5061.0
Notes:
repository, an administration console, and a client mobile application.
What is IBM Worklight Application Center?
The Application Center can be used as an Enterprise application store
and is a means of sharing information among different team members
within a company.
The concept of the Application Center is similar to the concept of the
Apple public App Store or the Android Market, except that it targets
only private usage within a company.
By using the Application Center, users from the same company or
organization download applications to mobile phones or tablets from a
single place that serves as a repository of mobile applications.
Works with IBM Worklight hybrid applications, but not restricted to
Worklight apps
Supports any iOS or Android application
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 18-3. Typical scenario WU5061.0
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.
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
A beta tester can launch the Application Center installer application,
the mobile client, locate the new version of the application and install
it on their mobile device
After testing, the beta tester can rate the application and submit
feedback on the Application Center console
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 18-4. Application Center architecture (1 of 2) WU5061.0
Notes:
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
iOs / Android
Application
Center
Installer App
Rest Services
Database - Derby
Application Center architecture (1 of 2)
Application Server
Application Center
Application Catalog
Service
Application Install
Service
Application Feedback
Service
Application Center
Console
Instructor Guide
V8.1
Uempty
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.
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 18-5. Application Center architecture (2 of 2) WU5061.0
Notes:
Application Center architecture (2 of 2)
The Application Center is installed as part of the Worklight Server
installation
As of IBM Worklight V5.0.6, the App Center is divided into two WAR
files: one for the console and one for services
The pre-built EAR file is available in
{worklight_install_folder}/ApplicationCenter/console.
The paths of the WAR files in this EAR file are as follows:
Console: /applicationconsole
Services: /applicationcenter
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 18-6. Application Center configuration WU5061.0
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.
Application Center configuration
The Application Center has two JEE security roles defined:
The appcenteruser role that represents an ordinary user of the Application
Center who can install mobile applications from the catalog to a mobile device
belonging to that user
The appcenteradmin role that represents a user who can perform administrative
tasks through the Application Center console
You must map the roles to the corresponding sets of users in your
organization
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 18-7. Application Center user configuration WU5061.0
Notes:
Application Center user configuration
You configure Application Center users in the WebSphere Application
Server console.
Access the Application Center by the following URL:
http://server:port/appcenterconsole
Where server is the address and port of the server where the
Application Center is installed
Only users with the administrator role can log in to the Application
Center console
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 18-8. Applications view WU5061.0
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.
Applications view
1. To add an application to the
console, click Add Application
2. Select an application (APK or IPA
file) to upload
Instructor Guide
Instructor notes:
Purpose
Details
Instructor Guide
V8.1
Uempty
Figure 18-9. Application details view WU5061.0
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.
Application details view
Instructor Guide
Internal Version: the internal version identification of the application;
android:versionCode attribute of the manifest element in the manifest file of
the application.
Commercial Version: the published version of the application.
Label: the label of the application; android:label attribute of the application
element in the manifest file of the application. See the Android SDK
documentation for more information.
For iOS applications:
Package is the company identifier and the product name;
CFBundleIdentifier key.
Internal Version is the build number of the application; CFBundleVersion
key of the application.
Commercial Version is the published version of the application.
Label is the label of the application; CFBundleDisplayName key of the
application. See the iOS SDK documentation for more information.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 18-10. Available applications view WU5061.0
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.
Available applications view
Version number
Rating
Access control setting
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 18-11. Feedback and rating WU5061.0
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.
Feedback and rating
Stakeholders and
testers submit
feedback directly from
the Application Center
mobile client
Stakeholders and
testers submit
feedback directly from
the Application Center
mobile client
Developers can review
feedback in the context of
specific device and user by
using the Application
Center console
Developers can review
feedback in the context of
specific device and user by
using the Application
Center console
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 18-12. Setting access control WU5061.0
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).
Setting access control
1. Select Applications > Available
Applications
2. Click unrestricted or restricted state of an
application.
3. To add a user, enter a user ID and click Add
User.
1. Select Applications > Available
Applications
2. Click unrestricted or restricted state of an
application.
3. To add a user, enter a user ID and click Add
User.
You can also add users
from another application.
Click Add users from
application, select the
application from the list,
and click OK.
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 18-13. Registered devices view WU5061.0
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.
Registered devices view
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 18-14. Application Center client WU5061.0
Notes:
Application Center client
A mobile application to manage
applications on the device
List all applications from the
catalog (for which you have
access rights)
List applications you have installed
on the device
Install an application or upgrade to
a new version
Provide feedback and rating for an
application (1-5 stars)
Set up the installer from the
Application Center console
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 18-15. Installing an application from the mobile client (1 of 2) WU5061.0
Notes:
Installing an application from the mobile client (1 of 2)
Nothing is installed
Nothing is installed
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 18-16. Installing an application from the mobile client (2 of 2) WU5061.0
Notes:
Installing an application from the mobile client (2 of 2)
Standard iOS controls
Standard iOS controls
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Notes:
Unit summary
Use the Application Center to manage and share mobile applications
within a development team.
Instructor Guide
V8.1
Uempty
Instructor notes:
the learning points
Instructor Guide
Notes:
8.0
Exercise 9
Exploring the Application Center
Instructor Guide
V8.1
Uempty
Instructor notes:
Instructor Guide
Notes:
Exercise objectives
Configure the Application Center
Manage applications in the Application Center
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Instructor Guide
Copyright IBM Corp. 2013 Unit 19. Course summary 19-1
V8.1
Uempty
Unit 19. Course summary
Estimated time
00:15
This unit summarizes the course, explains the class evaluation
process, and provides information for future study.
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
Instructor Guide
Notes:
Unit objectives
Identify other WebSphere Education courses that are related to this
topic
Instructor Guide
V8.1
Uempty
Instructor notes:
Details
Instructor Guide
Figure 19-2. Course learning objectives WU5061.0
Notes:
Course learning objectives
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
Use IBM Worklight client-side APIs for cross-platform portability
Use IBM Worklight server-side APIs for back-end integration
Include the Dojo Mobile, jQuery Mobile or Sencha Touch UI framework
in an application
Secure a mobile application using different IBM Worklight
authentication techniques
Manage application updates and versions
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Figure 19-3. References WU5061.0
Notes:
References
http://pic.dhe.ibm.com/infocenter/wrklight/v6r0m0/index.jsp?topic=%2Fcom.ibm.
help.doc%2Fwl_home.html
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Notes:
Unit summary
Identify other WebSphere Education courses that are related to this
topic
Instructor Guide
V8.1
Uempty
Instructor notes:
Purpose
Details
Instructor Guide
Instructor Guide
Copyright IBM Corp. 2013 Appendix 20. List of abbreviations 20-1
V8.1
AP
Appendix 20.List of abbreviations
IBM International Business Machines Corporation
Instructor Guide
V8.1
backpg
Back page

ABNFP Wu506 Instructorguide

Transféré par

Informations du document

Description originale:

Titre original

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

ABNFP Wu506 Instructorguide

Transféré par

Droits d'auteur :

Formats disponibles

Mobile Application

Development with IBM

was the name of a company acquired by IBM in July 2010.

Vous aimerez peut-être aussi