diff options
Diffstat (limited to '')
12 files changed, 474 insertions, 0 deletions
diff --git a/browser/components/places/docs/Bookmarks.rst b/browser/components/places/docs/Bookmarks.rst new file mode 100644 index 0000000000..1c830c74ef --- /dev/null +++ b/browser/components/places/docs/Bookmarks.rst @@ -0,0 +1,50 @@ +Bookmarks.jsm +============= + +Asynchronous API for managing bookmarks. +Bookmarks are organized in a tree structure, and include URLs, folders and separators. Multiple bookmarks for the same URL are allowed. +To be able to use “Redo” and “Undo” the Firefox UI views are not using API directly but use :doc:`PlacesTransactions`. + +Structure +--------- + +Each bookmark-item is represented by an object having the following properties: + + * ``guid (string)`` - the globally unique identifier of the item + * ``parentGuid (string)`` - the globally unique identifier of the folder containing the item. This will be an empty string for the Places root folder. The root folder is never accessible to the user, it just contains other roots, like toolbar, menu, unfiled, mobile + * ``index (number)`` - the zero-based position of the item in the parent folder + * ``dateAdded (Date)`` - the time at which the item was added + * ``lastModified (Date)`` - the time at which the item was last modified + * ``type (number)`` - the item's type, either ``TYPE_BOOKMARK``, ``TYPE_FOLDER`` or ``TYPE_SEPARATOR`` + +The following properties are only valid for URLs or folders: + + * ``title (string)`` - the item's title, if any. Empty titles and null titles are considered the same. Titles longer than ``DB_TITLE_LENGTH_MAX`` will be truncated + +The following properties are only valid for URLs: + + * ``url (URL, href or nsIURI)`` - the item's URL. Note that while input objects can contain either an URL object, an href string, or an nsIURI, output objects will always contain an URL object. An URL cannot be longer than ``DB_URL_LENGTH_MAX``, methods will throw if a longer value is provided. + +Main functions +-------------- + + * Every bookmark has a globally unique identifier represented by ``string`` also known as ``Guid``. ``Guid`` helps us to locate our bookmark in database, change it, move, copy or delete. + + + * Creating new bookmark. When we inserting a bookmark-item into the bookmark tree, we need to set up a parentGuid property, which is a section where bookmark will be located, for example - Toolbar (``"toolbar_____"``). Location can be any other folder guid, or special root folder guids like: + + - rootGuid: ``"root________"`` + - menuGuid: ``"menu________"`` + - toolbarGuid: ``"toolbar_____"`` + - unfiledGuid: ``"unfiled_____"`` + - mobileGuid: ``"mobile______"`` + + * As well, you would have to specify bookmark type (for example, ``TYPE_BOOKMARK`` for a single bookmark, or ``TYPE_FOLDER`` for a folder). + + * Remove bookmark. For removing one or more bookmark items, you would have to specify ``guidOrInfo``. This may be a bookmark guid, an object representing an item, or an array of objects representing the items. You can specify options for removal - throwing an exception when attempting to remove a folder that is not empty and the change source forwarded to all bookmark observers. (Default source is pointing to nsINavBookmarksService::SOURCE_DEFAULT). Removing a bookmark returns a promise which could be: resolved by completion or rejected, in case there are no matching bookmarks to be removed. + + * Fetching information about a bookmark-item. Any successful call to this method resolves to a single bookmark-item (or null), even when multiple bookmarks may exist (e.g. fetching by url). If you wish to retrieve all of the bookmarks for a given match, you would have to use the callback. Input for fetching a bookamrk can be either a guid or an object with one of filtering properties (for example, ``url`` - retrieves the most recent bookmark having the given URL). Fetching returns the promise which is resolved on completion, rejects if any errors happens through fetch or throws an error if any of the specified arguments are invalid. + +Each successful operation is notified through the PlacesObservers :doc:`notifyObservers` interface. + +Full file with actual javadoc and description of each method - `Bookmarks.jsm`_ diff --git a/browser/components/places/docs/History.rst b/browser/components/places/docs/History.rst new file mode 100644 index 0000000000..5dbf3704dc --- /dev/null +++ b/browser/components/places/docs/History.rst @@ -0,0 +1,43 @@ +History.jsm +=========== + +Asynchronous API for managing history. + +Structure +--------- + +The API makes use of `PageInfo` and `VisitInfo` objects, defined as follows. + +A `PageInfo` object is any object that contains A *subset* of the following properties: + + * ``guid (string)`` - the globally unique id of the page + * ``url (URL, href or nsIURI)`` - the full URI of the page. Note that `PageInfo` values passed as argument may hold ``nsIURI`` or ``string`` values for property ``url``, but `PageInfo` objects returned by this module always hold ``URL`` values + * ``title (string)`` - the title associated with the page, if any + * ``description (string)`` - the description of the page, if any + * ``previewImageURL (URL, nsIURI or string)`` - the preview image URL of the page, if any + * ``frecency (number)`` - the frecency of the page, if any. Note that this property may not be used to change the actual frecency score of a page, only to retrieve it. In other words, any "frecency" field passed as argument to a function of this API will be ignored + * ``visits (Array<VisitInfo>)`` - all the visits for this page, if any + * ``annotations (Map)`` - a map containing key/value pairs of the annotations for this page, if any + +A `VisitInfo` object is any object that contains A SUBSET of the following properties: + + * ``date (Date)`` - the time the visit occurred + * ``transition (number)`` - how the user reached the page + * ``referrer (URL, nsIURI or string)`` - the referring URI of this visit. Note that `VisitInfo` passed as argument may hold ``nsIURI`` or ``string`` values for property ``referrer``, but `VisitInfo` objects returned by this module always hold ``URL`` values + +Main functions +-------------- + + * Fetching. Fetch the available information for one page. You would have to specify as a string a unique identifier (Guid) or url (url, nsIURI or href). Fetching step returns a promise which is successfully resolved when fetch is completed and page is found. Throws an error when Guid or url does not have an expected type or, if it is a string, url / Guid is not valid. + + * Removing pages / visits from database. You would have to specify the desired page / object visit to be removed. Returns a promise which is resolved with true boolean. Throws an error when 'pages' has an unexpected type or if there are no data for provided string / filter. + + * Determining if a page has been visited. Connects with database and inquries if specified page has been visited or not. Returns a promise which is resolved with a true boolean value if page has been visited, falsy value if not. Throws an error if provided data is not a valid Guid or uri. + + * Clearing all history. Returns a promise which is resolved when operation is completed. + + * Updating an information for a page. Currently, it supports updating the description, preview image URL and annotations for a page, any other fields will be ignored (this function will ignore the update if the target page has not yet been stored in the database. ``History.fetch`` could be used to check whether the page and its meta information exist or not). If a property 'description' is provided, the description of the page is updated. An empty string or null will clear the existing value in database, and description length should not be longer than ``DB_DESCRIPTION_LENGTH_MAX``. If a property 'siteName' is provided the site name of the page is updated, and 'previewImageURL' updates the preview image URL of the page. Applies same rules as ones for description regarding empty string clearing existing data and max length as ``DB_SITENAME_LENGTH_MAX`` for site name, ``DB_URL_LENGTH_MAX`` for preview image. Property 'annotations' uppdates the annotation. It should be a map, containign key/values pairs, if the value is falsy, the annotation will be removed. The keys must be Strings, the values should be Boolaen, Number or Strings. Updating information returns a promise which is rejected if operation was unsuccessful or resolved once the update is complete. Throws an error when 'pageInfo' has an unexpected type, invalid url / guid or has neither 'description' nor 'previewImageURL'. + +Each successful operation is notified through the PlacesObservers :doc:`notifyObservers` interface. + +Full file with actual javadoc and description of each method - `History.jsm`_ diff --git a/browser/components/places/docs/PlacesTransactions.rst b/browser/components/places/docs/PlacesTransactions.rst new file mode 100644 index 0000000000..fd6d7cc21a --- /dev/null +++ b/browser/components/places/docs/PlacesTransactions.rst @@ -0,0 +1,43 @@ +PlacesTransactions.jsm +====================== + +This module serves as the transactions manager for Places (hereinafter *PTM*). Generally, we need a transaction manager because History and Bookmark UI allows users to use `Undo / Redo` functions. To implement those transaction History and Bookmark needed to have a layer between Bookmark API and History API. This layer stores all requested changes in a stack and perform calls to API. That construction allows users perform `Undo / Redo` simply removing / adding that transaction and call to API from an array. Inside array we store changes from oldest to newest. + +Transactions implements all the elementary UI commands: creating items, editing their various properties, and so forth. All those commands stored in array and are completed one after another. + + +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 be either 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. *Transact* 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. + +Using ``PlacesTransactions.batch`` in such cases can take either an array of transactions which will be executed in the given order and later be treated a a single entry in the transactions history. Once the generator function is called a batch starts, and it lasts until the asynchronous generator iteration is complete. + +``PlacesTransactions.batch`` returns a promise that is to be resolved when the batch ends. “Nested" batches are not supported, if you call batch while another batch is still running, the new batch is enqueued with all other PTM work and thus not run until the running batch ends. The same goes for undo, redo and clearTransactionsHistory. + +It’s important not to await any promise from batch function for such methods, as: undo, redo, clearTransactionsHistory. Doing so causing a complete shutdown of PlacesTransactionManager, not allowing execution of any transactions. + +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. + +Full file with actual javadoc and description of each method - `PlacesTransactions.jsm`_ diff --git a/browser/components/places/docs/architecture-overview.rst b/browser/components/places/docs/architecture-overview.rst new file mode 100644 index 0000000000..5149a371fd --- /dev/null +++ b/browser/components/places/docs/architecture-overview.rst @@ -0,0 +1,105 @@ +Architecture Overview +===================== + +Because Mozilla used to ship a framework called XULRunner, Places is split into a Toolkit and a Browser part. The toolkit part is usually made up of product-agnostic APIs, those can be used by any kind of project, not just Web Browsers. The browser part is the one containing code specific to the Firefox browser. + +Codebase +-------- + +Most of the codebase is written in: + * **JavaScript** + * **C++** (for ex., database initialization code or some of the visit tracking code). + +Frontend +-------- + +The frontend part of the bookmarking experience includes various kind of views: + * `Trees`_ + * `Menus`_ + * `Toolbars`_ + + .. _Trees: https://searchfox.org/mozilla-central/source/browser/components/places/content/places-tree.js + .. _Menus: https://searchfox.org/mozilla-central/rev/4c184ca81b28f1ccffbfd08f465709b95bcb4aa1/browser/components/places/content/browserPlacesViews.js#1990 + .. _Toolbars: https://searchfox.org/mozilla-central/rev/4c184ca81b28f1ccffbfd08f465709b95bcb4aa1/browser/components/places/content/browserPlacesViews.js#894 + +All the views share a common `Controller`_ that is responsible to handle operations and commands required by the views. Each view creates a Result object and receives notifications about changes from it. + +As an example, removing a bookmark from a view will call into the controller that calls into PlacesTransactions to actually do the removal. The removal will notify a `Places event`_, that is caught by the Result, that will immediately update its internal representation of the bookmarks tree. Then the Result sends a notification to the view that will handle it, updating what the user is seeing. The system works according to the classical `Model-View-Controller`_ pattern. + +Fronted dialogs and panels are written using xhtml and shadow DOM. The bookmark dialogs in particular are wrappers around a common template, `editBookmarkPanel.inc.xhtml`_, it could be extended or overloaded like an object (overlay, similar to Web Component). + +Most of the logic for the edit bookmark overlay lives in the generic script `editBookmark.js`_. + +.. _Controller: https://searchfox.org/mozilla-central/source/browser/components/places/content/controller.js +.. _Places event: https://searchfox.org/mozilla-central/source/dom/chrome-webidl/PlacesEvent.webidl +.. _Model-View-Controller: https://en.wikipedia.org/wiki/Model–view–controller +.. _editBookmarkPanel.inc.xhtml: https://searchfox.org/mozilla-central/source/browser/components/places/content/editBookmarkPanel.inc.xhtml +.. _editBookmark.js: https://searchfox.org/mozilla-central/source/browser/components/places/content/editBookmark.js + +Structure of Frontend +^^^^^^^^^^^^^^^^^^^^^ + +Most part of frontend code is located in : `Browser/Components/Places/Content`_: + + - `BookmarkProperties`_ , BookmarkProperties.xhtml - responsible for editBookmarks & newBookmark Dialog. The panel is initialized based on data given in the js object passed as ``window.arguments[0]``. ``Window.arguments[0]`` is set to the guid of the item, if the dialog is accepted. + - BookmarksHistoyTooltip.xhtml - code responsible for tooltip + - `BookmarksSidebar`_, bookmarksSidebar.xhtml - code responsible for sidebar window. Searches through existing bookmarks tree for desired bookmark. + - `BrowserPlacesViews`_ - controls most views (menu, panels, toolbox). The base view implements everything that's common to the toolbar and menu views. + - `Controller`_ - controller shared by all places views. Connect UI and actual operations. + - `EditBookmark`_, editBookmarkPanel.inc.xhtml - controls edit bookmark panel. Observes changes for bookmarks and connects all UI manipulations with backend. + - `HistorySidebar`_, historySidebar.xhtml - code responsible for history sidebar window. Searches through existing tree for requested History. + - `Places-menupopup`_ - custom element definition for Places menus + - `Places-tree`_ - class ``MozPlacesTree`` - builds a custom element definition for the places tree. This is loaded into all XUL windows. Has to be wrapped in a block to prevent leaking to a window scope. + - Places.css, places.js, places.xhtml - responsible for Library window + - PlacesCommands.inc.xhtml - commands for multiple windows + - PlacesContextMenu.inc.xhtml - definition for context menu + - `TreeView`_ - implementation of the tree view + + .. _Browser/Components/Places/Content: https://searchfox.org/mozilla-central/source/browser/components/places/content + .. _BookmarkProperties: https://searchfox.org/mozilla-central/source/browser/components/places/content/bookmarkProperties.js + .. _BookmarksSidebar: https://searchfox.org/mozilla-central/source/browser/components/places/content/bookmarksSidebar.js + .. _BrowserPlacesViews: https://searchfox.org/mozilla-central/source/browser/components/places/content/browserPlacesViews.js + .. _EditBookmark: https://searchfox.org/mozilla-central/source/browser/components/places/content/editBookmark.js + .. _HistorySidebar: https://searchfox.org/mozilla-central/source/browser/components/places/content/historySidebar.js + .. _Places-menupopup: https://searchfox.org/mozilla-central/source/browser/components/places/content/places-menupopup.js + .. _Places-tree: https://searchfox.org/mozilla-central/source/browser/components/places/content/places-tree.js + .. _TreeView: https://searchfox.org/mozilla-central/source/browser/components/places/content/treeView.js + + +Backend +------- + +Because any bookmark operation done by the user in the frontend is undo-able, Firefox usually doesn’t directly invoke the Bookmarks / History API, it instead goes through a wrapper called PlacesTransactions.jsm. + +The scope of this module is to translate requests for bookmark changes into operation descriptors, and store them in a log. When a bookmark has been modified by the user, PlacesTransactions stores the previous state of it in the log; that state can be restored if the user picks Undo (or CTRL+Z) in the Library window. This prevents data loss in case the user removes bookmarks inadvertently. + +Toolkit Places also provides a way to query bookmarks, through Results. This is one of the oldest parts of the codebase that will likely be rewritten in the future. It uses XPCOM (Cross Platform Component Object Model) a Mozilla technology that allows C++ and Javascript to communicate. It’s a declarative system, where interfaces must be defined and documented in XPIDL files. In practice all the available methods and attributes are documented in nsINavHistoryService.idl. Querying bookmarks returns a nsINavHistoryResult object that has a root node. The root node has children representing bookmarks or folders. It works like a tree, containers must be opened and then one can inspect their children. This is the base used by most of the Firefox frontend bookmark views. + +Structure of Backend +^^^^^^^^^^^^^^^^^^^^ + +Most part of backend code is located in : `Toolkit/Components/Places`_: + + - :doc:`Bookmarks` - Asynchronous API for managing bookmarks + - :doc:`History` - Asynchronous API for managing history + - `PlacesUtils`_ - This module exports functions for Sync to use when applying remote records + - :doc:`PlacesTransactions` - This module serves as the transactions manager for Places + + .. _Toolkit/Components/Places: https://searchfox.org/mozilla-central/source/toolkit/components/places + .. _PlacesUtils: https://searchfox.org/mozilla-central/source/toolkit/components/places/PlacesUtils.jsm + +Storage +------- + +Places uses `SQLite`_ (C-language library with a stable, cross-platform, and backwards compatible file format) as its data storage backend. +All the data is contained in a places.sqlite file, in the roaming Firefox profile folder. The database is accessed using a wrapper of the SQLite library called `mozStorage`_. +For storing our favicons we use favicons.sqlite which is represented as ATTACH-ed to places.sqlite. That makes it easier to use our two separate sqlites as one single database. + +Synchronization +--------------- + +Places works in strict contact with `Firefox Sync`_, to synchronize bookmarks and history across devices, thus you can meet Sync specific code in various parts of the Places codebase. Some of the code may refer to Weave, the old project name for Sync. + +.. _SQLite: https://www.sqlite.org/index.html +.. _mozStorage: https://searchfox.org/mozilla-central/source/storage +.. _Firefox Sync: https://www.mozilla.org/en-US/firefox/sync/ diff --git a/browser/components/places/docs/assets/nontechnical-overview/bookmark-folder-menu.png b/browser/components/places/docs/assets/nontechnical-overview/bookmark-folder-menu.png Binary files differnew file mode 100644 index 0000000000..f8f9dad728 --- /dev/null +++ b/browser/components/places/docs/assets/nontechnical-overview/bookmark-folder-menu.png diff --git a/browser/components/places/docs/assets/nontechnical-overview/bookmark-undo-redo.png b/browser/components/places/docs/assets/nontechnical-overview/bookmark-undo-redo.png Binary files differnew file mode 100644 index 0000000000..7fffaa3f49 --- /dev/null +++ b/browser/components/places/docs/assets/nontechnical-overview/bookmark-undo-redo.png diff --git a/browser/components/places/docs/assets/nontechnical-overview/firefox-bookmarks-main-application.png b/browser/components/places/docs/assets/nontechnical-overview/firefox-bookmarks-main-application.png Binary files differnew file mode 100644 index 0000000000..4a2028f4f3 --- /dev/null +++ b/browser/components/places/docs/assets/nontechnical-overview/firefox-bookmarks-main-application.png diff --git a/browser/components/places/docs/assets/nontechnical-overview/firefox-bookmarks-menu.png b/browser/components/places/docs/assets/nontechnical-overview/firefox-bookmarks-menu.png Binary files differnew file mode 100644 index 0000000000..63b4b8163b --- /dev/null +++ b/browser/components/places/docs/assets/nontechnical-overview/firefox-bookmarks-menu.png diff --git a/browser/components/places/docs/assets/nontechnical-overview/firefox-bookmarks-toolbar.png b/browser/components/places/docs/assets/nontechnical-overview/firefox-bookmarks-toolbar.png Binary files differnew file mode 100644 index 0000000000..0cdbe97f08 --- /dev/null +++ b/browser/components/places/docs/assets/nontechnical-overview/firefox-bookmarks-toolbar.png diff --git a/browser/components/places/docs/index.rst b/browser/components/places/docs/index.rst new file mode 100644 index 0000000000..dd6a64c05a --- /dev/null +++ b/browser/components/places/docs/index.rst @@ -0,0 +1,35 @@ +Places +====== + +This document describes the implementation of the Firefox Places component. + +It is a robust system to manage History and Bookmarks through a database on the backend side and a model-view-controller system that connects frontend UI user manipulation. + +History and Bookmarks +--------------------- + +In Firefox 2, History and Bookmarks used to be kept into separate databases in the Resource Description Framework format (`RDF format`_). + +However, Firefox 3 implemented the Places system. It has been done due to multiple reasons, such as: + + * **Performance**: certain search or maintenance operations were very slow + * **Reliability**: the filesystem facing side of RDF was not so robust, often causing corruption or unexpected states + * **Flexibility**: being able to cross data allows for interesting features, like the Awesome Bar + * **Maintainability**: the future of RDF was unclear, while SQLite is actively maintained and used by a large number of applications + + .. _RDF format: https://en.wikipedia.org/wiki/Resource_Description_Framework + +Where to Start +-------------- + +For the high-level, non-technical summary of how History and Bookmarks works, read :doc:`nontechnical-overview`. +For more specific, technical details of implementation, read :doc:`architecture-overview`. + +Table of Contents +----------------- + +.. toctree:: + :maxdepth: 2 + + nontechnical-overview + architecture-overview diff --git a/browser/components/places/docs/nontechnical-overview.rst b/browser/components/places/docs/nontechnical-overview.rst new file mode 100644 index 0000000000..e4da4b895e --- /dev/null +++ b/browser/components/places/docs/nontechnical-overview.rst @@ -0,0 +1,163 @@ +Nontechnical Overview +===================== + +This document provides a high level, nontechnical overview of Firefox’s Places component (Bookmarks and History). + +More information regarding Bookmarks - `Bookmarks in Firefox`_ + +.. _Bookmarks in Firefox: https://support.mozilla.org/en-US/kb/bookmarks-firefox + +There are multiple ways to access and manipulate Bookmarks, such as: + +.. contents:: + :depth: 2 + + +Firefox menu bar +---------------- + +To access bookmarks click on Bookmarks link in Firefox menu bar on the top of your screen. +If the Firefox Menu bar is missing, it is usually because Firefox is in full screen mode or it is not the selected application. + +In this case you can: + * Turn off full screen mode + * Select the Firefox application + +.. figure:: assets/nontechnical-overview/firefox-bookmarks-menu.png + :alt: Image of the Bookmarks Menu in Firefox menu bar + :scale: 50% + :align: center + + Firefox menu bar - Bookmarks Menu + +Main application button +----------------------- + +.. figure:: assets/nontechnical-overview/firefox-bookmarks-main-application.png + :alt: Image of the main Bookmarks application button + :scale: 45% + :align: center + + Firefox - Bookmarks Main Application + +Bookmarks Toolbar +----------------- + +.. figure:: assets/nontechnical-overview/firefox-bookmarks-toolbar.png + :alt: Image of the Bookmarks Toolbar + :scale: 50% + :align: center + + Firefox - Bookmarks Toolbar + +On the top of your Firefox screen just under the search bar - Bookmarks are on the left side. + +Firefox's toolbar provides easy access to common features: + * Click the menu button , click `More Tools` and choose `Customize Toolbar`. + + - **To turn on the Title bar:** Put a check mark next to `Title Bar` in the lower left. + - **To turn on the Bookmarks toolbar:** Click the Toolbars dropdown menu at the bottom of the screen and select Bookmarks Toolbar. + + * Click the `Done` button. + +Firefox sidebar +--------------- + +Firefox comes with a convenient Sidebar button which lets you access your bookmarks, history and synced tabs in one click. For using it, you have to: + +1. `Add the sidebar button to your controls`_. + +2. Toggle sidebar button on and off for preferable options (for ex., add bookmarks). + +.. _Add the sidebar button to your controls: https://support.mozilla.org/en-US/kb/use-firefox-sidebar-access-bookmarks-history-synced + +The Library window +------------------ +1. Click the `hamburger Menu` icon in the upper-right corner of your screen. +2. In the middle of the drop-down menu select `Library`. +3. In the `Library` menu select `Bookmarks`. +4. Press `Show All Bookmark` button. + +Keyboard shortcuts +------------------ + + * Show / Manage Bookmarks (Library Window) - :kbd:`Shift` + :kbd:`Ctrl` / :kbd:`Cmd` + :kbd:`O` + * Add / Edit Bookmark - :kbd:`Ctrl` / :kbd:`Cmd` + :kbd:`D` + * Bookmark all tabs into 1 bookmark folder - :kbd:`Shift` + :kbd:`Ctrl` / :kbd:`Cmd` + :kbd:`D` + * Delete bookmark / Bookmarks / Bookmarks folder - :kbd:`Delete` + * Show / Hide the Bookmarks toolbar - :kbd:`Shift` + :kbd:`Ctrl` / :kbd:`Cmd` + :kbd:`B` + * Focus Next Bookmark/Folder whose name (or sorted property) starts with a given character or character sequence - Type the character or quickly type the character sequence - in Bookmarks Library, Bookmarks Toolbar, Bookmarks Menu, Bookmarks Sidebar + +Firefox Context Menu +-------------------- + +Single // Multiple bookmarks on selection will allow you to perform different manipulations, such as: + + * Open (Open / Open in New Tab / Open in New Window / Open in New Private Window) + * Delete + * Edit (Cut / Copy / Paste) + * Add (Bookmark / Folder / Separator) + +.. figure:: assets/nontechnical-overview/bookmark-folder-menu.png + :alt: Image of the Bookmark Menu + :scale: 50% + :align: center + + Firefox - Bookmark Menu + +Undo / Redo +----------- + +Undo / Redo options available In Library Window and Sidebar Panel. +You can reverse your commands (creating bookmark, deleting bookmark, copy/paste etc.) with: + + * Keyboard combinations: + + - Undo - :kbd:`Ctrl` / :kbd:`Cmd` + :kbd:`Z` + - Redo - :kbd:`Shift` + :kbd:`Ctrl` / :kbd:`Cmd` + :kbd:`Z` + + * Choosing option in Menu - Edit - Undo / Redo + +.. figure:: assets/nontechnical-overview/bookmark-undo-redo.png + :alt: Image of the Undo/Redo options for Bookmark + :scale: 50% + :align: center + + Firefox - Undo / Redo for bookmark + +Import Bookmarks +---------------- + +There are various options to import bookmarks to Firefox. Some of them are: + + * `from Internet Explorer or Microsoft Edge`_ + * `from Google Chrome`_ + * `from an HTML file`_ + + .. _from Internet Explorer or Microsoft Edge: https://support.mozilla.org/en-US/kb/import-bookmarks-internet-explorer-or-microsoft-edge + .. _from Google Chrome: https://support.mozilla.org/en-US/kb/import-bookmarks-google-chrome + .. _from an HTML file: https://support.mozilla.org/en-US/kb/import-bookmarks-html-file + +Restore Bookmarks +----------------- + +Firefox automatically creates backups of your bookmarks and saves the last 15 backups for safekeeping. + +**To restore your bookmarks:** + +#. Click on *hamburger menu* button to open the Menu panel. +#. Go to *Bookmarks* - *Manage Bookmarks*. +#. Select the backup from which you want to restore: + + #. The dated entries are automatic bookmark backups. + #. From a manual backup ( *Choose file…* ). +#. After selecting the option and confirming your choice your bookmarks would be restored. + + +**For manually add backup:** + +#. Click on *hamburger menu* button to open the Menu panel. +#. Go to *Bookmarks* - *Manage Bookmarks*. +#. In the *Library window*, click the button and then select *Backup…*. +#. In the Bookmarks backup filename window that opens, choose a location to save the file, which is named ``bookmarks-date.json`` by default. The desktop is usually a good spot, but any place that is easy to remember will work. +#. Save the bookmarks json file. The Bookmarks backup filename window will close and then you can close the *Library* window. diff --git a/browser/components/places/docs/notifyObservers.rst b/browser/components/places/docs/notifyObservers.rst new file mode 100644 index 0000000000..5eb95f48e7 --- /dev/null +++ b/browser/components/places/docs/notifyObservers.rst @@ -0,0 +1,35 @@ +Observers +========= + +Historically, each successful operation is notified through the *nsINavBookmarksObserver* interface. To listen to such notifications you must register using *nsINavBookmarksService* addObserver and removeObserver methods. Note that bookmark addition or order changes won't notify bookmark-moved for items that have their indexes changed. +Similarly, lastModified changes not done explicitly (like changing another property) won't fire an onItemChanged notification for the lastModified property. + +However, right now we are in the process of implementing a Places Observers system to change the *nsINavBookmarksObserver* interface. + +Generally - the Observer pattern follows a subscription model. A subscriber (commonly referred to as the observer) subscribes to an event or an action handled by a publisher (commonly referred to as the subject) is notified when the event or action occurs. + +Each successful operation is noticed by observer for these events and passed to a subscriber. + +`PlacesObservers.webidl`_ a Global Singleton which provides utilities to observe or notify all events. +`PlacesEvent.webidl`_ states all types of possible events and describes their features. In our case, events are: + + - ``“page-visited”`` - ``data: PlacesVisit`` Fired whenever a page is visited + - ``“bookmark-added”`` - ``data: PlacesBookmarkAddition`` Fired whenever a bookmark (or a bookmark folder/separator) is created. + - ``“bookmark-removed”`` - ``data: PlacesBookmarkRemoved`` Fired whenever a bookmark (or a bookmark folder/separator) is removed. + - ``“bookmark-moved”`` - ``data: PlacesBookmarkMoved`` Fired whenever a bookmark (or a bookmark folder/separator) is moved. + - ``“bookmark-guid-changed”`` - ``data: PlacesBookmarkGuid`` Fired whenever a bookmark guid changes. + - ``“bookmark-keyword-changed”`` - ``data: PlacesBookmarkKeyword`` Fired whenever a bookmark keyword changes. + + - ``“bookmark-tags-changed”`` - ``data: PlacesBookmarkTags`` Fired whenever tags of bookmark changes. + - ``“bookmark-time-changed”`` - ``data: PlacesBookmarkTime`` Fired whenever dateAdded or lastModified of a bookmark is explicitly changed through the Bookmarks API. This notification doesn't fire when a bookmark is created, or when a property of a bookmark (e.g. title) is changed, even if lastModified will be updated as a consequence of that change. + - ``“bookmark-title-changed”`` - ``data: PlacesBookmarkTitle`` Fired whenever a bookmark title changes. + - ``“bookmark-url-changed”`` - ``data: PlacesBookmarkUrl`` Fired whenever a bookmark url changes. + - ``“favicon-changed”`` - ``data: PlacesFavicon`` Fired whenever a favicon changes. + - ``“page-title-changed”`` - ``data: PlacesVisitTitle`` Fired whenever a page title changes. + - ``“history-cleared”`` - ``data: PlacesHistoryCleared`` Fired whenever history is cleared. + - ``“page-rank-changed”`` - ``data: PlacesRanking`` Fired whenever pages ranking is changed. + - ``“page-removed”`` - ``data: PlacesVisitRemoved`` Fired whenever a page or its visits are removed. This may be invoked when a page is removed from the store because it has no more visits, nor bookmarks. It may also be invoked when all or some of the page visits are removed, but the page itself is not removed from the store, because it may be bookmarked. + - ``“purge-caches”`` - ``data: PlacesPurgeCaches`` Fired whenever changes happened that could not be observed through other notifications, for example a database fixup. When received, observers, especially data views, should drop any caches and reload from scratch. + + .. _PlacesObservers.webidl: https://searchfox.org/mozilla-central/source/dom/chrome-webidl/PlacesObservers.webidl + .. _PlacesEvent.webidl: https://searchfox.org/mozilla-central/source/dom/chrome-webidl/PlacesEvent.webidl |
