Deliver an exceptional mobile web experience using WebSphere Portal and IBM Worklight V5.0, Part 1: Integrating a hybrid mobile application with WebSphere Portal pages

IBM WebSphere Portal and IBM’s Exceptional Web Experience solutions have been the market leader in web experience for more than a decade. IBM Worklight is a new, complete mobile enterprise application platform for delivering native, hybrid, and web applications. This article explains how WebSphere Portal and Worklight together enable enterprise users to provide multi-channel site support to their web communities. An exercise using IBM Worklight Developer Edition 5.0 to build a hybrid Android application for viewing WebSphere Portal pages is included.

This article applies to IBM Worklight V5.x. Another version of this article is available for IBM Worklight V6.0.

Share:

Jaye Fitzgerald (jaye@us.ibm.com), Technical Lead for Mobile Portal Accelerator, IBM

Jaye Fitzgerald is the technical lead for Mobile Portal Accelerator at IBM's Littleton Development Lab. He has contributed to Portal's mobile products and has delivered consulting services as a member of the WebSphere Portal lab services team. Jaye has presented WebSphere Portal's mobile offerings at Lotusphere and the IBM Exceptional Web Experience Conferences.



Jonathan Lidaka, WebSphere Portal Front-end Engineer, IBM

Jon Lidaka is a Front-end engineer based at IBM's Research Triangle Park Development Lab.During his time in Portal development he has primarily contributed to theme development, focusing on accessibility and globalization, and to various components including the administration portlets and Web application integrator. Currently he leads the mobile development mission for Portal. Jon has spoken at multiple IBM conferences on user interface design and optimizing Portal themes for mobile devices.


developerWorks Contributing author
        level

07 August 2013 (First published 29 August 2012)

Also available in Chinese Russian Japanese Portuguese Spanish

Introduction

The mobile channel has become a critical and strategic channel for sales, marketing, and more for many – if not most industries. As businesses manage their company’s brand through web sites, a common challenge has become how to deliver content and applications to mobile devices.

Before looking at the intersection of IBM WebSphere Portal and IBM Worklight, it's important to understand the difference between a website and an application:

  • A website aggregates web content and multiple web applications into a single user experience and works across multiple channels, including desktop browser, kiosk, smartphones, and tablets. A simple example might be your favorite airline’s website. They probably have a mobile website, too, which supports phones and tablets. WebSphere Portal is the right platform for building a website.
  • A web application is custom-built and often targets specific tasks. For example, your favorite airline app from an app store that lets you book a flight or reserve a seat is an example of a web application. It usually contains a subset of the website’s features, targeted to what you can practically do on the device. IBM WebSphere Application Server is the right option for delivering standalone web applications. IBM Worklight provides the ability to create both native and hybrid applications, and you can use either WebSphere Application Server as the back end (if you are creating hybrid apps), or WebSphere Portal as the back end (if you are creating hybrid websites).

The choices, then, come down to developing a native application, a hybrid application, or a web application. But there are two questions that need to be answered that will influence your mobile channel technology decision:

  1. What devices will you need to support?
  2. What is your application going to do?

Underlying considerations to help you answer these include things like: What are your use cases? Will your application require specific device features, such as GPS or the camera? Does the application require high fidelity screen views or is the mobile browser sufficient? Answers to these questions are essential to this decision, as are the pros and cons of native versus hybrid versus pure web:

  • Native applications for enterprise mobile apps have a very high cost, and a lengthy timeline associated with pure native development. Skilled resources able to develop 100% native applications are difficult to find and can be expensive. Complex native applications could require several technical professionals, and cross-platform issues can further increase costs. Beyond initial development, continuous operating system updates require continuous application updates, which must be resubmitted for approval to get them back in app stores.
  • In contrast, full web applications based on HTML5, CSS3, and JavaScript™, or that use client side frameworks like Dojo and jQuery, provide a simple way to make mobile-friendly websites. Development costs are typically much lower, because general web UI skills are easier to find. Updates to device operating systems don't typically affect mobile web sites, which can be developed such that they work across vender devices. Web applications built with these common web standards also enable reuse of the code across a variety of devices, and reduce maintenance and total cost of ownership. Additionally, you don't have to worry about app store review processes or limitations that can delay or stop updates.

    The two main drawbacks to this approach are:

    • You only have access to native features that the browser provides to you. For example, on iOS devices, you have access to the potentiometer, accelerometer, and GPS, but not the camera.
    • You can only do graphically what is possible in HTML/CSS/JavaScript. As a result, some fidelity and UI features that are available to you in the native space are not available in the browser space.
  • Hybrid applications give you the best of both worlds. You get the simplicity of developing with HTML/CSS/JavaScript, but you can augment that with native services and produce an app for the app stores. With technology like Apache Cordova (which Worklight uses and ships), you can call native features with JavaScript from your web markup. For example, you can call the camera using a simple JavaScript line, such as: navigator.camera.takeSnapshot.

