# Just Type

Just Type as it first appears

This article describes how to integrate an apps with Palm'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, and so on.

An app can integrate with three different Just Type components:

1. Quick Actions — Displays apps that initiate a new action with the user-entered text. For exampe: a new email, a new memo, etc.

2. Launch and Search — Displays apps that search the Web or the Cloud.

3. db8 search — Just Type searches through db8 stored objects. If a user selects your app's data in the result set, your app is launched.

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

## About db8 and JSON

db8 is an addition to the webOS JavaScript framework's current storage methods designed to meet the needs of robust, high-performance applications. Though not a database itself, it is a service (com.palm.db) available on the device bus that interfaces to an embedded database storing JSON data objects. Javascript applications can use API calls provided with the JavaScript Foundation libraries to interface with the db8 service.

JSON is a lightweight data-interchange text format based on a subset of the JavaScript programming language that is easy for humans to read and write and for machines to parse and generate. Like XML, JSON contains name/value pair collections and ordered list of values (i.e., arrays).

For more information on JSON, see the following websites:

- JSON objects, values and format
- JSON schemas

A primer on how JSON data objects are formatted is beyond the scope of this document—consult the two links above for more information. However, in brief:

- Curly brackets ('{', '}') are used to enclose objects.
- Angle brackets ('[', ']') are used to enclose arrays.
- Colons (':') are used as delimiters in name/value pairs.
- Quotes (") are used for string values. Numeric and boolean values are not quoted.

In this section:

- Configuring appinfo.json for Just Type
- Appinfo.json Keywords
- Configuring Permissions for db8 Search

## 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
>           },
>           "search" :   {
>               "displayName"  : string,
>               "url"          : string,
>               "launchParam"  : string | any object
>           }
>       }
>     }

### action

This object configures an app for the "Quick Actions" menu in Just Type. When launched, the application is passed the field defined with "launchParam" as an argument. This field is HTML-encoded, so for example, any spaces would be replaced with "%20".

Element | Required | Type | Description
--- | --- | --- | ---
displayName | Yes | string | Display name for the application in the "Quick Actions" menu.
url | Yes | string | Application ID, i.e., "com.palm.contacts"
launchParam | Yes | string or any object | HTML-encoded, passed as an argument when the app is launched.

### dbsearch

db8 search indicating 5 matching entries |  | db8 search with expanded list

This object defines how Just Type accesses an application's db8 stored data. The application is launched if the user selects one of the result set entries returned. You can configure the query Just Type uses to access db8 storage, the result fields it displays, and 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 display name in the Just Type application.
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".
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

This object configures an app for the Launch and Search menu in Just Type. When launched, the application is passed the field defined with "launchParam" as an argument. This field can be a string or an object of any type. Again, this field will be HTML-encoded.

Element | Required | Type | Description
--- | --- | --- | ---
displayName | Yes | string | Display name for the application in the "Launch and Search" menu.
url | Yes | string | Application ID, i.e., "com.palm.contacts"
launchParam | Yes | string or any object | HTML-encoded, passed as an argument when the app is launched.

Example 1

>     {
>       "universalSearch": {
>           "action": {
>               "displayName": "Sample DB8",
>               "url":"com.palm.db8sample",
>               "launchParam":"searchString"
>           },
>           "dbsearch": {
>               "displayName":"DB8",
>               "url":"com.palm.db8sample",
>               "launchParam":"playerId",
>               "launchParamDbField":"_id",
>               "displayFields":["firstname","lastname","Club"],
>               "dbQuery":{"from":"com.palm.db8sample:1",
>                   "where":[{"prop":"firstname","op":"?","val":""}],"orderBy":"firstname","limit":40}
>           }
>       }
>     }

In this example, the user-entered text becomes the value for "#{searchTerms}" when launching the app from "Quick Actions" and the value for the "val" field when searching db8 storage.

For example, if the user typed "John", it becomes "launchParam":{"searchString":"John"} and "val":"John".

The JavaScript code to handle the Quick Actions launch this would look something like this:

>     this.launchParams = arg;
>     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
>     }

Example 2

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

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

## Appinfo.json Keywords

Another option you have with appinfo.json is to add a "keywords" field, which is an array of strings containing keyword meta-data. For example:

>     "keywords": ["dts"]

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

NOTE: You may need permission from Palm to do this.

## Configuring 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 create (or add to) a permissions file in "/etc/palm/db/permissions/". This file has to have the same name as your app, i.e., "com.palm.sample.app". Permissions are granted to applications for each db8 kind and its data objects. For Just Type, you would have to grant read permissions to "com.palm.launcher" (pardon the somewhat unintuitive name).

For example, if your app had only one kind, you would have a permissions file with JSON configuration that looked like this:

>     [
>       {
>           "type": "db.kind",
>           "object": "com.palm.sample:1",
>           "caller": "com.palm.launcher",
>           "operations": {
>               "read": "allow"
>           }
>       }
>     ]

NOTE: It's likely that third party developers will NOT get direct access to this directory, but, in JavaScript, you can implement this programmatically with the following "serviceRequest" call:

>     var permObj =[{"type":"db.kind","object":'com.palm.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!");}
>     });