Documentation

Just Type

This article describes how to integrate your app with HP's "Just Type" (formerly known as "Universal Search") feature. Just Type activates when a user begins typing in Launcher or Card view—starting an activity which can include searching, sending an email, making a phone call, searchiing app stored data, and so on.

An app can integrate with three different Just Type components:

Just Type Name	Just Type Preferences Name	Description
Quick Actions	Actions	Displays apps that launch with a specific task, for example: send a new email, write a new memo, add a contact, etc.
Search Using	Search Using	Displays apps that can search the Web/Cloud or the app's db8 data.
Launch	Content	Just Type can search through your app's db8 stored objects. If a user selects an object, your app is launched with that selection.

You can configure each of these in your app's appinfo.json file.

In this section:

Configuring appinfo.json for Just Type
Granting Permissions for db8 Search
User Settings for Just Type
JavaScript Implementation

Configuring appinfo.json for Just Type

You can add the following object and sub-objects to your app's appinfo.json file to configure it for Just Type.

Schema

   "universalSearch" : {
      "action" :  { 
          "displayName" : string,
          "url"         : string,
          "launchParam" : string | any object
      },
      "dbsearch":  {
          "displayName"        : string,
          "url"                : string,
          "launchParam"        : string,
          "launchParamDbField" : string,
          "displayFields"      : string array,
          "dbQuery"            : db8 Query object array
      },
      "search" :   { 
          "displayName"  : string,
          "url"          : string,
          "launchParam"  : string | any object
      }
   }

action

Figure 1: Sample Quiick Actions menu

Configures an app for Just Type's Quick Actions menu. When launched, the application is passed a launchParam argument indicating the action requested. This field is HTML-encoded, so for example, any spaces would be replaced with "%20".

Element	Required	Type	Description
displayName	Yes	string	App's display name in Just Type's Quick Actions menu.
url	Yes	string	Application ID, i.e., "com.palmdts.contacts".
launchParam	Yes	string or any object	HTML-encoded, passed as an argument when the app is launched; indicates the action the app should take.

dbsearch

Defines a db8 query Just Type uses for its Launch menu. The app is launched if the user selects one of the objects returned. For example, for a contacts app, this allows the user to select one contact and launch the app to edit that contact. The app is passed a launchParam argument that is HTML-encoded, so, for example, any spaces are replaced with "%20".

Figure 2: Sample app in Launch indicating how many db8 records (5) match the entered search criteria so far.

Note that Launch allows the user to drill-down to select one record. In the screenshot above, the user could select "Just Type sample app" and they would see a screen with 5 records. They could then select one and the app would launch with that selection. Alternatively, the user could keep entering text and continue to narrow the search results.

With "dbsearch" you can configure the following:

The query Just Type uses to access db8 storage
The result fields it displays
The parameters it passes when the app is launched

Including this object also means you have to give Just Type permission to access your db8 stored data, see Configuring Permissions for db8 Search.

