Places utilities for JavaScript

utils.js is accessible at the following URL:
http://mxr.mozilla.org/mozilla-centr...ntent/utils.js
This file includes utility functions used by a lot of the bookmarking, tagging, and annotation services that are built into Firefox. By default its only included in browser.xul. Its not an interface, and as such it will never be frozen, but it provides some easy to use functions that can save you from reinventing the wheel and cluttering up your own classes/functions when you need it.

Global Objects

There are a few global objects and constants defined in utils.js. These are:

QI_node

QI_node(aNode, aIID) Runs a query interface on a bookmark node to expose the interface available to that type. If the interface isn't available to that node, null is returned.

• aNode - The bookmark
• aIID - The return interface wanted.

There are several predefined versions of this for common calls. These just take in the node, as the interface is already defined:

• asVisit(aNode)
• asFullVisit(aNode)
• asContainer(aNode)
• asQuery(aNode)

Annotations

A few annotation names are defined here.

• LOAD_IN_SIDEBAR_ANNO - This annotation is associated with bookmarks or items that should load in the sidebar automatically.
• DESCRIPTION_ANNO - This annotation stores description information about a bookmark.
• POST_DATA_ANNO - I need to clarify here, but I think this is the name of the annotation that stores information for keyword searches from a bookmark.
• LMANNO_FEEDURI - Need to clarify here too, but I think for each livemark, there is an bookmark which contains an annotation storing the associated feed uri.
• LMANNO_SITEURI - Need to clarify here, but I think for each livemark, there is an bookmark which contains an annotation storing the associated site uri.
• ORGANIZER_FOLDER_ANNO - This annotation is associated with a folder that should be shown in the Library's left pane.
• ORGANIZER_QUERY_ANNO - This annotation is used by the places organizer to decide what nodes should be shown in the left pane.

Warning : PlacesUtils class since Firefox 3 beta 5 has been split into:

• PlacesUtils: can be used in any toolkit application
• PlacesUIUtils: only in Firefox

PlacesUtils

This is a gigantic object full of usefulness if you need to do any bookmark work from within browser.xul. As such, it gets its own special section.

PlacesUtils

Method overview

Constants

Mimetypes

• TYPE_X_MOZ_PLACE_CONTAINER
• TYPE_X_MOZ_PLACE_SEPARATOR: "text/x-moz-place-separator",
• TYPE_X_MOZ_PLACE: "text/x-moz-place",
• TYPE_X_MOZ_URL: "text/x-moz-url",
• TYPE_HTML: "text/html",
• TYPE_UNICODE: "text/unicode",

Services

There's easy access to some of the common services used in bookmarks or history navigation here. For instance, normally in order to get access to the bookmarks service, you have to run something like:

 Components.classes["@mozilla.org/browser/nav-bookmarks-service;1"]
   .getService(Components.interfaces.nsINavBookmarksService);

With places utils all you need to write is:

 PlacesUtils.bookmarks

This should save on the number of references to the service that are needed, and can help clean up interfaces that are already fairly cluttered. There are currently 11 services defined in here.

bookmarks

nsINavBookmarksService

history

nsINavHistoryService

globalHistory

nsIBrowserHistory

livemarks

nsILivemarkService

annotations

nsIAnnotationService

favicons

nsIFaviconService

microsummaries

nsIMicrosummaryService

tagging

nsITaggingService

RDF

nsIRDFService

ptm

nsIPlacesTransactionsService

clipboard

nsIClipboard

URIFixup

nsIURIFixup

Special Places

These are essentially references to the id's of special folders within places. They can save you time calling the service and searching for a particular folder on your own.

placesRootId

bookmarksMenuFolderId

The bookmarks menu.

toolbarFolderId

The bookmarks toolbar.

tagsFolderId

The folder that tags are stored in.

unfiledBookmarksFolderId

Other

Other attributes stored in PlacesUtils.

localStore

Warning: Local store provided access to the local-store rdf data source, which stores persisted information about the browser. Its functionality has been replaced by xulstore.

uriTypes

containerTypes

leftPaneQueries

Queries that appear in the Library's left pane.

leftPaneFolderId

A single folder shown in the Library's left pane.

allBookmarksFolderId

The id of the "All Bookmarks" folder shown in the Library's left pane.

placesFlavors

GENERIC_VIEW_DROP_TYPES

Methods

createFixedURI

 nsIURI createFixedURI(string aSpec)

Takes in a spec and returns a valid uri based on it using the nsIURIFixup service.

Parameters

aSpec

a url string that needs fixup

Return type

Returns a correct nsIURI.

getFormattedString()

 string getFormattedString(string key,
                           array string params)

Parameters

key

The string name to get from the string bundle

params

Strings to substitute into the bundle at designated points

See XUL:stringbundle for more information.

Return type

