ShowTable of Contents
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 Wiki
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 series. 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 Worklight
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 6 and Eclipse 3.7.2 are used.
Download Eclipse from the
Eclipse Downloads page 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 page 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 IDE. 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 guide 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 Catalog 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
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:
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:
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 documentation. 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);
}
}
Select the image. A thumbnail is displayed.
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.