Develop a hybrid mobile application using Rational Application Developer V8.5.1

A hands-on approach to use IBM Worklight platform for mobile application development

Gain fundamental knowledge about creating hybrid mobile applications using most commonly used technologies such as HTML5, CSS3, JavaScript,and Dojo. Explore different components of a hybrid mobile application developed using the IBM Worklight platform and rapidly develop a mobile application and test it on IBM Worklight Server to see the look and feel of a mobile application.

Share:

Hamid Kalantari (hamidk@ca.ibm.com), Staff software engineer, IBM

author photoHamid is a software engineer at IBM Toronto labs. He is the subject matter expert on web technologies and web services. He holds a Master's degree in software design and optimization from the University of Waterloo.



22 October 2013

Also available in Chinese Spanish

Introduction

Try out Rational Application Developer and IBM Worklight

IBM Rational Application Developer for WebSphere Software accelerates the development and deployment of Java, Java EE, Web 2.0, mobile, OSGi, portal and service-oriented architecture (SOA) applications.

Download IBM Rational Application Developer or use it in the cloud.

IBM Worklight helps you build, test, and deploy native, HTML5, and hybrid mobile apps for Android, iOS, BlackBerry, and Windows Phone devices.

Download Worklight to try it on your own.

Learn how to develop a hybrid mobile application using the IBM Worklight platform installed on IBM Rational Application Developer for WebSphere Software V8.5.1. IBM Worklight simplifies the development of mobile web, hybrid, and native applications across multiple mobile platforms: iOS, Android, BlackBerry, Windows phones, among others. It provides visual development capabilities based on platform and source code enhancements to help developers accelerate development, test, and delivery of mobile applications using open technologies such as HTML5, Apache Cordova, JavaScript, and popular JavaScript frameworks such as Dojo, jQuery, and Sencha Touch. By maximizing the sharing of the codebase across environments, IBM Worklight helps to reduce costs of development, time-to-market, and ongoing management efforts.

Upon completion of this article you should have a good understanding of the following tasks:

  • Setting up the IBM Worklight development environment
  • Creating an IBM Worklight project and a Worklight application
  • Understanding IBM Worklight project and "app" structure and contents
  • Exploring IBM Worklight environments (Android, iPhone, and Blackberry)
  • Creating views for the mobile application
  • Testing Android and iPhone versions in the mobile browser simulator.

Setting up the IBM Worklight development environment

To set up the development environment, install prerequisite software and start IBM Worklight Studio.

Install prerequisite software

Install the following software and plug-ins to set up the environment for your mobile app development. (See Resources for links.)

  • Rational Application Developer for WebSphere Software V8.5.1
  • IBM Worklight Consumer Edition V5.0.5
  • Android SDK V4.2.1
  • An Android SDK platform and the SDK platform tools. (Install using the Android SDK manager.)
  • ADT plug-in. (Select Developer tools from the list.)

Start IBM Worklight Studio

  1. Launch Rational Application Developer as administrator by right-clicking <RADInstallDir>\eclipse.exe > Run as administrator
  2. On the Workspace launcher dialog specify your workspace path.
  3. If you receive a welcome page, dismiss it by closing the Welcome tab.
  4. Switch to Design perspective Window > Open perspective > Other > Design.

Create an IBM Worklight project and a Worklight application

  1. Switch to Design perspective > Window > Open Perspective > Other > Design
  2. Select File > New > Worklight Project
  3. Make sure Hybrid Application is selected as the project template.
  4. Enter MyMobileApp as the project name > click Next.
  5. In the Hybrid Application panel specify the application name as MyMobileApp.
  6. Make sure the option Add Dojo Toolkit is selected > click Finish.
Figure 1. Create a new hybrid application
The wizard for creating a new hybrid application

Understand the IBM Worklight project structure and contents

The project structure is illustrated in Figure 2. It includes these components:

Worklight Server library
The Worklight API jar file
 
Server/java
Location for server-side java code in Java-based adapters (advanced)
 
JRE System library
Contains the JRE used in this project
 
JavaScript resources
Contains the project's JavaScript classes content
 
adapters
Contains the project's adapters (used for backend connectivity)
 
apps
Contains the project's applications
 
bin
Location for build artifacts (wlapp files) that are deployed to a Worklight server
 
components
Contains shell application components (advanced)
 
dojo
Contains the Dojo Toolkit JavaScript source
 
Server
Contains configuration files and extension locations for the embedded Worklight test server, including:
conf
IBM Worklight Server configuration files such as worklight.properties
 
java
Java code that must be compiled and packaged into jar files deployable to the server
 
lib
Pre-compiled libraries that must be deployed to the IBM Worklight server
Figure 2. IBM Worklight project structure and contents
Project structure and contents

Understand the IBM Worklight application structure and contents