Element	Required	Type	Description
displayName	Yes	string	App's display name in Just Type's Launch menu.
url	Yes	string	Application ID.
launchParam	Yes	string	Name of field passed as an argument to the app.
launchParamDbField	Yes	string	Name of field in database whose value is passed in "launchParam" to identify the record selected, usually the object's db8 ID ("`_id`").
displayFields	Yes	string array	db8 query result set fields displayed to user in Just Type, i.e., "firstname", "lastname", ...
dbQuery	Yes	string array	db8 query used in Just Type. The "val" field value (in the query's where clause) is set to the user-entered search text. See the db8 documentation for information on formatting a db8 query.

search

Figure 3: Sample Search Using menu

Configures an app for Just Type's Search Using menu. The application gets passed a "launchParam" argument that is HTML-encoded.

Element	Required	Type	Description
displayName	Yes	string	App's display name in Just Type's Search Using menu.
url	Yes	string	Application ID, i.e., "com.palmdts.mycontacts"
launchParam	Yes	string or any object	HTML-encoded, passed as an argument when the app is launched. If this field is a string, then it names a property of launchParams and is set to the user-entered text. For example, if set to "myField", then `launchParams.myField` contains the user-entered text. If defined as an object that contains `"#{searchTerms}"`, then `launchParams` is set to that object but `"#{searchTerms}"` is replaced with the user-entered text (see examples below).

appinfo.json Keywords

You can add a "keywords" option to appinfo.json—a string array containing keyword meta-data. For example:

"keywords": ["dts", "email"]

Just Type will list apps that contain the user-entered text in their "keywords" values.

Example 1

{
   "universalSearch":{
      "action":{
         "displayName":"Add New Contact",
         "url":"com.palmdts.mycontactsapp",
         "launchParam":"addContact"
      },
      "dbsearch":{
         "displayName":"My Contacts App",
         "url":"com.palmdts.mycontactsapp",
         "launchParam":"contactId",
         "launchParamDbField":"_id",
         "displayFields":[
            "firstname",
            "lastname",
            "Nickname"
         ],
         "dbQuery":{
            "from":"com.palmdts.mycontacts:1",
            "where":[
               {
                  "prop":"firstname",
                  "op":"?",
                  "val":""
               }
            ],
            "orderBy":"firstname",
            "limit":40
         }
      }
   }
}

In this example, the user-entered text becomes the value for the "val" field when searching db8 storage.

Example 2

{
   "universalSearch":{
      "search":{
         "displayName":"Palm App Catalog",
         "url":"com.palmdts.app.findapps",
         "launchParam":{
            "common":{
               "sceneType":"search",
               "params":{
                  "type":"query",
                  "search":"#{searchTerms}"
               }
            }
         }
      }
   }
}

In this example, "#(searchTerms)" is replaced with the user-entered text.

Granting Permissions for db8 Search

If you want Just Type to access your db8 data storage as indicated with the "dbsearch" object in appinfo.json, then you need to give the launcher permission to do so.

You can implement this programmatically with a db8 putPermissions service call.

Enyo

This example gives com.palm.launcher permission to access com.palmdts.sample:1 data objects. This code is taken from the sample JustType Enyo app that comes with the SDK.

    . . .
        {
            name: "putDBPermissions", 
            kind: enyo.PalmService,
            service: "palm://com.palm.db/",
            method: "putPermissions",
            onSuccess: "permissionSuccess",
            onFailure: "permissionFailure",
        }
    ],
    permissionSuccess: function(){
        console.log("DB permission granted successfully!");
    },
    permissionFailure: function(){
        console.log("DB failed to grant permissions!");
    },
    . . . 

    var permObj = [ {
      "type":"db.kind",
      "object":"com.palmdts.justtype:1",
      "caller":"com.palm.launcher",
      "operations":{
         "read":"allow"
      }}];

    this.$.putDBPermissions.call({"permissions":permObj});

Mojo

This example gives com.palm.launcher permission to access com.palmdts.sample:1 data objects.


var permObj =[{
   "type"   : "db.kind",
   "object" : "com.palmdts.sample:1",
   "caller" : "com.palm.launcher",
   "operations":{
      "read":"allow"
   }}];

this.controller.serviceRequest("palm://com.palm.db/", {
    method: "putPermissions",
    parameters: {"permissions":permObj},
    onSuccess: function() { Mojo.Log.info("DB permission granted successfully!");},
    onFailure: function() { Mojo.Log.error("DB failed to grant permissions!");}
 });

User Settings for Just Type

For your app to integrate with Just Type, the user has to select (check) the app for use in each Just Type category (Content, Search Using, and Actions) in the Just Type preferences program (under Setttings).

JavaScript Implementation

Enyo

The SDK comes with a sample Just Type Enyo app , which you can find in the SDK's ...\\more-examples\\JustType folder. This app displays and manages a hypothetical club's ball player roster and is configured to integrate with all 3 Just Type capabilities:

Quick Actions - Add a player.
Search Using - Search player records with user-entered text.
Launch - Search the players' firstname field with entered text. Edit player's record if selected in results.

The app's appinfo.json Just Type configuration looks like this:

{
   . . .

   "universalSearch":{
      "search":{
         "displayName":"Just Type app search",
         "url":"com.palmdts.justtype",
         "launchParam":"query"
      },
      "action":{
         "displayName":"JustType add player",
         "url":"com.palmdts.justtype",
         "launchParam":"newPlayer"
      },
      "dbsearch":{
         "displayName":"Just Type sample app",
         "url":"com.palmdts.justtype",
         "launchParam":"playerId",
         "launchParamDbField":"_id",
         "displayFields":[
            "firstname",
            "lastname",
            "Club"
         ],
         "dbQuery":{
            "from":"com.palmdts.justtype:1",
            "where":[
               {
                  "prop":"firstname",
                  "op":"%",
                  "val":""
               }
            ],
            "orderBy":"firstname",
            "limit":20
         }
      }
   }
}

Note how launchParam (app argument) is defined for each category. Here is how it is handled in the app's index.html file:

<body>
<script type="text/javascript">
    var appInstance = enyo.create({kind: "JustType"});

    //if we're being launched from the Just Type system then pass in any parameters
    if (window.PalmSystem && enyo.windowParams){
        appInstance.setLaunchParams(enyo.windowParams);
    }
    appInstance.renderInto(document.body);
</script>
</body>

Here, the main Enyo kind for this app is allocated (found in source\JustType.js). This kind has launchParams as one of its public properties:

published: {        
    launchParams: null
},

If a parameter is passed on launch, as it is with Just Type, the launchParams property is modified with a call to setLaunchParams. This automatically invokes the kind's launchParamsChanged function:

//
// This will be called if setLaunchParams is called from index.html.  
// It is  called automatically since launchParams is a published property on our kind.
//
launchParamsChanged: function(){
    //
    // If we received a launch parameter then we either make a 
    // query based on it, add a new player, or edit a player
    //
    if (this.launchParams){
        if (this.launchParams.playerId){
            //
            // Launch
            // Get player who was picked in db8 search result set
            //
            var inQuery = {
                "from":"com.palmdts.justtype:1",
                "where":[{
                    "prop":"_id",
                    "op":"=","val":this.launchParams.playerId
            }]};
            this.$.dbFind.call({query: inQuery}, 
                               {onSuccess: "playerQuerySuccess", 
                                onFailure: "playerQueryFail"});

         } else if (this.launchParams.newPlayer){
             //
             // Quick Actions
             // User selected "Add new player"
             //
             this.createNewPlayer();

         } else if (this.launchParams.query){
             //
             // Search Using
             // Reset the player list display based on our query param
             //
             this.$.list.reset(); 
        }
    }
},

Note how for each launchParam type (action, search, launch) it is handled in the above function as the app is launched and begins processing.

For the db8search to work, the launcher had to be given permission to access its db8 data objects:

//
// Attempt to give db permissions to the launcher so user's can perform queries on 
// our data with the Just Type feature. We do this after the db has been installed 
// since otherwise we'd have nothing to grant permissions for.
//
var permObj = [ {
        "type":"db.kind",
        "object":'com.palmdts.justtype:1',
        "caller":"com.palm.launcher",
        "operations":{
            "read":"allow"
         }
     }
];

this.$.putDBPermissions.call({"permissions":permObj});

Mojo

Your Mojo code can handle the Quick Actions or Search launch in the handleLaunch method in your app's AppAssistant. Using the fields defined by "launchParam" from Example 1 (above), it would look something like this:

AppAssistant.prototype.handleLaunch = function(launchParams) {
    if (this.launchParams) {

        if (this.launchParams.searchString) 
        {
            /* Do something, i.e., query database with searchString and display
        }
        else if (this.launchParams.playerId)
        {
            /* Do something, i.e., query database with ID and display
        }
    }
}