This tutorial explains how to develop a Pega Platform™ mobile app that uses the Contact Database JavaScript module, which is part of the public JavaScript API, to facilitate managing a contacts list on a mobile device. The public JavaScript API is available for Pega Mobile Client.

The key advantage of using the public JavaScript API along with Pega Mobile Client is that it facilitates using the built-in device features of a mobile app, including scanning a barcode, capturing media, leveraging push notifications, using the device's contacts list (address book), and interacting with its web browser. If you generate a standard Pega Platform web app that is started on a web browser instead of one dedicated to run within Pega Mobile Client, you do not have access to these built-in device features.

• Requirements
• Create JavaScript code
• Add JavaScript code as a text file
• Attach the text file to a harness
• Invoke JavaScript in an app
• Next steps

When this tutorial is completed, users of the finished Pega Platform mobile app can enter a first name or last name in the Enter name or surname field and click Find Contact. Contacts that match the query are displayed in the Results field. For this feature to work, the Find Contact button must be associated with a JavaScript function that directly invokes the public Pega Mobile Client API (Contact Database module) to perform a query on the contacts list.

Requirements

Before starting this tutorial, review the following requirements:

• Familiarize yourself with the modules that are in the public JavaScript API. For more information, see Pega Mobile Client API reference, which contains a link to the API reference guide.
• Create a simple Pega Platform mobile app that searches the contents of the contacts list on a mobile device.
• The Pega Platform app that you create must contain the following items:
  • A section within the Perform harness called SampleSection.
  • A dynamic layout within SampleSection that contains the following controls:
    • Enter name or surname field (associated with a property called ContactsName)
    • Find Contact button
    • Results field
• Make sure that the Perform harness is selected for all your case stages in the Harness name field in the Advanced > Assignment details section that is displayed when you click Configure process detail for each case stage.

In order for any Pega Mobile Client API to work correctly, it cannot be called before the onLaunchboxLoaded method is invoked. In the Pega Platform, to ensure that the API is called only after the onLaunchboxLoaded method is invoked, use the pega.mobile.hybrid.callWhenLaunchboxLoaded API. This condition also applies to the Encrypted SQL, Filesystem, and Geolocation APIs, which are proprietary implementations of standard W3C APIs. The following example invokes the Geolocation API:

var useGeolocation = function () { 
  navigator.geolocation.watchPosition(successCallback, failureCallback, options); 
}; 

if (pega.mobile.isHybridClient) { 
  pega.mobile.hybrid.callWhenLaunchboxLoaded(useGeolocation); 
} else { 
  useGeolocation(); 
}

Creating JavaScript code

The first step requires creating JavaScript code that makes direct calls to the public JavaScript API. To achieve this, you need to obtain an instance of the window object within your JavaScript code, and then use it to invoke any required method in the public Pega Mobile Client API itself. You accomplish this in one of the following ways (depending on how the JavaScript module is defined in the public API itself):

• theWindow.launchbox.<MODULE_NAME>.<METHOD_NAME_WITH_PARAMETERS>;
• theWindow.<MODULE_NAME>.<METHOD_NAME_WITH_PARAMETERS>;

The JavaScript code that you create for this sample Pega Platform app uses the Contact Database module from the public Pega Mobile Client API. In particular, its find() method must be invoked to be able to search for a name in a mobile device contacts list.

When you create JavaScript code in which you refer to any public Pega Mobile Client API objects or methods, be sure to do the following steps:

1. Declare an if() statement that checks whether the running app is a hybrid mobile app. Include the main JavaScript code that you create inside this statement to ensure that it is invoked only when running the created Pega Platform app from a Pega Mobile Client app.
   if( pega.mobile.isHybrid )
2. Within this if() statement, obtain an instance of the JavaScript window object:
   var theWindow = pega.desktop.support.getDesktopWindow();
3. Use an instance of this object to call the required public JavaScript API function. In this example, it is called find():
   theWindow.launchbox.Contacts.find( options, findCallbacks);

An example of JavaScript code for the Pega Platform mobile app using the Contact Database module is displayed below. Initially, a call to pega.mobile.isHybrid is made within an if() statement to ensure that a hybrid mobile app is used. If the app is not a hybrid mobile app, no code is executed, and a warning message is displayed.

Notice how an instance of the JavaScript window object is obtained and used to invoke the find() method. When the call to the find() method succeeds, the printContacts() function is invoked so that any names found in the contacts list are displayed in the Pega Platform app.

