diff --git a/docs/content/navigation/PRO__landing_page.md b/docs/content/navigation/PRO__landing_page.md index 5a210cbcb78..4d19e0d5e15 100644 --- a/docs/content/navigation/PRO__landing_page.md +++ b/docs/content/navigation/PRO__landing_page.md @@ -25,7 +25,7 @@ The landing page applies when signing in has nowhere else to go: When you were sent to the sign-in page from a specific page (a link to a finding, for example), signing in takes you back to that page instead. -If your landing page later becomes unavailable to you (a role is removed, or the feature behind it is turned off), signing in opens Home instead, without an error. +If your landing page later becomes unavailable to you (a role is removed, the feature behind it is turned off, or a [sidebar preset](/navigation/pro__sidebar_presets/) hides it), signing in opens Home instead, without an error. The profile page says so when the preset you picked hides it. ## Turning it off diff --git a/docs/content/navigation/PRO__sidebar.md b/docs/content/navigation/PRO__sidebar.md index 1c4b907a021..84e8c8555e1 100644 --- a/docs/content/navigation/PRO__sidebar.md +++ b/docs/content/navigation/PRO__sidebar.md @@ -50,7 +50,7 @@ Four conventions run through the whole menu: ![The Pinned section at the top of the sidebar](images/sidebar_pinned_pages.png) -Hover any page row in the sidebar or in a collapsed-rail flyout and a pin appears at its end; on touch screens the pin always shows. In Global Search, a page result's row actions menu (the **...** button, or **Option+Enter** / **Alt+Enter**) offers **Pin to Sidebar** and **Remove Sidebar Pin**. Pinning a page adds it to a **Pinned** section at the very top of the menu, which exists only while you have pins. A pinned row is the real menu entry, so its badge, its permissions, and the active highlight all keep working, and a page you lose access to simply stops appearing without losing its pin. The pin stands upright on rows that are pinned; select it again to unpin. +Hover any page row in the sidebar or in a collapsed-rail flyout and a pin appears at its end; on touch screens the pin always shows. In Global Search, a page result's row actions menu (the **...** button, or **Option+Enter** / **Alt+Enter**) offers **Pin to Sidebar** and **Remove Sidebar Pin**. Pinning a page adds it to a **Pinned** section at the very top of the menu, which exists only while you have pins. A pinned row is the real menu entry, so its badge, its permissions, and the active highlight all keep working, and a page you lose access to, or one your [sidebar preset](/navigation/pro__sidebar_presets/) hides, simply stops appearing without losing its pin. The pin stands upright on rows that are pinned; select it again to unpin. A page pinned from inside a group keeps the group's name and icon, since the entry's own name often leans on the group it came from: pinning **All** from **Findings** shows **Findings › All**, so it cannot be mistaken for the **All** under Assets. When the sidebar is too narrow, the group name shortens first and the page name stays whole; hover the row to see its full location. Pages that sit directly in a section, such as **My Work**, show just their name. @@ -181,7 +181,8 @@ The last category, **Elsewhere in the app**, lists pages that configure DefectDo The **UI Defaults** group collects the settings that control how much of the interface each person can tailor: - **[Form Configuration](/navigation/pro__form_configuration/)**: choose which fields the create and edit forms show and require, and whether the Optional Fields panel starts expanded. -- **Layout Defaults**: the **Restrict Layout Customization** switch, plus the global defaults designated for dashboards, [page layouts](/navigation/pro__page_layouts/), and table views. With the switch on, only superusers can create or change dashboards, page layouts, table views, and [pinned sidebar pages](#pinned-pages); everyone else is shown the designated defaults, or the built-in defaults when none are chosen. Personal layouts saved earlier are kept and reappear if the switch is turned back off. You choose each default from a dropdown of the layouts an administrator has shared, or designate one in context (a shared dashboard's Manage dialog, a view page's layout menu, or a table's Views menu). +- **[Sidebar Presets](/navigation/pro__sidebar_presets/)**: named presets that hide sidebar entries, shared with everyone or kept to one person, with one shared preset as the instance default. A preset hides, it never denies: direct links and the API keep working. +- **Layout Defaults**: the **Restrict Layout Customization** switch, plus the global defaults designated for dashboards, [page layouts](/navigation/pro__page_layouts/), [sidebar presets](/navigation/pro__sidebar_presets/), and table views. With the switch on, only superusers can create or change dashboards, page layouts, sidebar presets, table views, and [pinned sidebar pages](#pinned-pages); everyone else is shown the designated defaults, or the built-in defaults when none are chosen. Personal layouts saved earlier are kept and reappear if the switch is turned back off. You choose each default from a dropdown of the layouts an administrator has shared, or designate one in context (a shared dashboard's Manage dialog, a view page's layout menu, or a table's Views menu). ## What moved @@ -241,6 +242,8 @@ Most optional entries follow a flag on the [Feature Flags](/admin/feature_flags/ The others work the other way round: they are off by default, and the entry appears when the flag is turned on. Examples are the Triage Engine, the Remediation Center, Root Causes and PSIRT (which also needs Locations and a license). +Flags remove an entry for the whole instance. To take entries away for some people and not others, or for yourself, use a [sidebar preset](/navigation/pro__sidebar_presets/): a named list of hidden entries that leaves every page reachable by its link. + The Calendar toggle used to be **Enable Calendar** in System Settings. It moved so that the switches which add or remove a menu entry sit together in one place, and the System Settings checkbox is gone. Your existing choice is carried across on upgrade: an instance that had the calendar switched off keeps it off. ## The classic sidebar @@ -249,5 +252,6 @@ This layout is the only sidebar. The classic sidebar it replaced, and the **Menu ## Related +* [Sidebar Presets](/navigation/pro__sidebar_presets/): hiding entries with named, sharable presets * [Menu Badges](/navigation/pro__menu_badges/): what the `NEW`, `BETA`, `SOON`, `LEGACY` and `DEPRECATED` tags mean * [Feature Flags](/admin/feature_flags/pro__feature_flags/): turning optional features on and off diff --git a/docs/content/navigation/PRO__sidebar_presets.md b/docs/content/navigation/PRO__sidebar_presets.md new file mode 100644 index 00000000000..7cf99b16e49 --- /dev/null +++ b/docs/content/navigation/PRO__sidebar_presets.md @@ -0,0 +1,85 @@ +--- +title: "Sidebar Presets" +description: "Hide sidebar entries with named presets that can be shared, duplicated and set as the instance default" +draft: false +weight: 7 +audience: pro +--- +Note: Sidebar Presets are a DefectDojo Pro feature. + +A **sidebar preset** is a named list of sidebar entries to hide. A team that only triages findings can have a sidebar with the Connect section, the Sensei pages and most of Settings gone; a team that runs integrations can keep those and lose the rest. Presets are built on **Settings > UI Defaults > Sidebar Presets**, shared with everyone or kept to one person, duplicated like a dashboard or a page layout, and one shared preset can be the instance default. Each person picks the preset that shapes their own sidebar on their User Profile page. + +A preset follows the user, not the browser: the pick is saved to the account, and the sidebar, the **Cmd+K** / **Ctrl+K** menu search, the [Default Landing Page](/navigation/pro__landing_page/) list, the All Settings directory and the walkthrough lightbulb all read the same preset, so they never disagree about what is there. + +## Hidden, never denied + +A preset only takes entries away from what a person can already see. It never adds an entry a role, a feature flag or the license hides, and it never removes access: a direct link, a bookmark, the menu search for a page name that is hidden, and the API all keep working. Roles decide who may open a page; a preset decides what the sidebar shows. To stop someone opening a page, change their role. + +Because a preset is a list of hidden entries rather than a list of shown ones, the sidebar keeps up with the product on its own: + +- An entry added in a later release appears for everyone, whatever preset they use, until someone hides it. The editor marks such entries **New Since Last Saved**, and the preset picker shows how many a preset has not seen yet. +- An entry removed from the product disappears on its own. The editor lists it under **No Longer in the Sidebar** so it can be dropped on the next save. +- An entry a feature flag turns off is not in the sidebar, so a preset has nothing to say about it. Turning the flag on brings it back for everyone. + +Three entries are always shown, whatever a preset says: **Home**, so every section a person can see has somewhere to go, **All Settings**, so everyone keeps the way to their User Profile and their own preset choice, and **Sidebar Presets**, so a preset can never hide the page that would undo it. A group that holds one of them stays in the sidebar with only that entry. + +A preset also applies to **pinned pages**: a page the preset hides leaves the Pinned section of the sidebar until the preset shows it again. The pin itself is kept. This is deliberate, so a preset set for a team decides what that team's sidebar shows. + +## Building a preset + +Open **Settings > UI Defaults > Sidebar Presets**. A toolbar across the top holds the preset picker and the actions on the open preset: + +- The **picker** lists the presets you can see (the instance default first, then the one you use, then the rest by name) and filters by name as you type. An icon marks the preset you use, the instance default and the shared presets, and each option says how many entries the preset hides. +- **Use for Me** makes the open preset shape your own sidebar; it then reads **In Use**, and clicking it again stops using it. +- **Instance Default** (shared presets, for people who hold the Share permission) makes the open preset the instance default, or clears it. +- **Duplicate** starts a new preset from a copy named ` (Copy)`, and **Delete** removes the open preset after a confirmation. +- **New Preset**, the plus button at the end, starts an empty one. + +Under the toolbar, the editor has the preset's **Name**, an optional **Description** and, for people who hold the Share permission, a **Shared** checkbox. Below them, **Sidebar Entries** lists every sidebar section with its groups and entries, indented the way the sidebar nests them, each with a switch: + +- Switching an entry off hides it. Switching a **group** or a **section** off hides it and everything under it; those entries read **Hidden with ** and keep their own settings, so switching the group or section back on restores them exactly as they were. +- The list is the preview. An entry that stays in the sidebar is tinted, a hidden one is struck through where it sits, and a group or section with nothing left to show reads as hidden too. Each section's tag counts how many of its entries are shown, and the header counts what the whole preset hides. +- Sections and groups fold from the chevron at their left, as in the sidebar. A section you switch off folds on its own. +- Entries you cannot open yourself are still listed, marked **Not visible to the current user**, so an administrator can build a preset for people with other roles. +- The search box in the header filters the entries by name. + +Changes are kept in the fields until you save them: a bar at the bottom of the page names what changed, with **Save Changes** and **Discard**, the same bar that saves edits made in place on a finding or an asset. Saving also records which entries the sidebar had at that moment, which is what the **New Since Last Saved** marks are measured against. + +## Sharing and the instance default + +A **shared** preset appears in every user's picker and in the **Sidebar Preset** field on every User Profile page. A preset is shared or unshared with the **Shared** checkbox in the editor, saved with the rest of the preset. Sharing, unsharing, editing or deleting a shared preset, and choosing the instance default, all require the **Share Sidebar Preset** permission (under Additional Permissions in the role editor). A personal preset is edited and deleted by its owner with the Sidebar Preset Edit and Delete permissions, and anyone with Sidebar Preset Add can create one. + +The **instance default** is the shared preset everyone gets who has not picked a preset of their own. Set it with the **Instance Default** button on the Sidebar Presets toolbar, or on **Settings > UI Defaults > Layout Defaults**, next to the dashboard, page layout and table defaults. Clearing it gives those users the full sidebar again. Deleting a preset that people had picked sends them back to the instance default. + +While **Restrict Layout Customization** is on (also on the Layout Defaults page), everyone but superusers is pinned to the instance default: the **Sidebar Preset** field on User Profile reads **Set by an administrator**, and personal presets are kept but not applied until the switch is turned back off. + +## Picking a preset + +Each person picks their own preset in one of two places: + +- **Use for Me** on the Sidebar Presets toolbar, with the preset open. +- The **Sidebar Preset** field on the **User Profile** page (select your username at the bottom of the sidebar, then **User Profile**, under **Navigation**). The first option is the instance default; the rest are your own presets and the shared ones. **Submit** saves it with the rest of the profile. + +The sidebar, the menu search and the landing page list change at once, without a reload. If the chosen preset hides the page set as your [Default Landing Page](/navigation/pro__landing_page/), the profile page says so and sign-in opens Home instead. + +## The permissions + +| Permission | Lets a role | +| --- | --- | +| **Sidebar Preset View** | open the Sidebar Presets page and pick a preset on User Profile | +| **Sidebar Preset Add** | create presets and duplicate existing ones | +| **Sidebar Preset Edit** | edit the presets it owns | +| **Sidebar Preset Delete** | delete the presets it owns | +| **Share Sidebar Preset** | share and unshare presets, edit and delete shared ones, and set the instance default | + +The four verbs sit in the Global Feature Permissions table of the role editor and the Share capability under Additional Permissions. They take effect through a global role: a preset is instance-wide, so a role held on one organization grants nothing here. By default Owner and Maintainer hold all five, Writer holds View, and Reader holds none. Picking a preset for yourself needs no permission at all. + +## The API + +Presets are managed at `/api/v2/sidebar_presets/` with the usual API token: list, create, update and delete, plus `clone`, `set_default` and `clear_default` for the caller's own pick, `set_shared_default` and `clear_shared_default` for the instance default, `shared` for the shared presets and `for_current_user` for the preset in effect. The entries a preset hides are **navigation ids**: a page's route suffix (`asset/all`, `settings/feature-flags`), `group:` for a group, or `section:` for a whole section. The editor shows a row's id when the pointer rests on it. + +## Related + +* [The Sidebar](/navigation/pro__sidebar/): the sections, pinned pages and the menu search +* [Default Landing Page](/navigation/pro__landing_page/): the page sign-in opens +* [Customizing Page Layouts](/navigation/pro__page_layouts/): the same sharing and default model for view pages