Sample solution

This article outlines the steps for building a sample solution that integrates Worklight 5.0 and WebSphere Portal 8.0 through a hybrid application. This section looks at the components involved in this solution and related prerequisites you will need to perform these steps.

Components

  • Worklight

    The Worklight platform includes a set of components that enable you to manage the complete lifecycle of native, hybrid, and web applications, delivered to multiple mobile platforms, including iOS, Android, BlackBerry, and Windows® Phone. IBM Worklight Developer Edition 5.0 is a powerful and flexible mobile integrated development environment that you can download and use at no cost. Worklight Developer Edition is used here to build the sample application that accesses WebSphere Portal.

  • WebSphere Portal

    WebSphere Portal is the market leader in delivering a website framework for both desktop and mobile devices. WebSphere Portal provides site navigation and branding so you can customize your site for your business. The framework delivers targeted content with analytics to measure your site's effectiveness. Role-based access and context-driven content are other key features. WebSphere Portal's strengths derive from its foundation of WebSphere Application Server. WebSphere Portal has a rich list of features that include security, integrated web content management, content targeting, virtual portals, and more. WebSphere Portal's greatest value is the ability to aggregate applications on your site with this backdrop of features.

  • Responsive web design

    Creating an exceptional web experience that is optimized across multiple devices is essential for today's business. Users now expect to be able to browse the web on their smartphones just as easily as they browse the web on a desktop computer. However, targeting mobile devices usually starts with a conversation about native applications. As mentioned earlier, these applications have a high cost of ownership and code reuse is limited. Another solution has been to create an alternate website specifically for a mobile device, which is not an especially practical solution because you could end up with many code resources to maintain.

    Responsive web design (see Resources) is a practical solution to the shifting landscape of devices and screen sizes by creating flexible, fluid and adaptive web sites. Using responsive web design concepts provides a way for the user interface to optimize automatically for screen resolution, orientation, or capabilities for both rich web applications and hybrid applications. This will ensure you get the most out of your web design effort.

  • Topology choices

    You will encounter server topology options when planning your Worklight and WebSphere Portal deployment. A proxy will be required for IBM Worklight Server to access WebSphere Portal. This sample was tested with the WebSphere Portal and Worklight servers co-located on the same development machine; Listing 3 shows that the IP address in the WebSphere Portal URL is used to access the initial page. You need a proxy to deploy this sample when the servers are on different systems. Module 45 in theGetting started with IBM Worklight documentation discusses how to use a remote website, such as one hosted on a WebSphere Portal server.

Other IBM products could also fit your needs for building web or hybrid applications. For example, IBM Rational® Application Developer and IBM Web Experience Factory are other options for application development.

Prerequisites

To build the sample mobile hybrid application described here, you must have these software products and features properly installed and operational:

  • WebSphere Portal 8.0

    See the WebSphere Portal documentation for installation instructions.

  • Eclipse

    Download Eclipse. This sample is based on Eclipse 3.7.2 (Indigo), and was tested with Eclipse IDE for Java™ EE Developers. (The Eclipse Classic and Eclipse IDE for Java Developers might work also, although they have not been tested with this sample.)