function contacts_api(name){ 

  if(pega.mobile.isHybrid){ 
 
    var theWindow = pega.desktop.support.getDesktopWindow(); 
 
    var findCallbacks = { 
      onSuccess: function( contact ) { 
        printContacts(contact); 
      }, 
      onFailure: function( error ) { 
        alert("find onFailure called!" + JSON.stringify(error)); 
      } 
    }; 
 
    var options = { 
      filterValue: name, 
      filterOp: "contains", 
      filterBy: ["name"], 
      sortBy: "givenName", 
      sortOrder: "ascending", 
      filterLimit: 10 
    }; 
 
    theWindow.launchbox.Contacts.find(options, findCallbacks); 
  } 
  else{ 
    alert("This app must be run on a mobile device."); 
  } 
} 
function printContacts(contacts){ 
  var results = document.getElementById("Results"); 
  results.value = "Found: " + contacts.length + " result(s)."; 
  for (i = 0; i < contacts.length; i++) { 
    results.value += ('\n--------------------'); 
    results.value += ('\nContact #' + i); 
 
    results.value += ('\nFull name \n'); 
    if (contacts[i].name) { 
      results.value += (contacts[i].name); 
    } else { 
    results.value += (' - name not defined'); 
    } 
    results.value += ('\nPhone numbers '); 
    if (contacts[i].tel) { 
      for (k = 0; k < contacts[i].tel.length; k++) { 
        results.value += ("\n" + contacts[i].tel[k].type + ' - ' + contacts[i].tel[k].value); 
      } 
    } else { 
      results.value += (' - no phone numbers'); 
    } 
    results.value += ('\nE-mails '); 
    if (contacts[i].email) { 
      for (k = 0; k < contacts[i].email.length; k++) { 
        results.value += ("\n" + contacts[i].email[k].type + ' - ' + contacts[i].email[k].value); 
      } 
    } else { 
    results.value += (' - no emails'); 
    } 
  } 
};

Adding JavaScript code as a text file

To use the public Pega Mobile Client API (such as the Contact Database module) in your Pega Platform app, you must insert the JavaScript code that we created, as a text file.

1. From the App Explorer, right-click the name of your case and click Create > Technical > Text File.
2. In the Label field, enter contacts_api_example to name the new text file.
3. In the App Name (Directory) field, enter webwb.
4. In the File Type (extension) field, enter js.
   
5. Create and open the new text file, and then paste your JavaScript code into the File source field.
   
6. Click Save.

Attaching the text file to the harness

Attach the JavaScript code text file that you created to the Perform harness that contains the SampleSection section. This allows the Find Contact button that belongs to this section to use the public Pega Mobile Client API (Contact Database module) to search the contacts list that is on the mobile device.

1. From the App Explorer, edit the Performharness that contains the SampleSection section and click the Scripts & styles tab.
2. From the Scripts section, click Type > js.
3. In the Name field, locate the JavaScript code text file that you previously added.
   
4. Click Save.

Now you can invoke any functions that are defined in the JavaScript code text file directly from the harness. Remember that the JavaScript code text file contains the contacts_api() main function that was previously created. It is used to directly invoke the public Pega Mobile Client's Contact Database module function called find(), which searches the contacts list on the user's mobile device.

Invoking JavaScript in an app

You must create a Run Scriptaction for the Find Contact button. When the button is clicked, the Pega Platform mobile app searches the contacts list by invoking the contacts_api() function that is defined in the JavaScript code text file and displays any results in the Results field.

Pega Platform mobile app

1. Open the SampleSection section, and click View Properties for the Find Contact button.
2. From the Actions tab, click Create an action set.
3. Click Add an event and choose the Click mouse event.
4. Click Add an action, and then click All actions and choose the Run or Script action from the list.
5. In the Function Name field, enter the name of the function to be invoked, as defined in the JavaScript text file: contacts_api. Do not include brackets or parameters for the function.

   contacts_api(name){ 
    
     if(pega.mobile.isHybrid){ 
    
       var theWindow = pega.desktop.support.getDesktopWindow(); 
    
       var findCallbacks = { 
         onSuccess: function( contact ) { 
           printContacts(contact); 
         }, 
         onFailure: function( error ) { 
           alert("find onFailure called!" + JSON.stringify(error)); 
         } 
       }; 
    
       var options = { 
     ...

6. In the Name field, enter the name of the passed parameter for this function: name.
7. In the Value field, select the property that is associated with this passed parameter:.ContactsName. This property must correspond to the one that was assigned to the Enter name or surname text field in the SampleSection section when the Pega Platform app was created. This field specifies what to search for in the contacts list on the device.
   
8. Click Submit, and then click Save.

You have successfully created a Pega Platform app that leverages the public Pega Mobile Client API. Completing the steps in this section ensures that clicking the Find Contact button in the Pega Platform app searches the contacts list on a mobile device and displays the results on the device.

Next steps

Now that you have developed a Pega Platform app that leverages the public JavaScript API, you can build, brand, test, and distribute the created hybrid mobile app. For more information about hybrid mobile app, see these PDN articles:

• Building mobile apps
• Distributing mobile apps