App Sidebar - edmozley/freeitsm GitHub Wiki

๐Ÿงญ The sidebar

An optional rail of module icons down the left of every screen, for anybody who would rather see their modules than open the waffle menu each time (discussion #124). The waffle menu stays where it is unless you choose to hide its button.

Turning it on

Preferences โ†’ Display โ†’ Sidebar (or the โš™ sliders button at the bottom of the sidebar itself).

  1. Switch on Show the sidebar.
  2. Tick the modules you want on it. Only modules you can open are offered.

It appears from the next page you open. It is off until you switch it on, and it is yours alone - nobody else's screen changes.

What is on it

  • Your modules, in your module order - the same order as your waffle menu, set just above on the same tab under Module order. Reorder there and the sidebar follows.
  • The module you are in is highlighted, with a bar at its left edge.
  • Scroll arrows (4.0.0) - when your modules do not all fit, an up and a down arrow appear on rows of their own above and below the list. Click one to glide to the top or the bottom. Each only shows while there is more that way - no empty gap - and a list that fits has neither. The module you are in is scrolled into view when you open a page.
  • Module names (3.13.0) - Preferences -> Display -> Sidebar -> Module names:
    • Icons only (the default, as it has always been) - hover an icon for its name.
    • Open with names when you point at the sidebar - the rail widens to show every name when you point at it, or tab into it with the keyboard. It opens over the page, so nothing you are working on moves. A short pause before it opens stops it flashing when the pointer only passes over the edge.
    • Always open with names - the rail stays wide and the page moves over to make room.
    • With names on, a ๐Ÿ“Œ Pin / Unpin button at the bottom switches between the last two on the spot, and remembers it.
  • ๐Ÿ•˜ Recent at the bottom opens the waffle's Recent trail - everything you have opened lately, grouped by module, with its own search. It opens beside the sidebar at the bottom left, next to the button.
  • โš™ the sliders button takes you straight to the sidebar's settings.

Hiding the waffle button (4.0.0)

Once the sidebar is on, Preferences โ†’ Display โ†’ Sidebar โ†’ Waffle button can be set to Hide, for anybody who finds two module menus one too many. The default is Show, so nothing changes unless you choose it.

Only the button goes. ๐Ÿ•˜ Recent on the sidebar still opens the same panel, search included, so nothing is lost. On a phone the waffle button always shows, whatever this says - a phone has no sidebar, so the waffle is its only menu.

A module you lose access to drops off the sidebar on its own, and one you gain appears in the tick list.

On a phone

The sidebar is not shown on a phone; the phone keeps its compact menu (the waffle button too, even if you hid it on the desktop), and its screens do not move.

For developers

  • includes/app_sidebar.php - appSidebarPrefs() (one query, per request), appSidebarModules() (the modules from analystVisibleModules(), narrowed to the ticked ones) and renderAppSidebar().
  • It is drawn by renderWaffleMenuPanel() in includes/waffle-menu.php, which every analyst header already calls - so a new module or a new page needs nothing to have it.
  • assets/css/app-sidebar.css, linked by the sidebar itself only when it is on. Desktop only (min-width: 769px); body:has(.app-sidebar) moves the page right 54px. TRAP: anything pinned to the window's left edge with position: fixed; left: 0 lies under the rail - Files' desktop, taskbar and start menu are moved over by hand in that file. A new full-window layer needs the same.
  • Preferences: app_sidebar ('1' = on), app_sidebar_modules (a JSON list of module keys; absent = every module) app_sidebar_names (icons or absent / hover / pinned) and app_sidebar_waffle (hide; absent or empty = show), all in user_preferences - no schema change.
  • Names: every link carries its name in .app-sidebar-name; the rail is overflow: hidden, so at 54px only the icons show and widening it uncovers the names without moving the icons. The nav's class is app-sidebar--icons|hover|pinned; body:has(.app-sidebar--pinned) pads the page 220px (and moves Files' layers), while --hover widens on :hover / :focus-within with no padding, so it overlays. The pin button flips the class and saves app_sidebar_names - no reload.
  • Scroll arrows: .app-sidebar-scroll wraps #appSidebarList and the two .app-sidebar-arrow rows. A row is open only with its arrow (.show, height 0 -> 24px). TRAP: a click opens the FAR row at once and sets list.heading until the end is reached - otherwise the far row opens mid-glide, takes 24px off the list after the browser fixed the target, and the scroll stops 24px short. Transitions only after .ready (two frames after load), so rows do not slide open on every page. Smooth scrollTo, auto under prefers-reduced-motion.
  • Recent from the rail: appSidebarRecent() adds waffle-panel--rail to #wafflePanel (fixed, bottom left beside the rail) and closeWaffleMenu() takes it off. TRAP: the rail (z-index 1500) sits above the panel (1000), so a --hover rail is held at 54px while the panel is open, and the button blurs so :focus-within cannot hold it wide.
  • Waffle button: app_sidebar_waffle = hide adds app-sidebar--nowaffle to the nav, and body:has(.app-sidebar--nowaffle) .waffle-btn { display: none } sits inside the desktop media query on purpose, so a phone always keeps the button. Only the button is hidden - #wafflePanel stays in the page, because the rail's Recent button opens it.
  • The order is module_order (Display order - Developer Guide); the sidebar never stores an order of its own, so it can never disagree with the waffle.

See also