The IBM Worklight application structure and contents are shown in Figure 3. The contents include the following:

common
The default resources common to all environments such as CSS, images, JavaScript, and HTML
 
css: /MyMobileApp.css
The main application CSS file
 
css: /reset.css
Brings all rendering engines to one common ground
 
images
Default images for the common environment
 
js: /MyMobileApp.js
The main JavaScript file for the app, message.js
 
js: /messages.js
JSON object holding all app messages
 
js: /auth.js
Authentication mechanism
 
MyMobileApp.html
The main application html file. The application can have multiple html files.
 
legal
All legal related documents such as license document for the application or third party software
 
application-descriptor.xml
The application's meta data used to define various aspects of the app i.e. security config, server url, and so on.
 
build-dojo
Artifacts related to custom dojo profile builds (advanced)
Figure 3. IBM Worklight application structure and contents
Application structure and contents

The HTML and XML files associated with the IBM Worklight application include:

MyMobileApp.html
The main application HTML file that is loaded by the device rendering engine when deployed as a hybrid application on mobile devices such as iPhone and Android.
 
application-description.xml
In the editor view, click the Source tab to review the elements of the application-description.xml file. Figure 4 shows these elements.
Figure 4. application-description.xml source view
The source view of application-description

In the application-description XML file tags include more information about the application:

<application>
The root element of the application-descriptor.xml file with two attributes:
id
Contains the ID of the application which must be identical
 
platformVersion
Contains the version of the IBM Worklight platform on which the application was developed.

 
<displayName>
Contains the name of the application
 
<description>
Contains a description for the application
 
<author>
Contains the name of the application author
 
<height> and <width>
Used for desktop environments
 
<mainFile>
Contains the name of the main HTML file for the application
 
<thumbnailImage>
Contains the path to the thumbnail image for the application

Explore the IBM Worklight environments

An environment is a mobile, desktop, or web platform that is able to render and display a web-based application. Examples of environments include the Apple iPhone, Android phones, Facebook, and iGoogle. This section covers how to create environments to provide support for iPhone and Android.

Create the IBM Worklight environment for the MyMobileApp application.

  1. In the Project Explorer select the MyMobileApp application: MyMobileApp > apps, right-click, and select New > Worklight Environment. See Figure 5.
Figure 5. Add a Worklight environment to the app
The wizard to add Worklight environment
  1. In the Worklight Environment dialog select iPhone, Android phones and tablets > Click Finish.
  2. Verify the Console window and notice the message about the environments that you have configured in your application.
  3. In the Package Explorer view verify that there are now additional folders created under the MyMobileApp application folder. See Figure 6.
Figure 6. Additional folders created for respective mobile environment
Respective folder created for added environments

The new environment's resources will have the following relationship with the common resources:

image
Override the common image in case both share the same name
 
css
Extend and/or override the common CSS files
 
js
Extends the common application instance JS object i.e. the environment class extends the common app class.
 
HTML
Override the common HTML code in case both share the same name
 
native
Contains environment specific generated application code

Quick review of the native folder for specific environments

The Android native folder contains automatically generated android application code that is imported into the workspace as an Android project during the build and deploy task that will be performed later. It is not recommended to edit files under the assets folder as each time the application is built they are regenerated.

iPhone folders include a native folder that contains automatically generated iPhone app code. In addition, the package folder contains a packaged application. It is not recommended to edit files under native/www folder as each time the app is built they are regenerated.

Build and deploy all environments

  1. Right-click the MyMobileApp application and select Run As > Build All and Deploy
  2. Check the Console log to make sure that the build and deploy is successful. See Figure 7.
Figure 7. Build and deploy all environments
The console output for build and deploy
  1. Verify that the Native Android project has been created and imported into workspace. See Figure 8. This is an example of IBM Worklight integration with the device SDKs. Since the Android SDK is Eclipse-enabled, IBM Worklight is able to immediately generate an Android project in the workspace. This is also true for BlackBerry. For other platforms such as iPhone, Worklight launch the respective non-Eclipse tooling and provide a project in that tool's format for completion, for example, Xcode.
Figure 8. Native Android project created and imported into workspace
The Android project imported into workspace

Create views for MyMobileApp application

In this section we continue developing the MyMobileApp with the rich page editor of IBM Worklight.

  1. Build two MyMobileApp application views:
    1. The main view consists of a dojo.mobile.ScrollableView with a header, a navigation button to go to the profile view, and some sample text.
    2. The profile view is also built on a dojo.mobile.ScrollableView with a button to use for launching a pop-up.
  2. Configure Rational Application Developer for Rich Page Editor (RPE) development. Ensure that both Palette and Mobile Navigation tabs are visible. The Mobile Navigation will be used to drag visual elements onto the page. If these tabs are not visible from Rational Application Developer workbench, go to Window > Show View and select them accordingly.
  3. Open the file MyMobileApp.html into the editor.
  4. Add a scrollable view to the page. See Figure 9.
    1. Ensure that the MyMobileApp.html file is active and that the design or split tab is visible. It should be noted that pages in a mobile app are built on views. As mentioned for this application, we make use of dojo.mobile.ScrollableView, which are dojo view widgets that manage a view pane.
    2. From the Palette expand the Dojo Mobile Widget section. Drag the ScrollableView widget into the design tad of the editor, in the <body> section of the MyMobileApp.html file.
