tree: f9daeb9215287d8175515c92a2d979d98b196c8a [path history] [tgz]
  1. .eslintrc.js
  2. BUILD.gn
  3. OWNERS
  4. README.md
  5. actions.html
  6. actions.js
  7. api_listener.html
  8. api_listener.js
  9. app.html
  10. app.js
  11. bookmarks.html
  12. command_manager.html
  13. command_manager.js
  14. constants.html
  15. constants.js
  16. debouncer.html
  17. debouncer.js
  18. dialog_focus_manager.html
  19. dialog_focus_manager.js
  20. dnd_chip.html
  21. dnd_chip.js
  22. dnd_manager.html
  23. dnd_manager.js
  24. edit_dialog.html
  25. edit_dialog.js
  26. folder_node.html
  27. folder_node.js
  28. images/
  29. item.html
  30. item.js
  31. list.html
  32. list.js
  33. mouse_focus_behavior.html
  34. mouse_focus_behavior.js
  35. reducers.html
  36. reducers.js
  37. router.html
  38. router.js
  39. shared_style.html
  40. shared_vars.html
  41. store.html
  42. store.js
  43. store_client.html
  44. store_client.js
  45. toast_manager.html
  46. toast_manager.js
  47. toolbar.html
  48. toolbar.js
  49. types.js
  50. util.html
  51. util.js
chrome/browser/resources/md_bookmarks/README.md

Material Design Bookmark Manager

The bookmark manager (BMM) is a WebUI surface with a large amount of functionality for managing bookmarks across a relatively simple UI. This document serves as an overview of the page, both in terms of the page features, as well as the code design built up to support it.

Major features

The following are some of the main features of the BMM which impact the design of the code:

  • Real-time updates: The display updates in real-time in response to any change to the bookmark model, whether from the page itself or from any other part of the browser UI.

  • Item selection: It is possible to select items using either the mouse or keyboard, using ctrl/shift in much the same way as with a powerful file browser like Windows Explorer.

  • Contextual commands: All viewing/editing commands adapt to the current selection. Most commands have corresponding keyboard shortcuts.

  • Drag and drop: It is possible to drag bookmarks to move them between folders. This works within the BMM, as well as between native UI and the BMM, and between two different BMM instances from different Chrome profiles.

  • Policy support: Several policies are respected:

Data-flow model

Full design document

The BMM uses a one-way data flow model that is somewhat different to other Polymer WebUI pages. This model is inspired by Redux, with a simple layer which binds it to Polymer UI components. Designing our data flow in this way has a few primary benefits:

  • We have a single source of truth for the state of the page
  • We have a well-defined interface for making changes to the state of the page
  • UI components are able to directly read whatever state they need, removing the need for a chain of tedious, highly-coupled Polymer bindings to manage state.

The following is a brief overview of how the data-flow model works. Note that this model is only used for front-end Polymer UI, and is entirely separate to the backend BookmarkModel in C++.

Store

store.js provides a singleton class (bookmarks.Store) which gives access to a read-only state tree for the entire page (store.data).

Any Polymer UI element which wants to be able to data-bind values from the global state should add the behavior bookmarks.StoreClient (in store_client.js). This behavior allows elements to watch particular values in the store, and be automatically updated when they change.

Actions

Actions are the only way to modify the state tree. An Action is a plain Javascript object which describes a modification that should be made to the state tree. All Action objects are created by functions in actions.js.

To actually modify the state, call Store.dispatch(action) (or StoreClient.dispatch(action)). This tells the store to process the action and notify UI elements about what has changed.

Changes to the persistent bookmarks backend are made by calling into the bookmarks extension API. These then call back to the BMM through chrome.bookmarks event listeners, which dispatch actions to change the Javascript bookmark model, updating the page.

Note: There's also limited support for Actions which are processed asynchronously. See dispatchAsync for details, but this probably needs more work before they are generally useful.

Reducers

Reducers describe how an action affects the page state. These are pure functions located in reducers.js which take a state and an action, and return a new state.

Importantly, reducers must never modify any part of the input state: instead, they return new objects for any part of the state tree that has changed. By doing this, it is possible for StoreClient to quickly check for what has changed using ==, and only notify Polymer about things that have actually changed. Plus, these functions are easier to test and debug!

Context menus and keyboard shortcuts

Full design document

Context menus and keyboard shortcuts are controlled by the CommandManager, located in command_manager.js. This includes all logic for commands which open/edit bookmarks, including:

  • Determining which commands should appear in the context menu (and whether they are enabled or disabled).
  • Triggering commands on keyboard shortcuts
  • Showing appropriate UI (such as confirmation dialogs, toasts) when the command is executed.

An enum of all possible commands is defined in constants.js.