Unit 4 - IBM Worklight client-side development: Core APIs

Client-side basics
Application Sources

• Main HTML file: index.html

• Main JavaScript file: main.js
• Messages.js: used for storing application strings; primarily used for globalization
Worklight apps are developed by using standard web technologies:

• A single HTML file

• JavaScript
• Style sheets and images
Worklight apps use the Worklight API to access back-end data and server functionality.
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 load the
necessary APIs.
The main JavaScript file contains application logic including initialization, back-end data access,
and loading of other application logic modules.
Another core library that is used by Worklight client API is the jQuery library. Worklight comes
bundled with an encapsulated jQuery, which can be added to developer’s project with a single
line of code.
Worklight initialization

 initOptions.js
It defines application initialization options.
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.
The initOptions.js file calls WL.Client.init, passing an options object that includes any values that
you have overridden.
jQuery JavaScript framework

 wlq.js
Worklight includes an encapsulated jQuery, which can be added to the developer project with a
single line of code: – window.$ = window.jQuery = WLJQ;
The reference for the encapsulated jQuery in Worklight that is shown above, must be placed in
the appName.js file. There is no error message, or problem indicated if you do not include this
line.
Worklight client JavaScript API

 Worklight.js
Worklight Client API uses WL namespace. It provides bridging to native mobile platform APIs,
dynamic HTML load, and so on.
The WL namespace

• Use a WL namespace to use a Worklight API, for example: WL.Client, WL.Utils, and so
on.
• Exposes the API objects, methods, and constants (usually enums).
• Automatically added to the application main HTML file – worklight.js
• WL Namespace is automatically available on application initialization.
WL.client
With WL.Client, you can perform the following type of tasks:
• Initialize and reload the app
• Trigger login and logout
• Obtain general app information
• Retrieve and update data from corporate information systems
WL.Client.invokeProcedure (invocationData, options)
• Store and retrieve user preferences across sessions
• Specify environment-specific user interface behavior
• Store custom log lines for auditing and reporting purposes in special database tables
WL.Client.logActivity (activityType)
 Basic Debugging

Client-side debugging
You can debug native code by using standard tools that the platform SDK provides, such as
Xcode, Android LogCat/ADB, or Microsoft Visual Studio.
Desktop browser
Modern browsers, such as Chrome, Firefox, Safari, Opera, or Internet Explorer, provide an easy
and convenient way to debug web apps.
Web tools
There are many web tools for debugging on various desktop browsers, such as:
• FireBug extension for Firefox
• Developer tools for Chrome (press Ctrl+Shift+I to start)
• Developer tools for Internet Explorer (press F12 to start)
• Dragonfly for Opera
WL.Logger
IBM Worklight provides a WL.Logger object that you use to print log messages to the log for the
environment used.
Two of its methods: WL.Logger.debug() and WL.Logger.error()
The APIs are multiplatform. The output destination changes according to the platform on which
that application runs on:
• Developer console when it is running on a desktop browser.
• LogCat when it is running on Android device.
• Visual Studio Output when it is running on a Windows Phone 8 device and Windows 8
Apps.
• Xcode console when it is running on an iOS device.
Weinre (Web Inspector Remote)
Weinre is a debugger for web pages that is designed to work remotely.
You can use Weinre:
• for debugging of web pages on mobile devices such as iPhone or Android.
• to inspect and debug web resources such as HTML, JavaScript, CSS, and network traffic
on a remote mobile handset.
Weinre has a built-in JavaScript console that you can use as an extra powerful tool for web-
based mobile application debugging.
WireShark
It is a network protocol analyzer that you can use to see what happens on your network at a
microscopic level.
With WireShark, you can filter the range of traffic that you want to follow.

Building a multi-page Application

Working with pages
Applications with multiple pages can be built in two ways:
1. Single HTML file that contains all application pages.
2. Separate HTML file for each application page.

