Deliver an exceptional mobile web experience using WebSphere Portal and IBM Worklight, Part 7: Leveraging web content in a mobile app using Worklight

A case study

Building on Part 6 of this series on integrating IBM® WebSphere® Portal with IBM Worklight®, this article explains how you can leverage web content meta data and dynamic rules running inside of IBM WebSphere Portal and IBM Web Content Manager in an IBM Worklight mobile application. By leveraging the rules defined in Web Content Manager, you have one central place where business users and marketers can define promotions, and other dynamic and personalized content. This retail store example shows how you can combine the native geo-location feature of a mobile device with Web Content Manager's dynamic personalization rules that offer content based on the current user's context, location, or history. This opens up the possibility of a whole new set of applications that can be implemented using Worklight and Web Content Manager together, while keeping the content, its meta data, and the rules stored in Web Content Manager.

Vinod Appajanna (vinod_app@in.ibm.com ), Websphere Portal/WCM/Mobile-Portal-Accelerator Specialist, IBM

Vinod Appajanna is a Websphere Portal/WCM/Mobile-Portal-Accelerator Specialist at IBM (Mobile, Worklight integration, WEF, Portal integration with other products) and a Solution Architect. Vinod has around 9 Years experience in WebSphere Portal and mobile technology area. In this period he has played multiple roles including Product Architect, Solution Architect, IT Specialist, and Team/Project Lead, 4 years of experience in Design and Development of e-business application. In Recent months (since 8 months) he has been working on Worklight Portal integration work and has showcased some demos and sessions to Customers.



Stefan Hepper, WebSphere Portal Programming Model Architect, IBM

Stefan Hepper is the responsible architect for the WebSphere Portal and Workplace programming model and public APIs. He co-led the Java Portlet Specification V1.0 (JSR 168) and is now leading the V2.0 (JSR 286) effort. Stefan received a Diploma of Computer Science from the University of Karlsruhe, Germany, and in 1998 he joined the IBM Böblingen Development Laboratory.



26 March 2014

Introduction

This article, an extension of Part 6, describes a retail store use case to illustrate how the changes made in IBM Web Content Manager get reflected in an IBM Worklight mobile application. Through this example, you will also see how you can utilize meta data stored in content in the Web Content Manager and combine it with the native geo-location feature of the device to show information about a specific store.

Besides getting static information from Web Content Manager on the store name, location, and so on, the included example leverages a dynamic personalization rule for getting promotions for the store the user is currently looking at, and shows how it affects the end mobile application result. This article provides an idea of how you can apply comparable features to similar applications for other industries.

Provided here are examples that display stores located in the vicinity of the user’s current location on a map. Detailed information such as store name, address, promotions (if any), and phone number is also displayed. This data is stored as content in the Web Content Manager repository. As you add, modify, or delete the content in the Web Content Manager repository, you will see the data changes reflected on the device. This enables using a well defined workflow for creating and maintaining the store information, and for reviewing, approving, and versioning everything. It also enables the use of the publish-by-date feature from Web Content Manager so you can push out new or updated data at a predefined time automatically; for example, for a weekend promotion. The simple personalization rule used here shows how to integrate dynamic rules into the Worklight application.

The sample rule gets promotions based on the category of the selected store, but can easily be a lot more sophisticated. For example, if there is a user identity (for example, from a cookie or through authentication) the rule can display personalized promotions based on the user’s shopping history or other criteria.

Prerequisites

The solution described here uses:

  • IBM Websphere Portal V8.0
  • IBM Web Content Manager
  • IBM Worklight V6.0 or later. Before installing the Worklight environment, you must have this software installed properly and operational:
    • Eclipse 4.2.2
    • Android SDK 4.1.2 (API 16) on Eclipse
    • Oracle JRE 1.6.0 (required by Android SDK)

See Resources for more information on setting up the Worklight development environment.

To open the sample application in Worklight:

  1. Download the zip file on to your system. It contains two files:
    • wl_wcmstoredemo.zip contains the Web Content Manager library required for the sample application.
    • WorklightWCMStoreApp.zip is the sample worklight hybrid project.
  2. Extract the Web Content Manager library into a directory and then run this command to import the library:
    • Windows:
      ConfigEngine.bat import-wcm-data -DWasPassword=password -DPortalAdminPwd=password -Dimport.directory="<location where you have unzipped the library>" -Dimport.singledirectory=false
    • UNIX:
      ConfigEngine.sh import-wcm-data -DWasPassword=password -DPortalAdminPwd=password -Dimport.directory="<location where you have unzipped the library>" -Dimport.singledirectory=false

    After the successful import, logon to the WebSphere Portal administration console and check if the library exists. Be sure that you give anonymous access to the library.

  3. Download the Worklight project and import it (as an existing project in the workspace) into the same location in Eclipse where you have the Worklight plugin installed.
  4. If the dojoLib project is not in the workspace, then create a new library project called dojoLib; dojoLib is mapped to the sample and so is required for this exercise. Navigate to File > Properties > DojoToolkit > New Dojo Library, and name the new library dojoLib. Click OK.
  5. Right-click on the Worklight project (app\WorklightWCMStoreApp) and select Build All.
  6. Run the Android app.

