Recently I worked on a project that introduced me to IBM® Worklight® mobile application platform. Among other things, I was pleasantly surprised at the price tag of the Developer Edition of this product: it is free. The Developer Edition comes with an Eclipse-based IDE called the Worklight Studio which offers support for authoring the client-side of your mobile web, hybrid and native apps as well as developing server-side components called adapters.
The Worklight Studio comes with a web application called the Mobile Browser Simulator that can help you with developing and testing your hybrid applications created using Apache Cordova framework. The Mobile Browser Simulator offers you a suite of visual controls for simulating a variety of native bridge APIs to such native device capabilities as accelerometer, camera, compass, file system, device info, contacts database, etc., without the need to run your apps directly on mobile devices or their emulators (which would require setting up specific run-time environments, such as ADT Eclipse plug-in for Android, Xcode for iPhone, etc.)
Here is a screen-shot of the Mobile Browser Simulator that shows Cordova APIs’ visual controls/widgets on the left with the expanded Battery widget that helps simulate different battery levels and the battery plugged-in event (fired when the battery is plugged in for charging and stays in this state until un-plugged).
So, if you are interested in this approach to testing Cordova hybrid apps, below are a few simple steps to follow that will help you get up and running in no time.
Note: For this blog posting, I used Worklight ver. 6.0 which comes with Cordova framework ver. 2.6.
Prerequisites
- Make sure you have Java SE 6+ installed on your machine and the JAVA_HOME environment variable is properly set up (Java is needed for the Worklight Studio). I used JDK 6 update 20.
- Your browser should allow the running of Java applications inside it (it is required by the Worklight’s Mobile Browser Simulator web app)
- Download jQuery and jQuery mobile files and save them locally (the Worklight Studio will need them when building hybrid apps)
For this blog posting, I used:
Setting up the Worklight Studio
We will use the Juno package of Eclipse for Java EE development as the basis for the Worklight Studio IDE.
- Download and install the Juno package Sr2 for Java EE Developers
Run Eclipse and create a workspace as you would normally do. - In the Eclipse Toolbar, select Help > Eclipse Marketplace …
- In the Find window, enter Worklight; select Application Development Frameworks in the Categories drop-down listYou should get to the IBM Worklight Developer edition installation screen
- Click the Install button
- Wait for the system configuration process to complete
When prompted by the Confirm Selected Features dialog, select all options.
- Click Next >
- When prompted to Accept Licenses, do so and click Finish
Wait for the Worklight Studio installation to complete.
If prompted with Windows Security Alerts, allow access for the application. - In the Software Updates prompt, click Yes to restart Eclipse
Now time to set up a Worklight project.
Setting up a Worklight Project
When the Eclipse IDE restarts, activate it and close the Welcome dialog.
- In the Project Explorer view, right-click and select New > Worklight Project
- In the New Worklight Project dialog, for the Name, enter MobileAppTest
Keep the Hybrid Application Template selected. - Click Next >
The New Worklight Project dialog opens. - [In the New Worklight Project dialog] For the Application name, enter MobileAppTest; check the Add jQuery Mobile check-box; for the Location, enter the location of the jQuery mobile files you downloaded earlier and select all items in that folder
Ignore any warnings you may see.
- Click Finish
Now, you need to set up Mobile platform-specific project facets that are called Worklight Environments and which help with platform-specific content. - Right-click the MobileAppTest project and select New > Worklight Environment
- In the New Worklight Environment dialog that opens, select MobileAppTest in the Application/Component drop-down list; select support for iPhone and Android phones and tablets mobile platform environments
- Click Finish
Ignore a message in the Console window related to the failed import (shown in red). This warning is caused by the missing Android SDK which we are not going to install.
So, now you have your development environment all set up and you should have the following folder structure of your Worklight Studio project:
Platform-specific content goes into specific directories (under the android and iphone folders, in our case); the content shared between the two environments is stored under the common folder.The main app file is specified in application-descriptor.xml and, by default, it points to the HTML5 file named after the project name.The jQuery files you specified at the project creation step are stashed in the jqueyMobile folder.The auto-generated MobileAppTest.html file is a standard HTML5 file that leverages functionality of the jQuery mobile library. Worklight’s JavaScript libraries that support building hybrid apps are injected via the js/initOptions.jsscript. Let’s do some quick changes to the MobileAppTest.html file before we run it.
Locate the
<div data-role="content" style="padding: 15px">MobileAppTest</div>
line and replace it with
Hello, the mobile world!As a result of this update, the line should look as follows:
<div data-role="content" style="padding: 15px">Hello, the mobile world!</div>Save the file by pressing Ctrl-S.
Now, we are ready to run our first app in Worklight.
Building and Running your Worklight Application
- Right-click the apps/MobileAppTest node in the project tree and select RunAs > Build All and Deploy
If everything was done correctly, you should have your application registered with the Worklight server from where it can be managed via the Administrative web console.The Administrative web console (Admin console) is also a place from where you can launch the Mobile Browser Simulator that emulates the running of our applications on iPhone and Android (or other devices, if so configured).
It is interesting to note that previous versions of Worklight (e.g. 5.0.6) used Jetty as its development server; as of version 6, IBM decided to equip Worklight Studio with WebSphere Application Server 8.5 Liberty Profile which is Java EE 6 Web Profile certified. So, as a bonus for using Worklight 6.0, you can deploy your Dynamic Web Projects in this complimentary Web container ( which runs its HTTP connector on port 10080 ) with very fast startup time.
Let’s access the Admin console in order to launch our app.
- Use your browser to navigate to http://localhost:10080/MobileAppTest/console
You should see two versions of our MobileAppTest application: one for iPhone and the other for Android.
- Click the eye icon on the iPhone line to preview the iPhone version of the app
You can also do the same thing for the Android version of the app.
If you are prompted with the Do you want to run this application? dialog, click the Run button. And if you are prompted with the Security Warning dialog, click the Don’t Block button.And, at last, you should see our Hello, the mobile world! message rendered across the top of the Apple iPhone simulator screen.
At this point, you can start testing your hybrid apps in the Mobile Browser Simulator. Get code snippets from the official Cordova web site and use them in your MobileAppTest.html file.
Coding
Below is the source of a simple mobile hybrid app that detects battery level changes. The user-defined call-back function will be called by Cordova when it detects that the battery level has changed by at least 1 percent. This event is also fired when the device has been plugged in for charging or when un-plugged.
In code below, the user-defined function, onBatteryStatus, is registered as a call-back (event handler) for the batterystatus event through this binding statement: window.addEventListener(“batterystatus”, onBatteryStatus, false);
Just replace the existing content of the MobileAppTest.html file with the code below.
Note. Since we are using jQuery, there is a better way to attach to the DOM-ready event than using the HTML Body’s onLoad event handler. But here we are using the traditional way to make code simple.
<!DOCTYPE HTML>
<html>
<head>
<meta charset="UTF-8">
<title>MobileAppTest</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=0">
<link rel="shortcut icon" href="images/favicon.png">
<link rel="apple-touch-icon" href="images/apple-touch-icon.png">
<link href="jqueryMobile/jquery.mobile-1.3.1.css" rel="stylesheet">
<link rel="stylesheet" href="css/MobileAppTest.css">
<script>window.$ = window.jQuery = WLJQ;</script>
<script src="jqueryMobile/jquery-1.9.1.js"></script>
<script src="jqueryMobile/jquery.mobile-1.3.1.js"></script>
<script>
function onLoad() {
console.log("About to add deviceready event listener ...");
document.addEventListener("deviceready", onDeviceReady, false);
}
function onDeviceReady() {
console.log("Device-ready Cordova system event fired ...");
window.addEventListener("batterystatus", onBatteryStatus, false);
}
function onBatteryStatus(info) {
var e = document.getElementById('batteryStatus');
e.innerHTML = 'Battery level: ' + info.level + '<br />'
+ 'Is device plugged in?: ' + info.isPlugged;
}
</script>
</head>
<body id="content" style="display: none;" onload="onLoad()">
<!-- Page area starts -->
<div data-role="page">
<!-- Content area starts -->
<div data-role="content" data-theme="d">
<ul data-role="listview">
<li>
<p id="batteryStatus">Loading battery status...</p>
<li>
</ul>
</div>
<!-- ~~ Content area ends -->
</div>
<!-- ~~ Page area ends -->
<script src="js/initOptions.js"></script>
<script src="js/MobileAppTest.js"></script>
<script src="js/messages.js"></script>
</body>
</html>
Restart the application. Refresh the Admin console and launch the Mobile Browser Simulator.
Happy coding and testing!
