Concepts 🧠

Menu model 🗂️

A menu is an ordered tree of menu items stored in the menu behavior field.

Every item is either a folder item or a link item.

• A folder item is a placeholder. It groups children and has no navigation target; it renders as an a.nav-link with href="#" for Barceloneta feature parity.

• A link item is a leaf. It has exactly one target, either an internal Plone object or an external URL.

The stored value is native JSON:

{
  "version": 1,
  "items": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "type": "folder",
      "title": "Products",
      "css_class": "nav-products",
      "icon": "folder",
      "children": [
        {
          "id": "22222222-2222-4222-8222-222222222222",
          "type": "link",
          "title": "Product A",
          "css_class": "",
          "icon": "contenttype/document",
          "internal_uid": "e5f6…",
          "external_url": "",
          "open_in_new_tab": false
        }
      ]
    }
  ]
}

Inheritance 🧬

The menu in effect is the nearest ancestor with a configured menu.

• An unset field (None) means “inherit”; the search continues upward.

• An explicitly saved empty menu means “opt out”; the search stops and the viewlet renders nothing.

• If no ancestor configures a menu, the viewlet renders nothing.

• There is no fallback to Plone’s default main navigation.

This lets the site root define a site-wide menu, while a section can override it or opt out.

Link resolution and permissions 🔐

Internal links store the target’s raw UID. At render time the UID is looked up through the catalog and checked against the current user’s View permission.

• An inaccessible or deleted internal link is omitted.

• A folder whose visible children are all omitted is omitted too.

• External links are always rendered.

Rendering 🎨

A viewlet subclasses Plone’s GlobalSectionsViewlet and replaces the plone.global_sections viewlet. It preserves the Barceloneta markup contract:

• ul#portal-globalnav with navbar-nav;

• li.nav-item and a.nav-link;

• has_subtree, dropdown, and the mobile opener input/label pair;

• pat-navigationmarker for the active/in-path behavior.

Storage 💾

The menu is a native dict in a plone.schema.JSONField. Internal targets are also registered with plone.app.linkintegrity when the menu is saved, so deleting a referenced target shows Plone’s standard warning. External URLs and links to the Plone Site root itself are not tracked. Linkintegrity relations are created on the next save; existing menus are not backfilled.