Bookmarks

A bookmark describes a specific place in the desktop navigation. It consists of the following information:

  • The selected outline

  • The selected page

  • The path from the outline’s root to the selected page

For each page, the bookmark not only holds information about its identity but also about its state, e.g. search data, table filters, table settings etc.

This data can be persisted and used later to jump back to the same location in a single action.

The information presented in this chapter applies to Scout JS only. Scout Classic applications may use the legacy BookmarkUtility for a similar functionality.

Creating a Bookmark

All bookmark actions are provided by the class BookmarkSupport. A singleton instance is accessible via the static get() method. To create a new bookmark, simply call the createBookmark() method.

let bookmark = await BookmarkSupport.get(session).createBookmark();

By default, this creates a bookmark for the currently selected page. A different page can be specified via the optional argument CreateBookmarkParam. The same argument allows configuring the type and content of the resulting bookmark.

The return value is a data object containing mainly the bookmark definition itself (= the page state and the path). Depending on the implementation, additional metadata may be included, e.g. a human-readable title.

For a page to be bookmarkable, it needs to have a unique identifier, so it can be recognized later. This identifier is usually assigned by specifying the uuid property in the page model. Because all child pages of a table page are of the same type and therefore share the same uuid, some additional information is needed to unambiguously identify them:

  • If the table has columns marked as primary key, the corresponding row values are converted to a BookmarkTableRowIdentifierDo and stored in the bookmark.

  • If present, the page param of the child page is included in the bookmark. This data object contains the necessary input to re-create a specific page instance (e.g. the key of the corresponding entity). It needs to have the same name as the page with the suffix PageParamDo (e.g. PersonPage → PersonPageParamDo). For pages without an explicit page param, a PageIdDummyPageParamDo with the page’s uuid is stored in the bookmark.

Activating a Bookmark

Given a BookmarkDo, you can instruct the BookmarkSupport to navigate to the corresponding location.

await BookmarkSupport.get(session).activateBookmark(bookmark);

This resolves the elements of the page path step-by-step. Each page is loaded and restored to the previous state, before a drill-down with the next element of the path is performed. In case one element of the page path cannot be found anymore (e.g. because the corresponding data has been deleted in the meantime), the process stops and a warning is shown to the user. Otherwise, the last page in the page is selected.

Instead of jumping to the original location, it is also possible to simply create a new instance of a bookmarked page and add it dynamically to the outline. In that case, the rest of the page path in the bookmark is irrelevant. If the page requires some input, it has to be stored in an explicit page param, so it can be re-created without its parent. With the stored page param in hand, you can compute the corresponding object type of the page by using the PageResolver. Then, use scout.create() to create the page instance and add it to the outline like any other page.

Managing Bookmarks

The BookmarkSupport offers basic operations to create and activate bookmarks, but does not specify how they should be stored. Applications can and should implement their own UI if they want to enable their users to use this function.

Two basic form are provided as a starting point, although their use is entirely optional:

  • BookmarkForm: Allows to set or edit a bookmark’s name.

  • ManageBookmarksForm: Shows a list of bookmark entries and allows to edit, reorder and delete them.

The BookmarkStore base class specifies methods to load and store bookmarks. Scout provides a default implementation called LocalBookmarkStore that saves bookmarks as JSON into the browser’s local storage. To use a different storage method (e.g. storing to a database via REST service), you can register your own implementation via the object factory.