Change the admin menu

List your app's admin links in CUSTOM_NAV, in src/custom/nav.ts: they appear in the admin side menu just before Profile, translated like the core items. To change, hide, add or move items anywhere in the menu, Arc CMS's own included, use CUSTOM_NAV_CHANGES in src/custom/nav-changes.ts (Change Arc CMS's items).

Add an item

1. Add the item to src/custom/nav.ts:

   import type { MenuItem } from '../shared/components/side-navbar/side-navbar.component';
   
   export const CUSTOM_NAV: MenuItem[] = [
     {
       label: 'Lessons',
       labelKey: 'custom.nav.lessons',
       route: '/admin/lessons',
       icon: 'fa-solid fa-book-open',
       allowRoles: ['admin'],
     },
   ];

2. Add the label to src/custom/i18n/en.json, and the same key to src/custom/i18n/hi.json:

   { "custom": { "nav": { "lessons": "Lessons" } } }

3. Make sure the route exists. An admin page needs an explicit route with the admin shell (Add an admin page). npm run test fails on an item whose address no route serves, yours or Arc CMS's.

The fields of an item

Group items

export const CUSTOM_NAV: MenuItem[] = [
  {
    label: 'Classroom',
    labelKey: 'custom.nav.classroom',
    icon: 'fa-solid fa-school',
    allowRoles: ['admin'],
    subItems: [
      { label: 'Lessons', labelKey: 'custom.nav.lessons', route: '/admin/lessons', icon: 'fa-solid fa-book-open' },
      { label: 'Classes', labelKey: 'custom.nav.classes', route: '/admin/classes', icon: 'fa-solid fa-users' },
    ],
  },
];

A group opens by itself when the current page is one of its sub-items.

Hide an item when a feature is off

Set feature on an item or a sub-item that only makes sense with that feature (Choose your app's features):

{ label: 'Refunds', labelKey: 'custom.nav.refunds', route: '/admin/refunds', icon: 'fa-solid fa-rotate-left',
  allowRoles: ['admin'], feature: 'payments' },

A group whose sub-items all go goes with them.

Where the items appear

Your items are placed together, in the order you list them, just before Profile, with a dividing line before Profile. To put one somewhere else, give it an id and move it with CUSTOM_NAV_CHANGES, or add it there with CUSTOM_NAV_CHANGES instead. The menu shows only the items whose allowRoles include the signed-in person's role.

Change Arc CMS's items

Fill in CUSTOM_NAV_CHANGES in src/custom/nav-changes.ts. Its admin list changes the admin menu; its member list changes the member menu the same way (Change the member menu). Each change names an item by its id (The admin menu's ids), never by its label, which is translated:

import type { NavChanges } from '../app/core/nav/nav-changes';

export const CUSTOM_NAV_CHANGES: NavChanges = {
  admin: [
    // Dashboard opens the app's own page
    { id: 'dashboard', route: '/admin/extension-dashboard' },
    // Media Manager is gone from the menu
    { id: 'media', hide: true },
    // Users is reworded with the app's own key
    { id: 'users', labelKey: 'custom.nav.people' },
    // A new item just after Dashboard, for admins and editors
    { add: { id: 'reports', label: 'Reports', labelKey: 'custom.nav.reports', route: '/admin/reports',
             icon: 'fa-solid fa-chart-line', allowRoles: ['admin', 'editor'] }, after: 'dashboard' },
    // Settings moves to the top, for admins only
    { id: 'settings', before: 'dashboard', roles: ['admin'] },
  ],
};

A change can:

How the changes are made:

• They are applied in the order you list them, after Arc CMS builds the menu, adds your CUSTOM_NAV items and leaves out the items of features that are off. So an item of a feature that is off stays gone, whatever a change says, and an added item with a feature that is off is left out too.
• A change can name an item at the top level or inside a group (such as contacts in Audience). before and after put the item in the same list as the item they name, so you can move a link into a group or out of one. A group never goes inside another group.
• Setting route drops the item's externalUrl, and setting externalUrl drops its route: an item opens one or the other. Setting label without labelKey shows your label as written, untranslated; to reword an item in every admin language, set labelKey to a key of yours in src/custom/i18n/, or reword the core key there (Styles and translations).
• A change that names an id the menu does not have is ignored when the app runs (the test suite reports it first, see below). An add whose before or after item is not in the menu goes at the end; a move whose item is not there leaves the item where it was.
• Profile and Logout cannot be hidden: people must always be able to reach their profile and sign out. A change to their allowRoles can only add roles, and Logout always opens the sign-out dialog, so its route, queryParams and externalUrl cannot be changed. You can still reword and move them.
• A dividing line is kept before Profile, wherever it is, and lines never lead, trail or come two in a row, so hiding items leaves no gaps.

Change the menu for some roles

A change with roles applies only when the signed-in person's role is one of them. Without roles it applies to every role. This is how one app shows admins, editors and its own roles different menus:

admin: [
  // Editors see Media Manager, without Settings
  { id: 'media', allowRoles: ['admin', 'editor'], roles: ['editor'] },
  { id: 'settings', hide: true, roles: ['editor'] },
  // Profile and Logout for editors too
  { id: 'profile', allowRoles: ['editor'] },
  { id: 'logout', allowRoles: ['editor'] },
],

The menu shows an item to the roles in its allowRoles; roles on a change decides who the change is for. Each page an editor can now see in the menu still needs a route guard that lets editors in: the menu never gives anyone access.

What the test suite checks

npm run test (in src/app/custom-space.spec.ts) reads your src/custom/nav.ts and src/custom/nav-changes.ts and fails, with the list of valid ids, on:

• a change, before or after that names an id the menu does not have (core's, your CUSTOM_NAV items', or one an add in the same list brings);
• a route that is not a path on this site starting with /, or an externalUrl that is not an https:// address;
• an add without an id or label, or with an id the menu already has; both before and after on one change; an empty roles;
• hiding Profile or Logout, or changing where Logout leads;
• a labelKey that no English file has, and an admin label key missing from src/custom/i18n/hi.json.

The admin menu's ids

Arc CMS's items and their ids, in menu order. Each signup form's own group and each content type's link are built from your data and have no id.

The ids are in src/app/core/nav/admin-menu.ts; the changes are made by applyNavChanges() in src/app/core/nav/nav-changes.ts.

Choose an icon

The admin loads Font Awesome Free 6.5.1 (see index.html), so any free icon works. Write the style class and the icon class: fa-solid fa-book-open, fa-regular fa-calendar, fa-brands fa-youtube.

To see which icons and styles exist, search public/assets/icons/fa-index.json: each entry has the icon name (n), its label, its free styles (s) and search terms. npm run icons:index builds that file for the admin's icon picker; it is a core file, so you never need to run it in an app.