Figure 9. The source view shows the code inserted into the page for ScrollableView
The ScrollableView component inserted into the page
  1. Complete the Create a new Dojo Mobile Scrollable View panel as follows:
    1. Edit the Id field and change the default name of view0 to mainView
    2. Check the Set as default view checkbox.
    3. Select the Include heading checkbox.
    4. Enter MyMobileApp as the heading label.
    5. Click Finish to complete the task.
  2. Add a second dojo.mobile.ScrollableView to the application by dragging another ScrollableView widget into the page.
    1. From Dojo Mobile Widget drawer drag ScrollableView onto the design pane
    2. Insert the ScrollableView into the body after the mainView
  3. After dragging the dropping the ScrollableView the same dialog box will appear:
    1. Enter profileView as the Id.
    2. Select the Include heading checkbox to include a heading.
    3. Enter My Profile as the Heading label.
    4. Enter Home as the Back button label.
    5. Select mainView from the Back button drop-down list. Click Finish.
  4. Open the Mobile Navigation tab and verify how you can alternate the contents of the design tab in the rich page editor by selecting which is the active mobile view.

    When we created the second the ScrollableView (the profile view,) we were given the option in the wizard to create a back button for navigation back to the MyMobileApp home screen, for example, mainView. Now we will add a toolbar button on the mainView, which will send us to the profileView and complete our navigation.

    1. In the Mobile Navigation view select the eyelid of mainView to make it the active view in the editor. See Figure 10.
      Figure 10. Select the eyelid of mainView to make it the active view
      Mobile Navigation view displaying the active view
    2. From the Dojo Mobile Widget Palette, drag a ToolBarButton to the header portion of the mainView and drop it into the heading next to "MyMobileApp" header text. See Figure 11.
Figure 11. Drag a ToolBarButton on to the header portion of the mainView
Insert a ToolBarButton into the mainView
  1. Link the new button to the profileView mobile view
    1. Select the new button, which is currently called "Label". This will appear a hovering "Link to Mobile View" icon.
    2. Click the Link to Mobile View icon to open the Link to mobile view dialog.
    3. Select the profileView from the inline mobile view pulldown.
    4. Click Finish to complete the link from this button on the mainView to the profileView.
  2. Change the button label from its default value and add some inline CSS instructions to relocate the button to the right side of the header.
    1. Right-click the ToolBarButton and select Properties from the menu. Double-click on the Properties tab to maximize the view.
    2. In the Dojo tab of the Properties view update the label with the new name Profile.
    3. Switch to the All tab within the Properties view and scroll down to the style property.
    4. Enter float:right; as the Value for the style field. Click Enter to make sure the value is accepted. This causes the button to shift to the right side of the header.

The button should be labeled Profile and should be on the right side of the header, as shown in Figure 12.

Figure 12. The button labeled "Profile" on the right hand side of the header
The profile button placed inside the header
  1. Add a RoundRect component to the mainView page
    1. From the Dojo Mobile Widgets drag a RoundRect widget into the mainView and insert it into the ScrollableView below the heading, as shown in Figure 13.
      Figure 13. Adding RoundRect into the mainView page
      Inserting RoundRect component into the mainView page
    2. Double-click the newly created RoundRect to bring it into view in the Source tab. Insert the following text between the start and ending <div> tags for the RoundRect in the Source tab.
      This is a sample application built on the IBM Worklight Platform.
  2. Add a button to the profileView. This button will be used to launch a pop-up dialog box.
    1. In the Mobile Navigation view click on the eye icon to change the active view to profileView.
    2. Drag a Button from the Palette and drop it into the profileView below the heading.
    3. In the Properties page of the Button change to the All tab and enter Click me! as the label.
    4. In the same Properties page enter "onclick" in the filter field to shorten the property list.
    5. In the onclick property add the following function as the value:

      loadSimpleDialog('Button clicked on My Profile!')
  3. Add a Container (<div>) to the mainView
    1. Use the Mobile Navigation tab to bring the mainView back to the foreground of design tab.
    2. Add a Container to the mainView by dragging the Container widget from the Dojo Mobile Widgets palette and inserting into the ScrollableView before the RoundRect, as shown in Figure 14.
