Deliver an exceptional mobile web experience using WebSphere Portal and IBM Worklight V6.0, Part 2: Integrating multiple device support for 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 to enable support for both Android and iOS smartphone applications during the enablement of WebSphere Portal and Worklight integration. This exercise augments the sample presented in Part 1 and demonstrates how to build an iPhone application and dynamically include the appropriate Worklight V6.0 resources.

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

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.



29 January 2014

Also available in Russian Japanese

Introduction

Get Worklight now

Download IBM Worklight Developer Edition 6.0 now at no cost, and with no expiration date!

The IBM Worklight platform enables you to create applications for many device environments, including iOS, Android, and Blackberry. Through the use of technology like Apache Cordova, which Worklight uses and ships, you can call native features via JavaScript™ from your web markup.

This article guides you through the process of creating a hybrid iOS application, specifically for the iPhone, that integrates with IBM WebSphere Portal. It discusses the process for determining the device that has accessed the portal, and for including the appropriate resources — for either for an iOS or Android phone— to enable support for native capabilities within the application.

Prerequisites

This article augments the information that was presented in Part 1 of this series. Complete the sample solution from Part 1 before continuing through the steps outlined here.

In addition to the prerequisites defined in Part 1, you must have Apple Xcode installed to build the sample hybrid application described here. This article builds upon the Worklight hybrid application with support for the Apple iPhone. This sample was tested with Apple Xcode version 4.4.1 and is only available for Apple OS X.


Scope the Android resources in the theme

In Part 1, you created an Android application that integrates with IBM WebSphere Portal. During that process, you integrated the Worklight JavaScript resources within the theme. It is important that you take those resources and scope them to a folder specified for Android environments:

  1. Connect to WebDAV and navigate to: fs-type1:themes/<customTheme>/worklight/.
  2. Within that folder are the resources copied over from Part 1. Those folders are common, js and wlclient. Create a new folder at that location named android.
  3. Move the folders common, js, and wlclient from their current location to the newly created android folder (Figure 1).
    Figure 1. Worklight resources scoped for Android devices
    Worklight resources scoped for Android devices

    Click to see larger image

    Figure 1. Worklight resources scoped for Android devices

    Worklight resources scoped for Android devices

The module setup in Part 1 for Worklight integration will now have incorrect paths defined for the contributions. The JavaScript resources will not be available until you redefine the contribution paths for both Android and iOS (later in this article).


