52
edits
Labs/Ubiquity/Writing Noun Types: Difference between revisions
Labs/Ubiquity/Writing Noun Types (view source)
Revision as of 23:29, 21 August 2009
, 21 August 2009no edit summary
No edit summary |
|||
| Line 73: | Line 73: | ||
=== Basic structure === | === Basic structure === | ||
=== Scoring your suggestions === | === Scoring your suggestions === | ||
| Line 81: | Line 79: | ||
=== Asynchronous requests === | === Asynchronous requests === | ||
Some noun types need to make calls to external web services to decide whether the users input is valid for the particular noun type. noun_type_async_address and noun_type_async_restaurant are examples of nouns that do this. | |||
==== Registering an asynchronous call ==== | |||
If you are performing asynchronous calls to web services, your noun type must tell Ubiquity about these calls so that Ubiquity will know to wait for those requests to come back before completing the query. For this to work, all you need to do is pass an object back to Ubiquity in the return array of your suggest method which represents the asynchronous request. This could be an ajax request object, or any object that represents your request. If you're using an object other than an ajax request, you need to add a readyState attribute to that object and set it's value to 2. This tells Ubiquity that your request is still outstanding. When the async request is finished, update this value to 4. When the ready state value of the async request is 4, Ubiquity will remove it from the list of outstanding requests. | |||
Example: | |||
==== Returning results asynchronously === | |||
The suggest method of your noun type is passed a callback function which you can use to return results asynchronously. When you are ready to send Ubiquity a new suggestion, simply execute the callback function with your suggestion as the argument. | |||
Example: | |||
==== The noExternalCalls property ==== | |||
In an effort to limit the number of network calls made, noun types use a special property for telling Ubiquity whether or not they use external calls, called noExternalCalls. | |||
By default, Ubiquity assumes that all noun types use external calls. If your noun type does not make external calls, you need to explicitly tell Ubiquity this by adding the property noExternalCalls: true. Example: | |||
<pre> | |||
var noun_type_example = { | |||
label: "example", | |||
noExternalCalls: true, | |||
suggest: function (text, html, callback, selectionIndices) { | |||
....... | |||
} | |||
}; | |||
</pre> | |||
Note: It is important that you inform Ubiquity if your noun type does not use external calls. Ubiquity exhibits different behavior for the noun types depending on whether or not this property is true. If your noun type declares that it doesn't use external calls, Ubiquity will test your noun type during noun-first suggestions. Such that if the first thing the user types into Ubiquity is a noun, all noun types that don't do external calls will be queried to see if they match the input. If a noun matches the input, then associated commands that use that noun will be suggested to the user. | |||
=== Making the most of noun caching === | === Making the most of noun caching === | ||