Labs/Ubiquity/Ubiquity Source Tip Author Tutorial: Difference between revisions

Labs/Ubiquity/Ubiquity Source Tip Author Tutorial (view source)

Revision as of 02:43, 22 June 2009

242 bytes added , 22 June 2009

→‎Introduction to Noun Types

Jdicarlo

1,007

edits

@@ Line 375: / Line 375: @@
 == Introduction to Noun Types ==
-Notice that we specified the type of argument to expect by passing in an object &mdash; in this case, the predefined <code>noun_arb_text</code> object, which accepts any arbitrary text as a valid argument.  If we had wanted to restrict the inputs that our command could take, we could have used a more specific noun-type object to restrict the scope of the argument: for instance, <code>noun_type_date</code> to accept only dates (like the "check-calendar" command) or <code>noun_type_language</code> to accept only names of languages (like the optional modifiers for the "translate" command).
+Noun types specify what ''kind'' of input your command can accept for each one of its arguments.
-The benefit of specifying a more restrictive noun-type is that it helps the Ubiquity parser generate better suggestions and auto-completions based on user-input.  For instance, if the user has a date selected, commands that operate specifically on dates are more likely to be apropos than commands that take arbitrary text, so Ubiquity can suggest the date-specific commands first.
+For the "echo" command, we wanted the object-role argument to accept any text whatsoever, so for its nountype we passed in the predefined <code>noun_arb_text</code> object.  This object accepts any arbitrary text as a valid argument and passes it to the command unchanged.
-Here's an example of what a noun type looks like:
+This is OK for very simple commands, like echoing back the user's input.  But for commands that take structured data, you will want to use more specific nountypes.
-<pre>
-var noun_type_foo = {
+For example, if a command can take a date (like the "check calendar" command), you would want to use <code>noun_type_date</code> as the nountype of the argument.  <code>noun_type_date</code> provides several benefits to your command:  it does all of the date parsing for you; it suggests dates that the user might want to enter (for instance, it defaults to today's date).  And, it lets the parser know that your command takes a date.  This is useful because when the user selects a date on a page and invokes Ubiquity, your command -- along with "check calendar" -- will be one of the top suggestions.
-  _name: "foo",
-  suggest: function( text, html, callback ) {
-  },
-  default: function() {
-  }
-};
-</pre>
-Noun types with built-in implementations that can be used by any command include:
+You can write your own noun types -- we'll get into that later.  For now, let's take a look at the built-in nountypes that your command can use.  These include:
 * noun_arb_text (Arbitrary text)
@@ Line 407: / Line 400: @@
 Once you are familiar with writing commands, you should check out the [http://hg.toolness.com/ubiquity-firefox/file/6caa9d66b3bb/ubiquity/chrome/content/nlparser/en/nountypes.js nountypes.js], which has the implementation for most of the noun-types.  You can see what noun types are already available for your commands to use, what still needs to be written, and where the existing implementations could use improvement &mdash; and then come [[Labs/Ubiquity#Participation|get involved]] to help us improve them.
+Here's an example of what a noun type looks like:
+<pre>
+var noun_type_foo = {
+  _name: "foo",
+  suggest: function( text, html, callback ) {
+  },
+  default: function() {
+  }
+};
+</pre>
 == Insert Email: Commands with Specific Argument Types ==