forked from mirrors/gecko-dev
798e791b7a
Rather than accepting either an array or an async function, make it only accept an array. This simplifies the internals for future refactoring, and avoids depending on async functions created in other globals. Differential Revision: https://phabricator.services.mozilla.com/D193813
73 lines
3.3 KiB
ReStructuredText
73 lines
3.3 KiB
ReStructuredText
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 <toolkit/components/places/PlacesTransactions.sys.mjs>`
|