Skip to main content link. Accesskey S
  • Help
  • IBM Logo
  • IBM Web Experience Factory wiki
  • All Wikis
  • All Forums
  • ANNOUNCEMENT: Wiki changed to read-only. READ MORE...
  • Home
  • Product Documentation
  • Community Articles
  • Learning Center
  • IBM Redbooks
  • API Documentation
Search
Community Articles > Resources for Developers > Getting Started and Enabling Worklight Support
  • Share Show Menu▼
  • Subscribe Show Menu▼

About the Original Author

Click to view profileIBM contributorAjay Mulay
Contribution Summary:
  • Articles authored: 2
  • Articles edited: 2
  • Comments Posted: 0

Recent articles by this author

Simple Worklight Enablement builder samples

The Worklight Enablement builder introduced in the Multichannel Feature Pack for IBM Web Experience Factory v8.0.0.3 provides IBM Worklight APIs for a specified page and allows the page to access native mobile features. Samples provided below demonstrate how to use Cordova Device, Notification and ...

Getting Started and Enabling Worklight Support

This document provides step by step guide to configure Worklight Android with IBM Web Experience Factory to create a hybrid application.
Community articleGetting Started and Enabling Worklight Support
Added by IBM contributorAjay Mulay | Edited by IBM contributorMichael Burati on June 3, 2013 | Version 44
expanded Abstract
collapsed Abstract
This document provides step by step guide to configure Worklight & Android with IBM Web Experience Factory to create a hybrid application.
Tags: WEF Worklight Android iOS camera builder
ShowTable of Contents
HideTable of Contents
  • 1 Overview
  • 2 Setting up the Worklight and Android development environment
    • 2.1 Running your application on the Android Virtual Device / Emulator
    • 2.2 Running your application on actual Android device
  • 3 Creating a WEF project including the Camera (Feature Pack for 8.0) builder
  • 4 Providing the Worklight and Cordova JS files to the server application
  • 5 Creating a hybrid shell that points to your WEF server application
  • 6 Confirming your configuration and troubleshooting
    • 6.1 Troubleshooting your setup

Overview



When you run a hybrid application that is built using Worklight with Web Experience Factory (WEF), you have the following components:

  • The client application built with Worklight. This application is installed on a client mobile device such as an iPhone or Android smartphone. This application includes a web view that points to the server-based application. The user interface (UI) of this application comes from the server and is rendered in the web view of the hybrid application. This is what is often referred to as a "hybrid shell."
  • The server-based application built with WEF. Typically, this runs on WebSphere Portal, but you can also have the WEF application running on WebSphere Application Server. The UI, including forms, views, and so on, and logic for this application comes from standard WEF tools. To access native device features, such as the camera, the server application page must also include JavaScript (JS) libraries from Worklight and JS calls to those libraries. This is how the application can invoke the device camera. When you use the Camera builder, all the necessary calls to the JS libraries are generated for you by the Camera builder.
  • The Worklight server. If you are only using Cordova features in Worklight, such as the Camera support, the application does not need to access the Worklight server.

In order to build and test these hybrid applications, there are several steps involved in setting up complete environment. This document assumes that you already have an environment for developing and testing portlets or web applications with WEF. If you do not have an existing environment for developing and testing portlets or web applications, see the WEF Wikiexternal link for information on getting started with WEF.

To get started with these tools, complete the following steps:

  • Setting up the Worklight and Android development environment. This includes installing and configuring the mobile device software development kits (SDKs) for the device types you want to support (Android, iOS). Ensure that you can build and run a simple "hello world" Worklight application on your device or emulator.
  • Creating a WEF project that includes the Multi-Channel Feature Pack for WEF 8.0. In your project, include a simple test model, which you can download from the WEF wiki.
  • Providing the Worklight and Cordova JS files to the server application. These JS files are taken from your Worklight project, but must be available from the server pages where your application is running. To make the JS available on the server, provide these files via the portal theme, as described in parts 1 and 2 in this DeveloperWorks articles seriesexternal link. Alternatively, you can provide them in the WEF application WAR file.
  • Creating a hybrid shell that points to your server application. This is done using the Worklight Designer IDE along with the mobile device SDKs. When the hybrid shell is built, you must install it on your mobile device or emulator.
  • Confirming your configuration and troubleshooting. Sample CameraTest.model available on WEF samples wiki can be used to test hybrid camera functionality after you have built and configured your environment.

