Displaying Places information using views

Views are one component of the Places model-view-controller design. Use them to display nsINavHistoryResult objects to the user. See Querying Places for information about obtaining and using nsINavHistoryResult objects, which this page assumes you are familiar with.

An nsINavHistoryResult instance provides the data for a view. The view is responsible for expanding the root nsINavHistoryContainerResultNode of this instance and displaying the nsINavHistoryResultNode objects contained therein.

The built-in views

If you need to show the contents of Bookmarks or History in your extension or application, you may want to use the built-in Places views, which are generic and will save you a lot of time writing basic functionality so that you can focus on building your extension or application.

Places provides the following built-in views:

• Tree
• Menu
• Toolbar

Instantiating

The three built-in views are simply standard XUL elements with a special type attribute whose value is "places".

Every XUL document containing a built-in view must import the stylesheet browser/components/places/content/places.css and overlay the file browser/components/places/content/placesOverlay.xul:

<?xml-stylesheet href="chrome://browser/content/places/places.css" ?>
<?xul-overlay href="chrome://browser/content/places/placesOverlay.xul" ?>

It's this stylesheet that binds elements with the special type attribute to one of the views. The overlay contains JavaScript required by the views. It also contains the built-in Places context menu and commands, which you may want to take advantage of in your own uses of the views.

Connecting a view to its data

To hook up a built-in view to its data, use the view's special place attribute.

You may specify the attribute directly in the XUL or set its corresponding property via JavaScript. Its value is the URI of a query, and the data shown in the view are the results of this query. For simple queries whose URIs do not change over the life of the view, you might specify the place attribute directly in the XUL. For more complicated queries or queries whose URIs you plan on changing, you will want to set the view's place property dynamically using JavaScript. Note that in the latter case it is not sufficient to call setAttribute on the element; use the element's place property instead. See Querying Places and Places query URIs for information on query URIs.

The following example uses the built-in tree view to display bookmarks whose titles or URLs contain "mozilla". Remember that, because XUL is XML, any ampersands in query URIs must be written as entity reference & and not simply &.

<tree type="places" place="place:terms=mozilla&amp;onlyBookmarked=1&amp;queryType=1">
  <treecols>
    <treecol id="title" label="My Bookmarks" flex="1" primary="true" />
  </treecols>
  <treechildren />
</tree>

The next example does the same as the last but uses JavaScript to set the tree's place attribute:

var histServ =
  Cc["@mozilla.org/browser/nav-history-service;1"].
  getService(Ci.nsINavHistoryService);

var query = histServ.getNewQuery();
query.searchTerms = "mozilla";
query.onlyBookmarked = true;

var opts = histServ.getNewQueryOptions();
opts.queryType = opts.QUERY_TYPE_BOOKMARKS;

var uri = histServ.queriesToQueryString([query], 1, opts);
var tree = document.getElementById("mytree");
tree.place = uri;

These two examples use the built-in tree view, but the point is to demonstrate the use of the place attribute and property. In this regard the built-in menu and toolbar views are no different.

When a view's underlying data changes, the view will automatically update itself so that it displays the new data. This update is handled by logic between the view and its results. All Places views implement or own an instance of interface nsINavHistoryResultViewer, which is the point of interaction between a view and its results. Results themselves observe Places changes, and if on a Places change a result determines that its data specifically has changed, it notifies its view by calling an appropriate method of nsINavHistoryResultViewer. Once notified, the view is responsible for updating itself.

Tree view

Create a built-in tree view by setting the type attribute to "places" on a tree element. The treechildren element should be empty:

<tree type="places">
  <treecols>
    <treecol id="title" flex="1" primary="true" />
    <treecol id="url" flex="1" />
  </treecols>
  <treechildren />
</tree>

The tree view is implemented in browser/components/places/content/tree.xml. See the tree reference and Trees tutorial for general information about trees.

If you would like your tree view to be styled in the same manner that Firefox styles its uses of the view, you should include the following stylesheet. Note that this stylesheet is different from the one given above, which must be included if you use a built-in Places view. The following stylesheet is optional and only applies styles and icons to the built-in tree view:

<?xml-stylesheet href="chrome://browser/skin/places/places.css" ?>

For examples of instantiating a tree view from JavaScript rather than XUL, see Programmatic generation of the built-in tree view.

Column binding

The built-in tree view makes it easy to hook up specific columns of your tree to specific properties of the result. It does so by recognizing certain magic values of the id attribute on your treecol elements. A property in the result is bound to a column via that column's id attribute. For example, by setting a column's id to "title", you tell the view to display the title of the nsINavHistoryResultNode of each row in that column.

The following table shows the mappings between these magic column id values and their corresponding nsINavHistoryResultNode properties:

*keyword and description are looked up in the Places database using the nsINavHistoryResultNode property itemId.

**The title column (and only the title column) automatically receives the favicon referenced by the nsINavHistoryResultNode property icon.

You may specify as few or as many of these magic columns as you want, and your tree may of course contain other columns as well.  In lieu of setting an id on a treecol, you may specify an anonid attribute. This is useful when you need the id for another purpose or when a treecol is contained in anonymous content, as in XBL. If both an id attribute and anonid attribute are specified, the anonid is used.

The built-in tree view is provided as a general-purpose convenience. If you need to display additional data or otherwise require more control over your view, you may need to write your own. See Creating custom views below. 

Using the tree view

So you've got a built-in tree view. How do you ask it about the data it displays?

First, see nsIPlacesView. Like all Places views, the built-in tree view implements this interface, which provides broad methods such as getting the view's nsINavHistoryResult instance and examining the view's selection.

Second, know this: when it comes to trees, "view" is an overloaded word. This document describes Places views. Places views are just XUL elements; the built-in Places tree view is just a tree element whose type attribute is equal to "places", as described above. But recall that all trees—Places view or not—display their data using another kind of view, nsITreeView. The built-in Places tree view therefore has a view of its own, the built-in Places tree view's view. This view is an object that implements three interfaces: from most specific to most general, nsINavHistoryResultTreeViewer, nsINavHistoryResultObserver , and nsITreeView. nsINavHistoryResultTreeViewer maps between row indices and the nsINavHistoryResultNode objects contained in the rows. nsINavHistoryResultObserver notifies observing clients about updates when the underlying data changes. It's not so useful for our purposes here. nsITreeView provides a high-level interface for trees in general.

Finally, the built-in tree view implements several convenience methods and properties of its own.

You therefore have four points of interaction with the built-in Places tree view:

1. The convenience methods and properties implemented directly on the view itself,
2. the nsIPlacesView interface of the view itself,
3. the nsINavHistoryResultTreeViewer interface of the view's view, and
4. the nsITreeView interface of the view's view.

The methods and properties implemented directly on the view are very specific, while the interface provided by nsITreeView is very general. Tasks sometimes require you to use more than one of these points of interaction, going from one layer of generality to another.

To put it in terms of JavaScript, say you have a variable named treeView that references your Places tree view:

var treeView = document.getElementById("myPlacesTreeView");

Points 1 and 2 apply to this variable.

The tree view's view is the object at treeView.view.  Points 3 and 4 apply to this object.

var treeViewView = treeView.view;

Convenience methods

Because the built-in tree view is both widely used and complex, several convenience methods are implemented directly on it to make common tasks easier.

applyFilter()

Loads a new empty query with particular search terms and folders.

void applyFilter(
  string filterString,
  array folderRestrict
);

Parameters

filterString

The new query's searchTerms property will be set to this string.

folderRestrict

The setFolders function of the new query will be called on this array of folder IDs. Optional.

load()

Sets the queries that the view displays. This method may be used as an alternative to setting the tree's place property as described above.

void load(
  array queries,
  nsINavHistoryQueryOptions options
);

Parameters

queries

An array of nsINavHistoryQuery objects.

options

An nsINavHistoryQueryOptions object.

selectItems()

Selects the first node in the tree that matches each given item ID. It will open any parent nodes that it needs to in order to show the selected items.