Be aware that the application described here will only work with Android devices. Subsequent installments in this series will address Worklight integration with both Android and iOS operating systems.

  • Android SDK

    With Eclipse installed, your next step is to add the Android SDK. This sample was tested with Android SDK 2.3.3 (API 10).

    Oracle Java JRE is a prerequisite for the Android SDK. Once installed, you can configure your Eclipse instance to use the JRE by navigating to Window > Preferences > Java > Installed JREs (Figure 1).

    Figure 1. Set the Oracle JRE in Eclipse
    Figure 1. Set the Oracle JRE in Eclipse
  • Worklight

    This sample requires IBM Worklight 5.0 or later and will not work with earlier versions. You can download IBM Worklight Developer Edition 5.0 for development use at no cost. Details on how to update Eclipse with the plugin are available in the Setup modules of the Getting started with IBM Worklight documentation.

    Worklight installs the server as part of Eclipse. You may need to update eclipse.ini to change the port from 8080 to another value, such as 8085. The Worklight server automatically starts when you start Eclipse. Listing 1 shows an example eclipse.ini file content with -Dworklight_port set.

    Listing 1. eclipse.ini
    -startup
    plugins/org.eclipse.equinox.launcher_1.2.0.v20110502.jar
    --launcher.library
    plugins/org.eclipse.equinox.launcher.win32.win32.x86_64_1.1.100.v20110502
    -showsplash
    org.eclipse.platform
    --launcher.XXMaxPermSize
    256m
    --launcher.defaultAction
    openFile
    -vmargs 
    -Dworklight.port=8085
    -Xms40m
    -Xmx384m
  • WebDAV client

    To update the WebSphere Portal theme with Worklight JavaScript, you need a WebDAV client. This sample was developed using AnyClient. You can use any WebDAV client that WebSphere Portal supports. See Connecting to the Portal WebDAV with 8.0 for details.

  • Custom theme

    You need to create your own custom theme before applying Worklight JavaScript to your theme. Copying the WebSphere Portal theme ensures that your theme contains all the required elements it needs to function, and that your changes will not be overwritten by a fixpack. Do not modify the WebSphere Portal theme directly because it can be updated by service fixpacks. Instead, follow the instructions in this article to create a copy of the theme.


Create the Worklight application

  1. Start Eclipse. Notice in the Worklight console that the server started (Figure 2).
    Figure 2. Worklight server started
    Figure 2. Worklight server started
  2. To begin building the application, you need to create a new Worklight project. From Eclipse, navigate to New > Other > Worklight Project, then click Next (Figure 3).
    Figure 3. Create a new Worklight project
    Figure 3. Create a new Worklight project
  3. Name your project. In Figure 4, the project is called WLPortal. Keep Hybrid Application selected as the default and click Next.
    Figure 4. Name your Worklight project
    Figure 4. Name your Worklight project
  4. Name the hybrid application in the Worklight project, in this case WLPortalApp. There is no JavaScript package in this sample, but you have the option to add one on this panel (Figure 5).
    Figure 5. Name the hybrid application
    Figure 5. Name the hybrid application
  5. Click Finish. The project and application artifacts are created. This might take a few minutes. When completed, you might be asked to switch to the Design perspective and view the project in the Project Explorer (Figure 6).
    Figure 6. Project displayed in Eclipse
    Figure 6. Project displayed in Eclipse
  6. Next, you want to create a Worklight environment to build the hybrid application. Right click on the WLPortalApp in the apps folder, then select New > Worklight Environment (Figure 7).
    Figure 7. Create a new Worklight environment
    Figure 7. Create a new Worklight environment
  7. The New Worklight Environment panel displays (Figure 8). Because this particular sample is for a hybrid Android application only, select Android phones and tablets. If you needed to create environments for other device operating systems, this is the panel where you would specify those additional options. Click Finish.
    Figure 8. Worklight environment displayed in Eclipse
    Figure 8. Worklight environment displayed in Eclipse
  8. Worklight Studio builds and updates the project with a native application (Figure 9). The native project is named Worklight Project/WorklightApplication/Platform. Worklight Studio manages the lifecycle of this application, and you shouldn't make any changes to it. When the web application you initially created in the project is built and deployed, the native application will be overwritten with any application changes.
    Figure 9. The native app is built
    Figure 9. The native app is built
  9. Now that you've got the application set up, verify that it will build and deploy. As you can see in Figure 10, the Build All and Deploy command means the native application will be redeployed based on the web application changes. You can execute the Build All and Deploy command by right-clicking on the application and selecting Run As > Build All and Deploy.
    Figure 10. Selecting build and deploy
    Figure 10. Selecting build and deploy

    As the build process begins, you can see the progress in the lower right status banner in Eclipse. When the process completes, you should see the message Application 'YourApp' deployed successfully with all environments in the Worklight console (Figure 11).

    Figure 11. Success message displayed in log
    Figure 11. Success message displayed in log