Note:
An IBM Worklight hybrid application uses a single DOM model. A single DOM model means that
you cannot navigate between various HTML files by using hyperlinks or changing the
window.location property.
Instead, you must implement multi-page interfaces by loading external HTML file content, and
by using Ajax requests and injecting into the existing DOM. This is because the main application
HTML file loads the IBM 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.
Design Considerations
• A single HTML file is the preferred model for simpler applications.
• The developer is responsible for showing the current page <div> and hiding the rest.
However, large applications present a challenge:
• The developer must take full responsibility for which DIVs are shown and which DIVs are
hidden at any moment.
• If you want to add some new content to a page, for example a table, you cannot load a
prepared template but must generate it manually.
• A single large HTML file with many pages takes longer to load.
• It is easy to get lost in a single HTML file that contains multiple pages. Separate files are
easier to manage.
Dynamic Page Loading
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.
• You can insert HTML pages with CSS and JavaScript as needed.
• It is possible to implement navigation history.
• JavaScript code can be run when pages are loaded or unloaded
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.
• Can include JavaScript by using <script> tag
• Can include CSS files by using <link> tag
• You can inject it into the parent element by using <div>, but this method is not
mandatory
• Implemented by using jQuery $().load()API
• To load an HTML file, use the following syntax:
$(containerSelector).load(filePath, callbackFunction);
NOTE:
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: JavaScript function to execute when loading completes.
Common Controls
Worklight common controls are sets of pre-built client-side libraries or UI widgets for frequently
used UI functions such as modal pop-up, loading screens, tab bars, and other functions. These
UI components are common to most device environments.
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.
Developers can save a lot of time because they do not have to build these UI component
controls. They customize them to render in a native fashion for each supported device
environment.
WL.BusyIndicator
• WL.BusyIndicator implements a common API to display a modal activity indicator.
• Uses native implementation on Android, iPhone, and Windows Phone platforms.
• 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)
• 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 visible
WL.SimpleDialog

• Implements a common API for showing a dialog box with buttons for the application.
This technology is useful in constructing informational pop-ups or getting the user’s
attention.
• Uses native implementation on mobile platforms.
• Supports up to three buttons.
• Invocation syntax is:
▪ Parameters: title, text, and buttons as an array of up to three button objects
▪ The dialog box is closed when any of the buttons is clicked
▪ Options is an object with the form {title:String, text: String}
Worklight SimpleDialog takes four parameters:
1. The first parameter defines the title of the dialog box. It is mandatory.
2. The second parameter defines the text to show in the dialog box. It is also mandatory.
3. The third parameter represents the buttons to be placed in the dialog box. You can add
up to three buttons.
4. The options parameter is ignored by iPhone and Android. It has the form {title: string,
text: string}.
The active dialog box is closed when any of the buttons is pressed.

• Each button object has two properties:

1. text: the text that is displayed on the button.
2. handler: function to invoke if button is clicked.
The Dialog has two limitations:
1. When you use WL.SimpleDialog in Windows 8, you can use four buttons at most in each
WL.SimpleDialog.
2. When you use WL.SimpleDialog in Android, you can use three buttons at most in each
WL.SimpleDialog.
WL.TabBar

• Provides tabbed application navigation with a tab bar component.

• The Android and iOS mobile environments support the tab bar.
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.

• iOS implementation takes advantage of a native component.

• Android uses an HTML generated tab-bar.
• WL.TabBar must be initialized before use. The API you use is WL.TabBar.init().
• InitializeWL.TabBar in an environment JavaScript file.
• Use the following syntax to add a tab bar item:
WL.TabBar.addItem (itemID, callback, title, options);
▪ 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.
You use WL.TabBar.addItem to add a tab item. This API takes four parameters:
1. First, is the item id that uniquely identifies this tab item.
2. The callback function that must be invoked when the user interacts with this tab item.
For example, load a new page or open a dialog box when this tab item is used.
3. The third parameter specifies title text for this tab item for display.
4. The fourth parameter is an option object that contains device-specific information of
how to render the tab item.
WL.OptionsMenu

• The options menu displays buttons that can be used to invoke activities that are related
to the primary functionality.
• The options menu can be displayed by:
▪ Android
▪ Windows Phone 8
▪ Windows 8
On Android, the Options menu contains primary functionality that applies globally to the
current activity or starts a related activity. It is typically invoked when the user presses a button,
often labeled Menu.

• Initialize WL.OptionsMenu in the appropriate JavaScript file.

• The syntax is similar to that of the tab bar with some minor changes.
NOTE: You need to initialize the Worklight OptionsMenu before you can use it. To do this, use
WL.OptionsMenu.init.

• Use the following syntax to add an options menu:

WL.OptionsMenu.addItem(itemID, callback, title, options);
▪ 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:
o image:A path to a designated image, relative to resources root directory.
48x48px black and white .png file
o enabled: Boolean stating if the item is enabled or disabled
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 four parameters:
1. ItemID represents the unique identifier of a menu item.
2. The second parameter defines the callback function that should be invoked when the
user selects the item in the options menu.
3. You can specify the Menu title text by using the third parameter.
4. The Options parameter allows the application to customize the menu item and set it to
enabled or disabled.
Paths to image files should not be given; instead, the files should be placed at the following
locations:
• Android: nativeResouces\drawable-*
• Windows 8: Resources\applicationBar
• Windows Phone 8: nativeResources\applicationBar
Splash screen
• Worklight framework can provide a default splash screen.
▪ The splash screen is shown while the application launches.
• Code is defined in:
▪ android\native\src\com\app-name\app-name.java
▪ iphone-or-ipad\native\Classes\app-name.m
• The splash screen is hidden when initialization finishes.
• Supported by Android and iOS.
Hiding the splash screen
• Uncomment autoHideSplash in initOptions.js
• Use the following API method in at the point in the JavaScript code where you want the
splash screen to be hidden:
function wlCommonInit() {
WL.App.hideSplashScreen();
}
Showing the splash screen
• The splash screen can be displayed by using the JavaScript API:
WL.App.showSplashScreen();
Customizing the splash screen
• By default, the splash screen used in a Worklight application is a static image
• To use a different image, replace the following with another image:
▪ Android: native\res\drawable\splash.9.png
▪ iOS: native\Resources\Default-*.png
• You can implement custom code to extend the potential of the splash screen.
For example:
▪ Extend the time the splash screen is displayed
▪ Display an animated “loading…” screen
▪ Display a short video clip

Offline Access

Working in Offline Mode

• The Worklight Platform allows developers to detect application connectivity failures and
determine course of action.
• Applications going offline and online can be detected in two ways:
▪ Explicitly, on invoking server-based procedures.
▪ Implicitly, by using JavaScript event listeners.
• Developers can define custom application behavior for offline and online status.

Active detection: using methods

• Connectivity loss can be handled in two locations in application code:

▪ Application initialization: initOptions.js
▪ Adapter procedure invocation: WL.Client.invokeProcedure()
Both APIs can take an option parameter that you can use to 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 developers often focus on implementing the callback function to react to offline
condition.
Passive detection: Offline and online events

• Each time the Worklight framework attempts to access the Worklight Server; it might
detect that the application 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.
connect()

• WL.Client.connect (options): Attempts to connect to the Worklight Server and return to

online mode; options is an object that contains 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
getNetworkInfo()

• WL.Device.getNetworkInfo(callback) method is available for iOS and Android

environments.
• A callback must be specified as a function parameter.
The callback function receives a JSON structure with these properties:

• isAirplaneMode: true/false
• carrierName: string (for example, AT&T, VERIZON, and other providers)
• telephonyNetworkType: string (for example, UMTS or GPRS)
• isRoaming: true/false
• networkConnectionType: mobile/WIFI
• ipAddress: string
• isNetworkConnected: true/false
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.
• This technique is useful to restart connectivity on the device when the user leaves the
application.
• On returning to the app, the user expects the app to connect.

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.
• Both WL.Events.WORKLIGHT_IS_CONNECTED and
WL.Events.WORKLIGHT_IS_DISCONNECTED can be fired by the heartbeat.
• You can specify the heartbeat interval by using the
WL.Client.setHeartBeatInterval(intervalSeconds)API.
NOTE: A value of -1 disables the heartbeat.

String Translation
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 by using JavaScript.
Changing the default encoding in Eclipse

• The default workspace encoding in Eclipse is Cp1252.

• Before starting the translation work, this default encoding of the Eclipse workspace
must be changed before creating the Worklight project.
• In Eclipse, navigate to Window >Preferences> General> Workspace, and change the
encoding to UTF-8.
Enabling translation

• The messages.js file, which is designated for application strings, is in the common/js
folder.
• Application messages that are 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”.
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.
• To enable translation for a system message, override it in your application JavaScript.
• Override system messages on a global JavaScript level because some parts of the code
are executed only after the application has successfully initialized.
Setting 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.
NOTE: You should implement this override in a global-level JavaScript component so that it can
be used throughout your application.

Detecting device locale and language

• Use WL.App.getDeviceLocale() and WL.App.getDeviceLanguage() to detect the current

locale.