Figure 14. Adding ScrollableView to the mainView page
Inserting ScrollableView into the mainView page
  1. Add a class name to the Container so we can apply CSS instructions for margins.
    1. Select the dojo.mobile.Container line in the Source pane, as shown in Figure 15.
      Figure 15. Source view shows the code for "dojo.mobile.Container" component
      The code line inserted for container component
    2. Switch to the Properties view and ensure that the Container element is displayed.
    3. Switch to the Styles tab within the Properties view.
    4. Enter spacer as the value for the Class property. The CSS file will have a reference for the class named "spacer," which this container will inherit.
  2. Add a Container to the profileView:
    1. Use the Mobile Navigation tab to bring the profileView back to the foreground of design tab
    2. Add a Container to the profileView by dragging the Container widget from the Dojo Mobile Widgets palette and insert it into the ScrollableView before the Button.
  3. Add a class name to the Container so we can apply CSS for margins.
    1. Select the dojo.mobile.Container line in the Source pane, as shown in Figure 16.
      Figure 16. The source view shows the code for "dojo.mobile.Container" component
      The code line inserted for container component
    2. Switch to the Properties view and ensure that the Container element is displayed.
    3. Switch to the Styles tab within the Properties view.
    4. Enter spacer as the value for the Class property. The CSS file will have a reference for the class named "spacer," which this container will inherit.
  4. Add CSS to MyMobileApp.css to provide a branded look to the app, overriding defaults. This action will give a more consistent experience across different devices.
    1. In the Project Explorer view open /MyMobileApp/apps/MyMobileApp/common/css/MyMobileApp.css
      Enter the code from the Listing 1 into the bottom of the CSS file:
Listing 1. The casecase style sheet to override the defaults
.spacer {
    margin-top: 100px;
}
.mblView {
    background: -webkit-gradient(linear, left top, left bottom, from(#096093), to(#ffffff)) !important!
}
.mblHeading {
    background: -webkit-gradient(linear, left top, left bottom, from(#379AC4), to(#096193)) !important!
}
.mblToolBarButtonBody {
    background-image: -webkit-gradient(linear, left bottom, left top, color-stop(0, #0B0B0D), 
color-stop(1, #434949)) !important!
}
.mblArrowButtonBody {
    background-image: -webkit-gradient(linear, left bottom, left top, color-stop(0, #0B0B0D), 
color-stop(1, #434949)) !important!
}
.mblArrowButtonHead {
    background-image: -webkit-gradient(linear, left bottom, left top, color-stop(0, #0B0B0D), 
color-stop(1, #434949)) !important!
}
  1. Add the JavaScript function to implement the dialog pop up.
    1. In the project Explorer view, open the MyMobileApp.js by navigating to MyMobileApp/apps/MyMobileApp/common/js/MyMobileApp.js
    2. Enter the function code from Listing 2 into the bottom of MyMobileApp.js
Listing 2. JavaScript function to implement the dialog pop-up
function loadSimpleDialog(dialogText) {
	WL.SimpleDialog.show('Hello!', dialogText, [ {
		text : 'Dismiss',
		handler : function() {
			WL.Logger.debug("button pressed");
		}
	} ]);

}

This function accepts a string from the caller dialogText and invokes the Worklight common control WL.SimpleDialog.show(), which passes a title for dialog, the text to display in the dialog, and details about the dismiss button, which offers the ability to call a function as the dialog is dismissed.

Your mobile pages should look like the following figures when you save all of changes. Figure 17 shows the mainView and Figure 18 shows the profileView.

Figure 17. The mainView page displayed in the design pane for Apple iPhone 4s
The mainView page look and feel
Figure 18. The profileView page displayed in the design pane for Apple iPhone 4s
The profileView page look and feel

The mobile browser simulator test

To test the MyMobileApp application, use the mobile browser simulator for development time rendering in an integrated, device-specific container. Preview the iPhone environment in the mobile browser simulator:

  1. In the Project Explorer view expand MyMobileApp/apps/MyMobileApp and right-click iPhone environment > Run As > Preview
  2. View the preview to determine how the application and navigation work in the iPhone environment.

Summary

In this article you developed a hybrid mobile application with IBM Worklight Studio development environment installed on Rational Application Developer V8.5.1 platform. You used cross platform techniques such as HTML5, CSS3, JavaScript, and the Dojo mobile framework. You developed some fundamental knowledge on how mobile pages are built and connected and how you can make use of drag-and-drop components from the Palette view to rapidly create your mobile page. Also, you deployed your mobile application to IBM Worklight server embedded in your Rational Application Developer V8.5.1 platform to see the look and feel of your mobile application in different native environments such as iPhone and Android.

Acknowledgment

The author would like to thank Ali Manji for reviewing this article.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational, Mobile development
ArticleID=949354
ArticleTitle=Develop a hybrid mobile application using Rational Application Developer V8.5.1
publish-date=10222013