MozillaWiki - User contributions [en]

Firefox/Feature Brainstorming:Form handling and text areas

2010-04-06T21:33:25Z

Endolith: /* Automatically restore form with text values filled in if submit fails */ grrrrrrrrrrrrrrrr >:(

{{FeatureBrainstorming}}
== Text input field navigation improvements ==

*Allow {TAB}-key navigating 'through input fields only'. Pressing the {TAB}-key lets today's Firefox annoyingly jump to the next hyperlink (!) and option button (!), too, so that it often takes very long to select the next text input field (including the web adress bar and search bar). Hyperlinks and option buttons etc. can be used easier by mouseclicking, but input form fields could be selected faster by {TAB} and {SHIFT}-{TAB}. - [[User:Gutzndaifi|Gutzndaifi]] 09:14, 25 October 2007 (PDT)
*Maybe this can be integrated into an add-on like 'Highlight Focus' by Rudolf Noe, located at [https://addons.mozilla.org/en-US/firefox/addon/1310] etc., but it would be much better to implement it 'as standard'. - [[User:Gutzndaifi|Gutzndaifi]] 09:14, 25 October 2007 (PDT)
*On Firefox for the Mac, allow (TAB)-key navigating between other types of objects in a form. Currently, pressing TAB only navigates between text fields. Please add the ability to navigate to combo boxes, check boxes, radio buttons, buttons, etc. -JK 30 March, 2008
*I love the idea of separate tab queues for forms, links, images, i dunno what else. Forms and links are the two biggies IMHO. This is the only feature the keeps Opera installed on my box. Please Please Please may we have it? :) -CD 23 May, 2008
*Many pages will automatically place the text cursor in a particular text box only after a given percentage of the page has loaded (for example, Gmail places the cursor in the username field). However, one can manually begin information in whatever field before this occurs by clicking on that field. It is frustrating when, in the middle of typing something, the cursor is automatically relocated. Mozilla should include a feature whereby the manual placement of the cursor overrides the auto-placement. 

== Caution User when about to lose form data to the back button ==

*When the back button is pressed (or backspace on the keyboard accidentaly pressed), and some form element on the page has been edited but not submitted, display a dialog telling the user they are about to lose what they typed. The dialog could of course have a checkbox marked do not show this message again.

There is nothing more aggravating than losing a long post because you thought that a text field had focus. This way, 

== Web Forms 2.0 implementation ==
* Allow using of the extended forms. See the standard made by whatwg, which is located at [http://www.whatwg.org/specs/web-forms/current-work]
* Opera browser partially supports it, you can see how useful it can be in FireFox

== External editing of text boxes ==
* Allow an external editor (vim, emacs, textpad, etc) to edit text in form text boxes
* Currently supported by plug-ins, but only on some platforms; should be available everywhere
* Make it embedded in the place of the textarea, without opening another window. Otherwise it would be cumbersome and confusing to keep track of.
* As more and more apps move towards web services, the ability to effectively edit large blocks of text (wikis, blogs, forums, webmail) becomes more and more critical.
* Include ability to save/restore the text box contents.
* Provide a key binding and also bind to right-click/Edit in text areas.
**No, this should be in the form of plugins because it isn't possible to make firefox recognize every text-editing program by default. --[[User:Armaetin|Armaetin]] 15:49, 13 February 2007 (PST)
; References
* [https://bugzilla.mozilla.org/show_bug.cgi?id=103767 bug 103767]
* [https://bugzilla.mozilla.org/show_bug.cgi?id=13474 bug 13474]

== Full featured editing of text areas==
Much writing nowadays is done in text areas: wikis, blogs, forums, webmail. Text areas need full featured editing support:
* Unlimited undo/redo.
* Regular expression search and replace.
* Improve spell checking by switching from MySpell to the far-superior HunSpell (this is a direct descendant of MySpell and is the spell checking system now used by new versions of Open Office). There's a list of all the improvements in [https://bugzilla.mozilla.org/show_bug.cgi?id=319778 bug 319778]. This may also allow us to ship some dictionaries other than En-US in our localized builds (e.g. Hungarian).
* Grammar checking functionality similar to Spell checking (Grammar mistakes is just as prolific an bad spelling)
* The ability of checking multiple languages in a textarea simultaneously.
* Configurable shortcuts and macros.
* Allow easy saving of text area contents on the local machine.
* Automatic safety saves, so that the contents of a text area are never lost.
* Allow resizing of text areas, and splitting into two views.

;See also: [http://ifindkarma.typepad.com/relax/2005/01/life_in_a_texta.html Life in a TEXTAREA] by Adam Rifkin

== WYSIWYG Text Area ==
Enhanced the TEXTAREA tag to provide a WYSIWYG editor that generates HTML code. How many different Javascript, ActiveX, Applet and AJAX solutions exist for this problem? How many of them actually work? None. Let's fix this problem once and do it right. Imagine:

<TEXTAREA NAME="foo" TYPE="wysiwyg">

The user would see a text box with WYSIWYG editing controls. When the form submits, the field would contain HTML code for the user's content. Other browsers would ignore the new flag and display a standard TEXTAREA.

EVERYONE needs this, including this Wiki.
:However we would be breaking the standards, wouldn't we? And i think we shouldn't be trying to do W3C's job.

== Use mouse wheel to modify the values ==

When I'm hovering textarea with number/date and scroll my mouse up/down it should increase/decrease the value.
*This should be optional for those who don't want to accidentally change values when scrolling up or down a page. --[[User:Armaetin|Armaetin]] 15:49, 13 February 2007 (PST)
* This is not usable, because the scroll wheel is used for scrolling the page, as the previous reply said. -[[User:Pgan002|Pgan002]] 18:20, 27 March 2007 (PDT)

== Automatically restore form with text values filled in if submit fails ==
After filling in a long email, blog entry etc. and submitting the form, if the subsequent page fails to load (eg because the Internet connection was lost when you were typing, or because of a temporary problem with page), instead of just showing an error message Firefox should give the user the option to either:
* attempt to submit the data again
or
* return to the previous page with all form items filled in (loaded from offline cache in case Internet connection is still down)
or
* provide a separate page or a tab in Page info where the contents of forms that are sent last are shown.

There should definitely be some way to recover data that has been typed into a form and then lost. Cache everything typed into forms, make it available on an about:textareas page or something, so we can recover our ten minutes of typing even if the page crashes, changes, gets logged out, etc. and Firefox can't figure out how to re-fill it.

== Autofill forms ==

* Like Opera's Wand or Google's Autofill in the Google Toolbar.
* Have an option to fill in your name, address and other information necessary for many websites into Firefox so that when filling out forms you can click a button that 'autofills' them for you.
* Like Internet Explorer - it is best way.
* With Firefox 2, login form fields are only filled in with the login information stored in password manager after loading of the entire page has completed. However, form fields (in particular for login) should be rendered before any other elements on a page, because often all you want to do on a login page is ... to log in. But instead, rendering of a login page often hangs because billions of annoying ad servers take forever to reply to client requests. Rendering (login) forms and filling in the login information first would allow for immediate login, without having to wait until rendering of the whole page is complete -- also contributing to save bandwith, as requests to the billions of annoying ad servers would not be send, or at least cancelled immediately.
* Allow for check boxes to be filled based on the box being highlighted. So that if 10 check boxes are highlighted, you can fill them all in in one task not ten individual button clicks.

== User-created spell check blacklist ==

* Allow users to specify sites that should not have their text areas spell checked (i.e. sites with HTML editing text areas)

== Submit form to new tab/window ==

* Allow users to submit form buttons to a new tab/window
* [https://addons.mozilla.org/en-US/firefox/addon/483 Submit To Tab] Extension by nrlz
* [https://bugzilla.mozilla.org/show_bug.cgi?id=17754 Bug17754] Ability to submit form in a new window / tab
 
'Minor' Edit made; [[User:Nu(-)Ne(Ø)|_(-)(Ø)_]] 21:44, 29 December 2007 (PST)▼
 Apparently, context Menu Items like these aren't a big deal; at least not to the developers who are supposed to implement them, to my awareness thereof. Which is probably Why the Context Menu Item "View Image in New Tab" Option(amongst many other context menu Items mind you) is, Strangely, absent from the context Menu of Images(and to other respective/relevant objects as well) :O. That, or they just forgot about conveniences like that and need to be, reminded ;), ;). 
But I second the notion you've stated for a "Submit in New Window" and "Submit in New Tab" Context menu Item to be added to form like JavaScript based(?) Buttons as I to feel that it was, shall I say, "Left to be desired" :).
 
 
Please remove my input herein, if need be so.
▲

== Change the way the spell checker highlights the misspelled words ==

User interface consistency is important. I think misspelled words should be underlined with a red zigzag line, much like it's done on all modern text processors, instead of the current dotted line.

[added:stk 10-mar-07]
I concur that changing the way the spell checker highlights misspelled words would be a good thing. (Been trying to hack a way, but unsuccessful, so far).

1px dotted red is just a tad too difficult for these old (48ish) eyes to see. Been looking for a way to change text color (magenta, like google-spell does) ... or bg color ... SOMETHING more prominent.

Which leads to another idea - make such behaviors user-set-able in some advanced behaviors tab (including option to point to other user-defined, specialty dictionaries - e.g., Word custom.dic, etc.)?
* I also agree that the spellchecker's highlighting should be changed, although that isn't as high of a priority as many of the other excellent features Firefox still needs. I also agree that the spellchecker's color should be changed to the will of the user, even though I already like red because it parallels with that of MS Word's. By the way, stk, advanced user preferences can be accessed by typing about:config in the address bar, and dictionaries are "stored" in a file named persdict.dat. --[[User:Armaetin|Armaetin]] 11:39, 10 March 2007 (PST)

== Automatically pad text area with blank lines ==

When I am reading a long article, paging down, it is annoying to reach the last page only to find that it is shorter than all the other pages and now my place is lost somewhere in the middle of the screen. I have to hunt for where I left off. I could solve this using the mouse to scroll, and sometimes I do, but I find that more burdensome than just hitting page down. This behavior has existed since the earliest days of the web. It seems to me the easiest way to fix it is for the browser to position the last line of the current page as the first line of the next, no matter what, and fill the rest of the window as needed with blank space. Since I spend most of my web time reading text, consistent text positioning would be a major usability enhancement for me.

'minor' edit made; [[User:Nu(-)Ne(Ø)|_(-)(Ø)_]] 21:57, 29 December 2007 (PST)▼
You know what'd be a sweet Idea?
 # 13 of my list: Memory Markers of some sorts that you can "place" on the page so that when you go down or up the page, right click off the scrollbar and input a # or something, it would send you to the corresponding part of the page. Maybe a Context Menu Item that states something along the lines of "Place memory marker on this currently displayed position" with extra Context Items added to the list and set as Numbers so you can seamlessly scroll anywhere on the current page. I haven't fully gone into the details of its implementation but I'll work on it when I get the proper inspiration.
 Thanks however for your proposal as I often wondered if anyone else had the same Idea ;).
 
 
Please remove my input herein, if need be so. ▲

== Drag and dropping files into textboxes ==

* Allow users to drag and drop a local text/HTML file into a text box to insert the content of the file instead of its path.

== Thesaurus and Form Information Spell Check ==
There should be a submenu (similarly to the "Language" submenu) that lists the synonym of the right-clicked word.
*A submenu for antonyms, as per the synonyms in the previous bullet.
*An easier way to edit and update Firefox's dictionary without manually going into persdict.dat.
*Grammar Check

== Clipboard: A Modified Copy/Paste Functionality ==
What a clipboard would do:
* Firefox should add all objects we copy into a clipboard.
* The clipboard is accessible via a sidebar.
* Double-clicking an entry on the clipboard pastes the item, if appropriate.
* The clipboard is cleared after every session.
* A user can "merge" items on the clipboard. What this means is that a user can select multiple items on the clipboard (the same way multiple icons are selected on a desktop: using the Ctrl/Cmd key) and consolidate them into one item. This is for simplicity purposes, ie a user wants to paste everything on Firefox's clipboard into an external application.
Notes:
* Ideally, a clipboard should hold as many entries as possible.
* Unlike the floating clipboard in Microsoft Office programs, the clipboard should behave as a sidebar or toolbar.
* The clipboard does not affect copy and paste in any way. It merely pastes all instances of copying into its memory. Pasting an item from the clipboard merely copies the item from the history and pastes it, as if the user did it manually.
* The order of the items on a clipboard can be sorted via up/down buttons.

'Minor edit' made [[User:Nu(-)Ne(Ø)|_(-)(Ø)_]] 22:13, 29 December 2007 (PST)▼
You know, on KDE we have this thing called Klipper. It is shear Awesomeness! It is, or can be, almost as your description depicts. Except, its a Tray Icon instead of a sidebar. I don't think a sidebar would be very, space friendly, you know? Floating clipboard provide ease of access and is space considerate. I think the problem would be, as I am assuming, that it would get in the way of the cursor sometimes. I don't see why we can't have it as, a Sidebar, Toolbar, and Float. Just Position it to the right or left pane for sidebar preference, Up near the top for Toolbar preferences, and anywhere in between for floating preferences with context options for displaying said clipboard as such.
 
Still that would be a good thing to have when you want to download many specific things from a page while Browsing using Firefox :).
 
Please remove my input herein, if need be so.▲

== Allow specified textareas to expand with the size of the window ==
When editing large text, such as email, wiki, code and others, it is convenient to have the as large as possible an area to view it through. But when the browser window itself is too small, you end up with two horizontal and/or two vertical scrollbars. It wold be great if some specified text areas and text boxes could expand and contract with the size of the window.
*I agree, and I also think Firefox should give users the option of having the ability to manually set how large certain fields are. --[[User:Armaetin|Armaetin]] 22:57, 22 January 2007 (PST)

== Auto-Correction ==
Microsoft Word automatically corrects commonly misspelled words (ie, changing "teh" to "the"). Perhaps Firefox should do the same:
*The undo command (Ctrl+Z) would undo an auto-correct, if the user had intended to spell the word incorrectly.
*There would be an auto-correction dictionary (separate from the current dictionary) in which users can place their own entries on what Firefox auto-corrects and remove some of Firefox's default auto-correction entries (if, for example, "teh" was actually a word in that user's regular vocabulary and that user does not like how Firefox keeps changing "teh" into "the").

== Record and Play Macros ==
Some forms require clicking a series of routine "submit" buttons. Some of the button-clicking has to do with accepting security certificates. It's good that Firefox can remember the user IDs and passwords. It'd be better if Firefox allows us to "record" the sequence of button clicking as a macro files, and allows us (end users, not Web masters) to replay those macro files with a single click of a button.

----
--[[User:Paulmackinlay|Paulmackinlay]] 04:42, 25 May 2007 (PDT)
This feature would be very useful and can be extended further to be even more useful. If the macros could be saved, categorised, edited this could form the basis of a powerful web testing suite. Firefox has always had great web-app developer aids and this would be certainly one of the most useful since it could be used to generate test suites which would be fully automated functional tests. It would ensure the web-app it behaving as expected with the current version of gecko and rhino.

Assertions would need to be made available, which would indicate if a test passes or fails. It would also be useful to modify parameters such as domain name and port so that the same tests can be executed on more than one environment.

Actually, there is a great piece of software called Badboy[http://www.badboy.com.au/] which does something similar, it has a lot of excellent features. Unfortunately it is only available for a specific OS and becuase it is not portable I can't use it. I appreciate that web-app testing is probably beyond the scope of core Firefox but maybe a seperate component/plug that does this could be considered.

----
[[User:Glest|Glest]] 03:19, 19 February 2008 (PST)
I don't really like the idea of building a macro system in a browser. It would make it very easy to spam forms. I know it's already easy, but atleast there is no standard browser function called "Spam form".

== Searchable button labels ==
Make button labels searchable, so that you can text search (for example) this page for "Search" and have the cursor on the "Search" button at the top. This would help with navigation, especially in large webpages. First, like text search in general, it allows the focus to be positioned directly without using a pointing device, which is often faster. Second, there is often a specific button or function (such as search) which users want to use and have to scroll through the page and look for it manually. -[[User:Pgan002|Pgan002]] 15:07, 8 May 2007 (PDT)

== Easy clearing of bad completions ==
Add an "X" button to the end of each line in the completion list that removes the entry. This would allow you to get rid of accidental typos in previous forms that will pop up (without having to clear ALL the form completion data.) -[[User:EricBayer|EricBayer]] 22:10, 3 July 2007
* I think this should be optional because it might be aesthetically displeasing to some. I am assuming Mr. EricBayer is unaware that he can get rid of saved form entries using Shift+Delete? --[[User:Armaetin|Armaetin]] 22:48, 3 July 2007 (PDT)

== Remember chosen language for every text area on every page ==
For polyglot users, the Spell Checker loses much of its appeal, because you must manually switch the language every time you switch between languages.

If the checker simply remembered the language I chose for each web page and on a second level for each text area on that web page (probably hard to impossible), it would greatly simplify writing for polyglot users. So, if I write on English wikipedia it first checks which language header the web site sent and if I don't agree with that setting, I can choose my own - maybe British English, even though Wikipedia sends US-English headers - and the checker will remember my choice, when I revisit the page.

Another idea would be auto-recognition and multiple languages, but that's not too easy I guess, especially if the detection is based on the users misspellings.
I don't know whether there already is some sort of JS-Handler, but if web sites could tamper with Firefoxes Spell checker, they could suggest the right language right away - and annoy users a lot if they have bad intentions, of course.
--[[User:Rubenarslan|Rubenarslan]] 09:11, 4 November 2007 (PST)

Labs/Ubiquity/Parser 2 API Conversion Tutorial

2009-07-19T00:02:33Z

Endolith:

== Intro ==

Ubiquity 0.5 introduces an updated command API, reflecting the changes in [[Labs/Ubiquity/Parser_2|the parser]] as well as the new [[Labs/Ubiquity/Ubiquity_0.5_Making_Commands_Localizable|ability to localize (some) commands]]. This tutorial will walk you through some of the key changes you will need to make. If you are interested in writing a new Ubiquity command from scratch, please refer to the [[Labs/Ubiquity/Ubiquity_Source_Tip_Author_Tutorial|updated Command Authoring Tutorial]].

== A note on (backwards) compatibility ==

Please note that Ubiquity 0.5 by default uses Parser 2 and Parser 1 (and the Parser 1 API) will be deprecated in the future. For the time being, however, it is possible to use Parser 1 in Ubiquity 0.5 by going to the Ubiquity settings page and turning off "use Parser 2".

=== Parser 1 API commands in Parser 2 ===

[[Image:Ubiquity_Old_API_badge.png|right]]

All commands in the previous style (Parser 1 API) will be marked with an Old API badge in the Ubiquity command list, as seen on the right. Of these commands, those which do not take any arguments (no modifiers and no direct objects, in the Parser 1 API lingo) will be automatically converted and made to work with Parser 2, but all others will be ignored by Parser 2.

=== Parser 2 API commands in Parser 1 ===

While Parser 2 commands were built with some backwards compatibility in mind, there are some notable limitations. With Ubiquity 0.5 in Parser 1 mode (the "Use Parser 2" setting turned off), Parser 2 commands should be usable but they will only respond to specific prepositions. For example, a command which expects a <code>location</code> will only work with the preposition "near" rather than "near," "on," and "at," which all work for this argument with Parser 2 (see below for more information on semantic roles). In addition, commands will only work in English and localization does not work in Parser 1 mode.

Note, however, that Parser 2-style commands will ''not'' work at all in Ubiquity 0.1.x installs.

We strongly encourage that all community commands be rewritten in Parser 2 format to take advantage of new (and upcoming) features.

=== Supporting both Parser 1 and Parser 2 in Your Command Feed ===

There is a property added to the Command API that allows you to present different commands to clients running Parser 1 and Parser 2, called CmdUtils.parserVersion. A command can provide different options to CmdUtils.CreateCommand() and behave differently depending on this value, allowing a single command feed to cater to whatever parser the user is using.

if (CmdUtils.parserVersion == 2) {
//parser 2 command here
} else {
//parser 1 command here
}

== Converting your command ==

=== <code>names</code> ===

Where Parser 1 expected a single default verb name in the property <code>name</code> and possible synonyms in an optional <code>synonyms</code> property, Parser 2 requires that there be a single <code>names</code> property with an array of possible verb names.

'''Parser 1 (old) API:'''

CmdUtils.CreateCommand({
name: 'find',
synonyms: ['look-for', 'search'],
...

'''Parser 2 (new) API:'''

CmdUtils.CreateCommand({
names: ['find', 'look for', 'search'],
...

Note also that command names may now include spaces. (Hurray!)

=== Specifying semantic roles ===

The biggest change in the Parser 2 API is that arguments are now specified using abstract ''semantic roles'' instead of language-specific markers. (See [[Labs/Ubiquity/Parser_2/Semantic_Roles|Semantic roles in Parser 2]] for further explanation of semantic roles and the rationale for this change.) Arguments which previously were specified in <code>takes</code>, direct objects, use the role "object". Arguments which were specified in <code>modifiers</code> are specified using different semantic roles, based on the grammatical function of the argument, instead of by its English preposition. For example, an argument introduced by "to" would now be marked with the role <code>goal</code>, and an argument introduced by "using" would be encoded as <code>instrument</code>. These arguments are then all specified together with their nountypes in an array as property <code>arguments</code>.

'''Parser 1 (old) API:'''

CmdUtils.CreateCommand({
...
takes: {query: noun_arb_text}
modifiers: {'using': noun_type_searchengine}
...

'''Parser 2 (new) API:'''

CmdUtils.CreateCommand({
...
arguments: [ {role: 'object', nountype: noun_arb_text, label: 'query'},
{role: 'instrument', nountype: noun_type_searchengine} ],
...

Please refer to [[Labs/Ubiquity/Parser_2/Semantic_Roles|Semantic roles in Parser 2]] for a list of supported semantic roles with examples of their use. Note that the <code>label</code> parameter (used in specifying the <code>object</code> argument above) is optional.

In addition, the old-style (but rare) <code>DOType</code> and <code>DOLabel</code> specifications are also no longer supported.

=== Using semantic roles in <code>preview</code> and <code>execute</code> ===

As arguments are specified using semantic roles, arguments are then passed to the <code>preview</code> and <code>execute</code> methods based on their arguments as well. Both methods are handed an object with the semantic roles as the keys, and the argument data as the values, e.g.

{ object: { text: 'chicken',
data: 'chicken',
... },
instrument: { text: 'goo',
data: 'Google',
... }
}

Note that the structure of the argument data itself (with requisite properties <code>text</code>, <code>data</code>, and <code>html</code>) is the same as with the Parser 1 API.

Instead of handing the direct object's data and the other arguments' data separately to <code>preview</code> and <code>execute</code>, Parser 2 hands it to them together as one argument:

'''Parser 1 (old) API:'''

CmdUtils.CreateCommand({
...
preview: function(pblock, object, modifiers) {
var data = {};
data.query = object.text;
data.engine = modifiers.using.text;
pblock.innerHTML = CmdUtils.renderTemplate(
"Searching for ${query} using ${engine}.",
data );
},
execute: function(object, modifiers) {
var data = {};
data.query = object.text;
data.engine = modifiers.using.text;
displayMessage(CmdUtils.renderTemplate(
"Searching for ${query} using ${engine}.",
data );
},
...

'''Parser 2 (new) API:'''

CmdUtils.CreateCommand({
...
preview: function(pblock, args) {
var data = {};
data.query = args.object.text;
data.engine = args.instrument.text;
pblock.innerHTML = CmdUtils.renderTemplate(
"Searching for ${query} using ${engine}.",
data );
},
execute: function(args) {
var data = {};
data.query = args.object.text;
data.engine = args.instrument.text;
displayMessage(CmdUtils.renderTemplate(
"Searching for ${query} using ${engine}.",
data );
},
...

As always, it is best to first check whether the requisite arguments were filled in the parser before using it.

=== Making your command localizable ===

More detailed information on making commands localizable can be found in the tutorial [[Labs/Ubiquity/Ubiquity_0.5_Making_Commands_Localizable|Making Commands Localizable]].

Ubiquity doesn't yet support the localization of commands which are not bundled with Ubiquity itself. However, the localization of community commands is being planned, so making your command localizable now will future-proof your command and will later open your command up to a much wider target audience.

In addition to the Parser 2 API changes listed above, the main change to be made is to wrap any localizable strings in your <code>preview</code> and <code>execute</code> methods with the function <code>_()</code>. This <code>_()</code> command (familiar to anyone with prior experience with [http://en.wikipedia.org/wiki/Gettext Gettext]) handles the localization by finding the appropriate matching localized string on preview or execution.

displayMessage(_('No results were found.'));

In the case above, <code>_()</code> will then take care of finding appropriate localizations of the string "No results were found" for your command and, if available, display that string instead.

The <code>_()</code> function also handles [http://code.google.com/p/trimpath/wiki/JavaScriptTemplates <code>renderTemplate</code>ing] if you also give it an object with replacement variables. For examples, you can write the following:

displayMessage(_("${number} results found.", {number: numOfResults}))

By default, this will display, for example, "3 results found." if <code>numOfResults == 3</code> and something like "Il y a 3 résultats" given a French localization of "Il y a ${number} résultats". This templating can also be used to handle pluralization—please refer to [[Labs/Ubiquity/Ubiquity_0.5_Making_Commands_Localizable|Making Commands Localizable]] for more information.

There is no need to wrap any properties of the commands (<code>names</code>, <code>help</code>, <code>author</code>, etc.) in <code>_()</code>, nor do you need to wrap string previews in <code>_()</code>, in order for the command to be localizable. These direct properties of the command are automatically localizable as long as they are set in the original command.

More tips on making strings localizable can be found in [[Labs/Ubiquity/Ubiquity_0.5_Making_Commands_Localizable|Making Commands Localizable]].

== References ==
* [[Labs/Ubiquity/Ubiquity_Source_Tip_Author_Tutorial|The updated Command Authoring Tutorial]]
* [[Labs/Ubiquity/Parser_2/Semantic_Roles|Semantic roles in Parser 2]]: a list of supported semantic roles with explanations and examples
* [[Labs/Ubiquity/Ubiquity_0.5_Making_Commands_Localizable|Making your command localizable]]

Labs/Ubiquity/Parser 2 API Conversion Tutorial

2009-07-18T23:23:27Z

Endolith:

== Intro ==

Ubiquity 0.5 introduces an updated command API, reflecting the changes in [[Labs/Ubiquity/Parser_2|the parser]] as well as the new [[Labs/Ubiquity/Ubiquity_0.5_Making_Commands_Localizable|ability to localize (some) commands]]. This tutorial will walk you through some of the key changes you will need to make. If you are interested in writing a new Ubiquity command from scratch, please refer to the [[Labs/Ubiquity/Ubiquity_Source_Tip_Author_Tutorial|updated Command Authoring Tutorial]].

== A note on (backwards) compatibility ==

Please note that Ubiquity 0.5 by default uses Parser 2 and Parser 1 (and the Parser 1 API) will be deprecated in the future. For the time being, however, it is possible to use Parser 1 in Ubiquity 0.5 by going to the Ubiquity settings page and turning off "use Parser 2".

=== Parser 1 API commands in Parser 2 ===

[[Image:Ubiquity_Old_API_badge.png|right]]

All commands in the previous style (Parser 1 API) will be marked with an Old API badge in the Ubiquity command list, as seen on the right. Of these commands, those which do not take any arguments (no modifiers and no direct objects, in the Parser 1 API lingo) will be automatically converted and made to work with Parser 2, but all others will be ignored by Parser 2.

=== Parser 2 API commands in Parser 1 ===

While Parser 2 commands were built with some backwards compatibility in mind, there are some notable limitations. With Ubiquity 0.5 in Parser 1 mode (the "Use Parser 2" setting turned off), Parser 2 commands should be usable but they will only respond to specific prepositions. For example, a command which expects a <code>location</code> will only work with the preposition "near" rather than "near," "on," and "at," which all work for this argument with Parser 2 (see below for more information on semantic roles). In addition, commands will only work in English and localization does not work in Parser 1 mode.

Note, however, that Parser 2-style commands will ''not'' work at all in Ubiquity 0.1.x installs.

We strongly encourage that all community commands be rewritten in Parser 2 format to take advantage of new (and upcoming) features.

=== Supporting both Parser 1 and Parser 2 in Your Command Feed ===

There is a property added to the Command API that allows you to present different commands to clients running Parser 1 and Parser 2, called CmdUtils.parserVersion. A command can provide different options to CmdUtils.CreateCommand() and behave differently depending on this value, allowing a single command feed to cater to whatever parser the user is using.

if (CmdUtils.parserVersion == 2) {
//parser 2 command here
} else {
//parser 1 command here
}

== Converting your command ==

=== <code>names</code> ===

Where Parser 1 expected a single default verb name in the property <code>name</code> and possible synonyms in an optional <code>synonyms</code> property, Parser 2 requires that there be a single <code>names</code> property with an array of possible verb names.

'''Parser 1 (old) API:'''

CmdUtils.CreateCommand({
name: 'find',
synonyms: ['look-for', 'search'],
...

'''Parser 2 (new) API:'''

CmdUtils.CreateCommand({
names: ['find', 'look for', 'search'],
...

Note also that command names may now include spaces. (Hurray!)

=== Specifying semantic roles ===

The biggest change in the Parser 2 API is that arguments are now specified using abstract ''semantic roles'' instead of language-specific markers. (See [[Labs/Ubiquity/Parser_2/Semantic_Roles|Semantic roles in Parser 2]] for further explanation of semantic roles and the rationale for this change.) Arguments which previously were specified in <code>takes</code>, direct objects, use the role "object". Arguments which were specified in <code>modifiers</code> are specified using different semantic roles, based on the grammatical function of the argument, instead of by its English preposition. For example, an argument introduced by "to" would now be marked with the role <code>goal</code>, and an argument introduced by "using" would be encoded as <code>instrument</code>. These arguments are then all specified together with their nountypes in an array as property <code>arguments</code>.

'''Parser 1 (old) API:'''

CmdUtils.CreateCommand({
...
takes: {query: noun_arb_text}
modifiers: {'using': noun_type_searchengine}
...

'''Parser 2 (new) API:'''

CmdUtils.CreateCommand({
...
arguments: [ {role: 'object', nountype: noun_arb_text, label: 'query'},
{role: 'instrument', nountype: noun_type_searchengine} ],
...

Please refer to [[Labs/Ubiquity/Parser_2/Semantic_Roles|Semantic roles in Parser 2]] for a list of supported semantic roles with examples of their use. Note that the <code>label</code> parameter (used in specifying the <code>object</code> argument above) is optional.

In addition, the old-style (but rare) <code>DOType</code> and <code>DOLabel</code> specifications are also no longer supported.

=== Using semantic roles in <code>preview</code> and <code>execute</code> ===

As arguments are specified using semantic roles, arguments are then passed to the <code>preview</code> and <code>execute</code> methods based on their arguments as well. Both methods are handed an object with the semantic roles as the keys, and the argument data as the values, e.g.

{ object: { text: 'chicken',
data: 'chicken',
... },
instrument: { text: 'goo',
data: 'Google',
... }
}

Note that the structure of the argument data itself (with requisite properties <code>text</code>, <code>data</code>, and <code>html</code>) is the same as with the Parser 1 API.

Instead of handing the direct object's data and the other arguments' data separately to <code>preview</code> and <code>execute</code>, Parser 2 hands it to them together as one argument:

'''Parser 1 (old) API:'''

CmdUtils.CreateCommand({
...
preview: function(pblock, object, modifiers) {
var data = {};
data.query = object.text;
data.engine = modifiers.using.text;
pblock.innerHTML = CmdUtils.renderTemplate(
"Searching for ${query} using ${engine}.",
data );
},
execute: function(object, modifiers) {
var data = {};
data.query = object.text;
data.engine = modifiers.using.text;
displayMessage(CmdUtils.renderTemplate(
"Searching for ${query} using ${engine}.",
data );
},
...

'''Parser 2 (new) API:'''

CmdUtils.CreateCommand({
...
preview: function(pblock, args) {
var data = {};
data.query = args.object.text;
data.engine = args.instrument.text;
pblock.innerHTML = CmdUtils.renderTemplate(
"Searching for ${query} using ${engine}.",
data );
},
execute: function(args) {
var data = {};
data.query = args.object.text;
data.engine = args.instrument.text;
displayMessage(CmdUtils.renderTemplate(
"Searching for ${query} using ${engine}.",
data );
},
...

As always, it is best to first check whether the requisite arguments were filled in the parse before using it.

=== Making your command localizable ===

More detailed information on making commands localizable can be found in the tutorial [[Labs/Ubiquity/Ubiquity_0.5_Making_Commands_Localizable|Making Commands Localizable]].

Ubiquity doesn't yet support the localization of commands which are not bundled with Ubiquity itself. However, the localization of community commands is being planned, so making your command localizable now will future-proof your command and will later open your command up to a much wider target audience.

In addition to the Parser 2 API changes listed above, the main change to be made is to wrap any localizable strings in your <code>preview</code> and <code>execute</code> methods with the function <code>_()</code>. This <code>_()</code> command (familiar to anyone with prior experience with [http://en.wikipedia.org/wiki/Gettext Gettext]) handles the localization by finding the appropriate matching localized string on preview or execution.

displayMessage(_('No results were found.'));

In the case above, <code>_()</code> will then take care of finding appropriate localizations of the string "No results were found" for your command and, if available, display that string instead.

The <code>_()</code> function also handles [http://code.google.com/p/trimpath/wiki/JavaScriptTemplates <code>renderTemplate</code>ing] if you also give it an object with replacement variables. For examples, you can write the following:

displayMessage(_("${number} results found.", {number: numOfResults}))

By default, this will display, for example, "3 results found." if <code>numOfResults == 3</code> and something like "Il y a 3 résultats" given a French localization of "Il y a ${number} résultats". This templating can also be used to handle pluralization—please refer to [[Labs/Ubiquity/Ubiquity_0.5_Making_Commands_Localizable|Making Commands Localizable]] for more information.

There is no need to wrap any properties of the commands (<code>names</code>, <code>help</code>, <code>author</code>, etc.) in <code>_()</code>, nor do you need to wrap string previews in <code>_()</code>, in order for the command to be localizable. These direct properties of the command are automatically localizable as long as they are set in the original command.

More tips on making strings localizable can be found in [[Labs/Ubiquity/Ubiquity_0.5_Making_Commands_Localizable|Making Commands Localizable]].

== References ==
* [[Labs/Ubiquity/Ubiquity_Source_Tip_Author_Tutorial|The updated Command Authoring Tutorial]]
* [[Labs/Ubiquity/Parser_2/Semantic_Roles|Semantic roles in Parser 2]]: a list of supported semantic roles with explanations and examples
* [[Labs/Ubiquity/Ubiquity_0.5_Making_Commands_Localizable|Making your command localizable]]

Labs/Ubiquity/Ubiquity 0.5 Author Tutorial

2009-07-11T00:28:07Z

Endolith:

Back to [[Labs/Ubiquity]].

Author: Aza Raskin, Blair McBride, Abimanyu Raja, Jono DiCarlo, Atul Varma

= The Ubiquity version 0.5 Command Tutorial =

The great power of Ubiquity—from a developer standpoint—is how easy it is to create commands. With only a couple of lines of Javascript, Ubiquity enables even casual web developers to drastically enhance the features of the browser. From an 8-line command to insert a contact's email address in any text field, to a 50-line Twitter integration, this tutorial walks you through the process of being generative with Ubiquity.

The rest of this page documents the command developer API as it stands frozen in version 0.5.

If you want the bleeding-edge command developer API (which includes any new features that may have been added to the Ubiquity source code in HG but not yet included in a release), then that's [[Labs/Ubiquity/Ubiquity_Source_Tip_Author_Tutorial|here]].

If you want the old command developer API, as it stood in Ubiquity 0.1 (not recommended), that's [[Labs/Ubiquity/Ubiquity_0.1_Author_Tutorial|here]].

== Real Time Development ==

Ubiquity doesn't require you to restart Firefox as you develop. Restarting is a drastic measure, and we want none of it. Instead, Ubiquity reloads the commands every time it is summoned. When you are using the built-in editor then you don't even need to save!

To open the Ubiquity command editor, summon Ubiquity (control/alt + space) and use the "open command editor" command. Throughout this tutorial, when we want you to run a command in Ubiquity, we'll say '''Ubiq''' it. For instance, to open the editor, just Ubiq "open command editor".

In the following examples, just type in this editor. Updates happen the next time you summon Ubiquity.

== Choices, Choices... ==

You may notice a drop-down menu mentioning something about a "feed type" just above the editing field in the command editor:

http://www.toolness.com/images/20090318121423.jpg

For now, just make sure this drop-down is set to "Regular". We'll tell you more about what this means later.

= Hello World: The First Command =

== Just a Message: As Simple as it Gets ==

Let's start with the standard programing trope: printing "Hello, World!".

In the command editor type the following:

<pre>
CmdUtils.CreateCommand({
names: ["say hello"],
execute: function() {
displayMessage( "Hello, World!");
}
});
</pre>

Now try Ubiq-ing "say hello". You'll see that "Hello, World!" is immediately displayed on the screen. If you are on Mac OSX with [http://en.wikipedia.org/wiki/Growl_(software) Growl] installed the message will appear as a Growl notification. If you are on Windows, then it will appears as a standard "toaster" notification in the bottom right-hand corner of the screen.

http://farm3.static.flickr.com/2479/3651542339_022e4aa4c4.jpg

http://img517.imageshack.us/img517/7726/picture2vx2.png

In Ubuntu 8.04 (Hardy Heron) this appears thus:

http://img293.imageshack.us/img293/7746/ubiqubuntuhelloworldeq9.png

If you don't have Growl installed on OSX, or aren't on a Windows XP/Vista or Ubuntu Hardy, then you won't get any sort of notification. That's something to be [http://labs.toolness.com/trac/ticket/19 worked on] in future releases of Ubiquity.

=== CmdUtils.CreateCommand ===

<code>CmdUtils</code> is a namespace which contains all the functions you need to create commands. Commands are created by making an object and passing it to <code>CmdUtils.CreateCommand</code>. In Javascript, inline curly braces mean "new object", so this code:

<pre>
{
names: ["say hello"],
execute: function() { //etc }
}
</pre>

means "Make an object with two attributes, 'names' and 'execute'." This object is then passed as the argument to <code>CmdUtils.CreateCommand</code>.

=== names ===

'names' and 'execute' are the only two mandatory attributes for your command object. 'names' specifies what the command is called, and 'execute' specifies what it does. There are plenty of other attributes that you can specify, but they are all optional.

'names' is always an array (thus the square brackets). In the case of this command we provided only one name, "hello world". But we could have provided as many names as we wanted. For instance, if we had said:

names: ["say hello", "greet"]

then "say hello" would be the normal name of the command, but Ubiquity would also recognize "greet" as a synonym or alias for the command.

=== execute ===

'execute' is always a function. When the user executes your command, this is the function that will be run. It can do pretty much anything you want -- or at least, anything you know how to write in JavaScript.

In the example above, we simply call <code>displayMessage()</code>, which displays the given message in whichever way the operating system can.

There are a number of other useful functions in the <code>CmdUtils</code> 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 [http://hg.toolness.com/ubiquity-firefox/file/9a6c9935da9f/ubiquity/chrome/content/cmdutils.js cmdutils.js].

=== Making sure your command is localizable ===

Ubiquity now supports multiple languages. That means that hopefully someday someone will be translating your commands to the other languages that Ubiquity supports. Making your command localizable is easy, and a good habit to get into! You just have to locate all strings that appear in your <code>preview()</code> and <code>execute()</code> methods, that are intended for display to humans, and wrap them with:

_()

This may look odd, but what it does is quite important: it makes your strings appear in the template files that localizers will be using. So let's make our "Hello world!" command localizable:

<pre>
CmdUtils.CreateCommand({
names: ["say hello", "greet"],
execute: function() {
displayMessage( _("Hello, World!") );
}
});
</pre>

This makes it so that when a localization template is generated from your command feed, "Hello, World!" will be listed among the strings to be translated.

Note that we don't need to wrap the names, or other strings that appear in the command metadata -- these are automatically wrapped for us. We only need to wrap strings that appear inside the functions.

== Adding a Preview ==

http://img352.imageshack.us/img352/1002/picture3ex0.png

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 "say hello" command, we don't need anything fancy: just some help text that is more descriptive than the default "Executes the say hello command."

<pre>
CmdUtils.CreateCommand({
names: ["say hello", "greet"],
preview: "Displays a salutary greeting to the planet.",
execute: function() {
displayMessage( _("Hello, World!") );
}
})
</pre>

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.

<pre>
CmdUtils.CreateCommand({
names: ["insert date"],
execute: function() {
var date = new Date();
CmdUtils.setSelection( date.toLocaleDateString() );
}
})
</pre>

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>toLocalDateString()</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].

== A Better Preview ==

It's time to add a better preview to the date command. Let's have the preview show the date, so that the user will know what to expect when they execute the command. (As a side benefit the user doesn't even need to execute the command to do a quick check of the day.)

<pre>
CmdUtils.CreateCommand({
names: ["insert date"],

_date: function(){
var date = new Date();
return date.toLocaleDateString();
},

preview: function( pblock ) {
var msg = _('Inserts today's date: "${date}"');
pblock.innerHTML = CmdUtils.renderTemplate( msg, {date: this._date()} );
},

execute: function() {
CmdUtils.setSelection( this._date() );
}
})
</pre>

We've done three things here. The first was to factor out the code for getting the date into the <code>_date()</code> function. This way we don't break [http://en.wikipedia.org/wiki/Don%27t_repeat_yourself DRY] by repeating code across the preview and execute functions. Notice that to access the <code>_date()</code>, we use the <code>this</code> keyword.

The second thing we've done is to add a preview function. The first argument is the DOM element that gets displayed as the preview for your command. Modify <code>pblock</code> and you modify the preview. In this case, we set the <code>innerHTML</code> of the preview block to be the message we want.

The third thing we've done is to do some string formatting using the <code>renderTemplate()</code> function. This takes a template string and performs the appropriate substitution given the passed-in JSON object. Templates can handle a wide range of functionality, as we are currently using TrimPath's [http://code.google.com/p/trimpath/wiki/JavaScriptTemplates JavascriptTemplates]. You should read their site for more documentation. Although JavascriptTemplates has some nice properties, we are contemplating moving to [http://mjtemplate.org/ MJT] sometime soon.

=== A shortcut for localization and rendering templates ===

Note how in the code above, we used the localization wrapper <code>_()</code> before passing the string to renderTemplate. Because this is such a very common combination when displaying strings, we have a shortcut for it. Calling _() with a JSON object as the second argument will automatically trigger <code>CmdUtils.renderTemplate()</code> on the post-localization string. So the above preview method could be rewritten more simply as:

<pre>
preview: function( pblock ) {
var msg = 'Inserts today's date: "${date}"';
pblock.innerHTML = _( msg, {date: this._date()} );
},
</pre>

=== Networking calls and placeholder previews ===

Previews display something meaningful to the user immediately. If you have a preview that requires an AJAX request—say, to fetch some search results—that call might take a while to return. In the meantime, your command should display a placeholder preview giving the user feedback.

<pre>
preview: function( pblock ) {
pblock.innerHTML = _("This will show until the AJAX request returns");
// AJAX request
pblock.innerHTML = getFromServer();
},
</pre>

In the future, we may work on streamlining this process.

== Documentation and Metadata ==

Before you share your command with the world, you should consider adding some attributions to the code:

<pre>
CmdUtils.CreateCommand({
names: ["insert date"],
homepage: "http://azarask.in/",
author: { name: "Aza Raskin", email: "aza@mozilla.com"},
contributors: ["Atul Varma"],
license: "MPL",

/* THE REST OF THE CODE HERE */
})
</pre>

And you should definitely add some documentation:

<pre>
CmdUtils.CreateCommand({
names: ["insert date"],
homepage: "http://azarask.in/",
author: { name: "Aza Raskin", email: "aza@mozilla.com"},
contributors: ["Atul Varma"],
license: "MPL",
description: "Inserts today's date.",
help: "If you're in an editable text area, inserts today's date, formatted for the current locale.",

/* THE REST OF THE CODE HERE */
})
</pre>

The <code>.description</code> and <code>.help</code> attributes are both automatically displayed alongside your command's name on the command-list page. (The user can get to this page at any time by issuing the "list ubiquity commands" command.) HTML tags can be used in both of these strings.

Description is a one-line summary of what the command does, while Help is a longer description that can include examples, caveats, and so on. If your command is simple enough that all you have to say about it fits in one line, it's OK to use a description alone and leave out the help.

== Sharing it with the World ==

Now that we've got our awesome new "date" command, let's share it with the world. All you have to do is put it the javascript file on the web somewhere, and make an html page linking to it with "link rel".

<pre><link rel="commands" href="http://path-to-js" name="Title Goes Here" /></pre>

Anyone with Ubiquity who visits will get a message offering them the choice of subscribing to your command.

[[Image:Subscribe.png]]

If the user chooses to subscribe to a Regular command feed from an untrusted source, they will get a security warning message before they can install the command. Because Regular Ubiquity command feeds can execute arbitrary javascript with chrome privileges, subscribing to a command from a website means allowing that site full access to do whatever it wants to your browser. We want to make sure people understand the dangers before subscribing to commands, so we made the warning page pretty scary.

[[Image:Warning.PNG]]

=== Feed Types ===

Recall that back near the beginning of the tutorial, you set the "feed type" to "Regular". As you may have guessed, there's actually more than one way to write a command feed. The advantage of Regular feeds is that they let you do whatever you want, so it's really easy to innovate, but the disadvantages lie in subscribing to misbehaving or malicious code. You can alternatively write what's called a ''Locked-Down Feed'', which is much safer and doesn't raise a warning page when a user subscribes to it—but the consequences are that you have less freedom of implementation as a command author. If you're interested in learning more about Locked-Down Feeds, check out the [[Labs/Ubiquity/Locked-Down_Feed_Tutorial|Locked-Down Feed Tutorial]].

=== Trust Networks ===

In the future, we're going to have something set up that we call a "[[Labs/Ubiquity/TrustNetwork|trust network]]". When you try out a Ubiquity command from a website, and determine that the command is safe (or unsafe), you'll be able to leave an approval (or a warning). When your friends with Ubiquity installed visit the same site, they'll see the approval or the warning that you left. In this way, users will be able to rely on the judgement of other people they already know and trust in order to help them make decisions about whether a command is safe to install or not.

By the way, the reason we call it "subscribing" to a command, rather than "installing" a command, is that if the javascript file changes -- if the site owner adds new commands, removes old commands, or updates existing commands -- all users subscribed to that URL will automatically get the updates. This will be very convenient for both users and developers, but it will also introduce another type of security risk: just because you decided a command was safe at one point in time doesn't mean that the command will always remain safe. For this reason, we'll need to make sure that the trust network keeps track of when commands have been modified, and notifies users of changes that may make a command unsafe.

== Map Me! Location, Snapshots, and Inserting HTML ==

The "map" command that comes with Ubiquity is fairly powerful. It's also fairly complicated—well, comparatively. It's still only a couple hundred lines of code. The command, though, can get even more useful. Imagine being able to select some houses on Craigslist, or a list of restaurant names, and Ubiq "map these" to get just the map you want. The concept of "these" puts the power of mashups into the users hands. But I digress. Let's make a simple command that inserts a map of your current location.

In this command, we use the Google [http://code.google.com/apis/maps/documentation/staticmaps/ static map API] and the Ubiquity function <code>CmdUtils.getGeoLocation()</code> to insert a map of your current location. Ubiquity currently uses the [http://www.maxmind.com/app/api MaxMind] API for trying to guess your location from your IP. That will probably change in the future.

We'll call this command <code>"map me"</code> so that it won't be confused with the standard <code>"map"</code> command.

<pre>
CmdUtils.CreateCommand({
names: ["map me"],

_getMapUrl: function() {
var loc = CmdUtils.getGeoLocation();
var mapUrl = "http://maps.google.com/staticmap?";

var params = {
center: loc.lat + "," + loc.long,
size: "500x400",
zoom: 14,
key: "ABQIAAAAGZ11mh1LzgQ8-8LRW3wEShQeSuJunOpTb3RsLsk00-MAdzxmXhQoiCd940lo0KlfQM5PeNYEPLW-3w"
};

return mapUrl + jQuery.param( params );
},

preview: function( pblock ) {
var msg = "Inserts a map of your current location: " +
"<img src='${url}'/>";
pblock.innerHTML = _(msg, {url: this._getMapUrl()});
},

execute: function( ) {
CmdUtils.getImageSnapshot( this._getMapUrl(), function(imgData) {
CmdUtils.setSelection( "<img src='" + imgData +"'/>");
})
}
})
</pre>

There are three new things here: <code>CmdUtils.setSelection</code> to set HTML (yep, it can do that); the use of <code>CmdUtils.getGeoLocation()</code>; and using <code>CmdUtils.snapshotImage()</code> to capture the bits for the image.

I find getting the location—as imprecise as IP-based location can be—useful for doing sensible defaults for location-based commands, like Yelp. <code>CmdUtils.getGeoLocation()</code> returns an object which has the following properties: city, state, country, lat, and long.

Why do we need to use <code>CmdUtils.snapshotImage()</code>? Because the Google Maps API requires a key that is tied to a particular URL. If we naively inject the image tag into a random web page, the image won't load because the key doesn't match that random web page's URL. Thus, we use the <code>snapshotImage()</code> function to convert the image into a [http://en.wikipedia.org/wiki/Data:_URI_scheme data url].

There's also a <code>CmdUtils.snapshotWindow</code> function, which allows you to get the image data for any tab/window. The function takes a window as the first paramater, and a callback for the second.

= Commands with Arguments =

== Echo ==

We'll be working towards making some fun and useful commands—commands that let you control the seething tendrils of the internet with your little pinky. But, let's start by making a simple command to echo back whatever you type.

<pre>
CmdUtils.CreateCommand({
names: ["echo"],
arguments: [{role: "object",
nountype: noun_arb_text,
label: "your shout"}],
preview: function( pblock, arguments ) {
pblock.innerHTML = _("Will echo: ") + arguments.object.text;
},
execute: function( arguments ) {
var msg = arguments.object.text + "... " + arguments.object.text + "......";
displayMessage( msg );
}
});
</pre>

This says that the command "echo" takes one argument which is arbitrary text. Whatever text the user enters will get wrapped in an input object and passed into both the preview and execute function.

Try it! Ubiq "echo hellooooo" and watch what happens.

Ubiquity takes care of parsing the user's input, so you don't need to worry about handling prounoun substitution or any of the other natural-language-like features of the Ubiquity parser. Try selecting some text on a page, and Ubiq "echo this". Ubiquity should now echo the selected text.

Note that we gave three pieces of information when defining our argument: its role, its nountype, and its label. The label is the easiest part: It's just whatever text you want to have appear in the Ubiquity interface as a prompt for the user. E.g, if you ubiq "echo", you will see the label for the argument:

<pre>
echo (your shout)
</pre>

The roles and the nountypes require some more explanation. We'll cover each of them in detail next.

=== Argument Roles ===

Your command can take multiple arguments. Each one is identified by a "role". To understand roles, it helps to think of your command name as a verb, and each argument as a noun. Remember that Ubiquity's command line is a pseudo-natural-language environment, so it attempts to be as close to natural language grammar as possible.

For example, if you've ever used the <code>email</code> command, you know that it takes up to two arguments: a message and a person.

<pre>
email message
email to person
email message to person
email to person message
</pre>

In grammatical terms, the message argument is the "direct object" of the verb "email". The person argument is an indirect object. We call it the "goal" of the verb. So if we were writing the email command, we'd define the arguments like this:

<pre>
arguments: [{role: "object",
nountype: noun_arb_text,
label: "message"},
{role: "goal",
nountype: noun_type_contact,
label: "recipient"}]
</pre>

Because we give the recipient argument the "goal" role, the Ubiquity parser knows to expect the user to type the word "to". When the user enters "email hello to Aza", the parser knows that the word following "to" -- that is, "Aza" -- should be assigned to the recipient argument.

In our simple "echo" command, we expect the user to type "echo hellooooo" or something like that. The "hellooooo" is the direct object of the verb "echo", so we give it the "object" role.

"Object" is the most common role. If a command takes only one argument, that argument is usually an "object".

==== What Roles Can I Use? ====

* object (in "echo helloooo", hello is the object.)
* goal (in "email this to brandon", brandon is the goal.)
* source (in "translate this from spanish", spanish is the source.)
* location (in "yelp pizza near boston", boston is the location.)
* time (in "book a flight on thursday", thursday is the time.)
* instrument (in "search monkeys with google", google is the instrument.)
* format (in "check weather in celsius", celsius is the format.)
* modifier (in "get email address for chris", chris is the modifier.)
* alias (in "twitter this as jono", jono is the alias.)

[https://wiki.mozilla.org/Labs/Ubiquity/Parser_2/Semantic_Roles More information about these roles].

=== The Arguments Object ===

When your execute method is called, it is passed a single object that encapsulates the values for all arguments.

When your preview method is called, it is passed this object, too.

The object has one attribute corresponding to each role. In our example above, the command accepts only an object-role argument, so the preview and execute methods get passed an argument with an "arguments.object" attribute.

If we made a command, like email, that takes an object-role argument and a goal-role argument, its preview and execute methods would get passed an argument with "arguments.object" and "arguments.goal".

arguments.object (or arguments.goal) has several attributes of its own:

<pre>
arguments.object.text // a string of the input in plain text, without formatting
arguments.object.html // a string of the input in formatted html, including tags
arguments.object.data // for non-text input types, an arbitrary data object
arguments.object.summary // for very long inputs, an abbreviated display string
</pre>

Our example command only cares about the <code>.text</code> attribute of the input, because it simply wants plain text. Often, when the user invokes your command by typing a few short words into the input box, <code>.text</code>, <code>.html</code>, and <code>.summary</code> will all have exactly the same value, and <code>.data</code> will be null. Many, if not most, commands that you write will only care about the text value. Nevertheless, the other versions of the input data are provided to you in case they differ from <code>.text</code> and in case your command has a use for them.

== Introduction to Noun Types ==

Noun types specify what ''kind'' of input your command can accept for each one of its arguments.

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.

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.

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.

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)
* noun_type_language (Name of a human language, e.g. "English", "Japanese")
* noun_type_url (A URL)
* noun_type_contact (An email address from your address book)
* noun_type_date (A date, in any format, or a word like "tomorrow")
* noun_type_time (A time, in any format)
* noun_type_percentage
* noun_type_address
* noun_type_tab
* noun_type_searchengine
* noun_type_tag
* noun_type_geolocation

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 — and then come [[Labs/Ubiquity#Participation|get involved]] to help us improve them.

=== Regexps as Noun Types ===

If none of the nountypes above is what you're looking for, there are several ways to define your own. The simplest is to use a regular expression. Suppose that (for whatever odd reason) you wanted your command to accept only arguments that begin with the letter N. The following regexp matches words that start with N:

<pre>
/^[nN]/
</pre>

You could use it as a noun type, like so:

<pre>
arguments: [{role: "object",
nountype: /^[nN]/,
label: "word that starts with n"}]
</pre>

(Note that you do ''not'' put quotes around the regexp.)

A regexp nountype will reject input that doesn't match, but it doesn't know how to help the user by suggesting appropriate input.

=== Lists as Noun Types ===

Suppose you're writing a command that takes a color as an argument (perhaps it outputs a hexadecimal RGB representation of that color.) To make a nountype that accepts colors, you can simply pass in an array of strings:

<pre>
names: ["convert color"],
arguments: [{role: "object",
nountype: ["red", "orange", "yellow", "green",
"blue", "violet", "black", "white",
"grey", "brown", "beige", "magenta",
"cerulean", "puce"],
label: "color to convert"}]
</pre>

One benefit of using a list is that the parser can use it offer the user suggestions. If the user enters "get-color bl", for instance, Ubiquity will be able to suggest "black" and "blue" as the two valid completions based on the input. This makes list-based nountypes very useful for any command that can accept only a finite set of values.

=== Writing a Noun Type Object ===

Of course, not every type of noun you'd be interested in can be represented
as a finite list or as a regexp. If you want to be able to accept or reject input based on some algorithmic test, you can do so by writing a custom JavaScript object that implements a <code>suggest()</code> method (and, optionally, a <code>default()</code> method.)

There is an example of how to do this in the section on the tab commands, below.

== Insert Email: the Contact noun type ==

Let's take a look at one of the built-in noun-types: <code>noun_type_contact</code>. This lets Ubiquity know to expect a person (either by name or email address). By using the noun-type, Ubiquity will also autocomplete to known people while the user is entering the command. This is what the built-in Ubiquity command "email" uses.

At the moment, Ubiquity figures out what people you know through reading your Gmail contacts. In this prototyped version, you'll need to use Gmail and be logged in for for Ubiquity to know who you know. Eventually, we'd like to be able to interface with all major web-mail sites, as well as desktop software like Thunderbird.

Enough rambling. It's time for a command. I constantly find that I need to fetch someone's email address to paste into a text field because I don't know it off-hand. This command solves that by letting you insert someone's email address using autocomplete.

<pre>
CmdUtils.CreateCommand({
names: ["insert email"],
arguments: {modifier: noun_type_contact},
preview: "Inserts someone's email address by name.",
execute: function( arguments ) {
CmdUtils.setSelection( arguments.modifier.text );
}
});
</pre>

To try this out, Ubiq "insert email for " and then the first few letters of someone you email often.

=== Shorter Argument Declarations ===

Notice that we used a shortcut for declaring the arguments. In the long form, we would have had to say:

<pre>
arguments: [{role: "modifier",
nountype: noun_type_contact,
label: "contact"}]
</pre>

but if we don't care about specifying a label for the argument, we can get away with using a single object for "arguments", with the roles as the property names, and the nountypes as the property values:

<pre>
arguments: {modifier: noun_type_contact}
</pre>

If we had several arguments, and none of them needed labels, we could say:

<pre>
arguments: {object: noun_arb_text, modifier: noun_type_contact}
</pre>

and so on.

Aza writes:

<blockquote>
This one command sums up what I love about Ubiquity. In 8 lines of code, I can
fundamentally enhance the browser's functionality. Doing the same thing using
a normal Firefox extension methodology takes pages and pages of code—and the interface would take more thought still. Doing the same thing using a bookmarklet would require a server-side component (to get around cross-site Ajax request ban) as well as forcing the user to give up their email password.

Ubiquity increases the surface area of innovation for the browser many-fold, by making anyone who can write simple Javascript into an agent for bettering the browser and the open Web.
</blockquote>

== TinyURL: Network Calls and jQuery (and the URL noun type)==

Often while writing emails, I'll discover that I've pasted in a URL long enough to be used for unfortunate analogies. I'd like to be able to quickly turn that into a [http://en.wikipedia.org/wiki/Tinyurl TinyURL]—but the process of making a TinyURL involves lots of fiddly steps. Ubiquity to the rescue.

Because we include [http://en.wikipedia.org/wiki/jQuery jQuery] with Ubiquity, it is simple to perform Ajax calls as well as parse returning data. TinyUrl.com provides an easy to use RESTful API where you pass a URL and it returns its shortened form. We use that API in this command.

<pre>
CmdUtils.CreateCommand({
names: ["tinyurl"],
arguments: [{role: "object",
nountype: noun_type_url,
label: "url to shorten"}],
preview: "Replaces the selected URL with a TinyUrl.",
execute: function( arguments ) {
var baseUrl = "http://tinyurl.com/api-create.php";
var params = {url: arguments.object.text};
jQuery.get( baseUrl, params, function( tinyUrl ) {
CmdUtils.setSelection( tinyUrl );
})
}
})
</pre>

<code>noun_type_url</code> is a useful nountype because it defaults to the URL of the page that you are currently on. If that is in fact the URL that the user wants, then they don't have to type it or even select it.

jQuery is a powerful tool. With it, you can fairly effortlessly cherry-pick the data you need from RSS feeds, XML, and all sorts of other data formats. It also makes doing in-preview animations a breeze.

= Twitter: Putting It All Together =

We've now covered everything we need to cover in order to write a command that allows us to [http://en.wikipedia.org/wiki/Twitter Twitter] from Ubiquity. The code below is the actual source code of the Twitter command as it appears in Ubiquity 0.5.

Many thanks to [http://theunfocused.net/moz/ubiquity/verbs/ Blair McBride] for writing this command. The source code is a bit more intricate than anything we've seen so far, but it's built using exactly the same basic pieces -- and demonstrates nearly all of those pieces in action.

<pre>
const TWITTER_STATUS_MAXLEN = 140;

CmdUtils.CreateCommand({
names: ["twitter", "tweet", "share using twitter"],
arguments: [
{role: "object", label: 'status', nountype: noun_arb_text},
{role: "alias", nountype: noun_type_twitter_user}
],
icon: "http://twitter.com/favicon.ico",
description:
"Sets your Twitter status to a message of at most 160 characters.",
help: ("You'll need a <a href=\"http://twitter.com\">Twitter account</a>," +
" obviously. If you're not already logged in" +
" you'll be asked to log in."),
preview: function(previewBlock, args) {
var statusText = (args.object ? args.object.text : '');
var usernameText = "";
if (args.alias) {
usernameText = args.alias.text;
} else if (args.as) {
usernameText = args.as.text;
}
var previewTemplate = (
"<div class='twitter'>"+_("Updates your Twitter status ${username} to:")+" " +
"${status} " +
_("Characters remaining: ${chars}") +
""+_("tip: tweet @mozillaubiquity for help")+"</div>");
var truncateTemplate = (
""+_("The last ${truncate} characters will be truncated!")+"");
var previewData = {
status: <>{statusText}</>.toXMLString(),
username: usernameText && _("(For user ${usernameText})"),
chars: TWITTER_STATUS_MAXLEN - statusText.length
};

var previewHTML = CmdUtils.renderTemplate(
CmdUtils.renderTemplate(previewTemplate, previewData),
{usernameText:usernameText});

if (previewData.chars < 0) {
var truncateData = {
truncate: 0 - previewData.chars
};

previewHTML += CmdUtils.renderTemplate(truncateTemplate, truncateData);
}

previewBlock.innerHTML = previewHTML;
},
execute: function(args) {
var statusText = args.object.text;
if(statusText.length < 1) {
this._show(_("requires a status to be entered"));
return;
}

var updateUrl = "https://twitter.com/statuses/update.json";
var updateParams = {
source: "ubiquity",
status: statusText
//dont cut the input since sometimes, the user selects a big url,
//and the total lenght is more than 140, but tinyurl takes care of that
};
var me = this;

function sendMessage() {
jQuery.ajax({
type: "POST",
url: updateUrl,
data: updateParams,
dataType: "json",
error: function() {
me._show(_("error - status not updated"));
},
success: function() {
me._show(/^d /.test(statusText)
? _("direct message sent")
: _("status updated"));
},
username: login.username,
password: login.password
});
}

var login;
var alias = args.alias;
if (alias && alias.text && alias.data) {
login = alias.data;
sendMessage();
} else {
login = {username: null,
password: null};
if (alias && alias.text)
login.username = alias.text;
sendMessage();
}
},
_show: function(txt){
displayMessage({icon: this.icon, title: this.name, text: txt});
}
});
</pre>

= Switching Tabs =

The final command in this tutorial is for switching between tabs. The end goal is this: type a few keys to that matches the title of an open tab (in any window), hit return, and you've switched to that tab.

We'll write this command in two steps. The first step is creating a tab noun-type. The second step is using that noun-type to create the tab-switching command.

== Switching: Writing your own Noun-Types ==

A noun-type needs to only have two things: A <code>label</code> and a <code>suggest()</code> function. It can optionally also have a <code>default()</code> function.

The label is what shows up when the command prompts for input. Suggest returns a list of input objects, each one containing the name of a matching tab. We're using [http://developer.mozilla.org/en/docs/FUEL FUEL] to interact with the browser, which is where the "Application" variable comes from.

<pre>
var noun_type_tab = {
label: "tab name",

// Returns all tabs from all windows.
getTabs: function(){
var tabs = {};

for( var j=0; j < Application.windows.length; j++ ) {
var window = Application.windows[j];
for (var i = 0; i < window.tabs.length; i++) {
var tab = window.tabs[i];
tabs[tab.document.title] = tab;
}
}

return tabs;
},

suggest: function( text, html, callback ) {

var suggestions = [];
var tabs = noun_type_tab.getTabs();

//TODO: implement a better match algorithm
for ( var tabName in tabs ) {
if (tabName.match(text, "i"))
suggestions.push( CmdUtils.makeSugg(tabName) );
}

// Return a list of input objects, limited to at most five:
return suggestions.splice(0, 5);
}
}
</pre>

The suggest method of a noun type always gets passed both text and html. If the input is coming from a part of a web page that the user has selected, these
values can be different: they are both strings, but the html value contains markup tags while the text value does not. The Tab noun type only cares about the plain text of the tab name, so we ignore the value of html.

The callback argument is for use by nountypes that need to run asynchronously, i.e. becaus they need to do network calls to generate suggestions. The callback is a function; instead of returning a list of suggestions right away, an asynchronous noun type can call the callback with each suggestion it generates. More on this later; the tab noun type generates all its suggestions right away, so it just returns them instead of using the callback.

We use the convenience function <code>CmdUtils.makeSugg()</code> to generate an
input object of the type that the Ubiquity parser expects. The full signature of this function is
<pre>
CmdUtils.makeSugg( text, html, data );
</pre>
but html and data are optional and need be provided only if they differ from text.

If the text or html input is very long, <code>makeSugg()</code> generates a summary for us, and puts it in the <code>.summary</code> attribute of the input object.

We could have accomplished mostly the same thing without calling <code>makeSugg()</code> by returning a list of anonymous objects like these:
<pre>
{ text: tabName,
html: tabName,
data: null,
summary: tabName };
</pre>

The input objects that our <code>.suggest()</code> method generates are the same objects that will eventually get passed in to the <code>execute()</code> and <code>preview()</code> methods of any commands that use this noun type.

== Switching Tabs: The Command ==

Now that we are armed with the tab noun-type, it is easy to make the tab-switching command. Again, we use FUEL to focus the selected tab.

<pre>
CmdUtils.CreateCommand({
names: ["tab"],
arguments: {object: noun_type_tab},

execute: function( arguments ) {
var tabName = arguments.object.text;
var tabs = noun_type_tab.getTabs();
tabs[tabName]._window.focus();
tabs[tabName].focus();
},

preview: function( pblock, arguments ) {
var tabName = arguments.object.text;
if( tabName.length > 1 ){
var msg = "Changes to ${tab} tab.";
pblock.innerHTML = _(msg, {tab: tabName});
}
else
pblock.innerHTML = _("Switch to a tab by name.");
}
})
</pre>

= Development Hints =

You now know all you need to know to get started developing useful Ubiquity commands of your own.

Here are some miscellaneous tips that didn't fit elsewhere on this page, that may make development easier for you.

== The Source Code of Built-In Commands ==

Looking at the source code of built-in commands and built-in noun types can be a very useful aid to development. If you have the source checkout of Ubiquity (see [Labs/Ubiquity/Ubiquity_0.1_Development_Tutorial | the development tutorial] to find out how to get this), the source code can be found in the files:

ubiquity/standard-feeds/
ubiquity/builtin-feeds/en/builtincmds.js
ubiquity/modules/nountypes.js

If you don't have a checkout of the source code, you can view the latest version on the web here:

[http://hg.toolness.com/ubiquity-firefox/file/tip/ubiquity/standard-feeds/ standard-feeds]
[http://hg.toolness.com/ubiquity-firefox/file/tip/ubiquity/builtin-feeds/en/builtincmds.js builtincmds.js]
[http://hg.toolness.com/ubiquity-firefox/file/tip/ubiquity/modules/nountypes.js nountypes.js]

== Interacting with Other Extensions ==

http://img363.imageshack.us/img363/1906/picture7cm5.png

There isn't much to say here besides that it's easy. For example, here's a command (thanks to [http://foyrek.com/lyrics.html Abimanyu Raja] for writing this code) that finds the lyrics for a song. You can simply Ubiq something like "get lyrics for wild international" but the command will also interface with the FoxyTunes extension (if it is installed) and add the currently playing song to the suggestion list. Interfacing with other extensions, too, is easy because you can view the source code for every Firefox extension.

<pre>
var noun_type_song = {
label: "song name",
suggest: function( text, html ) {
var suggestions = [CmdUtils.makeSugg(text)];
if(window.foxytunesGetCurrentTrackTitle){
suggestions.push(CmdUtils.makeSugg(window.foxytunesGetCurrentTrackTitle()));
}
return suggestions;
}
}

CmdUtils.CreateCommand({
names: ["get lyrics"],
arguments: {modifier: noun_type_song},
preview: function(pblock, arguments) {

searchText = jQuery.trim(arguments.modifier.text);
if(searchText.length < 1) {
pblock.innerHTML = _("Searches for lyrics of the song");
return;
}

var previewTemplate = "Searches for the lyrics of ${query}";
pblock.innerHTML = _(previewTemplate, {query: searchText});

},
execute: function(arguments) {
var url = "http://www.google.com/search?q={QUERY}"
var query = arguments.object.text + _(" lyrics");
var urlString = url.replace("{QUERY}", query);
Utils.openUrlInBrowser(urlString);
}
});
</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",
label: "topic",
suggest: function freebase_topic_suggest(text, html, callback) {
return [
CmdUtils.makeSugg(text),
$.ajax({
url: "http://www.freebase.com/api/service/search",
dataType: "json",
data: {prefix: text, limit: 5},
success: function suggestTopics(response) {
if (response.status === "200 OK")
callback([CmdUtils.makeSugg(result.name, result.name, result)
for each (result in response.result)]);
},
})];
}
};

CmdUtils.CreateCommand({
names: ["lookup on freebase"],
arguments: {object: noun_type_freebase_topic},
preview: function preview(pblock, args) {
pblock.innerHTML = _(("Go to the Freebase topic page for " +
"{if text}${text}{else}any topic{/if}."),
args.object);
},
execute: function goToFreebase({object: {text, data}}) {
Utils.openUrlInBrowser(
text
? (data
? "http://www.freebase.com/view" + data.id
: ("http://www.freebase.com/search?query=" +
encodeURIComponent(text)))
: "http://www.freebase.com/");
}
});
</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 ==

Commands aren't the only thing you can put in a command feed. You can also include functions you want to be run automatically at page-load time and at Firefox startup time.

In order to run some code on page load, you simply have to prefix your function with <code>pageLoad_</code>. For example, if you want to say "Hi" every time a page is loaded, your code would look like this:

<pre>
function pageLoad_hi(){
displayMessage("hi");
}
</pre>

If you modify the function and want to see the changes, remember to first invoke Ubiquity. Although your function like above, might not be a Ubiquity command, this is necessary to refresh the cached code.

Similarly, if you want to run some code everytime Firefox starts up, you just have to prefix the function with <code>startup_</code> .

The awesome thing about these functions is the ability to develop whole Firefox extensions (that require minimal UI) as Ubiquity plugins in lesser lines of code. You don't need to worry about chrome.manifest or install.rdf. Another added benefit is that you never have to restart your Firefox during development unless of course, you are running code on Firefox startup.

<center>http://img388.imageshack.us/img388/3086/picture5eo9.png</center>

Here's the code for [http://foyrek.com/keyscape.js Keyscape] which is a Ubiquity command that makes use of <code>pageLoad</code> and <code>startup</code> to recreate the functionality of the [https://addons.mozilla.org/en-US/firefox/addon/339 Search Keys extension] by Jesse Ruderman. In line with Ubiquity's aim to let you do things quicker using your keyboard, this command lets you go to search results on Google by just pressing a number. It'll add hints to show the number of each link.

<pre>
//A lot of this code is borrowed from the Search Keys extension
//Many thanks to Jeese Ruderman

function startup_keyscape() {
window.addEventListener("keydown", keyscape_down, true);
}

function pageLoad_keyscape(doc){

var uri = Utils.url(doc.documentURI);
//If we are on about: or chrome://, just return
if(uri.scheme != "http")
return;

//Check if the page we are on is google
if( keyscape_isGoogle(uri) ){

for(var num=1; num<=10; num++){

var link = jQuery(doc.body).find('a.l')[num-1];

if( link ){

var hint = doc.createElementNS("http://www.w3.org/1999/xhtml", "span");
hint.style.color = "blue";
hint.style.background = "white";
hint.style.padding = "1px 2px 1px 2px";
hint.style.marginLeft = ".5em";
hint.appendChild(doc.createTextNode(num == 10 ? 0 : num));
link.parentNode.insertBefore(hint, link.nextSibling);
}
}
}
}

function keyscape_isGoogle(uri){
return uri.host.indexOf("google") != -1
&& (uri.path.substr(0,8) == "/search?"
|| uri.path.substr(0,8) == "/custom?");
}

function keyscape_down(event){

var doc = Application.activeWindow.activeTab.document;
var uri = Utils.url(doc.documentURI);

if( keyscape_isGoogle(uri) ){

var key = parseInt(event.keyCode || event.charCode);
var num;

if(48 <= key && key <= 57) //number keys
num = key - 48;
else if(96 <= key && key <= 105) //numeric keypad with numlock on
num = key - 96;
else
return;

//Don't do anything if we are in a textbox
//or some other related elements
var elt = window.document.commandDispatcher.focusedElement;

if (elt) {
var ln = new String(elt.localName).toLowerCase();
if (ln == "input" || ln == "textarea" || ln == "select" || ln == "isindex")
return;
}

//Get the link url from the search results page
var url_dest = jQuery(doc.body).find('a.l').eq(num-1).attr('href');

if(event.altKey){
//Open in new tab
Application.activeWindow.open(Utils.url(url_dest));
}else{
//Open in same tab
doc.location.href = url_dest;
}
}
}
</pre>

If Ubiquity does indeed become ubiquitous, a lot of extensions can be re-written as Ubiquity commands. This is much nicer for the end-user, as well, because the Ubiquity command installation process is a lot easier.

In the future, Ubiquity is also likely to have the ability to convert your Ubiquity commands into proper Firefox extensions. Look [http://labs.toolness.com/trac/ticket/3 here] to check on the progress of this functionality.

== Firebug ==

Ubiquity automatically enables Chrome Errors and Warnings on startup so that errors in your code appear in the Firebug console. Just use <tt>CmdUtils.log()</tt> rather than <tt>console.log()</tt>.

= Where To Go From Here =

Take a look at Ubiquity's reference documentation for the <tt>[https://ubiquity.mozilla.com/hg/ubiquity-firefox/raw-file/tip/ubiquity/index.html#modules/utils.js Utils]</tt> and <tt>[https://ubiquity.mozilla.com/hg/ubiquity-firefox/raw-file/tip/ubiquity/index.html#modules/cmdutils.js CmdUtils]</tt> namespaces.

If you have any questions or comments, feel free to join us on IRC at <tt>#ubiquity</tt> on <tt>irc.mozilla.org</tt>, as well as the [http://groups.google.com/group/ubiquity-firefox Ubiquity Google Group].

= Conclusion =

To reiterate a point I made before: Ubiquity increases the surface area of innovation for the browser many-fold, by making anyone who can write simple Javascript into an agent for bettering the browser and the open Web. You are one of those agents.

Now, go forth and create.

Labs/Ubiquity/Ubiquity 0.5 Author Tutorial

2009-07-10T23:14:13Z

Endolith:

Back to [[Labs/Ubiquity]].

Author: Aza Raskin, Blair McBride, Abimanyu Raja, Jono DiCarlo, Atul Varma

= The Ubiquity version 0.5 Command Tutorial =

The great power of Ubiquity—from a developer standpoint—is how easy it is to create commands. With only a couple of lines of Javascript, Ubiquity enables even casual web developers to drastically enhance the features of the browser. From an 8-line command to insert a contact's email address in any text field, to a 50-line Twitter integration, this tutorial walks you through the process of being generative with Ubiquity.

The rest of this page documents the command developer API as it stands frozen in version 0.5.

If you want the bleeding-edge command developer API (which includes any new features that may have been added to the Ubiquity source code in HG but not yet included in a release), then that's [[Labs/Ubiquity/Ubiquity_Source_Tip_Author_Tutorial|here]].

If you want the old command developer API, as it stood in Ubiquity 0.1 (not recommended), that's [[Labs/Ubiquity/Ubiquity_0.1_Author_Tutorial|here]].

== Real Time Development ==

Ubiquity doesn't require you to restart Firefox as you develop. Restarting is a drastic measure, and we want none of it. Instead, Ubiquity reloads the commands every time it is summoned. When you are using the built-in editor then you don't even need to save!

To open the Ubiquity command editor, summon Ubiquity (control/alt + space) and use the "open command editor" command. Throughout this tutorial, when we want you to run a command in Ubiquity, we'll say '''Ubiq''' it. For instance, to open the editor, just Ubiq "open command editor".

In the following examples, just type in this editor. Updates happen the next time you summon Ubiquity.

== Choices, Choices... ==

You may notice a drop-down menu mentioning something about a "feed type" just above the editing field in the command editor:

http://www.toolness.com/images/20090318121423.jpg

For now, just make sure this drop-down is set to "Regular". We'll tell you more about what this means later.

= Hello World: The First Command =

== Just a Message: As Simple as it Gets ==

Let's start with the standard programing trope: printing "Hello, World!".

In the command editor type the following:

<pre>
CmdUtils.CreateCommand({
names: ["say hello"],
execute: function() {
displayMessage( "Hello, World!");
}
});
</pre>

Now try Ubiq-ing "say hello". You'll see that "Hello, World!" is immediately displayed on the screen. If you are on Mac OSX with [http://en.wikipedia.org/wiki/Growl_(software) Growl] installed the message will appear as a Growl notification. If you are on Windows, then it will appears as a standard "toaster" notification in the bottom right-hand corner of the screen.

http://farm3.static.flickr.com/2479/3651542339_022e4aa4c4.jpg

http://img517.imageshack.us/img517/7726/picture2vx2.png

In Ubuntu 8.04 (Hardy Heron) this appears thus:

http://img293.imageshack.us/img293/7746/ubiqubuntuhelloworldeq9.png

If you don't have Growl installed on OSX, or aren't on a Windows XP/Vista or Ubuntu Hardy, then you won't get any sort of notification. That's something to be [http://labs.toolness.com/trac/ticket/19 worked on] in future releases of Ubiquity.

=== CmdUtils.CreateCommand ===

<code>CmdUtils</code> is a namespace which contains all the functions you need to create commands. Commands are created by making an object and passing it to <code>CmdUtils.CreateCommand</code>. In Javascript, inline curly braces mean "new object", so this code:

<pre>
{
names: ["say hello"],
execute: function() { //etc }
}
</pre>

means "Make an object with two attributes, 'names' and 'execute'." This object is then passed as the argument to <code>CmdUtils.CreateCommand</code>.

=== names ===

'names' and 'execute' are the only two mandatory attributes for your command object. 'names' specifies what the command is called, and 'execute' specifies what it does. There are plenty of other attributes that you can specify, but they are all optional.

'names' is always an array (thus the square brackets). In the case of this command we provided only one name, "hello world". But we could have provided as many names as we wanted. For instance, if we had said:

names: ["say hello", "greet"]

then "say hello" would be the normal name of the command, but Ubiquity would also recognize "greet" as a synonym or alias for the command.

=== execute ===

'execute' is always a function. When the user executes your command, this is the function that will be run. It can do pretty much anything you want -- or at least, anything you know how to write in JavaScript.

In the example above, we simply call <code>displayMessage()</code>, which displays the given message in whichever way the operating system can.

There are a number of other useful functions in the <code>CmdUtils</code> 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 [http://hg.toolness.com/ubiquity-firefox/file/9a6c9935da9f/ubiquity/chrome/content/cmdutils.js cmdutils.js].

=== Making sure your command is localizable ===

Ubiquity now supports multiple languages. That means that hopefully someday someone will be translating your commands to the other languages that Ubiquity supports. Making your command localizable is easy, and a good habit to get into! You just have to locate all strings that appear in your <code>preview()</code> and <code>execute()</code> methods, that are intended for display to humans, and wrap them with:

_()

This may look odd, but what it does is quite important: it makes your strings appear in the template files that localizers will be using. So let's make our "Hello world!" command localizable:

<pre>
CmdUtils.CreateCommand({
names: ["say hello", "greet"],
execute: function() {
displayMessage( _("Hello, World!") );
}
});
</pre>

This makes it so that when a localization template is generated from your command feed, "Hello, World!" will be listed among the strings to be translated.

Note that we don't need to wrap the names, or other strings that appear in the command metadata -- these are automatically wrapped for us. We only need to wrap strings that appear inside the functions.

== Adding a Preview ==

http://img352.imageshack.us/img352/1002/picture3ex0.png

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 "say hello" command, we don't need anything fancy: just some help text that is more descriptive than the default "Executes the say hello command."

<pre>
CmdUtils.CreateCommand({
names: ["say hello", "greet"],
preview: "Displays a salutary greeting to the planet.",
execute: function() {
displayMessage( _("Hello, World!") );
}
})
</pre>

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.

<pre>
CmdUtils.CreateCommand({
names: ["insert date"],
execute: function() {
var date = new Date();
CmdUtils.setSelection( date.toLocaleDateString() );
}
})
</pre>

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>toLocalDateString()</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].

== A Better Preview ==

It's time to add a better preview to the date command. Let's have the preview show the date, so that the user will know what to expect when they execute the command. (As a side benefit the user doesn't even need to execute the command to do a quick check of the day.)

<pre>
CmdUtils.CreateCommand({
names: ["insert date"],

_date: function(){
var date = new Date();
return date.toLocaleDateString();
},

preview: function( pblock ) {
var msg = _('Inserts todays date: "${date}"');
pblock.innerHTML = CmdUtils.renderTemplate( msg, {date: this._date()} );
},

execute: function() {
CmdUtils.setSelection( this._date() );
}
})
</pre>

We've done two things here. The first was to factor out the code for getting the date into the <code>_date()</code> function. This way we don't break [http://en.wikipedia.org/wiki/Don%27t_repeat_yourself DRY] by repeating code across the preview and execute functions. Notice that to access the <code>_date()</code>, we use the <code>this</code> keyword.

The second thing we've done is to add a preview function. The first argument is the DOM element that gets displayed as the preview for your command. Modify <code>pblock</code> and you modify the preview. In this case, we set the <code>innerHTML</code> of the preview block to be the message we want.

The other thing I've done is to do some string formatting using the <code>renderTemplate()</code> function. This takes a template string and performs the appropriate substitution given the passed-in JSON object. Templates can handle a wide range of functionality, as we are currently using TrimPath's [http://code.google.com/p/trimpath/wiki/JavaScriptTemplates JavascriptTemplates]. You should read their site for more documentation. Although JavascriptTemplates has some nice properties, we are contemplating moving to [http://mjtemplate.org/ MJT] sometime soon.

=== A shortcut for localization and rendering templates ===

Note how in the code above, we used the localization wrapper <code>_()</code> before passing the string to renderTemplate. Because this is such a very common combination when displaying strings, we have a shortcut for it. Calling _() with a JSON object as the second argument will automatically trigger <code>CmdUtils.renderTemplate()</code> on the post-localization string. So the above preview method could be rewritten more simply as:

<pre>
preview: function( pblock ) {
var msg = 'Inserts todays date: "${date}"';
pblock.innerHTML = _( msg, {date: this._date()} );
},
</pre>

=== Networking calls and placeholder previews ===

Previews display something meaningful to the user immediately. If you have a preview that requires an AJAX request—say, to fetch some search results—that call might take a while to return. In the meantime, your command should display a placeholder preview giving the user feedback.

<pre>
preview: function( pblock ) {
pblock.innerHTML = _("This will show until the AJAX request returns");
// AJAX request
pblock.innerHTML = getFromServer();
},
</pre>

In the future, we may work on streamlining this process.

== Documentation and Metadata ==

Before you share your command with the world, you should consider adding some attributions to the code:

<pre>
CmdUtils.CreateCommand({
names: ["insert date"],
homepage: "http://azarask.in/",
author: { name: "Aza Raskin", email: "aza@mozilla.com"},
contributors: ["Atul Varma"],
license: "MPL",

/* THE REST OF THE CODE HERE */
})
</pre>

And you should definitely add some documentation:

<pre>
CmdUtils.CreateCommand({
names: ["insert date"],
homepage: "http://azarask.in/",
author: { name: "Aza Raskin", email: "aza@mozilla.com"},
contributors: ["Atul Varma"],
license: "MPL",
description: "Inserts today's date.",
help: "If you're in an editable text area, inserts today's date, formatted for the current locale.",

/* THE REST OF THE CODE HERE */
})
</pre>

The <code>.description</code> and <code>.help</code> attributes are both automatically displayed alongside your command's name on the command-list page. (The user can get to this page at any time by issuing the "list ubiquity commands" command.) HTML tags can be used in both of these strings.

Description is a one-line summary of what the command does, while Help is a longer description that can include examples, caveats, and so on. If your command is simple enough that all you have to say about it fits in one line, it's OK to use a description alone and leave out the help.

== Sharing it with the World ==

Now that we've got our awesome new "date" command, let's share it with the world. All you have to do is put it the javascript file on the web somewhere, and make an html page linking to it with "link rel".

<pre><link rel="commands" href="http://path-to-js" name="Title Goes Here" /></pre>

Anyone with Ubiquity who visits will get a message offering them the choice of subscribing to your command.

[[Image:Subscribe.png]]

If the user chooses to subscribe to a Regular command feed from an untrusted source, they will get a security warning message before they can install the command. Because Regular Ubiquity command feeds can execute arbitrary javascript with chrome privileges, subscribing to a command from a website means allowing that site full access to do whatever it wants to your browser. We want to make sure people understand the dangers before subscribing to commands, so we made the warning page pretty scary.

[[Image:Warning.PNG]]

=== Feed Types ===

Recall that back near the beginning of the tutorial, you set the "feed type" to "Regular". As you may have guessed, there's actually more than one way to write a command feed. The advantage of Regular feeds is that they let you do whatever you want, so it's really easy to innovate, but the disadvantages lie in subscribing to misbehaving or malicious code. You can alternatively write what's called a ''Locked-Down Feed'', which is much safer and doesn't raise a warning page when a user subscribes to it—but the consequences are that you have less freedom of implementation as a command author. If you're interested in learning more about Locked-Down Feeds, check out the [[Labs/Ubiquity/Locked-Down_Feed_Tutorial|Locked-Down Feed Tutorial]].

=== Trust Networks ===

In the future, we're going to have something set up that we call a "trust network". When you try out a Ubiquity command from a website, and determine that the command is safe (or unsafe), you'll be able to leave an approval (or a warning). When your friends with Ubiquity installed visit the same site, they'll see the approval or the warning that you left. In this way, users will be able to rely on the judgement of other people they already know and trust in order to help them make decisions about whether a command is safe to install or not.

By the way, the reason we call it "subscribing" to a command, rather than "installing" a command, is that if the javascript file changes -- if the site owner adds new commands, removes old commands, or updates existing commands -- all users subscribed to that URL will automatically get the updates. This will be very convenient for both users and developers, but it will also introduce another type of security risk: just because you decided a command was safe at one point in time doesn't mean that the command will always remain safe. For this reason, we'll need to make sure that the trust network keeps track of when commands have been modified, and notifies users of changes that may make a command unsafe.

== Map Me! Location, Snapshots, and Inserting HTML ==

The "map" command that comes with Ubiquity is fairly powerful. It's also fairly complicated—well, comparatively. It's still only a couple hundred lines of code. The command, though, can get even more useful. Imagine being able to select some houses on Craigslist, or a list of restaurant names, and Ubiq "map these" to get just the map you want. The concept of "these" puts the power of mashups into the users hands. But I digress. Let's make a simple command that inserts a map of your current location.

In this command, we use the Google [http://code.google.com/apis/maps/documentation/staticmaps/ static map API] and the Ubiquity function <code>CmdUtils.getGeoLocation()</code> to insert a map of your current location. Ubiquity currently uses the [http://www.maxmind.com/app/api MaxMind] API for trying to guess your location from your IP. That will probably change in the future.

We'll call this command <code>"map me"</code> so that it won't be confused with the standard <code>"map"</code> command.

<pre>
CmdUtils.CreateCommand({
names: ["map me"],

_getMapUrl: function() {
var loc = CmdUtils.getGeoLocation();
var mapUrl = "http://maps.google.com/staticmap?";

var params = {
center: loc.lat + "," + loc.long,
size: "500x400",
zoom: 14,
key: "ABQIAAAAGZ11mh1LzgQ8-8LRW3wEShQeSuJunOpTb3RsLsk00-MAdzxmXhQoiCd940lo0KlfQM5PeNYEPLW-3w"
};

return mapUrl + jQuery.param( params );
},

preview: function( pblock ) {
var msg = "Inserts a map of your current location: " +
"<img src='${url}'/>";
pblock.innerHTML = _(msg, {url: this._getMapUrl()});
},

execute: function( ) {
CmdUtils.getImageSnapshot( this._getMapUrl(), function(imgData) {
CmdUtils.setSelection( "<img src='" + imgData +"'/>");
})
}
})
</pre>

There are three new things here: <code>CmdUtils.setSelection</code> to set HTML (yep, it can do that); the use of <code>CmdUtils.getGeoLocation()</code>; and using <code>CmdUtils.snapshotImage()</code> to capture the bits for the image.

I find getting the location—as imprecise as IP-based location can be—useful for doing sensible defaults for location-based commands, like Yelp. <code>CmdUtils.getGeoLocation()</code> returns an object which has the following properties: city, state, country, lat, and long.

Why do we need to use <code>CmdUtils.snapshotImage()</code>? Because the Google Maps API requires a key that is tied to a particular URL. If we naively inject the image tag into a random web page, the image won't load because the key doesn't match that random web page's URL. Thus, we use the <code>snapshotImage()</code> function to convert the image into a [http://en.wikipedia.org/wiki/Data:_URI_scheme data url].

There's also a <code>CmdUtils.snapshotWindow</code> function, which allows you to get the image data for any tab/window. The function takes a window as the first paramater, and a callback for the second.

= Commands with Arguments =

== Echo ==

We'll be working towards making some fun and useful commands—commands that let you control the seething tendrils of the internet with your little pinky. But, let's start by making a simple command to echo back whatever you type.

<pre>
CmdUtils.CreateCommand({
names: ["echo"],
arguments: [{role: "object",
nountype: noun_arb_text,
label: "your shout"}],
preview: function( pblock, arguments ) {
pblock.innerHTML = _("Will echo: ") + arguments.object.text;
},
execute: function( arguments ) {
var msg = arguments.object.text + "... " + arguments.object.text + "......";
displayMessage( msg );
}
});
</pre>

This says that the command "echo" takes one argument which is arbitrary text. Whatever text the user enters will get wrapped in an input object and passed into both the preview and execute function.

Try it! Ubiq "echo hellooooo" and watch what happens.

Ubiquity takes care of parsing the user's input, so you don't need to worry about handling prounoun substitution or any of the other natural-language-like features of the Ubiquity parser. Try selecting some text on a page, and Ubiq "echo this". Ubiquity should now echo the selected text.

Note that we gave three pieces of information when defining our argument: its role, its nountype, and its label. The label is the easiest part: It's just whatever text you want to have appear in the Ubiquity interface as a prompt for the user. E.g, if you ubiq "echo", you will see the label for the argument:

<pre>
echo (your shout)
</pre>

The roles and the nountypes require some more explanation. We'll cover each of them in detail next.

=== Argument Roles ===

Your command can take multiple arguments. Each one is identified by a "role". To understand roles, it helps to think of your command name as a verb, and each argument as a noun. Remember that Ubiquity's command line is a pseudo-natural-language environment, so it attempts to be as close to natural language grammar as possible.

For example, if you've ever used the <code>email</code> command, you know that it takes up to two arguments: a message and a person.

<pre>
email message
email to person
email message to person
email to person message
</pre>

In grammatical terms, the message argument is the "direct object" of the verb "email". The person argument is an indirect object. We call it the "goal" of the verb. So if we were writing the email command, we'd define the arguments like this:

<pre>
arguments: [{role: "object",
nountype: noun_arb_text,
label: "message"},
{role: "goal",
nountype: noun_type_contact,
label: "recipient"}]
</pre>

Because we give the recipient argument the "goal" role, the Ubiquity parser knows to expect the user to type the word "to". When the user enters "email hello to Aza", the parser knows that the word following "to" -- that is, "Aza" -- should be assigned to the recipient argument.

In our simple "echo" command, we expect the user to type "echo hellooooo" or something like that. The "hellooooo" is the direct object of the verb "echo", so we give it the "object" role.

"Object" is the most common role. If a command takes only one argument, that argument is usually an "object".

==== What Roles Can I Use? ====

* object (in "echo helloooo", hello is the object.)
* goal (in "email this to brandon", brandon is the goal.)
* source (in "translate this from spanish", spanish is the source.)
* location (in "yelp pizza near boston", boston is the location.)
* time (in "book a flight on thursday", thursday is the time.)
* instrument (in "search monkeys with google", google is the instrument.)
* format (in "check weather in celsius", celsius is the format.)
* modifier (in "get email address for chris", chris is the modifier.)
* alias (in "twitter this as jono", jono is the alias.)

[https://wiki.mozilla.org/Labs/Ubiquity/Parser_2/Semantic_Roles More information about these roles].

=== The Arguments Object ===

When your execute method is called, it is passed a single object that encapsulates the values for all arguments.

When your preview method is called, it is passed this object, too.

The object has one attribute corresponding to each role. In our example above, the command accepts only an object-role argument, so the preview and execute methods get passed an argument with an "arguments.object" attribute.

If we made a command, like email, that takes an object-role argument and a goal-role argument, its preview and execute methods would get passed an argument with "arguments.object" and "arguments.goal".

arguments.object (or arguments.goal) has several attributes of its own:

<pre>
arguments.object.text // a string of the input in plain text, without formatting
arguments.object.html // a string of the input in formatted html, including tags
arguments.object.data // for non-text input types, an arbitrary data object
arguments.object.summary // for very long inputs, an abbreviated display string
</pre>

Our example command only cares about the <code>.text</code> attribute of the input, because it simply wants plain text. Often, when the user invokes your command by typing a few short words into the input box, <code>.text</code>, <code>.html</code>, and <code>.summary</code> will all have exactly the same value, and <code>.data</code> will be null. Many, if not most, commands that you write will only care about the text value. Nevertheless, the other versions of the input data are provided to you in case they differ from <code>.text</code> and in case your command has a use for them.

== Introduction to Noun Types ==

Noun types specify what ''kind'' of input your command can accept for each one of its arguments.

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.

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.

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.

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)
* noun_type_language (Name of a human language, e.g. "English", "Japanese")
* noun_type_url (A URL)
* noun_type_contact (An email address from your address book)
* noun_type_date (A date, in any format, or a word like "tomorrow")
* noun_type_time (A time, in any format)
* noun_type_percentage
* noun_type_address
* noun_type_tab
* noun_type_searchengine
* noun_type_tag
* noun_type_geolocation

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 — and then come [[Labs/Ubiquity#Participation|get involved]] to help us improve them.

=== Regexps as Noun Types ===

If none of the nountypes above is what you're looking for, there are several ways to define your own. The simplest is to use a regular expression. Suppose that (for whatever odd reason) you wanted your command to accept only arguments that begin with the letter N. The following regexp matches words that start with N:

<pre>
/^[nN]/
</pre>

You could use it as a noun type, like so:

<pre>
arguments: [{role: "object",
nountype: /^[nN]/,
label: "word that starts with n"}]
</pre>

(Note that you do ''not'' put quotes around the regexp.)

A regexp nountype will reject input that doesn't match, but it doesn't know how to help the user by suggesting appropriate input.

=== Lists as Noun Types ===

Suppose you're writing a command that takes a color as an argument (perhaps it outputs a hexadecimal RGB representation of that color.) To make a nountype that accepts colors, you can simply pass in an array of strings:

<pre>
names: ["convert color"],
arguments: [{role: "object",
nountype: ["red", "orange", "yellow", "green",
"blue", "violet", "black", "white",
"grey", "brown", "beige", "magenta",
"cerulean", "puce"],
label: "color to convert"}]
</pre>

One benefit of using a list is that the parser can use it offer the user suggestions. If the user enters "get-color bl", for instance, Ubiquity will be able to suggest "black" and "blue" as the two valid completions based on the input. This makes list-based nountypes very useful for any command that can accept only a finite set of values.

=== Writing a Noun Type Object ===

Of course, not every type of noun you'd be interested in can be represented
as a finite list or as a regexp. If you want to be able to accept or reject input based on some algorithmic test, you can do so by writing a custom JavaScript object that implements a <code>suggest()</code> method (and, optionally, a <code>default()</code> method.)

There is an example of how to do this in the section on the tab commands, below.

== Insert Email: the Contact noun type ==

Let's take a look at one of the built-in noun-types: <code>noun_type_contact</code>. This lets Ubiquity know to expect a person (either by name or email address). By using the noun-type, Ubiquity will also autocomplete to known people while the user is entering the command. This is what the built-in Ubiquity command "email" uses.

At the moment, Ubiquity figures out what people you know through reading your Gmail contacts. In this prototyped version, you'll need to use Gmail and be logged in for for Ubiquity to know who you know. Eventually, we'd like to be able to interface with all major web-mail sites, as well as desktop software like Thunderbird.

Enough rambling. It's time for a command. I constantly find that I need to fetch someone's email address to paste into a text field because I don't know it off-hand. This command solves that by letting you insert someone's email address using autocomplete.

<pre>
CmdUtils.CreateCommand({
names: ["insert email"],
arguments: {modifier: noun_type_contact},
preview: "Inserts someone's email address by name.",
execute: function( arguments ) {
CmdUtils.setSelection( arguments.modifier.text );
}
});
</pre>

To try this out, Ubiq "insert email for " and then the first few letters of someone you email often.

=== Shorter Argument Declarations ===

Notice that we used a shortcut for declaring the arguments. In the long form, we would have had to say:

<pre>
arguments: [{role: "modifier",
nountype: noun_type_contact,
label: "contact"}]
</pre>

but if we don't care about specifying a label for the argument, we can get away with using a single object for "arguments", with the roles as the property names, and the nountypes as the property values:

<pre>
arguments: {modifier: noun_type_contact}
</pre>

If we had several arguments, and none of them needed labels, we could say:

<pre>
arguments: {object: noun_arb_text, modifier: noun_type_contact}
</pre>

and so on.

Aza writes:

<blockquote>
This one command sums up what I love about Ubiquity. In 8 lines of code, I can
fundamentally enhance the browser's functionality. Doing the same thing using
a normal Firefox extension methodology takes pages and pages of code—and the interface would take more thought still. Doing the same thing using a bookmarklet would require a server-side component (to get around cross-site Ajax request ban) as well as forcing the user to give up their email password.

Ubiquity increases the surface area of innovation for the browser many-fold, by making anyone who can write simple Javascript into an agent for bettering the browser and the open Web.
</blockquote>

== TinyURL: Network Calls and jQuery (and the URL noun type)==

Often while writing emails, I'll discover that I've pasted in a URL long enough to be used for unfortunate analogies. I'd like to be able to quickly turn that into a [http://en.wikipedia.org/wiki/Tinyurl TinyURL]—but the process of making a TinyURL involves lots of fiddly steps. Ubiquity to the rescue.

Because we include [http://en.wikipedia.org/wiki/jQuery jQuery] with Ubiquity, it is simple to perform Ajax calls as well as parse returning data. TinyUrl.com provides an easy to use RESTful API where you pass a URL and it returns its shortened form. We use that API in this command.

<pre>
CmdUtils.CreateCommand({
names: ["tinyurl"],
arguments: [{role: "object",
nountype: noun_type_url,
label: "url to shorten"}],
preview: "Replaces the selected URL with a TinyUrl.",
execute: function( arguments ) {
var baseUrl = "http://tinyurl.com/api-create.php";
var params = {url: arguments.object.text};
jQuery.get( baseUrl, params, function( tinyUrl ) {
CmdUtils.setSelection( tinyUrl );
})
}
})
</pre>

<code>noun_type_url</code> is a useful nountype because it defaults to the URL of the page that you are currently on. If that is in fact the URL that the user wants, then they don't have to type it or even select it.

jQuery is a powerful tool. With it, you can fairly effortlessly cherry-pick the data you need from RSS feeds, XML, and all sorts of other data formats. It also makes doing in-preview animations a breeze.

= Twitter: Putting It All Together =

We've now covered everything we need to cover in order to write a command that allows us to [http://en.wikipedia.org/wiki/Twitter Twitter] from Ubiquity. The code below is the actual source code of the Twitter command as it appears in Ubiquity 0.5.

Many thanks to [http://theunfocused.net/moz/ubiquity/verbs/ Blair McBride] for writing this command. The source code is a bit more intricate than anything we've seen so far, but it's built using exactly the same basic pieces -- and demonstrates nearly all of those pieces in action.

<pre>
const TWITTER_STATUS_MAXLEN = 140;

CmdUtils.CreateCommand({
names: ["twitter", "tweet", "share using twitter"],
arguments: [
{role: "object", label: 'status', nountype: noun_arb_text},
{role: "alias", nountype: noun_type_twitter_user}
],
icon: "http://twitter.com/favicon.ico",
description:
"Sets your Twitter status to a message of at most 160 characters.",
help: ("You'll need a <a href=\"http://twitter.com\">Twitter account</a>," +
" obviously. If you're not already logged in" +
" you'll be asked to log in."),
preview: function(previewBlock, args) {
var statusText = (args.object ? args.object.text : '');
var usernameText = "";
if (args.alias) {
usernameText = args.alias.text;
} else if (args.as) {
usernameText = args.as.text;
}
var previewTemplate = (
"<div class='twitter'>"+_("Updates your Twitter status ${username} to:")+" " +
"${status} " +
_("Characters remaining: ${chars}") +
""+_("tip: tweet @mozillaubiquity for help")+"</div>");
var truncateTemplate = (
""+_("The last ${truncate} characters will be truncated!")+"");
var previewData = {
status: <>{statusText}</>.toXMLString(),
username: usernameText && _("(For user ${usernameText})"),
chars: TWITTER_STATUS_MAXLEN - statusText.length
};

var previewHTML = CmdUtils.renderTemplate(
CmdUtils.renderTemplate(previewTemplate, previewData),
{usernameText:usernameText});

if (previewData.chars < 0) {
var truncateData = {
truncate: 0 - previewData.chars
};

previewHTML += CmdUtils.renderTemplate(truncateTemplate, truncateData);
}

previewBlock.innerHTML = previewHTML;
},
execute: function(args) {
var statusText = args.object.text;
if(statusText.length < 1) {
this._show(_("requires a status to be entered"));
return;
}

var updateUrl = "https://twitter.com/statuses/update.json";
var updateParams = {
source: "ubiquity",
status: statusText
//dont cut the input since sometimes, the user selects a big url,
//and the total lenght is more than 140, but tinyurl takes care of that
};
var me = this;

function sendMessage() {
jQuery.ajax({
type: "POST",
url: updateUrl,
data: updateParams,
dataType: "json",
error: function() {
me._show(_("error - status not updated"));
},
success: function() {
me._show(/^d /.test(statusText)
? _("direct message sent")
: _("status updated"));
},
username: login.username,
password: login.password
});
}

var login;
var alias = args.alias;
if (alias && alias.text && alias.data) {
login = alias.data;
sendMessage();
} else {
login = {username: null,
password: null};
if (alias && alias.text)
login.username = alias.text;
sendMessage();
}
},
_show: function(txt){
displayMessage({icon: this.icon, title: this.name, text: txt});
}
});
</pre>

= Switching Tabs =

The final command in this tutorial is for switching between tabs. The end goal is this: type a few keys to that matches the title of an open tab (in any window), hit return, and you've switched to that tab.

We'll write this command in two steps. The first step is creating a tab noun-type. The second step is using that noun-type to create the tab-switching command.

== Switching: Writing your own Noun-Types ==

A noun-type needs to only have two things: A <code>label</code> and a <code>suggest()</code> function. It can optionally also have a <code>default()</code> function.

The label is what shows up when the command prompts for input. Suggest returns a list of input objects, each one containing the name of a matching tab. We're using [http://developer.mozilla.org/en/docs/FUEL FUEL] to interact with the browser, which is where the "Application" variable comes from.

<pre>
var noun_type_tab = {
label: "tab name",

// Returns all tabs from all windows.
getTabs: function(){
var tabs = {};

for( var j=0; j < Application.windows.length; j++ ) {
var window = Application.windows[j];
for (var i = 0; i < window.tabs.length; i++) {
var tab = window.tabs[i];
tabs[tab.document.title] = tab;
}
}

return tabs;
},

suggest: function( text, html, callback ) {

var suggestions = [];
var tabs = noun_type_tab.getTabs();

//TODO: implement a better match algorithm
for ( var tabName in tabs ) {
if (tabName.match(text, "i"))
suggestions.push( CmdUtils.makeSugg(tabName) );
}

// Return a list of input objects, limited to at most five:
return suggestions.splice(0, 5);
}
}
</pre>

The suggest method of a noun type always gets passed both text and html. If the input is coming from a part of a web page that the user has selected, these
values can be different: they are both strings, but the html value contains markup tags while the text value does not. The Tab noun type only cares about the plain text of the tab name, so we ignore the value of html.

The callback argument is for use by nountypes that need to run asynchronously, i.e. becaus they need to do network calls to generate suggestions. The callback is a function; instead of returning a list of suggestions right away, an asynchronous noun type can call the callback with each suggestion it generates. More on this later; the tab noun type generates all its suggestions right away, so it just returns them instead of using the callback.

We use the convenience function <code>CmdUtils.makeSugg()</code> to generate an
input object of the type that the Ubiquity parser expects. The full signature of this function is
<pre>
CmdUtils.makeSugg( text, html, data );
</pre>
but html and data are optional and need be provided only if they differ from text.

If the text or html input is very long, <code>makeSugg()</code> generates a summary for us, and puts it in the <code>.summary</code> attribute of the input object.

We could have accomplished mostly the same thing without calling <code>makeSugg()</code> by returning a list of anonymous objects like these:
<pre>
{ text: tabName,
html: tabName,
data: null,
summary: tabName };
</pre>

The input objects that our <code>.suggest()</code> method generates are the same objects that will eventually get passed in to the <code>execute()</code> and <code>preview()</code> methods of any commands that use this noun type.

== Switching Tabs: The Command ==

Now that we are armed with the tab noun-type, it is easy to make the tab-switching command. Again, we use FUEL to focus the selected tab.

<pre>
CmdUtils.CreateCommand({
names: ["tab"],
arguments: {object: noun_type_tab},

execute: function( arguments ) {
var tabName = arguments.object.text;
var tabs = noun_type_tab.getTabs();
tabs[tabName]._window.focus();
tabs[tabName].focus();
},

preview: function( pblock, arguments ) {
var tabName = arguments.object.text;
if( tabName.length > 1 ){
var msg = "Changes to ${tab} tab.";
pblock.innerHTML = _(msg, {tab: tabName});
}
else
pblock.innerHTML = _("Switch to a tab by name.");
}
})
</pre>

= Development Hints =

You now know all you need to know to get started developing useful Ubiquity commands of your own.

Here are some miscellaneous tips that didn't fit elsewhere on this page, that may make development easier for you.

== The Source Code of Built-In Commands ==

Looking at the source code of built-in commands and built-in noun types can be a very useful aid to development. If you have the source checkout of Ubiquity (see [Labs/Ubiquity/Ubiquity_0.1_Development_Tutorial | the development tutorial] to find out how to get this), the source code can be found in the files:

ubiquity/standard-feeds/
ubiquity/builtin-feeds/en/builtincmds.js
ubiquity/modules/nountypes.js

If you don't have a checkout of the source code, you can view the latest version on the web here:

[http://hg.toolness.com/ubiquity-firefox/file/tip/ubiquity/standard-feeds/ standard-feeds]
[http://hg.toolness.com/ubiquity-firefox/file/tip/ubiquity/builtin-feeds/en/builtincmds.js builtincmds.js]
[http://hg.toolness.com/ubiquity-firefox/file/tip/ubiquity/modules/nountypes.js nountypes.js]

== Interacting with Other Extensions ==

http://img363.imageshack.us/img363/1906/picture7cm5.png

There isn't much to say here besides that it's easy. For example, here's a command (thanks to [http://foyrek.com/lyrics.html Abimanyu Raja] for writing this code) that finds the lyrics for a song. You can simply Ubiq something like "get lyrics for wild international" but the command will also interface with the FoxyTunes extension (if it is installed) and add the currently playing song to the suggestion list. Interfacing with other extensions, too, is easy because you can view the source code for every Firefox extension.

<pre>
var noun_type_song = {
label: "song name",
suggest: function( text, html ) {
var suggestions = [CmdUtils.makeSugg(text)];
if(window.foxytunesGetCurrentTrackTitle){
suggestions.push(CmdUtils.makeSugg(window.foxytunesGetCurrentTrackTitle()));
}
return suggestions;
}
}

CmdUtils.CreateCommand({
names: ["get lyrics"],
arguments: {modifier: noun_type_song},
preview: function(pblock, arguments) {

searchText = jQuery.trim(arguments.modifier.text);
if(searchText.length < 1) {
pblock.innerHTML = _("Searches for lyrics of the song");
return;
}

var previewTemplate = "Searches for the lyrics of ${query}";
pblock.innerHTML = _(previewTemplate, {query: searchText});

},
execute: function(arguments) {
var url = "http://www.google.com/search?q={QUERY}"
var query = arguments.object.text + _(" lyrics");
var urlString = url.replace("{QUERY}", query);
Utils.openUrlInBrowser(urlString);
}
});
</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",
label: "topic",
suggest: function freebase_topic_suggest(text, html, callback) {
return [
CmdUtils.makeSugg(text),
$.ajax({
url: "http://www.freebase.com/api/service/search",
dataType: "json",
data: {prefix: text, limit: 5},
success: function suggestTopics(response) {
if (response.status === "200 OK")
callback([CmdUtils.makeSugg(result.name, result.name, result)
for each (result in response.result)]);
},
})];
}
};

CmdUtils.CreateCommand({
names: ["lookup on freebase"],
arguments: {object: noun_type_freebase_topic},
preview: function preview(pblock, args) {
pblock.innerHTML = _(("Go to the Freebase topic page for " +
"{if text}${text}{else}any topic{/if}."),
args.object);
},
execute: function goToFreebase({object: {text, data}}) {
Utils.openUrlInBrowser(
text
? (data
? "http://www.freebase.com/view" + data.id
: ("http://www.freebase.com/search?query=" +
encodeURIComponent(text)))
: "http://www.freebase.com/");
}
});
</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 ==

Commands aren't the only thing you can put in a command feed. You can also include functions you want to be run automatically at page-load time and at Firefox startup time.

In order to run some code on page load, you simply have to prefix your function with <code>pageLoad_</code>. For example, if you want to say "Hi" every time a page is loaded, your code would look like this:

<pre>
function pageLoad_hi(){
displayMessage("hi");
}
</pre>

If you modify the function and want to see the changes, remember to first invoke Ubiquity. Although your function like above, might not be a Ubiquity command, this is necessary to refresh the cached code.

Similarly, if you want to run some code everytime Firefox starts up, you just have to prefix the function with <code>startup_</code> .

The awesome thing about these functions is the ability to develop whole Firefox extensions (that require minimal UI) as Ubiquity plugins in lesser lines of code. You don't need to worry about chrome.manifest or install.rdf. Another added benefit is that you never have to restart your Firefox during development unless of course, you are running code on Firefox startup.

<center>http://img388.imageshack.us/img388/3086/picture5eo9.png</center>

Here's the code for [http://foyrek.com/keyscape.js Keyscape] which is a Ubiquity command that makes use of <code>pageLoad</code> and <code>startup</code> to recreate the functionality of the [https://addons.mozilla.org/en-US/firefox/addon/339 Search Keys extension] by Jesse Ruderman. In line with Ubiquity's aim to let you do things quicker using your keyboard, this command lets you go to search results on Google by just pressing a number. It'll add hints to show the number of each link.

<pre>
//A lot of this code is borrowed from the Search Keys extension
//Many thanks to Jeese Ruderman

function startup_keyscape() {
window.addEventListener("keydown", keyscape_down, true);
}

function pageLoad_keyscape(doc){

var uri = Utils.url(doc.documentURI);
//If we are on about: or chrome://, just return
if(uri.scheme != "http")
return;

//Check if the page we are on is google
if( keyscape_isGoogle(uri) ){

for(var num=1; num<=10; num++){

var link = jQuery(doc.body).find('a.l')[num-1];

if( link ){

var hint = doc.createElementNS("http://www.w3.org/1999/xhtml", "span");
hint.style.color = "blue";
hint.style.background = "white";
hint.style.padding = "1px 2px 1px 2px";
hint.style.marginLeft = ".5em";
hint.appendChild(doc.createTextNode(num == 10 ? 0 : num));
link.parentNode.insertBefore(hint, link.nextSibling);
}
}
}
}

function keyscape_isGoogle(uri){
return uri.host.indexOf("google") != -1
&& (uri.path.substr(0,8) == "/search?"
|| uri.path.substr(0,8) == "/custom?");
}

function keyscape_down(event){

var doc = Application.activeWindow.activeTab.document;
var uri = Utils.url(doc.documentURI);

if( keyscape_isGoogle(uri) ){

var key = parseInt(event.keyCode || event.charCode);
var num;

if(48 <= key && key <= 57) //number keys
num = key - 48;
else if(96 <= key && key <= 105) //numeric keypad with numlock on
num = key - 96;
else
return;

//Don't do anything if we are in a textbox
//or some other related elements
var elt = window.document.commandDispatcher.focusedElement;

if (elt) {
var ln = new String(elt.localName).toLowerCase();
if (ln == "input" || ln == "textarea" || ln == "select" || ln == "isindex")
return;
}

//Get the link url from the search results page
var url_dest = jQuery(doc.body).find('a.l').eq(num-1).attr('href');

if(event.altKey){
//Open in new tab
Application.activeWindow.open(Utils.url(url_dest));
}else{
//Open in same tab
doc.location.href = url_dest;
}
}
}
</pre>

If Ubiquity does indeed become ubiquitous, a lot of extensions can be re-written as Ubiquity commands. This is much nicer for the end-user, as well, because the Ubiquity command installation process is a lot easier.

In the future, Ubiquity is also likely to have the ability to convert your Ubiquity commands into proper Firefox extensions. Look [http://labs.toolness.com/trac/ticket/3 here] to check on the progress of this functionality.

== Firebug ==

Ubiquity automatically enables Chrome Errors and Warnings on startup so that errors in your code appear in the Firebug console. Just use <tt>CmdUtils.log()</tt> rather than <tt>console.log()</tt>.

= Where To Go From Here =

Take a look at Ubiquity's reference documentation for the <tt>[https://ubiquity.mozilla.com/hg/ubiquity-firefox/raw-file/tip/ubiquity/index.html#modules/utils.js Utils]</tt> and <tt>[https://ubiquity.mozilla.com/hg/ubiquity-firefox/raw-file/tip/ubiquity/index.html#modules/cmdutils.js CmdUtils]</tt> namespaces.

If you have any questions or comments, feel free to join us on IRC at <tt>#ubiquity</tt> on <tt>irc.mozilla.org</tt>, as well as the [http://groups.google.com/group/ubiquity-firefox Ubiquity Google Group].

= Conclusion =

To reiterate a point I made before: Ubiquity increases the surface area of innovation for the browser many-fold, by making anyone who can write simple Javascript into an agent for bettering the browser and the open Web. You are one of those agents.

Now, go forth and create.

Labs/Ubiquity/Ubiquity 0.5 Author Tutorial

2009-07-10T23:10:28Z

Endolith:

Back to [[Labs/Ubiquity]].

Author: Aza Raskin, Blair McBride, Abimanyu Raja, Jono DiCarlo, Atul Varma

= The Ubiquity version 0.5 Command Tutorial =

The great power of Ubiquity—from a developer standpoint—is how easy it is to create commands. With only a couple of lines of Javascript, Ubiquity enables even casual web developers to drastically enhance the features of the browser. From an 8-line command to insert a contact's email address in any text field, to a 50-line Twitter integration, this tutorial walks you through the process of being generative with Ubiquity.

The rest of this page documents the command developer API as it stands frozen in version 0.5.

If you want the bleeding-edge command developer API (which includes any new features that may have been added to the Ubiquity source code in HG but not yet included in a release), then that's [[Labs/Ubiquity/Ubiquity_Source_Tip_Author_Tutorial|here]].

If you want the old command developer API, as it stood in Ubiquity 0.1 (not recommended), that's [[Labs/Ubiquity/Ubiquity_0.1_Author_Tutorial|here]].

== Real Time Development ==

Ubiquity doesn't require you to restart Firefox as you develop. Restarting is a drastic measure, and we want none of it. Instead, Ubiquity reloads the commands every time it is summoned. When you are using the built-in editor then you don't even need to save!

To open the Ubiquity command editor, summon Ubiquity (control/alt + space) and use the "open command editor" command. Throughout this tutorial, when we want you to run a command in Ubiquity, we'll say '''Ubiq''' it. For instance, to open the editor, just Ubiq "open command editor".

In the following examples, just type in this editor. Updates happen the next time you summon Ubiquity.

== Choices, Choices... ==

You may notice a drop-down menu mentioning something about a "feed type" just above the editing field in the command editor:

http://www.toolness.com/images/20090318121423.jpg

For now, just make sure this drop-down is set to "Regular". We'll tell you more about what this means later.

= Hello World: The First Command =

== Just a Message: As Simple as it Gets ==

Let's start with the standard programing trope: printing "Hello, World!".

In the command editor type the following:

<pre>
CmdUtils.CreateCommand({
names: ["say hello"],
execute: function() {
displayMessage( "Hello, World!");
}
});
</pre>

Now try Ubiq-ing "say hello". You'll see that "Hello, World!" is immediately displayed on the screen. If you are on Mac OSX with [http://en.wikipedia.org/wiki/Growl_(software) Growl] installed the message will appear as a Growl notification. If you are on Windows, then it will appears as a standard "toaster" notification in the bottom right-hand corner of the screen.

http://farm3.static.flickr.com/2479/3651542339_022e4aa4c4.jpg

http://img517.imageshack.us/img517/7726/picture2vx2.png

In Ubuntu 8.04 (Hardy Heron) this appears thus:

http://img293.imageshack.us/img293/7746/ubiqubuntuhelloworldeq9.png

If you don't have Growl installed on OSX, or aren't on a Windows XP/Vista or Ubuntu Hardy, then you won't get any sort of notification. That's something to be [http://labs.toolness.com/trac/ticket/19 worked on] in future releases of Ubiquity.

=== CmdUtils.CreateCommand ===

<code>CmdUtils</code> is a namespace which contains all the functions you need to create commands. Commands are created by making an object and passing it to <code>CmdUtils.CreateCommand</code>. In Javascript, inline curly braces mean "new object", so this code:

<pre>
{
names: ["say hello"],
execute: function() { //etc }
}
</pre>

means "Make an object with two attributes, 'names' and 'execute'." This object is then passed as the argument to <code>CmdUtils.CreateCommand</code>.

=== names ===

'names' and 'execute' are the only two mandatory attributes for your command object. 'names' specifies what the command is called, and 'execute' specifies what it does. There are plenty of other attributes that you can specify, but they are all optional.

'names' is always an array (thus the square brackets). In the case of this command we provided only one name, "hello world". But we could have provided as many names as we wanted. For instance, if we had said:

names: ["say hello", "greet"]

then "say hello" would be the normal name of the command, but Ubiquity would also recognize "greet" as a synonym or alias for the command.

=== execute ===

'execute' is always a function. When the user executes your command, this is the function that will be run. It can do pretty much anything you want -- or at least, anything you know how to write in JavaScript.

In the example above, we simply call <code>displayMessage()</code>, which displays the given message in whichever way the operating system can.

There are a number of other useful functions in the <code>CmdUtils</code> 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 [http://hg.toolness.com/ubiquity-firefox/file/9a6c9935da9f/ubiquity/chrome/content/cmdutils.js cmdutils.js].

=== Making sure your command is localizable ===

Ubiquity now supports multiple languages. That means that hopefully someday someone will be translating your commands to the other languages that Ubiquity supports. Making your command localizable is easy, and a good habit to get into! You just have to locate all strings that appear in your <code>preview()</code> and <code>execute()</code> methods, that are intended for display to humans, and wrap them with:

_()

This may look odd, but what it does is quite important: it makes your strings appear in the template files that localizers will be using. So let's make our "Hello world!" command localizable:

<pre>
CmdUtils.CreateCommand({
names: ["say hello"],
execute: function() {
displayMessage( _("Hello, World!") );
}
});
</pre>

This makes it so that when a localization template is generated from your command feed, "Hello, World!" will be listed among the strings to be translated.

Note that we don't need to wrap the names, or other strings that appear in the command metadata -- these are automatically wrapped for us. We only need to wrap strings that appear inside the functions.

== Adding a Preview ==

http://img352.imageshack.us/img352/1002/picture3ex0.png

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 "say hello" command, we don't need anything fancy: just some help text that is more descriptive than the default "Executes the say hello command."

<pre>
CmdUtils.CreateCommand({
names: ["say hello", "greet"],
preview: "Displays a salutary greeting to the planet.",
execute: function() {
displayMessage( _("Hello, World!") );
}
})
</pre>

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.

<pre>
CmdUtils.CreateCommand({
names: ["insert date"],
execute: function() {
var date = new Date();
CmdUtils.setSelection( date.toLocaleDateString() );
}
})
</pre>

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>toLocalDateString()</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].

== A Better Preview ==

It's time to add a better preview to the date command. Let's have the preview show the date, so that the user will know what to expect when they execute the command. (As a side benefit the user doesn't even need to execute the command to do a quick check of the day.)

<pre>
CmdUtils.CreateCommand({
names: ["insert date"],

_date: function(){
var date = new Date();
return date.toLocaleDateString();
},

preview: function( pblock ) {
var msg = _('Inserts todays date: "${date}"');
pblock.innerHTML = CmdUtils.renderTemplate( msg, {date: this._date()} );
},

execute: function() {
CmdUtils.setSelection( this._date() );
}
})
</pre>

We've done two things here. The first was to factor out the code for getting the date into the <code>_date()</code> function. This way we don't break [http://en.wikipedia.org/wiki/Don%27t_repeat_yourself DRY] by repeating code across the preview and execute functions. Notice that to access the <code>_date()</code>, we use the <code>this</code> keyword.

The second thing we've done is to add a preview function. The first argument is the DOM element that gets displayed as the preview for your command. Modify <code>pblock</code> and you modify the preview. In this case, we set the <code>innerHTML</code> of the preview block to be the message we want.

The other thing I've done is to do some string formatting using the <code>renderTemplate()</code> function. This takes a template string and performs the appropriate substitution given the passed-in JSON object. Templates can handle a wide range of functionality, as we are currently using TrimPath's [http://code.google.com/p/trimpath/wiki/JavaScriptTemplates JavascriptTemplates]. You should read their site for more documentation. Although JavascriptTemplates has some nice properties, we are contemplating moving to [http://mjtemplate.org/ MJT] sometime soon.

=== A shortcut for localization and rendering templates ===

Note how in the code above, we used the localization wrapper <code>_()</code> before passing the string to renderTemplate. Because this is such a very common combination when displaying strings, we have a shortcut for it. Calling _() with a JSON object as the second argument will automatically trigger <code>CmdUtils.renderTemplate()</code> on the post-localization string. So the above preview method could be rewritten more simply as:

<pre>
preview: function( pblock ) {
var msg = 'Inserts todays date: "${date}"';
pblock.innerHTML = _( msg, {date: this._date()} );
},
</pre>

=== Networking calls and placeholder previews ===

Previews display something meaningful to the user immediately. If you have a preview that requires an AJAX request—say, to fetch some search results—that call might take a while to return. In the meantime, your command should display a placeholder preview giving the user feedback.

<pre>
preview: function( pblock ) {
pblock.innerHTML = _("This will show until the AJAX request returns");
// AJAX request
pblock.innerHTML = getFromServer();
},
</pre>

In the future, we may work on streamlining this process.

== Documentation and Metadata ==

Before you share your command with the world, you should consider adding some attributions to the code:

<pre>
CmdUtils.CreateCommand({
names: ["insert date"],
homepage: "http://azarask.in/",
author: { name: "Aza Raskin", email: "aza@mozilla.com"},
contributors: ["Atul Varma"],
license: "MPL",

/* THE REST OF THE CODE HERE */
})
</pre>

And you should definitely add some documentation:

<pre>
CmdUtils.CreateCommand({
names: ["insert date"],
homepage: "http://azarask.in/",
author: { name: "Aza Raskin", email: "aza@mozilla.com"},
contributors: ["Atul Varma"],
license: "MPL",
description: "Inserts today's date.",
help: "If you're in an editable text area, inserts today's date, formatted for the current locale.",

/* THE REST OF THE CODE HERE */
})
</pre>

The <code>.description</code> and <code>.help</code> attributes are both automatically displayed alongside your command's name on the command-list page. (The user can get to this page at any time by issuing the "list ubiquity commands" command.) HTML tags can be used in both of these strings.

Description is a one-line summary of what the command does, while Help is a longer description that can include examples, caveats, and so on. If your command is simple enough that all you have to say about it fits in one line, it's OK to use a description alone and leave out the help.

== Sharing it with the World ==

Now that we've got our awesome new "date" command, let's share it with the world. All you have to do is put it the javascript file on the web somewhere, and make an html page linking to it with "link rel".

<pre><link rel="commands" href="http://path-to-js" name="Title Goes Here" /></pre>

Anyone with Ubiquity who visits will get a message offering them the choice of subscribing to your command.

[[Image:Subscribe.png]]

If the user chooses to subscribe to a Regular command feed from an untrusted source, they will get a security warning message before they can install the command. Because Regular Ubiquity command feeds can execute arbitrary javascript with chrome privileges, subscribing to a command from a website means allowing that site full access to do whatever it wants to your browser. We want to make sure people understand the dangers before subscribing to commands, so we made the warning page pretty scary.

[[Image:Warning.PNG]]

=== Feed Types ===

Recall that back near the beginning of the tutorial, you set the "feed type" to "Regular". As you may have guessed, there's actually more than one way to write a command feed. The advantage of Regular feeds is that they let you do whatever you want, so it's really easy to innovate, but the disadvantages lie in subscribing to misbehaving or malicious code. You can alternatively write what's called a ''Locked-Down Feed'', which is much safer and doesn't raise a warning page when a user subscribes to it—but the consequences are that you have less freedom of implementation as a command author. If you're interested in learning more about Locked-Down Feeds, check out the [[Labs/Ubiquity/Locked-Down_Feed_Tutorial|Locked-Down Feed Tutorial]].

=== Trust Networks ===

In the future, we're going to have something set up that we call a "trust network". When you try out a Ubiquity command from a website, and determine that the command is safe (or unsafe), you'll be able to leave an approval (or a warning). When your friends with Ubiquity installed visit the same site, they'll see the approval or the warning that you left. In this way, users will be able to rely on the judgement of other people they already know and trust in order to help them make decisions about whether a command is safe to install or not.

By the way, the reason we call it "subscribing" to a command, rather than "installing" a command, is that if the javascript file changes -- if the site owner adds new commands, removes old commands, or updates existing commands -- all users subscribed to that URL will automatically get the updates. This will be very convenient for both users and developers, but it will also introduce another type of security risk: just because you decided a command was safe at one point in time doesn't mean that the command will always remain safe. For this reason, we'll need to make sure that the trust network keeps track of when commands have been modified, and notifies users of changes that may make a command unsafe.

== Map Me! Location, Snapshots, and Inserting HTML ==

The "map" command that comes with Ubiquity is fairly powerful. It's also fairly complicated—well, comparatively. It's still only a couple hundred lines of code. The command, though, can get even more useful. Imagine being able to select some houses on Craigslist, or a list of restaurant names, and Ubiq "map these" to get just the map you want. The concept of "these" puts the power of mashups into the users hands. But I digress. Let's make a simple command that inserts a map of your current location.

In this command, we use the Google [http://code.google.com/apis/maps/documentation/staticmaps/ static map API] and the Ubiquity function <code>CmdUtils.getGeoLocation()</code> to insert a map of your current location. Ubiquity currently uses the [http://www.maxmind.com/app/api MaxMind] API for trying to guess your location from your IP. That will probably change in the future.

We'll call this command <code>"map me"</code> so that it won't be confused with the standard <code>"map"</code> command.

<pre>
CmdUtils.CreateCommand({
names: ["map me"],

_getMapUrl: function() {
var loc = CmdUtils.getGeoLocation();
var mapUrl = "http://maps.google.com/staticmap?";

var params = {
center: loc.lat + "," + loc.long,
size: "500x400",
zoom: 14,
key: "ABQIAAAAGZ11mh1LzgQ8-8LRW3wEShQeSuJunOpTb3RsLsk00-MAdzxmXhQoiCd940lo0KlfQM5PeNYEPLW-3w"
};

return mapUrl + jQuery.param( params );
},

preview: function( pblock ) {
var msg = "Inserts a map of your current location: " +
"<img src='${url}'/>";
pblock.innerHTML = _(msg, {url: this._getMapUrl()});
},

execute: function( ) {
CmdUtils.getImageSnapshot( this._getMapUrl(), function(imgData) {
CmdUtils.setSelection( "<img src='" + imgData +"'/>");
})
}
})
</pre>

There are three new things here: <code>CmdUtils.setSelection</code> to set HTML (yep, it can do that); the use of <code>CmdUtils.getGeoLocation()</code>; and using <code>CmdUtils.snapshotImage()</code> to capture the bits for the image.

I find getting the location—as imprecise as IP-based location can be—useful for doing sensible defaults for location-based commands, like Yelp. <code>CmdUtils.getGeoLocation()</code> returns an object which has the following properties: city, state, country, lat, and long.

Why do we need to use <code>CmdUtils.snapshotImage()</code>? Because the Google Maps API requires a key that is tied to a particular URL. If we naively inject the image tag into a random web page, the image won't load because the key doesn't match that random web page's URL. Thus, we use the <code>snapshotImage()</code> function to convert the image into a [http://en.wikipedia.org/wiki/Data:_URI_scheme data url].

There's also a <code>CmdUtils.snapshotWindow</code> function, which allows you to get the image data for any tab/window. The function takes a window as the first paramater, and a callback for the second.

= Commands with Arguments =

== Echo ==

We'll be working towards making some fun and useful commands—commands that let you control the seething tendrils of the internet with your little pinky. But, let's start by making a simple command to echo back whatever you type.

<pre>
CmdUtils.CreateCommand({
names: ["echo"],
arguments: [{role: "object",
nountype: noun_arb_text,
label: "your shout"}],
preview: function( pblock, arguments ) {
pblock.innerHTML = _("Will echo: ") + arguments.object.text;
},
execute: function( arguments ) {
var msg = arguments.object.text + "... " + arguments.object.text + "......";
displayMessage( msg );
}
});
</pre>

This says that the command "echo" takes one argument which is arbitrary text. Whatever text the user enters will get wrapped in an input object and passed into both the preview and execute function.

Try it! Ubiq "echo hellooooo" and watch what happens.

Ubiquity takes care of parsing the user's input, so you don't need to worry about handling prounoun substitution or any of the other natural-language-like features of the Ubiquity parser. Try selecting some text on a page, and Ubiq "echo this". Ubiquity should now echo the selected text.

Note that we gave three pieces of information when defining our argument: its role, its nountype, and its label. The label is the easiest part: It's just whatever text you want to have appear in the Ubiquity interface as a prompt for the user. E.g, if you ubiq "echo", you will see the label for the argument:

<pre>
echo (your shout)
</pre>

The roles and the nountypes require some more explanation. We'll cover each of them in detail next.

=== Argument Roles ===

Your command can take multiple arguments. Each one is identified by a "role". To understand roles, it helps to think of your command name as a verb, and each argument as a noun. Remember that Ubiquity's command line is a pseudo-natural-language environment, so it attempts to be as close to natural language grammar as possible.

For example, if you've ever used the <code>email</code> command, you know that it takes up to two arguments: a message and a person.

<pre>
email message
email to person
email message to person
email to person message
</pre>

In grammatical terms, the message argument is the "direct object" of the verb "email". The person argument is an indirect object. We call it the "goal" of the verb. So if we were writing the email command, we'd define the arguments like this:

<pre>
arguments: [{role: "object",
nountype: noun_arb_text,
label: "message"},
{role: "goal",
nountype: noun_type_contact,
label: "recipient"}]
</pre>

Because we give the recipient argument the "goal" role, the Ubiquity parser knows to expect the user to type the word "to". When the user enters "email hello to Aza", the parser knows that the word following "to" -- that is, "Aza" -- should be assigned to the recipient argument.

In our simple "echo" command, we expect the user to type "echo hellooooo" or something like that. The "hellooooo" is the direct object of the verb "echo", so we give it the "object" role.

"Object" is the most common role. If a command takes only one argument, that argument is usually an "object".

==== What Roles Can I Use? ====

* object (in "echo helloooo", hello is the object.)
* goal (in "email this to brandon", brandon is the goal.)
* source (in "translate this from spanish", spanish is the source.)
* location (in "yelp pizza near boston", boston is the location.)
* time (in "book a flight on thursday", thursday is the time.)
* instrument (in "search monkeys with google", google is the instrument.)
* format (in "check weather in celsius", celsius is the format.)
* modifier (in "get email address for chris", chris is the modifier.)
* alias (in "twitter this as jono", jono is the alias.)

[https://wiki.mozilla.org/Labs/Ubiquity/Parser_2/Semantic_Roles More information about these roles].

=== The Arguments Object ===

When your execute method is called, it is passed a single object that encapsulates the values for all arguments.

When your preview method is called, it is passed this object, too.

The object has one attribute corresponding to each role. In our example above, the command accepts only an object-role argument, so the preview and execute methods get passed an argument with an "arguments.object" attribute.

If we made a command, like email, that takes an object-role argument and a goal-role argument, its preview and execute methods would get passed an argument with "arguments.object" and "arguments.goal".

arguments.object (or arguments.goal) has several attributes of its own:

<pre>
arguments.object.text // a string of the input in plain text, without formatting
arguments.object.html // a string of the input in formatted html, including tags
arguments.object.data // for non-text input types, an arbitrary data object
arguments.object.summary // for very long inputs, an abbreviated display string
</pre>

Our example command only cares about the <code>.text</code> attribute of the input, because it simply wants plain text. Often, when the user invokes your command by typing a few short words into the input box, <code>.text</code>, <code>.html</code>, and <code>.summary</code> will all have exactly the same value, and <code>.data</code> will be null. Many, if not most, commands that you write will only care about the text value. Nevertheless, the other versions of the input data are provided to you in case they differ from <code>.text</code> and in case your command has a use for them.

== Introduction to Noun Types ==

Noun types specify what ''kind'' of input your command can accept for each one of its arguments.

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.

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.

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.

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)
* noun_type_language (Name of a human language, e.g. "English", "Japanese")
* noun_type_url (A URL)
* noun_type_contact (An email address from your address book)
* noun_type_date (A date, in any format, or a word like "tomorrow")
* noun_type_time (A time, in any format)
* noun_type_percentage
* noun_type_address
* noun_type_tab
* noun_type_searchengine
* noun_type_tag
* noun_type_geolocation

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 — and then come [[Labs/Ubiquity#Participation|get involved]] to help us improve them.

=== Regexps as Noun Types ===

If none of the nountypes above is what you're looking for, there are several ways to define your own. The simplest is to use a regular expression. Suppose that (for whatever odd reason) you wanted your command to accept only arguments that begin with the letter N. The following regexp matches words that start with N:

<pre>
/^[nN]/
</pre>

You could use it as a noun type, like so:

<pre>
arguments: [{role: "object",
nountype: /^[nN]/,
label: "word that starts with n"}]
</pre>

(Note that you do ''not'' put quotes around the regexp.)

A regexp nountype will reject input that doesn't match, but it doesn't know how to help the user by suggesting appropriate input.

=== Lists as Noun Types ===

Suppose you're writing a command that takes a color as an argument (perhaps it outputs a hexadecimal RGB representation of that color.) To make a nountype that accepts colors, you can simply pass in an array of strings:

<pre>
names: ["convert color"],
arguments: [{role: "object",
nountype: ["red", "orange", "yellow", "green",
"blue", "violet", "black", "white",
"grey", "brown", "beige", "magenta",
"cerulean", "puce"],
label: "color to convert"}]
</pre>

One benefit of using a list is that the parser can use it offer the user suggestions. If the user enters "get-color bl", for instance, Ubiquity will be able to suggest "black" and "blue" as the two valid completions based on the input. This makes list-based nountypes very useful for any command that can accept only a finite set of values.

=== Writing a Noun Type Object ===

Of course, not every type of noun you'd be interested in can be represented
as a finite list or as a regexp. If you want to be able to accept or reject input based on some algorithmic test, you can do so by writing a custom JavaScript object that implements a <code>suggest()</code> method (and, optionally, a <code>default()</code> method.)

There is an example of how to do this in the section on the tab commands, below.

== Insert Email: the Contact noun type ==

Let's take a look at one of the built-in noun-types: <code>noun_type_contact</code>. This lets Ubiquity know to expect a person (either by name or email address). By using the noun-type, Ubiquity will also autocomplete to known people while the user is entering the command. This is what the built-in Ubiquity command "email" uses.

At the moment, Ubiquity figures out what people you know through reading your Gmail contacts. In this prototyped version, you'll need to use Gmail and be logged in for for Ubiquity to know who you know. Eventually, we'd like to be able to interface with all major web-mail sites, as well as desktop software like Thunderbird.

Enough rambling. It's time for a command. I constantly find that I need to fetch someone's email address to paste into a text field because I don't know it off-hand. This command solves that by letting you insert someone's email address using autocomplete.

<pre>
CmdUtils.CreateCommand({
names: ["insert email"],
arguments: {modifier: noun_type_contact},
preview: "Inserts someone's email address by name.",
execute: function( arguments ) {
CmdUtils.setSelection( arguments.modifier.text );
}
});
</pre>

To try this out, Ubiq "insert email for " and then the first few letters of someone you email often.

=== Shorter Argument Declarations ===

Notice that we used a shortcut for declaring the arguments. In the long form, we would have had to say:

<pre>
arguments: [{role: "modifier",
nountype: noun_type_contact,
label: "contact"}]
</pre>

but if we don't care about specifying a label for the argument, we can get away with using a single object for "arguments", with the roles as the property names, and the nountypes as the property values:

<pre>
arguments: {modifier: noun_type_contact}
</pre>

If we had several arguments, and none of them needed labels, we could say:

<pre>
arguments: {object: noun_arb_text, modifier: noun_type_contact}
</pre>

and so on.

Aza writes:

<blockquote>
This one command sums up what I love about Ubiquity. In 8 lines of code, I can
fundamentally enhance the browser's functionality. Doing the same thing using
a normal Firefox extension methodology takes pages and pages of code—and the interface would take more thought still. Doing the same thing using a bookmarklet would require a server-side component (to get around cross-site Ajax request ban) as well as forcing the user to give up their email password.

Ubiquity increases the surface area of innovation for the browser many-fold, by making anyone who can write simple Javascript into an agent for bettering the browser and the open Web.
</blockquote>

== TinyURL: Network Calls and jQuery (and the URL noun type)==

Often while writing emails, I'll discover that I've pasted in a URL long enough to be used for unfortunate analogies. I'd like to be able to quickly turn that into a [http://en.wikipedia.org/wiki/Tinyurl TinyURL]—but the process of making a TinyURL involves lots of fiddly steps. Ubiquity to the rescue.

Because we include [http://en.wikipedia.org/wiki/jQuery jQuery] with Ubiquity, it is simple to perform Ajax calls as well as parse returning data. TinyUrl.com provides an easy to use RESTful API where you pass a URL and it returns its shortened form. We use that API in this command.

<pre>
CmdUtils.CreateCommand({
names: ["tinyurl"],
arguments: [{role: "object",
nountype: noun_type_url,
label: "url to shorten"}],
preview: "Replaces the selected URL with a TinyUrl.",
execute: function( arguments ) {
var baseUrl = "http://tinyurl.com/api-create.php";
var params = {url: arguments.object.text};
jQuery.get( baseUrl, params, function( tinyUrl ) {
CmdUtils.setSelection( tinyUrl );
})
}
})
</pre>

<code>noun_type_url</code> is a useful nountype because it defaults to the URL of the page that you are currently on. If that is in fact the URL that the user wants, then they don't have to type it or even select it.

jQuery is a powerful tool. With it, you can fairly effortlessly cherry-pick the data you need from RSS feeds, XML, and all sorts of other data formats. It also makes doing in-preview animations a breeze.

= Twitter: Putting It All Together =

We've now covered everything we need to cover in order to write a command that allows us to [http://en.wikipedia.org/wiki/Twitter Twitter] from Ubiquity. The code below is the actual source code of the Twitter command as it appears in Ubiquity 0.5.

Many thanks to [http://theunfocused.net/moz/ubiquity/verbs/ Blair McBride] for writing this command. The source code is a bit more intricate than anything we've seen so far, but it's built using exactly the same basic pieces -- and demonstrates nearly all of those pieces in action.

<pre>
const TWITTER_STATUS_MAXLEN = 140;

CmdUtils.CreateCommand({
names: ["twitter", "tweet", "share using twitter"],
arguments: [
{role: "object", label: 'status', nountype: noun_arb_text},
{role: "alias", nountype: noun_type_twitter_user}
],
icon: "http://twitter.com/favicon.ico",
description:
"Sets your Twitter status to a message of at most 160 characters.",
help: ("You'll need a <a href=\"http://twitter.com\">Twitter account</a>," +
" obviously. If you're not already logged in" +
" you'll be asked to log in."),
preview: function(previewBlock, args) {
var statusText = (args.object ? args.object.text : '');
var usernameText = "";
if (args.alias) {
usernameText = args.alias.text;
} else if (args.as) {
usernameText = args.as.text;
}
var previewTemplate = (
"<div class='twitter'>"+_("Updates your Twitter status ${username} to:")+" " +
"${status} " +
_("Characters remaining: ${chars}") +
""+_("tip: tweet @mozillaubiquity for help")+"</div>");
var truncateTemplate = (
""+_("The last ${truncate} characters will be truncated!")+"");
var previewData = {
status: <>{statusText}</>.toXMLString(),
username: usernameText && _("(For user ${usernameText})"),
chars: TWITTER_STATUS_MAXLEN - statusText.length
};

var previewHTML = CmdUtils.renderTemplate(
CmdUtils.renderTemplate(previewTemplate, previewData),
{usernameText:usernameText});

if (previewData.chars < 0) {
var truncateData = {
truncate: 0 - previewData.chars
};

previewHTML += CmdUtils.renderTemplate(truncateTemplate, truncateData);
}

previewBlock.innerHTML = previewHTML;
},
execute: function(args) {
var statusText = args.object.text;
if(statusText.length < 1) {
this._show(_("requires a status to be entered"));
return;
}

var updateUrl = "https://twitter.com/statuses/update.json";
var updateParams = {
source: "ubiquity",
status: statusText
//dont cut the input since sometimes, the user selects a big url,
//and the total lenght is more than 140, but tinyurl takes care of that
};
var me = this;

function sendMessage() {
jQuery.ajax({
type: "POST",
url: updateUrl,
data: updateParams,
dataType: "json",
error: function() {
me._show(_("error - status not updated"));
},
success: function() {
me._show(/^d /.test(statusText)
? _("direct message sent")
: _("status updated"));
},
username: login.username,
password: login.password
});
}

var login;
var alias = args.alias;
if (alias && alias.text && alias.data) {
login = alias.data;
sendMessage();
} else {
login = {username: null,
password: null};
if (alias && alias.text)
login.username = alias.text;
sendMessage();
}
},
_show: function(txt){
displayMessage({icon: this.icon, title: this.name, text: txt});
}
});
</pre>

= Switching Tabs =

The final command in this tutorial is for switching between tabs. The end goal is this: type a few keys to that matches the title of an open tab (in any window), hit return, and you've switched to that tab.

We'll write this command in two steps. The first step is creating a tab noun-type. The second step is using that noun-type to create the tab-switching command.

== Switching: Writing your own Noun-Types ==

A noun-type needs to only have two things: A <code>label</code> and a <code>suggest()</code> function. It can optionally also have a <code>default()</code> function.

The label is what shows up when the command prompts for input. Suggest returns a list of input objects, each one containing the name of a matching tab. We're using [http://developer.mozilla.org/en/docs/FUEL FUEL] to interact with the browser, which is where the "Application" variable comes from.

<pre>
var noun_type_tab = {
label: "tab name",

// Returns all tabs from all windows.
getTabs: function(){
var tabs = {};

for( var j=0; j < Application.windows.length; j++ ) {
var window = Application.windows[j];
for (var i = 0; i < window.tabs.length; i++) {
var tab = window.tabs[i];
tabs[tab.document.title] = tab;
}
}

return tabs;
},

suggest: function( text, html, callback ) {

var suggestions = [];
var tabs = noun_type_tab.getTabs();

//TODO: implement a better match algorithm
for ( var tabName in tabs ) {
if (tabName.match(text, "i"))
suggestions.push( CmdUtils.makeSugg(tabName) );
}

// Return a list of input objects, limited to at most five:
return suggestions.splice(0, 5);
}
}
</pre>

The suggest method of a noun type always gets passed both text and html. If the input is coming from a part of a web page that the user has selected, these
values can be different: they are both strings, but the html value contains markup tags while the text value does not. The Tab noun type only cares about the plain text of the tab name, so we ignore the value of html.

The callback argument is for use by nountypes that need to run asynchronously, i.e. becaus they need to do network calls to generate suggestions. The callback is a function; instead of returning a list of suggestions right away, an asynchronous noun type can call the callback with each suggestion it generates. More on this later; the tab noun type generates all its suggestions right away, so it just returns them instead of using the callback.

We use the convenience function <code>CmdUtils.makeSugg()</code> to generate an
input object of the type that the Ubiquity parser expects. The full signature of this function is
<pre>
CmdUtils.makeSugg( text, html, data );
</pre>
but html and data are optional and need be provided only if they differ from text.

If the text or html input is very long, <code>makeSugg()</code> generates a summary for us, and puts it in the <code>.summary</code> attribute of the input object.

We could have accomplished mostly the same thing without calling <code>makeSugg()</code> by returning a list of anonymous objects like these:
<pre>
{ text: tabName,
html: tabName,
data: null,
summary: tabName };
</pre>

The input objects that our <code>.suggest()</code> method generates are the same objects that will eventually get passed in to the <code>execute()</code> and <code>preview()</code> methods of any commands that use this noun type.

== Switching Tabs: The Command ==

Now that we are armed with the tab noun-type, it is easy to make the tab-switching command. Again, we use FUEL to focus the selected tab.

<pre>
CmdUtils.CreateCommand({
names: ["tab"],
arguments: {object: noun_type_tab},

execute: function( arguments ) {
var tabName = arguments.object.text;
var tabs = noun_type_tab.getTabs();
tabs[tabName]._window.focus();
tabs[tabName].focus();
},

preview: function( pblock, arguments ) {
var tabName = arguments.object.text;
if( tabName.length > 1 ){
var msg = "Changes to ${tab} tab.";
pblock.innerHTML = _(msg, {tab: tabName});
}
else
pblock.innerHTML = _("Switch to a tab by name.");
}
})
</pre>

= Development Hints =

You now know all you need to know to get started developing useful Ubiquity commands of your own.

Here are some miscellaneous tips that didn't fit elsewhere on this page, that may make development easier for you.

== The Source Code of Built-In Commands ==

Looking at the source code of built-in commands and built-in noun types can be a very useful aid to development. If you have the source checkout of Ubiquity (see [Labs/Ubiquity/Ubiquity_0.1_Development_Tutorial | the development tutorial] to find out how to get this), the source code can be found in the files:

ubiquity/standard-feeds/
ubiquity/builtin-feeds/en/builtincmds.js
ubiquity/modules/nountypes.js

If you don't have a checkout of the source code, you can view the latest version on the web here:

[http://hg.toolness.com/ubiquity-firefox/file/tip/ubiquity/standard-feeds/ standard-feeds]
[http://hg.toolness.com/ubiquity-firefox/file/tip/ubiquity/builtin-feeds/en/builtincmds.js builtincmds.js]
[http://hg.toolness.com/ubiquity-firefox/file/tip/ubiquity/modules/nountypes.js nountypes.js]

== Interacting with Other Extensions ==

http://img363.imageshack.us/img363/1906/picture7cm5.png

There isn't much to say here besides that it's easy. For example, here's a command (thanks to [http://foyrek.com/lyrics.html Abimanyu Raja] for writing this code) that finds the lyrics for a song. You can simply Ubiq something like "get lyrics for wild international" but the command will also interface with the FoxyTunes extension (if it is installed) and add the currently playing song to the suggestion list. Interfacing with other extensions, too, is easy because you can view the source code for every Firefox extension.

<pre>
var noun_type_song = {
label: "song name",
suggest: function( text, html ) {
var suggestions = [CmdUtils.makeSugg(text)];
if(window.foxytunesGetCurrentTrackTitle){
suggestions.push(CmdUtils.makeSugg(window.foxytunesGetCurrentTrackTitle()));
}
return suggestions;
}
}

CmdUtils.CreateCommand({
names: ["get lyrics"],
arguments: {modifier: noun_type_song},
preview: function(pblock, arguments) {

searchText = jQuery.trim(arguments.modifier.text);
if(searchText.length < 1) {
pblock.innerHTML = _("Searches for lyrics of the song");
return;
}

var previewTemplate = "Searches for the lyrics of ${query}";
pblock.innerHTML = _(previewTemplate, {query: searchText});

},
execute: function(arguments) {
var url = "http://www.google.com/search?q={QUERY}"
var query = arguments.object.text + _(" lyrics");
var urlString = url.replace("{QUERY}", query);
Utils.openUrlInBrowser(urlString);
}
});
</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",
label: "topic",
suggest: function freebase_topic_suggest(text, html, callback) {
return [
CmdUtils.makeSugg(text),
$.ajax({
url: "http://www.freebase.com/api/service/search",
dataType: "json",
data: {prefix: text, limit: 5},
success: function suggestTopics(response) {
if (response.status === "200 OK")
callback([CmdUtils.makeSugg(result.name, result.name, result)
for each (result in response.result)]);
},
})];
}
};

CmdUtils.CreateCommand({
names: ["lookup on freebase"],
arguments: {object: noun_type_freebase_topic},
preview: function preview(pblock, args) {
pblock.innerHTML = _(("Go to the Freebase topic page for " +
"{if text}${text}{else}any topic{/if}."),
args.object);
},
execute: function goToFreebase({object: {text, data}}) {
Utils.openUrlInBrowser(
text
? (data
? "http://www.freebase.com/view" + data.id
: ("http://www.freebase.com/search?query=" +
encodeURIComponent(text)))
: "http://www.freebase.com/");
}
});
</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 ==

Commands aren't the only thing you can put in a command feed. You can also include functions you want to be run automatically at page-load time and at Firefox startup time.

In order to run some code on page load, you simply have to prefix your function with <code>pageLoad_</code>. For example, if you want to say "Hi" every time a page is loaded, your code would look like this:

<pre>
function pageLoad_hi(){
displayMessage("hi");
}
</pre>

If you modify the function and want to see the changes, remember to first invoke Ubiquity. Although your function like above, might not be a Ubiquity command, this is necessary to refresh the cached code.

Similarly, if you want to run some code everytime Firefox starts up, you just have to prefix the function with <code>startup_</code> .

The awesome thing about these functions is the ability to develop whole Firefox extensions (that require minimal UI) as Ubiquity plugins in lesser lines of code. You don't need to worry about chrome.manifest or install.rdf. Another added benefit is that you never have to restart your Firefox during development unless of course, you are running code on Firefox startup.

<center>http://img388.imageshack.us/img388/3086/picture5eo9.png</center>

Here's the code for [http://foyrek.com/keyscape.js Keyscape] which is a Ubiquity command that makes use of <code>pageLoad</code> and <code>startup</code> to recreate the functionality of the [https://addons.mozilla.org/en-US/firefox/addon/339 Search Keys extension] by Jesse Ruderman. In line with Ubiquity's aim to let you do things quicker using your keyboard, this command lets you go to search results on Google by just pressing a number. It'll add hints to show the number of each link.

<pre>
//A lot of this code is borrowed from the Search Keys extension
//Many thanks to Jeese Ruderman

function startup_keyscape() {
window.addEventListener("keydown", keyscape_down, true);
}

function pageLoad_keyscape(doc){

var uri = Utils.url(doc.documentURI);
//If we are on about: or chrome://, just return
if(uri.scheme != "http")
return;

//Check if the page we are on is google
if( keyscape_isGoogle(uri) ){

for(var num=1; num<=10; num++){

var link = jQuery(doc.body).find('a.l')[num-1];

if( link ){

var hint = doc.createElementNS("http://www.w3.org/1999/xhtml", "span");
hint.style.color = "blue";
hint.style.background = "white";
hint.style.padding = "1px 2px 1px 2px";
hint.style.marginLeft = ".5em";
hint.appendChild(doc.createTextNode(num == 10 ? 0 : num));
link.parentNode.insertBefore(hint, link.nextSibling);
}
}
}
}

function keyscape_isGoogle(uri){
return uri.host.indexOf("google") != -1
&& (uri.path.substr(0,8) == "/search?"
|| uri.path.substr(0,8) == "/custom?");
}

function keyscape_down(event){

var doc = Application.activeWindow.activeTab.document;
var uri = Utils.url(doc.documentURI);

if( keyscape_isGoogle(uri) ){

var key = parseInt(event.keyCode || event.charCode);
var num;

if(48 <= key && key <= 57) //number keys
num = key - 48;
else if(96 <= key && key <= 105) //numeric keypad with numlock on
num = key - 96;
else
return;

//Don't do anything if we are in a textbox
//or some other related elements
var elt = window.document.commandDispatcher.focusedElement;

if (elt) {
var ln = new String(elt.localName).toLowerCase();
if (ln == "input" || ln == "textarea" || ln == "select" || ln == "isindex")
return;
}

//Get the link url from the search results page
var url_dest = jQuery(doc.body).find('a.l').eq(num-1).attr('href');

if(event.altKey){
//Open in new tab
Application.activeWindow.open(Utils.url(url_dest));
}else{
//Open in same tab
doc.location.href = url_dest;
}
}
}
</pre>

If Ubiquity does indeed become ubiquitous, a lot of extensions can be re-written as Ubiquity commands. This is much nicer for the end-user, as well, because the Ubiquity command installation process is a lot easier.

In the future, Ubiquity is also likely to have the ability to convert your Ubiquity commands into proper Firefox extensions. Look [http://labs.toolness.com/trac/ticket/3 here] to check on the progress of this functionality.

== Firebug ==

Ubiquity automatically enables Chrome Errors and Warnings on startup so that errors in your code appear in the Firebug console. Just use <tt>CmdUtils.log()</tt> rather than <tt>console.log()</tt>.

= Where To Go From Here =

Take a look at Ubiquity's reference documentation for the <tt>[https://ubiquity.mozilla.com/hg/ubiquity-firefox/raw-file/tip/ubiquity/index.html#modules/utils.js Utils]</tt> and <tt>[https://ubiquity.mozilla.com/hg/ubiquity-firefox/raw-file/tip/ubiquity/index.html#modules/cmdutils.js CmdUtils]</tt> namespaces.

If you have any questions or comments, feel free to join us on IRC at <tt>#ubiquity</tt> on <tt>irc.mozilla.org</tt>, as well as the [http://groups.google.com/group/ubiquity-firefox Ubiquity Google Group].

= Conclusion =

To reiterate a point I made before: Ubiquity increases the surface area of innovation for the browser many-fold, by making anyone who can write simple Javascript into an agent for bettering the browser and the open Web. You are one of those agents.

Now, go forth and create.

Labs/Ubiquity/Roadmap

2009-06-25T18:37:31Z

Endolith: /* Ubiquity 0.7: The Web-of-Trust Security Model */

= The Purpose of the Ubiquity experiment =

Ubiquity is really two experiments in one.

== Pseudo-Natural Language ==

The first is an attempt to build a practical, learnable, efficient user-interface using pseudo-natural-language parsing. Parsing and understanding the semantics of natural language in the general case is extremely difficult, maybe even impossible, and IMHO best left to academic A.I. researchers. But maybe it's possible to make an interface which is similar enough to a limited subset of natural language that the user's linguistic instincts will make it easier to learn and use. That's what we're exploring.

== Verbing the web ==

The second experiment has to do with the "verbification" of the web. Traditionally the web has been made of "locations", i.e. pages, that you "go" to using a browser. But as more and more of those locations become interactive and offer useful services, maybe it makes more sense to treat those services as things you can "pick up" and "take with you" to use elsewhere, instead of treating them as locations. These chunks of code become '''commands''', the "verbs" of the web, as opposed to the "nouns" that are content-oriented websites.

=== Security plus generativity ===

To make this work, we need to solve the problems of how discrete chunks of code can be written and shared (as easily as web pages can) in a way that offers protection from malicious code without sacrificing generativity. Security and generativity are often at odds (c.f. "The Future of the Internet and How to Stop It" by Jonathan Zittrain) so to resolve the paradox we explore new and untested security models such as the proposed "web of trust". If we can find something that works, it could be applied to many other projects as well.

== The benefit for the user is efficiency ==

Natural language and generativity are of interest mainly to developers. For the end-user, the benefit of installing Ubiquity is that it gives a faster way to do common web tasks. With the appropriate command installed, you can accomplish something by simply selecting text on a page and invoking a command, as opposed to copying text, going to a different website, pasting it into a form, etc. For all of the complexity going on under the surface, this efficiency boost is the reason people use Ubiquity. To drive more uptake, we should look for more opportunities to write commands that streamline repetitive tasks.

Although there are a nearly infinite number of cool new features that can be proposed for Ubiquity, we should try to stay focused on these three areas: natural language interface, verbifying the web, and increasing the efficiency of the user's internet tasks. Things that aren't closely related to one of these should be considered out-of-scope for the project.

= Planned Upcoming Releases =

== Ubiquity 0.5: The New Parser ==

The big news here is the new parser, which supports internationalization. We took everything we learned from writing the original parser and used it to create a much more robust and expandable basis for future development of multiple-language pseudo-natural-language input.

Second biggest news is the new interactive tutorial. User testing showed we had a desperate need for a better first-run experience, so we created a walkthrough that takes new users by the hand and teaches them the basic concepts along with a handful of the most useful commands.

Release date: June 22 (or 23rd if we're following the tuesday-publicity theory), timed to coincide with release of Firefox 3.5. (Update: We released 0.5pre, a still-buggy preview edition, on June 22. We will release 0.5 for real, with no new features but lots of bug fixes, on June 30.)

Must support both Firefox 3.0 and 3.5.

Major new features:

* Parser version 2, which supports internationalization
* More consistent naming of standard feed commands, with no more hyphens
* New interactive tutorial
* better organized web/help content
* improved asynchronous noun suggestions
* Supports multiple languages: English, Japanese, and Danish at launch; more later.

=== Community building after 0.5: ===

* New command developer documentation
* Series of videos promoting new features that 0.5 offers to command developers and encouraging command developers to update their feeds to the new format.
* Educate command developers on locked-down feeds, encourage them to use locked-down feeds whenever possible and standard feeds only when absolutely neccessary.
* Human interface guidelines for command developers, to encourage consistency of interface between commands.
* Outreach to localization community, to solicit the help of localizers to get Ubiquity working in more languages.

== Server-Side Improvements ==

There are three server side components to Ubiquity:

# The command search engine ("The Herd")
# The bug-reporting system
# The developer support infrastructure, e.g. Hg and Trac, that run on ubiquity.mozilla.com.

All three of these have been experiencing major availability and/or performance problems. The lack of usable uptime is really starting to hold us back. As soon as 0.5 is released, we need to focus on making all three of these server-side components stable and reliable enough to support our plans for growth of the user and developer communities.

== Ubiquity 0.5.1 ==

Beginning of Q3, 2009

A few features that didn't make it into 0.5, along with fixes for whatever the biggest bugs are that we discover after 0.5. Notable features (which are almost done, but didn't get in to 0.5 before feature freeze) are:

* Provider plugin arguments
* Suggestion memory in parser 2

== Ubiquity 0.6: Push for more End-User Benefits ==

Mid Q3, 2009

After the deep infrastructure work of 0.5, we need to focus on turning the new power of the platform into tangible benefits for the end-user. That means improving the implementation of the standard feed commands for better stability and functionality, plus expanding the range of commands available, and attempting to expand the size of our user base.

Around this time, the Test Pilot project will have produced a usable set of policy guidelines for collecting data without compromising user privacy. These guidelines will be implemented in 0.6 so that we can start collecting usage data that we can use to scientifically improve the usability of Ubiquity from here on.

* Instrument Ubiquity for data collection according to Test Pilot standards.
* Improvements to standard feed commands and their documentation; more new commands.
* New and better default skin; Better graphics for user interface.
* Localization gets wider and deeper: More locales supported; make nountypes localizable; look into distributing localization so that a command feed can be localized independently from its creator.
* Suggestion memory improved to cover noun suggestions
* Experiment with doing noun recognition in the cloud

=== Community Building after 0.6 ===

We should come up with metrics to estimate the size of our user base, and set targets for the number of users we would like to have. With the higher quality of the standard commands that will be emphasized in 0.6, it will be easier to reach new users.

Increasing our user base will increase our command developer base as well as our command subscriber base, and allow us to make more realistic explorations of the scaling effects that start to affect security and trust when the network grows past critical mass. For instance, I am not aware of anyone having yet attempted to write a malicious Ubiquity command. I'm sure this is mostly because the user base is too small to be worth targeting. As the user base grows, it becomes inevitable that someone will attempt to attack our users using a malicious command. Thus, growing the community is an opportunity to test out the web-of-trust security model.

We should take a hint from the "Extend Firefox" contests and run a contest to write the best Ubiquity command -- the most useful, most innovative, and best implemented commands that conform to our security and human interface guidelines will be rewarded with publicity and swag.

Separately from any contests, we should also have a spot on the Herd / command-search front page for "Featured Commands". This can be a short, rotating list of commands that we have reviewed for security and usability and found highly useful and worthy of recommendation.

The Herd ought to offer a feature where users can give thumbs-up or thumbs-down to commands, and then view commands ranked by number of thumbs.

Good, popular third-party commands can also be considered for inclusion into future versions of the standard feeds. (But inclusion in standard feeds will never be offered as a prize for any contest; that goes against Mozilla's policies.)

== Ubiquity 0.6.1 ==

A few features that didn't make it into 0.6, along with fixes for whatever the biggest bugs are that we discover after 0.6.

== Ubiquity 0.7: The Web-of-Trust Security Model ==

Late Q3, 2009

Because of the growing user population, this release will need to focus on security. With the growing user population, sooner or later someone will start writing malicious Ubiquity commands. We will try to combat this by using the power of networked users for good instead of evil. Our longstanding plans for a "[[Labs/Ubiquity/TrustNetwork|web of trust]]" security model will require several improvements to the infrastructure of command subscription. First, Ubiquity will need to know who your friends are, so that it can see what commands your friends have recommended subscribing to, and what commands they've recommended avoiding.

Second, commands will no longer be able to have direct access to third-party servers through XHRs, or to the XPCOM components in the Mozilla platform. Instead, they will have to make API calls through a security layer. This security layer will identify exactly what permissions a command is requesting, so that when a user subscribes to it, Ubiquity can tell that user in a plain, human-readable way exactly what is being requested: "This command wants permission to write to your filesystem", for instance, or "This command wants to contact the site www.sendmealotofspam.com."

The security layer will make it so that users know what questions are being asked of them by a command install (which will be a big step up from the scary red screen with javascript source code); the web of trust, with recommendations from your friends, will help users decide sensible answers to these questions.

* The web-of trust: Ubiquity becomes aware of your friends and includes a system for giving feedback on commands.
* The security layer: commands get access to third-party XHRs, XPCOM components, etc. only through security-aware proxy object.
* User-defined command aliases
* More locales supported, more and better built-in commands

== Ubiquity 0.7.1 ==

A few features that didn't make it into 0.7, along with fixes for whatever the biggest bugs are that we discover after 0.7.

== Ubiquity 0.8: User-interface experimentation ==

Q4, 2009

This release will focus on opening up the Ubiquity user-interface to more experimentation.

By rebuilding Ubiquity on top of Jetpack, so that Ubiquity and Jetpack share a common runtime, we will not only make debugging of Ubiquity much easier; we will also be able to expose the library of installed Ubiquity commands through a Jetpack API, so that others can write new interfaces to take advantage of these commands.

* Ubiquity built to run on Jetpack
* Commands exposed through Jetpack
* Experimentation with different UI, such as always-on input field, or mouse-based UI.
* Command chaining, AKA pipes between commands
* Solve whatever are the most pressing usability problems discovered through Test Pilot data collection
* More locales supported, more and better built-in commands

== Ubiquity 1.0: A product ready for mainstream use ==

Q1, 2010

This release will focus on polish. It will not have any major new features beyond 0.8, but before a release is worthy of being called 1.0 it must be much more solid than any release we have made thus far. The built-in commands and nountypes, the security model, the user interface, and the parser must all be clean and reliable, and all remaining major bugs must be fixed.

== Beyond 1.0: ==

Experiments in these areas can be done beyond 1.0 if there are sufficient developer resources, but they are outside the core project goals.

* Weave integration
* Thunderbird integration
* Bespin integration

Talk:Labs/Ubiquity/TrustNetwork

2009-06-08T14:48:20Z

Endolith: Created page with 'Is this for trusting the reliability/functionality of the script, or the malicious intentions of the author? Does it make sense to have metrics for both reliability/quality and ...'

Is this for trusting the reliability/functionality of the script, or the malicious intentions of the author? Does it make sense to have metrics for both reliability/quality and lack of maliciousness?

Talk:Labs/Ubiquity/The Great Renaming

2009-05-30T04:42:58Z

Endolith: Created page with 'I sure hope we don't actually have to type out "search for something with google" in order to search google. I want to type "go[Tab]something[Enter]" like I currently do.'

I sure hope we don't actually have to type out "search for something with google" in order to search google. I want to type "go[Tab]something[Enter]" like I currently do.

Labs/Ubiquity/Commands In The Wild

2009-03-01T16:57:14Z

Endolith: /* extensions of the core commands */

Back to [[Labs/Ubiquity]].

'''LEGAL NOTICE: Mozilla is providing links to these third-party Ubiquity commands as a courtesy, and makes no representations regarding the commands or any information related there to. Any questions, complaints or claims regarding the commands must be directed to the appropriate developer or software vendor.'''

''' Commands in the Wild '''

Please note that the main way we'd like commands to be distributed and shared in the future is via [http://ubiquity.mozilla.com/herd/ The Ubiquity Herd]. Right now there isn't any social functionality on the Herd, though, which is why we're using this page to allow for user-contributed commentary and discussion. At some point in the near future we'll be adding this kind of functionality to the Herd and will migrate the content on this page there.

''' There Be Dragons Here '''

Pioneering can be crazy fun, but also a bit dangerous. The commands referenced here have not been reviewed by Mozilla. They may contain malicious code, so use them only at your own risk. Until Ubiquity becomes more mature, we recommend only adding commands that come from people you trust, or if you've read the code and know that they are safe.

Beware that even if you review the code before subscribing, the code may be subject to change from the publisher, and your copy will automatically update on firefox restart. This problem will be remedied in later versions of Ubiquity.

=Country specific Commands=
==AT==
*[http://gist.github.com/25096 gist.github.com/25096]: ÖBB Railway time table search

==BR==
*[http://minhavidaorientadaaobjetos.blogspot.com/2009/01/buscap-ubiquity-compare-produtos.html Buscape Command]: Compare products quickly in Buscapé
*[http://minhavidaorientadaaobjetos.blogspot.com/2009/01/americanascom-para-ubiquity-facilitando.html Americanas.com Command]: Search for products at Americanas.com
*[http://gist.github.com/65907 lyrics a.k.a. letras]: Search for lyrics at letras.mus.br
*[http://gist.github.com/65903 whois-br]: Whois search for brazilian hosts (registro.br)

==CA==
* [http://mricon.com/ubi/ Montréal Transit]: Look up STM bus and AMT train schedules

==CH==
*[http://www.frigi.ch/index.php/ubiquity '''SBB CFF FFS''']: Swiss Railway time table search for [http://www.sbb.ch SBB CFF FFS]. You can find some screen shot [http://frigi.ch/index.php/ubiquity/screenshot here].
*[http://www.frigi.ch/index.php/ubiquity '''Tel.Search.ch''']: Swiss Phone Book search from [http://tel.search.ch tel.search.ch]
*[http://www.frigi.ch/index.php/ubiquity '''Swiss Teletext''']: Swiss Teletext page browser. You can find some screen shot [http://frigi.ch/index.php/ubiquity/screenshot here].
*[http://www.frigi.ch/index.php/ubiquity '''Rete 3''']: visualizza le ultime canzoni in onda su [http://rete3.rtsi.ch/ Rete 3]. Puoi trovare degli screen shot [http://frigi.ch/index.php/ubiquity/screenshot qui].
*[http://www.frigi.ch/index.php/ubiquity '''Meteo-local''']: show the calculated meteo for a location. Information from [http://www.meteosvizzera.admin.ch Federal Office of Meteorology and Climatology]. You can find some screen shot [http://frigi.ch/index.php/ubiquity/screenshot here].
*[http://www.frigi.ch/index.php/ubiquity '''Meteo-radar''']: show the last radar image from [http://www.meteosvizzera.admin.ch Federal Office of Meteorology and Climatology]. You can find some screen shot [http://frigi.ch/index.php/ubiquity/screenshot here].
*[http://www.frigi.ch/index.php/ubiquity '''Slf''']: show the latest avalanche bulletin from [http://www.slf.ch Institute for Snow and Avalanche Research SLF]. You can find some screen shot [http://frigi.ch/index.php/ubiquity/screenshot here].
*[http://www.frigi.ch/index.php/ubiquity '''Swisswebcams''']: show a random webcam image from the site [http://www.swisswebcams.ch Swisswebcams]. You can find some screen shot [http://frigi.ch/index.php/ubiquity/screenshot here].

==CN==
* [http://gist.github.com/51784 jiwai]: Command for posting to jiwai.de, a microblogging service in China. For information [http://damienh.org/2009/01/25/ubiquity%e5%8f%bd%e6%ad%aa%e5%91%bd%e4%bb%a4%e5%8a%a0%e5%bc%ba%e7%89%88/ check here].
*[http://ubidu.sourceforge.net/ ubidu]: Search Baidu.com, the No.1 search engine in China.
* [http://17th.name/wp-content/uploads/2008/09/fanfou.html Fanfou Command] - post to Fanfou.com (??)
* [http://www.utblog.com/tools/ubiquity/yodao-dict.htm Youdao or Yodao Dict Search Command] - Translate english to chinese and vice versa through dict.yodao.com service.
* [http://gist.github.com/25703 Translate word with dict.cn ] - Translate word with dict.cn, both English to Chinese or Chinese to English.
* [http://gist.github.com/31480 Search in douban] - Search douban items for movie/music/book/generic. With live preview of search results. See a screen shot [http://desktable.blogbus.com/logs/32090698.html here].
* [http://gist.github.com/49305 Search in Jukuu] - Retrive a word’s pronounce and example sentences from www.jukuu.com, supports English-Chinese and Chinese-English translations. See a screen shot [http://sealence.x10hosting.com/wordpress/?p=61 here].
* [http://gist.github.com/49422 Recite word everyday on iciba.com] - Retrieving 5 words from the every day recite word lists from www.iciba.com. None input for today’s word, input date string like “2009-1-19″ to retrieve previous day. See a screen shot [http://sealence.x10hosting.com/wordpress/?p=63 here].

==CZ==
* [http://ubiquity.wegguy.cz/idos/ idos]: Search Czech public transport connections

==DE==
* [http://daniel.lomm.es/projects/ubiquity-vrr vrr]: Search for timetables for trains, trams and buses in the Rhein-Ruhr region.

==DK==
* [http://u.ter.dk/mitkbh mitkbh]: search locations and reviews in Copenhagen
* [http://u.ter.dk/tv tv]: Danish tv guide

==FI==
*[http://www.juhamakkonen.com/ubiquity/commands/finland/horeca/eat/ eat]: twelve city specific (e.g. eat-helsinki) finnish restaurant searches from eat.fi
*[http://www.juhamakkonen.com/ubiquity/commands/finland/horeca/vapaa-aikavirasto/vapaa-aikavirasto.htm vapaa-aikavirasto]: fi-nationwide restaurant/bar search from vapaa-aikavirasto.com
*[http://www.juhamakkonen.com/ubiquity/commands/finland/horeca/viini/viini.htm viini]: wine review search from viiniweb.net
*[http://www.juhamakkonen.com/ubiquity/commands/finland/jalkapallo/suomencup.htm suomencup]: search material related to finnish cup football from suomencup.net wiki
*[http://www.juhamakkonen.com/ubiquity/commands/finland/jalkapallo/veikkausliiga.htm veikkausliiga]: rss news feeds from veikkausliiga football teams

==KR==
*[http://dotnet.pe.kr/ubiquity/me2day_ubiquity.html me2day] - Enables ubiquity to send posts to me2DAY(http://me2day.net) a Korean microblogging site. setme2daykey command sets the username and userkey that is required for posting.
*[http://sites.google.com/site/coosgadgets/east-asian-language-romanization korean] - Romanization of Korean language (Hangul)

==IT==
*[http://gstefanoni.netsons.org/ubiquity/treni-from.html treni-from] - Searches for the next available train on the selected route on the Trenitalia network
==JA==
*[http://gist.github.com/8346 eijiro] - Japanese <=> English
*[http://sites.google.com/site/coosgadgets/east-asian-language-romanization japanese] - Japanese <=> English with Romaji

==NO==
* [http://skogvoldconsulting.no/ubiquity/1881/ 1881.no]: Norwegian phone book online.
* [http://skogvoldconsulting.no/ubiquity/posten/ Sporing på posten.no]: Norwegian mail tracking

==NL==
* [http://gist.github.com/35909 vandale]: For looking up words in the free online version of the leading Dutch dictionary: Van Dale.
* [http://gist.github.com/59840 hyves-zoek]: For looking for people on the social networking site Hyves.

==NZ==
* [http://tommo39.com/trademe.html trademe]: Searches trademe.co.nz for whatever item you are looking for.

==PT==
*[http://gist.github.com/19991 priberam] - Looks up a word in the Priberam Portuguese dictionary [http://priberam.pt/dlpo/ Priberam] (Homepage [http://sites.google.com/site/edgargoncalves/work/software/ubiquity here])

==RO==
* [http://avatars.postiton.net/ avatars] - Search Avatars in English and add to your emails [http://avatars.postiton.net/ avatars.postiton.net]
* [http://avatare.afisatepe.net/ avatar] - Search Avatar in Romanian and add to your emails [http://avatare.afisatepe.net/ avatare.afisatepe.net]

==RS==
* [http://gist.github.com/11398 sr-map] - Search maps of major Serbian cities using [http://mape.b92.net mape.b92.net]

==SE==
* [http://raymond.bergmark.googlepages.com/hitta.htm Hitta.se]: Swedish phone book online.

==TR==
* [http://burakcelebi.googlepages.com/ubiquity-eksisozluk.html EksiSozluk Commands] - Commands for http://sozluk.sourtimes.org

* [http://www.deniz.web.tr/ubiquity cevir] - Turkish - English translation command.

* [http://www.azizce.com/wp-content/ubiquity/tdk.html Turk Dil Kurumu 'nda Arama] - Fast search command for [http://www.tdk.gov.tr/ Official TDK Website].

* [http://www.verisux.com/ubi-seslisozluk.html seslisozluk] - Integration with seslisozluk.com for quick enlish/german/turkish translations

==TW==
*[http://linlichangjen.googlepages.com/ubiquity ydic]: Translate English word to Tratitional Chinese

*[http://fortelin.net78.net/ubiquity/2r 2r, another extended version of twitter command]: with url shortened and edit dialogue function, enjoy it ^^

*[http://fortelin.net78.net/ubiquity/soso soso Command for Ubiquity]:another extended, tabbed version of the google command.

==UK==
*[http://mskadu.googlepages.com/ubiquityscripts yell]: Search Yell.com for businesses in the UK

*[http://www.red-eyed.org.uk/ubiquity.html amazonuk]: Search Amazon.co.uk for any item. A version of amazon-search-all customised for the UK version of the Amazon site.

*[http://tevp.net/projects/ubiquity/ journey]: Searches the TfL journeyplanner for a destination. Currently has hardcoded start point and walking speed.

*[http://www.socialanimal.com/pubs/ubiquity.htm pubfinder]: Looks for pubs in the specified place or postcode.

*[http://choffee.co.uk/Ubiquity trainuk]: Simple interface to search for train times in the UK.

*[http://github.com/elson/ubiquity-bbc-iplayer/wikis/command-feed BBC iPlayer]: Watch or listen to recent programmes on BBC iPlayer

==Multiple Countries==
*[http://garyhodgson.com/ubiquity/amazon.html amazon-locale]: Perform a 'Blended' search on Amazon Germany, UK, USA, Japan or Canada.

= Directory Search =
*[http://mskadu.googlepages.com/ubiquityscripts yell]: Search Yell.com for businesses in the UK
* [http://gist.github.com/65093 Cambridge English Advanced Learner's Dictionary Definition Lookup with preview ]: English (Cambridge). See a screen shot [http://sealence.x10hosting.com/wordpress/?p=66 here].

= Web Search =

* OneLook Reverse Lookup - http://icecreamfactory.freehostia.com/ubiquity/reverse-lookup.html

== Site-specific Search ==

* Agentarius User-Agent-Info - http://www.agentarius.net
* All Music Guide - http://a9ej32w.googlepages.com/allmusic
* Allrecipes.com - http://www.javajill.com/ubiquity/recipe.html
* AltLaw - http://www.keysquaremedia.com/
* Archive.org - http://ubiquity.washing-up.co.uk/archive.html
* Aspectweb - http://annoq.aspectweb.org/uq.html
* Avatars - http://avatars.postiton.net
* Babylon - http://www.geocities.com/ubiquities1
* Beat Goes On - http://***.pixelcore.ca/bgo_ubiquity/ (Used CDs DVDs & Video Games)
* BibleGateway - http://www.zenorsoft.com/ubiquity.php (Looks up Bible Verses)
* BoardGameGeek - http://www.hunterandlori.com/ubiquity/
* Brainstorm #9 - http://www.brainstorm9.com.br
* Cambridge - http://sealence.x10hosting.com/wordpress/?p=66
* CharlieRose.com - http://erikvold.com/tools/ubiquity/charlierose/charlierose.cfm
* Common Lisp Hyperspec - http://common-lisp.net/project/lifp/ubiquity/clhs.htm
* Coxa Creme (Brazil) - http://gist.github.com/10795
* craigslist - http://labs.vunite.com/vubiqs/verbs.php
* Deal Extreme - http://skogvoldconsulting.no/ubiquity/dealextreme
* Demonoid - http://www.thecompgeek.info/ubiquity/demonoid.html
* Deezer - http://jacquin.pascal.free.fr/ubiquity/ (Search&listen music online)
* Digg - http://captspify.is-a-geek.com/scripts/Home/Ubiquity (Searches Digg)
* dinehere.ca - http://dairong.googlepages.com/ubiquity.html
* Discogs - http://a9ej32w.googlepages.com/discogs
* eBay (geodetects your location and searches accordingly) - http://mskadu.googlepages.com/ebaysearch2
* EmacsWiki - http://ubiquity.chrononaut.net/emacswiki.html
* eMule - http://gist.github.com/16364
* Fileshunt - http://avid.me/ubi/fileshunt.html
* Filmweb.pl - http://gist.github.com/19735
* Firefox add-ons - http://www.rakudave.ch/?q=node/20
* Freebase - http://hamstersoup.com/freebase/ubiquity/
* Futureshop.ca - http://dairong.googlepages.com/ubiquity.html
* GitHub - http://ubiquity.chrononaut.net/github.html
* Google Finance - http://www.hoffstein.net/ubiquity/stock-quote.html
* Google Image (with preview) - http://gist.github.com/10704
* Google Image Search (preview, links, embedding) - http://www.jimmy2k.it/getimagescommand
* Google Trends (with preview) - http://gist.github.com/10706
* Google Scholar - http://static.isnotworking.com/scholar-search.html
* Google Books - http://www.radiantweb.net/ubiquity/
* Hoogle - http://www.randomhacks.net/git/ubiquity/hoogle/
* Hulu - http://gist.github.com/51468
* Imdb (with preview) - http://gist.github.com/59109
* Iciba.com(irecite) - http://sealence.x10hosting.com/wordpress/?p=63
* Jaiku - http://jonasnockert.com/2008/08/ubiquity-code-for-jaiku-search/
* Jiwa - http://jacquin.pascal.free.fr/ubiquity/ (Search&listen music online)
* Jukuu - http://sealence.x10hosting.com/wordpress/?p=61
* Kewego.fr - http://ht.ubiquity.googlepages.com/ubiquity-kewego.html
* Last.FM - http://static.isnotworking.com/lastfm-search.html
* Last.fm "advanced" - http://www.satf.se/page/ubiquity-advanced-last-fm-search
* Last.fm Artist Lookup - http://gist.github.com/50505
* leo.org dictionary - http://www.geocities.com/ubiquities1
* LibraryThing - http://www.quicksilverillness.com/ubiquity/librarything_searches.html
*Lifehacker.com search - http://gist.github.com/47455
* Lifehacking tagcloud search - http://lifehacking.nl/web20/ubiquity-verbindt-het-web-weer/ (Dutch only!)
* Live - http://www.powerset.com
* LolCats latest image - http://members.optusnet.com.au/~crazyjane13/lolcats.html
* LoveFilm - http://dave.org.uk/ubiquity/lovefilm.html
* metacritic.com - http://dairong.googlepages.com/ubiquity.html
* metal-archives.com - http://people.iola.dk/arj/2008/09/02/adding-some-metal-to-ubiquity/
* Mozilla Add-ons - http://projects.fligtar.com/ubiquity/add-on.php
* Mozilla Add-ons (by folarb) - http://gist.github.com/34678
* MusicBrainz - http://a9ej32w.googlepages.com/musicbrainz
* NCIX.com - http://dairong.googlepages.com/ubiquity.html
* netflix - http://radria.sqlfusion.com/ubiquity.php
* NewAdvent.org - http://gist.github.com/54249
* Newegg - http://test.fathomthat.org/ubiquity/newegg.html
* Newzbin - http://www.quicksilverillness.com/newzbin_search.html
* Orkut User Search - http://avid.me/ubi/orkut.html
* PubMed - http://code.google.com/p/tl-ubiquity-commands/source/browse/trunk/pubmed/search-pubmed.js
* Powerset - http://www.powerset.com
* Questionable Content MediaFire Thread - http://bluesuncorp.co.uk/bbq/mfsearch.htm
* Reddit - http://captspify.is-a-geek.com/scripts/Home/Ubiquity/
* RetailMeNot - http://www.quicksilverillness.com/ubiquity/retailmenot.html
* REVU - http://revu.ubuntuwire.com/ubiquity-plugin.py
* Ruhr-University Bochum OPAC - http://bibliolabs.ub.rub.de/ubiquity
* Shoutcast Search
* SearchMe - http://www.thecompgeek.info/ubiquity/searchme.html
* Skweezer - http://unplugd.com/enblogd
* Smelly Cat - http://www.smellycat.com.br
* Snow Report - http://www.freewebs.com/wwprograms/ubiquity.htm
* Social Actions - http://www.crankreport.org/junkdrawer/js/ubiq_social_actions_page.html
* stock.xchng / sxc.hu - http://www.juhamakkonen.com/ubiquity/commands/images/sxc.hu/sxc.htm
* Subscene - http://avid.me/ubi/subscene.html
* suggest-experts - [http://gist.github.com/15544 subscribe], [http://code.google.com/p/tl-ubiquity-commands/source/browse/trunk/pubmed/suggest-experts.js project at google code]
* Thesaurus - Used to search thesaurus.reference.com http://www.zacharyspencer.com/2008/09/my-first-ubiquity-command/
* Thottbot - http://topthis.tv/ubiquity/
* Tonight.eu - http://www.tonight.eu/ubiquity/
* Ubuntu brainstorm - http://www.rakudave.ch/?q=node/21
* Ultimate Guitar (supports grabbing FoxyTunes track info) - http://propus.lunarpages.com/~thefo2/ug.htm
* Update or Die (Brazil) - http://gist.github.com/10788
* Urban Dictionary - http://common-lisp.net/project/lifp/ubiquity/urban-dictionary.htm (now with preview!)
* Urban Dictionary, alternate version - http://gist.github.com/47363
* Vimeo - http://gist.github.com/72179
* Viu Isso? (Brazil) - http://gist.github.com/10791
* YTMND.com - http://gist.github.com/21802
* Wapedia Search - http://unplugd.com/enblogd
* The Wayback Machine - http://www.yardensachs.com/ubiquity/
* Webmd search - http://predator101.webng.com/ubiquity/webmd.html
* Websource.It - http://www.briandgoad.com/blog/ubiquity-commands/websourceit/
* What.CD - http://corevette.googlepages.com/whatcdubiquity.html
* WhitePages.com - http://charlesconnell.com/ubiquity.html
* Wikiquote - http://www.geocities.com/ubiquities1
* Wordnik – http://jonasnockert.com/2008/10/ubiquity-wordnik/
* WorldCat - http://bibliolabs.ub.rub.de/ubiquity
* WTFCalls.com - http://wtfcalls.com/search/
* WTSBooks.com - http://www.nerdlets.org/2009/01/14/ubiquity-command-for-the-westminster-bookstore/
* xkcd - http://ieng6.ucsd.edu/~rjc002/
*[http://mskadu.googlepages.com/ubiquityscripts yell]: Search Yell.com for businesses in the UK
* Yahoo! Finance http://www.matthias-schuetz.eu/yfin-ubiquity.html Quickly review stock quotes and charts
* Yahoo! Finance http://proplus.aptanacloud.com/ubiquity/yahoo-graph.html Tiny Year To Date ticker chart
* dict.youdao.com / dict.yodao.com - http://www.utblog.com/tools/ubiquity/yodao-dict.htm
* Zappos - http://topthis.tv/ubiquity/
* Zipzoomfly - http://test.fathomthat.org/ubiquity/zipzoomfly.html
* Zootool - http://zootool.com/blog/2008/08/27/zootool-and-ubiquity/

== Web Lookup ==
[http://www.starwarsdatapad.741.com/ubiq.htm whois]: Performs a whois on selected or typed URL/IP.

[http://www.starwarsdatapad.741.com/ubiq.htm ping]: Pings the selected or typed URL/IP

[http://www.starwarsdatapad.741.com/ubiq.htm lookup]: Performs a lookup on selected or typed URL/IP.

[http://www.starwarsdatapad.741.com/ubiq.htm tracert]: Performs a tracert on selected or typed URL/IP.

[http://www.rakudave.ch/?q=node/25 just-ping]: Pings the selected or typed URL/IP from 32 checkpoints worldwide.

[http://www.starwarsdatapad.741.com/ubiq.htm isdown]: Takes selected or typed URL and determines if it is working using the downforeveryoneorjustme.com tool.

[http://gist.github.com/9285 Whats-My-IP]: Gets your IP address and displays it in the preview. Copies IP to clipboard on execute.

[http://gist.github.com/10700 Search-Domain-Name]: Checks the availability of com/org/net TLD domain names.

[http://gist.github.com/10707 Traffic]: Get Compete traffic charts for the given site.

[http://gist.github.com/10703 Host]: Checks the Web Host of the given site.

[http://gist.github.com/10702 Site-Down]: Checks if the site is down.

[http://gist.github.com/10249 Gmane]: Look up gmane group

==Google==

===extensions of the core commands===
* [http://mytechieself.blogspot.com/2008/08/writing-ubiquity-commands.html Google Scholar and Google Patent Searches]
* [http://www.radiantweb.net/ubiquity/ Google Book Search]
* [http://www.radiantweb.net/ubiquity/ Google News Search]
* [http://hondje.mine.nu/ubiquity/ Google Search within current domain]
** [http://www.endolith.com/ubiquity_commands.html Version that lets you specify which domain]
* [http://pynej.blogspot.com/2008/10/ubiquity-command-search-google-web.html Google Web History Search]
* [http://www.anod1.free.fr/pdf.html pdf] is a command that search pdf files with google.
*[http://threepipeproblem.com/ubiquity/gmine_ubiquity.html Gmine] searches Gmail, Google Calendar, and GDocs for your search term.

===Google Feeling Lucky ===
* [http://gist.github.com/16507 Quicky] not only runs your input through I'm Feeling Lucky, but lets you preview the page also. A quick, dirty splice up of 'go' and 'goto'.
* [http://point.pt/~guillaume/ubiquity/feeling-lucky.html Feeling-lucky] is a simple command that looks up the first result and displays it on the preview, and upon hitting enter, it executes by opening that particular web-page.
* [http://point.pt/~guillaume/ubiquity/feeling-lucky.html Link-to-feeling-lucky] is a command that is similar to ''link-to-wikipedia'': upon execution it injects a link to google's first result on the rich text-editing field. Quite handy when linking to companies websites while blogging.
''[[User:Griflet|Griflet]]: I renamed these commands with their natural names. The old commands with their original names can still be found [http://point.pt/~guillaume/ubiquity/myCows.html here]''

===google hacks===
* [http://www.anod1.free.fr/music.html music] is a command that use google hacks in order to find mp3 or ogg music.
* [http://www.anod1.free.fr/video.html video] is a command that use google hacks in order to find video.
* [http://icecreamfactory.freehostia.com/ubiquity/googlism.html googlism] shows what google.com thinks of you, your friends or anything
* [http://icecreamfactory.freehostia.com/ubiquity/directions.php directions] shows how to go from location-a to location-b on google maps

==Multiple site search==

* [http://math-www.uni-paderborn.de/~axel/ubiquity_search.html multi-search]: Searches Google, Yahoo, MSN Live and Ask.com simultaneously, in different tabs.

==Let Me Google That For You==

* [http://gist.github.com/45201 lmgtfy]: create a link to a (not so?) subtle suggestion for someone who asks you, via a computer, about something that Google might be able to answer. Courtesy of [[LetMeGoogleThatForYou.com]].

==Picitup Visual Search==

[http://www.picitup.com]: 2 commands:
* shop - Executes a shopping search with visual similarity and shopping compariosn - [http://www.picitup.com/picitup/picShop.jsp]
* picitup - Executes a visual search query agianst, Yahoo, Flikcr and Picasa image search engines [http://www.picitup.com]

== Legal Citation Search ==
*[http://www.keysquaremedia.com legal-cite]: Executes search of AltLaw for U.S. Code (federal statutes) and some federal case law (i.e., Supreme Court Opinions and federal appeals court opinions that were reported by West)

== Oracle ==
*[http://www.pythian.com/blogs/1187/ubiquity-and-tahiti-together-at-last Tahiti]: Executes search of Oracle documentation from their repository at http://tahiti.oracle.com. Can search all docs or version-specific docs.
*[http://mskadu.googlepages.com/ubiquityscripts search-oracle-docs: Search through the Oracle Documentation on] [http://www.oracle.com/technology/documentation/index.html Oracle Documentation website]

== Torrent Search ==
* [http://slackers.se/projects/ubiquity-hdbits HDBits]: Search for torrents on HDBits.
* [http://entvibes.com/torrents.htm torrent]: Search for torrents on ALL the big trackers at once (uses Torrent Vortex and Torrent-Finder)
* [http://www.furey.com.au/stuff/ubiquity/mininova/ mininova]: Search for torrents on [http://Mininova.org Mininova]. Refine your search using categories ("in") and sort types ("by").
* [http://garyhodgson.com/ubiquity/torrent.html mininova]: Performs a search for the selected text on [http://Mininova.org Mininova]. Optionally, a category can be defined, e.g. Books, Anime, etc.)
* [http://garyhodgson.com/ubiquity/torrent.html mininova-imdb]: Performs a search on Mininova.org for a given IMDB code (with or without the 'tt'-prefix).
* [http://gist.github.com/53950 imdbt]: Accurately search for movie torrents on mininova. Type movie keywords and specify desired movie with the "with" mod phrase using the movie's imdb code shown in the preview (start typing "with t" and choose from autocomplete suggestions). Search will be done using imdb code if available or keywords otherwise.
* [http://gist.github.com/57852 thePirateBay]: Performs a search for (a) given word(s) on [http://ThePirateBay.org ThePirateBay]. The result will be display directly on the ubiquity preview window, you can start downloading without opening a new tab.
* [http://gist.github.com/64552 piratebay]: Search for a torrent on Pirate Bay, with the option of specifying a category (Audio/Video/Software/Games/Other) and/or a sort (Type/Name/Uploaded/Size/Seeds).
* [http://garyhodgson.com/ubiquity/torrent.html piratebay]: Performs a search for the selected text on [http://ThePirateBay.org ThePirateBay]. Optionally, a category can be defined, e.g. Audio, Video, etc.)
* [http://mskadu.googlepages.com/ubiquityscripts search-torrentz: Search for torrents] on [http://www.torrentz.com Torrentz.com]
* [http://math-www.uni-paderborn.de/~axel/ubiquity_torrent.html torrent-search]: Searches on PirateBay, Isohunt and Torrentz simultaneously, in different tabs.
* [http://knightar.artician.com/blog/2008/09/TokyoToshocom-Search-Addon-for-Ubiquity/ tokyotosho]: Searches and lists TokyoTosho.com torrents. (Optionally, a category can be defined, e.g. Anime, Manga, Drama, Raws, etc.)
* [http://www.thecompgeek.info/ubiquity/demonoid.html Demonoid]: Searches for the predetermined set of keywords on Demonoid.com. Plain and simple.
* [http://avid.me/ubi/speckly.html Speckly]: Searches for keywords on Speckly.com - Searches 10 torrent sites
* [http://www.dca.fee.unicamp.br/~tatai/ubiquity btjunkie-search]: Searches for torrents on BTJunkie

= Natural Languages =
* [http://developer.swekee.com/ubiquity/ David Álvaro <> Diccionario de la lengua de la Real Academia Española ]: Español / Spanish (D-RAE)
* [http://yardensachs.com/ubiquity/ Yarden's Hebrew<>English Morfix dictionary lookup ]: morfix
*[http://yardensachs.com/ubiquity/ Yarden's Hebrish<>Engrew convert - between Hebrew char's and English char's with QWERTY layout ]: hetoen / entohe
* [http://halcy.de/past/2008/8/27/mozilla_ubiquity_beolingus_germanenglish_dictionary/ German<>English dictionary lookup ]: beo
* [http://www.satf.se/page/ubiquity-japanese-english-romaji-dictionary pihl's Japanese<>English romaji dictionary lookup ]: jaen
* [http://radheef.com/ubiquity/ Dhivehi Radheef (dictionary) lookup ]: jaa
* [http://olobolger.blogspot.com/2008/08/mozilla-ubiquity.html RAE Spanish dictionary definition lookup]: rae
* [http://pnxk.freehostia.com/ubiquity/cambridge_dictionary.html Cambridge English Advanced Learner's Dictionary Definition Lookup ]: English (Cambridge)
* [http://gist.github.com/65093 Cambridge English Advanced Learner's Dictionary Definition Lookup with preview ]: English (Cambridge). See a screen shot [http://sealence.x10hosting.com/wordpress/?p=66 here].
* [http://pnxk.freehostia.com/ubiquity/rae_dictionary.html Real Academia Española Diccionário/Dictionary Definition Lookup ]: Español / Spanish (RAE)
*[http://www.geocities.com/baloo_rch/rae_ubiquity.html Real Academia Española Diccionário/Dictionary Definition Lookup (with preview) ]: definir
*[http://www.heartsmagic.net/ubi.html Seslisozluk, Zargan English <-> Turkish look up] English <-> Turkish
*[http://www.verdsveven.com/ubiquity/nn_nb_dict.html Nynorskordboka og Bokmålsordboka]: Norwegian dictionaries
* [http://www.jpemartin.com/ubiq/calc2.html calc2] - natural language calculator
* [http://jarfil.net/ubiquity/dict.html dict.org lookup]: dict
* [http://gist.github.com/60377 dizionario]: - Italian dictonary (Hoepli)
* [http://gist.github.com/70871 De Mauro]: - Search Italian Dictionary De Mauro Paravia

=Programming Languages=
== Asterisk ==
[[Labs/Ubiquity/dial]]: Configure your Asterisk PBX to use the 'dial' command for Ubiquity.

== Common Lisp ==
* [http://common-lisp.net/project/lifp/ubiquity/clhs.htm Search Common Lisp Hyperspec]

== C++ ==
[http://abauchu.net/ubiquity/search-cpp.html search-c++] Searches a term on [http://www.cplusplus.com cplusplus.com].

== jQuery ==
# [http://erikvold.com/tools/ubiquity/jquery/jquery.cfm jquery]: Searches the jQuery documentation.

== PHP ==
[http://taukon.de/ubiquity-php-function.php php]
search PHP function documentation
example: php join()

[http://taukon.de/ubiquity-php-function-doc.php phpd]
search PHP documentation
example: phpd class

== Perl ==
[http://www.grok.in/ubiquity/perl.html perldoc, cpan, monks]: Three commands, one each to search perldocs, CPAN and perlmonks.org

== Rails ==
[http://gist.github.com/43619 rails]
search rails documentation
example: rails link_to

== ActionScript ==
[http://anirudhs.chaosnet.org/blog/2008.09.04.html as3livedocs, as3desc, as3package]: Three commands, one to open up livedocs page given a class, one to give the description of an actionscript class and another to give the package to which a class belongs to.

== Coldfusion ==
[http://erikvold.com/tools/ubiquity/coldfusion/coldfusion.cfm coldfusion]: Search the Coldfusion 8 LiveDocs.

== MySQL ==
[http://erikvold.com/tools/ubiquity/mysql/mysql.cfm mysql]

* mysql: Search all of the MySQL documentation.
* mysql5: Search the MySQL 5.0 reference manual.
* mysql5.1: Search the MySQL 5.1 reference manual.
* mysql6: Search the MySQL 6.0 reference manual.
* mysql-admin: Search the MySQL administrator reference manual.
* mysql-query-browser: Search the MySQL query browser reference manual
* mysql-migration-toolkit: Search the MySQL migration toolkit reference manual.
* mysql-workbench: Search the MySQL workbench reference manual.

[http://mitcho.com/code/select select] - select gives you read access to your MySQL databases right from Ubiquity, with smart suggestions of your table and column names.

== Postgres ==
[http://gist.github.com/44867 postgres]

* postgres: Search all of the Postgress documentation.
* postgres83: Search the Postgress 8.3 reference manual.
* postgres82: Search the Postgress 8.2 reference manual.
* postgres81: Search the Postgress 8.1 reference manual.
* postgres80: Search the Postgress 8.0 reference manual.
* postgres74: Search the Postgress 7.4 reference manual

== Java ==
[http://www.cse.ucsd.edu/users/jnguy/java.html Java API] - Wraps a google search pointing to the java API

== Javascript ==
[http://blog.monstuff.com/archives/000341.html Beautify-JS] - Let's you nicely reformat any selected javascript code. Handy for Ubiquity verb authors.

== HTML/CSS Reference ==
[http://gist.github.com/62697 W3Schools Search] uses google to search W3Schools' documentation on HTML, javascript, CSS, and other web technologies.

== HTML Validation ==
[http://joshhuckabee.com/w3c-validator-ubiquity-plugin W3C Validator Ubiquity Plugin] Submits the current page to the W3C's markup validator. Enter the command "validate" on any publicly available web page and hit enter.

== Wordpress ==
[http://avid.me/ubi/wordpress.html Wordpress] Searches the terms in Documentation & Forums on Wordpress.com

== Drupal API ==
[http://joshhuckabee.com/drupal-api-ubiquity-plugin Drupal API Ubiquity Plugin] Lookup functions, files, constants, etc. in Drupal's API. Enter the command "drupal" followed by what you wish to lookup. Hit enter to be taken to that item in the API.

==Python==
[http://www.vwelch.com/ubiquity/pydoc.html Pydoc] Lookup any Python terms via http://starship.python.net/crew/theller/pyhelp.cgi. Enter "pydoc" followed by the search term.

=URL Tools=

* goto: Simply navigate to any URL - http://gist.github.com/72189

==mac==
https://wiki.mozilla.org/Mac
search for manifacturer with last octet of mac adress

==is.gd==
[http://arunstechcorner.blogspot.com/2009/02/shorten-urls-in-ubiquity-with-isgd.html is.gd] Shorten and replace the selected URL with is.gd service. The shortened URL is also copied to the clipboard
== Inlinks ==
[http://erikvold.com/tools/ubiquity/inlinks/inlinks.cfm Inlinks] Find the number of external inlinks to a provided url (yahoo.com only).

== BuiltWith ==
[http://builtwith.com BuiltWith] Find out what technologies the URL is using.

== Text2Link ==

[http://text2link.jeffreyjmorgan.com/ubiquity/ Text2Link] opens URLs and sends emails to addresses not marked up as HTML links with the A tag. This is the Ubiquity version of the [https://addons.mozilla.org/en-US/firefox/addon/6003 Text2Link Firefox Extension].

== shortText.com ==

2 commands:

* [http://shortText.com/ shorttext]: Creates a shortText URL for any selected text
* [http://shortText.com/ longtext]: Select any shortText URL on any site and it will replace the URL with the actual content

== Bit.ly ==

* [http://mskadu.googlepages.com/bitly bitly] - Shortens the selected url using [http://bit.ly Bit.ly]. Pretty much the same as the built-in tinyurl.
* Shorten URL and copy to clipboard using bit.ly service: http://bit.ly/18Fsn2
* Shorten and replace selected URL in a Rich Text Field or reverse an already shortened bit.ly URL: http://bit.ly/315THd

== LongURL ==

[http://longurl.org/tools expand-short-url] Uses the LongURL service to expand URLs shortened with any shortening service (TinyURL.com, Bit.ly, etc.)

== Tr.im ==
[http://almaer.com/firefox/commands/ trimurl] Uses the tr.im service to shorten a URL and put it in your clipboard if successful

== Hurl.ws ==

Shorten a URL using hurl.
Simply navigate to [http://www.hurl.ws hurl.ws] to install using firefox.
Use the command "hurl"

== a.longreply.com ==

Use a.longereply.com to convert any section of text into a URL so you can then send this link via IM, Twitter, email? Can send very large peices of text.
Use the command "longreply". To install it [http://a.longreply.com a.longreply.com]

== shorten ==

The all in one URL shortner: [http://labs.vunite.com/vubiqs/verbs.php vunite's commands]
Usage: shorten [url] using [tinyurl|isgd|bitly|hurl|snipurl]

== kissa.be ==

A new [http://www.yalazi.org/ubiquity/list.html kissalt, url shortening service], kissalt means "shorten" in Turkish (original word: kisalt)

== lincr ==

[http://sathyasays.com/2008/09/21/my-first-ubiquity-command-lincr-it/ Lincr ] is a URL shortening service. The [http://lin.cr homepage] also shows a list of recently Lincr'd URLs and a RSS feed of the same.

== Other URL manipulation==
* [http://projects.fligtar.com/ubiquity/url.php URL Tool] - Converts selected URLs to links or lets you choose which one to open in a new tab.
* [http://nevermind85.net63.net/Ubiquity/try.html ToLink] - Converts the selected text link in a real clickable link.
* [http://blog.monstuff.com/archives/000343.html insert-link] - Search for a link in your history and insert it.
* [http://earth2marsh.com/ubiquity/ Percent Encoding Tools] Commands to percent encode as well as decode (aka "URI encoding") selected text. Provides preview and/or replaces selected text.
* [http://kollektive.com/ubiquity/ links] - converts non-marked up text/html which contains urls and email addresses into proper anchor tags. Works within html pages, and in rich text editing fields (eg. rich text editing in GMAIL)
[[Media:Example.ogg]]

= Web 2.0 (Social networks, blogs, recommenders, etc) =

== BackType ==
# [http://erikvold.com/tools/ubiquity/backtype/backtype.cfm backtype]: Starts a search of BackType, which allows you to do a search for a person's comments on blogs and other sites.

==CipherHive==
A Global search of Moodle Based Courses, Forums, Wiki's, Blogs, Users, Posts, Authors, etc.

Script: http://www.cipherhive.org/course/view.php?id=19

To use, just type cipher + the word you wish to search.

== Digg ==

Submit a selected, or manually typed URL, or simply type digg to submit the current tab's URL to digg...
... will be extended shortly with options to include title, description, category and preview image ... possibly even skip the digg "new entry" page ...

Script: http://www.wgbox.de/ubiquity/digg.html

== Del.icio.us ==

=== Add a page to your delicious bookmarks ===

Script: http://gist.github.com/7516

To use, just type delicious + your tags.

Another Command: http://decafbad.com/UbiquityCommands/

Highlight some text on the page for notes, activate Ubiquity, enter command share-on-delicious. You can also enter your own notes, assign tags to the bookmark with the "tagged" modifier, and alter the bookmark default page title with the "entitled" modifier. Note that you must also already be logged in at delicious.com to use this command.

Another Command: http://gist.github.com/9499

Emulates the Delicious.com bookmarklet. Highlight some text on the page for notes, activate Ubiquity, enter command delicious. It will pop up a new window where you can select tags other people have used for the URL.

=== View a users delicious tags ===
Script: http://parentno.de/ubiquity/?command=get-delicious

Shows del.icio.us bookmarks from this user {username} tagged with {tagname}
To use, type get-delicious {username} tag {tagname}

=== View the 10 most recent/popular bookmarks in delicious ===
Script: http://201.238.211.147/~yinocl/ubiquity.html

Shows the 10 most recent/popular del.icio.us bookmarks.
To use, type recent-delicious or popular-delicious.
A basic save-delicious is included as well.

== Evernote ==
*[http://gist.github.com/50974 clip to Evernote] Clip the current web page selection to Evernote

== Facebook ==

Lets you update your status and go quickly to a friend's profile.

[[http://grantrules.com/ubiquity/facebook.html script]] with two commands:
* 'facebook-status (your status)' - Updates your status, doesn't add "is"!
* 'facebook-friend (your friend)' - Locate a friend. You have to type whole words, though (if searching for Amy Jones, you can't type Amy Jon; it must be one of: amy, jones, amy jones!)

=== Share on Facebook ===
Shares the the page in the current tab on Facebook. I parsed the bookmarklet provided by Facebook so you get the nice little pop-up window rather than a whole new tab.

Script: http://jallen7usa.com/ubiquity/

=== Search Facebook ===

Look anything up in Facebook, contacts, groups and it even works whether you are logged in or not.

script here
http://myfirstscript.blogspot.com/2008/10/ubiquity-is-awesome_06.html

== Ffffound it! ==

Adds images to the Ffffound! image repository site. You must have a Ffffound! account to be able to use.
Simply navigate to [http://www.lantern.co.nz/ubiquity/ffffound.html lantern.co.nz/ubiquity/ffffound.html] to install using firefox.
Use the command "ffffound it" on a page which has the image you want to save.

== Friendfeed ==
*[http://gist.github.com/51007 share-on-friendfeed] Simple bookmarklet command to share the current page on friendfeed.

== Hatena ==

*[http://gist.github.com/8351 hatebu]
*[http://gist.github.com/8575 hotentry]

== Identi.ca ==

Script: [[http://bobbo.me.uk/code/ubiquity/]] Allows you to post to Identi.ca from Mozilla Ubiquity. To use, install from link, open Ubiquity and type "identi.ca" followed by your status message.

== Mixx==
# [http://erikvold.com/tools/ubiquity/mixx/mixx.cfm mixx]: Mixx the typed/pasted url, or highlighted url, or otherwise the current page. Also get the mixx count of the url in the preview.

== myExperiment ==

Script: [http://www.myexperiment.org/files/151/download/myexperiment_search.js myExperiment basic search command] Basic search plugin for myExperiment, an online comunity for scientists.

== MySpace.com ==

Four tools to update and interact with your MySpace account.

- Comment
- Send Message
- Post Bulletin
- Create Blog Entry

[http://devstatus.com/ MySpace Command Collection] Quick and easy way to use the contextual information from Ubiquity on MySpace. Read syntax and examples on related pages.

== Pawst.com ==

Search social bookmarking websites using pawst.com 
Simply type 'pawst topic' i.e 'pawst funny pics'

by [http://shmuel.ahdut.com Shmuel Ahdut] - licensed as MPL

Subscribe: http://pawst.com (You'll get Ubiquity's subscribe popline) 
Script: http://pawst.com/javascripts/ubiquity.js

== Sphinn ==
# [http://erikvold.com/tools/ubiquity/sphinn/sphinn.cfm sphinn]: Sphinns the typed url, or highlighted url, or otherwise the current page. Also get the sphinn count of the url in the preview.

== Jaiku ==
Script: http://ubiquity.pastebin.com/f495c6d62
To add your username and api key use the command:
jaiku-setuserandkey <username> api <apikey> -- you can get your api key on http://api.jaiku.com
(inspired by http://trodrigues.net/ubiquity/pingfm/)
to post:
jaiku <you presence> at <location> : The location is optional, if you don't pass, the script will try to guess it using CmdUtils.getGeoLocation().

== Idiquity ==
[http://geekmatters.com/Ubiquity/Idiquity.html Idiquity]allows updating and checking your timeline from Ubiquity. More functionality is to come; details are at the site. It is compatible with any Laconi.ca based site (or any site with a Twitter compatible API).

== News and Feed Readers ==

[http://i8news.appspot.com/ubiquity/nytimes.html NYTimes recent Headlines]: autosuggest recent headlines when you are typing; and if no matching, just hit enter, you will go to NYTimes.com search page.

[http://www.bennysheerin.com/ubiquity.html Simple news feed]: Returns latest headlines from various vendors such as bbc, cnn and digg.

[http://www.planetaki.com/ubiquity Planetaki Commands]: Add the website you're visiting to your Planet

[http://cokeeffe.wordpress.com/get-news-for-ubiquity/ get-news]: Enables you to search Google News for news titles.

== Nexopia ==

=== Go to user profile ===

Type "nexopia" and the user's name and it will take you directly to that user's profile on Nexopia.com.

Script: http://jodyheavener.com/ubiquity/nexopia/

== People Search ==
* [http://www.123people.com 123people]: Let's you search people meta data from around the world via Ubiquity.
* [http://avid.me/ubi/pipl.html pipl]: Searches for People's name on pipl.com
* [http://avid.me/ubi/chickipedia.html Chickipedia]: Searchs for Chickipedia, the world’s largest web-based, women-based, wiki-based database of hot chicks.

== Serchilo ==
[http://wiki.serchilo.net/Serchilo:Ubiquity Serchilo in Ubiquity] allows using [http://serchilo.net Serchilo] commands in Ubiquity.

== Slashdot ==
* [http://blipo.ath.cx/chkslashdot.html Check Slashdot]

== Ping.fm ==

Allows you to post messages via the ping.fm service.

Script: http://ubiquity.washing-up.co.uk/pingfm.html

The first time it is used, you must provide it with your ping.fm app key by typing "ping-set-key <your app key>" Once it has stored your app key, you do not need to provide it again, and can just type "ping <message>" Your app key can be found at [http://ping.fm/key http://ping.fm/key]

== Tonight.eu ==

Lets you to search venues, restaurants and events in some big european cities.

Script: http://www.tonight.eu/ubiquity/

== Bugmenot ==

A password database site for general public

[http://www.yalazi.org/ubiquity/list.html bugmenot, username password retrieving from bugmenot]

== Google Bookmark ==
Adds the current page to your Google bookmarks with the title you give it. Still rather rough - not robust against invalid inputs.
http://www.cs.washington.edu/homes/butaud/ubiquity.html

== Google Reader (shared items) ==
Adds the current selection to your Google Reader Shared Items page
and allows you to add a note to it.
[http://abauchu.net/ubiquity/share-on-reader.html share-on-reader command]

Alternate Command: [http://pynej.blogspot.com/2008/10/ubiquity-command-note-in-reader.html Note in Reader]

==Gmail==

* [http://fettig.net/playground/ubiquity/ Gmail Status Message] Update your Google Talk status message in Gmail
* [http://www.jpemartin.com/ubiq/smiley.html Smiley] Insert smileys into your email message (also works with other email or blog)
* [http://www.geocities.com/skyhopper88/GmailEdit.html GMail Edit] Edit of an old Ubiquity script to work with latest version (.1.1). Opens Gmail in a new tab, as well as showing you the last couple of new messages in the preivew.
* [http://www.strangeblackhole.com/sign-it/ Sign It] Now you can sign your message, blog post and other with HTML code.

== Reddit ==

[http://urdna.org/ubiquity Urdna's 'Reddit-This' command]

== Social Graph (FOAF/XFN etc) ==

[http://danbri.org/2008/ubisg/ DanBri's 'foaf' command] (calls Google SGAPI)

== Stickam ==

http://stickhacks.googlepages.com - Watch someone's live Stickam stream without going to their profile

== mYoUvies.com ==
[http://myouvies.com/ubiquity/ movieshare]: Allows for simple posting to the social movie news website [http://myouvies.com mYoUvies.com]

== Soup.io ==
[http://static.al3x.net/ubiquity.html soup] - replicates the functionality of the bookmarklet for the Soup.io tumblelogging service

== Open Contacts ==

Create, search, list or sign [http://annoq.aspectweb.org/uq.html commands] for [http://annoq.aspectweb.org/softLink.html#openq openqx.org] experimental project. Associates freely accessible contact information (such person name, telephone number, email, etc.) with regular web domains. Web API and flexible query language included. Ubiquity commands:
* openq-search (cross domain searching)
* openq-list (lists contacts for contextual domain)
* openq-create (adds new contact to the contextual domain)
* openq-sign (sign documents with your Open Contact data)
* openq-to (fill address fields by querying Open Contacts)

== Form Data Templates ==

Create data templates by saving form content (ubiquity form-save). Password fields are left out for security reasons. Once persisted, the data becomes available to anyone (ubiquity form-load). [http://annoq.aspectweb.org/fuq.html commands]. The functionality is similar to what you already know from wire transfer templates but '''please avoid experimenting with sensitive data'''. (eg. go to Bugzilla graphical [https://bugzilla.mozilla.org/query.cgi?format=report-graph report generation page] and issue form-load [Enter])

== Web Annotations & User Links ==

Yet another [http://aspectweb.org aspectweb.org] project. Social service commands to create, embed or search comments or custom links for any regular web page. [http://annoq.aspectweb.org/sq.html commands] (eg.: goto Jean Gebser wiki [http://en.wikipedia.org/wiki/Jean_Gebser page] and type '''slink-list''' to list current user links or '''annoq-list''' for related annotations)
* [http://www.strangeblackhole.com/sign-it/ Sign It] Now you can sign your message, blog post and other with HTML code.

== shortText ==

2 commands:

* [http://shortText.com/ shorttext]: Creates a URL for any selected text
* [http://shortText.com/ longtext]: Select any shortText URL on any site and it will replace the URL with the actual content

==Twitter==
* [http://benatkin.com/ubiquity/tweet/ Ben's tweet command]: post to twitter (with URL shortener)
* [http://geekmum.com/ubiquity twittersearch]
* [http://www.matthias-schuetz.eu/twitter-ubiquity.html twitter]With timeline and auto completion for contacts' names.
* [http://sites.google.com/site/coosgadgets/2ii 2ii], based on matthias' work. Add current url replacement and shorten, hyperlink in the preview etc.
* [http://gist.github.com/52797 twtplus] Forked from 2ii. Cleared out "ugly hacks" and refactored a lot. New features include shortening all urls in a post, d message with friend username autocompletion, and posting as specified user account.
* [http://gist.github.com/20044 otw] I can't type such a long username.
* [http://gist.github.com/38698 wtw] Twitter viewer.

==Tumblr==
* [http://gist.github.com/48778 ptm] You can post to Tumblr. But please pay attention to L3 and L4 - email and password.

= Web 3.0 (Web Of Data, Semantic Web, etc) =
Commands allowing the access or manipulation Web 3.0 content, that is [http://www.w3.org/RDF/ RDF]-based datasets such as [http://linkeddata.org linked data].

* [http://srv.buzzword.org.uk/ Cognition] microformat/RDF/RDFa/eRDF/GRDDL parser.
*# <code>cognify</code>
*[http://jowl.ontologyonline.org/Ubiquity.html jOWL Ubiquity command], Visualize and query on OWL-DL files with [http://jowl.ontologyonline.org jOWL]
*# <code>view_ontology</code>

== Microformats ==
* Microformats Extraction commands available at http://transformr.co.uk/
*#commands:
*#* <code>get-atom</code> from [http://microformats.org/wiki/hatom hAtom]
*#* <code>get-vcard</code> from [http://microformats.org/wiki/hcard hCard]
*#* <code>get-webcal</code> from [http://microformats.org/wiki/hcalendar hCalendar]
*#* <code>get-podcast</code> from [http://microformats.org/wiki/haudio hAudio]
*#* <code>get-rdf</code> from [http://www.w3.org/TR/xhtml-rdfa-primer/ RDFa]

* Search the [http://microformats.org/wiki/ Microformats Wiki] available at http://weborganics.co.uk/
*#command:
*#* <code>uf-search</code> (search term)

== WoD ==
[[User:MichaelHausenblas|Michael Hausenblas]] has put together a [http://sw.joanneum.at/ubiq/ collection of WoD commands]. Currently three commands are available:
* query the semantic indexer [http://sindice.com Sindice] for a term
* lookup [http://dbpedia.org/About DBpedia] resources [http://gist.github.com/59915 lookupNdbpedia]
* lookup [http://dbpedia.org/About DBpedia] for things in a certain category
* perform a [http://curl.haxx.se/ curl] HEAD for a URI

== Crunchbase ==
[http://bnode.org/about Benjamin Nowack] has written the [http://cb.semsol.org/ubiquity cb command] allowing to do [http://www.crunchbase.com/ CrunchBase] lookups for companies, products or people.

== Twine ==
[http://static.isnotworking.com/add-to-twine.html add-to-twine]:
Brings up the dialog for posting the current page to [http://twine.com Twine].

== Linked Data Exploration ==
[http://demo.openlinksw.com/ubiq OpenLink Web Resource Description Commands] - Commands for obtaining structured descriptions of Web Resources. Uses [http://virtuoso.openlinksw.com/ Openlink Virtuoso]'s in-built RDFization Middleware ("Sponger") and Linked Data Deployment technology.

== Link lookup and insertion ==
[http://demo.monrai.com summon command] - look up a link representing the keywords or phrase you enter, and inserts it into the page. Good for quickly inserting links into emails, blog, blog comments, twitter, etc.

== headup ==
[http://www.headup.com/ubiquity.html headup]: Connect the artist / city / person / company / movie / book / etc - with relevant and personalized information, using the headup Firefox addon - [http://www.headup.com Get headup].

= Visualization =
* [http://code.google.com/p/tl-ubiquity-commands/source/browse/trunk/visualization/word-cloud.js word-cloud] generates a 'word cloud' from the selected text.

= Clocks =
* analog clock - http://www.jpemartin.com/ubiq/time.html (also allows you to specify a timezone)
* minute-minder: show the time on page-load - http://individual.utoronto.ca/duez/cw.html
* MJD to UTC and UTC to MJD converters: [http://www.storybookdachshunds.com/surlyfritter/ mjd2utc and utc2mjd]
see also swies's commands, below
* [http://swapoff.org/files/ubiquity_time/ An international clock (plus flags!)] This looks pretty cool but say, Moscow time is off by one hour! Looks like the problem with EarthTools, maybe use something else?

= Travel =
* [http://widgets.bootsnall.com/ubiquity/flight.html flight search]
* [http://blog.mikelorengo.com/2008/09/ubiquitizing-jenn-for-flight.html fly-alaskaair]. Shops for flights on Alaska Airlines and Horizon Airlines "fly-alaskaair (cmd)" where (cmd) can be free form text. Examples include:
** fly-alaskaair sea lih 02/11/2009 return 02/25/2009
** fly-alaskaair sea lax next thursday return sunday
** fly-alaskaair sea sjd next wednesday one way
* [http://widgets.bootsnall.com/ubiquity/hotel.html hotel search]
* [http://widgets.bootsnall.com/ubiquity/vacation.htmlvacation package search] (flight+hotel together)
* [http://widgets.bootsnall.com/ubiquity/car.html car rental search]

= Maths =
* Converts selected amount to foreign currency (currently supports over 60 currencies) http://users.tpg.com.au/tbchris
* [http://www.verdsveven.com/ubiquity/metric.html metric]: Converts numbers to metric units. Can recognize numbers in the selection and replace them.
* [http://samespirit.net/ricky/dev/ubiquity/chart.html chart]: Draws a chart using the Google Charts API based on the selected table row.
* temperature converter - http://www.jpemartin.com/ubiq/temp.html
* base64 decode / encode - http://taukon.de/ubiquity-base64.php
* Integrate - http://tat.wright.name/ubiquity/integrate.html
* gcalc (interface to Google's calculator; converts units and currencies, knows constants of nature etc.) - http://math-www.uni-paderborn.de/~axel/ubiquity_gcalc.html
* calculate2 (a good calculator) - http://www.jpemartin.com/ubiq/calc2.html

= Programming / development tools =

* [http://www.ewitk.com/char-count.html char-count] is a command to count the number of characters in a block of selected text.
* [http://www.dahius.com/projects/ubiquity/pwgen/ pwgen] is a password generator service (http://pwgen.net)
* Whatismyip - http://www.srobbin.com/ubiquity-commands/whatismyip/
* [http://gist.github.com/10371 comments]: Display html comments on the page as css roll-over popups
* [http://mitcho.com/code/select select] - select gives you read access to your MySQL databases right from Ubiquity, with smart suggestions of your table and column names.

= Random tools =
* [http://jasonwilsondesign.com/development-locker/ubiquity-commands/BBFlickr.php BBFlickr]: Quickly translates Flickr's generated HTML links to BBCode in your clipboard.
* [http://www.bennysheerin.com/ubiquity_open.html open]: Allows you to quickly open your favourite web sites.
* open-in-tab - http://bergius.org/ubiquity/?open-in-tab
* Twurl shorten URL - http://xolotl.org/ubiquity
* xkcd (shows latest xkcd comic in preview pane) - http://alexsydell.com/applications/ubiquity/xkcd/
* flags of the world - http://www.jpemartin.com/ubiq/flag.html
* forecast - http://dothejustice.com/forecast/
* images (shows only the images on a page) - http://kloudsolutions.com
* [http://erikvold.com/tools/ubiquity/comicstrip/comicstrip.cfm comicstrip]: Allows you to view a comicstrip and drop the image into an area selected (such as a gmail email). So far the command supports bc, bornloser, dilbert, garfield, getfuzzy, herman, monty, peanuts, penny-arcade, offthemark, opus, userfriendly, workingitout, and xkcd.
* [http://members.optusnet.com.au/~crazyjane13/lolcats.html lolcats]: Retrieves the latest LOLCAT in the preview, jumps to page on execute - by Brett Dalton
*[http://members.optusnet.com.au/~crazyjane13/roll.html roll]: Dice rolling verb, rolls single, multiple dice of any size with option for variable dificulty exploding dice pool (as per World of Darkness) - by Brett Dalton
*[http://student.dei.uc.pt/~rmramos/ubiquity/lorem.html lorem]: Allows you to copy any given number of words or paragraphs of the "Lorem Ipsum" placeholder text onto your Clipboard, useful if you want to paste it in some other application afterward. Use: lorem [num] nice [words||paragraphs]
* nofollow - Preview counts no-follow links and execute highlights them. [[http://surfmind.com/lab/mozilla/ubiquity/nofollow.html Install Page]], [[http://surfmind.com/lab/mozilla/ubiquity/nofollow.js Script:]], [[http://flickr.com/photos/andyed/2767130077/in/photostream/ Preview]]
* [http://www.rakudave.ch/?q=node/26 Rhyme] a word
* [http://common-lisp.net/project/lifp/ubiquity/sharebee.htm sharebee-download] Sharebee
* [http://insideoutsites.com/ubiquity/ xbl] - displays your xbox live friends list in the preview window
* [http://www.nt7s.com/blog/ubiquity-qrz/ qrz] - Lookup amateur radio callsigns on the QRZ.com server.
* [http://www.briandgoad.com/blog/ubiquity-commands/websourceit/ websource] - Compares the popularity on the internet of two (or more) terms using Websource.It
* [http://www.developerfriendly.com/ubiquity/roll.php UbiquityRoll] - get your roll on demand, currently supports rickroll duckroll and hoodroll
* [http://www.nasser.me/ubiquity/rapidsharecom-link-checker/ rscheck] - check selected links on rapidshare.com link checker.
* [http://f.resourcehog.net/has-swearing.php has-swearing] - check to see if the selected text has any swearing in it; highlights any instances of swearing.
* [http://www.dib0.nl/ubiquity.html open-all-bookmarks-in-tabs] - opens all bookmarks filed under the given folder in new tabs. It is also possible to open bookmarks with a specific tag.
* [http://www.geocities.com/ubiquities1 reverse-telephone] - reverse lookup on a german telephone number via das-oertliche.de
* [http://www.watersheep.org/~markh/screengrab.html screengrab] - takes a screen grab of the current page.
* [http://stuarthendren.net/printwyl printwyl] - opens current page in [http://www.printwhatyoulike.com PrintWhayYouLike.com] so you can create a better print out of the information you need.
* [http://yonen.ca/ubiquity2.html qr_code] - Generates QR Code images.
* [http://gist.github.com/21311 notepad] - Opens Notepad on Windows
* [http://gist.github.com/21319 paint] - Opens MS Paint on Windows
* [http://mike.thedt.net/ubiquity/note/note.php note] - The purpose of this command is to quickly save the inputted text (can be selected text or your own text) to a file on your disk without having to launch a text editor.
* [http://boardraider-ubiquity-commands.googlecode.com/svn/trunk/fx-update-scanner.html fx-update-scanner] - Update checks for restricted user accounts
* [http://boardraider-ubiquity-commands.googlecode.com/svn/trunk/gd-upload.html gd-upload] - Uploads a document to Google Docs via URL
* [http://boardraider-ubiquity-commands.googlecode.com/svn/trunk/vacuum-places.html vacuum-places] - Executes the VACUUM statement on your places.sqlite
* [http://gist.github.com/62707 d20] - Searches d20srd.org.
* [http://kilianvalkhof.com/uploads/ubiquity-binary Binary tools] - Convert text to binary, and the other way around.
* [http://kilianvalkhof.com/uploads/ubiquity-yoda Yoda speak] - Convert text to how master Yoda would say it.
* [http://gist.github.com/70761 lyric]: Lookup song lyrics from lyrics.astraweb.com
* [http://gist.github.com/69722 muni]: Grab San Francisco, CA muni bus arrival information from nextmuni.com. ''example: muni 24 at Divis and Fulton''
==Flip==
* [http://www.michaeltheweissman.com/flip flip]: Flips text uʍop ǝpısdn

=Development Tools=
== Gecko Development ==
* [http://sites.google.com/site/cgranade/projects/ubiquity-scripts xpc-interfaces]: Queries a list of interfaces supported by a given XPCOM contract ID.

=Other Web Applications=
== Woot ==
[http://gist.github.com/41227 Woot Checker] - Previews the current Woot item and takes you to the "Want One" page.

== ESV bible ==
[http://www.duncanandmeg.org/projects/ubiquity-esv-insert.php esv-insert, esv-insert-plain, esv-search] - Replaces the current selection with verses from the ESV Bible, or searches by passage or phrase.

== Amazon ==
=== Wish List ===
[http://jplorenti.googlepages.com/ubiquity-wishamazon WishAmazon] - Allows adding any product page on the web to your Amazon Wish List. Similar functionality to the Amazon Universal Wish List bookmarklet.

[http://avid.me/ubi/skreemr.html Skreemr] - Searches Skreemr.com for downloading Mp3's

== BookMooch ==
[http://www.sillybean.net/downloads/ubiquity-commands.html mooch] - Search [http://bookmooch.com/ BookMooch] for the term you provide.

== Finances ==
=== Buxfer ===
[http://gist.github.com/66959 buxfer-spend, buxfer-receive] - Adds a transaction to www.buxfer.com using its remote API, spending or receiving a given amount. (Homepage [http://sites.google.com/site/edgargoncalves/work/software/ubiquity here]).

[http://dl.getdropbox.com/u/103378/projects/buxferubiquity/buxferubiquity.html twixfer] - Adds a transaction to www.buxfer.com, using the Twitter API (obsolete - use buxfer-spend and buxfer-receive instead) (Homepage [http://sites.google.com/site/edgargoncalves/work/software/twixfer here]).

== GTD ==
=== gtd-php ===
[http://www.gtd-php.com/Developers/Ubiquity gtdphp] - <tt>gtdin</tt> adds an inbox item, and <tt>gtdref</tt> creates a reference to the current page, as a child of a specific project
=== Remember The Milk ===
* [http://garyhodgson.com/ubiquity/rtm-api.html rtm-*] - Commands to manage your Remember The Milk task lists. Add, postpone, prioritise, complete, move and view commands are available.
* [http://garyhodgson.com/ubiquity/rtm.html rtm (bookmarklet)] - Opens the RTM [http://www.rememberthemilk.com/help/answers/quickadd/ quick-add bookmarklet].

=== Gubb ===
[http://ivancho.awardspace.com/ubiquity/gubb.html gubb-*] - Interface to [http://gubb.net Gubb], with adding items and inserting lists/contents functionality.

=== Nozbe ===
[http://svd.at.tut.by/nozbe.html nozbe-*] - commands to manage tasks in Nozbe.

== Science ==
=== NCBI ===
[http://gist.github.com/67266] - Very preliminary attempt to access NCBI and other genomic resources - currently only Pubmed

== Wikis ==
=== TiddlyWiki ===
[http://garyhodgson.com/ubiquity/tiddlywiki.html tw-*] - Allows you to Create, Open, or Search for keywords within, Tiddlers from your [http://www.tiddlywiki.com/ TiddlyWiki]

== Temporary Email Address ==
=== Jetable.org ===
Script: http://gist.github.com/11261

Creates a temporary Jetable email address for a given life span (one hour, one day, one week, one month).
=== Mailinator.com ===
mailinator - http://gist.github.com/16415

Opens the mailinator inbox of the typed name.
=== Spambox.us ===
http://gist.github.com/41634

Creates a temporary Spambox.us email address for a given life span (half hour, hour, half day, day, week, month, half year, year).

== TheSixtyOne.com ==
[http://www.jpemartin.com/ubiq/pause-TSO.html pause-TSO] pause and resume music playback.

== World of Warcraft ==
* Gryffyn's Basic Allakhazam Lookup w/Preview: http://www.gryffyndevelopment.com/ubiquity/alla.html
* Zenwolf's WoW Armory Command: [http://www.annieandmatt.com/ubiquity/wowarmory.html Subscribe/View code here]
* Amosh's Wowhead Database Search [http://gist.github.com/19910]

== instapaper.com bookmarklet ==

[http://www.duncanandmeg.org/projects/ubiquity-instapaper.php instapaper]: Saves current page to read later on [http://www.instapaper.com/ Instapaper]. If you select some text from the page, it will be stored as the summary. This command will store your instapaper login and password in the browser password manager. Uses the new [http://blog.instapaper.com/post/73123968/read-later-api instapaper API].

[http://static.al3x.net/ubiquity.html later]: an alternate implementation that mimics the instapaper.com bookmarklet (requires your bookmarklet hash key). Might be a dead link now???

== laterloop.com Bookmarklet/RSS ==
[http://gist.github.com/10172 laterloop-this]: Mimics functionality of the [http://www.laterloop.com laterloop] bookmarklet.

[http://gist.github.com/10172 laterloop]: Shows items you have saved for later in your preview. Allows for paging and can open a specific item through use of an "open #" modifier.

[http://gist.github.com/10172 laterloop-clear]: Utility command to clear out preference values stored when initially setting up the laterloop and laterloop-this commands.

== Shoutcast Search ==
http://myfirstscript.blogspot.com/2008/10/ubiquity-is-awesome_06.html
Search for anything in Shoutcast, artist, song, genre. use it everytime you wanna hear that one great song!.

== ROT13 ==
[http://www.randomloci.com/dev/ubiquity/rot13.php ROT13]: Translate selected text using the ROT13 algorithm. Background [http://www.randomloci.com/dev/ubiquity/index.php here].

= Command collections =

[http://devstatus.com/ MySpace command collection]: MySpace Command Collection

[http://ianj.appspot.com/insert Insert words using a keyword]: insert and learn-to-insert

[http://jorgensen.ian.googlepages.com/size.html Screen Resolution commands]: size and resize

[http://liketribe.com/liketribe/lktrb-ubiquity.html liketribe]: chat with an intelligent assistant bot to get recommendations, directions, weather, connect with friends, or just ramble on aimlessly.

[http://www.tonight.eu/ubiquity/ Tonight]: searches for venues, restaurants and events in your city, near a specific location.

[http://www.bennysheerin.com/ubiquity.html news command]: simple news command.

[http://www.rakudave.ch/?q=node/18 rakudave's commands]: firefox add-ons, ubuntu brainstorm, just-ping, rhyme

[http://widgets.bootsnall.com/ubiquity/everystockphoto.html Everystockphoto.com]: Search for images at everystockphoto.com

[http://widgets.bootsnall.com/ubiquity/shopping-search.html Shopping.com]: Search for products and compare prices at Shopping.com

[http://mika.lepisto.com/ubiquity-commands-160.html Ubiquity Commands by Mika]: Random commands including Everystockphoto.com and Shopping.com referenced above.

[http://www.ubiqcmds.co.nr issi_noho's (and others) commands]: torrentz.com and more soon. Submit your command here.

[http://www.thecompgeek.info/ubiquity/ CyberPrime's Commands]: SearchMe.Com, demonoid, about:commands and much more to come

[http://enobrev.info/ enobrev's commands]: php and html (with auto-completion)

[http://swieskowski.net/verbs/ swies's commands]: dog, clock, msdn

[http://foyrek.com/ubi.html Abi's commands]

[http://erikvold.com/tools/ubiquity/index.cfm Erik Vold's Commands]

[http://dietrich.ganx4.com/mozilla/ubiquity.html Dietrich's commands]

[http://www.gilbertpellegrom.co.uk/2008/08/27/my-ubiquity-commands/ Gilbert's commands]: date, time-12, time-24

[http://www.bjtitus.net/ubiquity/ Brandon's Commands]: FriendFeed

[http://www.fuzzhead.com/ubiquity.html Fuzzhead's Commands]: What's My IP?

[http://lokonline.com/ip/ubiq.html Improved IP address retrieval] Should work for ipv6 too.

[http://sites.google.com/site/ubiquitycommands/ Whatthechuck's commands]: validate (W3C markup validator), vimeo

[http://npattison.com/ubiquity/ Nickworks's commands]: Seeqpod, PHP.net

[http://aufrank.net/ubiquity/ aufrank's commands]: gfl, urej

[http://mysite.verizon.net/zaduma/ calhoun_ftw's commands]: Embiggen TinyURL replacer adaption, newegg, pirate bay, many more, releasing new always.

[http://www.mzzt.net/ubiq.html mzzt.net commands]: remove/replace selection, detach tab to new window, open chromeless window

[http://ubiquity.skumleren.net FreakCERS's commands]: latex

[http://www.satf.se/page/ubiquity-satf-se-s-commands-for-you pihl's commands]: <blink>, jaen, fix-all-problems, last.fm

[http://web.me.com/yaztromo/rot13-ubiq.html Yaz's Commands]: rot13

[http://hoffstein.net/ubiquity hoffstein's commands]: stock-quote, stock-chart

[http://nocturne.net.nz/verbs Bayard's commands]: WoWhead, WoW Armoury, BBCode

[http://grantrules.com/ubiquity Grant's commands]: Facebook, Lorem Ipsum generator, MD5/Sha1 hashes, Penis flood, What.cd artist/torrent search, UPS/USPS/FedEx tracking

[http://www.gfx-fr.com/ubiquity/ Setsuna666's commands]: Amazon Canada

[http://www.yalazi.org/ubiquity/list.html Onur Yalaz?'s commands]: kissalt, bugmenot

[http://labs.vunite.com/vubiqs/verbs.php vunite's commands]: goto, shorten, craigslist

[http://common-lisp.net/project/lifp/ubiquity/ Timofei Shatrov's commands]: clhs, myip, urban-dictionary-search, sharebee-download

[http://jimmahdigital.com/ubiq/ Jim's commands]: add-to-reader

[http://www.phoque.de/projekte/ubiquity/ phoque.de]: Add marked text to your blog

[http://www.srobbin.com/ubiquity-commands/ srobbin.com]: whatismyip

[http://tim.sorbera.googlepages.com/ubiquity.html Mini-Geek's commands]: homestar-runner-wiki, starcraft-wiki, tniv-bible-passage, tniv-bible-word, webster-dictionary, webster-thesaurus, open-url, ign, and fileshack

[http://www.geero.net Geero's commands]: Last.fm track search, Bible Gateway ESV URL builder

[http://www.jasonsmith.ca/articles/ubiquity_by_mozilla_labs amazon-search-all]: Search all items on [http://www.amazon.com Amazon.com]

[http://www.mikedeboer.nl Mike's commands]: mail (uses mailto: urls)

[http://www.bpeers.com/ubiq/ bpeers.com]: ticker (preview or paste a stock quote and its change); bling (currency conversion in google syntax)

[http://static.al3x.net/ubquity.html]: bit.ly, Instapaper, Soup.io, Google Reader subscribe, Twitter Search, Yep, zap CSS

[http://kollektive.com/ubiquity/ kollektive]: links - converts non-marked up text/html which contains urls and email addresses into proper anchor tags. Works within html pages, and in rich text editing fields (eg. rich text editing in GMAIL)

[http://www.cse.cuhk.edu.hk/~gli/ubiquity.html Xatan's ubiquity commands]: google scholar, xunlei(??), baidu(??), douban(??), verycd, google news, dict.cn(??), mininova, dictionary.hm (detailed english explanation)

[http://www.acarlos.com.br/ubiquity/ TV Globo Video Search]: searches for TV Globo and GloboSat videos (Brazil).

[http://v0xel.ubuntusrbija.org/2008/08/31/mozilla-ubiquity-i-b92-mape-srbije/ sr-map]: Searches for street names and shows them on a map. Works for couple of cities in Serbia.

[http://www.geocities.com/skyhopper88/ Skyhopper88's Commands] Several Search Commands, edit of Gmail script below for .1.1

[http://17th.name/wp-content/uploads/2008/09/fanfou.html Alex's fanfou command]: post to fanfou (??)

[http://unplugd.com/enblogd Samps's command collection]: eBay-Au, Ubuntu-WiKi, Skweezer, Wapedia, PHP function search

[http://test.fathomthat.org/ubiquity/evav.html Evilavatar]: Search Evilavatar for new posts containing your search term

[http://icecreamfactory.freehostia.com/ubiquity/ I.C.E.C.R.E.A.M COMMANDS]: directions, reverse-lookup, googlism

[http://www.geocities.com/ubiquities1 Sieglinde's commands]: babylon,leo,quote,reverse-telephone

[http://www.objectforward.com/ubiquity/ objectforward's commands]:
dictionary - simple command to use dictionary.reference.com for word look up.
thesaurus - uses thesaurus.reference.com for similar word look up.
I just like this better than the default 'define' command. Enjoy!

[http://updates.versionone.com/ubiquity/ VersionOne]: A command set for users of the VersionOne agile project management suite.

[http://craxy.bplaced.de/prog/ubiquity/ find commands]: Commands to control the firefox search (ctrl+f)

= Pre 0.1 Style Commands (Now Broken) =

# Quote text for BB-style forums. [http://www.gialloporpora.netsons.org/ubiquity/index.php?command=quotebb Quotebb.js]
# Quotes HTML entities in your selection. [http://www.gialloporpora.netsons.org/ubiquity/index.php?command=quotehtml quotehtml.js]
# Opens Gmail in a new tab, as well as showing you the last couple of new messages in the preivew. [http://ubiquity-firefox.googlegroups.com/web/ubiquity_gmail.js?gda=gHCQx0IAAAD_mC6ocghADlnwgKtOZarHy0pz4L1zdfNBZQ-WVQEtDWG1qiJ7UbTIup-M2XPURDThhrjtatuGnhW3da2gcLyrMQ4HhOIVlic7wv2V2HiqYg Gmail.js]
#Let's you Twitter from anywhere. This command has been moved into Ubiquity core. [http://theunfocused.net/moz/ubiquity/verbs/twitter.js Twitter.js]
#Another micro-blogging service like Twitter/Pounce/etc., but open source Essentially identical code to Twitter+Ubiquity above, except for renaming of constants and web addresses [http://ubiquity-firefox.googlegroups.com/web/identica%20(2).js?gda=4oc_PEkAAACqaO7Aax4IB5JX_WYSl8iOrBnsuQS45ejhBtvVuEfs-xpD7Q4I70bg7A2QUTeiVCyg9p4rhRQ_Rj874eUFNZ-HhAioEG5q2hncZWbpWmJ7IQ identica(2).js]
#[http://www.gialloporpora.netsons.org/ubiquity/diggthis.js DiggThis.js]
# Converts your selection to lower case. [http://www.gialloporpora.netsons.org/ubiquity/index.php?command=tolower tolower.js]

Labs/Ubiquity/Ubiquity Command Suggestions

2009-02-27T17:35:44Z

Endolith: /* Finished Commands */

Many of the commands suggested on this page have already been implemented, either by us or by third parties. Please take a look at [https://labs.toolness.com/ubiquity-herd/all-feeds/ | The Herd's command feed index] to see what commands other people have implemented. You may find what you're looking for there!

Back to [[Labs/Ubiquity]].

==Interesting Commands ==

These commands are either extremely useful to everyone (likely to be included as a builtin command) or they push the boundaries of what Ubiquity can do.

* Search the Herd for new Ubiquity commands directly using Ubiquity without having to physically navigate to the site.
* Commands for all of the menu items (so that I never have to reach for the mouse to menu again). Sandro mentioned this recently.
* Program launcher (When in Chrome, JS can launch other applications)
* "cmd" command to pass selected text to the command line, i.e. "cmd wget" would pass the selected text to the wget function via the cli.
* Upload code to pastebin (useful for sharing commands from the command-editor)
* Integration with webchuck extension (with the ability to view webchunks in the preview).
* BlueOrganizer (be inspired by this addon and it's somewhat semantic knowledge)
* Graphing data (currently, only sparklines are supported). Would be nice to plot bar graphs and pie charts of things like countries by GDP from Wikipedia or browser usage on my website. There's a lot to think about here but this could potentially become one of the best features of Ubiquity.
* Task-specific tab grouping. Allow for opening and closing a set of tabs all at once. The key question here is how to add tabs to groups using Ubiquity.

==Search Commands==
*Creative Commons: Find something in CC
*Wikipedia in spanish: (or use it in another languages)
*Bookmarklet command; execute any bookmarklet via the keyboard.(This could include normal bookmarks something like quick dial with the keyboard)
*Map contact command, a command to get the location(s) of a contact from your contact list.( map-contact (name) )
* Google site search multiple urls in selection. You would select a block of text containing multiple urls, and be able to search them all simultaneously for any given text.
** Is this even possible? What is the format? "site:mozilla.org,wikipedia.org test"? "site:mozilla.org site:wikipedia.org test"?
* Flickr search (a [http://194.95.111.244/%7Ecountzero/scripts/_myImageFlow/ coverflow-like preview] would be awesome)
* last.fm search with preview (a first attempt has been made [http://www.geero.net/ here])
* Google Image Search with preview
** Built-in image-search command does this, no?
* Google Sets (part of Google labs) to give related terms based on user input
* More specific Google searches, like google video search on 'video', and google definition search type "define:mozilla" into google.
* A search for the Gawker sites eg: Gizmodo, Lifehacker, etc...
* a command to find the largest number in a given tab/present page
* A search for books by ISBN number for availability in libraries of your choice. Use the [http://en.wikipedia.org/wiki/Special:BookSources/ 'Book sources'] by wikipedia to find it. To find the book with ISBN number 1871890306 in SF, you Ubiq "ISBN 1871890306 in San Francisco", or if you are in San Francisco, you can type "ISBN 1871890306 here", using your geo-location by ip attached to the [http://labs.toolness.com/trac/ticket/179 magic word 'here'], which I believe will be part of Ubiq 0.2. Integration with maps in a later stage? Discuss [http://getsatisfaction.com/mozilla/topics/book_source_your_isbn_numbers_through_ubiquity here].
* One command should be able to launch several searches on different sites in different tabs. It worked before, with several Utils.openUrlInBrowser's, but 0.1.1 broke it.
* Froogle search ([http://stanford.edu/~marce110/verbs/froogle-search.html This] works pretty well for now, but it's messy and would break if Google changed the format of the search results.)
* search google calendar
* taking the name of a television show, search for the show's schedule and add that schedule to google calendar
* A command that searches the web for a picture similar to one selected. using similar pixel arraignment to find pictures of better resolution or less cropped than one you might find roaming randomly.
** [http://blogs.msdn.com/livesearch/archive/2008/12/01/using-images-to-find-other-images.aspx Microsoft Live Search can do this]
* A image cover flow or even just something as simple as a image viewer. Also it should be able to add images into e-mails like the maps.
* Would love to see a search function for Calorie King to look up Nutrition Fact tables for foods ([http://is.gd/euXv like this one]).
* A search function for XHTML entities (maybe looking like [http://www.digitalmediaminute.com/reference/entity/index.php this]?) would be awesome. Not sure what auto-complete would look like for this....
* A function where you can highlight a text and then add additional text to that in ubiquity. For example I highlight a bands name on wiki then open Ubiquity and add a song name and then search on youtube.
*A search function for custom search command adding.
For example, allowing a user to search [input] using www.ffxiclopedia.org's main search [input] by setting "ffxi" command to it.

==Program Integration==
* Goto command for navigating the web quick and easy but I want it in the core.
* Search command (allows you to search for text in any open tab, and then navigate you there)
* Flock stuff (be inspired by whatever seems to be actually useful in Flock)
** Especially nice if it could integrate with existing application launchers (ie: Quicksilver, Launchy, etc)
* Ability to take snapshots of the current window
* Queries for places datastores, rendering in plain html blue links (Beltzer showed me a little js console script that is a fine starting point).
** tag:(hci gestuers)
** site:google date:yesterday show:clicks
** starred intitle:Concept
* Integrate with Thunderbird, Sunbird, Songbird and other Mozilla software
* Allow for commands to be treated as content/arguments for other commands ie: email {map Washington DC} to myfriend@gmail.com would open up an email box to friend1 with a map of DC in the content pane
* clone of email command for Gajim/Pidgin/Psi/Adium...
* Integration with Instant Messenger clients (AIM, Pidgin, Trillion, etc) to allow inserting content into a message for a particular contact ie 'IM this to John'
* Idea:: have a very, very small program run on start up, that detects when the key combination is pressed and will launch Ubiquity. After Ubiquity is dismissed, it will return to its original state.
* In Firefox, "Bookmark this" & "Create bookmark folder <data>"
* For Linux, allow users and other commands to be sent to the terminal...eg. IF you had selected text and wanted to open in gedit, ubiquity would tell the terminal to open gedit then paste in text..etc
* Ability to select the address-bar. I.e. "Select-address" would jump to the address-bar and highlight it.

==Tools==
* Annotate web pages and then share those annotations (perhaps using google notebook?)
* Close unrelated tabs: similar to close all related tabs
* Download manager - A text based download manager like wget on linux
* Related articles and images, possibly using Zemanta like [https://addons.mozilla.org/en-US/firefox/addon/7571 this plugin].
* Replace words in selected text (optional: regular expressions)
* Save current site into a PDF file
** "convert" command already does this
* Save page as... "Web Page, complete" to a pre-specified folder
* Save selection/highlighted text to a file in a pre-specified location
* Spell checker - any text, not just form fields
* Related to spell checker - take highlighted text, pass it through any number of online dictionaries, and let user select which word to use as replacement.
* Status message editor - Easily modify status and/or status message on popular IM protocols
* Perhaps "convert 8pm australian time to my time" where my timezone could automatically be obtained from CmdUtils.getLocation()
* 'Tag' function:
** Auto-complete from current tags list would be excellent
** Needs to handle multiple, comma-separated tags, better. Currently adds the comma to the tag name (eg. 'tag snacks, quick-meals' creates a new tag called "snacks,")
* 'Undo' function should work on in-page replacements (eg. translating highlighted text or inserting a map into page)
* Upload selected image to [http://tinypic.com tinypic] or the like
* Disable "window.print()" API for all pages, or replace it with a less intrusive variant (toast notification?)
* Command Creator From Forms: Kind of like how you can create keyword searches by right clicking any search box, but you would be able to right-click any form from any search or web publish forms and select "Create Ubiquity Command..." which pops a box where you say the the command keyword
* Add a domain (current domain as default) to cookie whitelist
* Add a thesaurus search function
** http://www.zacharyspencer.com/2008/09/my-first-ubiquity-command/
* Restart Firefox
** Built-in "restart" command does this
* Download instead of opening URL
* The ability to Edit existing/installed commands. I.E. "edit-command define" would search for an installed "define" command and open the source in the command-editor.
* The ability to bookmark a page and bypass the [ok/cancel] dialog box so that you can bookmark related tabs all at once.

==Site Integration==
*Forum (BBCode) formatting
*Youtube: Highlight a youtube link and embed the video. Could be used with other sites as well.
* Blogger:
** 'blog' function, to create a new blog post from selected text
*Command for [http://www.mytextfile.com MyTextFile] such as, "note/textfile (text)." It should auto-save so you never leave Ubiquity, unless, opening a new tab is necessary. Very similar to how email works now.
* Google Calendar:
**ability to add more information to a calendar appointment such as location (perhaps signaled by @ ), calendar choice ( [ ] ), improved date parsing (you could say next Wednesday, and it could figure it out, maybe like [http://www.datejs.com/ DateJS]).
**ability to get a preview of my next 10 calendar entries.
** access HTTPS version of calendar, perhaps with 'add-to-scalendar' and 'check-scalendar'
* Gmail:
** Add contact, from a selected text to your contact list in gmail.
*** Add a contact group (and contacts if needed) from the emails list in a received email (all cc'ed people, including the sender, excluding yourself), or from a list of email address'.
** Gmail labels, alphabetical lookup from available labels. Code possibly similar to the greasemonkey script [http://blog.persistent.info/2007/11/macros-for-new-version-of-gmail.html macros] for gmail.
* Google Maps -
** when a google map image is inserted into a form, the image should have a link to the map on the google map site. e.g.: http://maps.google.com/maps?f=q&hl=en&geocode=&q=Budapest,+Hungary&ie=UTF8&z=11&iwloc=addr
** Google Directions search, perhaps separating locations with a semicolon if Ubiquity doesn't understand multiple word arguments.
** Route information
* Internationalisation (google.co.uk, ebay.co.uk. etc)
** weather command in Celsius
** localize verbs (and their parameters: 01/09 = 1st September in some country)
** "map" command needs to be country-specific (maps.google.com.xx)
* Flickr integration (ability to inject pictures/slideshows and post found images to Flickr)
* More advanced twitter integration (a command to view last x messages from a specific friend and another to view your recent friends timeline)
* Blog integration (select a chunk of text or an image and then blog about it in your favorite blog software)
* Fly command (possibly using [http://tripeedo.com/ Tripeedo]'s built-in natural language search and the site's preview or the Kayak API) to make booking flights easier
* Digg (see Sandro's [http://ubiquity-firefox.googlegroups.com/web/diggthis.js diggthis command])
* Reddit/Mixx
* Del.icio.us (e.g. "delic this" or "delic this with tag1 tag2 tag3")
* Turn referencing friend feed comments and tweets on a page (defaulted to the current page) into page annotations via command "show conversations"
* Integration with Jaiku, Plurk, Pownce, and other microblogging services (not only with Twitter)
* Integration with Google Docs and Google Notebook
* Command to send selected text to tinypaste.com and/or <strike>shorttext.com</strike> ([http://shortText.com/ Commands 'shorttext', 'longtext'] now available), pastebin.com, cl1p.net etc.
* Subscribe to current site's feed via Google Reader or other RSS reader
* Add to Google Bookmarks
* Easily control [http://www.bitlet.org BitLet.org]
* Add torrents with [http://www.azureuswiki.com/index.php/HTML_WebUI Azureus' HTML WebUI]. => this can be done with Greasemonkey already
* Geotag flickr photos easily (see [http://labs.sumaato.net/tools/flickr_geocode_bookmarklet/ Localize Bookmarklet])
* Take highlighted thread, and paste it in a forum. Because of the amount of forums, it might be better to just have a template for each forum type.
* Evernote command (post this page/text to evernote) suggested by Ben [http://groups.google.com/group/ubiquity-firefox/browse_thread/thread/68d7f5d7f817c4d5?hl=en here]
* Adobe Buzzword integration
* tempomail / jetable (temp mail address) integration. Implemented. See [http://gist.github.com/11261 Jetable]
* Horde email/calendar
* SMS Messaging. Text-message content to a contact or phone number. Could integrate with an existing service such as: http://smseverywhere.com/send.htm
* Set tv recording. For those people using mythtv / myth* or a TiVo with a web front-end, if you saw a show on some web site, like tvrage or any channel that shows tv-listings, highlight the show, and say 'record this'. This would probably be very dependent on your specific web front-end / TVR hardware.
*integrate into MySpace. command such as "send this to (myspace contact): (selected text or image, maybe even if your on youtube, it will automatically imbed.)" Another could be "set headline as (selected text or input)"
* Integrate with [http://www.squirrelmail.org/ SqirrelMail]
* Integrate with [http://roundcube.net/ RoundCube Mail]
* Integrate with [http://sourceforge.net/projects/scuttle/ Scuttle Bookmarks]
* Integrate with [http://webcalendar.sourceforge.net/ WebCalendar]
* Integrate with [http://www.rememberthemilk.com/ Remember The Milk]. Add tasks, get list of tasks, mark tasks as completed, etc. They have a really rich API. (Adding tasks is done: [http://garyhodgson.com/ubiquity/rtm.html here], with a more advanced version [http://garyhodgson.com/ubiquity/rtm-wip.html in progress].)
* Integrate with [http://www.toodledo.com/ Toodledo] in a similar way to that described for RTM
* [http://www.facebook.com Facebook] status setting-resetting integration. Ping.fm has been implemented but there are users (like me) that prefer to use only one social networking site, hence they don't need a ping.fm account. (already done [http://home.comcast.net/~captainbeah/ubiquity/facebook/ here])
* Integrate with [http://www.me.com/ MobileMe] to allow similar email and calendar editing integration as for the Google equivalents (GMail etc.)
* Integrate with [http://www.ryanair.com/ Ryanair] to allow searching for flights using Ubiquity.
* Subscribe with Bloglines
* Integrate with Google Apps (Gmail, Calendar) [http://www.google.com/apps/] to allow using the standard commands

==Extension Integration==
* PasswordMaker: http://passwordmaker.org/
* BlueOrganizer (be inspired by [https://addons.mozilla.org/en-US/firefox/addon/3481 this addon] and it's somewhat semantic knowledge)
* Take inspiration from [https://addons.mozilla.org/en-US/firefox/addon/1407 Clipmarks]
* Firebug integration, inspect DOM-Reference, show firebug net panel
* Media player control similar to [https://addons.mozilla.org/en-US/firefox/addon/219 FoxyTunes]
* AnyColor integration -- https://addons.mozilla.org/en-US/firefox/addon/6991
* Faviconize -- A command called Fav [open tab] to change it's state from showing/hiding title
* Commands for Screen grab! extension
* Undo Closed Tabs Button feature like the extension of that name. (Note: this is built into Firefox 3.0, no need for this extension anymore)
* Adblock Plus integration, along with NoScript.
* Ability to inject Webslices, for use with Webchunks.
* Fast Dial integration
* Overwrite the window.print command with a less intrusive UI. It would instead pop a notification/toaster ("this site wants to print itself. _Print_").
** What does this have to do with Ubiquity? Sounds like something for Bugzilla.
* Greasemonkey integration: "greasemonkey-edit <userscript>". It would autocomplete the userscript name based on the list of installed userscripts.
* Cool iris functionality with a image flow.

==Finished Commands==
* [http://shortText.com/ shortText.com] done. Create a URL of any selected text by using command 'shorttext' or expand a shortText URL to its full content by using command 'longtext'
* [http://www.google.com/sitesearch/ Google Site Search] integration. (Example: "search komplett.ie for cpu coolers") [http://mysite.verizon.net/zaduma/ Done]
* Metacritic (metacritic.com) review searching - [http://mysite.verizon.net/zaduma/ Done] [http://www.endolith.com/ubiquity_commands.html this version has ability to choose between example.org, subdomain.example.org, etc.]
** <tt>google-here <text></tt>: site-search on current site (without typing it explicitly) => ([http://groups.google.com/group/ubiquity-firefox/browse_thread/thread/5c2c80df1c61d4f8 Done])
* Torrent search [http://mysite.verizon.net/zaduma/ Done]
* Reveal the exact URL-s behind tinyurl-s (see [http://ghill.customer.netspace.net.au/embiggen/ Embiggen Bookmarklet]) [http://mysite.verizon.net/zaduma/ Done]
* BugMeNot lookup for current page [http://www.geocities.com/lemming4242 Done]
* Open command (select multiple links, then open them all in tabs) [http://www.geocities.com/lemming4242/ Done]
* An online bible service command. [http://tim.sorbera.googlepages.com/ubiquity.html Done]
* A command to open a selected URL. [http://tim.sorbera.googlepages.com/ubiquity.html Done]
* Twitter Search - [http://gist.github.com/7594 Done] but could benefit from a sexier UI
* Random number generator. Floating point value with input of the following type: random lower-val higher-val
** Example: Random 0 1; Gives 0.252
** Example: Random 1 100; Gives 275.840
** [http://ubiquitously.org/forum/viewtopic.php?f=4&t=12 Done]
* Go command (for switching between tabs by name) (achieved by the "tab" command builtin to Ubiquity)
* Reopen an existing tab in a new tab. Sometimes you want to search for a new topic (in Wikipedia for example), and you have to re-open a new tab, then copy and paste the current url. Why not have a "re-open" command that lets you create a new tab, and copy the currently opened page over to it? (Alt+D > Alt+Enter currently does this. necessary?) (No. Did it anyways.) [http://ubiquitously.org/forum/viewtopic.php?f=5&t=22 Done]
* Currency conversion [http://ubiquitously.org/forum/viewtopic.php?f=4&t=25 Done]
* Unit conversion [http://ubiquitously.org/forum/viewtopic.php?f=4&t=25 Done (Same as above)]
* Stock quotes [http://ubiquitously.org/forum/viewtopic.php?f=4&t=26 Done]
* A "view source" for Ubiq commands. For example, "view-source link-to-wikipedia" => [https://wiki.mozilla.org/Labs/Ubiquity/Ubiquity_0.1.1_Release_Notes available] in Ubiq 0.1.1, although not as a command.
* Link finder (like the "link-to-wikipedia" command but then, instead of inserting a link to wikipedia, allow the user to find the link from history/bookmarks. This would save a lot of excess work because at the moment, to insert a link, you have to open up a new tab, find the page you want to link to, copy the address and then, go back to add the link) => try [http://blog.monstuff.com/archives/000343.html insert-link]
* Command that takes each search plugin/provider you have in the search-bar (by default, right of the locationbar in IE7 & FF2 & 3, plus more), and turns it into a command you can use. Thus, having search plugin/providers at your fingertips in ubiquity, and adding a search plugin/provider command is just as easy as using already created functionality; This could either be done in the underlying code of Ubiquity, or maybe have it so that the command is done as "Search <Plugin/Provider> <Terms>
** I'm a moron..I actually had a command that did this.[http://theunfocused.net/moz/ubiquity/verbs/?cmd=search]
** Dup: Integration of your installed Firefox search engines.
* Timezone converter - something like "get time in australia" ([https://wiki.mozilla.org/Labs/Ubiquity/Commands_In_The_Wild#Time Done])
* Ping.fm - can potentially replace twitter and facebook-status commands ([http://waleed.doubleudesigns.com/2008/08/ubiquity-and-pingfm/ Done])
* Mibbit IRC (mibbit [server] [optional:channels]) ([http://scguy318.freeshell.org/Mibbit%20Ubiquity%20Script.html Done])
Can anyone write a command that decodes 2D barcodes in images on a web page?

-I am working on a 2D barcode translator now. I have a standard barcode reader command working: http://devstatus.com ~ matt

*I just finished a simple Woot checker that goes to the "Want One" page on enter: [http://gist.github.com/41227 Woot]
<nowiki>Insert non-formatted text here</nowiki>

Labs/Ubiquity/Ubiquity Command Suggestions

2009-02-27T17:33:55Z

Endolith: /* Finished Commands */

Many of the commands suggested on this page have already been implemented, either by us or by third parties. Please take a look at [https://labs.toolness.com/ubiquity-herd/all-feeds/ | The Herd's command feed index] to see what commands other people have implemented. You may find what you're looking for there!

Back to [[Labs/Ubiquity]].

==Interesting Commands ==

These commands are either extremely useful to everyone (likely to be included as a builtin command) or they push the boundaries of what Ubiquity can do.

* Search the Herd for new Ubiquity commands directly using Ubiquity without having to physically navigate to the site.
* Commands for all of the menu items (so that I never have to reach for the mouse to menu again). Sandro mentioned this recently.
* Program launcher (When in Chrome, JS can launch other applications)
* "cmd" command to pass selected text to the command line, i.e. "cmd wget" would pass the selected text to the wget function via the cli.
* Upload code to pastebin (useful for sharing commands from the command-editor)
* Integration with webchuck extension (with the ability to view webchunks in the preview).
* BlueOrganizer (be inspired by this addon and it's somewhat semantic knowledge)
* Graphing data (currently, only sparklines are supported). Would be nice to plot bar graphs and pie charts of things like countries by GDP from Wikipedia or browser usage on my website. There's a lot to think about here but this could potentially become one of the best features of Ubiquity.
* Task-specific tab grouping. Allow for opening and closing a set of tabs all at once. The key question here is how to add tabs to groups using Ubiquity.

==Search Commands==
*Creative Commons: Find something in CC
*Wikipedia in spanish: (or use it in another languages)
*Bookmarklet command; execute any bookmarklet via the keyboard.(This could include normal bookmarks something like quick dial with the keyboard)
*Map contact command, a command to get the location(s) of a contact from your contact list.( map-contact (name) )
* Google site search multiple urls in selection. You would select a block of text containing multiple urls, and be able to search them all simultaneously for any given text.
** Is this even possible? What is the format? "site:mozilla.org,wikipedia.org test"? "site:mozilla.org site:wikipedia.org test"?
* Flickr search (a [http://194.95.111.244/%7Ecountzero/scripts/_myImageFlow/ coverflow-like preview] would be awesome)
* last.fm search with preview (a first attempt has been made [http://www.geero.net/ here])
* Google Image Search with preview
** Built-in image-search command does this, no?
* Google Sets (part of Google labs) to give related terms based on user input
* More specific Google searches, like google video search on 'video', and google definition search type "define:mozilla" into google.
* A search for the Gawker sites eg: Gizmodo, Lifehacker, etc...
* a command to find the largest number in a given tab/present page
* A search for books by ISBN number for availability in libraries of your choice. Use the [http://en.wikipedia.org/wiki/Special:BookSources/ 'Book sources'] by wikipedia to find it. To find the book with ISBN number 1871890306 in SF, you Ubiq "ISBN 1871890306 in San Francisco", or if you are in San Francisco, you can type "ISBN 1871890306 here", using your geo-location by ip attached to the [http://labs.toolness.com/trac/ticket/179 magic word 'here'], which I believe will be part of Ubiq 0.2. Integration with maps in a later stage? Discuss [http://getsatisfaction.com/mozilla/topics/book_source_your_isbn_numbers_through_ubiquity here].
* One command should be able to launch several searches on different sites in different tabs. It worked before, with several Utils.openUrlInBrowser's, but 0.1.1 broke it.
* Froogle search ([http://stanford.edu/~marce110/verbs/froogle-search.html This] works pretty well for now, but it's messy and would break if Google changed the format of the search results.)
* search google calendar
* taking the name of a television show, search for the show's schedule and add that schedule to google calendar
* A command that searches the web for a picture similar to one selected. using similar pixel arraignment to find pictures of better resolution or less cropped than one you might find roaming randomly.
** [http://blogs.msdn.com/livesearch/archive/2008/12/01/using-images-to-find-other-images.aspx Microsoft Live Search can do this]
* A image cover flow or even just something as simple as a image viewer. Also it should be able to add images into e-mails like the maps.
* Would love to see a search function for Calorie King to look up Nutrition Fact tables for foods ([http://is.gd/euXv like this one]).
* A search function for XHTML entities (maybe looking like [http://www.digitalmediaminute.com/reference/entity/index.php this]?) would be awesome. Not sure what auto-complete would look like for this....
* A function where you can highlight a text and then add additional text to that in ubiquity. For example I highlight a bands name on wiki then open Ubiquity and add a song name and then search on youtube.
*A search function for custom search command adding.
For example, allowing a user to search [input] using www.ffxiclopedia.org's main search [input] by setting "ffxi" command to it.

==Program Integration==
* Goto command for navigating the web quick and easy but I want it in the core.
* Search command (allows you to search for text in any open tab, and then navigate you there)
* Flock stuff (be inspired by whatever seems to be actually useful in Flock)
** Especially nice if it could integrate with existing application launchers (ie: Quicksilver, Launchy, etc)
* Ability to take snapshots of the current window
* Queries for places datastores, rendering in plain html blue links (Beltzer showed me a little js console script that is a fine starting point).
** tag:(hci gestuers)
** site:google date:yesterday show:clicks
** starred intitle:Concept
* Integrate with Thunderbird, Sunbird, Songbird and other Mozilla software
* Allow for commands to be treated as content/arguments for other commands ie: email {map Washington DC} to myfriend@gmail.com would open up an email box to friend1 with a map of DC in the content pane
* clone of email command for Gajim/Pidgin/Psi/Adium...
* Integration with Instant Messenger clients (AIM, Pidgin, Trillion, etc) to allow inserting content into a message for a particular contact ie 'IM this to John'
* Idea:: have a very, very small program run on start up, that detects when the key combination is pressed and will launch Ubiquity. After Ubiquity is dismissed, it will return to its original state.
* In Firefox, "Bookmark this" & "Create bookmark folder <data>"
* For Linux, allow users and other commands to be sent to the terminal...eg. IF you had selected text and wanted to open in gedit, ubiquity would tell the terminal to open gedit then paste in text..etc
* Ability to select the address-bar. I.e. "Select-address" would jump to the address-bar and highlight it.

==Tools==
* Annotate web pages and then share those annotations (perhaps using google notebook?)
* Close unrelated tabs: similar to close all related tabs
* Download manager - A text based download manager like wget on linux
* Related articles and images, possibly using Zemanta like [https://addons.mozilla.org/en-US/firefox/addon/7571 this plugin].
* Replace words in selected text (optional: regular expressions)
* Save current site into a PDF file
** "convert" command already does this
* Save page as... "Web Page, complete" to a pre-specified folder
* Save selection/highlighted text to a file in a pre-specified location
* Spell checker - any text, not just form fields
* Related to spell checker - take highlighted text, pass it through any number of online dictionaries, and let user select which word to use as replacement.
* Status message editor - Easily modify status and/or status message on popular IM protocols
* Perhaps "convert 8pm australian time to my time" where my timezone could automatically be obtained from CmdUtils.getLocation()
* 'Tag' function:
** Auto-complete from current tags list would be excellent
** Needs to handle multiple, comma-separated tags, better. Currently adds the comma to the tag name (eg. 'tag snacks, quick-meals' creates a new tag called "snacks,")
* 'Undo' function should work on in-page replacements (eg. translating highlighted text or inserting a map into page)
* Upload selected image to [http://tinypic.com tinypic] or the like
* Disable "window.print()" API for all pages, or replace it with a less intrusive variant (toast notification?)
* Command Creator From Forms: Kind of like how you can create keyword searches by right clicking any search box, but you would be able to right-click any form from any search or web publish forms and select "Create Ubiquity Command..." which pops a box where you say the the command keyword
* Add a domain (current domain as default) to cookie whitelist
* Add a thesaurus search function
** http://www.zacharyspencer.com/2008/09/my-first-ubiquity-command/
* Restart Firefox
** Built-in "restart" command does this
* Download instead of opening URL
* The ability to Edit existing/installed commands. I.E. "edit-command define" would search for an installed "define" command and open the source in the command-editor.
* The ability to bookmark a page and bypass the [ok/cancel] dialog box so that you can bookmark related tabs all at once.

==Site Integration==
*Forum (BBCode) formatting
*Youtube: Highlight a youtube link and embed the video. Could be used with other sites as well.
* Blogger:
** 'blog' function, to create a new blog post from selected text
*Command for [http://www.mytextfile.com MyTextFile] such as, "note/textfile (text)." It should auto-save so you never leave Ubiquity, unless, opening a new tab is necessary. Very similar to how email works now.
* Google Calendar:
**ability to add more information to a calendar appointment such as location (perhaps signaled by @ ), calendar choice ( [ ] ), improved date parsing (you could say next Wednesday, and it could figure it out, maybe like [http://www.datejs.com/ DateJS]).
**ability to get a preview of my next 10 calendar entries.
** access HTTPS version of calendar, perhaps with 'add-to-scalendar' and 'check-scalendar'
* Gmail:
** Add contact, from a selected text to your contact list in gmail.
*** Add a contact group (and contacts if needed) from the emails list in a received email (all cc'ed people, including the sender, excluding yourself), or from a list of email address'.
** Gmail labels, alphabetical lookup from available labels. Code possibly similar to the greasemonkey script [http://blog.persistent.info/2007/11/macros-for-new-version-of-gmail.html macros] for gmail.
* Google Maps -
** when a google map image is inserted into a form, the image should have a link to the map on the google map site. e.g.: http://maps.google.com/maps?f=q&hl=en&geocode=&q=Budapest,+Hungary&ie=UTF8&z=11&iwloc=addr
** Google Directions search, perhaps separating locations with a semicolon if Ubiquity doesn't understand multiple word arguments.
** Route information
* Internationalisation (google.co.uk, ebay.co.uk. etc)
** weather command in Celsius
** localize verbs (and their parameters: 01/09 = 1st September in some country)
** "map" command needs to be country-specific (maps.google.com.xx)
* Flickr integration (ability to inject pictures/slideshows and post found images to Flickr)
* More advanced twitter integration (a command to view last x messages from a specific friend and another to view your recent friends timeline)
* Blog integration (select a chunk of text or an image and then blog about it in your favorite blog software)
* Fly command (possibly using [http://tripeedo.com/ Tripeedo]'s built-in natural language search and the site's preview or the Kayak API) to make booking flights easier
* Digg (see Sandro's [http://ubiquity-firefox.googlegroups.com/web/diggthis.js diggthis command])
* Reddit/Mixx
* Del.icio.us (e.g. "delic this" or "delic this with tag1 tag2 tag3")
* Turn referencing friend feed comments and tweets on a page (defaulted to the current page) into page annotations via command "show conversations"
* Integration with Jaiku, Plurk, Pownce, and other microblogging services (not only with Twitter)
* Integration with Google Docs and Google Notebook
* Command to send selected text to tinypaste.com and/or <strike>shorttext.com</strike> ([http://shortText.com/ Commands 'shorttext', 'longtext'] now available), pastebin.com, cl1p.net etc.
* Subscribe to current site's feed via Google Reader or other RSS reader
* Add to Google Bookmarks
* Easily control [http://www.bitlet.org BitLet.org]
* Add torrents with [http://www.azureuswiki.com/index.php/HTML_WebUI Azureus' HTML WebUI]. => this can be done with Greasemonkey already
* Geotag flickr photos easily (see [http://labs.sumaato.net/tools/flickr_geocode_bookmarklet/ Localize Bookmarklet])
* Take highlighted thread, and paste it in a forum. Because of the amount of forums, it might be better to just have a template for each forum type.
* Evernote command (post this page/text to evernote) suggested by Ben [http://groups.google.com/group/ubiquity-firefox/browse_thread/thread/68d7f5d7f817c4d5?hl=en here]
* Adobe Buzzword integration
* tempomail / jetable (temp mail address) integration. Implemented. See [http://gist.github.com/11261 Jetable]
* Horde email/calendar
* SMS Messaging. Text-message content to a contact or phone number. Could integrate with an existing service such as: http://smseverywhere.com/send.htm
* Set tv recording. For those people using mythtv / myth* or a TiVo with a web front-end, if you saw a show on some web site, like tvrage or any channel that shows tv-listings, highlight the show, and say 'record this'. This would probably be very dependent on your specific web front-end / TVR hardware.
*integrate into MySpace. command such as "send this to (myspace contact): (selected text or image, maybe even if your on youtube, it will automatically imbed.)" Another could be "set headline as (selected text or input)"
* Integrate with [http://www.squirrelmail.org/ SqirrelMail]
* Integrate with [http://roundcube.net/ RoundCube Mail]
* Integrate with [http://sourceforge.net/projects/scuttle/ Scuttle Bookmarks]
* Integrate with [http://webcalendar.sourceforge.net/ WebCalendar]
* Integrate with [http://www.rememberthemilk.com/ Remember The Milk]. Add tasks, get list of tasks, mark tasks as completed, etc. They have a really rich API. (Adding tasks is done: [http://garyhodgson.com/ubiquity/rtm.html here], with a more advanced version [http://garyhodgson.com/ubiquity/rtm-wip.html in progress].)
* Integrate with [http://www.toodledo.com/ Toodledo] in a similar way to that described for RTM
* [http://www.facebook.com Facebook] status setting-resetting integration. Ping.fm has been implemented but there are users (like me) that prefer to use only one social networking site, hence they don't need a ping.fm account. (already done [http://home.comcast.net/~captainbeah/ubiquity/facebook/ here])
* Integrate with [http://www.me.com/ MobileMe] to allow similar email and calendar editing integration as for the Google equivalents (GMail etc.)
* Integrate with [http://www.ryanair.com/ Ryanair] to allow searching for flights using Ubiquity.
* Subscribe with Bloglines
* Integrate with Google Apps (Gmail, Calendar) [http://www.google.com/apps/] to allow using the standard commands

==Extension Integration==
* PasswordMaker: http://passwordmaker.org/
* BlueOrganizer (be inspired by [https://addons.mozilla.org/en-US/firefox/addon/3481 this addon] and it's somewhat semantic knowledge)
* Take inspiration from [https://addons.mozilla.org/en-US/firefox/addon/1407 Clipmarks]
* Firebug integration, inspect DOM-Reference, show firebug net panel
* Media player control similar to [https://addons.mozilla.org/en-US/firefox/addon/219 FoxyTunes]
* AnyColor integration -- https://addons.mozilla.org/en-US/firefox/addon/6991
* Faviconize -- A command called Fav [open tab] to change it's state from showing/hiding title
* Commands for Screen grab! extension
* Undo Closed Tabs Button feature like the extension of that name. (Note: this is built into Firefox 3.0, no need for this extension anymore)
* Adblock Plus integration, along with NoScript.
* Ability to inject Webslices, for use with Webchunks.
* Fast Dial integration
* Overwrite the window.print command with a less intrusive UI. It would instead pop a notification/toaster ("this site wants to print itself. _Print_").
** What does this have to do with Ubiquity? Sounds like something for Bugzilla.
* Greasemonkey integration: "greasemonkey-edit <userscript>". It would autocomplete the userscript name based on the list of installed userscripts.
* Cool iris functionality with a image flow.

==Finished Commands==
* [http://shortText.com/ shortText.com] done. Create a URL of any selected text by using command 'shorttext' or expand a shortText URL to its full content by using command 'longtext'
* [http://www.google.com/sitesearch/ Google Site Search] integration. (Example: "search komplett.ie for cpu coolers") [http://mysite.verizon.net/zaduma/ Done]
* Metacritic (metacritic.com) review searching - [http://mysite.verizon.net/zaduma/ Done] [http://www.endolith.com/ubiquity_commands.html this version has ability to choose between example.org, subdomain.example.org, etc.]
* Torrent search [http://mysite.verizon.net/zaduma/ Done]
* Reveal the exact URL-s behind tinyurl-s (see [http://ghill.customer.netspace.net.au/embiggen/ Embiggen Bookmarklet]) [http://mysite.verizon.net/zaduma/ Done]
* BugMeNot lookup for current page [http://www.geocities.com/lemming4242 Done]
* Open command (select multiple links, then open them all in tabs) [http://www.geocities.com/lemming4242/ Done]
* An online bible service command. [http://tim.sorbera.googlepages.com/ubiquity.html Done]
* A command to open a selected URL. [http://tim.sorbera.googlepages.com/ubiquity.html Done]
* Twitter Search - [http://gist.github.com/7594 Done] but could benefit from a sexier UI
* Random number generator. Floating point value with input of the following type: random lower-val higher-val
** Example: Random 0 1; Gives 0.252
** Example: Random 1 100; Gives 275.840
** [http://ubiquitously.org/forum/viewtopic.php?f=4&t=12 Done]
* Go command (for switching between tabs by name) (achieved by the "tab" command builtin to Ubiquity)
* Reopen an existing tab in a new tab. Sometimes you want to search for a new topic (in Wikipedia for example), and you have to re-open a new tab, then copy and paste the current url. Why not have a "re-open" command that lets you create a new tab, and copy the currently opened page over to it? (Alt+D > Alt+Enter currently does this. necessary?) (No. Did it anyways.) [http://ubiquitously.org/forum/viewtopic.php?f=5&t=22 Done]
* Currency conversion [http://ubiquitously.org/forum/viewtopic.php?f=4&t=25 Done]
* Unit conversion [http://ubiquitously.org/forum/viewtopic.php?f=4&t=25 Done (Same as above)]
* Stock quotes [http://ubiquitously.org/forum/viewtopic.php?f=4&t=26 Done]
* A "view source" for Ubiq commands. For example, "view-source link-to-wikipedia" => [https://wiki.mozilla.org/Labs/Ubiquity/Ubiquity_0.1.1_Release_Notes available] in Ubiq 0.1.1, although not as a command.
* Link finder (like the "link-to-wikipedia" command but then, instead of inserting a link to wikipedia, allow the user to find the link from history/bookmarks. This would save a lot of excess work because at the moment, to insert a link, you have to open up a new tab, find the page you want to link to, copy the address and then, go back to add the link) => try [http://blog.monstuff.com/archives/000343.html insert-link]
* Command that takes each search plugin/provider you have in the search-bar (by default, right of the locationbar in IE7 & FF2 & 3, plus more), and turns it into a command you can use. Thus, having search plugin/providers at your fingertips in ubiquity, and adding a search plugin/provider command is just as easy as using already created functionality; This could either be done in the underlying code of Ubiquity, or maybe have it so that the command is done as "Search <Plugin/Provider> <Terms>
** I'm a moron..I actually had a command that did this.[http://theunfocused.net/moz/ubiquity/verbs/?cmd=search]
** Dup: Integration of your installed Firefox search engines.
* Timezone converter - something like "get time in australia" ([https://wiki.mozilla.org/Labs/Ubiquity/Commands_In_The_Wild#Time Done])
* Ping.fm - can potentially replace twitter and facebook-status commands ([http://waleed.doubleudesigns.com/2008/08/ubiquity-and-pingfm/ Done])
* Mibbit IRC (mibbit [server] [optional:channels]) ([http://scguy318.freeshell.org/Mibbit%20Ubiquity%20Script.html Done])
* <tt>google-here <text></tt>: site-search on current site (without typing it explicitly) => ([http://groups.google.com/group/ubiquity-firefox/browse_thread/thread/5c2c80df1c61d4f8 Done])
Can anyone write a command that decodes 2D barcodes in images on a web page?

-I am working on a 2D barcode translator now. I have a standard barcode reader command working: http://devstatus.com ~ matt

*I just finished a simple Woot checker that goes to the "Want One" page on enter: [http://gist.github.com/41227 Woot]
<nowiki>Insert non-formatted text here</nowiki>

Labs/Ubiquity/Ubiquity Command Suggestions

2009-02-27T17:30:48Z

Endolith: /* Extension Integration */

Many of the commands suggested on this page have already been implemented, either by us or by third parties. Please take a look at [https://labs.toolness.com/ubiquity-herd/all-feeds/ | The Herd's command feed index] to see what commands other people have implemented. You may find what you're looking for there!

Back to [[Labs/Ubiquity]].

==Interesting Commands ==

These commands are either extremely useful to everyone (likely to be included as a builtin command) or they push the boundaries of what Ubiquity can do.

* Search the Herd for new Ubiquity commands directly using Ubiquity without having to physically navigate to the site.
* Commands for all of the menu items (so that I never have to reach for the mouse to menu again). Sandro mentioned this recently.
* Program launcher (When in Chrome, JS can launch other applications)
* "cmd" command to pass selected text to the command line, i.e. "cmd wget" would pass the selected text to the wget function via the cli.
* Upload code to pastebin (useful for sharing commands from the command-editor)
* Integration with webchuck extension (with the ability to view webchunks in the preview).
* BlueOrganizer (be inspired by this addon and it's somewhat semantic knowledge)
* Graphing data (currently, only sparklines are supported). Would be nice to plot bar graphs and pie charts of things like countries by GDP from Wikipedia or browser usage on my website. There's a lot to think about here but this could potentially become one of the best features of Ubiquity.
* Task-specific tab grouping. Allow for opening and closing a set of tabs all at once. The key question here is how to add tabs to groups using Ubiquity.

==Search Commands==
*Creative Commons: Find something in CC
*Wikipedia in spanish: (or use it in another languages)
*Bookmarklet command; execute any bookmarklet via the keyboard.(This could include normal bookmarks something like quick dial with the keyboard)
*Map contact command, a command to get the location(s) of a contact from your contact list.( map-contact (name) )
* Google site search multiple urls in selection. You would select a block of text containing multiple urls, and be able to search them all simultaneously for any given text.
** Is this even possible? What is the format? "site:mozilla.org,wikipedia.org test"? "site:mozilla.org site:wikipedia.org test"?
* Flickr search (a [http://194.95.111.244/%7Ecountzero/scripts/_myImageFlow/ coverflow-like preview] would be awesome)
* last.fm search with preview (a first attempt has been made [http://www.geero.net/ here])
* Google Image Search with preview
** Built-in image-search command does this, no?
* Google Sets (part of Google labs) to give related terms based on user input
* More specific Google searches, like google video search on 'video', and google definition search type "define:mozilla" into google.
* A search for the Gawker sites eg: Gizmodo, Lifehacker, etc...
* a command to find the largest number in a given tab/present page
* A search for books by ISBN number for availability in libraries of your choice. Use the [http://en.wikipedia.org/wiki/Special:BookSources/ 'Book sources'] by wikipedia to find it. To find the book with ISBN number 1871890306 in SF, you Ubiq "ISBN 1871890306 in San Francisco", or if you are in San Francisco, you can type "ISBN 1871890306 here", using your geo-location by ip attached to the [http://labs.toolness.com/trac/ticket/179 magic word 'here'], which I believe will be part of Ubiq 0.2. Integration with maps in a later stage? Discuss [http://getsatisfaction.com/mozilla/topics/book_source_your_isbn_numbers_through_ubiquity here].
* One command should be able to launch several searches on different sites in different tabs. It worked before, with several Utils.openUrlInBrowser's, but 0.1.1 broke it.
* Froogle search ([http://stanford.edu/~marce110/verbs/froogle-search.html This] works pretty well for now, but it's messy and would break if Google changed the format of the search results.)
* search google calendar
* taking the name of a television show, search for the show's schedule and add that schedule to google calendar
* A command that searches the web for a picture similar to one selected. using similar pixel arraignment to find pictures of better resolution or less cropped than one you might find roaming randomly.
** [http://blogs.msdn.com/livesearch/archive/2008/12/01/using-images-to-find-other-images.aspx Microsoft Live Search can do this]
* A image cover flow or even just something as simple as a image viewer. Also it should be able to add images into e-mails like the maps.
* Would love to see a search function for Calorie King to look up Nutrition Fact tables for foods ([http://is.gd/euXv like this one]).
* A search function for XHTML entities (maybe looking like [http://www.digitalmediaminute.com/reference/entity/index.php this]?) would be awesome. Not sure what auto-complete would look like for this....
* A function where you can highlight a text and then add additional text to that in ubiquity. For example I highlight a bands name on wiki then open Ubiquity and add a song name and then search on youtube.
*A search function for custom search command adding.
For example, allowing a user to search [input] using www.ffxiclopedia.org's main search [input] by setting "ffxi" command to it.

==Program Integration==
* Goto command for navigating the web quick and easy but I want it in the core.
* Search command (allows you to search for text in any open tab, and then navigate you there)
* Flock stuff (be inspired by whatever seems to be actually useful in Flock)
** Especially nice if it could integrate with existing application launchers (ie: Quicksilver, Launchy, etc)
* Ability to take snapshots of the current window
* Queries for places datastores, rendering in plain html blue links (Beltzer showed me a little js console script that is a fine starting point).
** tag:(hci gestuers)
** site:google date:yesterday show:clicks
** starred intitle:Concept
* Integrate with Thunderbird, Sunbird, Songbird and other Mozilla software
* Allow for commands to be treated as content/arguments for other commands ie: email {map Washington DC} to myfriend@gmail.com would open up an email box to friend1 with a map of DC in the content pane
* clone of email command for Gajim/Pidgin/Psi/Adium...
* Integration with Instant Messenger clients (AIM, Pidgin, Trillion, etc) to allow inserting content into a message for a particular contact ie 'IM this to John'
* Idea:: have a very, very small program run on start up, that detects when the key combination is pressed and will launch Ubiquity. After Ubiquity is dismissed, it will return to its original state.
* In Firefox, "Bookmark this" & "Create bookmark folder <data>"
* For Linux, allow users and other commands to be sent to the terminal...eg. IF you had selected text and wanted to open in gedit, ubiquity would tell the terminal to open gedit then paste in text..etc
* Ability to select the address-bar. I.e. "Select-address" would jump to the address-bar and highlight it.

==Tools==
* Annotate web pages and then share those annotations (perhaps using google notebook?)
* Close unrelated tabs: similar to close all related tabs
* Download manager - A text based download manager like wget on linux
* Related articles and images, possibly using Zemanta like [https://addons.mozilla.org/en-US/firefox/addon/7571 this plugin].
* Replace words in selected text (optional: regular expressions)
* Save current site into a PDF file
** "convert" command already does this
* Save page as... "Web Page, complete" to a pre-specified folder
* Save selection/highlighted text to a file in a pre-specified location
* Spell checker - any text, not just form fields
* Related to spell checker - take highlighted text, pass it through any number of online dictionaries, and let user select which word to use as replacement.
* Status message editor - Easily modify status and/or status message on popular IM protocols
* Perhaps "convert 8pm australian time to my time" where my timezone could automatically be obtained from CmdUtils.getLocation()
* 'Tag' function:
** Auto-complete from current tags list would be excellent
** Needs to handle multiple, comma-separated tags, better. Currently adds the comma to the tag name (eg. 'tag snacks, quick-meals' creates a new tag called "snacks,")
* 'Undo' function should work on in-page replacements (eg. translating highlighted text or inserting a map into page)
* Upload selected image to [http://tinypic.com tinypic] or the like
* Disable "window.print()" API for all pages, or replace it with a less intrusive variant (toast notification?)
* Command Creator From Forms: Kind of like how you can create keyword searches by right clicking any search box, but you would be able to right-click any form from any search or web publish forms and select "Create Ubiquity Command..." which pops a box where you say the the command keyword
* Add a domain (current domain as default) to cookie whitelist
* Add a thesaurus search function
** http://www.zacharyspencer.com/2008/09/my-first-ubiquity-command/
* Restart Firefox
** Built-in "restart" command does this
* Download instead of opening URL
* The ability to Edit existing/installed commands. I.E. "edit-command define" would search for an installed "define" command and open the source in the command-editor.
* The ability to bookmark a page and bypass the [ok/cancel] dialog box so that you can bookmark related tabs all at once.

==Site Integration==
*Forum (BBCode) formatting
*Youtube: Highlight a youtube link and embed the video. Could be used with other sites as well.
* Blogger:
** 'blog' function, to create a new blog post from selected text
*Command for [http://www.mytextfile.com MyTextFile] such as, "note/textfile (text)." It should auto-save so you never leave Ubiquity, unless, opening a new tab is necessary. Very similar to how email works now.
* Google Calendar:
**ability to add more information to a calendar appointment such as location (perhaps signaled by @ ), calendar choice ( [ ] ), improved date parsing (you could say next Wednesday, and it could figure it out, maybe like [http://www.datejs.com/ DateJS]).
**ability to get a preview of my next 10 calendar entries.
** access HTTPS version of calendar, perhaps with 'add-to-scalendar' and 'check-scalendar'
* Gmail:
** Add contact, from a selected text to your contact list in gmail.
*** Add a contact group (and contacts if needed) from the emails list in a received email (all cc'ed people, including the sender, excluding yourself), or from a list of email address'.
** Gmail labels, alphabetical lookup from available labels. Code possibly similar to the greasemonkey script [http://blog.persistent.info/2007/11/macros-for-new-version-of-gmail.html macros] for gmail.
* Google Maps -
** when a google map image is inserted into a form, the image should have a link to the map on the google map site. e.g.: http://maps.google.com/maps?f=q&hl=en&geocode=&q=Budapest,+Hungary&ie=UTF8&z=11&iwloc=addr
** Google Directions search, perhaps separating locations with a semicolon if Ubiquity doesn't understand multiple word arguments.
** Route information
* Internationalisation (google.co.uk, ebay.co.uk. etc)
** weather command in Celsius
** localize verbs (and their parameters: 01/09 = 1st September in some country)
** "map" command needs to be country-specific (maps.google.com.xx)
* Flickr integration (ability to inject pictures/slideshows and post found images to Flickr)
* More advanced twitter integration (a command to view last x messages from a specific friend and another to view your recent friends timeline)
* Blog integration (select a chunk of text or an image and then blog about it in your favorite blog software)
* Fly command (possibly using [http://tripeedo.com/ Tripeedo]'s built-in natural language search and the site's preview or the Kayak API) to make booking flights easier
* Digg (see Sandro's [http://ubiquity-firefox.googlegroups.com/web/diggthis.js diggthis command])
* Reddit/Mixx
* Del.icio.us (e.g. "delic this" or "delic this with tag1 tag2 tag3")
* Turn referencing friend feed comments and tweets on a page (defaulted to the current page) into page annotations via command "show conversations"
* Integration with Jaiku, Plurk, Pownce, and other microblogging services (not only with Twitter)
* Integration with Google Docs and Google Notebook
* Command to send selected text to tinypaste.com and/or <strike>shorttext.com</strike> ([http://shortText.com/ Commands 'shorttext', 'longtext'] now available), pastebin.com, cl1p.net etc.
* Subscribe to current site's feed via Google Reader or other RSS reader
* Add to Google Bookmarks
* Easily control [http://www.bitlet.org BitLet.org]
* Add torrents with [http://www.azureuswiki.com/index.php/HTML_WebUI Azureus' HTML WebUI]. => this can be done with Greasemonkey already
* Geotag flickr photos easily (see [http://labs.sumaato.net/tools/flickr_geocode_bookmarklet/ Localize Bookmarklet])
* Take highlighted thread, and paste it in a forum. Because of the amount of forums, it might be better to just have a template for each forum type.
* Evernote command (post this page/text to evernote) suggested by Ben [http://groups.google.com/group/ubiquity-firefox/browse_thread/thread/68d7f5d7f817c4d5?hl=en here]
* Adobe Buzzword integration
* tempomail / jetable (temp mail address) integration. Implemented. See [http://gist.github.com/11261 Jetable]
* Horde email/calendar
* SMS Messaging. Text-message content to a contact or phone number. Could integrate with an existing service such as: http://smseverywhere.com/send.htm
* Set tv recording. For those people using mythtv / myth* or a TiVo with a web front-end, if you saw a show on some web site, like tvrage or any channel that shows tv-listings, highlight the show, and say 'record this'. This would probably be very dependent on your specific web front-end / TVR hardware.
*integrate into MySpace. command such as "send this to (myspace contact): (selected text or image, maybe even if your on youtube, it will automatically imbed.)" Another could be "set headline as (selected text or input)"
* Integrate with [http://www.squirrelmail.org/ SqirrelMail]
* Integrate with [http://roundcube.net/ RoundCube Mail]
* Integrate with [http://sourceforge.net/projects/scuttle/ Scuttle Bookmarks]
* Integrate with [http://webcalendar.sourceforge.net/ WebCalendar]
* Integrate with [http://www.rememberthemilk.com/ Remember The Milk]. Add tasks, get list of tasks, mark tasks as completed, etc. They have a really rich API. (Adding tasks is done: [http://garyhodgson.com/ubiquity/rtm.html here], with a more advanced version [http://garyhodgson.com/ubiquity/rtm-wip.html in progress].)
* Integrate with [http://www.toodledo.com/ Toodledo] in a similar way to that described for RTM
* [http://www.facebook.com Facebook] status setting-resetting integration. Ping.fm has been implemented but there are users (like me) that prefer to use only one social networking site, hence they don't need a ping.fm account. (already done [http://home.comcast.net/~captainbeah/ubiquity/facebook/ here])
* Integrate with [http://www.me.com/ MobileMe] to allow similar email and calendar editing integration as for the Google equivalents (GMail etc.)
* Integrate with [http://www.ryanair.com/ Ryanair] to allow searching for flights using Ubiquity.
* Subscribe with Bloglines
* Integrate with Google Apps (Gmail, Calendar) [http://www.google.com/apps/] to allow using the standard commands

==Extension Integration==
* PasswordMaker: http://passwordmaker.org/
* BlueOrganizer (be inspired by [https://addons.mozilla.org/en-US/firefox/addon/3481 this addon] and it's somewhat semantic knowledge)
* Take inspiration from [https://addons.mozilla.org/en-US/firefox/addon/1407 Clipmarks]
* Firebug integration, inspect DOM-Reference, show firebug net panel
* Media player control similar to [https://addons.mozilla.org/en-US/firefox/addon/219 FoxyTunes]
* AnyColor integration -- https://addons.mozilla.org/en-US/firefox/addon/6991
* Faviconize -- A command called Fav [open tab] to change it's state from showing/hiding title
* Commands for Screen grab! extension
* Undo Closed Tabs Button feature like the extension of that name. (Note: this is built into Firefox 3.0, no need for this extension anymore)
* Adblock Plus integration, along with NoScript.
* Ability to inject Webslices, for use with Webchunks.
* Fast Dial integration
* Overwrite the window.print command with a less intrusive UI. It would instead pop a notification/toaster ("this site wants to print itself. _Print_").
** What does this have to do with Ubiquity? Sounds like something for Bugzilla.
* Greasemonkey integration: "greasemonkey-edit <userscript>". It would autocomplete the userscript name based on the list of installed userscripts.
* Cool iris functionality with a image flow.

==Finished Commands==
* [http://shortText.com/ shortText.com] done. Create a URL of any selected text by using command 'shorttext' or expand a shortText URL to its full content by using command 'longtext'
* [http://www.google.com/sitesearch/ Google Site Search] integration. (Example: "search komplett.ie for cpu coolers") [http://mysite.verizon.net/zaduma/ Done]
* Metacritic (metacritic.com) review searching - [http://mysite.verizon.net/zaduma/ Done]
* Torrent search [http://mysite.verizon.net/zaduma/ Done]
* Reveal the exact URL-s behind tinyurl-s (see [http://ghill.customer.netspace.net.au/embiggen/ Embiggen Bookmarklet]) [http://mysite.verizon.net/zaduma/ Done]
* BugMeNot lookup for current page [http://www.geocities.com/lemming4242 Done]
* Open command (select multiple links, then open them all in tabs) [http://www.geocities.com/lemming4242/ Done]
* An online bible service command. [http://tim.sorbera.googlepages.com/ubiquity.html Done]
* A command to open a selected URL. [http://tim.sorbera.googlepages.com/ubiquity.html Done]
* Twitter Search - [http://gist.github.com/7594 Done] but could benefit from a sexier UI
* Random number generator. Floating point value with input of the following type: random lower-val higher-val
** Example: Random 0 1; Gives 0.252
** Example: Random 1 100; Gives 275.840
** [http://ubiquitously.org/forum/viewtopic.php?f=4&t=12 Done]
* Go command (for switching between tabs by name) (achieved by the "tab" command builtin to Ubiquity)
* Reopen an existing tab in a new tab. Sometimes you want to search for a new topic (in Wikipedia for example), and you have to re-open a new tab, then copy and paste the current url. Why not have a "re-open" command that lets you create a new tab, and copy the currently opened page over to it? (Alt+D > Alt+Enter currently does this. necessary?) (No. Did it anyways.) [http://ubiquitously.org/forum/viewtopic.php?f=5&t=22 Done]
* Currency conversion [http://ubiquitously.org/forum/viewtopic.php?f=4&t=25 Done]
* Unit conversion [http://ubiquitously.org/forum/viewtopic.php?f=4&t=25 Done (Same as above)]
* Stock quotes [http://ubiquitously.org/forum/viewtopic.php?f=4&t=26 Done]
* A "view source" for Ubiq commands. For example, "view-source link-to-wikipedia" => [https://wiki.mozilla.org/Labs/Ubiquity/Ubiquity_0.1.1_Release_Notes available] in Ubiq 0.1.1, although not as a command.
* Link finder (like the "link-to-wikipedia" command but then, instead of inserting a link to wikipedia, allow the user to find the link from history/bookmarks. This would save a lot of excess work because at the moment, to insert a link, you have to open up a new tab, find the page you want to link to, copy the address and then, go back to add the link) => try [http://blog.monstuff.com/archives/000343.html insert-link]
* Command that takes each search plugin/provider you have in the search-bar (by default, right of the locationbar in IE7 & FF2 & 3, plus more), and turns it into a command you can use. Thus, having search plugin/providers at your fingertips in ubiquity, and adding a search plugin/provider command is just as easy as using already created functionality; This could either be done in the underlying code of Ubiquity, or maybe have it so that the command is done as "Search <Plugin/Provider> <Terms>
** I'm a moron..I actually had a command that did this.[http://theunfocused.net/moz/ubiquity/verbs/?cmd=search]
** Dup: Integration of your installed Firefox search engines.
* Timezone converter - something like "get time in australia" ([https://wiki.mozilla.org/Labs/Ubiquity/Commands_In_The_Wild#Time Done])
* Ping.fm - can potentially replace twitter and facebook-status commands ([http://waleed.doubleudesigns.com/2008/08/ubiquity-and-pingfm/ Done])
* Mibbit IRC (mibbit [server] [optional:channels]) ([http://scguy318.freeshell.org/Mibbit%20Ubiquity%20Script.html Done])
* <tt>google-here <text></tt>: site-search on current site (without typing it explicitly) => ([http://groups.google.com/group/ubiquity-firefox/browse_thread/thread/5c2c80df1c61d4f8 Done])
Can anyone write a command that decodes 2D barcodes in images on a web page?

-I am working on a 2D barcode translator now. I have a standard barcode reader command working: http://devstatus.com ~ matt

*I just finished a simple Woot checker that goes to the "Want One" page on enter: [http://gist.github.com/41227 Woot]
<nowiki>Insert non-formatted text here</nowiki>

Labs/Ubiquity/Ubiquity Command Suggestions

2009-02-27T17:26:38Z

Endolith: /* Tools */

Many of the commands suggested on this page have already been implemented, either by us or by third parties. Please take a look at [https://labs.toolness.com/ubiquity-herd/all-feeds/ | The Herd's command feed index] to see what commands other people have implemented. You may find what you're looking for there!

Back to [[Labs/Ubiquity]].

==Interesting Commands ==

These commands are either extremely useful to everyone (likely to be included as a builtin command) or they push the boundaries of what Ubiquity can do.

* Search the Herd for new Ubiquity commands directly using Ubiquity without having to physically navigate to the site.
* Commands for all of the menu items (so that I never have to reach for the mouse to menu again). Sandro mentioned this recently.
* Program launcher (When in Chrome, JS can launch other applications)
* "cmd" command to pass selected text to the command line, i.e. "cmd wget" would pass the selected text to the wget function via the cli.
* Upload code to pastebin (useful for sharing commands from the command-editor)
* Integration with webchuck extension (with the ability to view webchunks in the preview).
* BlueOrganizer (be inspired by this addon and it's somewhat semantic knowledge)
* Graphing data (currently, only sparklines are supported). Would be nice to plot bar graphs and pie charts of things like countries by GDP from Wikipedia or browser usage on my website. There's a lot to think about here but this could potentially become one of the best features of Ubiquity.
* Task-specific tab grouping. Allow for opening and closing a set of tabs all at once. The key question here is how to add tabs to groups using Ubiquity.

==Search Commands==
*Creative Commons: Find something in CC
*Wikipedia in spanish: (or use it in another languages)
*Bookmarklet command; execute any bookmarklet via the keyboard.(This could include normal bookmarks something like quick dial with the keyboard)
*Map contact command, a command to get the location(s) of a contact from your contact list.( map-contact (name) )
* Google site search multiple urls in selection. You would select a block of text containing multiple urls, and be able to search them all simultaneously for any given text.
** Is this even possible? What is the format? "site:mozilla.org,wikipedia.org test"? "site:mozilla.org site:wikipedia.org test"?
* Flickr search (a [http://194.95.111.244/%7Ecountzero/scripts/_myImageFlow/ coverflow-like preview] would be awesome)
* last.fm search with preview (a first attempt has been made [http://www.geero.net/ here])
* Google Image Search with preview
** Built-in image-search command does this, no?
* Google Sets (part of Google labs) to give related terms based on user input
* More specific Google searches, like google video search on 'video', and google definition search type "define:mozilla" into google.
* A search for the Gawker sites eg: Gizmodo, Lifehacker, etc...
* a command to find the largest number in a given tab/present page
* A search for books by ISBN number for availability in libraries of your choice. Use the [http://en.wikipedia.org/wiki/Special:BookSources/ 'Book sources'] by wikipedia to find it. To find the book with ISBN number 1871890306 in SF, you Ubiq "ISBN 1871890306 in San Francisco", or if you are in San Francisco, you can type "ISBN 1871890306 here", using your geo-location by ip attached to the [http://labs.toolness.com/trac/ticket/179 magic word 'here'], which I believe will be part of Ubiq 0.2. Integration with maps in a later stage? Discuss [http://getsatisfaction.com/mozilla/topics/book_source_your_isbn_numbers_through_ubiquity here].
* One command should be able to launch several searches on different sites in different tabs. It worked before, with several Utils.openUrlInBrowser's, but 0.1.1 broke it.
* Froogle search ([http://stanford.edu/~marce110/verbs/froogle-search.html This] works pretty well for now, but it's messy and would break if Google changed the format of the search results.)
* search google calendar
* taking the name of a television show, search for the show's schedule and add that schedule to google calendar
* A command that searches the web for a picture similar to one selected. using similar pixel arraignment to find pictures of better resolution or less cropped than one you might find roaming randomly.
** [http://blogs.msdn.com/livesearch/archive/2008/12/01/using-images-to-find-other-images.aspx Microsoft Live Search can do this]
* A image cover flow or even just something as simple as a image viewer. Also it should be able to add images into e-mails like the maps.
* Would love to see a search function for Calorie King to look up Nutrition Fact tables for foods ([http://is.gd/euXv like this one]).
* A search function for XHTML entities (maybe looking like [http://www.digitalmediaminute.com/reference/entity/index.php this]?) would be awesome. Not sure what auto-complete would look like for this....
* A function where you can highlight a text and then add additional text to that in ubiquity. For example I highlight a bands name on wiki then open Ubiquity and add a song name and then search on youtube.
*A search function for custom search command adding.
For example, allowing a user to search [input] using www.ffxiclopedia.org's main search [input] by setting "ffxi" command to it.

==Program Integration==
* Goto command for navigating the web quick and easy but I want it in the core.
* Search command (allows you to search for text in any open tab, and then navigate you there)
* Flock stuff (be inspired by whatever seems to be actually useful in Flock)
** Especially nice if it could integrate with existing application launchers (ie: Quicksilver, Launchy, etc)
* Ability to take snapshots of the current window
* Queries for places datastores, rendering in plain html blue links (Beltzer showed me a little js console script that is a fine starting point).
** tag:(hci gestuers)
** site:google date:yesterday show:clicks
** starred intitle:Concept
* Integrate with Thunderbird, Sunbird, Songbird and other Mozilla software
* Allow for commands to be treated as content/arguments for other commands ie: email {map Washington DC} to myfriend@gmail.com would open up an email box to friend1 with a map of DC in the content pane
* clone of email command for Gajim/Pidgin/Psi/Adium...
* Integration with Instant Messenger clients (AIM, Pidgin, Trillion, etc) to allow inserting content into a message for a particular contact ie 'IM this to John'
* Idea:: have a very, very small program run on start up, that detects when the key combination is pressed and will launch Ubiquity. After Ubiquity is dismissed, it will return to its original state.
* In Firefox, "Bookmark this" & "Create bookmark folder <data>"
* For Linux, allow users and other commands to be sent to the terminal...eg. IF you had selected text and wanted to open in gedit, ubiquity would tell the terminal to open gedit then paste in text..etc
* Ability to select the address-bar. I.e. "Select-address" would jump to the address-bar and highlight it.

==Tools==
* Annotate web pages and then share those annotations (perhaps using google notebook?)
* Close unrelated tabs: similar to close all related tabs
* Download manager - A text based download manager like wget on linux
* Related articles and images, possibly using Zemanta like [https://addons.mozilla.org/en-US/firefox/addon/7571 this plugin].
* Replace words in selected text (optional: regular expressions)
* Save current site into a PDF file
** "convert" command already does this
* Save page as... "Web Page, complete" to a pre-specified folder
* Save selection/highlighted text to a file in a pre-specified location
* Spell checker - any text, not just form fields
* Related to spell checker - take highlighted text, pass it through any number of online dictionaries, and let user select which word to use as replacement.
* Status message editor - Easily modify status and/or status message on popular IM protocols
* Perhaps "convert 8pm australian time to my time" where my timezone could automatically be obtained from CmdUtils.getLocation()
* 'Tag' function:
** Auto-complete from current tags list would be excellent
** Needs to handle multiple, comma-separated tags, better. Currently adds the comma to the tag name (eg. 'tag snacks, quick-meals' creates a new tag called "snacks,")
* 'Undo' function should work on in-page replacements (eg. translating highlighted text or inserting a map into page)
* Upload selected image to [http://tinypic.com tinypic] or the like
* Disable "window.print()" API for all pages, or replace it with a less intrusive variant (toast notification?)
* Command Creator From Forms: Kind of like how you can create keyword searches by right clicking any search box, but you would be able to right-click any form from any search or web publish forms and select "Create Ubiquity Command..." which pops a box where you say the the command keyword
* Add a domain (current domain as default) to cookie whitelist
* Add a thesaurus search function
** http://www.zacharyspencer.com/2008/09/my-first-ubiquity-command/
* Restart Firefox
** Built-in "restart" command does this
* Download instead of opening URL
* The ability to Edit existing/installed commands. I.E. "edit-command define" would search for an installed "define" command and open the source in the command-editor.
* The ability to bookmark a page and bypass the [ok/cancel] dialog box so that you can bookmark related tabs all at once.

==Site Integration==
*Forum (BBCode) formatting
*Youtube: Highlight a youtube link and embed the video. Could be used with other sites as well.
* Blogger:
** 'blog' function, to create a new blog post from selected text
*Command for [http://www.mytextfile.com MyTextFile] such as, "note/textfile (text)." It should auto-save so you never leave Ubiquity, unless, opening a new tab is necessary. Very similar to how email works now.
* Google Calendar:
**ability to add more information to a calendar appointment such as location (perhaps signaled by @ ), calendar choice ( [ ] ), improved date parsing (you could say next Wednesday, and it could figure it out, maybe like [http://www.datejs.com/ DateJS]).
**ability to get a preview of my next 10 calendar entries.
** access HTTPS version of calendar, perhaps with 'add-to-scalendar' and 'check-scalendar'
* Gmail:
** Add contact, from a selected text to your contact list in gmail.
*** Add a contact group (and contacts if needed) from the emails list in a received email (all cc'ed people, including the sender, excluding yourself), or from a list of email address'.
** Gmail labels, alphabetical lookup from available labels. Code possibly similar to the greasemonkey script [http://blog.persistent.info/2007/11/macros-for-new-version-of-gmail.html macros] for gmail.
* Google Maps -
** when a google map image is inserted into a form, the image should have a link to the map on the google map site. e.g.: http://maps.google.com/maps?f=q&hl=en&geocode=&q=Budapest,+Hungary&ie=UTF8&z=11&iwloc=addr
** Google Directions search, perhaps separating locations with a semicolon if Ubiquity doesn't understand multiple word arguments.
** Route information
* Internationalisation (google.co.uk, ebay.co.uk. etc)
** weather command in Celsius
** localize verbs (and their parameters: 01/09 = 1st September in some country)
** "map" command needs to be country-specific (maps.google.com.xx)
* Flickr integration (ability to inject pictures/slideshows and post found images to Flickr)
* More advanced twitter integration (a command to view last x messages from a specific friend and another to view your recent friends timeline)
* Blog integration (select a chunk of text or an image and then blog about it in your favorite blog software)
* Fly command (possibly using [http://tripeedo.com/ Tripeedo]'s built-in natural language search and the site's preview or the Kayak API) to make booking flights easier
* Digg (see Sandro's [http://ubiquity-firefox.googlegroups.com/web/diggthis.js diggthis command])
* Reddit/Mixx
* Del.icio.us (e.g. "delic this" or "delic this with tag1 tag2 tag3")
* Turn referencing friend feed comments and tweets on a page (defaulted to the current page) into page annotations via command "show conversations"
* Integration with Jaiku, Plurk, Pownce, and other microblogging services (not only with Twitter)
* Integration with Google Docs and Google Notebook
* Command to send selected text to tinypaste.com and/or <strike>shorttext.com</strike> ([http://shortText.com/ Commands 'shorttext', 'longtext'] now available), pastebin.com, cl1p.net etc.
* Subscribe to current site's feed via Google Reader or other RSS reader
* Add to Google Bookmarks
* Easily control [http://www.bitlet.org BitLet.org]
* Add torrents with [http://www.azureuswiki.com/index.php/HTML_WebUI Azureus' HTML WebUI]. => this can be done with Greasemonkey already
* Geotag flickr photos easily (see [http://labs.sumaato.net/tools/flickr_geocode_bookmarklet/ Localize Bookmarklet])
* Take highlighted thread, and paste it in a forum. Because of the amount of forums, it might be better to just have a template for each forum type.
* Evernote command (post this page/text to evernote) suggested by Ben [http://groups.google.com/group/ubiquity-firefox/browse_thread/thread/68d7f5d7f817c4d5?hl=en here]
* Adobe Buzzword integration
* tempomail / jetable (temp mail address) integration. Implemented. See [http://gist.github.com/11261 Jetable]
* Horde email/calendar
* SMS Messaging. Text-message content to a contact or phone number. Could integrate with an existing service such as: http://smseverywhere.com/send.htm
* Set tv recording. For those people using mythtv / myth* or a TiVo with a web front-end, if you saw a show on some web site, like tvrage or any channel that shows tv-listings, highlight the show, and say 'record this'. This would probably be very dependent on your specific web front-end / TVR hardware.
*integrate into MySpace. command such as "send this to (myspace contact): (selected text or image, maybe even if your on youtube, it will automatically imbed.)" Another could be "set headline as (selected text or input)"
* Integrate with [http://www.squirrelmail.org/ SqirrelMail]
* Integrate with [http://roundcube.net/ RoundCube Mail]
* Integrate with [http://sourceforge.net/projects/scuttle/ Scuttle Bookmarks]
* Integrate with [http://webcalendar.sourceforge.net/ WebCalendar]
* Integrate with [http://www.rememberthemilk.com/ Remember The Milk]. Add tasks, get list of tasks, mark tasks as completed, etc. They have a really rich API. (Adding tasks is done: [http://garyhodgson.com/ubiquity/rtm.html here], with a more advanced version [http://garyhodgson.com/ubiquity/rtm-wip.html in progress].)
* Integrate with [http://www.toodledo.com/ Toodledo] in a similar way to that described for RTM
* [http://www.facebook.com Facebook] status setting-resetting integration. Ping.fm has been implemented but there are users (like me) that prefer to use only one social networking site, hence they don't need a ping.fm account. (already done [http://home.comcast.net/~captainbeah/ubiquity/facebook/ here])
* Integrate with [http://www.me.com/ MobileMe] to allow similar email and calendar editing integration as for the Google equivalents (GMail etc.)
* Integrate with [http://www.ryanair.com/ Ryanair] to allow searching for flights using Ubiquity.
* Subscribe with Bloglines
* Integrate with Google Apps (Gmail, Calendar) [http://www.google.com/apps/] to allow using the standard commands

==Extension Integration==
* PasswordMaker: http://passwordmaker.org/
* BlueOrganizer (be inspired by [https://addons.mozilla.org/en-US/firefox/addon/3481 this addon] and it's somewhat semantic knowledge)
* Take inspiration from [https://addons.mozilla.org/en-US/firefox/addon/1407 Clipmarks]
* Firebug integration, inspect DOM-Reference, show firebug net panel
* Media player control similar to [https://addons.mozilla.org/en-US/firefox/addon/219 FoxyTunes]
* AnyColor integration -- https://addons.mozilla.org/en-US/firefox/addon/6991
* Faviconize -- A command called Fav [open tab] to change it's state from showing/hiding title
* Commands for Screen grab! extension
* Undo Closed Tabs Button feature like the extension of that name. (Note: this is built into Firefox 3.0, no need for this extension anymore)
* Adblock Plus integration, along with NoScript.
* Ability to inject Webslices, for use with Webchunks.
* Fast Dial integration
* Overwrite the window.print command with a less intrusive UI. It would instead pop a notification/toaster ("this site wants to print itself. _Print_").
* Greasemonkey integration: "greasemonkey-edit <userscript>". It would autocomplete the userscript name based on the list of installed userscripts.
* Cool iris functionality with a image flow.

==Finished Commands==
* [http://shortText.com/ shortText.com] done. Create a URL of any selected text by using command 'shorttext' or expand a shortText URL to its full content by using command 'longtext'
* [http://www.google.com/sitesearch/ Google Site Search] integration. (Example: "search komplett.ie for cpu coolers") [http://mysite.verizon.net/zaduma/ Done]
* Metacritic (metacritic.com) review searching - [http://mysite.verizon.net/zaduma/ Done]
* Torrent search [http://mysite.verizon.net/zaduma/ Done]
* Reveal the exact URL-s behind tinyurl-s (see [http://ghill.customer.netspace.net.au/embiggen/ Embiggen Bookmarklet]) [http://mysite.verizon.net/zaduma/ Done]
* BugMeNot lookup for current page [http://www.geocities.com/lemming4242 Done]
* Open command (select multiple links, then open them all in tabs) [http://www.geocities.com/lemming4242/ Done]
* An online bible service command. [http://tim.sorbera.googlepages.com/ubiquity.html Done]
* A command to open a selected URL. [http://tim.sorbera.googlepages.com/ubiquity.html Done]
* Twitter Search - [http://gist.github.com/7594 Done] but could benefit from a sexier UI
* Random number generator. Floating point value with input of the following type: random lower-val higher-val
** Example: Random 0 1; Gives 0.252
** Example: Random 1 100; Gives 275.840
** [http://ubiquitously.org/forum/viewtopic.php?f=4&t=12 Done]
* Go command (for switching between tabs by name) (achieved by the "tab" command builtin to Ubiquity)
* Reopen an existing tab in a new tab. Sometimes you want to search for a new topic (in Wikipedia for example), and you have to re-open a new tab, then copy and paste the current url. Why not have a "re-open" command that lets you create a new tab, and copy the currently opened page over to it? (Alt+D > Alt+Enter currently does this. necessary?) (No. Did it anyways.) [http://ubiquitously.org/forum/viewtopic.php?f=5&t=22 Done]
* Currency conversion [http://ubiquitously.org/forum/viewtopic.php?f=4&t=25 Done]
* Unit conversion [http://ubiquitously.org/forum/viewtopic.php?f=4&t=25 Done (Same as above)]
* Stock quotes [http://ubiquitously.org/forum/viewtopic.php?f=4&t=26 Done]
* A "view source" for Ubiq commands. For example, "view-source link-to-wikipedia" => [https://wiki.mozilla.org/Labs/Ubiquity/Ubiquity_0.1.1_Release_Notes available] in Ubiq 0.1.1, although not as a command.
* Link finder (like the "link-to-wikipedia" command but then, instead of inserting a link to wikipedia, allow the user to find the link from history/bookmarks. This would save a lot of excess work because at the moment, to insert a link, you have to open up a new tab, find the page you want to link to, copy the address and then, go back to add the link) => try [http://blog.monstuff.com/archives/000343.html insert-link]
* Command that takes each search plugin/provider you have in the search-bar (by default, right of the locationbar in IE7 & FF2 & 3, plus more), and turns it into a command you can use. Thus, having search plugin/providers at your fingertips in ubiquity, and adding a search plugin/provider command is just as easy as using already created functionality; This could either be done in the underlying code of Ubiquity, or maybe have it so that the command is done as "Search <Plugin/Provider> <Terms>
** I'm a moron..I actually had a command that did this.[http://theunfocused.net/moz/ubiquity/verbs/?cmd=search]
** Dup: Integration of your installed Firefox search engines.
* Timezone converter - something like "get time in australia" ([https://wiki.mozilla.org/Labs/Ubiquity/Commands_In_The_Wild#Time Done])
* Ping.fm - can potentially replace twitter and facebook-status commands ([http://waleed.doubleudesigns.com/2008/08/ubiquity-and-pingfm/ Done])
* Mibbit IRC (mibbit [server] [optional:channels]) ([http://scguy318.freeshell.org/Mibbit%20Ubiquity%20Script.html Done])
* <tt>google-here <text></tt>: site-search on current site (without typing it explicitly) => ([http://groups.google.com/group/ubiquity-firefox/browse_thread/thread/5c2c80df1c61d4f8 Done])
Can anyone write a command that decodes 2D barcodes in images on a web page?

-I am working on a 2D barcode translator now. I have a standard barcode reader command working: http://devstatus.com ~ matt

*I just finished a simple Woot checker that goes to the "Want One" page on enter: [http://gist.github.com/41227 Woot]
<nowiki>Insert non-formatted text here</nowiki>

Labs/Ubiquity/Ubiquity Command Suggestions

2009-02-27T16:54:09Z

Endolith: /* Search Commands */

Many of the commands suggested on this page have already been implemented, either by us or by third parties. Please take a look at [https://labs.toolness.com/ubiquity-herd/all-feeds/ | The Herd's command feed index] to see what commands other people have implemented. You may find what you're looking for there!

Back to [[Labs/Ubiquity]].

==Interesting Commands ==

These commands are either extremely useful to everyone (likely to be included as a builtin command) or they push the boundaries of what Ubiquity can do.

* Search the Herd for new Ubiquity commands directly using Ubiquity without having to physically navigate to the site.
* Commands for all of the menu items (so that I never have to reach for the mouse to menu again). Sandro mentioned this recently.
* Program launcher (When in Chrome, JS can launch other applications)
* "cmd" command to pass selected text to the command line, i.e. "cmd wget" would pass the selected text to the wget function via the cli.
* Upload code to pastebin (useful for sharing commands from the command-editor)
* Integration with webchuck extension (with the ability to view webchunks in the preview).
* BlueOrganizer (be inspired by this addon and it's somewhat semantic knowledge)
* Graphing data (currently, only sparklines are supported). Would be nice to plot bar graphs and pie charts of things like countries by GDP from Wikipedia or browser usage on my website. There's a lot to think about here but this could potentially become one of the best features of Ubiquity.
* Task-specific tab grouping. Allow for opening and closing a set of tabs all at once. The key question here is how to add tabs to groups using Ubiquity.

==Search Commands==
*Creative Commons: Find something in CC
*Wikipedia in spanish: (or use it in another languages)
*Bookmarklet command; execute any bookmarklet via the keyboard.(This could include normal bookmarks something like quick dial with the keyboard)
*Map contact command, a command to get the location(s) of a contact from your contact list.( map-contact (name) )
* Google site search multiple urls in selection. You would select a block of text containing multiple urls, and be able to search them all simultaneously for any given text.
** Is this even possible? What is the format? "site:mozilla.org,wikipedia.org test"? "site:mozilla.org site:wikipedia.org test"?
* Flickr search (a [http://194.95.111.244/%7Ecountzero/scripts/_myImageFlow/ coverflow-like preview] would be awesome)
* last.fm search with preview (a first attempt has been made [http://www.geero.net/ here])
* Google Image Search with preview
** Built-in image-search command does this, no?
* Google Sets (part of Google labs) to give related terms based on user input
* More specific Google searches, like google video search on 'video', and google definition search type "define:mozilla" into google.
* A search for the Gawker sites eg: Gizmodo, Lifehacker, etc...
* a command to find the largest number in a given tab/present page
* A search for books by ISBN number for availability in libraries of your choice. Use the [http://en.wikipedia.org/wiki/Special:BookSources/ 'Book sources'] by wikipedia to find it. To find the book with ISBN number 1871890306 in SF, you Ubiq "ISBN 1871890306 in San Francisco", or if you are in San Francisco, you can type "ISBN 1871890306 here", using your geo-location by ip attached to the [http://labs.toolness.com/trac/ticket/179 magic word 'here'], which I believe will be part of Ubiq 0.2. Integration with maps in a later stage? Discuss [http://getsatisfaction.com/mozilla/topics/book_source_your_isbn_numbers_through_ubiquity here].
* One command should be able to launch several searches on different sites in different tabs. It worked before, with several Utils.openUrlInBrowser's, but 0.1.1 broke it.
* Froogle search ([http://stanford.edu/~marce110/verbs/froogle-search.html This] works pretty well for now, but it's messy and would break if Google changed the format of the search results.)
* search google calendar
* taking the name of a television show, search for the show's schedule and add that schedule to google calendar
* A command that searches the web for a picture similar to one selected. using similar pixel arraignment to find pictures of better resolution or less cropped than one you might find roaming randomly.
** [http://blogs.msdn.com/livesearch/archive/2008/12/01/using-images-to-find-other-images.aspx Microsoft Live Search can do this]
* A image cover flow or even just something as simple as a image viewer. Also it should be able to add images into e-mails like the maps.
* Would love to see a search function for Calorie King to look up Nutrition Fact tables for foods ([http://is.gd/euXv like this one]).
* A search function for XHTML entities (maybe looking like [http://www.digitalmediaminute.com/reference/entity/index.php this]?) would be awesome. Not sure what auto-complete would look like for this....
* A function where you can highlight a text and then add additional text to that in ubiquity. For example I highlight a bands name on wiki then open Ubiquity and add a song name and then search on youtube.
*A search function for custom search command adding.
For example, allowing a user to search [input] using www.ffxiclopedia.org's main search [input] by setting "ffxi" command to it.

==Program Integration==
* Goto command for navigating the web quick and easy but I want it in the core.
* Search command (allows you to search for text in any open tab, and then navigate you there)
* Flock stuff (be inspired by whatever seems to be actually useful in Flock)
** Especially nice if it could integrate with existing application launchers (ie: Quicksilver, Launchy, etc)
* Ability to take snapshots of the current window
* Queries for places datastores, rendering in plain html blue links (Beltzer showed me a little js console script that is a fine starting point).
** tag:(hci gestuers)
** site:google date:yesterday show:clicks
** starred intitle:Concept
* Integrate with Thunderbird, Sunbird, Songbird and other Mozilla software
* Allow for commands to be treated as content/arguments for other commands ie: email {map Washington DC} to myfriend@gmail.com would open up an email box to friend1 with a map of DC in the content pane
* clone of email command for Gajim/Pidgin/Psi/Adium...
* Integration with Instant Messenger clients (AIM, Pidgin, Trillion, etc) to allow inserting content into a message for a particular contact ie 'IM this to John'
* Idea:: have a very, very small program run on start up, that detects when the key combination is pressed and will launch Ubiquity. After Ubiquity is dismissed, it will return to its original state.
* In Firefox, "Bookmark this" & "Create bookmark folder <data>"
* For Linux, allow users and other commands to be sent to the terminal...eg. IF you had selected text and wanted to open in gedit, ubiquity would tell the terminal to open gedit then paste in text..etc
* Ability to select the address-bar. I.e. "Select-address" would jump to the address-bar and highlight it.

==Tools==
* Annotate web pages and then share those annotations (perhaps using google notebook?)
* Close unrelated tabs: similar to close all related tabs
* Download manager - A text based download manager like wget on linux
* Related articles and images, possibly using Zemanta like [https://addons.mozilla.org/en-US/firefox/addon/7571 this plugin].
* Replace words in selected text (optional: regular expressions)
* Save current site into a PDF file
* Save page as... "Web Page, complete" to a pre-specified folder
* Save selection/highlighted text to a file in a pre-specified location
* Spell checker - any text, not just form fields
* Related to spell checker - take highlighted text, pass it through any number of online dictionaries, and let user select which word to use as replacement.
* Status message editor - Easily modify status and/or status message on popular IM protocols
* Perhaps "convert 8pm australian time to my time" where my timezone could automatically be obtained from CmdUtils.getLocation()
* 'Tag' function:
** Auto-complete from current tags list would be excellent
** Needs to handle multiple, comma-separated tags, better. Currently adds the comma to the tag name (eg. 'tag snacks, quick-meals' creates a new tag called "snacks,")
* 'Undo' function should work on in-page replacements (eg. translating highlighted text or inserting a map into page)
* Upload selected image to [http://tinypic.com tinypic] or the like
* Disable "window.print()" API for all pages, or replace it with a less intrusive variant (toast notification?)
* Command Creator From Forms: Kind of like how you can create keyword searches by right clicking any search box, but you would be able to right-click any form from any search or web publish forms and select "Create Ubiquity Command..." which pops a box where you say the the command keyword
* Add a domain (current domain as default) to cookie whitelist
* Add a thesaurus search function
* Restart Firefox
* Download instead of opening URL
* The ability to Edit existing/installed commands. I.E. "edit-command define" would search for an installed "define" command and open the source in the command-editor.
* The ability to bookmark a page and bypass the [ok/cancel] dialog box so that you can bookmark related tabs all at once.

==Site Integration==
*Forum (BBCode) formatting
*Youtube: Highlight a youtube link and embed the video. Could be used with other sites as well.
* Blogger:
** 'blog' function, to create a new blog post from selected text
*Command for [http://www.mytextfile.com MyTextFile] such as, "note/textfile (text)." It should auto-save so you never leave Ubiquity, unless, opening a new tab is necessary. Very similar to how email works now.
* Google Calendar:
**ability to add more information to a calendar appointment such as location (perhaps signaled by @ ), calendar choice ( [ ] ), improved date parsing (you could say next Wednesday, and it could figure it out, maybe like [http://www.datejs.com/ DateJS]).
**ability to get a preview of my next 10 calendar entries.
** access HTTPS version of calendar, perhaps with 'add-to-scalendar' and 'check-scalendar'
* Gmail:
** Add contact, from a selected text to your contact list in gmail.
*** Add a contact group (and contacts if needed) from the emails list in a received email (all cc'ed people, including the sender, excluding yourself), or from a list of email address'.
** Gmail labels, alphabetical lookup from available labels. Code possibly similar to the greasemonkey script [http://blog.persistent.info/2007/11/macros-for-new-version-of-gmail.html macros] for gmail.
* Google Maps -
** when a google map image is inserted into a form, the image should have a link to the map on the google map site. e.g.: http://maps.google.com/maps?f=q&hl=en&geocode=&q=Budapest,+Hungary&ie=UTF8&z=11&iwloc=addr
** Google Directions search, perhaps separating locations with a semicolon if Ubiquity doesn't understand multiple word arguments.
** Route information
* Internationalisation (google.co.uk, ebay.co.uk. etc)
** weather command in Celsius
** localize verbs (and their parameters: 01/09 = 1st September in some country)
** "map" command needs to be country-specific (maps.google.com.xx)
* Flickr integration (ability to inject pictures/slideshows and post found images to Flickr)
* More advanced twitter integration (a command to view last x messages from a specific friend and another to view your recent friends timeline)
* Blog integration (select a chunk of text or an image and then blog about it in your favorite blog software)
* Fly command (possibly using [http://tripeedo.com/ Tripeedo]'s built-in natural language search and the site's preview or the Kayak API) to make booking flights easier
* Digg (see Sandro's [http://ubiquity-firefox.googlegroups.com/web/diggthis.js diggthis command])
* Reddit/Mixx
* Del.icio.us (e.g. "delic this" or "delic this with tag1 tag2 tag3")
* Turn referencing friend feed comments and tweets on a page (defaulted to the current page) into page annotations via command "show conversations"
* Integration with Jaiku, Plurk, Pownce, and other microblogging services (not only with Twitter)
* Integration with Google Docs and Google Notebook
* Command to send selected text to tinypaste.com and/or <strike>shorttext.com</strike> ([http://shortText.com/ Commands 'shorttext', 'longtext'] now available), pastebin.com, cl1p.net etc.
* Subscribe to current site's feed via Google Reader or other RSS reader
* Add to Google Bookmarks
* Easily control [http://www.bitlet.org BitLet.org]
* Add torrents with [http://www.azureuswiki.com/index.php/HTML_WebUI Azureus' HTML WebUI]. => this can be done with Greasemonkey already
* Geotag flickr photos easily (see [http://labs.sumaato.net/tools/flickr_geocode_bookmarklet/ Localize Bookmarklet])
* Take highlighted thread, and paste it in a forum. Because of the amount of forums, it might be better to just have a template for each forum type.
* Evernote command (post this page/text to evernote) suggested by Ben [http://groups.google.com/group/ubiquity-firefox/browse_thread/thread/68d7f5d7f817c4d5?hl=en here]
* Adobe Buzzword integration
* tempomail / jetable (temp mail address) integration. Implemented. See [http://gist.github.com/11261 Jetable]
* Horde email/calendar
* SMS Messaging. Text-message content to a contact or phone number. Could integrate with an existing service such as: http://smseverywhere.com/send.htm
* Set tv recording. For those people using mythtv / myth* or a TiVo with a web front-end, if you saw a show on some web site, like tvrage or any channel that shows tv-listings, highlight the show, and say 'record this'. This would probably be very dependent on your specific web front-end / TVR hardware.
*integrate into MySpace. command such as "send this to (myspace contact): (selected text or image, maybe even if your on youtube, it will automatically imbed.)" Another could be "set headline as (selected text or input)"
* Integrate with [http://www.squirrelmail.org/ SqirrelMail]
* Integrate with [http://roundcube.net/ RoundCube Mail]
* Integrate with [http://sourceforge.net/projects/scuttle/ Scuttle Bookmarks]
* Integrate with [http://webcalendar.sourceforge.net/ WebCalendar]
* Integrate with [http://www.rememberthemilk.com/ Remember The Milk]. Add tasks, get list of tasks, mark tasks as completed, etc. They have a really rich API. (Adding tasks is done: [http://garyhodgson.com/ubiquity/rtm.html here], with a more advanced version [http://garyhodgson.com/ubiquity/rtm-wip.html in progress].)
* Integrate with [http://www.toodledo.com/ Toodledo] in a similar way to that described for RTM
* [http://www.facebook.com Facebook] status setting-resetting integration. Ping.fm has been implemented but there are users (like me) that prefer to use only one social networking site, hence they don't need a ping.fm account. (already done [http://home.comcast.net/~captainbeah/ubiquity/facebook/ here])
* Integrate with [http://www.me.com/ MobileMe] to allow similar email and calendar editing integration as for the Google equivalents (GMail etc.)
* Integrate with [http://www.ryanair.com/ Ryanair] to allow searching for flights using Ubiquity.
* Subscribe with Bloglines
* Integrate with Google Apps (Gmail, Calendar) [http://www.google.com/apps/] to allow using the standard commands

==Extension Integration==
* PasswordMaker: http://passwordmaker.org/
* BlueOrganizer (be inspired by [https://addons.mozilla.org/en-US/firefox/addon/3481 this addon] and it's somewhat semantic knowledge)
* Take inspiration from [https://addons.mozilla.org/en-US/firefox/addon/1407 Clipmarks]
* Firebug integration, inspect DOM-Reference, show firebug net panel
* Media player control similar to [https://addons.mozilla.org/en-US/firefox/addon/219 FoxyTunes]
* AnyColor integration -- https://addons.mozilla.org/en-US/firefox/addon/6991
* Faviconize -- A command called Fav [open tab] to change it's state from showing/hiding title
* Commands for Screen grab! extension
* Undo Closed Tabs Button feature like the extension of that name. (Note: this is built into Firefox 3.0, no need for this extension anymore)
* Adblock Plus integration, along with NoScript.
* Ability to inject Webslices, for use with Webchunks.
* Fast Dial integration
* Overwrite the window.print command with a less intrusive UI. It would instead pop a notification/toaster ("this site wants to print itself. _Print_").
* Greasemonkey integration: "greasemonkey-edit <userscript>". It would autocomplete the userscript name based on the list of installed userscripts.
* Cool iris functionality with a image flow.

==Finished Commands==
* [http://shortText.com/ shortText.com] done. Create a URL of any selected text by using command 'shorttext' or expand a shortText URL to its full content by using command 'longtext'
* [http://www.google.com/sitesearch/ Google Site Search] integration. (Example: "search komplett.ie for cpu coolers") [http://mysite.verizon.net/zaduma/ Done]
* Metacritic (metacritic.com) review searching - [http://mysite.verizon.net/zaduma/ Done]
* Torrent search [http://mysite.verizon.net/zaduma/ Done]
* Reveal the exact URL-s behind tinyurl-s (see [http://ghill.customer.netspace.net.au/embiggen/ Embiggen Bookmarklet]) [http://mysite.verizon.net/zaduma/ Done]
* BugMeNot lookup for current page [http://www.geocities.com/lemming4242 Done]
* Open command (select multiple links, then open them all in tabs) [http://www.geocities.com/lemming4242/ Done]
* An online bible service command. [http://tim.sorbera.googlepages.com/ubiquity.html Done]
* A command to open a selected URL. [http://tim.sorbera.googlepages.com/ubiquity.html Done]
* Twitter Search - [http://gist.github.com/7594 Done] but could benefit from a sexier UI
* Random number generator. Floating point value with input of the following type: random lower-val higher-val
** Example: Random 0 1; Gives 0.252
** Example: Random 1 100; Gives 275.840
** [http://ubiquitously.org/forum/viewtopic.php?f=4&t=12 Done]
* Go command (for switching between tabs by name) (achieved by the "tab" command builtin to Ubiquity)
* Reopen an existing tab in a new tab. Sometimes you want to search for a new topic (in Wikipedia for example), and you have to re-open a new tab, then copy and paste the current url. Why not have a "re-open" command that lets you create a new tab, and copy the currently opened page over to it? (Alt+D > Alt+Enter currently does this. necessary?) (No. Did it anyways.) [http://ubiquitously.org/forum/viewtopic.php?f=5&t=22 Done]
* Currency conversion [http://ubiquitously.org/forum/viewtopic.php?f=4&t=25 Done]
* Unit conversion [http://ubiquitously.org/forum/viewtopic.php?f=4&t=25 Done (Same as above)]
* Stock quotes [http://ubiquitously.org/forum/viewtopic.php?f=4&t=26 Done]
* A "view source" for Ubiq commands. For example, "view-source link-to-wikipedia" => [https://wiki.mozilla.org/Labs/Ubiquity/Ubiquity_0.1.1_Release_Notes available] in Ubiq 0.1.1, although not as a command.
* Link finder (like the "link-to-wikipedia" command but then, instead of inserting a link to wikipedia, allow the user to find the link from history/bookmarks. This would save a lot of excess work because at the moment, to insert a link, you have to open up a new tab, find the page you want to link to, copy the address and then, go back to add the link) => try [http://blog.monstuff.com/archives/000343.html insert-link]
* Command that takes each search plugin/provider you have in the search-bar (by default, right of the locationbar in IE7 & FF2 & 3, plus more), and turns it into a command you can use. Thus, having search plugin/providers at your fingertips in ubiquity, and adding a search plugin/provider command is just as easy as using already created functionality; This could either be done in the underlying code of Ubiquity, or maybe have it so that the command is done as "Search <Plugin/Provider> <Terms>
** I'm a moron..I actually had a command that did this.[http://theunfocused.net/moz/ubiquity/verbs/?cmd=search]
** Dup: Integration of your installed Firefox search engines.
* Timezone converter - something like "get time in australia" ([https://wiki.mozilla.org/Labs/Ubiquity/Commands_In_The_Wild#Time Done])
* Ping.fm - can potentially replace twitter and facebook-status commands ([http://waleed.doubleudesigns.com/2008/08/ubiquity-and-pingfm/ Done])
* Mibbit IRC (mibbit [server] [optional:channels]) ([http://scguy318.freeshell.org/Mibbit%20Ubiquity%20Script.html Done])
* <tt>google-here <text></tt>: site-search on current site (without typing it explicitly) => ([http://groups.google.com/group/ubiquity-firefox/browse_thread/thread/5c2c80df1c61d4f8 Done])
Can anyone write a command that decodes 2D barcodes in images on a web page?

-I am working on a 2D barcode translator now. I have a standard barcode reader command working: http://devstatus.com ~ matt

*I just finished a simple Woot checker that goes to the "Want One" page on enter: [http://gist.github.com/41227 Woot]
<nowiki>Insert non-formatted text here</nowiki>

Labs/Ubiquity/Ubiquity Command Suggestions

2009-02-27T16:43:18Z

Endolith: /* Search Commands */

Many of the commands suggested on this page have already been implemented, either by us or by third parties. Please take a look at [https://labs.toolness.com/ubiquity-herd/all-feeds/ | The Herd's command feed index] to see what commands other people have implemented. You may find what you're looking for there!

Back to [[Labs/Ubiquity]].

==Interesting Commands ==

These commands are either extremely useful to everyone (likely to be included as a builtin command) or they push the boundaries of what Ubiquity can do.

* Search the Herd for new Ubiquity commands directly using Ubiquity without having to physically navigate to the site.
* Commands for all of the menu items (so that I never have to reach for the mouse to menu again). Sandro mentioned this recently.
* Program launcher (When in Chrome, JS can launch other applications)
* "cmd" command to pass selected text to the command line, i.e. "cmd wget" would pass the selected text to the wget function via the cli.
* Upload code to pastebin (useful for sharing commands from the command-editor)
* Integration with webchuck extension (with the ability to view webchunks in the preview).
* BlueOrganizer (be inspired by this addon and it's somewhat semantic knowledge)
* Graphing data (currently, only sparklines are supported). Would be nice to plot bar graphs and pie charts of things like countries by GDP from Wikipedia or browser usage on my website. There's a lot to think about here but this could potentially become one of the best features of Ubiquity.
* Task-specific tab grouping. Allow for opening and closing a set of tabs all at once. The key question here is how to add tabs to groups using Ubiquity.

==Search Commands==
*Creative Commons: Find something in CC
*Wikipedia in spanish: (or use it in another languages)
*Bookmarklet command; execute any bookmarklet via the keyboard.(This could include normal bookmarks something like quick dial with the keyboard)
*Map contact command, a command to get the location(s) of a contact from your contact list.( map-contact (name) )
* Google site search multiple urls in selection. You would select a block of text containing multiple urls, and be able to search them all simultaneously for any given text.
** Is this even possible? What is the format? "site:mozilla.org,wikipedia.org test"? "site:mozilla.org site:wikipedia.org test"?
* Flickr search (a [http://194.95.111.244/%7Ecountzero/scripts/_myImageFlow/ coverflow-like preview] would be awesome)
* last.fm search with preview (a first attempt has been made [http://www.geero.net/ here])
* Google Image Search with preview
* Google Sets (part of Google labs) to give related terms based on user input
* More specific Google searches, like google video search on 'video', and google definition search type "define:mozilla" into google.
* A search for the Gawker sites eg: Gizmodo, Lifehacker, etc...
* a command to find the largest number in a given tab/present page
* A search for books by ISBN number for availability in libraries of your choice. Use the [http://en.wikipedia.org/wiki/Special:BookSources/ 'Book sources'] by wikipedia to find it. To find the book with ISBN number 1871890306 in SF, you Ubiq "ISBN 1871890306 in San Francisco", or if you are in San Francisco, you can type "ISBN 1871890306 here", using your geo-location by ip attached to the [http://labs.toolness.com/trac/ticket/179 magic word 'here'], which I believe will be part of Ubiq 0.2. Integration with maps in a later stage? Discuss [http://getsatisfaction.com/mozilla/topics/book_source_your_isbn_numbers_through_ubiquity here].
* One command should be able to launch several searches on different sites in different tabs. It worked before, with several Utils.openUrlInBrowser's, but 0.1.1 broke it.
* Froogle search ([http://stanford.edu/~marce110/verbs/froogle-search.html This] works pretty well for now, but it's messy and would break if Google changed the format of the search results.)
* search google calendar
* taking the name of a television show, search for the show's schedule and add that schedule to google calendar
* A command that searches the web for a picture similar to one selected. using similar pixel arraignment to find pictures of better resolution or less cropped than one you might find roaming randomly.
** [http://blogs.msdn.com/livesearch/archive/2008/12/01/using-images-to-find-other-images.aspx Microsoft Live Search can do this]
* A image cover flow or even just something as simple as a image viewer. Also it should be able to add images into e-mails like the maps.
* Would love to see a search function for Calorie King to look up Nutrition Fact tables for foods ([http://is.gd/euXv like this one]).
* A search function for XHTML entities (maybe looking like [http://www.digitalmediaminute.com/reference/entity/index.php this]?) would be awesome. Not sure what auto-complete would look like for this....
* A function where you can highlight a text and then add additional text to that in ubiquity. For example I highlight a bands name on wiki then open Ubiquity and add a song name and then search on youtube.
*A search function for custom search command adding.
For example, allowing a user to search [input] using www.ffxiclopedia.org's main search [input] by setting "ffxi" command to it.

==Program Integration==
* Goto command for navigating the web quick and easy but I want it in the core.
* Search command (allows you to search for text in any open tab, and then navigate you there)
* Flock stuff (be inspired by whatever seems to be actually useful in Flock)
** Especially nice if it could integrate with existing application launchers (ie: Quicksilver, Launchy, etc)
* Ability to take snapshots of the current window
* Queries for places datastores, rendering in plain html blue links (Beltzer showed me a little js console script that is a fine starting point).
** tag:(hci gestuers)
** site:google date:yesterday show:clicks
** starred intitle:Concept
* Integrate with Thunderbird, Sunbird, Songbird and other Mozilla software
* Allow for commands to be treated as content/arguments for other commands ie: email {map Washington DC} to myfriend@gmail.com would open up an email box to friend1 with a map of DC in the content pane
* clone of email command for Gajim/Pidgin/Psi/Adium...
* Integration with Instant Messenger clients (AIM, Pidgin, Trillion, etc) to allow inserting content into a message for a particular contact ie 'IM this to John'
* Idea:: have a very, very small program run on start up, that detects when the key combination is pressed and will launch Ubiquity. After Ubiquity is dismissed, it will return to its original state.
* In Firefox, "Bookmark this" & "Create bookmark folder <data>"
* For Linux, allow users and other commands to be sent to the terminal...eg. IF you had selected text and wanted to open in gedit, ubiquity would tell the terminal to open gedit then paste in text..etc
* Ability to select the address-bar. I.e. "Select-address" would jump to the address-bar and highlight it.

==Tools==
* Annotate web pages and then share those annotations (perhaps using google notebook?)
* Close unrelated tabs: similar to close all related tabs
* Download manager - A text based download manager like wget on linux
* Related articles and images, possibly using Zemanta like [https://addons.mozilla.org/en-US/firefox/addon/7571 this plugin].
* Replace words in selected text (optional: regular expressions)
* Save current site into a PDF file
* Save page as... "Web Page, complete" to a pre-specified folder
* Save selection/highlighted text to a file in a pre-specified location
* Spell checker - any text, not just form fields
* Related to spell checker - take highlighted text, pass it through any number of online dictionaries, and let user select which word to use as replacement.
* Status message editor - Easily modify status and/or status message on popular IM protocols
* Perhaps "convert 8pm australian time to my time" where my timezone could automatically be obtained from CmdUtils.getLocation()
* 'Tag' function:
** Auto-complete from current tags list would be excellent
** Needs to handle multiple, comma-separated tags, better. Currently adds the comma to the tag name (eg. 'tag snacks, quick-meals' creates a new tag called "snacks,")
* 'Undo' function should work on in-page replacements (eg. translating highlighted text or inserting a map into page)
* Upload selected image to [http://tinypic.com tinypic] or the like
* Disable "window.print()" API for all pages, or replace it with a less intrusive variant (toast notification?)
* Command Creator From Forms: Kind of like how you can create keyword searches by right clicking any search box, but you would be able to right-click any form from any search or web publish forms and select "Create Ubiquity Command..." which pops a box where you say the the command keyword
* Add a domain (current domain as default) to cookie whitelist
* Add a thesaurus search function
* Restart Firefox
* Download instead of opening URL
* The ability to Edit existing/installed commands. I.E. "edit-command define" would search for an installed "define" command and open the source in the command-editor.
* The ability to bookmark a page and bypass the [ok/cancel] dialog box so that you can bookmark related tabs all at once.

==Site Integration==
*Forum (BBCode) formatting
*Youtube: Highlight a youtube link and embed the video. Could be used with other sites as well.
* Blogger:
** 'blog' function, to create a new blog post from selected text
*Command for [http://www.mytextfile.com MyTextFile] such as, "note/textfile (text)." It should auto-save so you never leave Ubiquity, unless, opening a new tab is necessary. Very similar to how email works now.
* Google Calendar:
**ability to add more information to a calendar appointment such as location (perhaps signaled by @ ), calendar choice ( [ ] ), improved date parsing (you could say next Wednesday, and it could figure it out, maybe like [http://www.datejs.com/ DateJS]).
**ability to get a preview of my next 10 calendar entries.
** access HTTPS version of calendar, perhaps with 'add-to-scalendar' and 'check-scalendar'
* Gmail:
** Add contact, from a selected text to your contact list in gmail.
*** Add a contact group (and contacts if needed) from the emails list in a received email (all cc'ed people, including the sender, excluding yourself), or from a list of email address'.
** Gmail labels, alphabetical lookup from available labels. Code possibly similar to the greasemonkey script [http://blog.persistent.info/2007/11/macros-for-new-version-of-gmail.html macros] for gmail.
* Google Maps -
** when a google map image is inserted into a form, the image should have a link to the map on the google map site. e.g.: http://maps.google.com/maps?f=q&hl=en&geocode=&q=Budapest,+Hungary&ie=UTF8&z=11&iwloc=addr
** Google Directions search, perhaps separating locations with a semicolon if Ubiquity doesn't understand multiple word arguments.
** Route information
* Internationalisation (google.co.uk, ebay.co.uk. etc)
** weather command in Celsius
** localize verbs (and their parameters: 01/09 = 1st September in some country)
** "map" command needs to be country-specific (maps.google.com.xx)
* Flickr integration (ability to inject pictures/slideshows and post found images to Flickr)
* More advanced twitter integration (a command to view last x messages from a specific friend and another to view your recent friends timeline)
* Blog integration (select a chunk of text or an image and then blog about it in your favorite blog software)
* Fly command (possibly using [http://tripeedo.com/ Tripeedo]'s built-in natural language search and the site's preview or the Kayak API) to make booking flights easier
* Digg (see Sandro's [http://ubiquity-firefox.googlegroups.com/web/diggthis.js diggthis command])
* Reddit/Mixx
* Del.icio.us (e.g. "delic this" or "delic this with tag1 tag2 tag3")
* Turn referencing friend feed comments and tweets on a page (defaulted to the current page) into page annotations via command "show conversations"
* Integration with Jaiku, Plurk, Pownce, and other microblogging services (not only with Twitter)
* Integration with Google Docs and Google Notebook
* Command to send selected text to tinypaste.com and/or <strike>shorttext.com</strike> ([http://shortText.com/ Commands 'shorttext', 'longtext'] now available), pastebin.com, cl1p.net etc.
* Subscribe to current site's feed via Google Reader or other RSS reader
* Add to Google Bookmarks
* Easily control [http://www.bitlet.org BitLet.org]
* Add torrents with [http://www.azureuswiki.com/index.php/HTML_WebUI Azureus' HTML WebUI]. => this can be done with Greasemonkey already
* Geotag flickr photos easily (see [http://labs.sumaato.net/tools/flickr_geocode_bookmarklet/ Localize Bookmarklet])
* Take highlighted thread, and paste it in a forum. Because of the amount of forums, it might be better to just have a template for each forum type.
* Evernote command (post this page/text to evernote) suggested by Ben [http://groups.google.com/group/ubiquity-firefox/browse_thread/thread/68d7f5d7f817c4d5?hl=en here]
* Adobe Buzzword integration
* tempomail / jetable (temp mail address) integration. Implemented. See [http://gist.github.com/11261 Jetable]
* Horde email/calendar
* SMS Messaging. Text-message content to a contact or phone number. Could integrate with an existing service such as: http://smseverywhere.com/send.htm
* Set tv recording. For those people using mythtv / myth* or a TiVo with a web front-end, if you saw a show on some web site, like tvrage or any channel that shows tv-listings, highlight the show, and say 'record this'. This would probably be very dependent on your specific web front-end / TVR hardware.
*integrate into MySpace. command such as "send this to (myspace contact): (selected text or image, maybe even if your on youtube, it will automatically imbed.)" Another could be "set headline as (selected text or input)"
* Integrate with [http://www.squirrelmail.org/ SqirrelMail]
* Integrate with [http://roundcube.net/ RoundCube Mail]
* Integrate with [http://sourceforge.net/projects/scuttle/ Scuttle Bookmarks]
* Integrate with [http://webcalendar.sourceforge.net/ WebCalendar]
* Integrate with [http://www.rememberthemilk.com/ Remember The Milk]. Add tasks, get list of tasks, mark tasks as completed, etc. They have a really rich API. (Adding tasks is done: [http://garyhodgson.com/ubiquity/rtm.html here], with a more advanced version [http://garyhodgson.com/ubiquity/rtm-wip.html in progress].)
* Integrate with [http://www.toodledo.com/ Toodledo] in a similar way to that described for RTM
* [http://www.facebook.com Facebook] status setting-resetting integration. Ping.fm has been implemented but there are users (like me) that prefer to use only one social networking site, hence they don't need a ping.fm account. (already done [http://home.comcast.net/~captainbeah/ubiquity/facebook/ here])
* Integrate with [http://www.me.com/ MobileMe] to allow similar email and calendar editing integration as for the Google equivalents (GMail etc.)
* Integrate with [http://www.ryanair.com/ Ryanair] to allow searching for flights using Ubiquity.
* Subscribe with Bloglines
* Integrate with Google Apps (Gmail, Calendar) [http://www.google.com/apps/] to allow using the standard commands

==Extension Integration==
* PasswordMaker: http://passwordmaker.org/
* BlueOrganizer (be inspired by [https://addons.mozilla.org/en-US/firefox/addon/3481 this addon] and it's somewhat semantic knowledge)
* Take inspiration from [https://addons.mozilla.org/en-US/firefox/addon/1407 Clipmarks]
* Firebug integration, inspect DOM-Reference, show firebug net panel
* Media player control similar to [https://addons.mozilla.org/en-US/firefox/addon/219 FoxyTunes]
* AnyColor integration -- https://addons.mozilla.org/en-US/firefox/addon/6991
* Faviconize -- A command called Fav [open tab] to change it's state from showing/hiding title
* Commands for Screen grab! extension
* Undo Closed Tabs Button feature like the extension of that name. (Note: this is built into Firefox 3.0, no need for this extension anymore)
* Adblock Plus integration, along with NoScript.
* Ability to inject Webslices, for use with Webchunks.
* Fast Dial integration
* Overwrite the window.print command with a less intrusive UI. It would instead pop a notification/toaster ("this site wants to print itself. _Print_").
* Greasemonkey integration: "greasemonkey-edit <userscript>". It would autocomplete the userscript name based on the list of installed userscripts.
* Cool iris functionality with a image flow.

==Finished Commands==
* [http://shortText.com/ shortText.com] done. Create a URL of any selected text by using command 'shorttext' or expand a shortText URL to its full content by using command 'longtext'
* [http://www.google.com/sitesearch/ Google Site Search] integration. (Example: "search komplett.ie for cpu coolers") [http://mysite.verizon.net/zaduma/ Done]
* Metacritic (metacritic.com) review searching - [http://mysite.verizon.net/zaduma/ Done]
* Torrent search [http://mysite.verizon.net/zaduma/ Done]
* Reveal the exact URL-s behind tinyurl-s (see [http://ghill.customer.netspace.net.au/embiggen/ Embiggen Bookmarklet]) [http://mysite.verizon.net/zaduma/ Done]
* BugMeNot lookup for current page [http://www.geocities.com/lemming4242 Done]
* Open command (select multiple links, then open them all in tabs) [http://www.geocities.com/lemming4242/ Done]
* An online bible service command. [http://tim.sorbera.googlepages.com/ubiquity.html Done]
* A command to open a selected URL. [http://tim.sorbera.googlepages.com/ubiquity.html Done]
* Twitter Search - [http://gist.github.com/7594 Done] but could benefit from a sexier UI
* Random number generator. Floating point value with input of the following type: random lower-val higher-val
** Example: Random 0 1; Gives 0.252
** Example: Random 1 100; Gives 275.840
** [http://ubiquitously.org/forum/viewtopic.php?f=4&t=12 Done]
* Go command (for switching between tabs by name) (achieved by the "tab" command builtin to Ubiquity)
* Reopen an existing tab in a new tab. Sometimes you want to search for a new topic (in Wikipedia for example), and you have to re-open a new tab, then copy and paste the current url. Why not have a "re-open" command that lets you create a new tab, and copy the currently opened page over to it? (Alt+D > Alt+Enter currently does this. necessary?) (No. Did it anyways.) [http://ubiquitously.org/forum/viewtopic.php?f=5&t=22 Done]
* Currency conversion [http://ubiquitously.org/forum/viewtopic.php?f=4&t=25 Done]
* Unit conversion [http://ubiquitously.org/forum/viewtopic.php?f=4&t=25 Done (Same as above)]
* Stock quotes [http://ubiquitously.org/forum/viewtopic.php?f=4&t=26 Done]
* A "view source" for Ubiq commands. For example, "view-source link-to-wikipedia" => [https://wiki.mozilla.org/Labs/Ubiquity/Ubiquity_0.1.1_Release_Notes available] in Ubiq 0.1.1, although not as a command.
* Link finder (like the "link-to-wikipedia" command but then, instead of inserting a link to wikipedia, allow the user to find the link from history/bookmarks. This would save a lot of excess work because at the moment, to insert a link, you have to open up a new tab, find the page you want to link to, copy the address and then, go back to add the link) => try [http://blog.monstuff.com/archives/000343.html insert-link]
* Command that takes each search plugin/provider you have in the search-bar (by default, right of the locationbar in IE7 & FF2 & 3, plus more), and turns it into a command you can use. Thus, having search plugin/providers at your fingertips in ubiquity, and adding a search plugin/provider command is just as easy as using already created functionality; This could either be done in the underlying code of Ubiquity, or maybe have it so that the command is done as "Search <Plugin/Provider> <Terms>
** I'm a moron..I actually had a command that did this.[http://theunfocused.net/moz/ubiquity/verbs/?cmd=search]
** Dup: Integration of your installed Firefox search engines.
* Timezone converter - something like "get time in australia" ([https://wiki.mozilla.org/Labs/Ubiquity/Commands_In_The_Wild#Time Done])
* Ping.fm - can potentially replace twitter and facebook-status commands ([http://waleed.doubleudesigns.com/2008/08/ubiquity-and-pingfm/ Done])
* Mibbit IRC (mibbit [server] [optional:channels]) ([http://scguy318.freeshell.org/Mibbit%20Ubiquity%20Script.html Done])
* <tt>google-here <text></tt>: site-search on current site (without typing it explicitly) => ([http://groups.google.com/group/ubiquity-firefox/browse_thread/thread/5c2c80df1c61d4f8 Done])
Can anyone write a command that decodes 2D barcodes in images on a web page?

-I am working on a 2D barcode translator now. I have a standard barcode reader command working: http://devstatus.com ~ matt

*I just finished a simple Woot checker that goes to the "Want One" page on enter: [http://gist.github.com/41227 Woot]
<nowiki>Insert non-formatted text here</nowiki>

Labs/Ubiquity/Ubiquity 0.1 Author Tutorial

2009-01-21T04:42:14Z

Endolith: /* Using CreateCommand */ add link to Ubiquity Code Documentation

Back to [[Labs/Ubiquity]].

Author: Aza Raskin, Blair McBride, Abimanyu Raja, Jono DiCarlo, Atul Varma

== In other languages ==

* [[zh-CN:Ubiquity 0.1 Author Tutoria|简体中文l]]
* [[ja:Ubiquity 0.1.2 User Tutorial|日本語で]]
* [[es:Ubiquity 0.1.2 User Tutorial|En español]]
* [[mr:Ubiquity 0.1.2 User Tutorial|Mr मराठी (Marathi)]]
* [[Labs/Ubiquity/hi:Ubiquity 0.1.2 User Tutorial|Hi हिंदी (Hindi)]]

If English isn't your first language feel free to read the tutorial in your own language. If it doesn't exists, feel free to jump in and translate.

= The Ubiquity 0.1 Command Tutorial =

The great power of Ubiquity—from a developer standpoint—is how easy it is to create commands. With only a couple of lines of Javascript, Ubiquity enables even casual web developers to drastically enhance the features of the browser. From an 8-line command to insert a contact's email address in any text field, to a 50-line Twitter integration, this tutorial walks you through the process of being generative with Ubiquity.

'''WARNING''': Ubiquity is still in flux. This is a 0.1 release. The API is likely to change drastically in later revisions. While this means that what you write today might not work next week, it also means that by writing commands and giving us [[Labs/Ubiquity#Participation|your feedback]], you'll be able to directly influence the direction that Ubiquity goes.

The rest of this page documents the command developer API as it currently stands in the latest released version of Ubiquity, 0.1.1. However, if you have the latest source checkout, then you'll have a newer API with some additional features not in 0.1.1. You can read about the latest and greatest source-tip API on [[Labs/Ubiquity/Ubiquity Source Tip Author Tutorial|Ubiquity Source Tip Author Tutorial]].

== Real Time Development ==

Ubiquity doesn't require you to restart Firefox as you develop. That's a barbaric act, and we want none of it. Instead, Ubiquity reloads the commands every time it is summoned. When you are using the built-in editor then you don't even need to save!

To open the Ubiquity command editor, summon Ubiquity (control/alt + space) and use the "command-editor" command. Throughout this tutorial, when we want you to run a command in Ubiquity, we'll say '''Ubiq''' it. For instance, to open the editor, just Ubiq "command-editor".

In the following examples, just type in this editor. Updates happen the next time you summon Ubiquity.

= Hello World: The First Command =

== Just a Function: As Simple as it Gets ==

Let's start with the standard programing trope: printing "Hello, World!". In Ubiquity, commands are simply functions with various attributes tacked on. We'll start by manually making a function to define a command, but we'll quickly move to using a more elegant method.

In the command editor type the following:

<pre>
function cmd_hello_world() {
displayMessage( "Hello, World!");
}
</pre>

Now try Ubiq-ing "hello-world". You'll see that "Hello, World!" is immediatly displayed on the screen. If you are on Mac OSX with [http://en.wikipedia.org/wiki/Growl_(software) Growl] installed the message will appear as a Growl notification. If you are on Windows, then it will appears as a standard "toaster" notification in the bottom right-hand corner of the screen.

http://img367.imageshack.us/img367/7051/picture1ui2.png

http://img517.imageshack.us/img517/7726/picture2vx2.png

In Ubuntu 8.04 (Hardy Heron) this appears thus:

http://img293.imageshack.us/img293/7746/ubiqubuntuhelloworldeq9.png

If you don't have Growl installed on OSX, or aren't on a Windows XP/Vista or Ubuntu Hardy/Intrepid, then you won't get any sort of notification. That's something to be [http://labs.toolness.com/trac/ticket/19 worked on] in future released of Ubiquity.

There's not much in this command, so let's dive straight in. Any function that starts with <code>cmd_</code> automatically becomes a Ubiquity command. It's a little bit of namespace magic that makes development super-simple.

There are other prefixes that have other effects, like running code on page load (<code>pageLoad_</code>), and startup (<code>startup_</code>), but that's for a different tutorial.

Back to the example. The meat of the command is in the function <code>displayMessage()</code>, which displays the message in whichever way the operating system can.

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 and 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:

<pre>
CmdUtils.CreateCommand({
name: "hello-world",
execute: function() {
displayMessage( "Hello, World!" );
}
})
</pre>

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—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 ==

http://img352.imageshack.us/img352/1002/picture3ex0.png

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."

<pre>
CmdUtils.CreateCommand({
name: "hello-world",
preview: "Displays a salutary greeting to the planet.",
execute: function() {
displayMessage( "Hello, World!" );
}
})
</pre>

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.

<pre>
CmdUtils.CreateCommand({
name: "date",
execute: function() {
var date = new Date();
CmdUtils.setSelection( date.toLocaleDateString() );
}
})
</pre>

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>toLocalDateString()</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].

== A Better Preview ==

It's time to add a better preview to the date command. Let's have the preview show the date, so that the user will know what to expect when they execute the command. (As a side benefit the user doesn't even need to execute the command to do a quick check of the day.)

<pre>
CmdUtils.CreateCommand({
name: "date",

_date: function(){
var date = new Date();
return date.toLocaleDateString();
},

preview: function( pblock ) {
var msg = 'Inserts todays date: "${date}"';
pblock.innerHTML = CmdUtils.renderTemplate( msg, {date: this._date()} );
},

execute: function() {
CmdUtils.setSelection( this._date() );
}
})
</pre>

We've done two things here. The first was to factor out the code for getting the date into the <code>_date()</code> function. This way we don't break [http://en.wikipedia.org/wiki/Don%27t_repeat_yourself DRY] by repeating code across the preview and execute functions. Notice that to access the <code>_date()</code>, we use the <code>this</code> keyword.

The second thing we've done is to add a preview function. The first argument is the DOM element that gets displayed as the preview for your command. Modify <code>pblock</code> and you modify the preview. In this case, we set the <code>innerHTML</code> of the preview block to be the message we want.

The other thing I've done is to do some string formatting using the <code>renderTemplate()</code> function. This takes a template string and performs the appropriate substitution given the passed-in JSON object. Templates can handle a wide range of functionality, as we are currently using TrimPath's [http://code.google.com/p/trimpath/wiki/JavaScriptTemplates JavascriptTemplates]. You should read their site for more documentation. Although JavascriptTemplates has some nice properties, we are contemplating moving to [http://mjtemplate.org/ MJT] sometime soon.

Previews display something meaningful to the user immediately. If you have a preview that requires an AJAX request—say, to fetch some search results—that call might take a while to return. In the meantime, your command should display a placeholder preview giving the user feedback.

<pre>
preview: function( pblock ) {
pblock.innerHTML = "This will show until the AJAX request returns";
// AJAX request
pblock.innerHTML = getFromServer();
},
</pre>

In the future, we may work on streamlining this process.

== Documentation and Metadata ==

Before you share your command with the world, you should consider adding some attributions to the code:

<pre>
CmdUtils.CreateCommand({
name: "date",
homepage: "http://azarask.in/",
author: { name: "Aza Raskin", email: "aza@mozilla.com"},
contributors: ["Atul Varma"],
license: "MPL",

/* THE REST OF THE CODE HERE */
})
</pre>

And you should definitely add some documentation:

<pre>
CmdUtils.CreateCommand({
name: "date",
homepage: "http://azarask.in/",
author: { name: "Aza Raskin", email: "aza@mozilla.com"},
contributors: ["Atul Varma"],
license: "MPL",
description: "Inserts today's date.",
help: "If you're in an editable text area, inserts today's date, formatted for the current locale.",

/* THE REST OF THE CODE HERE */
})
</pre>

The <code>.description</code> and <code>.help</code> attributes are both automatically displayed alongside your command's name on the command-list page. (The user can get to this page at any time by issuing the "command-list" command.) HTML tags can be used in both of these strings.

Description is a one-line summary of what the command does, while Help is a longer description that can include examples, caveats, and so on. If your command is simple enough that all you have to say about it fits in one line, it's OK to use a description alone and leave out the help.

== Sharing it with the World ==

Now that we've got our awesome new "date" command, let's share it with the world. All you have to do is put it the javascript file on the web somewhere, and make an html page linking to it with "link rel".

<pre><link rel="commands" href="http://path-to-js" name="Title Goes Here" /></pre>

''Note: your webserver must serve .js files as 'application/x-javascript'. The mime-type 'text/javascript' is silently ignored.
''

Anyone with Ubiquity who visits will get a message offering them the choice of subscribing to your command.

[[Image:Subscribe.png]]

If the user chooses to subscribe to a command from an untrusted source, they will get a security warning message before they can install the command. (And in Ubiquity 0.1, ALL sources are considered untrusted, so don't take it personally!) Because Ubiquity commands can execute arbitrary javascript with chrome privileges, subscribing to a command from a website means allowing that site full access to do whatever it wants to your browser. We want to make sure people understand the dangers before subscribing to commands, so we made the warning page pretty scary.

[[Image:Warning.PNG]]

In the future, we're going to have something set up that we call a "trust network". When you try out a Ubiquity command from a website, and determine that the command is safe (or unsafe), you'll be able to leave an approval (or a warning). When your friends with Ubiquity installed visit the same site, they'll see the approval or the warning that you left. In this way, users will be able to rely on the judgement of other people they already know and trust in order to help them make decisions about whether a command is safe to install or not.

By the way, the reason we call it "subscribing" to a command, rather than "installing" a command, is that if the javascript file changes -- if the site owner adds new commands, removes old commands, or updates existing commands -- all users subscribed to that URL will automatically get the updates. This will be very convenient for both users and developers, but it will also introduce another type of security risk: just because you decided a command was safe at one point in time doesn't mean that the command will always remain safe. For this reason, we'll need to make sure that the trust network keeps track of when commands have been modified, and notifies users of changes that may make a command unsafe.

== Map Me! Location, Snapshots, and Inserting HTML ==

The "map" command that comes with Ubiquity is fairly powerful. It's also fairly complicated—well, comparatively. It's still only a couple hundred lines of code. The command, though, can get even more useful. Imagine being able to select some houses on Craigslist, or a list of restaurant names, and Ubiq "map these" to get just the map you want. The concept of "these" puts the power of mashups into the users hands. But I digress. Let's make a simple command that inserts a map of your current location.

In this command, we use the Google [http://code.google.com/apis/maps/documentation/staticmaps/ static map API] and the Ubiquity function <code>CmdUtils.getGeoLocation()</code> to insert a map of your current location. Ubiquity currently uses the [http://www.maxmind.com/app/api MaxMind] API for trying to guess your location from your IP. That will probably change in the future.

<pre>
CmdUtils.CreateCommand({
name: "map-me",

_getMapUrl: function() {
var loc = CmdUtils.getGeoLocation();
var mapUrl = "http://maps.google.com/staticmap?";

var params = {
center: loc.lat + "," + loc.long,
size: "500x400",
zoom: 14,
key: "ABQIAAAAGZ11mh1LzgQ8-8LRW3wEShQeSuJunOpTb3RsLsk00-MAdzxmXhQoiCd940lo0KlfQM5PeNYEPLW-3w"
};

return mapUrl + jQuery.param( params );
},

preview: function( pblock ) {
var msg = "Inserts a map of your current location: ";
msg += "<img src='%s'/>".replace( /%s/, this._getMapUrl() );
pblock.innerHTML = msg;
},

execute: function( ) {
CmdUtils.getImageSnapshot( this._getMapUrl(), function(imgData) {
CmdUtils.setSelection( "<img src='" + imgData +"'/>");
})
}
})
</pre>

There are three new things here: <code>CmdUtils.setSelection</code> to set HTML (yep, it can do that); the use of <code>CmdUtils.getGeoLocation()</code>; and using <code>CmdUtils.getImageSnapshot()</code> to capture the bits for the image.

I find getting the location—as imprecise as IP-based location can be—useful for doing sensible defaults for location-based commands, like Yelp. <code>CmdUtils.getGeoLocation()</code> returns an object which has the following properties: city, state, country, lat, and long.

Why do we need to use <code>CmdUtils.getImageSnapshot()</code>? Because the Google Maps API requires a key that is tied to a particular URL. If we naively inject the image tag into a random web page, the image won't load because the key doesn't match that random web page's URL. Thus, we use the <code>snapshotImage()</code> function to convert the image into a [http://en.wikipedia.org/wiki/Data:_URI_scheme data url].

There's also a <code>CmdUtils.getWindowSnapshot()</code> function, which allows you to get the image data for any tab/window. The function takes a window as the first paramater, and a callback for the second.

= Commands with Arguments =

== Echo ==

We'll be working towards making some fun and useful commands—commands that let you control the seething tendrils of the internet with your little pinky. But, let's start by making a simple command to echo back whatever you type.

<pre>
CmdUtils.CreateCommand({
name: "echo",
takes: {"your shout": noun_arb_text},
preview: function( pblock, theShout ) {
pblock.innerHTML = "Will echo: " + theShout.text;
},
execute: function( theShout ) {
var msg = theShout.text + "... " + theShout.text + "......";
displayMessage( msg );
}
})
</pre>

This says that the command "echo" takes one argument which is arbitrary text. Whatever text the user enters will get wrapped in an input object and passed into both the preview and execute function.

Ubiquity takes care of parsing the user's input, so you don't need to worry about handling prounoun substitution or any of the other natural-language-like features of the Ubiquity parser. Try selecting some text on a page, and Ubiq "echo this". Ubiquity should now echo the selected text.

=== The Input Object ===

The input object that your execute and preview functions receive has the following attributes:

<pre>
inputObject.text // a string of the input in plain text, without formatting
inputObject.html // a string of the input in formatted html, including tags
inputObject.data // for non-text input types, an arbitrary data object
inputObject.summary // for very long inputs, an abbreviated display string
</pre>

Our example command only cares about the <code>.text</code> attribute of the input, because it simply wants plain text. Often, when the user invokes your command by typing a few short words into the input box, <code>.text</code>, <code>.html</code>, and <code>.summary</code> will all have exactly the same value, and <code>.data</code> will be null. Many, if not most, commands that you write will only care about the text value. Nevertheless, the other versions of the input data are provided to you in case they differ from <code>.text</code> and in case your command has a use for them.

=== Introduction to Noun Types ===

Notice that we specified the type of argument to expect by passing in an object — 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).

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.

There are many types of nouns that a command could conceivably take: people, dates, places, tabs, etc. Many of these noun-types aren't implemented yet, and most of the them currently have a lack-luster implementation. This is one of the areas where Ubiquity could use the greatest help. Noun-types enable creating compelling user experiences, with minimal amounts of code. It also allows for code-reuse across numerous commands.

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 — and then come [[Labs/Ubiquity#Participation|get involved]] to help us improve them.

== Insert Email: Commands with Specific Argument Types ==

Let's take a look at one of the special noun-types: <code>noun_type_contact</code>. This lets Ubiquity know to expect a person (either by name or email address). By using the noun-type, Ubiquity will also autocomplete to known people while the user is entering the command. This is what the built-in Ubiquity command "email" uses.

At the moment, Ubiquity figures out what people you know through reading your Gmail contacts. In this prototyped version, you'll need to use Gmail and be logged in for for Ubiquity to know who you know. Eventually, we'd like to be able to interface with all major web-mail sites, as well as desktop software like Thunderbird.

Enough rambling. It's time for a command. I constantly find that I need to fetch someone's email address to paste into a text field because I don't know it off-hand. This command solves that by letting you insert someone's email address using autocomplete.

<pre>
CmdUtils.CreateCommand({
name: "insert-email",
takes: {"person": noun_type_contact},
preview: "Inserts someone's email address by name.",
execute: function( email ) {
CmdUtils.setSelection( email.text );
}
})
</pre>

This one command sums up what I love about Ubiquity. In 8 lines of code, I can fundamentally enhance the browser's functionality. Doing the same thing using a normal Firefox extension methodology takes pages and pages of code—and the interface would take more thought still. Doing the same thing using a bookmarklet would require a server-side component (to get around cross-site Ajax request ban) as well as forcing the user to give up their email password.

Ubiquity increases the surface area of innovation for the browser many-fold, by making anyone who can write simple Javascript into an agent for bettering the browser and the open Web.

== TinyURL: Network Calls and jQuery ==

Often while writing emails, I'll discover that I've pasted in a URL long enough to be used for unfortunate analogies. I'd like to be able to quickly turn that into a [http://en.wikipedia.org/wiki/Tinyurl TinyURL]—but the process of making a TinyURL involves lots of fiddly steps. Ubiquity to the rescue.

Because we include [http://en.wikipedia.org/wiki/jQuery jQuery] with Ubiquity, it is simple to perform Ajax calls as well as parse returning data. TinyUrl.com provides an easy to use RESTful API where you pass a URL and it returns its shortened form. We use that API in this command.

<pre>
CmdUtils.CreateCommand({
name: "tinyurl",
takes: {"url to shorten": noun_arb_text},
preview: "Replaces the selected URL with a TinyUrl.",
execute: function( urlToShorten ) {
var baseUrl = "http://tinyurl.com/api-create.php";
var params = {url: urlToShorten.text};
jQuery.get( baseUrl, params, function( tinyUrl ) {
CmdUtils.setSelection( tinyUrl );
})
}
})
</pre>

Although I used the <code>noun_arb_text</code> command noun-type, I should have used the <code>noun_type_url</code>—if such a thing existed. It doesn't yet.

jQuery is a powerful tool. With it, you can fairly effortlessly cherry-pick the data you need from RSS feeds, XML, and all sorts of other data formats. It also makes doing in-preview animations a breeze.

== Color: Creating Bounded Noun Types ==

Suppose you're writing a set of commands for artists and
web designers, and you know that several of the commands will operate
on colors. You'd like to be able to specify that certain commands
expect names of colors as arguments. Since there are a finite number of
named colors, you can define a custom noun type for them based on a list
of strings, like so:

<pre>
noun_type_color = new CmdUtils.NounType( "Color",
["red", "orange", "yellow", "green", "blue", "violet", "black", "white",
"grey", "brown", "beige", "magenta", "cerulean", "puce"] // etc...
);
</pre>

Note that we gave the new object a name starting with "<code>noun_</code>".
The Ubiquity command loader automatically detects objects starting with
"<code>noun_</code>" as custom noun-types, in the same way as it auto-detects
functions starting with "<code>cmd_</code>" as custom commands.

Once you've defined a custom noun-type, you can use it in as many commands
as you like, thus:

<pre>
CmdUtils.CreateCommand({
name: "get-color-code",
takes: {"color": noun_type_color},
preview: "Inserts the HTML hex-code for the given color.",
// etc...
</pre>

One benefit of creating the custom color noun-type is that if the user
has entered "get-color bl", for instance, Ubiquity will be able to suggest
"black" and "blue" as the two valid completions based on the input.

Of course, not every type of noun you'd be interested in can be represented
as a finite list. If you want to be able to accept or reject input based
on some algorithmic test, you can do so by creating your own noun-type
implementation instead of instantiating <code>CmdUtils.NounType</code>. There is an example of this in the section on the tab commands, below.

== Replace: Commands With Multiple Arguments ==

Commands, like the translate command, can take multiple (and possibly optional) arguments. Ubiquity takes care of the parsing—you don't have to worry about what order the user types them in, you'll just get passed a dictionary with the appropriate entries.

To illustrate that, let's make a simple regular-expression-based "replace" command. It will take three arguments: the thing to replace, the replacement, and the scope-text to do the replacing in. Here's the command:

<pre>
CmdUtils.CreateCommand({
name: "replace",
takes: {"what": noun_arb_text},
modifiers: {"with": noun_arb_text, "in": noun_arb_text},

preview: function( pblock, what, mods ) {
// args contains .with and .in, both of which are input objects.
var msg = 'Replaces "${whatText}" with ${withText} in ${inText}.';
var subs = {whatText: what.text, withText: mods["with"].text, inText: mods["in"].text};

pblock.innerHTML = CmdUtils.renderTemplate( msg, subs );
},

execute: function( what, mods ) {
// If the scope text isn't specified, use the current selection.
var text = mods["in"].text || CmdUtils.getSelection();
var newText = text.replace( what.text, mods["with"].text, "i");
CmdUtils.setSelection( newText );
}
});

</pre>

(In earlier prototypes, modifier arguments could only accept a single-word value, but this has now been fixed.)

The modifiers argument takes a dictionary, where the key is the name of the argument and the value is the noun-type of the argument. In later releases we may include further options, like the ability to specify an argument as required/optional, etc.

The translate command is a good place to learn more about modifiers and the <code>noun_type_language</code>.

= Twitter: Putting It All Together =

We've now covered everything we need to cover in order to write a command that allows us to [http://en.wikipedia.org/wiki/Twitter Twitter] from Ubiquity. Many thanks to [http://theunfocused.net/ Blair McBride] for writing this command. This is a fully functioning command: the browser takes care of the odd edge cases, like not being logged in.

<pre>
// max of 140 chars is recommended, but it really allows 160
const TWITTER_STATUS_MAXLEN = 160;

CmdUtils.CreateCommand({
name: "twitter",
takes: {status: noun_arb_text},

homepage: "http://theunfocused.net/moz/ubiquity/verbs/",
author: {name: "Blair McBride", homepage: "http://theunfocused.net/"},
license: "MPL",

preview: function(previewBlock, statusText) {
var previewTemplate = "Updates your Twitter status to: " +
"${status} " +
"Characters remaining: ${chars}";
var truncateTemplate = " The last ${truncate} " +
"characters will be truncated!";
var previewData = {
status: statusText.text,
chars: TWITTER_STATUS_MAXLEN - statusText.text.length
};

var previewHTML = CmdUtils.renderTemplate(previewTemplate,
previewData);

if(previewData.chars < 0) {
var truncateData = {
truncate: 0 - previewData.chars
};

previewHTML += CmdUtils.renderTemplate(truncateTemplate,
truncateData);
}

previewBlock.innerHTML = previewHTML;
},

execute: function(statusText) {
if(statusText.text.length < 1) {
displayMessage("Twitter requires a status to be entered");
return;
}

var updateUrl = "https://twitter.com/statuses/update.json";
var updateParams = {
source: "ubiquity",
status: statusText.text
};

jQuery.ajax({
type: "POST",
url: updateUrl,
data: updateParams,
dataType: "json",
error: function() {
displayMessage("Twitter error - status not updated");
},
success: function() {
displayMessage("Twitter status updated");
}
});
}
});
</pre>

= Switching Tabs =

The final command in this tutorial is for switching between tabs. The end goal is this: type a few keys to that matches the title of an open tab (in any window), hit return, and you've switched to that tab.

We'll write this command in two steps. The first step is creating a tab noun-type. The second step is using that noun-type to create the tab-switching command.

== Switching: Writing your own Noun-Types ==

A noun-type needs to only have two things: A name and a suggest function. Soon, we'll probably move to having a convenience <code>CmdUtils.CreateNounType()</code>, which will simplify things even more.

The name is what shows up when the command prompts for input. Suggest returns a list of input objects, each one containing the name of a matching tab. We're using [http://developer.mozilla.org/en/docs/FUEL FUEL] to interact with the browser, which is where the "Application" variable comes from.

<pre>
var noun_type_tab = {
_name: "tab name",

// Returns all tabs from all windows.
getTabs: function(){
var tabs = {};

for( var j=0; j < Application.windows.length; j++ ) {
var window = Application.windows[j];
for (var i = 0; i < window.tabs.length; i++) {
var tab = window.tabs[i];
tabs[tab.document.title] = tab;
}
}

return tabs;
},

suggest: function( text, html ) {

var suggestions = [];
var tabs = noun_type_tab.getTabs();

//TODO: implement a better match algorithm
for ( var tabName in tabs ) {
if (tabName.match(text, "i"))
suggestions.push( CmdUtils.makeSugg(tabName) );
}

// Return a list of input objects, limited to at most five:
return suggestions.splice(0, 5);
}
}
</pre>

The suggest method of a noun type always gets passed both text and html. If the input is coming from a part of a web page that the user has selected, these
values can be different: they are both strings, but the html value contains markup tags while the text value does not. The Tab noun type only cares about the plain text of the tab name, so we ignore the value of html.

We use the convenience function <code>CmdUtils.makeSugg()</code> to generate an
input object of the type that the Ubiquity parser expects. The full signature of this function is
<pre>
CmdUtils.makeSugg( text, html, data );
</pre>
but html and data are optional and need be provided only if they differ from text.

If the text or html input is very long, <code>makeSugg()</code> generates a summary for us, and puts it in the <code>.summary</code> attribute of the input object.

We could have accomplished mostly the same thing without calling <code>makeSugg()</code> by returning a list of anonymous objects like these:
<pre>
{ text: tabName,
html: tabName,
data: null,
summary: tabName };
</pre>

The input objects that our <code>.suggest()</code> method generates are the same objects that will eventually get passed in to the <code>execute()</code> and <code>preview()</code> methods of any commands that use this noun type.

== Switching Tabs: The Command ==

Now that we are armed with the tab noun-type, it is easy to make the tab-switching command. Again, we use FUEL to focus the selected tab.

<pre>
CmdUtils.CreateCommand({
name: "tab",
takes: {"tab name": noun_type_tab},

execute: function( directObj ) {
var tabName = directObj.text;
var tabs = noun_type_tab.getTabs();
tabs[tabName]._window.focus();
tabs[tabName].focus();
},

preview: function( pblock, directObj ) {
var tabName = directObj.text;
if( tabName.length > 1 ){
var msg = "Changes to %s tab.";
pblock.innerHTML = msg.replace(/%s/, tabName);
}
else
pblock.innerHTML = "Switch to a tab by name.";
}
})
</pre>

= Development Hints =

You now know all you need to know to get started developing useful Ubiquity commands of your own.

Here are some miscellaneous tips that didn't fit elsewhere on this page, that may make development easier for you.

== The Source Code of Built-In Commands ==

Looking at the source code of built-in commands and built-in noun types can be a very useful aid to development. If you have the source checkout of Ubiquity (see [https://wiki.mozilla.org/index.php?title=Labs/Ubiquity/Ubiquity_0.1_Development_Tutorial the development tutorial] to find out how to get this), the source code can be found in the files and directories:

ubiquity/standard-feeds/
ubiquity/builtin-feeds/en/builtincmds.js
ubiquity/feed-parts/header/en/nountypes.js

If you don't have a checkout of the source code, you can view the latest version on the web here:

[http://hg.toolness.com/ubiquity-firefox/file/tip/ubiquity/standard-feeds/ standard-feeds]
[http://hg.toolness.com/ubiquity-firefox/file/tip/ubiquity/builtin-feeds/en/builtincmds.js builtincmds.js]
[http://hg.toolness.com/ubiquity-firefox/file/tip/ubiquity/feed-parts/header/en/nountypes.js nountypes.js]

== Interacting with Other Extensions ==

http://img363.imageshack.us/img363/1906/picture7cm5.png

There isn't much to say here besides that it's easy. For example, here's a command (thanks to [http://foyrek.com/lyrics.html Abimanyu Raja] for writing this code) that finds the lyrics for a song. You can simply Ubiq something like "get-lyrics wild international" but the command will also interface with the FoxyTunes extension (if it is installed) and add the currently playing song to the suggestion list. Interfacing with other extensions, too, is easy because you can view the source code for every Firefox extension.

<pre>
var noun_type_song = {
_name: "song name",
suggest: function( text, html ) {
var suggestions = [CmdUtils.makeSugg(text)];
if(window.foxytunesGetCurrentTrackTitle){
suggestions.push(CmdUtils.makeSugg(window.foxytunesGetCurrentTrackTitle()));
}
return suggestions;
}
}

CmdUtils.CreateCommand({
name: "get-lyrics",
takes: {song: noun_type_song},
preview: function(pblock, directObject) {

searchText = jQuery.trim(directObject.text);
if(searchText.length < 1) {
pblock.innerHTML = "Searches for lyrics of the song";
return;
}

var previewTemplate = "Searches for the lyrics of ${query}";
var previewData = {query: searchText};
pblock.innerHTML = CmdUtils.renderTemplate(previewTemplate, previewData);

},
execute: function(directObject) {
var url = "http://www.google.com/search?q={QUERY}"
var query = directObject.text + " lyrics";
var urlString = url.replace("{QUERY}", query);
Utils.openUrlInBrowser(urlString);
}
});
</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 ==

In order to run some code on page load, you simply have to prefix your function with <code>pageLoad_</code>. For example, if you want to say "Hi" every time a page is loaded, your code would look like this:

<pre>
function pageLoad_hi(){
displayMessage("hi");
}
</pre>

If you modify the function and want to see the changes, remember to first invoke Ubiquity. Although your function like above, might not be a Ubiquity command, this is necessary to refresh the cached code.

Similarly, if you want to run some code everytime Firefox starts up, you just have to prefix the function with <code>startup_</code> .

The awesome thing about these functions is the ability to develop whole Firefox extensions (that require minimal UI) as Ubiquity plugins in lesser lines of code. You don't need to worry about chrome.manifest or install.rdf. Another added benefit is that you never have to restart your Firefox during development unless of course, you are running code on Firefox startup.

<center>http://img388.imageshack.us/img388/3086/picture5eo9.png</center>

Here's the code for [http://foyrek.com/commands/keyscape.js Keyscape] which is a Ubiquity command that makes use of <code>pageLoad</code> and <code>startup</code> to recreate the functionality of the [https://addons.mozilla.org/en-US/firefox/addon/339 Search Keys extension] by Jesse Ruderman. In line with Ubiquity's aim to let you do things quicker using your keyboard, this command lets you go to search results on Google by just pressing a number. It'll add hints to show the number of each link.

<pre>
//A lot of this code is borrowed from the Search Keys extension
//Many thanks to Jeese Ruderman

function startup_keyscape() {
window.addEventListener("keydown", keyscape_down, true);
}

function pageLoad_keyscape(doc){

var uri = Utils.url(doc.documentURI);
//If we are on about: or chrome://, just return
if(uri.scheme != "http")
return;

//Check if the page we are on is google
if( keyscape_isGoogle(uri) ){

for(var num=1; num<=10; num++){

var link = jQuery(doc.body).find('a.l')[num-1];

if( link ){

var hint = doc.createElementNS("http://www.w3.org/1999/xhtml", "span");
hint.style.color = "blue";
hint.style.background = "white";
hint.style.padding = "1px 2px 1px 2px";
hint.style.marginLeft = ".5em";
hint.appendChild(doc.createTextNode(num == 10 ? 0 : num));
link.parentNode.insertBefore(hint, link.nextSibling);
}
}
}
}

function keyscape_isGoogle(uri){
return uri.host.indexOf("google") != -1
&& (uri.path.substr(0,8) == "/search?"
|| uri.path.substr(0,8) == "/custom?");
}

function keyscape_down(event){

var doc = Application.activeWindow.activeTab.document;
var uri = Utils.url(doc.documentURI);

if( keyscape_isGoogle(uri) ){

var key = parseInt(event.keyCode || event.charCode);
var num;

if(48 <= key && key <= 57) //number keys
num = key - 48;
else if(96 <= key && key <= 105) //numeric keypad with numlock on
num = key - 96;
else
return;

//Don't do anything if we are in a textbox
//or some other related elements
var elt = window.document.commandDispatcher.focusedElement;

if (elt) {
var ln = new String(elt.localName).toLowerCase();
if (ln == "input" || ln == "textarea" || ln == "select" || ln == "isindex")
return;
}

//Get the link url from the search results page
var url_dest = jQuery(doc.body).find('a.l').eq(num-1).attr('href');

if(event.altKey){
//Open in new tab
Application.activeWindow.open(Utils.url(url_dest));
}else{
//Open in same tab
doc.location.href = url_dest;
}
}
}
</pre>

If Ubiquity does indeed become ubiquitous, a lot of extensions can be re-written as Ubiquity commands. This is much nicer for the end-user, as well, because the Ubiquity command installation process is a lot easier.

In the future, Ubiquity is also likely to have the ability to convert your Ubiquity commands into proper Firefox extensions. Look [http://labs.toolness.com/trac/ticket/3 here] to check on the progress of this functionality.

== Firebug ==

You should enable Chrome Errors and Warnings if you want the errors in your code to appear in the Firebug console. Use CmdUtils.log() rather than console.log() ''Note: For now, you can only pass one argument to log()''

== Adding Commands Programmatically ==

Here is a snippet of code that shows how a developer can programmatically register a command included in a Firefox extension.

<pre>

// Helper function used to determine the local directory where the
// extension which contains the command is installed. This is used
// to create the URL of the js file which includes the implementation
// of the list of commands you want to add.
function getExtensionDir() {
var extMgr = Components.classes["@mozilla.org/extensions/manager;1"]
.getService(Components.interfaces.nsIExtensionManager);
return extMgr.getInstallLocation( "feedly@devhd" ).getItemLocation( "feedly@devhd" );
}

function getBaseUri() {
var ioSvc = Components.classes["@mozilla.org/network/io-service;1"]
.getService(Components.interfaces.nsIIOService);
var extDir = getExtensionDir();
var baseUri = ioSvc.newFileURI(extDir).spec;
return baseUri;
}

// your extension needs to call the addUbiquity command each time a new browser
// session is create and your extension is loaded.
function addUbiquityCommands(){
// url of the file which contains the implementation of the commands
// we want to add.
var url = getBaseUri() + "content/app/ubiquity/commands.js"

// link to the ubiquity setup module.
var jsm = {};
Components.utils.import("resource://ubiquity/modules/setup.js", jsm);

// look up the feed manager and add a new command. Note: we are using the
// isBuiltIn=true option so that the command is only added for the duration
// of the browser session. This simplifies the overall lifecycle: if the
// extension is disabled or un-installed, it will be automatically
// "removed" from ubiquity.
jsm.UbiquitySetup.createServices().feedManager.addSubscribedFeed( {
url: url,
sourceUrl: url,
canAutoUpdate: true,
isBuiltIn: true
});
}
</pre>

Inside your command implementation, you can use importing modules or looking up a singleton XPCOM component to link your command back to the functionality encapsulated by your extension. Here is a sample command which does that:

<pre>
var StreetsUtils = function(){
var that = {};
that.lookupCore = function(){
return Components.classes["@devhd.com/feedly-boot;1"]
.getService(Components.interfaces.nsIFeedlyBoot)
.wrappedJSObject
.lookupCore();
};
return that;
}();

CmdUtils.CreateCommand({
name: "my-extension-test",
takes: {"message": noun_arb_text},
icon: "chrome://my-extension-test/skin/icon-16x16.png",
modifiers: {to: noun_type_contact},
description:"Testing the feedly+ubiquity integration",
help:"This is a test help message",
preview: function(pblock, directObj, modifiers) {
var html = "Testing my-extension-test ";
if (modifiers.to) {
html += "to " + modifiers.to.text + " ";
}
if (directObj.html) {
html += "with these contents:" + directObj.html;
} else {
html += "with a link to the current page.";
}
pblock.innerHTML = html;
},

execute: function(directObj, headers) {
CmdUtils.log( ">>> my-extension core? " + ( StreetsUtils.lookupCore() != null ) );
}
});
</pre>

Note: If you command file needs to include/load other JS files included in your extension, you can use the following piece of code at the top of the command js file you are adding to ubiquity.

<pre>
function include( partialURI )
{
// Load JS libraries
var u = "chrome://feedly/content/app/" + partialURI;
var jsl = Cc["@mozilla.org/moz/jssubscript-loader;1"]
.getService(Ci.mozIJSSubScriptLoader);

jsl.loadSubScript( u );
}

include( "ubiquity/templates.ubiquity.js" );
</pre>

= Conclusion =

To reiterate a point I made before: Ubiquity increases the surface area of innovation for the browser many-fold, by making anyone who can write simple Javascript into an agent for bettering the browser and the open Web. You are one of those agents.

Now, go forth and create.

Labs/Ubiquity/Ubiquity 0.1 Author Tutorial

2009-01-21T04:38:37Z

Endolith: /* Just a Function: As Simple as it Gets */ notifications work in Intrepid, too

Back to [[Labs/Ubiquity]].

Author: Aza Raskin, Blair McBride, Abimanyu Raja, Jono DiCarlo, Atul Varma

== In other languages ==

* [[zh-CN:Ubiquity 0.1 Author Tutoria|简体中文l]]
* [[ja:Ubiquity 0.1.2 User Tutorial|日本語で]]
* [[es:Ubiquity 0.1.2 User Tutorial|En español]]
* [[mr:Ubiquity 0.1.2 User Tutorial|Mr मराठी (Marathi)]]
* [[Labs/Ubiquity/hi:Ubiquity 0.1.2 User Tutorial|Hi हिंदी (Hindi)]]

If English isn't your first language feel free to read the tutorial in your own language. If it doesn't exists, feel free to jump in and translate.

= The Ubiquity 0.1 Command Tutorial =

The great power of Ubiquity—from a developer standpoint—is how easy it is to create commands. With only a couple of lines of Javascript, Ubiquity enables even casual web developers to drastically enhance the features of the browser. From an 8-line command to insert a contact's email address in any text field, to a 50-line Twitter integration, this tutorial walks you through the process of being generative with Ubiquity.

'''WARNING''': Ubiquity is still in flux. This is a 0.1 release. The API is likely to change drastically in later revisions. While this means that what you write today might not work next week, it also means that by writing commands and giving us [[Labs/Ubiquity#Participation|your feedback]], you'll be able to directly influence the direction that Ubiquity goes.

The rest of this page documents the command developer API as it currently stands in the latest released version of Ubiquity, 0.1.1. However, if you have the latest source checkout, then you'll have a newer API with some additional features not in 0.1.1. You can read about the latest and greatest source-tip API on [[Labs/Ubiquity/Ubiquity Source Tip Author Tutorial|Ubiquity Source Tip Author Tutorial]].

== Real Time Development ==

Ubiquity doesn't require you to restart Firefox as you develop. That's a barbaric act, and we want none of it. Instead, Ubiquity reloads the commands every time it is summoned. When you are using the built-in editor then you don't even need to save!

To open the Ubiquity command editor, summon Ubiquity (control/alt + space) and use the "command-editor" command. Throughout this tutorial, when we want you to run a command in Ubiquity, we'll say '''Ubiq''' it. For instance, to open the editor, just Ubiq "command-editor".

In the following examples, just type in this editor. Updates happen the next time you summon Ubiquity.

= Hello World: The First Command =

== Just a Function: As Simple as it Gets ==

Let's start with the standard programing trope: printing "Hello, World!". In Ubiquity, commands are simply functions with various attributes tacked on. We'll start by manually making a function to define a command, but we'll quickly move to using a more elegant method.

In the command editor type the following:

<pre>
function cmd_hello_world() {
displayMessage( "Hello, World!");
}
</pre>

Now try Ubiq-ing "hello-world". You'll see that "Hello, World!" is immediatly displayed on the screen. If you are on Mac OSX with [http://en.wikipedia.org/wiki/Growl_(software) Growl] installed the message will appear as a Growl notification. If you are on Windows, then it will appears as a standard "toaster" notification in the bottom right-hand corner of the screen.

http://img367.imageshack.us/img367/7051/picture1ui2.png

http://img517.imageshack.us/img517/7726/picture2vx2.png

In Ubuntu 8.04 (Hardy Heron) this appears thus:

http://img293.imageshack.us/img293/7746/ubiqubuntuhelloworldeq9.png

If you don't have Growl installed on OSX, or aren't on a Windows XP/Vista or Ubuntu Hardy/Intrepid, then you won't get any sort of notification. That's something to be [http://labs.toolness.com/trac/ticket/19 worked on] in future released of Ubiquity.

There's not much in this command, so let's dive straight in. Any function that starts with <code>cmd_</code> automatically becomes a Ubiquity command. It's a little bit of namespace magic that makes development super-simple.

There are other prefixes that have other effects, like running code on page load (<code>pageLoad_</code>), and startup (<code>startup_</code>), but that's for a different tutorial.

Back to the example. The meat of the command is in the function <code>displayMessage()</code>, which displays the message in whichever way the operating system can.

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 and 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:

<pre>
CmdUtils.CreateCommand({
name: "hello-world",
execute: function() {
displayMessage( "Hello, World!" );
}
})
</pre>

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—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 [http://hg.toolness.com/ubiquity-firefox/file/9a6c9935da9f/ubiquity/chrome/content/cmdutils.js cmdutils.js].

== Adding a Preview ==

http://img352.imageshack.us/img352/1002/picture3ex0.png

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."

<pre>
CmdUtils.CreateCommand({
name: "hello-world",
preview: "Displays a salutary greeting to the planet.",
execute: function() {
displayMessage( "Hello, World!" );
}
})
</pre>

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.

<pre>
CmdUtils.CreateCommand({
name: "date",
execute: function() {
var date = new Date();
CmdUtils.setSelection( date.toLocaleDateString() );
}
})
</pre>

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>toLocalDateString()</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].

== A Better Preview ==

It's time to add a better preview to the date command. Let's have the preview show the date, so that the user will know what to expect when they execute the command. (As a side benefit the user doesn't even need to execute the command to do a quick check of the day.)

<pre>
CmdUtils.CreateCommand({
name: "date",

_date: function(){
var date = new Date();
return date.toLocaleDateString();
},

preview: function( pblock ) {
var msg = 'Inserts todays date: "${date}"';
pblock.innerHTML = CmdUtils.renderTemplate( msg, {date: this._date()} );
},

execute: function() {
CmdUtils.setSelection( this._date() );
}
})
</pre>

We've done two things here. The first was to factor out the code for getting the date into the <code>_date()</code> function. This way we don't break [http://en.wikipedia.org/wiki/Don%27t_repeat_yourself DRY] by repeating code across the preview and execute functions. Notice that to access the <code>_date()</code>, we use the <code>this</code> keyword.

The second thing we've done is to add a preview function. The first argument is the DOM element that gets displayed as the preview for your command. Modify <code>pblock</code> and you modify the preview. In this case, we set the <code>innerHTML</code> of the preview block to be the message we want.

The other thing I've done is to do some string formatting using the <code>renderTemplate()</code> function. This takes a template string and performs the appropriate substitution given the passed-in JSON object. Templates can handle a wide range of functionality, as we are currently using TrimPath's [http://code.google.com/p/trimpath/wiki/JavaScriptTemplates JavascriptTemplates]. You should read their site for more documentation. Although JavascriptTemplates has some nice properties, we are contemplating moving to [http://mjtemplate.org/ MJT] sometime soon.

Previews display something meaningful to the user immediately. If you have a preview that requires an AJAX request—say, to fetch some search results—that call might take a while to return. In the meantime, your command should display a placeholder preview giving the user feedback.

<pre>
preview: function( pblock ) {
pblock.innerHTML = "This will show until the AJAX request returns";
// AJAX request
pblock.innerHTML = getFromServer();
},
</pre>

In the future, we may work on streamlining this process.

== Documentation and Metadata ==

Before you share your command with the world, you should consider adding some attributions to the code:

<pre>
CmdUtils.CreateCommand({
name: "date",
homepage: "http://azarask.in/",
author: { name: "Aza Raskin", email: "aza@mozilla.com"},
contributors: ["Atul Varma"],
license: "MPL",

/* THE REST OF THE CODE HERE */
})
</pre>

And you should definitely add some documentation:

<pre>
CmdUtils.CreateCommand({
name: "date",
homepage: "http://azarask.in/",
author: { name: "Aza Raskin", email: "aza@mozilla.com"},
contributors: ["Atul Varma"],
license: "MPL",
description: "Inserts today's date.",
help: "If you're in an editable text area, inserts today's date, formatted for the current locale.",

/* THE REST OF THE CODE HERE */
})
</pre>

The <code>.description</code> and <code>.help</code> attributes are both automatically displayed alongside your command's name on the command-list page. (The user can get to this page at any time by issuing the "command-list" command.) HTML tags can be used in both of these strings.

Description is a one-line summary of what the command does, while Help is a longer description that can include examples, caveats, and so on. If your command is simple enough that all you have to say about it fits in one line, it's OK to use a description alone and leave out the help.

== Sharing it with the World ==

Now that we've got our awesome new "date" command, let's share it with the world. All you have to do is put it the javascript file on the web somewhere, and make an html page linking to it with "link rel".

<pre><link rel="commands" href="http://path-to-js" name="Title Goes Here" /></pre>

''Note: your webserver must serve .js files as 'application/x-javascript'. The mime-type 'text/javascript' is silently ignored.
''

Anyone with Ubiquity who visits will get a message offering them the choice of subscribing to your command.

[[Image:Subscribe.png]]

If the user chooses to subscribe to a command from an untrusted source, they will get a security warning message before they can install the command. (And in Ubiquity 0.1, ALL sources are considered untrusted, so don't take it personally!) Because Ubiquity commands can execute arbitrary javascript with chrome privileges, subscribing to a command from a website means allowing that site full access to do whatever it wants to your browser. We want to make sure people understand the dangers before subscribing to commands, so we made the warning page pretty scary.

[[Image:Warning.PNG]]

In the future, we're going to have something set up that we call a "trust network". When you try out a Ubiquity command from a website, and determine that the command is safe (or unsafe), you'll be able to leave an approval (or a warning). When your friends with Ubiquity installed visit the same site, they'll see the approval or the warning that you left. In this way, users will be able to rely on the judgement of other people they already know and trust in order to help them make decisions about whether a command is safe to install or not.

By the way, the reason we call it "subscribing" to a command, rather than "installing" a command, is that if the javascript file changes -- if the site owner adds new commands, removes old commands, or updates existing commands -- all users subscribed to that URL will automatically get the updates. This will be very convenient for both users and developers, but it will also introduce another type of security risk: just because you decided a command was safe at one point in time doesn't mean that the command will always remain safe. For this reason, we'll need to make sure that the trust network keeps track of when commands have been modified, and notifies users of changes that may make a command unsafe.

== Map Me! Location, Snapshots, and Inserting HTML ==

The "map" command that comes with Ubiquity is fairly powerful. It's also fairly complicated—well, comparatively. It's still only a couple hundred lines of code. The command, though, can get even more useful. Imagine being able to select some houses on Craigslist, or a list of restaurant names, and Ubiq "map these" to get just the map you want. The concept of "these" puts the power of mashups into the users hands. But I digress. Let's make a simple command that inserts a map of your current location.

In this command, we use the Google [http://code.google.com/apis/maps/documentation/staticmaps/ static map API] and the Ubiquity function <code>CmdUtils.getGeoLocation()</code> to insert a map of your current location. Ubiquity currently uses the [http://www.maxmind.com/app/api MaxMind] API for trying to guess your location from your IP. That will probably change in the future.

<pre>
CmdUtils.CreateCommand({
name: "map-me",

_getMapUrl: function() {
var loc = CmdUtils.getGeoLocation();
var mapUrl = "http://maps.google.com/staticmap?";

var params = {
center: loc.lat + "," + loc.long,
size: "500x400",
zoom: 14,
key: "ABQIAAAAGZ11mh1LzgQ8-8LRW3wEShQeSuJunOpTb3RsLsk00-MAdzxmXhQoiCd940lo0KlfQM5PeNYEPLW-3w"
};

return mapUrl + jQuery.param( params );
},

preview: function( pblock ) {
var msg = "Inserts a map of your current location: ";
msg += "<img src='%s'/>".replace( /%s/, this._getMapUrl() );
pblock.innerHTML = msg;
},

execute: function( ) {
CmdUtils.getImageSnapshot( this._getMapUrl(), function(imgData) {
CmdUtils.setSelection( "<img src='" + imgData +"'/>");
})
}
})
</pre>

There are three new things here: <code>CmdUtils.setSelection</code> to set HTML (yep, it can do that); the use of <code>CmdUtils.getGeoLocation()</code>; and using <code>CmdUtils.getImageSnapshot()</code> to capture the bits for the image.

I find getting the location—as imprecise as IP-based location can be—useful for doing sensible defaults for location-based commands, like Yelp. <code>CmdUtils.getGeoLocation()</code> returns an object which has the following properties: city, state, country, lat, and long.

Why do we need to use <code>CmdUtils.getImageSnapshot()</code>? Because the Google Maps API requires a key that is tied to a particular URL. If we naively inject the image tag into a random web page, the image won't load because the key doesn't match that random web page's URL. Thus, we use the <code>snapshotImage()</code> function to convert the image into a [http://en.wikipedia.org/wiki/Data:_URI_scheme data url].

There's also a <code>CmdUtils.getWindowSnapshot()</code> function, which allows you to get the image data for any tab/window. The function takes a window as the first paramater, and a callback for the second.

= Commands with Arguments =

== Echo ==

We'll be working towards making some fun and useful commands—commands that let you control the seething tendrils of the internet with your little pinky. But, let's start by making a simple command to echo back whatever you type.

<pre>
CmdUtils.CreateCommand({
name: "echo",
takes: {"your shout": noun_arb_text},
preview: function( pblock, theShout ) {
pblock.innerHTML = "Will echo: " + theShout.text;
},
execute: function( theShout ) {
var msg = theShout.text + "... " + theShout.text + "......";
displayMessage( msg );
}
})
</pre>

This says that the command "echo" takes one argument which is arbitrary text. Whatever text the user enters will get wrapped in an input object and passed into both the preview and execute function.

Ubiquity takes care of parsing the user's input, so you don't need to worry about handling prounoun substitution or any of the other natural-language-like features of the Ubiquity parser. Try selecting some text on a page, and Ubiq "echo this". Ubiquity should now echo the selected text.

=== The Input Object ===

The input object that your execute and preview functions receive has the following attributes:

<pre>
inputObject.text // a string of the input in plain text, without formatting
inputObject.html // a string of the input in formatted html, including tags
inputObject.data // for non-text input types, an arbitrary data object
inputObject.summary // for very long inputs, an abbreviated display string
</pre>

Our example command only cares about the <code>.text</code> attribute of the input, because it simply wants plain text. Often, when the user invokes your command by typing a few short words into the input box, <code>.text</code>, <code>.html</code>, and <code>.summary</code> will all have exactly the same value, and <code>.data</code> will be null. Many, if not most, commands that you write will only care about the text value. Nevertheless, the other versions of the input data are provided to you in case they differ from <code>.text</code> and in case your command has a use for them.

=== Introduction to Noun Types ===

Notice that we specified the type of argument to expect by passing in an object — 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).

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.

There are many types of nouns that a command could conceivably take: people, dates, places, tabs, etc. Many of these noun-types aren't implemented yet, and most of the them currently have a lack-luster implementation. This is one of the areas where Ubiquity could use the greatest help. Noun-types enable creating compelling user experiences, with minimal amounts of code. It also allows for code-reuse across numerous commands.

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 — and then come [[Labs/Ubiquity#Participation|get involved]] to help us improve them.

== Insert Email: Commands with Specific Argument Types ==

Let's take a look at one of the special noun-types: <code>noun_type_contact</code>. This lets Ubiquity know to expect a person (either by name or email address). By using the noun-type, Ubiquity will also autocomplete to known people while the user is entering the command. This is what the built-in Ubiquity command "email" uses.

At the moment, Ubiquity figures out what people you know through reading your Gmail contacts. In this prototyped version, you'll need to use Gmail and be logged in for for Ubiquity to know who you know. Eventually, we'd like to be able to interface with all major web-mail sites, as well as desktop software like Thunderbird.

Enough rambling. It's time for a command. I constantly find that I need to fetch someone's email address to paste into a text field because I don't know it off-hand. This command solves that by letting you insert someone's email address using autocomplete.

<pre>
CmdUtils.CreateCommand({
name: "insert-email",
takes: {"person": noun_type_contact},
preview: "Inserts someone's email address by name.",
execute: function( email ) {
CmdUtils.setSelection( email.text );
}
})
</pre>

This one command sums up what I love about Ubiquity. In 8 lines of code, I can fundamentally enhance the browser's functionality. Doing the same thing using a normal Firefox extension methodology takes pages and pages of code—and the interface would take more thought still. Doing the same thing using a bookmarklet would require a server-side component (to get around cross-site Ajax request ban) as well as forcing the user to give up their email password.

Ubiquity increases the surface area of innovation for the browser many-fold, by making anyone who can write simple Javascript into an agent for bettering the browser and the open Web.

== TinyURL: Network Calls and jQuery ==

Often while writing emails, I'll discover that I've pasted in a URL long enough to be used for unfortunate analogies. I'd like to be able to quickly turn that into a [http://en.wikipedia.org/wiki/Tinyurl TinyURL]—but the process of making a TinyURL involves lots of fiddly steps. Ubiquity to the rescue.

Because we include [http://en.wikipedia.org/wiki/jQuery jQuery] with Ubiquity, it is simple to perform Ajax calls as well as parse returning data. TinyUrl.com provides an easy to use RESTful API where you pass a URL and it returns its shortened form. We use that API in this command.

<pre>
CmdUtils.CreateCommand({
name: "tinyurl",
takes: {"url to shorten": noun_arb_text},
preview: "Replaces the selected URL with a TinyUrl.",
execute: function( urlToShorten ) {
var baseUrl = "http://tinyurl.com/api-create.php";
var params = {url: urlToShorten.text};
jQuery.get( baseUrl, params, function( tinyUrl ) {
CmdUtils.setSelection( tinyUrl );
})
}
})
</pre>

Although I used the <code>noun_arb_text</code> command noun-type, I should have used the <code>noun_type_url</code>—if such a thing existed. It doesn't yet.

jQuery is a powerful tool. With it, you can fairly effortlessly cherry-pick the data you need from RSS feeds, XML, and all sorts of other data formats. It also makes doing in-preview animations a breeze.

== Color: Creating Bounded Noun Types ==

Suppose you're writing a set of commands for artists and
web designers, and you know that several of the commands will operate
on colors. You'd like to be able to specify that certain commands
expect names of colors as arguments. Since there are a finite number of
named colors, you can define a custom noun type for them based on a list
of strings, like so:

<pre>
noun_type_color = new CmdUtils.NounType( "Color",
["red", "orange", "yellow", "green", "blue", "violet", "black", "white",
"grey", "brown", "beige", "magenta", "cerulean", "puce"] // etc...
);
</pre>

Note that we gave the new object a name starting with "<code>noun_</code>".
The Ubiquity command loader automatically detects objects starting with
"<code>noun_</code>" as custom noun-types, in the same way as it auto-detects
functions starting with "<code>cmd_</code>" as custom commands.

Once you've defined a custom noun-type, you can use it in as many commands
as you like, thus:

<pre>
CmdUtils.CreateCommand({
name: "get-color-code",
takes: {"color": noun_type_color},
preview: "Inserts the HTML hex-code for the given color.",
// etc...
</pre>

One benefit of creating the custom color noun-type is that if the user
has entered "get-color bl", for instance, Ubiquity will be able to suggest
"black" and "blue" as the two valid completions based on the input.

Of course, not every type of noun you'd be interested in can be represented
as a finite list. If you want to be able to accept or reject input based
on some algorithmic test, you can do so by creating your own noun-type
implementation instead of instantiating <code>CmdUtils.NounType</code>. There is an example of this in the section on the tab commands, below.

== Replace: Commands With Multiple Arguments ==

Commands, like the translate command, can take multiple (and possibly optional) arguments. Ubiquity takes care of the parsing—you don't have to worry about what order the user types them in, you'll just get passed a dictionary with the appropriate entries.

To illustrate that, let's make a simple regular-expression-based "replace" command. It will take three arguments: the thing to replace, the replacement, and the scope-text to do the replacing in. Here's the command:

<pre>
CmdUtils.CreateCommand({
name: "replace",
takes: {"what": noun_arb_text},
modifiers: {"with": noun_arb_text, "in": noun_arb_text},

preview: function( pblock, what, mods ) {
// args contains .with and .in, both of which are input objects.
var msg = 'Replaces "${whatText}" with ${withText} in ${inText}.';
var subs = {whatText: what.text, withText: mods["with"].text, inText: mods["in"].text};

pblock.innerHTML = CmdUtils.renderTemplate( msg, subs );
},

execute: function( what, mods ) {
// If the scope text isn't specified, use the current selection.
var text = mods["in"].text || CmdUtils.getSelection();
var newText = text.replace( what.text, mods["with"].text, "i");
CmdUtils.setSelection( newText );
}
});

</pre>

(In earlier prototypes, modifier arguments could only accept a single-word value, but this has now been fixed.)

The modifiers argument takes a dictionary, where the key is the name of the argument and the value is the noun-type of the argument. In later releases we may include further options, like the ability to specify an argument as required/optional, etc.

The translate command is a good place to learn more about modifiers and the <code>noun_type_language</code>.

= Twitter: Putting It All Together =

We've now covered everything we need to cover in order to write a command that allows us to [http://en.wikipedia.org/wiki/Twitter Twitter] from Ubiquity. Many thanks to [http://theunfocused.net/ Blair McBride] for writing this command. This is a fully functioning command: the browser takes care of the odd edge cases, like not being logged in.

<pre>
// max of 140 chars is recommended, but it really allows 160
const TWITTER_STATUS_MAXLEN = 160;

CmdUtils.CreateCommand({
name: "twitter",
takes: {status: noun_arb_text},

homepage: "http://theunfocused.net/moz/ubiquity/verbs/",
author: {name: "Blair McBride", homepage: "http://theunfocused.net/"},
license: "MPL",

preview: function(previewBlock, statusText) {
var previewTemplate = "Updates your Twitter status to: " +
"${status} " +
"Characters remaining: ${chars}";
var truncateTemplate = " The last ${truncate} " +
"characters will be truncated!";
var previewData = {
status: statusText.text,
chars: TWITTER_STATUS_MAXLEN - statusText.text.length
};

var previewHTML = CmdUtils.renderTemplate(previewTemplate,
previewData);

if(previewData.chars < 0) {
var truncateData = {
truncate: 0 - previewData.chars
};

previewHTML += CmdUtils.renderTemplate(truncateTemplate,
truncateData);
}

previewBlock.innerHTML = previewHTML;
},

execute: function(statusText) {
if(statusText.text.length < 1) {
displayMessage("Twitter requires a status to be entered");
return;
}

var updateUrl = "https://twitter.com/statuses/update.json";
var updateParams = {
source: "ubiquity",
status: statusText.text
};

jQuery.ajax({
type: "POST",
url: updateUrl,
data: updateParams,
dataType: "json",
error: function() {
displayMessage("Twitter error - status not updated");
},
success: function() {
displayMessage("Twitter status updated");
}
});
}
});
</pre>

= Switching Tabs =

The final command in this tutorial is for switching between tabs. The end goal is this: type a few keys to that matches the title of an open tab (in any window), hit return, and you've switched to that tab.

We'll write this command in two steps. The first step is creating a tab noun-type. The second step is using that noun-type to create the tab-switching command.

== Switching: Writing your own Noun-Types ==

A noun-type needs to only have two things: A name and a suggest function. Soon, we'll probably move to having a convenience <code>CmdUtils.CreateNounType()</code>, which will simplify things even more.

The name is what shows up when the command prompts for input. Suggest returns a list of input objects, each one containing the name of a matching tab. We're using [http://developer.mozilla.org/en/docs/FUEL FUEL] to interact with the browser, which is where the "Application" variable comes from.

<pre>
var noun_type_tab = {
_name: "tab name",

// Returns all tabs from all windows.
getTabs: function(){
var tabs = {};

for( var j=0; j < Application.windows.length; j++ ) {
var window = Application.windows[j];
for (var i = 0; i < window.tabs.length; i++) {
var tab = window.tabs[i];
tabs[tab.document.title] = tab;
}
}

return tabs;
},

suggest: function( text, html ) {

var suggestions = [];
var tabs = noun_type_tab.getTabs();

//TODO: implement a better match algorithm
for ( var tabName in tabs ) {
if (tabName.match(text, "i"))
suggestions.push( CmdUtils.makeSugg(tabName) );
}

// Return a list of input objects, limited to at most five:
return suggestions.splice(0, 5);
}
}
</pre>

The suggest method of a noun type always gets passed both text and html. If the input is coming from a part of a web page that the user has selected, these
values can be different: they are both strings, but the html value contains markup tags while the text value does not. The Tab noun type only cares about the plain text of the tab name, so we ignore the value of html.

We use the convenience function <code>CmdUtils.makeSugg()</code> to generate an
input object of the type that the Ubiquity parser expects. The full signature of this function is
<pre>
CmdUtils.makeSugg( text, html, data );
</pre>
but html and data are optional and need be provided only if they differ from text.

If the text or html input is very long, <code>makeSugg()</code> generates a summary for us, and puts it in the <code>.summary</code> attribute of the input object.

We could have accomplished mostly the same thing without calling <code>makeSugg()</code> by returning a list of anonymous objects like these:
<pre>
{ text: tabName,
html: tabName,
data: null,
summary: tabName };
</pre>

The input objects that our <code>.suggest()</code> method generates are the same objects that will eventually get passed in to the <code>execute()</code> and <code>preview()</code> methods of any commands that use this noun type.

== Switching Tabs: The Command ==

Now that we are armed with the tab noun-type, it is easy to make the tab-switching command. Again, we use FUEL to focus the selected tab.

<pre>
CmdUtils.CreateCommand({
name: "tab",
takes: {"tab name": noun_type_tab},

execute: function( directObj ) {
var tabName = directObj.text;
var tabs = noun_type_tab.getTabs();
tabs[tabName]._window.focus();
tabs[tabName].focus();
},

preview: function( pblock, directObj ) {
var tabName = directObj.text;
if( tabName.length > 1 ){
var msg = "Changes to %s tab.";
pblock.innerHTML = msg.replace(/%s/, tabName);
}
else
pblock.innerHTML = "Switch to a tab by name.";
}
})
</pre>

= Development Hints =

You now know all you need to know to get started developing useful Ubiquity commands of your own.

Here are some miscellaneous tips that didn't fit elsewhere on this page, that may make development easier for you.

== The Source Code of Built-In Commands ==

Looking at the source code of built-in commands and built-in noun types can be a very useful aid to development. If you have the source checkout of Ubiquity (see [https://wiki.mozilla.org/index.php?title=Labs/Ubiquity/Ubiquity_0.1_Development_Tutorial the development tutorial] to find out how to get this), the source code can be found in the files and directories:

ubiquity/standard-feeds/
ubiquity/builtin-feeds/en/builtincmds.js
ubiquity/feed-parts/header/en/nountypes.js

If you don't have a checkout of the source code, you can view the latest version on the web here:

[http://hg.toolness.com/ubiquity-firefox/file/tip/ubiquity/standard-feeds/ standard-feeds]
[http://hg.toolness.com/ubiquity-firefox/file/tip/ubiquity/builtin-feeds/en/builtincmds.js builtincmds.js]
[http://hg.toolness.com/ubiquity-firefox/file/tip/ubiquity/feed-parts/header/en/nountypes.js nountypes.js]

== Interacting with Other Extensions ==

http://img363.imageshack.us/img363/1906/picture7cm5.png

There isn't much to say here besides that it's easy. For example, here's a command (thanks to [http://foyrek.com/lyrics.html Abimanyu Raja] for writing this code) that finds the lyrics for a song. You can simply Ubiq something like "get-lyrics wild international" but the command will also interface with the FoxyTunes extension (if it is installed) and add the currently playing song to the suggestion list. Interfacing with other extensions, too, is easy because you can view the source code for every Firefox extension.

<pre>
var noun_type_song = {
_name: "song name",
suggest: function( text, html ) {
var suggestions = [CmdUtils.makeSugg(text)];
if(window.foxytunesGetCurrentTrackTitle){
suggestions.push(CmdUtils.makeSugg(window.foxytunesGetCurrentTrackTitle()));
}
return suggestions;
}
}

CmdUtils.CreateCommand({
name: "get-lyrics",
takes: {song: noun_type_song},
preview: function(pblock, directObject) {

searchText = jQuery.trim(directObject.text);
if(searchText.length < 1) {
pblock.innerHTML = "Searches for lyrics of the song";
return;
}

var previewTemplate = "Searches for the lyrics of ${query}";
var previewData = {query: searchText};
pblock.innerHTML = CmdUtils.renderTemplate(previewTemplate, previewData);

},
execute: function(directObject) {
var url = "http://www.google.com/search?q={QUERY}"
var query = directObject.text + " lyrics";
var urlString = url.replace("{QUERY}", query);
Utils.openUrlInBrowser(urlString);
}
});
</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 ==

In order to run some code on page load, you simply have to prefix your function with <code>pageLoad_</code>. For example, if you want to say "Hi" every time a page is loaded, your code would look like this:

<pre>
function pageLoad_hi(){
displayMessage("hi");
}
</pre>

If you modify the function and want to see the changes, remember to first invoke Ubiquity. Although your function like above, might not be a Ubiquity command, this is necessary to refresh the cached code.

Similarly, if you want to run some code everytime Firefox starts up, you just have to prefix the function with <code>startup_</code> .

The awesome thing about these functions is the ability to develop whole Firefox extensions (that require minimal UI) as Ubiquity plugins in lesser lines of code. You don't need to worry about chrome.manifest or install.rdf. Another added benefit is that you never have to restart your Firefox during development unless of course, you are running code on Firefox startup.

<center>http://img388.imageshack.us/img388/3086/picture5eo9.png</center>

Here's the code for [http://foyrek.com/commands/keyscape.js Keyscape] which is a Ubiquity command that makes use of <code>pageLoad</code> and <code>startup</code> to recreate the functionality of the [https://addons.mozilla.org/en-US/firefox/addon/339 Search Keys extension] by Jesse Ruderman. In line with Ubiquity's aim to let you do things quicker using your keyboard, this command lets you go to search results on Google by just pressing a number. It'll add hints to show the number of each link.

<pre>
//A lot of this code is borrowed from the Search Keys extension
//Many thanks to Jeese Ruderman

function startup_keyscape() {
window.addEventListener("keydown", keyscape_down, true);
}

function pageLoad_keyscape(doc){

var uri = Utils.url(doc.documentURI);
//If we are on about: or chrome://, just return
if(uri.scheme != "http")
return;

//Check if the page we are on is google
if( keyscape_isGoogle(uri) ){

for(var num=1; num<=10; num++){

var link = jQuery(doc.body).find('a.l')[num-1];

if( link ){

var hint = doc.createElementNS("http://www.w3.org/1999/xhtml", "span");
hint.style.color = "blue";
hint.style.background = "white";
hint.style.padding = "1px 2px 1px 2px";
hint.style.marginLeft = ".5em";
hint.appendChild(doc.createTextNode(num == 10 ? 0 : num));
link.parentNode.insertBefore(hint, link.nextSibling);
}
}
}
}

function keyscape_isGoogle(uri){
return uri.host.indexOf("google") != -1
&& (uri.path.substr(0,8) == "/search?"
|| uri.path.substr(0,8) == "/custom?");
}

function keyscape_down(event){

var doc = Application.activeWindow.activeTab.document;
var uri = Utils.url(doc.documentURI);

if( keyscape_isGoogle(uri) ){

var key = parseInt(event.keyCode || event.charCode);
var num;

if(48 <= key && key <= 57) //number keys
num = key - 48;
else if(96 <= key && key <= 105) //numeric keypad with numlock on
num = key - 96;
else
return;

//Don't do anything if we are in a textbox
//or some other related elements
var elt = window.document.commandDispatcher.focusedElement;

if (elt) {
var ln = new String(elt.localName).toLowerCase();
if (ln == "input" || ln == "textarea" || ln == "select" || ln == "isindex")
return;
}

//Get the link url from the search results page
var url_dest = jQuery(doc.body).find('a.l').eq(num-1).attr('href');

if(event.altKey){
//Open in new tab
Application.activeWindow.open(Utils.url(url_dest));
}else{
//Open in same tab
doc.location.href = url_dest;
}
}
}
</pre>

If Ubiquity does indeed become ubiquitous, a lot of extensions can be re-written as Ubiquity commands. This is much nicer for the end-user, as well, because the Ubiquity command installation process is a lot easier.

In the future, Ubiquity is also likely to have the ability to convert your Ubiquity commands into proper Firefox extensions. Look [http://labs.toolness.com/trac/ticket/3 here] to check on the progress of this functionality.

== Firebug ==

You should enable Chrome Errors and Warnings if you want the errors in your code to appear in the Firebug console. Use CmdUtils.log() rather than console.log() ''Note: For now, you can only pass one argument to log()''

== Adding Commands Programmatically ==

Here is a snippet of code that shows how a developer can programmatically register a command included in a Firefox extension.

<pre>

// Helper function used to determine the local directory where the
// extension which contains the command is installed. This is used
// to create the URL of the js file which includes the implementation
// of the list of commands you want to add.
function getExtensionDir() {
var extMgr = Components.classes["@mozilla.org/extensions/manager;1"]
.getService(Components.interfaces.nsIExtensionManager);
return extMgr.getInstallLocation( "feedly@devhd" ).getItemLocation( "feedly@devhd" );
}

function getBaseUri() {
var ioSvc = Components.classes["@mozilla.org/network/io-service;1"]
.getService(Components.interfaces.nsIIOService);
var extDir = getExtensionDir();
var baseUri = ioSvc.newFileURI(extDir).spec;
return baseUri;
}

// your extension needs to call the addUbiquity command each time a new browser
// session is create and your extension is loaded.
function addUbiquityCommands(){
// url of the file which contains the implementation of the commands
// we want to add.
var url = getBaseUri() + "content/app/ubiquity/commands.js"

// link to the ubiquity setup module.
var jsm = {};
Components.utils.import("resource://ubiquity/modules/setup.js", jsm);

// look up the feed manager and add a new command. Note: we are using the
// isBuiltIn=true option so that the command is only added for the duration
// of the browser session. This simplifies the overall lifecycle: if the
// extension is disabled or un-installed, it will be automatically
// "removed" from ubiquity.
jsm.UbiquitySetup.createServices().feedManager.addSubscribedFeed( {
url: url,
sourceUrl: url,
canAutoUpdate: true,
isBuiltIn: true
});
}
</pre>

Inside your command implementation, you can use importing modules or looking up a singleton XPCOM component to link your command back to the functionality encapsulated by your extension. Here is a sample command which does that:

<pre>
var StreetsUtils = function(){
var that = {};
that.lookupCore = function(){
return Components.classes["@devhd.com/feedly-boot;1"]
.getService(Components.interfaces.nsIFeedlyBoot)
.wrappedJSObject
.lookupCore();
};
return that;
}();

CmdUtils.CreateCommand({
name: "my-extension-test",
takes: {"message": noun_arb_text},
icon: "chrome://my-extension-test/skin/icon-16x16.png",
modifiers: {to: noun_type_contact},
description:"Testing the feedly+ubiquity integration",
help:"This is a test help message",
preview: function(pblock, directObj, modifiers) {
var html = "Testing my-extension-test ";
if (modifiers.to) {
html += "to " + modifiers.to.text + " ";
}
if (directObj.html) {
html += "with these contents:" + directObj.html;
} else {
html += "with a link to the current page.";
}
pblock.innerHTML = html;
},

execute: function(directObj, headers) {
CmdUtils.log( ">>> my-extension core? " + ( StreetsUtils.lookupCore() != null ) );
}
});
</pre>

Note: If you command file needs to include/load other JS files included in your extension, you can use the following piece of code at the top of the command js file you are adding to ubiquity.

<pre>
function include( partialURI )
{
// Load JS libraries
var u = "chrome://feedly/content/app/" + partialURI;
var jsl = Cc["@mozilla.org/moz/jssubscript-loader;1"]
.getService(Ci.mozIJSSubScriptLoader);

jsl.loadSubScript( u );
}

include( "ubiquity/templates.ubiquity.js" );
</pre>

= Conclusion =

To reiterate a point I made before: Ubiquity increases the surface area of innovation for the browser many-fold, by making anyone who can write simple Javascript into an agent for bettering the browser and the open Web. You are one of those agents.

Now, go forth and create.

Labs/Ubiquity

2009-01-20T03:16:57Z

Endolith: I kept looking at this page when it updated, and couldn't find the release notes. Now I look in about:ubiquity

Back to [[Labs]].

[https://ubiquity.mozilla.com/xpi/ubiquity-latest.xpi Install latest version of Ubiquity for Firefox]

[https://ubiquity.mozilla.com/xpi/ubiquity-latest-beta.xpi Install the latest beta of Ubiquity for Firefox]

= What is Ubiquity? =
You can learn more about Ubiquity by reading Atul's blog post entitled [http://www.toolness.com/wp/?p=54 Ubiquitous Interfaces, Ubiquitous Functionality], or try it out via the [[Labs/Ubiquity/Latest Ubiquity User Tutorial|User Tutorial]].

Other informative blog posts about Ubiquity include:
# [http://www.toolness.com/wp/?p=64 Trusting Functionality] by Atul
# [http://www.azarask.in/blog/post/can-ubiquity-be-used-only-with-the-mouse/ Mouse-Based Ubiquity]
# [http://azarask.in/blog/post/sharing-streamable-functionality/ Sharing Streamable Functionality] by Aza
# [http://jonoscript.wordpress.com/2008/07/21/language-based-interfaces-part-1-the-problem/ Language-Based Interfaces, part 1: The Problem] by Jono
# [http://jonoscript.wordpress.com/2008/07/25/our-presentation-at-labs-night/ Our Presentation at Labs Night] by Jono
# [http://jonoscript.wordpress.com/2008/07/26/why-verbs/ Why Verbs?] by Jono
# [[Labs/Ubiquity/Selected Press|Selected Press]]

= Participation =
# [http://getsatisfaction.com/mozilla/products/mozilla_ubiquity Ideas, Complaints, Forum, and "Customer Service"]
# [http://groups.google.com/group/ubiquity-firefox General Google Group/mailing list] - Useful for discussion of command development, user interface, feature suggestions, and other high-level discussions.
# [[Labs/Ubiquity/Commands In The Wild|Commands In The Wild]] Add links to your commands here.
# [http://ubiquitously.org/forum Ubiquitously, an Ubiquity developer geared forum]
# [irc://irc.mozilla.org/ubiquity #ubiquity irc.mozilla.org] - Live internet relay chat discussion.
# [http://labs.toolness.com/trac/report/1 Issue Tracker] - Used to report/discuss bugs and submit patches for Ubiquity.
# [http://hg.toolness.com/ubiquity-firefox/ Ubiquity HG Repository] - The Mercurial source code repository for Ubiquity.
# [http://labs.toolness.com:8010/ Buildbot] - Continuous integration that runs Ubiquity unit tests after every commit. If the tests fail, they're reported immediately to the mailing list.
# [http://groups.google.com/group/ubiquity-core Core Google Group/mailing list] - Discussion of low-level internals of Ubiquity.
# [[Labs/Ubiquity/Credits|Credits]]

= Meeting Notes =
# [http://docs.google.com/Doc?id=ddf2vjms_24cpjjq9g9 Meeting notes for 0.1 release]
# [[Labs/Ubiquity/November 12 Meeting Notes|November 12 Meeting Notes]]

= Documentation =
# [[Labs/Ubiquity/Latest Ubiquity User Tutorial|Ubiquity Tutorial]]
# [[Labs/Ubiquity/Ubiquity 0.1_Author_Tutorial|Creating Commands Tutorial]]
# [[Labs/Ubiquity/Skins/|Skinning Ubiquity Tutorial]]
# [[Labs/Ubiquity/Ubiquity 0.1_Development_Tutorial|Contributing to Core Development]]
# [[Labs/Ubiquity/Ubiquity 0.1_Localization_Tutorial|Localizing Ubiquity to Your Language]]
# [[Labs/Ubiquity/Ubiquity 0.1_Nountypes_Reference|Noun-types Reference]]
# [[Labs/Ubiquity/Bundled Libraries|Bundled libraries]]
# [[Labs/Ubiquity/jQuery in Ubiquity|Using jQuery in Ubiquity]]
# [https://developer.mozilla.org/en/JavaScript_style_guide JavaScript style guide]
# [[Labs/Ubiquity/Ubiquity_Source_Tip_Author_Tutorial|Source-tip Commands Tutorial]]
# [[Labs/Ubiquity/Ubiquity_0.1.3_Architecture|Ubiquity 0.1.3 Architecture]]

= The Herd =
The Herd keeps track of all Ubiquity scripts. For more information, see the following links:
# [http://hg.toolness.com/ubiquity-site/ Herd HG Repository]
# [http://hg.toolness.com/ubiquity-site/file/tip/README Herd Developer FAQ]
# [http://wiki.apache.org/couchdb/HttpViewApi CouchDB] - database used for Herd
# [https://ubiquity.mozilla.com/herd/ The Herd]-The Herd Itself.

= Proposals =

# [[Labs/Ubiquity/Ubiquity Command Suggestions|Command Suggestions]] - use this page to suggest new Ubiquity commands you'd like to see.
# [[Labs/Ubiquity/Nouns | Proposals for New Nouns]]
# [[Labs/Ubiquity/Magic_Words | Proposals for new "Magic Words"]]
# [[Labs/Ubiquity/Ubiquity_Commands_Center | Ubiquity Commands Center]] - an idea for a web-panel that maintains a database of Ubiquity scripts.
# [[Labs/Ubiquity/TrustNetwork | Ubiquity Trust Network]] - a proposal for a distributed trust network
# [[Labs/Ubiquity/Thunderbird | Ubiquity In Thunderbird]] - let's make Ubiquity work in Thunderbird!
# [[Labs/Ubiquity/0.2 Roadmap Proposals | 0.2 Roadmap Proposals]] - Brainstorming on possible directions to go for Ubiquity 0.2.
# [[Labs/Ubiquity/0.2 Design: UI and Security Extensibility|0.2 Design: UI and Security Extensibility]] - Design-related thoughts on how to make Ubiquity extensible in regards to security/command-execution and access by other Firefox UIs.
# [[Labs/Ubiquity/0.2 Proposed Uplift Commands| Proposed commands for uplift into Ubiquity 0.2]]

= Release Notes =
# [[Labs/Ubiquity/Ubiquity 0.1.1 Release Notes|Ubiquity 0.1.1 Release Notes]]
# [[Labs/Ubiquity/Ubiquity 0.1.2 Release Notes (Raging Stream)|Ubiquity 0.1.2 Release Notes (Raging Stream)]]
# [[Labs/Ubiquity/Ubiquity 0.1.3 Release Notes|Ubiquity 0.1.3 Release Notes]]
# [[Labs/Ubiquity/Ubiquity_0.1.5_Release_Notes|Ubiquity 0.1.5 Release Notes]]
# ...