The steps in this document mostly describe how to create Android applications. To create iOS applications, follow the steps in this document - Creating iOS Hybrid Shell Applications with Web Experience Factory and Worklightexternal link

Setting up the Worklight and Android development environment


a. Download and install Eclipse
  • IBM Worklight Version 5.0.5 [1] supports Eclipse 3.6.2 and 3.7.2 [2].
  • The Android Development Tools (ADT) plugin, which we are using, supports Eclipse 3.6.2 or later [3].
  • The Android software development kit (SDK) requires Java Development Kit (JDK) 6 as well as the JRE[4].

In this document, 32-bit versions of the Sun JDK 6external link and Eclipse 3.7.2 are used.
Download Eclipse from the Eclipse Downloads pageexternal link and decompress it to your preferred folder. Eclipse requires a JRE in order to run. You can use the JRE included in JDK that you are planning to use for Android.
Note: Using two different versions of Eclipse for WEF and Worklight makes setup and maintenance easier.
b. Install the Worklight plugin for Eclipse
The installation instructions for the Worklight plugin are same as for any other Eclipse plugin installation.

Please refer to the Worklight installation pageexternal link for more information.

Note: The Worklight plugin installation on Eclipse 3.6.2 involves more steps than on Eclipse 3.7.2.
c. Create a new hybrid Worklight project
For Eclipse 3.7.2 navigate to File > New > Other > Worklight Project.

Name your project. Select Hybrid Application project template and click Next.

Name your application and click Finish. For convenience, you can name your application the same as your project, and append App to the name.



In this document, the name HelloWorld is used to identify the Worklight project and HelloWorldApp is used to identify the hybrid application we created in HelloWorld. Worklight generates the supporting file structure and resources for your Worklight project.

Publish HelloWorldApp to the Worklight server, which is part of Worklight plugin we installed before, by right clicking HelloWorldApp and selecting Run as > Build All and Deploy.
Note: By default, the local Worklight server uses port 8080.

The console displays progress information for the publishing of your application to the Worklight Server.



After the application is deployed to the Worklight server, navigate to the Worklight console at http://localhost:8080/console.



Click the Preview as Common Resources link to test HelloWorldApp in a browser. This default application only displays the name of your application in the browser.


d. Install the Android SDK and ADT plugin
The Android SDK provides tools and APIs to build, test, and debug applications on the Android platform. Steps to set up an existing IDE for Android development are at Setting up existing IDEexternal link. Follow these instructions to download and install the Android SDK. Install the ADT plugin in the same Eclipse that you are using for the Worklight plugin.

To create an Emulator / Android Virtual Device (AVD), navigate to Eclipse > Window > AVD Manager > Click New > Create AVD.

Refer to the Android Emulator developer guideexternal link to verify the configuration options and defaults.

Add an Android Environment for your Worklight application by clicking the IBM Worklight icon and selecting Worklight Environment.


Select the HelloWorld project, the HelloWorldApp, and the environment that you want to add. In this case, select Android phones and tablets and click Finish.



A subfolder folder named android is automatically created in your HelloWorld\apps\HelloWorldApp folder. This new folder contains the necessary supporting files.

