THIS PAGE IS A WORKING DRAFT
	The page may be difficult to navigate, and some information on its subject might be incomplete and/or evolving rapidly. If you have any questions or ideas, please add them as a new topic on the discussion page.

This version is for the latest source version of Ubiquity 0.5. Click here for the 0.1 version of this page

TODO

Do we need this reference now that we have auto-generated docs?

What are Noun Types?

Why Use Noun Types?

Using nountypes can save you writing boilerplate code in your command, AND it helps Ubiquity provide better suggestions to the user, making your command easier to use.

1. Using a nountype lets the user see suggestions for what input they might want to give as arguments to your command
2. ...and saves the user typing by letting them choose a correct suggestion
3. Nountypes can pre-parse the input for the arguments of your command, so your preview() and execute() methods get data in exactly the format they need. For instance, if you use noun_type_date, you don't need to write date-parsing code for your command.
4. A command using specific nountypes will appear higher in the suggestion list when the user has the appropriate type of content selected and invokes Ubiquity

noun_type_contact

Suggests email addresses from your GMail address book.

Input accepted: A person's name (or part of it).

Suggestions generated: A list of email addresses for your contacts who match the input name.

Example: My input is "aza". Suggestions are [{text:"aza@mozilla.com"}, {text:"aza@humanized.com"}].

Used in commands: email, get-email-address

Defaults to: None

TODO: Needs rewriting to take advantage of async noun suggestions. Needs to be extended to use other sources of email contacts besides GMail! Needs to accept email addresses (and fragments) as input too, not just names.

noun_arb_text

Accepts any text at all and suggests it back without changes. Use this for commands that can accept anything at all as input.

Note that all noun-types can accept selected text, not just typed text, as input. However, if you're writing a command that operates on a chunk of text that the user has selected, noun_arb_text is probably the noun-type that you want to use. (It's better to use noun_arb_text, as opposed to just having your command grab the selection directly, because noun_arb_text also allows the user to type in an argument, as well as showing the user a preview of the argument.)

When the input comes from a selection, HTML tags, if any, that are part of the selection will be included in the .html attribute of the suggestion. The .text attribute of the suggestion will include just the plain text with no HTML tags.

Example: The user has selected a bold word on a web page, like this: hello. The suggestion returned is [{text:"hello", html:"<b>hello</b>"}].

Defaults to: None

Used in commands: Lots and lots of them

TODO: There are many commands that are using noun_arb_text that would really be better off using a more specific noun type.

noun_type_date

Input Accepted: A date, in nearly any format.

Suggestions generated: A parsed version of the date.

This noun-type is based on date.js, so it understands input like "today", "tomorrow", "friday", and so on, as well as "august 15" or "4/12/07", etc.

The .data attribute of the suggestion contains a Date object which your command can use, so you can have direct access to the data without having to parse the date yourself.

Defaults to: Today's date.

Used in commands: add-to-calendar

TODO: needs to be more accepting of partial input -- e.g. it currently accepts "today" as input but doesn't accept "to", etc. This is annoying because it treats your input as invalid while you're in the middle of typing it.

noun_type_time

Accepts a time of day in nearly any format. Uses date.js, so it understands input like "5:00", "11am", and even "13:00".

The .data attribute of the suggestion contains a Date object which your command can use, so you can have direct access to the data without having to parse the time yourself.

Defaults to: The current time.

Used in commands: None yet.

TODO: Give it some real-world testing.

noun_type_percentage

Accepts numerical input only. Interprets numbers greater than and equal to 1 as if they are followed by a percent sign, while numbers less than one are accepted literally.

The .data attribute of the suggestion contains the number, so you don't have to parse it yourself.

'Examples:

• Input is "50". Suggests: [{text:"50%", data:0.5}]
• Input is "0.2". Suggests: [{text:"20%", data:0.2}]
• Input is "five". Suggests: []

Defaults to: None

Used in commands: zoom

noun_type_address

Accepts only inputs that are addresses.

TODO: in the process of being replaced with an asynchronous implementation that ought to work a lot better.

Default: None

Used in commands: none currently

noun_type_language

Suggests the name of a (human) language: "English", "Dutch", "Korean", etc.

Input accepted: a string that matches part of a language name.

Suggestions generated: All language names that match the input. The language name is in the .text attribute, while the .data attribute of the suggestion contains the standard two-letter language code. A list of available languages with their associated code can be found in nountype.js.

Example: User input is "g". Suggestions are: [{text:"greek", data:"el"}, {text:"german", data:"de"}]

Defaults to: None Used in commands: translate

TODO: Should default to suggesting a list of ALL languages when there's no input? Or perhaps just the two or three most often used languages?

noun_type_tab

Suggests names of all open Firefox tabs.

Input accepted: Any text that matches part of the name of one of the open Firefox tabs.

Suggestions generated: One for each tab that matches the input. The tab name is in the .text attribute.

Example:

Defaults to: Nothing

Used in commands: tab, close-tab

TODO: Should default to suggesting a list of ALL open tabs when there's no input?

noun_type_searchengine

Suggests names of search engines that are built into the Firefox search bar.

Defaults to: Whichever search engine is set as your default in Firefox.

Used in commands: search

noun_type_tag

Suggests tags names out of the set of tag names you have previously used on Firefox bookmarks.

Used by commands: None currently

Defaults to: None currently

TODO: Should be tested and used in the "tag" command. Not sure how functional it is. Needs a default method.

noun_type_geolocation

Suggests a (real-world) location, defaulting to your current location.

Magic words: input of "here" will suggest your current location as determined by IP lookup. (Actually three suggestions: your precise location, your city, and your country.)

Used by commands: weather

Defaults to: Your current location, as determined by IP lookup.

TODO: This and noun_type_address should probably be combined into one, since there's no good reason for them to be different things. Currently too permissive, as it accepts any input: should make some attempt to reject input that is obviously not a location. Should use Geode instead of IP lookup to get your current location. Could do some cacheing to suggest locations you've entered before.

noun_type_url

Suggests URLs, based on partial URLs you type. Will do some basic canonicalization (i.e. prepending "http://")

Magic words: input of "page" or "url" will suggest back the URL of the current page.

Used by commands: tinyurl

Defaults to: None

TODO: Should be better about filtering out inputs that are not URLs, as right now it's too permissive and pretty much accepts anything. Also, it should default to the current page. Finally, it would be really cool if it could read from the Awesomebar's data source to suggest URLs that you've visited before.

noun_type_livemark

Suggests livemark titles based on those that have been bookmarked

Used by commands: None currently

Suggestions are: [ { text:"Livemark Title", data: { itemIds : [ ] } ]

Note: Individual itemIds can be passed to the Places interface for further operation

Defaults to: "All livemarks" if any exist, otherwise null.