App bars – menus, navigation and toolbars¶
An app bar is a list of buttons. The same definition serves as the navigation of the application – the top and the left app bar – and as a toolbar above a grid, a list, a form or on a dashboard. This chapter describes how you build an app bar and how roles decide which app bars a user sees.
It is intended for administrators who design the navigation and the screens of an application.
1. App bars at a glance¶
| Where an app bar is used | Set in | The actions of the buttons run against |
|---|---|---|
| Top app bar – the bar along the top of the window | Role, "Top App Bar" | no record |
| Left app bar – the navigation on the left | Role, "Left App Bar" | no record |
| Toolbar of a grid or list | Grid or list, "Toolbar" | the selected rows (see Grids) |
| Buttons in every row of a grid | Toolbar column of a grid | the record of the row |
| Toolbar block in a form | Form (see Forms) | the record of the form |
| "App-Bar Block" on a dashboard | Dashboard (see App-Bar Block) | no record |
Every item of an app bar is a button. An item with child items opens them as a dropdown menu.
App bars are managed in the Admin Studio under Design → App Bars, or under an entity in the area Entities. The permissions are "Open App Bar Manager", "Add App Bar", "Edit App Bar" and "Delete App Bar".
2. The app bar editor¶
The editor is split in two:
- Left: a search field ("Search Items..."), the entry "App Bar Properties" and the tree of the items.
- Right: the properties of what is selected on the left – name, description and tags of the app bar, or the settings of an item.
| Task | How |
|---|---|
| Add an item | "Add Item" in the toolbar of the editor, or "+Above", "+Inside", "+Below" in the menu of an item. "+Inside" adds a child item. |
| Reorder items | Drag an item in the tree. A child item can be dragged to the top level and back. |
| Copy an item | "Clone" in the menu of the item. The copy is named "… (Copy)". |
| Remove an item | "Remove Item" in the toolbar or "Delete" in the menu of the item |
| Find an item | "Search Items..." filters all levels of the tree |
A new item is selected right away and scrolled into view.
3. Settings of an item¶
| Setting | Category | Meaning | Default |
|---|---|---|---|
| "Name" | – | How the item is called in the editor. Users never see it. | "New Item" |
| "Label" | – | The text of the button, computed by an expression | none |
| "Icon" | – | The icon of the button, an image expression (see Images) | none |
| "Tooltip" | – | Text shown when the pointer rests on the item. Empty shows no tooltip. | none |
| "Action" | – | What happens on a click. An item with child items opens them instead and needs no action. | none |
| "Item Style" | Appearance | Default, Primary, Secondary, Outlined, Primary Outline, Subtle, Ghost, Link, Danger. Default lets the place decide: borderless in the top and left app bar, a bordered button in a toolbar. | Default |
| "Hide Dropdown Chevron" | Appearance | Leaves off the arrow of an item with child items | off |
| "CSS Classes" | Appearance | CSS classes computed by an expression | none |
| "Visible" | Behavior | Condition under which the item is shown. A hidden item is left out completely. | always visible |
| "Disabled" | Behavior | Condition under which the item is greyed out and cannot be clicked | never disabled |
An item needs a "Label" or an "Icon" – otherwise the button is empty. It also needs an "Action" or child items – otherwise a click does nothing.
"Hide Dropdown Chevron" on an item with an action makes its child items unreachable: the click runs the action, and there is no arrow left to open the menu. Use it only on items without an action.
The expressions of an item are evaluated when the app bar is drawn. In the top and left app bar and on a dashboard there is no record, so the expressions cannot read fields. In a toolbar of a form or a toolbar column they are evaluated against the record.
4. Which app bars a user sees¶
The top and the left app bar are set per role, on the tab "General" of the role editor (Admin Studio → Access → Roles): "Top App Bar" and "Left App Bar".
The app bars of all roles of a user are shown together. nexxcite takes the roles in the order of their "Priority" (the lowest value first) and puts the items of their app bars one after the other.
Example: "Clerk" (priority 20) has the left app bar "Clerk menu" with "My tasks" and "Customers". "Team lead" (priority 10) has the left app bar "Team menu" with "Team dashboard". A user with both roles sees "Team dashboard", "My tasks", "Customers".
- Roles without an app bar contribute nothing.
- If two roles of a user link the same app bar, its items appear twice. Give such roles one shared role that carries the app bar (see "Included Roles" in Roles and permissions), or use different app bars.
- To show an item only to some users, use its "Visible" condition – for example with the roles of the current user.
Changes to app bars and roles reach a user who is already working when they reload the page or sign in again.
5. Behaviour at runtime¶
Top app bar¶
- The items sit in one line next to the logo. Only as many items as fit are shown; the rest is cut off. Every item – also the ones cut off – can be found with the spotlight search (Ctrl+K). On narrow screens the items are reachable through the spotlight search only.
- An item with child items opens them as a menu below it.
- The logo can be replaced per role with "Logo (Light Mode)" and "Logo (Dark Mode)".
Left app bar¶
- The bar can be expanded (icon and label) and collapsed (icons only) with the arrow button at its bottom. Collapsed, the label is shown as a tooltip.
- An item with child items opens them below itself.
Links and new tabs¶
Every item of the top and left app bar that runs an action is also a link with its own address,
/menu/<item id>. Users can therefore open it in a new tab with a middle click or Ctrl+click,
or bookmark it. A link only works for users who can see the item: opening it checks the roles and the
"Visible" condition of the user who opens it.
While an action runs¶
A button of the top app bar is shown as busy while its action runs.
6. Examples¶
A navigation with a submenu. Left app bar "Service":
| Item | Label | Icon | Action | Child items |
|---|---|---|---|---|
| Dashboard | "Overview" | dashboard | "Open service dashboard" | – |
| Tickets | "Tickets" | confirmation_number | – | "Open tickets", "My tickets", "Closed tickets" |
| New | "New ticket" | add | "Create ticket" | – |
"Tickets" has no action, so "Hide Dropdown Chevron" can be switched on: a click opens the submenu anyway.
A toolbar for a grid. App bar "Ticket list toolbar" with "Assign to me" (action of the entity "Ticket", runs for all selected rows) and "New ticket" (an action without a record). Select it as "Toolbar" of the grid.
7. Limitations¶
- An item is always a button. Separators, spacers or search boxes inside an app bar do not exist.
- The top app bar does not wrap; items that do not fit are only reachable through the spotlight search.
- The same app bar linked from two roles of a user is shown twice.
- The left app bar cannot be switched off per role. A role without a left app bar contributes no items, but the bar itself remains.