Returns a string from the default places stringbundle.

getString()

 string getString(string key)

Parameters

key

The name of the string to get.

Return type

Returns a string from the default places stringbundle.

nodeIs()

There are a ton of nodeIs(something) functions in here to check properties of a bookmark node. The all take in the same argument and return a boolean true or false, so I'm just going to list them all in one lump:

boolean nodeIsFolder(aNode)

Determines whether or not a ResultNode is a Bookmark folder or not.

boolean nodeIsBookmark(aNode)

Determines whether or not a ResultNode represents a bookmarked URI.

boolean nodeIsSeparator(aNode)

Determines whether or not a ResultNode is a Bookmark separator.

boolean nodeIsVisit(aNode)

Determines whether or not a ResultNode is a visit item or not

boolean nodeIsURI(aNode)

Determines whether or not a ResultNode is a URL item or not

boolean nodeIsQuery(aNode)

Determines whether or not a ResultNode is a Query item or not

boolean nodeIsReadOnly(aNode)

Determines if a node is read only (children cannot be inserted, sometimes they cannot be removed depending on the circumstance)

boolean nodeIsHost(aNode)

Determines whether or not a ResultNode is a host folder or not

boolean nodeIsContainer(aNode)

Determines whether or not a ResultNode is a container item or not

boolean nodeIsDynamicContainer(aNode)

Determines whether or not a result-node is a dynamic-container item. The dynamic container result node type is for dynamically created containers (e.g. for the file browser service where you get your folders in bookmark menus).

boolean nodeIsLivemarkContainer(aNode)

Determines whether a result node is a remote container registered by the livemark service.

boolean nodeIsLivemarkItem(aNode)

Determines whether a result node is a live-bookmark item

Parameters

aNode

The node to check.

Return type

Returns a boolean.

isReadonlyFolder()

Determines whether or not a node is a readonly folder.

 boolean isReadonlyFolder(aNode)

Parameters

aNode

The node to check.

Return type

Return true if the node is a folder, false otherwise.

getIndexOfNode()

Gets the index of a node within its parent container

 int getIndexOfNode(aNode)

Parameters

aNode

The node to look up

Return type

Returns the index of the node within its parent container, or -1 if the node was not found or the node specified has no parent.

wrapNode()

String-wraps a result node according to the rules of the specified content type.

 string wrapNode(aNode,
                 string aType,
                 nsIURI aOverrideURI)

Parameters

aNode

The Result node to wrap (serialize)

aType

The content type to serialize as

aOverrideURIOptional

Used instead of the node's URI if provided. This is useful for wrapping a container as TYPE_X_MOZ_URL, TYPE_HTML or TYPE_UNICODE.

Return type

Returns A string serialization of the node

unwrapNodes()

Unwraps data from the Clipboard or the current Drag Session.

 array object unwrapNodes(blob,
                          type)

Parameters

blob

A blob (string) of data, in some format we potentially know how to parse.

type

The content type of the blob.

Return type

Returns an array of objects representing each item contained by the source.

makeTransaction()

Constructs a Transaction for the drop or paste of a blob of data into a container.

 makeTransaction(data,
                 type,
                 container,
                 index,
                 copy)

Parameters

data

The unwrapped data blob of dropped or pasted data.

type

The content type of the data

container

The container the data was dropped or pasted into

index

The index within the container the item was dropped or pasted at

copy

The drag action was copy, so don't move folders or links.

Return type

Returns an object implementing nsITransaction that can perform the move/insert.

getFolderContents()

 getFolderContents(aFolderId,
                   aExcludeItems,
                   aExpandQueries)

Generates a nsINavHistoryResult for the contents of a folder.

Parameters

folderId

The folder to open

[optional] excludeItems

True to hide all items (individual bookmarks). This is used on the left places pane so you just get a folder hierarchy.

[optional] expandQueries

True to make query items expand as new containers. For managing,you want this to be false, for menus and such, you want this to be true.

Return type

Returns a nsINavHistoryResult containing the contents of the folder. The result.root is guaranteed to be open.

Bookmark Dialog

Methods to show the bookmarkProperties dialog in its various modes.

The showMinimalAdd methods open the dialog by its alternative URI. Thus they persist the dialog dimensions separately from the showAdd methods. Note these variants also do not return the dialog "performed" state since they may not open the dialog modally.

showAddBookmarkUI()

Shows the "Add Bookmark" dialog.

 showAddBookmarkUI(aURI,
                   aTitle,
                   aDescription,
                   aDefaultInsertionPoint,
                   aShowPicker,
                   aLoadInSidebar,
                   aKeyword,
                   aPostData)

Parameters

[optional] aURI

An nsIURI object for which the "add bookmark" dialog is to be shown.

[optional] aTitle

The default title for the new bookmark.

[optional] aDescription

The default description for the new bookmark