Create the iPhone environment in Worklight

  1. To create a new environment for the iPhone in Worklight, open the Project Explorer and right-click on WLPortalApp in the apps folder, then select New > Worklight Environment (Figure 2).
    Figure 2. Create a new Worklight environment
    Create a new Worklight environment
  2. The New Worklight Environment panel displays (Figure 3). For this particular sample, select iPhone. If you needed to create environments for other iOS devices, such as iPad, this is where you would specify those additional options. Click Finish.
    Figure 3. Worklight environment displayed in Eclipse
    Worklight environment displayed in Eclipse

    Click to see larger image

    Figure 3. Worklight environment displayed in Eclipse

    Worklight environment displayed in Eclipse
  3. Worklight Studio updates the project with a native application for iPhone devices (Figure 4).
    Figure 4. iPhone native app is added to the project
    iPhone native app is added to the project
  4. Make sure that the application-descriptor.xml file has the URL or IP address set within the main file element of the WebSphere Portal server (done during Part 1) that you want to render in the hybrid application (Figure 5).
    Figure 5. The application-descriptor.xml with the Portal URL
    The application-descriptor.xml with the Portal URL

    Click to see larger image

    Figure 5. The application-descriptor.xml with the Portal URL

    The application-descriptor.xml with the Portal URL
  5. Now that you have the application set up, you should verify that it will build and deploy. As you can see in Figure 6, the Build All and Deploy command means the native applications will be redeployed based on the web application changes. Execute the command by right-clicking on the application and selecting Run As > Build All and Deploy.
    Figure 6. Selecting build and deploy
    Selecting build and deploy

    Click to see larger image

    Figure 6. Selecting build and deploy

    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 'WLPortalApp' deployed successfully with all environments in the Worklight console. Both the iOS and Android applications have been updated. The portal will automatically display within the iPhone application using the URL set in the application-descriptor.xml file, the same behavior as the Android application built in Part 1.

  6. Next, you want to view the application in the iPhone simulator. To do this, first right-click iphone under the project in Eclipse, then select Run as > Xcode project (Figure 7). This will launch Xcode and your application will be displayed in the console (Figure 8).
    Figure 7. Running application as Xcode project
    Running application as Xcode project

    Click to see larger image

    Figure 7. Running application as Xcode project

    Running application as Xcode project
    Figure 8. Your application displayed in Xcode
    Your application displayed in Xcode

    Click to see larger image

    Figure 8. Your application displayed in Xcode

    Your application displayed in Xcode
  7. Since the application was created for iPhone devices, change the simulator to iPhone by clicking on the down arrow, next to the Run icon in the top left of the console, and select the appropriate iPhone Simulator, (iOS 7.0 is shown in Figure 9, but a newer version will work as well.
    Figure 9. Change the simulator to iPhone
    Change the simulator to iPhone
  8. Select the Run icon in the top left (Figure 10) and the simulator will launch your application (Figure 11).
    Figure 10. Run button in Xcode
    The Run button in Xcode
    Figure 11. Your application running in the iPhone simulator
    Your application running in the iPhone simulator

    Click to see larger image

    Figure 11. Your application running in the iPhone simulator

    Your application running in the iPhone simulator

Update the Worklight module contributions for both iOS and Android phones

  1. Locate the JavaScript files in Eclipse for the Worklight libraries specific to iPhone that you will load in WebSphere Portal. These folders are named wlclient, js, and common, similar to the Android resources. You can find them at \WLPortal\apps\WLPortalApp\iphone\native\www\default\.
  2. Connect to WebDAV and navigate to: fs-type1:themes/<customTheme>/worklight/.
  3. Create a new folder at that location named iphone.
  4. Copy the Worklight folders from the iPhone environment in Eclipse into the iphone folder you created on WebDAV (Figure 12). You will not need to use all of the JavaScript included in these three folders right away for basic Cordova and Worklight client integration, but when using more advanced features such as analytics and device sensor APIs, these will also need to be defined in the module.
    Figure 12. The iphone folder has been created on webDAV
    The iphone folder has been created on webDAV

    Click to see larger image

    Figure 12. The iphone folder has been created on webDAV

    The iphone folder has been created on webDAV
  5. Create a file specifically for the iPhone static properties (Listing 1).
    Listing 1. Static properties for iPhone devices
    var WL = WL ? WL : {};
    
    /**
     * WLClient configuration variables.
     * Values are injected by the deployer that packs the gadget.
     */
    
     WL.StaticAppProps = {
    "APP_DISPLAY_NAME": "WLPortalApp",
    "APP_SERVICES_URL": "\/apps\/services\/",
    "APP_VERSION": "1.0",
    "ENVIRONMENT": "iphone",
    "LOGIN_DISPLAY_TYPE": "embedded",
    "WORKLIGHT_ROOT_URL": "\/apps\/services\/api\/WLPortalApp\/iphone\/"
    };
  6. Take the JavaScript from Listing 1 and include it in a usable fashion within a new JavaScript file named staticprops.js. Place this new file at in the fs-type1:themes/<customTheme>/worklight/iphone/js/ directory.

    In production, it would be worthwhile to create JavaScript layers for each device-specific set of files. This would reduce the requests on page render and help improve performance.

The WebSphere Portal theme now requires an update to identify the mobile device operating system that will enable the inclusion of the appropriate module contributions for the Worklight resources. The identification of the mobile device operating system will be determined by the device class mechanism in WebSphere Portal. Out-of-the-box, the smartphone clients for Android and iOS are combined into one device class called smartphone. It is required to separate the clients to load resources based on the operating system, as well as ensure these resources are only loaded when using a Worklight application.

  1. To create two new device classes that will identify the iPhone and Android smartphone clients while running in a Worklight application, run the xmlaccess script in Listing 2. These device classes will also enable you to load the resources separately within a theme module.
    Listing 2. XMLAccess script to add device classes for iPhone and Android within a Worklight application
    <?xml version="1.0" encoding="UTF-8"?>
    <request type="update" create-oids="true"
    	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    	xsi:noNamespaceSchemaLocation="PortalConfig_7.0.0_2.xsd">
    	<portal action="locate">
    		<device-class action="update" name="android-worklight" 
    			uniquename="wps.deviceclass.android_wl" />
    		<device-class action="update" name="iphone-worklight" 
    			uniquename="wps.deviceclass.iphone_wl" />
    	</portal>	
    </request>
  2. Once the device classes are created, they need to be assigned to a client. Two new clients will be created so that WebSphere Portal will identify the Worklight iPhone and Worklight Android phone environments. Run the xmlaccess script in Listing 3 to create these two new clients with the new device classes assigned.
    Listing 3. XMLAccess script to add clients for iPhone and Android within a Worklight application
    <?xml version="1.0" encoding="UTF-8"?>
    <request type="update" 
    		 version="8.0.0.0" 
    		 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    		 xsi:noNamespaceSchemaLocation="PortalConfig_8.0.0.xsd">
     	<portal action="locate">
          <client action="update" domain="rel" manufacturer="Apple" markup="html" 
    uniquename="wps.client.iphoneworklight">
          <useragent-pattern>.*iPhone.*Worklight.*</useragent-pattern>
    	<client-capability update="set">com.ibm.portal.devicesupport.deviceclass=
    	iphone-worklight</client-capability>     	
          <client-capability update="set">HTML_4_0</client-capability>
          </client>
          <client action="update" domain="rel" manufacturer="Google" markup="html" 
    uniquename="wps.client.androidmobileworklight">
          <useragent-pattern>.*Android.*Mobile.*Worklight.*</useragent-pattern>
    	<client-capability update="set">com.ibm.portal.devicesupport.deviceclass=
    android-worklight</client-capability>     	
          <client-capability update="set">HTML_4_0</client-capability>
          </client>
        </portal>
        </request>
  3. At this point, you have all of the Worklight resources in place for the theme, and the device classes are available to detect the device environment. The resources will be aggregated on the page using a theme module. The theme module has the ability to define a JavaScript contribution and determine the proper environment for which it should be aggregated. The deviceClass attribute will be leveraged to pivot resources between iPhone and Android.
  4. Connect to WebDAV and open the contributions folder under your custom theme and open the file named worklight.json. This file was file created in Part 1. It defines a module identified as wl_client.
  5. Copy the worklight.json file to your local machine and replace the contents of this file with Listing 4.
    Listing 4. Module definition for the Worklight resources
    {
       "modules":[{
          "id":"wl_client",
          "contributions":[{
             "type":"config",
                "sub-contributions":[
     		{  
    			"type":"js",
    			"uris":[
    			{
    				"value":"/worklight/android/js/staticprops.js",
    				"deviceClass":"android-worklight"
    			}, {
    				"value":"/worklight/iphone/js/staticprops.js",
    				"deviceClass":"iphone-worklight"
    			}]
               },
               {  
    			"type":"js",
    			"uris":[
    			{
    				"value":"/worklight/android/wlclient/js/cordova.js",
    				"deviceClass":"android-worklight"
    			}, {
    				"value":"/worklight/iphone/wlclient/js/cordova.js",
    				"deviceClass":"iphone-worklight"
    			}]
               },
               {  
    			"type":"js",
    			"uris":[
    			{
    				"value":"/worklight/android/common/js/wljq.js",
    				"deviceClass":"android-worklight"
    			}, {
    				"value":"/worklight/iphone/common/js/wljq.js",
    				"deviceClass":"iphone-worklight"
    			}]
               },
    		{
    			"type":"js",
    			"uris":[
    			{
    				"value":"/worklight/android/common/js/wl_.min.js",
    				"deviceClass":"android-worklight"
    			}, {
    				"value":"/worklight/iphone/common/js/wl_.min.js",
    				"deviceClass":"iphone-worklight"
    			}]
               },
               {  
            	      "type":"js",
    			"uris":[
    			{
    				"value":"/worklight/android/common/js/sjcl.min.js",
    				"deviceClass":"android-worklight"
    			}, {
    				"value":"/worklight/iphone/common/js/sjcl.min.js",
    				"deviceClass":"iphone-worklight"
    			}]
    			
               },
    	   {
               		"type":"js",
    			"uris":[
    			{
    				"value":"/worklight/android/common/js/stacktrace.min.js",
    				"deviceClass":"android-worklight"
    			}, {
    				"value":"/worklight/iphone/common/js/stacktrace.min.js",
    				"deviceClass":"iphone-worklight"
    			}]
               },
               {               
            	      "type":"js",
    			"uris":[
    			{
    				"value":"/worklight/android/common/js/base.js",
    				"deviceClass":"android-worklight"
    			}, {
    				"value":"/worklight/iphone/common/js/base.js",
    				"deviceClass":"iphone-worklight"
    			}]
               },
               {
    	       	       "type":"js",
    			"uris":[
    			{
    				"value":"/worklight/android/wlclient/js/messages.js",
    				"deviceClass":"android-worklight"
    			}, {
    				"value":"/worklight/iphone/wlclient/js/messages.js",
    				"deviceClass":"iphone-worklight"
    			}]
               },
               {
            	       "type":"js",
    			"uris":[
    			{
    				"value":"/worklight/android/common/js/wlcommon.js",
    				"deviceClass":"android-worklight"
    			}, {
    				"value":"/worklight/iphone/common/js/wlcommon.js",
    				"deviceClass":"iphone-worklight"
    			}]
               },				
               {
    	              "type":"js",
    			"uris":[
    			{
    				"value":"/worklight/android/wlclient/js/diagnosticDialog.js",
    				"deviceClass":"android-worklight"
    			}, {
    				"value":"/worklight/iphone/wlclient/js/diagnosticDialog.js",
    				"deviceClass":"iphone-worklight"
    			}]
               },
               {
            	        "type":"js",
    			"uris":[
    			{
    			    "value":"/worklight/android/wlclient/js/deviceAuthentication.js",
    			    "deviceClass":"android-worklight"
    			}, {
    			    "value":"/worklight/iphone/wlclient/js/deviceAuthentication.js",
    			    "deviceClass":"iphone-worklight"
    			}]
               },
               {
    	               "type":"js",
    			"uris":[
    			{
    				"value":"/worklight/android/wlclient/js/window.js",
    				"deviceClass":"android-worklight"
    			}, {
    				"value":"/worklight/iphone/wlclient/js/window.js",
    				"deviceClass":"iphone-worklight"
    			}]
               },
               {
    	               "type":"js",
    			"uris":[
    			{
    				"value":"/worklight/android/wlclient/js/worklight.js",
    				"deviceClass":"android-worklight"
    			}, {
    				"value":"/worklight/iphone/wlclient/js/worklight.js",
    				"deviceClass":"iphone-worklight"
    			}]
               },
               {
            	       "type":"js",
    			"uris":[
    			{
    				"value":"/worklight/android/wlclient/js/wlclient.js",
    				"deviceClass":"android-worklight"
    			}, {
    				"value":"/worklight/iphone/wlclient/js/wlclient.js",
    				"deviceClass":"iphone-worklight"
    			}]
               },
               {
    	               "type":"js",
    			"uris":[
    			{
    				"value":"/worklight/android/wlclient/js/wlfragments.js",
    				"deviceClass":"android-worklight"
    			}, {
    				"value":"/worklight/iphone/wlclient/js/wlfragments.js",
    				"deviceClass":"iphone-worklight"
    			}]
               },
               {
     	              "type":"js",
    			"uris":[
    			{
    				"value":"/worklight/android/wlclient/js/encryptedcache.js",
    				"deviceClass":"android-worklight"
    			}, {
    				"value":"/worklight/iphone/wlclient/js/encryptedcache.js",
    				"deviceClass":"iphone-worklight"
    			}]
               },
               {
            	       "type":"js",
    			"uris":[
    			{
    				"value":"/worklight/android/wlclient/js/checksum.js",
    				"deviceClass":"android-worklight"
    			}, {
    				"value":"/worklight/iphone/wlclient/js/checksum.js",
    				"deviceClass":"iphone-worklight"
    			}]
               },
      		{
            	       "type":"js",
    			"uris":[
    			{
    				"value":"/worklight/android/wlclient/js/features_stubs/
    					jsonstore_stub.js",
    				"deviceClass":"android-worklight"
    			}, {
    				"value":"/worklight/iphone/wlclient/js/features_stubs/
    					jsonstore_stub.js",
    				"deviceClass":"iphone-worklight"
    			}]
                },
                {
    	               "type":"js",
            	       "uris":[{"value":"/worklight/iphone/wlclient/js/json2.js",
                   			"deviceClass":"iphone-worklight"}]
                },
                {
    	       	        "type":"js",
    			"uris":[
    		{
    				"value":"/worklight/android/wlclient/js/wlgap.android.js",
    				"deviceClass":"android-worklight"
    		}, {
    				"value":"/worklight/iphone/wlclient/js/wlgap.ios.js",
    				"deviceClass":"iphone-worklight"
    			}]
                },
                {
    	               "type":"js",
    			"uris":[
    			{
    				"value":"/worklight/android/js/initOptions.js",
    				"deviceClass":"android-worklight"
    			}, {
    				"value":"/worklight/iphone/js/initOptions.js",
    				"deviceClass":"iphone-worklight"
    			}]
                },
                {
            	       "type":"js",
    			"uris":[
    			{
    				"value":"/worklight/android/js/messages.js",
    				"deviceClass":"android-worklight"
    			}, {
    				"value":"/worklight/iphone/js/messages.js",
    				"deviceClass":"iphone-worklight"
    			}]
                }]
            }]
       }]
    }
  6. Copy the worklight.json file back to the /themes/<customTheme>/contributions folder on WebDAV.
  7. Restart WebSphere Portal.

    You can turn on development mode to avoid restarting when making module or profile changes. This setting should be disabled before going into production. To turn on development mode:

    1. In the WebSphere Application Server console, navigate to Resources > Resource Environment > Resource Environment Providers.
    2. Select the WP ConfigService resource environment provider (REP). Change the resourceaggregation.development.mode property to true.
  8. When WebSphere Portal starts back up, the modules will be available for use in a profile. Your custom profile named profile_worklight.json located on webDAV at /themes/<customTheme>/profiles/ should be available from Part 1. You should not need to modify the profile further as the module ID did not change.

Test the application

Since this exercise continued from Part 1, there is a sample already in place to test the Worklight API. This sample will display the device name and version at the top of the page. The test will be to confirm that this information is shown correctly for both the Android emulator and iOS simulator.

  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 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, navigate to the page to which you applied the custom theme and Worklight profile. If this page does not have anonymous access, then login and navigate to the page. It 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 13.
    Figure 13. The Android emulator showing Portal with the Worklight API sample
    The Android emulator showing Portal with the Worklight API sample

    Click to see larger image

    Figure 13. The Android emulator showing Portal with the Worklight API sample

    The Android emulator showing Portal with the Worklight API sample

    At this time you will notice that the look and feel is not optimized for the phone environment as it was before you added the new device classes. The next section will discuss the changes required to optimize the look and feel for the phone environment using the new device classes.

  4. Right-click on iphone under the WLPortalApp and select Run As > Xcode project. This will launch the Xcode application, and you will need to run the application in the iOS simulator. Once running, the application will display your WebSphere Portal.
  5. After the application has rendered the WebSphere Portal application, navigate once again to the page where you applied the custom theme and Worklight profile. You will see the device name and version appear at the top of the page, as shown in Figure 14.
    Figure 14. iOS simulator showing WebSphere Portal with the Worklight API
    iOS simulator showing WebSphere Portal with the Worklight API

    Click to see larger image

    Figure 14. iOS simulator showing WebSphere Portal with the Worklight API

    iOS simulator showing WebSphere Portal with the Worklight API

As you have seen, the Worklight resources are available and you can begin to leverage native capabilties, but the look and feel needs an update to optimize for the iPhone environment


Update the WebSphere Portal theme styles

The first step to optimizing the look and feel of WebSphere Portal is ensuring that the responsive styles for a smartphone are applied to the page. To do this you must define contributions for the theme styles module that apply the new device classes.

  1. Connect to WebDAV and navigate to: fs-type1:themes/<customTheme>/contributions/.
  2. Within that folder open the file named theme.json.
  3. This file includes the module that defines the styles for the theme, named wp_theme_portal_80. The module contributes the smartphone styles from Listing 5.
    Listing 5. Theme module contribution for smartphone styles
    {
    "value":"/css/master_smartphone.css",
    "deviceClass":"smartphone"
    }
  4. Copy the code from Listing 5 and use it to define two new contributions within the module for each new Worklight device class that will contribute the same styles, shown in Listing 6.
    Listing 6. Theme module contributions created with new device classes
    {
    "value":"/css/master_smartphone.css",
    "deviceClass":"smartphone"
    },
    {
    "value":"/css/master_smartphone.css",
    "deviceClass":"iphone-worklight"
    },
    {
    "value":"/css/master_smartphone.css",
    "deviceClass":"android-worklight"
    }
  5. Save theme.json and copy it back to WebDAV.
  6. Restart WebSphere Portal if development mode is not enabled.

Update the WebSphere Portal theme dynamic content

The default theme in WebSphere Portal 8.0.0.1 uses device classes to provide appropriate resources for a particular environment. To ensure that the look and feel of the portal continues to optimize for these smartphone devices, you will have to update the areas of WebSphere Portal that use device classes to also include these new device classes: android-worklight and iphone-worklight.

In Part 1, you created a custom theme and part of that theme was creating a new web application EAR that includes custom dynamic resources. You will be updating theme dynamic content spots, located at /<wp_profile>/installedApps/<node>/<custom_ear>/<custom_war>/themes/html/dynamicSpots/ as well as the boostrap located in the parent folder.

  1. In the file boostrap.jspf, located in the parent to the dynamicSpots folder <wp_profile>/installedApps/<node>/<custom_ear>/<custom_war>/themes/html/, locate this code:
    <c:set var="isMobile" scope="request" value="${deviceClass ==
    'tablet' || deviceClass == 'smartphone'}”>

    and change it to:

    <c:set var="isMobile" scope="request" value="${deviceClass == 'tablet' || 
    deviceClass == 'smartphone' || deviceClass == 'iphone-worklight' || 
    deviceClass == 'android-worklight'}" />

    Touch Default.jsp after these changes.

  2. In the file commonActions.jsp,
    1. Locate this code:
      <c:set var="isMobile" scope="request" value="${deviceClass ==
      'tablet' || deviceClass == 'smartphone'}>

      and change it to:

      <c:set var="isMobile" scope="request" value="${(deviceClass == 'tablet') || 
      (deviceClass == 'smartphone') || (deviceClass == 'iphone-worklight') || 
      (deviceClass == 'android-worklight')}" />
    2. Locate this code:
      <ul class="wpthemeCommonActions wpthemeRight">
      <portal-logic:if loggedIn="yes">
      <%-- Username is used as a link to 'Edit My Profile' --%>
      <c:if test="${deviceClass != 'smartphone'}">

      and change it to:

      <ul class="wpthemeCommonActions wpthemeRight">
      <portal-logic:if loggedIn="yes">
      <%-- Username is used as a link to 'Edit My Profile' --%>
      <c:if test="${deviceClass != 'smartphone' && deviceClass != "iphone-worklight"
      &&
      deviceClass != "android-worklight"}">
    3. Locate this code:
      <%-- Sign up Link --%>
      <c:if test="${deviceClass != 'smartphone'}">

      and change it to:

      <%-- Sign up Link --%>
      <c:if test="${deviceClass != 'smartphone' && deviceClass != "iphone-worklight"
      &&
      deviceClass != "android-worklight"}">
  3. In the file crumbTrail.jsp, locate this code:
    <%-- The following variables are defined in bootstrap.jspf for performance reasons and reused here.
    * selectionPath
    * deviceClass
    * isMobile --%>
    <c:if test="${deviceClass != 'smartphone'}">

    and change the device class logic to:

    <c:if test="${deviceClass != 'smartphone' && deviceClass !=
    "iphone-worklight" && deviceClass != "android-worklight"}">
  4. In the file footer.jsp, locate this code:
    <c:if test="${deviceClass == 'smartphone'}">
    <script>window.scrollTo(0, 47);</script>
    </c:if>

    and change the device class logic to:

    <c:if test="${deviceClass == 'smartphone' || deviceClass ==
    "iphone-worklight" || deviceClass == "android-worklight"}">
  5. In the file pageModeToggle.jsp, locate this code:
    <c:if test="${deviceClass != 'smartphone' && deviceClass
    != 'tablet'}">

    and change it to:

    <c:if test="${deviceClass != 'smartphone' &&
    deviceClass != 'tablet' && deviceClass != 'iphone-worklight' && 
    deviceClass != 'android-worklight' }">
  6. The previous steps updated the theme's dynamic content spots, but there are also mappings to dynamic content spots from WebSphere Portal out-of-the-box modules. The next step is to override the dynamic content spot with your own custom JSP. The dynamic content spots that need to be overriden are:
    • customTheme_search
    • customTheme_mobileSearch
    • customTheme_projectMenu
    In the out-of-the-box pagebuilder module, locate this JSP:

    <PortalServer>\theme\wp.theme.modules\webapp\installedApps\ThemeModules.ear\ThemeModules.war\modules\pagebuilder\jsp\projectMenu.jsp

    .
  7. Copy the projectMenu.jsp to your custom theme WAR and rename it to customProjectMenu.jsp. You custom theme WAR should be located in a path similar to:

    /<wp_profile>/installedApps/<node>/<custom_ear>/<custom_war>/themes/html/dynamicSpots/

  8. Inside customProjectMenu.jsp, locate the code:
    <c:if test="${deviceClass != 'smartphone' && deviceClass !=
        'tablet'}">

    and change that code to include the new device classes:

    <c:if test="${deviceClass != 'smartphone' && deviceClass != 'tablet' &&
    deviceClass != 'iphone-worklight' && deviceClass != 'android-worklight' }">
  9. Inside customProjectMenu.jsp, locate the line:
    <%@ include file="../../../themes/html/includePortalTaglibs.jspf"%>

    The includePortalTaglibs.jspf file should have been copied to your custom WAR during the theme creation process in Part 1. The location of this file has changed now that the file is located in your custom theme. Change this line of code to:

    <%@ include file="../includePortalTaglibs.jspf"%>
  10. In the search module, locate this JSP:

    <PortalServer>\theme\wp.theme.modules\webapp\installedApps\ThemeModules.ear\ThemeModules.war\themes\html\dynamicSpots\modules\search\search.jsp

    Copy the search.jsp to your custom theme WAR and rename it to customSearch.jsp (same location as customProjectMenu.jsp).
  11. Directly above where the HTML markup begins in the file, above the line that starts with:
    <div class="wpthemeSearch...

    add this line of code for setting the isMobile variable:

    <c:set var="isMobile" scope="request" value="${(deviceClass == 'tablet') ||
        (deviceClass == 'smartphone') || (deviceClass == 'iphone-worklight') || (deviceClass
        == 'android-worklight')}" />
  12. Similar to the customProjectMenu.jsp, you will need to change the path to the includePortalTaglibs.jspf file. Locate this line of code:
    <%@ include file="../../../includePortalTaglibs.jspf" %>

    and change it to:

    <%@ include file="../includePortalTaglibs.jspf" %>

    The files that will be used in place of the out-of-the-box JSPs are complete.

  13. Create a new file named customDynamicSpots.json. This new file will define modules that will contribute your custom JSP overrides.
  14. Copy the code from Listing 7 into the new customDynamicSpots.json file. The modules will be overriding three content spot mappings:
    • customTheme_search
    • customTheme_mobileSearch
    • customTheme_projectMenu
    There are two search dynamic spots as the theme injects the JSP into different locations based on device. These spots are toggled based on the device classes defined via the mapping in the REP.
    Listing 7. The module definitions for the JSP content spot overrides
    { 
    "modules":[{ 
      "id" : "custom_search", 
      "contributions": [{ 
      	"type":"dyn-cs", 
      	"sub-contributions": [{ 
      		"type":"markup", 
          	"ref-id":"customTheme_search", 
          	"uris": [{ 
            	"value":"res:/customTheme/themes/html/dynamicSpots/customSearch.jsp" 
            }] 
          }] 
        }] 
      },
      { 
      "id" : "custom_mobileSearch", 
      "contributions": [{ 
        "type":"dyn-cs", 
        "sub-contributions": [{ 
          	"type":"markup", 
          	"ref-id":"customTheme_mobileSearch", 
          	"uris": [{ 
            	"value":"res:/customTheme/themes/html/dynamicSpots/customSearch.jsp" 
            }] 
          }] 
        }] 
     },
     { 
      "id" : "custom_projectMenu", 
      "contributions": [{ 
        "type":"dyn-cs", 
        "sub-contributions": [{ 
          	"type":"markup", 
          	"ref-id":"customTheme_projectMenu", 
          	"uris": [{ 
            	"value":"res:/customTheme/themes/html/dynamicSpots/customProjectMenu.jsp" 
            }] 
          }] 
        }] 
     }]
    }

    Be aware that the customTheme suffix might differ from the namespace that you used for your theme, or if you continued to use the out-of-the-box mappings, then the namespace will be 80theme. Ensure the namspace you used for the mappings is reflected in the attribute ref-id of the module definition from Listing 7. Also, make sure the context root to the custom theme WAR is correct in the path to the JSP.

  15. Copy the customDynamicSpots.json file to webDAV at this location: fs-type1:themes/<customTheme>/contributions/.
  16. Open the profile assigned to the page. In Part 1, the profile was named profile_worklight.json, located at: fs-type1:themes/<customTheme>/profiles/.
  17. Add the modules custom_search, custom_mobileSearch and custom_projectMenu (Listing 8).
    Listing 8. The dynamic content spot override modules added to the profile
    {	"moduleIDs": [
    		"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",
    		"wp_theme_edit",
    		"wl_client",
    		"custom_search",
    		"custom_searchMobile",
    		"custom_projectMenu"
    	],
  18. Restart WebSphere Portal if development mode is not enabled. More information on the process for overriding a module JSP dynamic content spot is available in this article.
  19. The device class logic within the dynamic content JSPs has been updated for the Worklight environment; however, it is also necessary to update the dynamic content spot mappings. Change the dynamic content spot mappings in your custom theme that align with the keys from the default theme located in the REP, identified as WP DynamicContentSpotMappings. (See this article for more information on working with the dynamic content spot mappings.)

    The first two mappings that you will modify are for the search dynamic content spots. Although the JSP will be overriden, the mapping will still define the device classes that will toggle visibility.

    Table 1. JSP mapping
    KeyChange value to:
    customTheme_search mvc:res:/wps/themeModules/themes/html/dynamicSpots/modules/search/search.jsp,smartphone@,tablet@,iphone-worklight@,android-worklight@
    customTheme_mobileSearchmvc:smartphone/tablet/iphone-worklight/android-worklight@res:/wps/themeModules/themes/html/dynamicSpots/modules/search/search.jsp
    customTheme_primaryNavmvc:res:/<customThemeContext>/themes/html/dynamicSpots/navigation.jsp?rootClass=wpthemePrimaryNav%2520wpthemeLeft&startLevel=1,smartphone@,tablet@,iphone-worklight@,android-worklight@
    customTheme_secondaryNavmvc:res:/<customThemeContext>/themes/html/dynamicSpots/navigation.jsp?rootClass=wpthemeSecondaryNav&startLevel=2&levelsDisplayed=2,smartphone@,tablet@,iphone-worklight@,android-worklight@
    customTheme_sideNavmvc:res:/<customThemeContext>/themes/html/dynamicSpots/sideNavigation.jsp?startLevel=2,smartphone@,tablet@,iphone-worklight@,android-worklight@
    customTheme_mobileNavmvc:smartphone/tablet/iphone-worklight/android-worklight@res:/<customThemeContext>/themes/html/dynamicSpots/mobileNavigation.jsp
  20. Save the changes made to the REP (Figure 15).
    Figure 15. The save link in the console
    The save link in the console

    Click to see larger image

    Figure 15. The save link in the console

    The save link in the console
  21. Restart WebSphere Portal. Everything is in place for your portal to detect the device that is accessing WebSphere Portal, include the set of files required to integrate correctly with Worklight, and optimize the theme for smartphone devices.
  22. When the portal is running, you can now launch both the iPhone and Android applications. The Worklight resources will be included for the appropriate environment, and the theme will be optimized for the mobile device (Figures 16 and 17).
    Figure 16. Android emulator showing blank portal page with optimized theme and Worklight sample
    Android emulator showing blank Portal page with optimized theme and worklight sample

    Click to see larger image

    Figure 16. Android emulator showing blank portal page with optimized theme and Worklight sample

    Android emulator showing blank Portal page with optimized theme and worklight sample
    Figure 17. iOS simulator showing blank portal page with optimized theme and Worklight sample
    iOS simulator showing blank Portal page with optimized theme and worklight sample

    Click to see larger image

    Figure 17. iOS simulator showing blank portal page with optimized theme and Worklight sample

    iOS simulator showing blank Portal page with optimized theme and worklight sample

Conclusion

IBM WebSphere Portal makes it easy to tailor the native device capabilities available to your multi-channel web applications. The Worklight shell created for both Android and iOS can also be packaged into a deliverable that can be published to either 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 tailored for multiple devices. The next articles in this series will discuss the configuration for single sign-on authentication, and integrating Worklight and Web Exeperience Factory, respectively.


Download

DescriptionNameSize
Sample applicationPart2-sample_files.zip9 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


  • Bluemix Developers Community

    Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.

  • Mobile weekly

    Innovations in tools and technologies for mobile development.

  • DevOps Services

    Software development in the cloud. Register today to create a project.

  • IBM evaluation software

    Evaluate IBM software and solutions, and transform challenges into opportunities.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Mobile development, WebSphere, Lotus
ArticleID=961000
ArticleTitle=Deliver an exceptional mobile web experience using WebSphere Portal and IBM Worklight V6.0, Part 2: Integrating multiple device support for WebSphere Portal pages
publish-date=01292014