Create an Android Virtual Device before you try to run your new Android application. See this article on using hardware devices for details about AVDs.

  1. To run the Android application, right-click on the WLPortalWLPortalAppAndroid project in the Project Explorer and select Run As > Android Application. This launches the Android Emulator (if not already running) and loads a new application instance. You might have to open the initial emulator screen to see the application. Figure 12 shows a view of the application you've built.
    Figure 12. Application rendered in emulator
    Figure 12. Application rendered in emulator

Next, you will add code to your application to call a WebSphere Portal page.


Update the WebSphere Portal theme with Worklight JavaScript

  1. The first step to integrating WebSphere Portal and Worklight is to display the portal within the Android application. To do this, create a hybrid application that connects to WebSphere Portal within the native wrapper. In Eclipse, open the Java class that initializes the application (Listings 2a and 2b), located at \WLPortal\apps\WLPortalApp\android\native\src\com\WLPortalApp\WLPortalApp.java.
    Listing 2a. WLPortalApp.java in Worklight version 5.0.5
    package com.WLPortalApp;
    
    import android.os.Bundle;
    
    import com.worklight.androidgap.WLDroidGap;
    
    public class WLPortalApp 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());
    	}		
    	}
    Listing 2b. WLPortalApp.java in Worklight version 5.0.6
    package com.WLPortalApp ;
    
    import android.os.Bundle;
    
    import com.worklight.androidgap.WLDroidGap;
    
    public class WLPortalApp extends WLDroidGap {
    	
    	@Override
    	public void onCreate(Bundle savedInstanceState){
    		super.onCreate(savedInstanceState);
    	}
    	
    	/**
         * onWLInitCompleted is called when the Worklight runtime 
         * framework initialization is complete
         */
    	@Override
    	public void onWLInitCompleted(Bundle savedInstanceState){
    		super.loadUrl(getWebMainFilePath());
    		// Add custom initialization code after this line
    	}
    }