[optional] aDefaultInsertionPoint

The default insertion point for the new item. If set, the folder picker would be hidden unless aShowPicker is set to true, in which case the dialog only uses the folder identifier from the insertion point as the initially selected item in the folder picker.

[optional] aShowPicker

see above

[optional] aLoadInSidebar

If true, the dialog will default to load the new item in the sidebar (as a web panel).

[optional] aKeyword

The default keyword for the new bookmark. The keyword field will be shown in the dialog if this is used.

[optional] aPostData

POST data for POST-style keywords.

Return type

Returns true if any transaction has been performed.

showMinimalAddBookmarkUI()

 showMinimalAddBookmarkUI(aURI,
                        aTitle,
                        aDescription,
                        aDefaultInsertionPoint,
                        aShowPicker,
                        aLoadInSidebar,
                        aKeyword,
                        aPostData)

This opens the dialog with only the name and folder pickers visible by default. You can still pass in the various paramaters as the default properties for the new bookmark. The keyword field will be visible only if the aKeyword parameter was used.

See showAddBookmarkUI for a description of the params.

showAddLivemarkUI()

Shows the "Add Live Bookmark" dialog.

 boolean showAddLivemarkUI(aFeedURI,
                           aSiteURI,
                           aTitle,
                           aDescription,
                           aDefaultInsertionPoint,
                           aShowPicker)

Parameters

[optional] aFeedURI

The feed URI for which the dialog is to be shown (nsIURI).

[optional] aSiteURI

The site URI for the new live-bookmark (nsIURI).

[optional] aDefaultInsertionPoint

The default insertion point for the new item. If set, the folder picker would be hidden unless aShowPicker is set to true, in which case the dialog only uses the folder identifier from the insertion point as the initially selected item in the folder picker.

[optional] aShowPicker

see above

Return type

Return true if any transaction has been performed.

showMinimalAddLivemarkUI()

This opens the dialog with only the name and folder pickers visible by default. You can still pass in the various paramaters as the default properties for the new live-bookmark.

 boolean showMinimalAddLivemarkUI(aFeedURI,
                                  aSiteURI,
                                  aTitle,
                                  aDescription,
                                  aDefaultInsertionPoint,
                                  aShowPicker)

See showAddLivemarkUI for a description of the params.

showMinimalAddMultiBookmarkUI()

Show an "Add Bookmarks" dialog to allow the adding of a folder full of bookmarks corresponding to the objects in the uriList. This will be called most often as the result of a "Bookmark All Tabs..." command.

 showAddMultiBookmarkUI(aURIList)

Parameters

aURIList

List of nsIURI objects representing the locations to be bookmarked.

Return type

Return true if any transaction has been performed.

showBookmarkProperties()

Opens the bookmark properties panel for a given bookmark identifier.

 showBookmarkProperties(aId)

Parameters

aId

bookmark identifier for which the properties are to be shown

Return type

Return true if any transaction has been performed.

showFolderProperties()

Opens the folder properties panel for a given folder ID.

 showFolderProperties(aId)

Parameters

aId

an integer representing the ID of the folder to edit

Return type

Return true if any transaction has been performed.

showAddFolderUI()

Shows the "New Folder" dialog.

 showAddFolderUI(aTitle,
                 aDefaultInsertionPoint,
                 aShowPicker)

Parameters

[optional] aTitle

The default title for the new bookmark.

[optional] aDefaultInsertionPoint

The default insertion point for the new item. If set, the folder picker would be hidden unless aShowPicker is set to true, in which case the dialog only uses the folder identifier from the insertion point as the initially selected item in the folder picker.

[optional] aShowPicker

see above

Return type

Return true if any transaction has been performed.

Annotations

These are functions that simplify annotating pages. Information like keywords, descriptions, and POST data is already stored as annotations by Firefox, but you can create additional ones. Using the functions can save you some implementation work. For example, given a uri, the traditional code to get all its annotations would be:

 var annotationService = Components.classes["@mozilla.org/browser/annotation-service;1"]
   .getService(Components.interfaces.nsIAnnotationService);
 try {
   var names = annotationService.getPageAnnotationNames(uri);
 } catch(e) {
   // no annotations
 }
 var annotations = new Array();
 for(var i in names) {
   try {
     annotations.push(annotationService.getPageAnnotation(uri, names[i]));
   } catch(e) {
     // this shouldn't happen
   }
 }

The code using placesUtils collapses a bit to:

 var annotations = PlacesUtils.getAnnotationsForUri(uri);

saving you a bit of clumsy code and leaving Mozilla to make sure everything is written correctly. It also gives you more information that my hastily written (and probably incorrect) example up above. The annotation objects returned or send from/to all these functions all are arrays of objects which have the properties:

name

the annotation name

flags

annotation flags

expires

annotation expiration

mimeType

