Warning: The content of this article may be out of date.
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
nsIURI createFixedURI(string aSpec); |
string getFormattedString(string key, string params); |
string getString(string key); |
boolean nodeIsFolder( |
boolean nodeIsBookmark( |
boolean nodeIsSeparator( |
boolean nodeIsVisit( |
boolean nodeIsURI( |
boolean nodeIsQuery( |
boolean nodeIsReadOnly( |
boolean nodeIsHost( |
boolean nodeIsContainer( |
boolean nodeIsDynamicContainer( |
|
boolean nodeIsLivemarkItem( Obsolete since Gecko 21 |
boolean isReadonlyFolder( |
int getIndexOfNode( |
string wrapNode( |
array unwrapNodes(string blob, string aType); |
|
|
boolean showAddBookmarkUI( |
boolean showMinimalAddBookmarkUI( |
boolean showAddLivemarkUI( |
boolean showMinimalAddLivemarkUI( |
boolean showMinimalAddMultiBookmarkUI(array |
boolean showBookmarkProperties(int aId); |
boolean showFolderProperties(int aId); |
boolean showAddFolderUI(string aTitle, int aDefaultInsertionPoint, boolean aShowPicker); |
array object getAnnotationsForURI( |
array object getAnnotationsForItem(int aItemId); |
void setAnnotationsForURI( |
void setAnnotationsForURI(int aItemId, object aAnnos); |
getViewForNode( |
void markPageAsTyped(string aURL); |
void markPageAsFollowedBookmark(string aURL); |
boolean checkURLSecurity( |
string getQueryStringForFolder(int aFolderId); |
string getDescriptionFromDocument( |
string setPostDataForBookmark(int aBoomarkId, string aPostData); |
string getPostDataForBookmark(int aBoomarkId); |
array string getURLAndPostDataForKeyword(string aKeyword); |
string getItemDescription(int aItemId); |
|
|
|
void openContainerNodeInTabs( |
void openURINodesInTabs(array |
void createMenuItemForNode( |
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
aOverrideURI
- [optional] 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)