Desktop

The desktop is the root widget of every Scout application. The default desktop consists of 3 areas:

Navigation
Displays an Outline with Pages
Header
Shows the tabs of views and a toolbar with menus.
A view is a display mode of a Form.
Bench
Contains the content of the active view or active page.

Desktop Bench Layout

The layout of the desktop bench can be configured using the IDesktop.setBenchLayoutData method. This property is observed and might be changed during the application lifecycle. The desktop consists out of 9 view stacks (see Figure 1). Each form can be assigned to a single view stack using the property DisplayViewId (IForm.getConfiguredDisplayViewId). If multiple forms are assigned to the same view stack the views will be displayed as tabs where the top form is visible and the corresponding tab selected.

Tabs are only visible if the form does have a title, subtitle or an image.

Figure 1. Desktop Bench overview

The east, center and west columns are separated with splitters which can be moved according to the layout data properties. Each column is split into a north, center and south part. Within a column the north, center and south parts can not differ in their width.

The modifications (splitter movements) are cached when a cache key (BenchLayoutData.withCacheKey) is set. In case the cache key is null the layout starts always with the initial values.

An example of a bench layout data configuration with a fixed north (N) view stack and a south (S) view stack with a minimal size. See org.eclipse.scout.rt.client.ui.desktop.bench.layout.FlexboxLayoutData API for the documentation of the properties.

desktop.setBenchLayoutData( (1)
    new BenchLayoutData()
        .withCacheKey("a-cache-key") (2)
        .withCenter( (3)
            new BenchColumnData()
                .withNorth(new FlexboxLayoutData().withGrow(0).withShrink(0).withInitial(280).withRelative(false)) (4)
                .withCenter(new FlexboxLayoutData()) (5)
                .withSouth(new FlexboxLayoutData().withShrink(0).withInitial(-1)))); (6)

1	set the `BenchLayoutData` to the desktop.
2	set a cache key to store the layout modifications (dragging splitters) to the session store. Aware the settings are stored to the browsers session store they are not transferred over different browsers nor systems.
3	configure the center column (N, C, S).
4	The north part is fixed in size so the splitter between north (N) and center © view stack is disabled. The size is fixed to 280 pixel.
5	Use default for the center © view stack.
6	The south part is using the UI height as initial size and is growable but not shrinkable.

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.