07 — Navigation and mega menu#

Navigation is where "editable by a non-technical person" usually breaks down. KodePress treats menus as data (a tree of items with rules) and mega-menu panels as content (a block tree), which is why a mega panel is built with the page editor rather than a bespoke screen.

7.1 Menus#

Menus in the sidebar lists every menu with its location and item count.

Menu screen layout: the tree on the left (drag and drop, collapse/expand, multi-select), the selected item's settings in the middle, and a live preview of the rendered menu on the right. The preview uses the real renderer inside the real header, so the owner sees the actual result.

Bulk operations: select several items to move them under a new parent, delete them, toggle new_tab, or set visibility in one go.

Menu-level settings (menus.settings): desktop alignment (left/centre/right), submenu open trigger (hover/click), submenu animation (none/fade/slide), submenu indicator (chevron on/off), mobile behaviour (accordion/drawer), and auto_children (see 7.4).

Import/export: a menu exports as JSON (items with targets resolved to slugs, not ids) and imports into another menu or another site, re-resolving slugs and reporting anything it could not match. Copy menu duplicates within the site.

7.2 Item types#

Per-item settings:

7.3 Visibility rules#

menu_items.visibility:

{
  "auth":    "any",                 // any | guest | user
  "roles":   ["admin", "editor"],   // empty = no role restriction (only meaningful with auth=user)
  "devices": ["desktop", "mobile"], // empty = all
  "locales": ["bn"]                 // empty = all
}

Evaluation:

• auth and roles are evaluated server-side. An item a visitor must not see is never emitted into the HTML.
• devices is applied with CSS classes (kp-hide-mobile), because the HTML cache is shared across devices. Hiding a link on mobile is a layout choice, not a security boundary — the docs for the field say exactly that.
• locales is evaluated server-side; each locale has its own cached HTML anyway.
• A rule on a parent hides the whole branch.

Because auth-dependent menus cannot be shared with anonymous visitors, a menu containing any auth != any item makes its containing header cacheable: false for logged-in users only: anonymous visitors still get the cached file (built with the guest view of the menu), and logged-in users render dynamically. See 13-caching-and-performance.md.

7.4 Auto-sync and integrity#

auto_children is a per-item toggle (settings.auto_children) that expands a category item with its child categories, optionally with a View all first entry. Manually added children and auto-children can coexist; manual ones come first.

Active-item highlighting: the renderer marks an item aria-current="page" when its resolved URL equals the current path, and adds kp-menu-ancestor to its ancestors. Because HTML is cached per path, the active state is baked into each page's cached copy — correct by construction, with no JavaScript.

7.5 Mega menus#

Any item at depth 0 has a Mega menu toggle. Turning it on opens the panel editor: the same section/column/block editor used for pages, in the mega context.

• The tree is stored in menu_items.mega.
• An empty panel means the item behaves as a normal dropdown. Turning the toggle off keeps the tree, so experimenting is safe.
• Any block whose contexts include mega can be used: icon_list, heading, text, image, button, post_list, video, search, language_switcher, divider, spacer.

Ready-made panel layouts#

Offered when the toggle is first turned on (each is a templates row with kind = section and category mega):

The tabbed layout is the only one with behaviour beyond layout: tab state is Alpine-local, panels are all rendered and toggled with hidden, so there is no request on hover.

Panel settings (menu_items.settings)#

Behaviour#

• Desktop: open_on: hover opens after a 120 ms intent delay and closes after a 240 ms grace period, so a diagonal mouse path does not close the panel. open_on: click toggles on click and on Enter/Space, and closes on Escape or an outside click.
• Keyboard: the trigger is a <button aria-expanded aria-controls>; Tab moves into the panel; Escape closes and returns focus to the trigger. Hover-only menus are still fully operable by keyboard because hover and click both open.
• Mobile: the panel becomes an accordion (the panel tree rendered stacked, single column) or a drawer, per mobile_mode. Columns collapse to one; icon_list stays a list; a post_list inside a panel caps at 3 items on mobile. This is a render-time transformation of the same tree, not a second tree the owner must maintain.
• Touch on desktop widths: the first tap opens, the second follows the link.

7.6 Rendering a menu#

MenuSlot block (menu_id, depth limit, style overrides)
  -> MenuRenderer::render(menu, ctx)
       |-- load items once, ordered by (parent_id, position), build the tree in PHP
       |-- resolve each target to a URL (page path, category path, raw url, tel:, mailto:)
       |-- drop items failing server-side visibility; add device CSS classes
       |-- mark active / ancestor against ctx.path
       |-- for each item with a non-empty `mega`: PanelRenderer::render(tree, ctx)
       +-- emit nav > ul > li markup with ARIA

One query loads all items for a menu; nothing in the loop touches the database. Target resolution batches its lookups (all page ids in one query, all category ids in one query). A menu with 60 items and 4 mega panels costs 4 queries, and in practice zero, because the result lands in the cached page HTML.

Markup contract:

<nav class="kp-menu kp-menu--header" aria-label="Main menu">
  <ul class="kp-menu__list">
    <li class="kp-menu__item kp-menu__item--has-panel">
      <button class="kp-menu__link" aria-expanded="false" aria-controls="kp-panel-12">
        Products <span class="kp-menu__chevron" aria-hidden="true"></span>
      </button>
      <div class="kp-panel" id="kp-panel-12" hidden> ... panel tree ... </div>
    </li>
    <li class="kp-menu__item">
      <a class="kp-menu__link" href="/about" aria-current="page">About</a>
    </li>
  </ul>
</nav>

7.7 Permissions#

An Editor can keep navigation current (add a link to a new page) without being able to restructure the design. This split is enforced by MenuPolicy, not by hiding buttons.

7.8 Tests for this document#

KodePress documentation · generated from the Markdown sources by tools/build-docs-site.py · internal preview, not indexed.