Labs/Ubiquity/Ubiquity 0.5 User Tutorial
Back to Labs/Ubiquity.
The best way to take this tutorial is by installing Ubiquity and using the interactive tutorial. Use the "help" command.
- 1 In other languages
- 2 Download
- 3 Welcome
- 4 The Basics
- 5 More Command Examples
- 6 Going Further
In other languages
The tutorial hasn't been translated to other languages yet, feel free to jump in and translate.
Install latest version of Ubiquity for Firefox (recommended)
Ubiquity is an experimental Firefox extension that gives you a powerful new way to interact with the Web.
You're used to telling Firefox where you want to go by typing Web addresses into the URL bar:
With Ubiquity installed, you'll be able to tell Firefox what you want it to do by typing commands into a new Ubiquity input box.
Ubiquity commands can do nearly anything. Ubiquity comes with a set of commands that make common Web tasks faster and easier. In this tutorial we'll teach you how to use some of them. By the end of this tutorial you'll be able to perform quick Wikipedia, Google, definition, and Yelp searches; add maps to your email; and translate a snippet of a web page, highlight a word, and then email it to a friend.
The commands that come with Ubiquity are just the beginning: anyone can create new commands and share them. Creating Ubiquity commands — and extending the web — should be as easy as creating a web page. If you want to learn how to create your own commands, please see the Developer Tutorial.
Ubiquity is still a work in progress, and we are eager for you to join our virtual team to experiment. If, when reading this tutorial, you think of a way to make Ubiquity easier to use, or an idea for its future development, we hope you'll take a moment to share your thoughts. By getting involved with Ubiquity while the project is still in its early stages, you have an opportunity to shape the direction of its growth.
on a Mac
You'll need to install Growl. This is a Mac OS X system extension that applications can use to display unobtrusive transparent messages. Ubiquity uses Growl notifications to show you the output of commands and tell you about errors.
On Windows (XP and later), you don't need to install anything special, as Ubiquity will use the operating system's built-in "toaster"-style pop-up messaging.
On Linux, you shouldn't have to do anything special: just make sure you're updated to the latest version of Firefox.
Take the Interactive Tutorial
There is an interactive tutorial that takes you through how to use Ubiquity. You can get to it by typing about:ubiquity into the address bar. This tutorial is meant to supplement the built-in interactive tutorial. It goes over the basics of Ubiquity, some examples of cool things you can do with commands, how to teach Ubiquity new commands, and how to get help with Ubiquity.
If you haven't already done so, install Ubiquity. Once you've done that, you can summon Ubiquity by tapping option-space on the Mac, or control-space if you're on Windows. On Linux, try alt-space
Once you hit the appropriate key-combo, you'll be presented with a command input box in the upper-left of your browser.
You give Ubiquity a command by typing something in here. For the sake of brevity, we'll call this "issuing" a command. For the rest of this tutorial, when we say to "issue 'XYZ'", we mean "hit alt-space (or ctrl-space) to bring up the Ubiquity box, then type XYZ".
First Command: Searching Wikipedia
Let's start with Wikipedia. Say you want to know what a "babel fish" is. You simply issue "wikipedia babel fish".
While you're typing your command, you'll see two things underneath the input box: A suggestion list and a preview of the current command. In the picture below, the suggestion list consists of "wikipedia" and "weather", while the preview says "Searches Wikipedia".
When you finish typing "wikipedia babel fish" you should see some summaries of various Wikipedia pages about Babel Fish, like so:
It will take a moment for the above information to be gleaned from Wikipedia, but Ubiquity stays fully responsive during this time.
Next, you can:
- Hit Enter (or Return) to execute the command. Executing the Wikipedia command has the effect of taking you to the Wikipedia page.
- Hit Escape to cancel the command. Ubiquity disappears with no effect.
- Click on one of the links in the preview. In the case of the Wikipedia preview, clicking a link will take you directly to the article you're interested in.
Abbreviating Commands and Using the Suggestion List
"Wikipedia babel fish" is quite a lot to type. You can save some wear and tear on your fingers by letting Ubiquity's suggestion list do the work for you. As you saw in the last section, bringing up Ubiquity and typing only "w" presents you with suggestions that have "w" in them.
When you add the letter "i", the suggestion list narrows down to suggestions containing "wi". You can use the tab key to auto-complete a command so that Ubiquity stops guessing what you want. Try typing wi, then tab, then "babel fish".
You can also use the arrow keys to select the command you want. Let's say you want to update your Twitter status. Summon Ubiquity and type "t".
The second choice is the "twitter" command. I use the down arrow key to select it:
And then tab to auto-complete "twitter", and type in my status update.
You can see a preview of what your status will be updated to, and how many characters you have left. You also can type "as username" to specify which twitter account you want to use, but that's optional.
Ubiquity also guesses right most of the time if you give it the first few letters of the command you want. So "tw updating my status with Ubiquity" would work too.
Doing Commands on Selections
Often, the thing you're interested in searching for is right in front of you, on the web page you're looking at. Why go to the trouble of re-typing it when you can use what you've already got?
Let's check the weather for Mountain View. Select the words "Mountain View, California" below by dragging your mouse across them:
Mountain View, California
Now summon Ubiquity, and just type the first few letters of the command name:
Or, let's say you're reading a web page and you find an unfamiliar word:
Just select the word and issue "define".
You could have achieved the same thing by typing "define aglet"—or just "def aglet", or even "def this". (Ubiquity understands "this" to refer to the selection.)
More Command Examples
Right now, the email command uses Google Mail. That means you'll only be able to follow along with the next part of the tutorial if you have a GMail account. Eventually, of course, the command should work with all major web-based email providers, as well as applications like Thunderbird. (If you're a programmer, we'd love some help with that.) For now, if you have a GMail account, please make sure you're logged in. If you don't, you might want to skip ahead to the next part of the tutorial.
Assuming you're logged into your GMail account, issue "email". In the suggestion list, you'll see a suggestion that says "Email (message) (to contact)".
This is a clue that the Email command expects two pieces of information: the message is what you're emailing, and the contact is who you want to send it to. However, you can leave out one of these things — or both of them — and the Email command will still work. So I can issue any of these commands:
- "email hello"
- "email to chris"
- "email hello to chris"
- "email to chris hello"
I'm using "chris" because that's the name of someone in my GMail contacts list. If you don't have a "chris" in your contacts list, just substitute the name of any of your friends in these examples.
Let's say I've found an interesting fact on a web page and I want to send it to Chris. I can select part of the page, including links, pictures, and anything else, and then issue "email this to chris". Ubiquity understands "this" to refer to my selection. (I could also have said "email it to chris" or "email selection to chris" -- all of these are equivalent.) The selected part of the page shows up in my preview:
(Actual email addresses blurred out to protect the innocent.) Since I know several people named Chris, there are several lines in the suggestion list -- one each Chris in my GMail contacts list. I can arrow-key down to the Chris I want and then hit the Enter key.
I'm taken to the GMail "compose new email" page. The chunk of the page that I selected is reproduced in the body of my email, the "to" field is filled with the email address I selected, and the "subject" field contains the title of the web page I was on. I can now edit this email to add anything else I want to say, before clicking "Send".
The Map command
Let's say you're arranging to meet up with a friend at a restaurant, and you want to include a map in the email. (Yes, it's Aza's favorite example.)
Type out the address you want to map, then select it and issue "map". In the preview, you'll see a thumbnail-size map of the area (from Google Maps).
If you execute the command, you'll be taken to the Google Maps page. Or, you can click on the image in the preview to get a larger, interactive version. After scrolling and zooming this map to your liking, you can click the "insert map in page" link to insert the map into your email.
You can give it a try by selecting the address below and issuing "map":
1981 Landings Drive, Mountain View, CA
Then click the image in the preview to get the larger map, then click the "insert map in page" link and watch what happens. Surprised?
The Translate command
That's right, Ubiquity commands can alter the contents of a page, even if the page wouldn't normally be editable. A command that makes good use of this ability is the "Translate" command. To try it, select the text below and issue "translate" (or just "tra") and execute.
It's translation-by-machine, so the results are bound to sound awkward, but at least you can get the gist of the meaning.
The full command is
translate (text) (from language) (to language)
So you can specify what language you want to translate from, and what language you want to translate to. If you leave either of these out, Ubiquity will just make a guess about what you want.
Here are some other examples you can try:
- "tr good evening to spanish"
- "tr buenas tardes from spanish to french"
- Select some English text on this page and then: "translate this to german"
Getting Help and Discovering Commands
By now you're probably wondering, "How many commands are there? What are they all called? How am I supposed to know what a command could be unless I memorize them all?"
These are good questions! To start getting some answers, issue the "list ubiquity commands" command, and hit Return to execute it. You'll be taken to a special page listing every command you have installed, and describing what each one does.
For more general help, you can execute the "help" command. Here, you can change the hotkey that you use to activate Ubiquity, unsubscribe from command feeds, enable and disable commands, and find information about support options.
The general help page and the command list page link to each other, so whichever one you open, you can get to the other with a single click.
You can also get to the main help page by typing about:ubiquity into the Firefox URL bar.
Teaching Ubiquity New Commands
We've mentioned that anyone can create Ubiquity commands. Once created, these commands can be embedded in any web page. If you have Ubiquity installed and you visit a page with an embedded command, Firefox will present you with the option of subscribing to the command.
To see this in action, you can visit this example page on Atul's personal site. You should see a bar coming down from the top of the browser window asking you whether you want to subscribe to the command or not.
If you choose to subscribe, you'll see a rather scary-looking warning page:
It's important to understand the dangers of subscribing to Ubiquity commands from sites that you don't trust. Since a Ubiquity command can do anything, and it has full access to your web browser, a bad person could write a Ubiquity command to steal your personal information or do malicious things to your computer. You should not install Ubiquity commands unless you are confident that the source is trustworthy.
Finding New Ubiquity Commands
TODO: Add information about the herd here.
- Check out Planet Ubiquity for the latest and greatest Ubiquity happenings.
- Read and contribute to Ubiquity’s documentation on the Mozilla wiki.
- Get help and help others on our Get Satisfaction page.
- Join the ubiquity-firefox mailing list to discuss Ubiquity with others.
- Join the #ubiquity channel on irc.mozilla.org to talk to Ubiquity community members in real-time over IRC.
- Browse the command library to find Ubiquity commands all over the Internet.
- Report or help fix bugs at our bug tracker.
- Discuss translation and localization issues on the Ubiquity-i18n (internationalization) mailing list.