void selectItems(
  array aIDs,
  array aOpenContainers
);

Parameters

aIDs

An array of item IDs.

aOpenContainers

If true or undefined, folders that are closed are also searched. They are not searched otherwise. Optional.

selectNode()

Causes a particular node to be selected in the tree, resulting in all containers above the node in the hierarchy to be opened so that the node is visible.

void selectNode(
  nsINavHistoryNode node
);

Parameters

node

The nsINavHistoryResultNode to select.

selectPlaceURI()

Causes a particular node represented by the specified placeURI to be selected in the tree. All containers above the node in the hierarchy will be opened so that the node is visible.

void selectPlaceURI(
  string placeURI
);

Parameters

placeURI

The URI (as a string) of the nsINavHistoryResultNode to select.

Convenience properties

In addition to the methods above, some properties of convenience are implemented directly on the built-in tree view.

Example uses

To get the nsINavHistoryResultNode at a specific row:

var treeView = document.getElementById("myPlacesTreeView");
var rowIndex = 0;
var historyResultNode = treeView.view.nodeForTreeIndex(rowIndex);

To get the row index of a specific nsINavHistoryResultNode:

var treeView = document.getElementById("myPlacesTreeView"); 
var rowIndex = treeView.view.treeIndexForNode(historyResultNode);

To select a row in the tree whose node has a specific URI:

var treeView = document.getElementById("myPlacesTreeView");
treeView.selectPlaceURI("some place URI");

To select a row in the tree that contains a specific nsINavHistoryResultNode:

var treeView = document.getElementById("myPlacesTreeView");
treeView.selectNode(someHistoryResultNode); 

PlacesTreeView

The built-in tree view is backed by an instance of PlacesTreeView, a prototype defined in browser/components/places/content/treeView.js. PlacesTreeView performs double duty for the built-in tree view: it implements both nsITreeView and much of the functionality required of a Places view. The latter functionality is specified specifically by interface nsINavHistoryResultTreeViewer, which inherits from the more general nsINavHistoryResultObserver .

Because of PlacesTreeView's double duty, you can use it to bridge a query result and a tree element:

var result = historyService.executeQuery(query, opts); // your Places query result
var tree = document.getElementById("mytree");          // your tree element

var showRootNodeInTree = true;
var view = new PlacesTreeView(showRootNodeInTree);

// Here's the bridge!
result.addObserver(view.QueryInterface(Components.interfaces.nsINavHistoryResultObserver));
tree.view = view.QueryInterface(Components.interfaces.nsITreeView);

In fact this is how the built-in tree view works.  It runs code similar to the above when you set its place property or call its load method.

While you are free to set up your tree view in this manner, it's not recommended if you are using the built-in view. Doing so circumvents updating the view's place attribute, causing it to fall out of sync with the view's query result. Use the view's load method or place property instead and let it do the work for you. If, on the other hand, you are writing a custom tree view, you will need to write similar code at some point.

Menu view

You can display Places information in a popup menu.

Create a built-in menu view by setting the type attribute to "places" on an empty menupopup element (which would be a child of some parent menu element):

<menu>
  <menupopup type="places" />
</menu>

The place attribute or property should be set on the menupopup as well.

You can add Places information to a popup like this:

<menu id="bookmarksMenu">
  <menupopup placespopup="true">
    onpopupshowing="if (!document.getElementById('bookmarksMenu')._placesView)
                        new PlacesMenu(event, 'place:folder=BOOKMARKS_MENU');"
  </menupopup>
</menu> 

The menu view is implemented in browser/components/places/content/menu.xml. See the menupopup and menu references and Popup Menus tutorial for general information about menus.

Toolbar view

Create a built-in toolbar view by setting the type attribute to "places" on an empty hbox element (which would be a child of some parent toolbaritem element, itself the child of a toolbar element):

<toolbar>
  <toolbaritem>
    <hbox type="places" />
  </toolbaritem>
</toolbar>

The place attribute or property should be set on the hbox as well.

The toolbar view is implemented in browser/components/places/content/toolbar.xml. See the toolbaritem and toolbar references and Toolbars tutorial for general information about toolbars.