While testing this Android application, make sure that:

  • the AndroidManifest.xml file has these entries:

    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

  • Location Service is enabled on the Android device.

Creating resources for displaying store and promotion information

This section describes these resources used by the sample application in order it to obtain content from Web Content Manager:

Feed components

These two components are part of the sample library that exposes the Web Content Manager contents as feeds so that it can be consumed by Worklight:

  • Web Content Manager library

    The Web Content Manager library, WL_WCMStoreDemo, acts as a repository for storing store information, such as its name, location, geo-location (latitude, longitude), and promotion details, along with the categories that are mapped to the stores and promotions.

  • Feed (menu) components

    Two components involved in determining the content that will display in the app are:

    • Store Atom Feed is a menu component that generates a feed for the stores.
    • Store Promotions Feed is a personalization component that generates the promotion feed for a particular store. The Personalization menu component in particular returns the atom results after triggering the rule. Figure 1 shows the Personalization component that displays the promotions (if any) for the store, based on the category of the store passed in as a request parameter. The category set on the store is compared with the category set on the promotions, and, if a match is found, then those promotions are displayed. (See Part 6 and Resources for information on creating a Menu component.) Being able to pass in any kind of parameter from outside into the query opens up many use cases; it can be used to pass in any kind of information available on the Worklight side of the application into Web Content Manager.
    Figure 1. Personalization component
    Personalization component

Site areas

You can add/modify/delete stores or promotions under the Locations and Promotions site areas (Figure 2):

  • Administer the site area containing store content items by navigating to: WL_WCMStoreDemo > Content > Stores > Locations.
  • For the site area containing promotion content items, go to: WL_WCMStoreDemo > Content > Stores > Promotions.

To add to either site area, navigate to either New > Content > WL_WCMStoreDemo > StoresAT or New > Content > WL_WCMStoreDemo > PromotionsAT

Figure 2. Site areas in Library Explorer
Site areas in Library Explorer

Click to see larger image

Figure 2. Site areas in Library Explorer

Site areas in Library Explorer

Authoring templates

StoresAT and PromotionsAT are the authoring templates that are part of the sample library. You can add more fields to the authoring template by navigating to WL_WCMStoreDemo > Authoring Templates > PromotionsAT (or StoresAT) and selecting Manage elements. Default fields include location, latitude, longitude fields, store image, phone number, and promotions.

Categories

Categories (Area1 and Area2, shown in Figure 3) are mapped to stores and promotions. Promotions are fetched by matching the categories that are mapped to stores and promotions. Figure 3 shows that there are two stores deployed in the WL_WCMStoreDemo library.

Figure 3. Categories deployed in WL_WCMStoreDemo
Categories deployed in WL_WCMStoreDemo

Click to see larger image

Figure 3. Categories deployed in WL_WCMStoreDemo

Categories deployed in WL_WCMStoreDemo

To map a category to the content for individual stores, navigate to WL_WCMStoreDemo > Content > Locations > Store1 and select Add Categories. In the Profile section, map either category Area1 or Area2 (Figure 4).

You can add more categories in the WL_WCMStoreDemo > Categories > Stores sections and then map them to individual stores under WL_WCMStoreDemo > Content > Store > Locations.

Figure 4. Mapping categories to content
Mapping categories to content

Click to see larger image

Figure 4. Mapping categories to content

Mapping categories to content

Creating a hybrid application to utilize Web Content Manager resources

By applying strategic use of the resources described above, the objectives of the sample application are to (Figure 5):

The sample utilizes the geo-location native feature (using Worklight) for fetching the current location. The store and promotion information is fetched using a RESTcall/feed (using Worklight Adapters).

  • Display the user’s current geo-location.
  • Display the map (OpenLayers).
  • Fetch applicable stores, store details, and promotion details from the Web Content Manager repository, and show the same on the map using markers. Only stores that are in the user's vicinity are displayed.
Figure 5. Sample application flow
Sample application flow

Implementing application for fetching Web Content Manager resources

In the sample application files:

  • WorklightWCMStoreApp.html mainly uses dojox.mobile.Accordion and dojox.mobile.SimpleDialog dojo UI components for displaying the UI (map/popup).
  • WorklightWCMStoreApp.js contains the script code that invokes the adapter procedure to fetch the store and promotion details, and the code for constructing the map using the Openlayers API. The map construction includes placing the markers and popups that display the store details.

The code sections that follow show key code in the WorklightWCMStoreApp.js file, located in apps/WorklightWCMStoreApp/common/js/WorklightWCMStoreApp.js.

