ShowTable of Contents
When using IBM Web Experience Factory 8.5 (WEF) to create an IBM Worklight hybrid application, you will need to consider the following components:
Worklight hybrid application. The Worklight hybrid application is installed on the iPhone or Android device, and provides access to the WEF application. The WEF application provides most of the user interface for this hybrid application, while the Worklight components used by the WEF application provide access to native device features. This type of hybrid application is often referred to as a "hybrid shell".
Worklight server. The Worklight server provides access to Worklight server-based functionality, including push notification, authentication and security services, and direct application updates. If your application is only accessing native device features (such as camera, contacts, or file transfer) it does not need to use the Worklight server.
There are several other steps required to set up your development environment to create and test hybrid applications.
Create a WEF project for developing Worklight hybrid applications. You will need to add a model that can be used to test native device features. A sample model with camera functionality can be downloaded from the WEF wiki.
Install IBM Worklight Studio. You will need to install and configure IBM Worklight Studio and any software development kits (SDKs) for the necessary mobile device type(s).
Create a Worklight hybrid application. You will need to use IBM Worklight Studio to create a hybrid application which provides access to the WEF application. You will need to install the hybrid application on a mobile device or emulator.
Run the hybrid application. You will need to install and run the hybrid application on a mobile device or emulator. If you encounter problems. you will need to troubleshoot the application or the development environment.
The steps provided below are specific for creating Worklight hybrid applications that run on Android devices. To create Worklight hybrid applications that run on iOS devices, refer tohttp://www-10.lotus.com/ldd/pfwiki.nsf/dx/Creating_iOS_Hybrid_Shell_Applications_with_Web_Experience_Factory_8.5_and_Worklight_126.96.36.199" title=" Creating iOS Hybrid Shell Applications with Web Experience Factory and Worklight"> Creating iOS Hybrid Shell Applications with Web Experience Factory and Worklight
Create a WEF project for developing Worklight hybrid applications
It is assumed that you already have Web Experience Factory 8.5 Designer set up and configured for developing portlets and web applications. If not, go to the WEF Wiki
for information on getting started.
1. Create the WEF project
Select the File > New > Project menu in WEF Designer, and choose the Web Experience Factory Project wizard to create a new WEF project. On the wizard's Project Name page, give the project an appropriate name (this example will use a project named "HybridAppTest".) On the wizard's Feature Set page, you will need to include the Worklight feature set. (Some of the Worklight sample models also require the Client-Side Application feature set.) On the wizard's Server Configuration page, choose the server to be used for publishing. By default, the project will be published to the Liberty server (if IBM WebSphere Application Server Liberty Profile 8.5 is installed,), but you can publish the project to any configured server.
An existing WEF project can also be used for developing Worklight hybrid applications by adding the Worklight feature set to the project. To do this, right-click the project in WEF Designer's Project Explorer view and select the Properties menu item. On the Properties dialog, navigate to the Web Experience Factory Project Properties > Features Info panel. Select the Worklight feature set and OK the dialog to include the features needed to develop Worklight hybrid applications. (Also select the Client-Side Application feature set to include the client-side features used by some of the Worklight sample models.)
2. Add a model
3. Enable file upload
The Camera builder includes functionality to upload pictures to the WEF server. However, WEF will only allow files to be uploaded if that capability is explicitly enabled for the project. In order to enable file upload, open the file at "/HybridAppTest/WebContent/WEB-INF/config/override.properties", and add the following properties. You can specify any value you choose for the maximum upload file size.
# This determines whether file upload is active for this server.
# This determines the maximum file size that can be uploaded at one time in KiloBytes.
4. Run the CameraTest model
Now run the CameraTest model from the WEF Designer.
A Worklight hybrid application can only be run from a mobile device. Because WEF runs models in a desktop browser, these models are not run as a Worklight hybrid application. Even though the application is not running as a Worklight hybrid application, the Camera UI is displayed because the "Hide If Not Hybrid Application" input in the model's Camera builder call is not checked. If that input was checked, the "Photo Preview", "Take Picture", and "Use existing picture" controls would be hidden when running in a desktop browser. Also note that the "Take Picture" button is disabled. This button will only be enabled when the device camera functionality is detected. Camera functionality is not available in a desktop browser, so the button remains disabled.
Eventually, when the application is run as a Worklight hybrid application on a mobile device, the "Take Picture" button will be enabled. However, a few more steps must be completed before the CameraTest application can be run as a Worklight hybrid application on a mobile device.
Install IBM Worklight Studio
1. Install Eclipse and the Worklight plugin
Refer to Installing IBM Worklight Developer Edition
for information on which version of Eclipse to install. This page will also provide information on how to install the latest version of the Worklight plugin. Use the "About Eclipse" dialog to verify that the installed version of Worklight is "6.1.0.01-20140427-1450", or later .
For easier setup and maintenance, it is recommended that you install a separate instance of Eclipse to be used for Worklight. It is not recommended to install Worklight in the same instance of Eclipse being used for WEF.
2. Install the Android SDK and ADT plugin
The Android SDK provides tools and APIs to build, test, and debug Android applications. For information on setting up an existing IDE for Android development, refer to Setting Up an Existing IDE
.The Android SDK Tools are Windows-based applications and can be run independently of Worklight. The ADT plugin is installed in the same Eclipse instance that is used for Worklight, and provides integration with the Android SDK Tools.
To create an emulator (called an Android Virtual Device or AVD) that can run Android applications on a Windows computer, refer to Managing Virtual Devices
Create a Worklight hybrid application
Worklight provides a "Design" perspective for working with Worklight projects. Open this perspective by selecting the Window > Open Perspective > Other
menu item, choosing "Design", and pressing the OK button.
Now create a Worklight project to be used for running the WEF Worklight samples by selecting the File > New > Worklight Project
menu item. Name the project "WEF_Samples". Press the "Next" button to display the Hybrid Application panel, and name the hybrid application "CameraTest". Once the project and application have been created, the "index.html" file is displayed. You will not need to edit this file, so you can close it. This new Worklight project now contains the necessary common files, but does not contain the necessary platform-specific files. To include these files for the Android platform, right-click on the "CameraTest" app folder, select the New > Worklight Environment
menu item, select the "Android phones and tablets" check box, and press the Finish button. The project and hybrid application will look similar to this:
The hybrid application now contains all of the necessary files, but does not yet have the necessary settings.
- In order to access the CameraTest application, the CameraTest URL must be specified in the element in the "application-descriptor.xml" file. The CameraTest URL can be obtained by launching the CameraTest model from the WEF Designer, and copying the URL from the address bar of the desktop browser.
- To allow the hybrid application to access the native Android device features, certain permissions must be defined in the "android/native/AndroidManifest.xml" file. The following permissions are required by the WEF Worklight samples:
<!-- Additional permissions for 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.RECORD_AUDIO" />
<uses-permission android:name="android.permission.VIBRATE" />
- In the "android/native/AndroidManifest.xml" file, remove the android:debuggable="true" attribute from the element. This attribute will result in an error if it is not removed.
- In order to avoid warnings during the application build, set the android:targetSdkVersion attribute in the "application-descriptor.xml" file to the latest installed version of the Android SDK (eg 19). Also, in the "android/native/project.properties" file, set the target to the latest installed version of the Android SDK (eg android-19).
Once the settings have been specified, the application environment must be updated by building the application. Right-click the CameraTest folder and select the Run As > Build All Environments
menu item. The hybrid application is now ready to run on a mobile device.
input should be set to “Never Include
input should be set to “Include when Running Standalone
input should be set to “Always Include”
Run the hybrid application
When the Worklight builds a hybrid application environment, it generates another project. For our example, the generated project is named "WEF_SamplesTestCameraAndroid".
Running a hybrid application
To run the hybrid application on an Android device, make sure an Android device is attached via USB, right-click the generated project and select the Run As > Android Application
menu item. In the Android Device Chooser dialog, select the attached Android device and press the OK button. This will install the Worklight hybrid application on the Android device. Once the application is installed, it will be launched and will run the CameraTest application.
Note that the "Take Picture" button is now enabled, because the device camera was detected. Pressing the Take Picture button will activate the camera on the Android device. Once the picture is saved from the camera, it will be displayed as a thumbnail in the "Photo Preview" control. Pressing the "Submit Picture" button shows the result of uploading the picture to the WEF server.
Troubleshooting a hybrid application
1. Common Issues
The ADT plugin provides the "Logcat" view in Eclipse. The Logcat view displays a detailed log of the hybrid application events occurring on the device.
3. Reverse proxy
A reverse proxy can be used to monitor the HTTP traffic for a Worklight hybrid application. This technique allows you to inspect the requests made from the hybrid application running on a mobile device, and the WEF responses to those requests. For example, Fiddler can be used as a reverse proxy by setting up your Worklight hybrid application to make requests to a specific port on which Fiddler is listening. Fiddler will monitor these requests, and can be configured (custom rule) to forward these requests to the WEF application.
Sample rule for forwarding port 8888 to the local Portal Server. This code is contained within Fiddler's OnBeforeRequest(oSession: Session) function. Any available port can be used, and rules can be setup to forward different ports to different servers.
// Reverse proxy for port 8888. All requests on port
// 8888 will be routed to the local Portal Server.
if (oSession.host == "192.168.1.101:8888")
// Default target is the local Portal Server.
oSession.host = "192.168.1.101:10039";
Sample rule for handling redirects, to make sure the subsequent request will be made through the proxy. This code is contained within Fiddler's OnBeforeResponse(
// Make sure any redirects go back through the proxy.
var location = oSession.oResponse.headers.Item["Location"].ToString();
// Handle a redirect to the local Portal Server.
location = location.Replace("192.168.1.101:10039", "192.168.1.101:8888")
, and displaying the Console
5. Application cache
If you change your model and want to test the new output, you do not need to republish your WEF project to the server. However, you may need clear the cached data for the hybrid application on 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.
6. IBM developerWorks