You must build and deploy your project one more time. Right click HelloWorldApp and select Run As > Build All and Deploy. A new Android project named
ProjectNameApplicationNameAndroid, in this case HelloWorldHelloWorldAppAndroid, is created in your workspace.
e. Run your application
After you build and deploy your application to the Worklight server, you can preview it in the Worklight Console (http://localhost:8080/console/). To preview your application, click the preview icon next to the environment in which you want to run the application.

Running your application on the Android Virtual Device / Emulator

After you build and deploy your application on the Worklight server, right click the generated Android project HelloWorldHelloWorldAndroid and select Run As > Android Application.

The default AVD you created earlier launches and runs the application.


Running your application on actual Android device

If an Android device is connected to your system using a USB cable, the ADT plugin automatically recognizes it. You can change the configuration to launch the application on the device. Right click the Android project HelloWorldHelloWorldAndroid and select Run As > Run Configurations > Target > Pick up your Android Device.

Creating a WEF project including the Camera (Feature Pack for 8.0) builder


a. Create a WEF project with Mobile and Dojo feature sets, for example, TestCamera, by clicking File > New > Project.


b. Navigate to IBM Collaboration Solutions Catalogexternal link and download the IBM Multi-Channel FeaturePack For IBM Web Experience Factory v8.0 zip file.
c. Import the MultichannelResponsiveUI.zip WEF archive and Worklight.zip WEF archive to your project.
Right click project TestCamera and select Import > WEF Archive. Navigate to the Multi-Channel Feature Pack for WEF 8.0 folder and select the WEF archive zip files.


 

d. Enable file uploading for your project and edit related properties by selecting the WEF project TestCamera \ WebContent \ WEB-INF \ config \ override.properties file. In this case images are being uploaded to demo folder in the root folder of your application. Add following lines to the file:

NOTE - for quick-setup of the demo, this is specifying upload of the image immediately to servable content, which is not a best practice and could pose a security risk.

For actual applications and deployment, applications (camera or otherwise) should upload to non-servable content under WEB-INF,  validate the content with the application (eg, allowed/expected file types and optionally contents) and then move the file (image or otherwise) to a more permanent location outside the WAR .

# Enable file uploading

		bowstreet.upload.enabled=true

		# This sets the directory where uploaded files will be stored upon successful upload.
	
		# This should be under non-servable content ( WEB-INF/... ) and is a temporary location
	
		# until your application verifies the file extension and content and moves it to a more permanent location outside the WAR.

		bowstreet.upload.destinationPath=${bowstreet.rootDirectory}/../demo

		# This determines the maximum file size that can be uploaded at one time in KiloBytes.

		bowstreet.upload.maxFileSizeK=100000

		
e. Download the samples zip file, which contains sample Camera Test models, from the Camera Builder Samples for the Multichannel Feature Pack for WEF 8.0external link. Copy CameraTest.model to project
TestCamera \ WebContent \ WEB-INF \ models. You will be using the CameraTest.model to troubleshoot your hybrid shell in the following sections.

Providing the Worklight and Cordova JS files to the server application



The Worklight 5.0.5 JavaScript files must be available on the page containing the Camera (Feature Pack for 8.0) builder. There are two ways to provide these JavaScript files. For portlets that are deployed on IBM® WebSprhere® Portal Server, the JavaScript files can be added to a custom theme. Otherwise, the JavaScript files can be added to the WEF project so that they are included in the application WAR file.
a. Add the Worklight 5.0.5 JavaScript files to a custom WebSphere Portal theme
This is the preferred method of providing the Worklight 5.0.5 JavaScript files for portlets. Instructions for adding the Worklight JavaScript files to a WebSphere Portal theme and using the theme artifacts on a page can be found in the following IBM DeveloperWorks article:
Deliver an exceptional mobile web experience using WebSphere Portal and IBM Worklightexternal link.

b. Include the Worklight 5.0.5 JavaScript files in the Web Experience Factory WAR file
The JavaScript files required by a Worklight 5.0.5 hybrid application are contained in the HelloWorld Worklight project you created. The location of the JavaScript files is shown below. A copy of the highlighted "js" folders is used in the next step.
The JavaScript files from the Worklight project must be copied to the WEF project TestCamera in the locations shown below. The Camera (Feature Pack for 8.0) builder expects to find the Worklight 5.0.5 JavaScript files in these locations in the deployed application.
If the application will be available for iOS devices, then additional JavaScript files must be added to the WEF project. For the iOS JavaScript files to be created in your Worklight project, you must add an iPhone Worklight Environment to your Worklight project. Follow the previous steps for adding an Android phones and tablets Worklight Environment, but select the iPhone checkbox for the new Worklight Environment. This creates an iPhone folder within your Worklight application folder.
Locate the JavaScript files within the iPhone folder, as shown above for the Android folder. There are five JavaScript files that are renamed and copied to the TestCamera project, in the same locations shown above for the Android environment. The five JavaScript files are listed in the table below, which shows the original file name, the new file name, and the location of the new file within the TestCamera project.
Original File Name
New File Name
Location
wlcommon.js
wlcommon.ios.js
common/js
checksum.js
checksum.ios.js
wlclient/js
cordova.js
cordova.ios.js
wlclient/js
json2.js
json2.ios.js
wlclient/js
wlgap.js
wlgap.ios.js
wlclient/js
Set the Include Worklight JS input for the Camera (Feature Pack for 8.0) builder call
If the WEF application is always deployed as a portlet, and the Worklight JavaScript files are provided by the Portal Theme used on the page, then the Camera (Feature Pack for 8.0) builder call must specify Never Include for the Include Worklight JS input.
If the WEF application can be deployed as either a portlet or a standalone web application, and the Worklight JavaScript files are provided by the Portal Theme when the application is deployed as a portlet, then the Camera (Feature Pack for 8.0) builder call must specify Include when Running Standalone for the Include Worklight JS input.
In other cases, the Camera (Feature Pack for 8.0) builder call specifies Always Include for the Include Worklight JS input.
Note: If there are multiple Camera (Feature Pack for 8.0) builders in a WEF application, specify the same value for the Include Worklight JS input.

Creating a hybrid shell that points to your WEF server application


At this point, you have created your WEF project TestCamera and Worklight application HelloWorldApp in sections 2 and 1, respectively, in this document. You must add application permissions to the hybrid application HelloWorldApp and point it to the WEF application deployed on the Portal Server.
a. Navigate to your Worklight project HelloWorld \ apps \ HelloWorldApp \ android \ native \ AndroidManifest.xml. The following permissions are used for accessing camera functionality and the mobile geolocation:
<!-- Added To test WEF application -->

	<uses-permission android:name="android.permission.CAMERA" />

	<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

	<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

	<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

	<!-- -->

	


b. You must also update the HelloWorld.java Java file that invokes the application. Navigate to project HelloWorld \ apps \ HelloWorldApp \ android \ native \ src \ com \ HelloWorldApp \ HelloWorldApp.java.

The Java file contains:
package com.HelloWorldApp;

			

			import android.os.Bundle;

			import com.worklight.androidgap.WLDroidGap;

			

			public class HelloWorldApp extends WLDroidGap

			{

			@Override

			public void onCreate(Bundle savedInstanceState)

			{

			super.onCreate(savedInstanceState);

			//DeviceAuthManager.getInstance().setProvisioningDelegate(<Use default ProvisioningDelegateImpl class or replace with your IProvisioningDelegate implementation>);

			super.loadUrl(getWebMainFilePath());

			}

			}

			

The Worklight application HelloWorldApp uses the HelloWorldApp class to, by default, forward control to the HTML page located at project HelloWorld \ apps \ HelloWorldApp \ common \ HelloWorldApp.html. You must update the HelloWorldApp class to point it to your server and application.

To point to your server and application, you have two options: use the stand-alone WEF model URL or use the WebSphere Portal URL and access the application as a portlet. You also add code for CookieManager in the onCreate method as follows:
public void onCreate(Bundle savedInstanceState)

	{

	super.onCreate(savedInstanceState);

	CookieSyncManager.createInstance(appView.getContext());

	CookieManager.getInstance().removeSessionCookie();

	// For accessing via WebSphere Portal:

	// super.loadUrl("http://10.0.2.2:10039/wps/portal",false);

	// For the standalone Web Experience Factory model:

	super.loadUrl("http://10.0.2.2:10039/TestCamera/webengine/samples/fp80/camera_test/CameraTest", false);

	}

	
Note: The IP address here is the IP address of WebSphere Portal server on which you published your WEF project. 10.0.2.2 is used here as an alias to your host loopback interface, for example, 127.0.0.1 on your development machine, as described in Android Emulator documentationexternal link. If your portal server is running on the same machine as your Worklight Eclipse machine, you can use a 10.0.2.2 IP address similar to the local host, but only for the Emulator.

Import the following classes to resolve the dependencies of CookieManager and CookieSyncManager.
import android.webkit.CookieSyncManager;

		import android.webkit.CookieManager;

		

Add the following method for authenticated pages to work with the redirects. Add this method to the HelloWorldApp class.
public void loadUrl(String url)
		
			{

			loadUrl(url,false);

			}

			

Here is the final version of your HelloWorldApp.java file:
package com.HelloWorldApp;
		
			

			import android.os.Bundle;

			import android.webkit.CookieSyncManager;

			import android.webkit.CookieManager;

			import com.worklight.androidgap.WLDroidGap;

			

			public class HelloWorldApp extends WLDroidGap

			{

			@Override

			public void onCreate(Bundle savedInstanceState)

			{

			super.onCreate(savedInstanceState);

			CookieSyncManager.createInstance(appView.getContext());

			CookieManager.getInstance().removeSessionCookie();

			// For accessing via WebSphere Portal:

			// super.loadUrl("http://10.0.2.2:10039/wps/portal",false);

			// For the standalone Web Experience Factory model:

			super.loadUrl("http://10.0.2.2:10039/TestCamera/webengine/samples/fp80/camera_test/CameraTest", false);

			} 

			

			public void loadUrl(String url)

			{

			loadUrl(url,false);

			} 

			}

			
c. Modify the config.xml file located in your project at HelloWorld \ apps \ HelloWorldApp \ android \ native \ res \ xml \ config.xml.Allow access to the domains on which you are hosting your application.
 
 
The access elements we added for our application are highlighted in the above screen shot.
 

Confirming your configuration and troubleshooting

After you create a WEF project, add new Feature sets and JS files, and add a CameraTest.model to your project, use the CameraTest sample model to test your environment.
a. Refresh the project TestCamera. Make sure there are no errors.
b. Publish your project to the portal server. Running the CameraTest.model model on the portal server displays the output shown below in a web browser:
Point your hybrid shell to the address highlighted below. (Verify the link specified in the onCreate() method in the HelloWorldApp.java file in your worklight hybrid project is same as the highlighted URL below.)
c. Click the Take Picture button. The following pop-up message is displayed:
d. To test the CameraTest model with the hybrid Shell, build and deploy your android application. Navigate to your Worklight project HelloWorld and select apps. Right click HelloWorldApp and select Run As > Build All and Deploy.
e. Right click your Worklight generated Android project HelloWorldHelloWorldAppAndroid and select Run As > Android Application.
f. This launches the Android Emulator. It takes several seconds for the Emulator to launch and load device settings. Your hybrid application is loaded on the emulator and starts running in a few seconds.
Click the Take Picture button.

Select the image. A thumbnail is displayed.


Troubleshooting your setup

a. If you are running your model stand-alone in a Chrome browser from a WEF project, you can look for anomalies on the Chrome Developer Tools console by right clicking anywhere on the page and selecting Inspect element > Console.

b. The Logcat window in Worklight Eclipse displays a detailed log of all the actions taking place while running your application. Check this log if problems occur.


c. If you change your model and want to test the new output, you do not need to republish it to the server. However, you must clear the application cache from the device. For Android devices, navigate to Settings > Application Manager > All and select your application. Select Clear Data. For iOS devices, uninstalling and then installing your application again clears the cache.
d. For additional questions, refer to the following forums:
  • WEF Forumexternal link
  • Worklight Forumexternal link
  • Portal Forumexternal link
 

 

expanded Attachments (0)
collapsed Attachments (0)
expanded Versions (52)
collapsed Versions (52)
Version Comparison     
VersionDateChanged by              Summary of changes
52Jun 19, 2014, 11:46:01 AMThomas Dinger  IBM contributor
51Sep 20, 2013, 3:50:52 PMAjay Mulay  IBM contributor
50Sep 20, 2013, 3:35:39 PMAjay Mulay  IBM contributor
49Sep 18, 2013, 4:32:43 PMAjay Mulay  IBM contributor
48Sep 18, 2013, 4:26:09 PMAjay Mulay  IBM contributor
47Sep 18, 2013, 11:10:40 AMAjay Mulay  IBM contributor
45Jun 24, 2013, 4:39:32 AMThomas Dinger  IBM contributor
45Sep 16, 2013, 4:44:05 PMAjay Mulay  IBM contributor
This version (44)Jun 3, 2013, 5:13:23 PMMichael Burati  IBM contributorAdd a note that the above upload config location is for quick demo pur...
43Feb 7, 2013, 3:11:22 AMThomas Dinger  IBM contributor
42Jan 28, 2013, 4:44:43 AMThomas Dinger  IBM contributor
41Jan 28, 2013, 4:08:45 AMThomas Dinger  IBM contributor
40Jan 28, 2013, 3:05:26 AMThomas Dinger  IBM contributor
39Jan 28, 2013, 1:55:35 AMThomas Dinger  IBM contributor
37Jan 27, 2013, 11:55:49 PMThomas Dinger  IBM contributor
37Jan 27, 2013, 11:55:49 PMThomas Dinger  IBM contributor
36Jan 27, 2013, 2:43:49 PMThomas Dinger  IBM contributor
35Jan 27, 2013, 1:23:43 PMThomas Dinger  IBM contributor
34Jan 27, 2013, 4:57:12 AMThomas Dinger  IBM contributor
33Jan 26, 2013, 4:16:51 PMThomas Dinger  IBM contributor
32Jan 26, 2013, 3:10:44 PMThomas Dinger  IBM contributor
31Jan 26, 2013, 2:16:32 PMThomas Dinger  IBM contributor
30Jan 26, 2013, 12:58:15 PMThomas Dinger  IBM contributor
29Jan 26, 2013, 5:59:52 AMThomas Dinger  IBM contributor
28Jan 26, 2013, 5:18:03 AMThomas Dinger  IBM contributor
27Jan 26, 2013, 3:16:04 AMThomas Dinger  IBM contributor
26Jan 25, 2013, 8:50:45 PMThomas Dinger  IBM contributor
25Jan 25, 2013, 1:26:24 PMAjay Mulay  IBM contributor
24Jan 25, 2013, 1:10:35 PMAjay Mulay  IBM contributor
23Jan 25, 2013, 12:28:11 PMAjay Mulay  IBM contributor
22Jan 25, 2013, 12:21:23 PMAjay Mulay  IBM contributor
21Jan 25, 2013, 11:30:24 AMAjay Mulay  IBM contributor
20Jan 25, 2013, 11:07:47 AMAjay Mulay  IBM contributor
19Jan 25, 2013, 10:40:25 AMAjay Mulay  IBM contributor
17Jan 25, 2013, 9:43:05 AMAjay Mulay  IBM contributor
16Jan 25, 2013, 9:40:01 AMAjay Mulay  IBM contributor
15Jan 8, 2013, 3:33:19 PMAjay Mulay  IBM contributor
14Jan 8, 2013, 3:33:08 PMAjay Mulay  IBM contributor
13Jan 8, 2013, 3:21:38 PMAjay Mulay  IBM contributor
12Jan 8, 2013, 3:18:55 PMAjay Mulay  IBM contributor
11Jan 8, 2013, 3:17:00 PMAjay Mulay  IBM contributor
10Jan 8, 2013, 11:51:57 AMAjay Mulay  IBM contributor
9Jan 8, 2013, 11:20:18 AMAjay Mulay  IBM contributor
8Jan 8, 2013, 10:53:32 AMAjay Mulay  IBM contributor
7Jan 8, 2013, 10:49:28 AMAjay Mulay  IBM contributor
6Jan 8, 2013, 10:23:10 AMAjay Mulay  IBM contributor
5Jan 8, 2013, 10:22:55 AMAjay Mulay  IBM contributor
4Jan 8, 2013, 10:21:20 AMAjay Mulay  IBM contributor
3Jan 8, 2013, 10:10:05 AMAjay Mulay  IBM contributor
2Jan 8, 2013, 10:08:49 AMAjay Mulay  IBM contributor
1Jan 3, 2013, 1:09:06 PMAjay Mulay  IBM contributor
1Jan 3, 2013, 1:12:47 PMAjay Mulay  IBM contributor
Copy and paste this wiki markup to link to this article from another article in this wiki.
Go ElsewhereStay ConnectedHelpAbout
  • IBM Collaboration Solutions wikis
  • IBM developerWorks
  • IBM Software support
  • Twitter LinkIBMSocialBizUX on Twitter
  • BlogsIBMSocialBizUX on Facebook
  • ForumsLotus product forums
  • BlogsIBM Social Business UX blog
  • Community LinkThe Social Lounge
  • Wiki Help
  • Forgot user name/password
  • Wiki design feedback
  • Content feedback
  • About the wiki
  • About IBM
  • Privacy
  • Accessibility
  • IBM Terms of use
  • Wiki terms of use