mimetype of the annotation, usually only used for binary annotations

type

the type used for non-binary annotations

value

the value of the annotation

getAnnotationsForURI()

Fetch all annotations for a URI, including all properties of each annotation which would be required to recreate it.

 array object getAnnotationsForURI(aURI)

Parameters

aURI

The URI for which annotations are to be retrieved.

Return array of objects, each containing the following properties: name, flags, expires, mimeType, type, value

getAnnotationsForItem()

Fetch all annotations for an item, including all properties of each annotation which would be required to recreate it.

 array object getAnnotationsForItem(aItemId)

Parameters

aItemId

The identifier of the itme for which annotations are to be retrieved.

Return type

Return Array of objects, each containing the following properties: name, flags, expires, mimeType, type, value

setAnnotationsForURI()

Annotate a URI with a batch of annotations.

 setAnnotationsForURI(nsIURI aURI,
                      array object aAnnos)

Parameters

aURI

The URI for which annotations are to be set.

aAnnotations

Array of objects, each containing the following properties: name, flags, expires, type, mimeType (only used for binary annotations) value.

setAnnotationsForItem()

Annotate an item with a batch of annotations.

 setAnnotationsForItem(int aItemId,
                       array object aAnnos)

Parameters

aItemId

The identifier of the item for which annotations are to be set

aAnnotations

Array of objects, each containing the following properties: name, flags, expires, type, mimeType (only used for binary annotations) value.

Other

Other functions that I'm not sure how to file.

getViewForNode()

Returns the closet ancestor places view for the given DOM node

 getViewForNode(aNode)

Parameters

aNode

a DOM node

Return type

Return the closet ancestor places view if exists, null otherwsie.

markPageAsTyped()

By calling this before we visit a URL, we will use TRANSITION_TYPED as the transition for the visit to that URL (if we don't have a referrer). This is used when visiting pages from the history menu, history sidebar, url bar, url autocomplete results, and history searches from the places organizer. If we don't call this, we'll treat those visits as TRANSITION_LINK.

 markPageAsTyped(string aURL)

markPageAsFollowedBookmark()

By calling this before we visit a URL, we will use TRANSITION_BOOKMARK as the transition for the visit to that URL (if we don't have a referrer). This is used when visiting pages from the bookmarks menu, personal toolbar, and bookmarks from within the places organizer. If we don't call this, we'll treat those visits as TRANSITION_LINK.

 markPageAsFollowedBookmark(string aURL)

checkURLSecurity()

Allows opening of javascript/data URI only if the given node is bookmarked (see bug 224521).

 checkURLSecurity(aURINode)

Parameters

aURINode

a URI node

Return type

Return true if it's safe to open the node in the browser, false otherwise.

getQueryStringForFolder()

Helper for getting a serialized Places query for a particular folder.

 getQueryStringForFolder(int aFolderId)

Parameters

aFolderId

The folder id to get a query for.

Return type

Return string serialized place URI

getDescriptionFromDocument()

Get the description associated with a document, as specified in a <META> element.

 getDescriptionFromDocument(doc)

Parameters

doc

A DOM Document to get a description for

Return type

Returns a description string if a META element was discovered with a "description" or "httpequiv" attribute, empty string otherwise.

setPostDataForBookmark()

Set the POST data associated with a bookmark, if any. Used by POST keywords.

 setPostDataForBookmark(int aBookmarkId,
                        string aPostData)

aBookmarkId

Return type

Returns string of POST data

getPostDataForBookmark()

Get the POST data associated with a bookmark, if any.

 getPostDataForBookmark(int aBookmarkId)

Parameters

aBookmarkId

Return type

Returns string of POST data if set for aBookmarkId. null otherwise.

getURLAndPostDataForKeyword()

Get the URI (and any associated POST data) for a given keyword.

 getURLAndPostDataForKeyword(aKeyword)

Parameters

aKeyword

keyword

Return type

Returns an array containing a string URL and a string of POST data

getItemDescription()

Retrieve the description of an item

 getItemDescription(aItemId)

Parameters

aItemId

item identifier

Return type

Returns the description of the given item, or an empty string if it is not set.

getMostRecentBookmarkForURI()

Get the most recently added/modified bookmark for a URL, excluding items under tag or livemark containers. -1 is returned if no item is found.

 getMostRecentBookmarkForURI(aURI)

getMostRecentFolderForFeedURI()

 getMostRecentFolderForFeedURI(aURI)

getURLsForContainerNode()

 getURLsForContainerNode(aNode)

openContainerNodeInTabs()

 openContainerInTabs(aNode,
                     aEvent)

openURINodesInTabs()

 openURINodesInTabs(aNodes,
                    aEvent)

createMenuItemForNode()

Helper for the toolbar and menu views.

 createMenuItemForNode(aNode,
                       aContainersMap)