Labs/Ubiquity/Parser 2 API Conversion Tutorial

Intro

Ubiquity 0.5 introduces an updated command API, reflecting the changes in the parser as well as the new 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 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

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 location 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.

Converting your command

names

Where Parser 1 expected a single default verb name in the property name and possible synonyms in an optional synonyms property, Parser 2 requires that there be a single names 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!)

Making your command localizable

More detailed information on making commands localizable can be found in the tutorial 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 preview and execute methods with the function _(). This _() command (familiar to anyone with prior experience with Gettext) handles the localization by finding the appropriate matching localized string on preview or execution.

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

In the case above, _() 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 _() function also handles renderTemplateing 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 numOfResults == 3 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 Making Commands Localizable for more information.

There is no need to wrap any properties of the commands (names, help, author, etc.) in _(), nor do you need to wrap string previews in _(), 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 Making Commands Localizable.

References

• The updated Command Authoring Tutorial
• Semantic roles in Parser 2: a list of supported semantic roles with explanations and examples
• Making your command localizable