Download the PHP package acrossai-co/main-menu without Composer

AcrossAI Main Menu

A reusable Composer package that registers the shared AcrossAI top-level admin menu and its standard submenus inside WP Admin:

• Dashboard — the AcrossAI landing page (parent menu)
• Settings — a shared WordPress Settings API page (flat or tabbed) that any plugin extends with its own sections, fields, and options
• Notices — a shared admin-notice collector any plugin can push into via the acrossai_notices filter; a WP-native dismissible summary is emitted on every other admin page when notices exist

Designed to be installed in multiple plugins side-by-side: automattic/jetpack-autoloader ensures only the highest-version copy boots, so the menu is registered exactly once regardless of how many plugins ship the package.

Requirements

• PHP 8.1+
• WordPress 6.0+
• automattic/jetpack-autoloader: ^5.0 in your plugin's composer.json

Installation

Load the autoloader in your plugin (jetpack-autoloader generates vendor/autoload_packages.php):

Quick start (consumer plugin)

In your plugin's main file:

That's it. The first plugin (by jetpack-autoloader version resolution) to boot registers, in order under the AcrossAI parent menu:

• AcrossAI parent menu (add_menu_page, slug acrossai) — the Dashboard landing page
• Settings submenu (slug acrossai-settings, priority 20)
• Notices submenu (slug acrossai-notices, priority 25 — only when at least one notice is registered via the acrossai_notices filter)
• Add-ons submenu (slug acrossai-addons, priority 1000)
• Consultations submenu (slug acrossai-consultations, priority 1010)

If 3 plugins all ship this package, you still get one menu and one of each page. Every other copy becomes a no-op via jetpack-autoloader's version resolution.

The Settings page renders a standard <form action="options.php"> with settings_fields(), do_settings_sections(), and submit_button(). Feature plugins (Abilities, MCP, Model, etc.) register their own submenu pages against the acrossai parent slug from their own codebases — the main-menu package no longer pre-registers navigation slots for them.

Known limitations

• Multisite: not tested or supported. Works on per-site dashboards but network-activated behaviour is undefined.

Adding settings from your plugin

The shared identifier is acrossai-settings — it is both the page slug (for add_settings_section / add_settings_field) and the option_group (for register_setting / settings_fields). Use it as the target everywhere.

That's the entire extension. No JS, no enqueue, no PHP routing — just standard WP hooks. The Settings page will display Plugin A's section automatically.

Tabs

The Settings page has two rendering modes:

• Flat — no plugin hooks the acrossai_settings_tabs filter. The page renders a single form (today's behavior); use 'acrossai-settings' as the page slug for add_settings_section / add_settings_field.
• Tabbed — any plugin registers at least one tab. The page renders a nav-tab-wrapper bar; each tab has its own form and Save button. Sections must target a tab's page slug (see below).

Registering a tab

Hook the acrossai_settings_tabs filter and append a tab entry:

Tab entry shape:

Duplicate slugs: first registration wins. With WP_DEBUG on, subsequent duplicates trigger _doing_it_wrong().

Adding sections/fields to a tab

Get the shared renderer and call its tab_page_slug( 'your-tab-slug' ) instance method to obtain the $page argument:

Notes:

• option_group is tab-scoped in 0.0.13+. Each tab's form posts with option_page = <tab-scoped slug>, so WordPress walks only that tab's whitelist on save. This prevents the cross-tab option-clobber bug that shared-acrossai-settings had in 0.0.12 (saving one tab silently wiped other tabs' options). See "Migrating from 0.0.12" below.
• One Save button per tab. Switching tabs without saving discards in-progress changes (standard WP admin pattern).
• Active tab persistence. The active tab survives the Save round-trip via _wp_http_referer — no extra wiring needed.
• Backward compatibility. If no plugin hooks acrossai_settings_tabs, the flat-page example earlier in this README keeps working unchanged. Once any plugin registers a tab, sections still attached to the bare 'acrossai-settings' slug are not rendered — migrate them under a tab.

Migrating from 0.0.12 (breaking change)

0.0.13 fixes a cross-tab option-clobber bug by making each tab's form use its own tab-scoped option_page / option_group. If your consumer plugin registered settings against the shared 'acrossai-settings' in tabbed mode, its Save will silently no-op (WP's options.php handler rejects the write because the option is not in the tab-scoped whitelist).

One-line migration per register_setting() call:

No other code changes are required. add_settings_section() / add_settings_field() were already using $page = tab_page_slug(...) — those stay the same.

Reusing the tabbed pattern on another page

The Settings page is one instance of a generic pattern. To add a second tabbed admin page (e.g. a "Tools" page) without re-implementing tab rendering, subclass TabbedPageRenderer and pin two things — the WP page slug and a short key that becomes the tabs filter name:

Third-party plugins register tabs on the new page by hooking acrossai_tools_tabs — same entry shape (slug, label, priority, capability) as acrossai_settings_tabs. They register sections against $renderer->tab_page_slug( 'my-tab' ) exactly as with the Settings page.

The filter name is always "acrossai_{$key}_tabs", so each page gets its own isolated tab list. Rendering, capability gating, active-tab detection, and the per-tab form + Save button are all handled by TabbedPageRenderer — subclasses add no rendering code.

Using the tabs base without a Settings page

The tab plumbing (filter, list, active tab, nav rendering) lives in \AcrossAI_Main_Menu\Tabs. TabbedPageRenderer extends Tabs and layers the Settings-API form + Save button on top. If you want the tab bar but not the Settings-API form — a custom admin screen, a meta box, a dashboard widget, a Tools submenu that renders its own body — extend Tabs directly:

The default tab-URL builder is add_query_arg( 'tab', $slug ) against the current request URL, so tab links stay on whatever screen you're rendering. Two extension points cover non-standard contexts:

• Override default_tab_url( $tab_slug ) on your subclass to emit a different URL scheme (e.g. an admin submenu that needs admin.php?page=…&tab=…, or a REST-driven screen with a hash fragment).
• Pass a $url_for callable to render_tab_nav() per invocation for one-off tweaks — e.g. $tabs_ui->render_tab_nav( $tabs, $active['slug'], fn( $slug ) => my_url( $slug ) ).

For non-URL active-tab sources (block attribute, POST body, session), override protected function get_requested_slug(): string to read from your source instead of $_GET['tab'].

Notices

Any consumer plugin can push admin-notice records into a shared collection with the acrossai_notices filter. Those records surface in two places:

• Notices submenu under the AcrossAI parent (slug acrossai-notices) — always visible when at least one notice exists, with a count bubble in the menu label. Full styled list, no dismiss controls — this page is the always-visible collector.
• Top-of-page summary — a single WordPress-native .notice.notice-warning.is-dismissible printed on every other admin page. Reads "AcrossAI has N notifications for your attention — View notices →". Clicking the ✕ persists dismissal until the notice set changes.

The Notices submenu is not registered when zero notices exist; the summary is not printed on the Notices page itself, when the count is zero, or for users without manage_options.

Registering a notice

The hook that adds the filter callback must fire before admin_menu (priority 25) — init, admin_init, or module bootstrap all work. Registering on admin_notices itself is too late: the notice list is memoized on first read.

Behaviour rules

• Deduped by id — first registration wins, later entries with the same id are silently dropped. Use a plugin-prefixed id (my_plugin_wp_cron_disabled) so consumer plugins don't collide.
• Required fields — id plus at least one of title or message. Missing either → the entry is dropped, not rendered.
• type fallback — anything other than error | warning | info | success becomes warning.
• message accepts inline HTML — rendered through wp_kses_post. title and source are esc_html-escaped.
• Dismiss persistence — the summary's dismiss stores a fingerprint (sha1 of the sorted notice ids) in the user meta _acrossai_notices_summary_fp. Add a notice, remove one, or change any id → the fingerprint changes and the summary reappears.
• Per-user dismiss — every admin dismisses the summary for themselves; other admins still see it.

Reading the notice list

For a consumer that wants to inspect the current collection (for a health check, dashboard widget, etc.):

SettingsPage::get_notices() returns null if the main-menu package has not booted yet in this request — safe to null-guard as shown.

How the page composes across plugins

do_settings_sections( 'acrossai-settings' ) iterates every section registered against that page slug, in registration order. So:

• 0 active plugins registering sections → empty page (just the Save button)
• 1 plugin → its section is shown
• 2+ plugins → sections are stacked top-to-bottom in registration order

All registered options share one Save button. A single POST to options.php saves every option whitelisted via register_setting( 'acrossai-settings', ... ) regardless of which plugin registered it.

Controlling section order

WP renders sections in the order they're registered. If you need deterministic ordering, hook your admin_init callback with an explicit priority:

Public PHP API

Notes for multi-plugin installs

• Version pinning matters: jetpack-autoloader picks the highest version of acrossai-co/main-menu across all active plugins. Bumping the version in one plugin's composer.lock makes that plugin's copy "win".
• All plugins should agree on the major version to avoid API drift across vendor copies.
• If you forget to load vendor/autoload_packages.php, the class won't be found and the menu silently won't appear.
• Option names must be globally unique across plugins (standard WP rule). Prefix them with your plugin slug (e.g. plugin_a_api_key) to avoid collisions.