Listing 1. Fetches stores by invoking the adapter procedure
function fecthStores(){
                    var invocationData = {
                    adapter : 'wcmstore',
                    procedure : 'getGeoLocations'
                    };
                    
                    WL.Client.invokeProcedure(invocationData,{
                    onSuccess : fetchStoresSuccess,
                    onFailure : fetchStoresFailure,
                    });
                    }
Listing 2. Show map, stores, and promotions
function displayStores() {
                    
                    //distanceCalulation checks if the fetched stores locations are with the range of 
                    //the current location.
                    
                    if (distanceCalculation(latilongi[1], latilongi[0], latilongi[1], latilongi[0], 
                    gpslati, gpslongi) < 30) {
                    
                    // create a popup for displaying the store details on clicking the markers.
                    
                    ......
                    
                    feature.data.popupContentHTML = "<font size='2' color='green'> Name: " + 
                    items[i].title + "<br/><hr/> Location: " + items[i].location + "<br/><hr/> 
                    Phone: " + items[i].phone + "<br/><hr/> <a href='#' style='text-decoration: 
                    none' onclick='javascript:fetchPromotions(\"" + items[i].category + "\");
                    '>Promotions<\a> <br/></font>";
                    
                    .........
                    
                    //register the click/touch event for the marker
                    marker.events.register("touchstart", feature, markerClick);
                    //marker.events.register("click", feature, markerClick);
                    
                    // Add markers on the Map
                    markers.addMarker(marker);
                    
                    }
                    
                    }

For testing purposes using the Android simulator or Firefox browser, you might want to comment out marker.events.register("touchstart", feature, markerClick) and uncomment marker.events.register("click", feature, markerClick). This is a precaution just to ensure that the event works.

In Listing 2, the value 30 (distance in KM) can be changed according to the user’s requirements. All the stores within this distance from the user’s current location are displayed.

Figure 6 shows the mobile app displaying the nearest stores with respect to the user’s current location.

Figure 6. Mobile app showing nearby store locations
Mobile app showing nearby store locations

Click to see larger image

Figure 6. Mobile app showing nearby store locations

Mobile app showing nearby store locations

Listing 3 shows the code for calculating distances from the user’s location to the displayed store locations, and the store details as they are represented on the app (Figure 7).

Listing 3. Code for distance calculation
function distanceCalculation (dest1_lati, dest1_longi, dest2_lati, dest2_longi) {	
                    
                    distance = 6371 * Math.acos(Math.cos(dest1_lati) * Math.cos(dest2_lati) * 
                    Math.cos(dest2_longi - dest1_longi) + Math.sin(dest1_lati) * Math.sin(dest2_lati));
                    
                    return distance;
Figure 7. Store details
Mobile app showing nearby store locations

Click to see larger image

Figure 7. Store details

Mobile app showing nearby store locations

Listing 4 shows the code for fetching promotion information for a particular store. This is invoked when the user clicks on the Promotions link in the store detail popup. Figure 8 shows the promotional details as displayed in the mobile app.

Listing 4. Code for promotion fetching
function fetchPromotions (store) {
                    
                    //Invokes the getPromotions adapter procedure to fetch the details pertaining 
                    //to the store.
                    
                    var invocationData = {
                    adapter: "wcmstore",
                    procedure: "getPromotions",
                    parameters: [store]
                    };
                    
                    WL.Client.invokeProcedure(invocationData, {
                    onSuccess: lang.hitch(this, loadFeedsOK), 
                    onFailure: lang.hitch(this, loadFeedsFAIL)
                    }); 
                    
                    
                    //Displays the popup/dialog with Promotions information.
                    .......
                    dom.byId("mblSimpleDialogText").innerHTML = feed.description;
                    registry.byId("dlg_message").show();
                    ....
                    
                    
                    }
Figure 8. Promotion details for selected store
Mobile app showing nearby store locations

Click to see larger image

Figure 8. Promotion details for selected store

Mobile app showing nearby store locations

Conclusion

This application described in this article shows how you can not only leverage Web Content Manager for static content inclusion in Worklight applications, but also leverage dynamic personalization rules that offer content based on the current user's context, location, or history. This opens the possibility of a whole new set of applications that can be implemented using Worklight and Web Content Manager together. In order for this application to work, there should be connectivity to the portal server. In the conclusion to this series, you will see how these feeds can be stored offline on the device, and how updates to the feed can be synched to the device.


Downloads

DescriptionNameSize
Sample demowl_wcmstoredemo.zip784 KB
Sample projectWorklightWCMStoreApp.zip4.1 MB

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 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=966397
ArticleTitle=Deliver an exceptional mobile web experience using WebSphere Portal and IBM Worklight, Part 7: Leveraging web content in a mobile app using Worklight
publish-date=03262014