The IP address in this example should be the address of the WebSphere Portal server you want to render in the hybrid application. See the Sample solution components section for more information on the Worklight and WebSphere Portal installation.

  1. The application uses the class shown in Listings 2a and 2b to forward control to the HTML page located at \WLPortal\apps\WLPortalApp\common\WLPortalApp.html. You need to change this file so that it forwards to the WebSphere Portal IP address and port. To do this in Worklight version 5.0.5, you can change the onCreate method to load the WebSphere Portal URL and utilize the cookie manager (Listing 3a). In version 5.0.6 you will change the onWLInitCompleted method (Listing 3b).
    Listing 3a. onCreate method utilizing the WebSphere Portal URL in Worklight version 5.0.5
    public void onCreate(Bundle savedInstanceState) {
    	   super.onCreate(savedInstanceState);
    	   CookieSyncManager.createInstance(appView.getContext());
    	   CookieManager.getInstance().removeSessionCookie();
    	   super.loadUrl("http://9.99.999.999:10039/wps/portal",false);
    	   }
    Listing 3b. onCreate method utilizing the WebSphere Portal URL in Worklight version 5.0.6
    public void onWLInitCompleted(Bundle savedInstanceState){
    		CookieSyncManager.createInstance(appView.getContext());
    		CookieManager.getInstance().removeSessionCookie();
    super.loadUrl("http://9.99.999.999:10039/wps/portal",false);
    }
  2. Make sure to add the import dependencies for the CookieSyncManager and CookieManager shown in Listing 4.
    Listing 4. CookieSyncManager and CookieManager dependencies
    import android.webkit.CookieSyncManager;
    import android.webkit.CookieManager;
  3. Because of the redirects, you need to define one other method to get authenticated pages to work, shown in Listing 5. The result of these updates is shown in Listings 6a and 6b.
    Listing 5. Add this loadUrl method
    public void loadUrl(String url) {
    	loadUrl(url,false);
    	}
    Listing 6a. The final contents of WLPortalApp.java in Worklight version 5.0.5
    package com.WLPortalApp;
    
    import android.os.Bundle;
    import android.webkit.CookieSyncManager;
    import android.webkit.CookieManager;
    
    import com.worklight.androidgap.WLDroidGap;
    
    public class WLPortalApp extends WLDroidGap {
    	@Override
    	public void onCreate(Bundle savedInstanceState) {
    		   super.onCreate(savedInstanceState);
    		   CookieSyncManager.createInstance(appView.getContext());
    		   CookieManager.getInstance().removeSessionCookie();
    		   super.loadUrl("http://9.99.999.999:10039/wps/portal",false);
    	}	
    	
    	public void loadUrl(String url) {
    		loadUrl(url,false);
    	}
    	}
    Listing 6b. The final contents of WLPortalApp.java in Worklight version 5.0.6
    package com.WLPortalApp ;
    
    import android.os.Bundle;
    import android.webkit.CookieSyncManager;
    import android.webkit.CookieManager;
    
    import com.worklight.androidgap.WLDroidGap;
    
    public class WLPortalApp extends WLDroidGap {
    	
    	@Override
    	public void onCreate(Bundle savedInstanceState){
    		super.onCreate(savedInstanceState);
    	}
    
    	@Override
    	public void onWLInitCompleted(Bundle savedInstanceState){
    		CookieSyncManager.createInstance(appView.getContext());
    		CookieManager.getInstance().removeSessionCookie();
    	super.loadUrl("http://9.99.999.999:10039/wps/portal",false);
    	}
    	
    	public void loadUrl(String url) {
    		loadUrl(url,false);
    	}	
    }
  4. To ensure that all links are opened with the hybrid container web view, set the stay-in-webview preference in cordova.xml for Worklight version 5.0.5, located at \WLPortal\apps\WLPortalApp\android\native\res\xml\cordova.xml; for version 5.0.6, the file is called config.xml located at \WLPortal\apps\WLPortalApp\android\native\res\xml\config.xml. To this:

    <preference name="stay-in-webview" value="true" />

    If you are using a non-local portal server, then you can modify the security policy in this location as well. The default security policy is to block all network access. You can then declare access to specific network domains and subdomains within cordova.xml. This article provides more information.

  5. You can now right-click on the application again and select Build All and Deploy. You will see the progress in the lower right status banner of Eclipse. When the process completes, right-click on WLPortalWLPortalAppAndroid and select Run As... > Android Application. This launches the Android Emulator, and the application displays your WebSphere Portal, shown in Figure 13.
    Figure 13. Emulator running application displaying WebSphere Portal
    Figure 13. Emulator running application displaying WebSphere Portal
  6. At this point, you need your custom theme, based on the WebSphere Portal 8.0 theme that you created earlier. You will need to use a WebDAV utility to:
    • Update the theme template (theme.html).
    • Copy Worklight JavaScript files to the theme.
    • Create modules that will be defined in a new theme profile.

    Start your WebDAV utility (we used AnyClient for this sample) and connect to the fs-type1 entry point. When it loads, it displays the folder structure shown in Figure 14.

    Figure 14. WebDAV folder structure for fs-type1
    Figure 14. WebDAV folder structure for fs-type1
  7. Navigate to your custom theme; for example, fs-type1:themes/<customTheme>. Create a folder named worklight within your custom theme (Figure 15).
    Figure 15. The worklight folder has been created
    Figure 15. The worklight folder has been created
  8. Locate the JavaScript files in Eclipse for the Worklight libraries that you will load in WebSphere Portal. These folders are named wlclient and common, and you can find them at: \WLPortal\apps\WLPortalApp\android\native\assets\www\default\. Copy both the wlclient and common folders into the worklight folder you created on WebDAV.
  9. Open the main HTML file that the application loaded before you inserted the WebSphere Portal URL, at \WLPortal\apps\WLPortalApp\android\native\assets\www\default\WLPortalApp.html. There are two parts in this file that you need to integrate into WebSphere Portal, because the application doesn't use this file anymore.
    • The first is the static JavaScript file included in the <head> element (Listing 7).
      Listing 7. Static JavaScript included in the head element of WLPortalApp.html
      <script type="text/javascript">
          // Define WL namespace.
          var WL = WL ? WL : {};
      
          /**
      
           * WLClient configuration variables.
      
           * Values are injected by the deployer that packs the gadget.
      
           */
      
          WL.StaticAppProps = {
          "APP_DISPLAY_NAME": "WLPortalApp",
          "APP_LOGIN_TYPE": "never",
          "APP_SERVICES_URL": "\/apps\/services\/",
          "APP_VERSION": "1.0",
          "ENVIRONMENT": "android",
          "LOGIN_DISPLAY_TYPE": "embedded",
          "LOGIN_REALM": null,
          "WORKLIGHT_ROOT_URL": "\/apps\/services\/api\/WLPortalApp\/android\/"
      };</script>
    • The second is the onload set on the <body> element, which initializes the Worklight client (Listing 8).
      Listing 8. The onload method set on the body to initialize the Worlight JavaScript
      <body id="content" onload="WL.Client.init({})" style="display: none">

    Both of these sections must be included in the theme as artifacts of a module. Take the JavaScript from this HTML file and include it in a usable fashion within individual JavaScript files. Create two new files in the <customTheme>/worklight/common/js folder of the Worklight library, named init.js and staticprops.js (Figure 16) at: fs-type1:themes/<customTheme>/worklight/common/js/.

    Figure 16. New files init.js and staticprops.js are created
    Figure 16. New files init.js and staticprops.js are created
  10. Copy the staticprops.js file that you just created to your local machine and open the file (Listing 9). Copy the static JavaScript from the HTML page into this file.
    Listing 9. Contents of the staticprops.js file
    var WL = WL ? WL : {};
    WL.StaticAppProps = {
        "APP_DISPLAY_NAME": "WLPortalApp",
        "APP_LOGIN_TYPE": "never",
        "APP_SERVICES_URL": "\/apps\/services\/",
        "APP_VERSION": "1.0",
        "ENVIRONMENT": "android",
        "LOGIN_DISPLAY_TYPE": "embedded",
        "LOGIN_REALM": null,
        "WORKLIGHT_ROOT_URL": "\/apps\/services\/api\/WLPortalApp\/android\/"
    };

    Copy the updated staticprops.js file back to the <customTheme>/worklight/common/js folder on WebDAV.

  11. Copy the init.js file that you just created to your local machine and open the file (Listing 10). The i$ API, which is included in the WebSphere Portal theme, is used here to create an onload function that replaces the inline onload set in the HTML page.
    Listing 10. Contents of the init.js file
    i$.addOnLoad(function(){	
    	WL.Client.init({});
    });

    Copy the init.js file back to the <customTheme>/worklight/common/js folder on WebDAV.

    See the WebSphere Portal 8.0 Javadocs for more on the i$ API, and the WebSphere Portal wiki for more on creating modules using the theme optmization framework.

  12. The last artifact that you need to create before defining the new theme modules is the sample that tests the Worklight JavaScript. This sample tests to make sure the Cordova API is available within the WebSphere Portal theme, and is based on the example set in the Cordova API.

    Because this sample is intended to only test the API use in WebSphere Portal, and the re-use value is therefore limited, there is no need to create a module for the sample code. Place the code snippet directly into the theme template, then copy the localized theme template to your machine. The theme template is on WebDAV located in the custom theme fs-type1:themes/<customTheme>/nls/theme_en.html (Figure 17).

    Figure 17. The localized theme template to add sample code
    Figure 17. The localized theme template to add sample code
  13. Open the theme template and find the <a rel="dynamic-content" href="co:config"></a> dynamic content element, located towards the bottom of the template. Place the deviceready example from the Cordova API after this dynamic content spot, as shown in Listing 11.
    Listing 11. Sample for testing Cordova API in WebSphere Portal
    <div class="wpthemeComplementaryContent" 
            id="wpthemeComplementaryContent" 
    		role="region" 
    		aria-labelledby="wpthemeComplementaryContentText">
      <span class="wpthemeAltText" id="wpthemeComplementaryContentText">
    	Complementary Content
      </span>
      <a rel="dynamic-content" href="co:config"></a>
      <script type="text/javascript">
      document.addEventListener("deviceready", onDeviceReady, false);
      function onDeviceReady() {	
            var element = document.getElementById('deviceProperties');
            element.innerHTML = 'Device Name: '     + device.name + '<br/>' + 
                                'Device Version: '  + device.version;
      }
      <script>
    </div>
  14. After the JavaScript is in place to test Cordova, you need to insert an element within the theme template that will show the device info. Directly underneath the <body> element, place an element with an id of "deviceProperties" in the theme template. Listing 12 shows an example.
    Listing 12. Device properties element in theme template
    <p id="deviceProperties">Loading device info</p>
  15. While you have the theme template open, add an id to the <body> element with the value "content" (Listing 13) This is required by the Worklight init method.
    Listing 13. Add new ID to the body element
    <body id="content" class="lotusui30dojo tundra locale_en">
  16. Now that the items from the HTML page and a sample for testing the Worklight JavaScript are included as individual files in the theme, you can define them as artifacts in new modules. To do this, register new theme contributions as a JSON configuration file in the contributions folder under the custom theme in WebDAV. The system automatically scans the files in this folder and the contributions defined are registered for the theme that defines them. (To learn more about creating theme specific contributions, see Registering theme specific contributions.)
    1. Open the contributions folder under your custom theme and create a file named worklight.json. This file should define two new modules for each of the following:
      • Worklight JavaScript library files
      • Worklight initialization onload

      These two modules will be identified as wl_client and wl_init, respectively.

    2. Copy the worklight.json file to your local machine and place the contents of Listing 14 into this file.
      Listing 14. Contents of the worklight.json file
      {
         "modules":[{
            "id":"wl_client",
            "contributions":[{
               "type":"config",
                  "sub-contributions":[
                  {
                     "type":"js",
                     "uris":[{"value":"/worklight/common/js/staticprops.js"}]
                  },
                  {
                     "type":"js",
                     "uris":[{"value":"/worklight/wlclient/js/cordova.js"}]
                  },
                  {
                     "type":"js",
                     "uris":[{"value":"/worklight/common/js/wljq.js"}]
                  },
                  {
                     "type":"js",
                     "uris":[{"value":"/worklight/common/js/base.js"}]
                  },
                  {
                     "type":"js",
                     "uris":[{"value":"/worklight/wlclient/js/messages.js"}]
                  },
                  {
                     "type":"js",
                     "uris":[{"value":"/worklight/common/js/wlcommon.js"}]
                  },				
                  {
                     "type":"js",
                     "uris":[{"value":"/worklight/wlclient/js/diagnosticDialog.js"}]
                  },
                  {
                     "type":"js",
                     "uris":
                        [{"value":"/worklight/wlclient/js/deviceAuthentication.js"}]
                  },
                  {
                     "type":"js",
                     "uris":[{"value":"/worklight/wlclient/js/window.js"}]
                  },
                  {
                     "type":"js",
                     "uris":[{"value":"/worklight/wlclient/js/worklight.js"}]
                  },
                  {
                     "type":"js",
                     "uris":[{"value":"/worklight/wlclient/js/wlclient.js"}]
                  },
                  {
                     "type":"js",
                     "uris":[{"value":"/worklight/wlclient/js/wlfragments.js"}]
                  },
                  {
                     "type":"js",
                     "uris":[{"value":"/worklight/wlclient/js/encryptedcache.js"}]
                  },
                  {
                     "type":"js",
                     "uris":[{"value":"/worklight/wlclient/js/checksum.js"}]
                  },
                  {
                     "type":"js",
                     "uris":[{"value":"/worklight/wlclient/js/wlgap.android.js"}]
                  }]
              }]
         },
         {
            "id":"wl_init",
            "prereqs":[{
               "id":"wl_client"
            },{
               "id":"wp_client_main"
            },{
               "id":"wp_client_ext"
            }],
            "contributions":[{
               "type":"config",
               "sub-contributions":[{
                  "type":"js",
                  "uris":[{
                     "value":"/worklight/common/js/init.js"
                  }]
               }]
            }]
         }
         ]
      }
    3. Copy the worklight.json file back to the <customTheme>/contributions folder on WebDAV.
  17. The Worklight JavaScript libraries are now defined into theme modules. The sample to test the JavaScript was directly placed into the theme template so it could be easily removed after testing, but no module is required in the profile for the sample code. The last step is to take the modules and define them in a theme profile. Create a new profile by opening the lightweight profile located in the custom theme at fs-type1:themes/<customTheme>/profiles/profile_lightweight.json. Copy this file to your local machine and rename it to profile_worklight.json.
  18. Open the profile_worklight.json file and add the modules wl_client and wl_init that you defined as contributions (Listing 15).
    Listing 15. Example of the module ID array defined in the profile
    "moduleIDs": [
    		"wp_theme_portal_80",
    		"wp_portlet_css",
    		"wp_one_ui",
    		"wp_one_ui_dijit",
    		"wp_legacy_layouts",
    		"wp_client_ext",
    		"wp_status_bar",
    		"wp_theme_menus",
    		"wp_theme_skin_region",
    		"wp_theme_high_contrast",
    		"wp_layout_windowstates",
    		“wl_client”,
    		“wl_init”
    	],
  19. Rename the profile so you can easily identify it when selecting in the page properties dialog. To do this, find the English title (or the locale you plan to work with) and change the title from “Lightweight” to “Worklight” (Listings 16 and 17).
    Listing 16. Profile title before the change
    {
    	"value":"Lightweight",
    	"lang":"en"
    },
    Listing 17. Profile title after the change
    {
    	"value":"Worklight",
    	"lang":"en"
    },
  20. Copy the profile_worklight.json file back to the <customTheme>/profiles/ directory on WebDAV. Clear the browser cache and restart WebSphere Portal to make sure the new profile is enabled.

    All of the theme artifacts required for applying the the IBM Worklight JavaScript in WebSphere Portal are in place. You can now take the profile that has defined the modules to include the Worklight artifacts and apply it to a page. Create a page with your custom theme applied if you have not already done so. (See Page creation and navigation for more about creating pages.)

    There are two ways you can apply the profile to the page and view your changes for Worklight. You can either:

    • Set the profile as the theme default.
    • Set it specifically for a particular page.

    Either way will work so you can see your changes, but setting the profile on a particular page is the easiest. To do this, open the Page Properties dialog that is available within the customization shelf and find the drop down menu for available theme profiles on the Advanced tab (Figure 18). (See Changing the theme profile for more information.)

    Figure 18. The profile menu in the page properties dialog
    Figure 18. The profile menu in the page properties dialog

