Pt:Ubiquity 0.1 Author Tutoria: Difference between revisions

You may be wondering why there is a hyphen in the name, instead of a space. That's because the Ubiquity natural language parser isn't yet smart enough to handle commands that are multiple words <i>and</i> arguments that are multiple words. It's something we'll be working on in the future.

== Using CreateCommand ==

For commands that are more complicated than our simple "hello-world" command, you can use the helper function <code>CmdUtils.CreateCommand()</code>, which takes an options dictionary. To redo the "hello-world" command using the convenience function, we'd write:

This may not seem to be much of a win (and it isn't for simple commands) but as the commands become more complex, you'll see that it helps a lot. For one, you can name the command more freely with the method&mdash;unicode non-English characters are now fair game.

There are a number of other useful functions in the CmdUtils namespace. We don't yet have full documentation for these commands, but you'll get a sense of the useful ones in this tutorial. For more detailed information, take a look at the [https://ubiquity.mozilla.com/hg/ubiquity-firefox/raw-file/tip/ubiquity/index.html automatically generated documentation] or [http://hg.toolness.com/ubiquity-firefox/file/9a6c9935da9f/ubiquity/chrome/content/cmdutils.js cmdutils.js].

== Adding a Preview ==

Let's add a preview to our new command. Previews give the user feedback about what a command does before it's executed. Previews are great for providing rich visual feedback like displaying a graphical representation of atmospheric conditions when using the weather command as shown above. Previews have the full expressive power of HTML, including animations, so there's a lot you can do with them.

One point of design: Preview code should never have side-effects. That is, a preview should never (without user interaction) change the state of the system.

For the "hello-world" command, we don't need anything fancy: just some help text that is more descriptive than the default "Executes the hello-world command."

   preview: "Displays a <i>salutary</i> greeting to the planet.",

Here the preview is an HTML-formatted string. The preview can also be a function. We'll get to that in the next section.

= The Date Command: The Second Command =

== Setting the Selection ==

I often forget what day it is. That may be because I need to go outside more often, but, like any programmer, I generally solve my problem's symptoms with technology rather then addressing the root cause. My solution is to create a command that inserts the date at the location of the cursor.

The new function here is <code>setSelection()</code>. This inserts the passed-in text onto the page at the location of the cursor. If the cursor is in an editable text or rich-text fields, the text gets dumped there. If the cursor isn't in an editable area, <code>setSelection()</code> will still be able to insert the date. (Even when it isn't displayed, Firefox always keeps track of a cursor position. To see it, type F7.) Try going to a page, selecting some non-mutable text, and using the command. See, it works! This is particularly useful for commands like "translate", where you want to replace non-editable text with its translation.

The <code>toLocaleDateString()</code> function is native to Javascript, so if you're not familiar with it check out the documentation for the Javascript [http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Reference:Global_Objects:Date Date object].