gobj-ui: The shell API

The shell API¶

C_YUI_SHELL draws the frame of the application from one JSON file: the toolbar, the menus and the zones where the views go. These functions drive it from outside.

Source code: src/c_yui_shell.js

The design is in The declarative shell and Routing. This page is the reference of the functions.

`yui_shell_navigate(shell_gobj, route, opts)`¶

Goes to a route.

Option	Effect
(none)	Push. It writes an entry in the history, so the Back button returns. It is the default, and it is the safe one: a human chose to go there.
`opts.replace: true`	Replace. It changes the URL and writes no entry. Use it when the code decided the move: a redirect, a normalization, the default child of a parent menu, or a restore after a reload of the page.
`opts.push: true`	The default, written out. It stays valid, so a call site documents its intent.

`yui_shell_set_sub_routes(shell_gobj, base_route, nodes)`¶

Declares the deep routes that a view owns, for the site map. nodes is an ordered array of {route, label, icon?, children?} with full routes.

Give an empty value to clear them, and do it when the view stops. A map that holds the children of a view that went away is a map that lies.

`yui_shell_register_event_handler(shell_gobj, event, gclass)`¶

Declares that a gclass handles an action of the toolbar or of the account menu, so the site map shows where the action lives. Call it one time, next to the subscription. More than one gclass can handle the same event.

`yui_shell_unpark_route(route)`¶

Takes the URL off an action route that the application parked it on. Call it from the path that closes the overlay.

The function has a guard, and the guard is the point of it. When the close comes from the drain of the overlays, because the user went to another route while the overlay was open, the URL moved already. A history.back() there lands on the entries of the action, fires the action again, opens the overlay again, and takes the navigation that the user asked for. The function goes back only while the URL still sits on the route.

Drawers¶

The three functions open and close the off-canvas navigation from outside, such as from a button in the toolbar. menu_id is optional.

`yui_shell_open_drawer(shell_gobj, menu_id)`¶

Opens the drawer.

`yui_shell_close_drawer(shell_gobj, menu_id)`¶

Closes the drawer.

`yui_shell_toggle_drawer(shell_gobj, menu_id)`¶

Opens the drawer when it is closed, and closes it when it is open.

The escape chain¶

An overlay that the shell does not own declares itself here, so the Escape key reaches the top one first. The drawer is built in.

let close_fn = () => my_modal.close();
yui_shell_push_escape(shell, "modal", close_fn);
// … when the modal closes by any path:
yui_shell_pop_escape(shell, close_fn);

`yui_shell_push_escape(shell_gobj, layer, handler)`¶

Puts a handler on the chain. layer is a free tag, such as "modal", "popup" or "overlay". Today it is information only: the order of the stack decides the priority, and that order matches the layers of the z-index that most applications use.

`yui_shell_pop_escape(shell_gobj, handler)`¶

Takes a handler off the chain. Call it on every path that closes the overlay, and not only on the Escape key.

Overlays and the Back button¶

An overlay is transient. It declares itself here so the Back button closes it before it moves the application.

let overlay = yui_shell_register_overlay(shell, close_fn);
// … when the overlay closes by any path that is not Back:
yui_shell_overlay_dismissed(shell, overlay);

`yui_shell_register_overlay(shell_gobj, close_fn, opts)`¶

Declares an overlay. close_fn is what the Back button calls to take the overlay down.

With opts.keep_on_navigate set to true the overlay is a panel of navigation, and it stays when the route changes. The default is off, because an overlay that outlives the view below it is the exception, and the exception asks for itself.

Returns the overlay, or null when the integration with the history is off. A caller that receives null skips the call below.

`yui_shell_overlay_dismissed(shell_gobj, overlay)`¶

Tells the shell that the overlay went away by a path that is not the Back button.

Avatars¶

`yui_shell_set_avatar_provider(shell_gobj, provider)`¶

Gives the function that the shell asks for the image of a user.

`yui_shell_refresh_avatars(shell_gobj)`¶

Asks the provider again, and draws the avatars again.

Language¶

`yui_shell_set_translator(shell_gobj, t)`¶

Gives the translation function of the application to the shell.

`yui_shell_set_connection_state(shell_gobj, connected)`¶

Draws the state of the connection in the toolbar.

Changes the icon of an item of the toolbar.

Writes a badge on an item of the toolbar, such as a count of messages.

Closes the dropdown of the account.

The site map¶

`yui_shell_show_route_map(shell, opts)`¶

Opens the site map, which shows the whole surface of the navigation as a tree: the toolbar, each menu, the sub-routes that each view declared, and the routes that only the table of routes holds. It marks the position of the reader.

The shell API¶

Navigation¶

Drawers¶

The escape chain¶

Overlays and the Back button¶

Avatars¶

Language¶

The toolbar¶

The site map¶