Test the hybrid application with the Android Emulator

Now that you have applied the profile to a WebSphere Portal page, you can test the sample using the Android Emulator:

  1. Once again, build and deploy the application by right-clicking on the application and selecting Build All and Deploy. You can see the progress in the lower right status banner in Eclipse.
  2. When the process completes, right-click on WLPortalWLPortalAppAndroid and select Run As... > Android Application. This will launch the Android Emulator and the application will display your WebSphere Portal.
  3. After the application has rendered the WebSphere Portal application, if the new page to which you applied the Worklight profile does not have anonymous access, then login and navigate to the page. This will take a few seconds for the device settings to load, but you will see them appear at the top of the page, as shown in Figure 19.
    Figure 19. Worklight application displaying device information in WebSphere
    Figure 19. Worklight application displaying device information in WebSphere

Conclusion

IBM Worklight makes it easy to enable multi-channel web applications to interact with the device and device delivery channels. The Worklight shell is a thin layer of native client code on the device that handles things like authentication, security, application launch, and notifications, and can be tailored to the specific needs of an organization or business. The shell serves to launch the web content (the real meat of the application). IBM WebSphere Portal can aggregate portlets that include mark up that leverage Worklight native services along with other portlets. To do this, the Worklight shell is delivered in its standard manner and points to the WebSphere Portal-managed websites. The Worklight shell can also be packaged into a deliverable that can be published in an app store or deployed via MDM, if needed. The result is that you get the full WebSphere Portal multi-channel website management capabilities extended to include native device services.

Subsequent articles in this series will look at leveraging native capabilities within your WebSphere Portal theme, configuring authentication between Worklight and WebSphere Portal, providing native integration to your device social services via Worklight and web content management, and augmenting your IBM Rational Application Developer and IBM Web Experience Factory portlets using Worklight.


Downloads

DescriptionNameSize
Sample portal theme filesWLPortalApp-theme_files.zip8 KB
Sample applicationWLPortalApp.zip1 KB

Resources

Learn

Get products and technologies

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 Mobile development on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Mobile development, WebSphere, Lotus
ArticleID=832078
ArticleTitle=Deliver an exceptional mobile web experience using WebSphere Portal and IBM Worklight V5.0, Part 1: Integrating a hybrid mobile application with WebSphere Portal pages
publish-date=08072013