Using a view

So you've got a Places view. How do you interact with it?

Because it is fairly complex, the built-in tree view provides uniquely tailored interfaces to make it easier to use. If you write your own complex view, you might do something similar.

But all Places views should provide a minimal interface so that you and controllers have a consistent, general way to interact with them. For this reason views implement interface nsIPlacesView. It allows you to do things like getting the nsINavHistoryResult instance that a view displays and examining its selected nodes. In fact the special place property described above is a property of this interface.

Creating custom views

If you need greater flexibility than a built-in view provides, you can create a custom view. Good reasons for needing a custom view might include (but are in no way limited to):

• Displaying custom columns alongside those provided by the built-in tree view.
• Changing the way a built-in view displays dates or other data.
• Inserting information into the display that is not determined by the underlying data.
• Displaying Places information in an element not covered by one of the built-in views.

Potentially bad reasons for creating a custom view might include (but are not limited to):

• Changing only the superficial appearance of a built-in view rather than the content it displays. Try CSS here.
• Hiding columns of the built-in tree view. Just leave out the treecol elements you want to hide.
• Managing how the view responds to clicks, commands, and other user interaction. Don't break the separation of concerns here. Views are for displaying data, controllers for logic. You can hook up a built-in view to the standard Places commands and context menu, or you can create a custom controller to handle custom commands. See View Controller for more information.

Regardless of the kind of view you are writing, it should implement interface nsIPlacesView. (nsIPlacesView is currently not a true interface; the built-in views simply implement its methods and attributes directly.) As described above in Using a view, this interface provides controllers and other callers a consistent, general way to interact with views.

Your view should also either implement or own an instance of nsINavHistoryResultObserver. To hook up your view to a nsINavHistoryResult object, you call addObserver() on the result, passing the viewer object which is an instance of nsINavHistoryResultObserver. If your view implements nsINavHistoryResultObserver, then you can pass your viewer object. If your view contains an internal instance of nsINavHistoryResultObserver, you would pass it instead. (The three built-in views take this approach.) The results object then communicates to your view via this instance, notifying it about changes in the underlying data so it can update its display.

var bmServ =
    Components.classes["@mozilla.org/browser/nav-bookmarks-service;1"].
    getService(Components.interfaces.nsINavBookmarksService);
var histServ =
  Components.classes["@mozilla.org/browser/nav-history-service;1"].
  getService(Components.interfaces.nsINavHistoryService);

var opts = histServ.getNewQueryOptions();
var query = histServ.getNewQuery();
query.setFolders([bmServ.placesRoot], 1);
var result = histServ.executeQuery(query, opts);

// Here myView is your view, and myView.viewer is some object implementing nsINavHistoryResultObserver.  
result.addObserver(myView.viewer);

