Places:Transactions

Introduction

The Places:Controller performs all edit operations (node creation, removal, modification) on Bookmark items using Transactions. Transactions support the execution of commands, as well as reverting (undoing) and repeating (redoing) them. Transactions thus support the Undo/Redo feature.

This document talks about how the Transactions are used, and what you should know as a programmer.

All Edits Are Transaction-Based

Any edit you perform to a bookmark item in a Places View is generally undo-able using the undo command (and then subsequently re-doable). To take advantage of this in your code, you need to use one of the Places*Transactions defined in controller.js, rather than just using the data APIs directly.

Consturcting a Transaction

To create a new folder called "Foo" at the end of the Bookmarks Toolbar, you might write code that looks like this:

var bms = 
    Cc["@mozilla.org/browser/nav-bookmarks-service;1"].
    getService(Ci.nsINavBookmarksService);
var txn = new PlacesCreateFolderTransaction("Foo", bms.toolbarRoot, -1);
PlacesController.tm.doTransaction(txn);

The PlacesController maintains an active transaction manager for each instance of itself (e.g. one for the Places Organizer, one for each browser window, etc. This object implements nsITransactionManager.

Basic Transactions

All Places transactions inherit from PlacesBaseTransaction.

Here are some of the basic transactions provided:

function PlacesCreateItemTransaction(uri, container, index);
function PlacesCreateSeparatorTransaction(container, index);
function PlacesMoveFolderTransaction(id, oldContainer, oldIndex, newContainer, newIndex);
function PlacesMoveItemTransaction(uri, oldContainer, oldIndex, newContainer, newIndex);
function PlacesRemoveItemTransaction(uri, oldContainer, oldIndex);
function PlacesRemoveSeparatorTransaction(oldContainer, oldIndex);
function PlacesEditItemTitleTransaction(uri, newTitle);
function PlacesEditFolderTitleTransaction(id, newTitle);
function PlacesEditBookmarkKeywordTransaction(uri, newKeyword);

Grouping Transactions

Several transactions can be aggregated together into a single atomic unit of work using PlacesAggregateTransaction. For example, consider creating and naming a new Bookmark:

var ios = 
    Cc["@mozilla.org/network/io-service"].
    getService(Ci.nsIIOService);
var uri = ios.newURI("http://www.mozilla.org/", null, null);
var bms = 
    Cc["@mozilla.org/browser/nav-bookmarks-service;1"].
    getService(Ci.nsINavBookmarksService);
var createTxn = new PlacesCreateItemTransaction(uri, bms.toolbarRoot, -1);
var nameTxn = new PlacesEditItemTitleTransaction(uri, "Mozilla.org");

var aggTxn = new PlacesAggregateTransaction("Create Bookmark", 
                                            [createTxn, nameTxn]);
PlacesController.tm.doTransaction(aggTxn);

The aggregator does/undoes/redoes each of the transactions in the set provided.