2
edits
Changes
→Development Hints
</pre>
== Implementing Asynchronous Noun Suggestions ==
The noun types we've seen so far in this tutorial have all worked synchronously, returning their suggestions right away. However, Ubiquity also supports asynchronous noun suggestions. These are useful for when a noun type needs to do some potentially time-consuming work before it can make suggestions — most commonly when it needs to call an external service.
Implementing asynchronous suggestions is simple. Whenever the Ubiquity parser calls a noun type's <code>suggest</code> function, it includes a callback function that may be used to send suggestions back to the parser as they become available. In the most typical case, the noun type's <code>suggest</code> function makes an AJAX request, invoking the parser's callback function from within the callback function for the AJAX request.
Here's a simple example: a noun type that suggests [http://www.freebase.com/ Freebase] topics based on the text the user has typed or selected, and a barebones <code>freebase-lookup</code> command that uses the noun type.
<pre>
var noun_type_freebase_topic = {
_name: "Freebase topic",
suggest: function suggest( text, html, callback ) {
jQuery.ajax( {
url: "http://www.freebase.com/api/service/search",
dataType: "json",
data: { prefix: text, limit: 5 },
success: function suggestTopics( response ) {
var i, results, result;
results = response.result;
for ( i = 0; i < results.length; i++ ) {
result = results[ i ];
callback( CmdUtils.makeSugg( result.name, result.name, result ) );
}
}
} );
return [];
}
}
CmdUtils.CreateCommand( {
name: "freebase-lookup",
takes: { topic: noun_type_freebase_topic },
preview: function preview( container, topic ) {
var text = topic.text || "any topic";
container.innerHTML = "Go to the Freebase topic page for " + text + ".";
},
execute: function goToFreebase( topic ) {
if ( topic ) {
Utils.openUrlInBrowser( "http://www.freebase.com/view" + topic.data.id );
}
}
} );
</pre>
A few notes:
* The parser's callback function expects only one suggestion (not an array of suggestions), so it must be called one time for each suggestion, even if the noun type has multiple suggestions available at the same time (as in the Freebase example above). This is a bit different from the synchronous case, in which the <code>suggest</code> function is expected to return an array.
* A noun type's <code>suggest</code> function typically returns an empty array when it intends to make asynchronous suggestions, but it can return one or more suggestions synchronously if it has them available.
* Because the work being done to generate asynchronous suggestions is generally somewhat expensive, and because a noun type's <code>suggest</code> function may be called for every keystroke the user makes, you should probably consider implementing a delay before starting the work and/or caching the work at some level. Ubiquity currently leaves this up to each noun type individually.
* A much more robust implementation of Freebase-derived noun types can be found [http://graynorton.com/ubiquity/freebase-nouns.html here].
== Running on page load and startup ==