More practically, a variation of the code above might be internal to a method on your view. A caller would pass in a result or a query, and you would execute the query and add your view as an observing client using addObserver(). (That's how the load method of the built-in tree view works.)

When you let your view observe the result, the result will in turn set the result property on the given nsINavHistoryResultObserver. You should not set the result property explicitly. To disconnect a viewer from its result, call removeObserver(view) on your result.

Be careful about reference cycles. The viewer and the result both hold owning references to each other. For these objects to be freed during JavaScript garbage collection, you must clear this cycle by calling result.removeObserver(view). (For example, the built-in tree view does this automatically. When the tree is destroyed or a different nsITreeView is associated with the tree, the tree will set the tree property of the old nsITreeView to null. Because the object implementing nsITreeView also implements nsINavHistoryResultObserver, the viewer then disconnects itself from the result by calling removeObserver().)

Creating custom tree views

Custom Places tree views can be a lot of work. Take a look at Using the tree view above to get an idea of what's required. Custom nsITreeViews in general are a lot of work, and if you are not familiar with creating custom nsITreeViews, see the Custom Tree Views and Tree View Details pages in the XUL tutorial. All of that information is relevant here.

Fortunately you can commandeer parts of the built-in tree view to suit your purposes. The JavaScript prototype backing the built-in view, PlacesTreeView, is especially useful since it implements all three of nsINavHistoryResultTreeViewer, nsINavHistoryResultObserver, and nsITreeView. You can therefore implement your own custom functionality on top of PlacesTreeView while relying on it for non-custom functionality and much of the tedious work. One strategy is to create your custom object(s) implementing each of these interfaces, support your custom behavior with them, but pass off everything else to a PlacesTreeView instance that you would own. Perhaps an easier strategy is to modify an existing PlacesTreeView instance, which is what the following example does.

The following JavaScript creates a new PlacesTreeView instance but overrides two of its nsITreeView methods to display columns not present in the built-in tree view:

var view = new PlacesTreeView();

view._getCellText = view.getCellText;
view.getCellText = function (aRowIndex, aCol) {
  // Handle our special columns. As with PlacesTreeView, we'll recognize
  // them by their id's or anonid's.
  switch (aCol.id || aCol.element.getAttribute("anonid"))
  {
  // URI for all nodes (like folders), not just URI nodes (like bookmarks)
  case "fullURI":
    return this.nodeForTreeIndex(aRowIndex).uri;
    break;
  // Index of node in parent container
  case "indexInParent":
    return this.nodeForTreeIndex(aRowIndex).bookmarkIndex;
    break;
  // Is the row even or odd?
  case "parity":
    return (aRowIndex % 2 === 0 ? "even" : "odd");
    break;
  }
  // Otherwise, pass off to the original getCellText method.
  return this._getCellText(aRowIndex, aCol);
};

view._cycleHeader = view.cycleHeader;
view.cycleHeader = function (aCol) {
  switch (aCol.id || aCol.element.getAttribute("anonid"))
  {
  case "fullURI":
  case "indexInParent":
  case "parity":
    // You might resort by column here.
    break;
  default:
    this._cycleHeader(aCol);
    break;
  }
};

// Execute a query and gets its result.
var bmServ =
    Components.classes["@mozilla.org/browser/nav-bookmarks-service;1"].
    getService(Components.interfaces.nsINavBookmarksService);
var histServ =
  Components.classes["@mozilla.org/browser/nav-history-service;1"].
  getService(Components.interfaces.nsINavHistoryService);
var opts = histServ.getNewQueryOptions();
var query = histServ.getNewQuery();
query.setFolders([bmServ.placesRoot], 1);
var result = histServ.executeQuery(query, opts);

// Hook up the result's viewer and the tree's nsITreeView to our custom view.
var treeView = document.getElementById("myTreeView");
result.addObserver(view);
treeView.view = view;

The following XUL defines the myTreeView element referenced in the JavaScript:

<tree id="myTreeView" flex="1">
  <treecols>
    <treecol id="title" label="title" flex="1" primary="true" />
    <splitter class="tree-splitter" />
    <treecol anonid="fullURI" label="fullURI" flex="1" />
    <splitter class="tree-splitter" />
    <treecol id="indexInParent" label="indexInParent" />
    <splitter class="tree-splitter" />
    <treecol id="parity" label="parity" />
  </treecols>
  <treechildren />
</tree>

The full code listing is available in the Files section of the page below.

Note that the tree element above does not have the special type attribute common to the built-in views. It's just a regular tree element that you've hooked up to a Places query, with none of the convenience properties or methods of the built-in Places tree view. If your custom view is used only once in your application, code similar to the above will likely be sufficient; it's enough to create a single PlacesTreeView object, modify it, and attach it to a regular tree. If your view is widely used, however, you may want to take a cue from the built-in tree view and create your own JavaScript prototype similar to PlacesTreeView and your own XBL tree binding so that much of the work of creating views and viewers and hooking them up to results is abstracted away.

The attribute nsINavHistoryResultNode.viewIndex is provided explicitly for the use of the view. This value is initialized to -1 when each node is created. You can use this value to keep track of visible nodes. PlacesTreeView uses this attribute to store the row index that the node is on.

See also

• nsIPlacesView
• Querying Places
• View Controller