Using the Places keywords API

The Places keywords API allows to assign a keyword to an URL. Keywords represent an alias for the given URL in the autocomplete (AKA Awesomebar) field, with smart replacement of query terms.

A keyword can only be associated to a given url, it's not possible to associate the same keyword with multiple urls (doing so will just update the url it's pointing to). Each keyword can be associated with POST data, in such a case a POST action will be executed when the given URL is selected from the Awesomebar. Different keywords can reference the same url, if their POST data differ.

Keywords in Firefox are currently created through the Add Keyword For this search contextual menu option in form text fields.

Note this is the same feature previously known as Bookmark keywords, the key difference is that keywords are not bound to a specific bookmark, but to a specific URL.

Using the keywords API

The keywords API is a promise-based API available through the PlacesUtils module:

Components.utils.import("resource://gre/modules/XPCOMUtils.jsm");
XPCOMUtils.defineLazyModuleGetter(this, "PlacesUtils", "resource://gre/modules/PlacesUtils.jsm");

Setting a keyword for an URL

The insert() method accepts a keyword entry object describing the keyword to insert. It has the following properties:

• keyword: string representing the keyword
• url: either a URL or spec represeting the URL to associate to
• postData: optional POST data string. Should be omitted if there's no POST data.

PlacesUtils.keywords.insert({ keyword:  "my_keyword",
                              url:      "http://www.example.com/"
                              postData: "post+data=1&test=2"
                            }).then(() => { /* success */ },
                                     e => { /* failure */ });

Note that setting an already existing keyword to a different URL, will silently update the existing keyword to the new URL.

Fetching an entry by keyword

The fetch() method acceps a keyword string (or an object having a keywords property) and might resolve to a keyword entry with the following properties:

• keyword: string representing the keyword
• url: the URL represeted by the keyword
• postData: optional POST data string. Not defined if there's no POST data.

If no keyword exists, will resolve to null.

PlacesUtils.keywords.fetch("my_keyword").then(entry => { /* entry is either null, or a keyword entry */ },
                                                  e => { /* failure */});

Fetching entries by URL

The fetch() method also accepts a keyword entry, where it's possible to specify keyword, url, or both. If both are specified it will try to fetch an exact match. Specifying only an url, will fetch all the keywords associated to such an URL. Note that fetch() always resolves to a single entry, to fetch all of the entries it's necessary to provide a callback function.

PlacesUtils.keywords.fetch({ url: "http://www.example.com/" },
                           entry => { /* Invoked for each found keyword entry */ })
                    .then(oneEntry => { /* oneEntry is either null, or one of the keyword entries */ },
                                 e => { /* failure */});

Removing a keyword

The remove() method accepts a keyword string.

PlacesUtils.keywords.remove("my_keyword").then(() => { /* success */ },
                                                e => { /* failure */ });