From 26a029d407be480d791972afb5975cf62c9360a6 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 19 Apr 2024 02:47:55 +0200 Subject: Adding upstream version 124.0.1. Signed-off-by: Daniel Baumann --- .../components/places/docs/PlacesTransactions.rst | 73 ++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 browser/components/places/docs/PlacesTransactions.rst (limited to 'browser/components/places/docs/PlacesTransactions.rst') diff --git a/browser/components/places/docs/PlacesTransactions.rst b/browser/components/places/docs/PlacesTransactions.rst new file mode 100644 index 0000000000..474a3d3170 --- /dev/null +++ b/browser/components/places/docs/PlacesTransactions.rst @@ -0,0 +1,73 @@ +PlacesTransactions +================== + +This module serves as the transactions manager for Places (hereinafter *PTM*). +We need a transaction manager because the bookmarking UI allows users to use +`Undo` and `Redo` functions. To implement transactions a layer has been inserted +between the UI and the Bookmarks API. +This layer stores all the requested changes in a stack and perform calls to the +API. Interall the transactions history is implemented as an array storing +changes from oldest to newest. + +Transactions implements all the elementary UI commands: creating items, editing +their properties, and so forth. All the commands are stored in transactions +history and are executed in order. + +Constructing transactions +------------------------- + +Transactions are exposed by the module as constructors +(e.g. PlacesTransactions.NewFolder). The input for these constructors is taken +in the form of a single argument, a plain object consisting of the properties +for the transaction. Input properties may either be required or optional (for +example, *keyword* is required for the ``EditKeyword`` transaction, but optional +for the ``NewBookmark`` transaction). + +Executing Transactions (the `transact` method of transactions) +-------------------------------------------------------------- + +Once a transaction is created, you must call it's ``transact`` method for it to +be executed and take effect. +That is an asynchronous method that takes no arguments, and returns a promise +that resolves once the transaction is executed. + +Executing one of the transactions for creating items (``NewBookmark``, +``NewFolder``, ``NewSeparator``) resolves to the new item's *GUID*. +There's no resolution value for other transactions. + +If a transaction fails to execute, ``transact`` rejects and the transactions +history is not affected. As well, ``transact`` throws if it's called more than +once (successfully or not) on the same transaction object. + +Batches +------- + +Sometimes it is useful to "batch" or "merge" transactions. + +For example, something like "Bookmark All Tabs" may be implemented as one +NewFolder transaction followed by numerous NewBookmark transactions - all to be +undone or redone in a single undo or redo command. + +Use ``PlacesTransactions.batch`` in such cases, passing an array of transactions +which will be executed in the given order and later be treated a a single entry +in the transactions history. ``PlacesTransactions.batch`` returns a promise +resolved when the batch has been executed. If a transaction depends on results +from a previous one, it can be replaced in the array with a function that takes +``previousArguments`` as only argument, and returns a transaction. + +The transactions-history structure +---------------------------------- + +The transactions-history is a two-dimensional stack of transactions: the +transactions are ordered in reverse to the order they were committed. +It's two-dimensional because PTM allows batching transactions together for the +purpose of undo or redo. + +The undoPosition property is set to the index of the top entry. If there is no +entry at that index, there is nothing to undo. Entries prior to undoPosition, +if any, are redo entries, the first one being the top redo entry. + +Sources +------- + +* :searchfox:`PlacesTransactions.sys.mjs ` -- cgit v1.2.3