Download the PHP package automattic/jetpack-admin-ui without Composer

admin-ui

Generic Jetpack wp-admin UI elements

How to use

Menu Registration

Use the Admin_Menu class to add your plugin under the Jetpack top level menu in WP-Admin.

This package will make sure to register the top level menu, if not registered yet, and will add the new menu(s) item(s) under it.

Use the add_menu to register your menu, no need to do it inside the admin_menu hook. You can do it in your plugin initialization.

The parameters this method gets are the same parameters add_submenu_page gets, except that you don't need to inform parent menu.

Example:

Menu visibility

An item can declare what gates it, so that turning its feature off removes it from the sidebar. Pass the declaration as the seventh argument:

Prefer product. A product is not the same thing as a plugin. It may be gated by a Jetpack module, by a standalone plugin, or by either:

The product's is_activated() already knows which of those applies, so a registration site names the product and never has to work out which kind it is. It asks only whether the site has switched the product on, never whether it has a plan: a lapsed plan keeps the item, so the route back to upgrading survives, and resolving a gate never makes a request to WordPress.com.

Reach for module only when a sidebar item has no product class at all. SEO is the example: it's gated by the seo-tools module and has no My Jetpack card, so there's no product to name. An item that declares neither is always shown.

A name this site has no module for cannot be answered, so it keeps the item rather than removing it — a typo in a gate is inert. Off the Jetpack plugin that covers any module a standalone plugin has not declared through jetpack_get_available_standalone_modules, so declare one there before expecting a module gate to do anything.

A module gate reads Modules::is_active(), which always answers true on WordPress.com Simple, so gates there never remove anything. Hosts on Simple shape the sidebar through the filter below.

Always declare a key, as a fixed string rather than a reference to the page's slug constant, so renaming a page never renames what hosts have written into their filters.

Everything fails open. An item that declares no gate, a gate naming a product that isn't registered, and a site where My Jetpack didn't initialize all leave the item in place, so declaring a gate can only ever remove an item deliberately.

Declaring a gate is a commitment that the page renders something sensible when the gate is unsatisfied, because a host can force it visible anyway — see below.

Host control

jetpack_admin_menu_visibility filters a map of item key to state. Absent keys stay default.

Every state governs the sidebar entry only. An item that is hidden, or whose gate is unsatisfied, still registers its page, so admin.php?page=… keeps working for My Jetpack's Manage buttons, bookmarks, and support links.

The whole map is passed at once so two mu-plugins setting different keys merge rather than clobber each other. visible cannot expose a page to someone who lacks the capability for it: an item is only registered for users who have it.

Only items registered through Admin_Menu::add_menu() or Admin_Menu::add_top_level_menu() are in the map. Anything added with a bare add_submenu_page() or add_menu_page() is out of this filter's reach.

Top level pages

A few Jetpack pages deliberately sit outside the Jetpack menu. add_top_level_menu() registers those under the same gate, filter and hidden-but-reachable behavior as add_menu(). The parameters mirror add_menu_page(), with the visibility declaration appended:

A gate removes the item wherever it resolves false, so check it holds in every context that registers the page — a standalone plugin can run without the Jetpack plugin a product gate may assume.

Stats and Premium Analytics register this way, under the keys jetpack-stats and jetpack-premium-analytics.

Unlike add_menu(), the page gets neither the core-notice CSS nor the WPDS design tokens; call Admin_Menu::hide_core_admin_notices() or Admin_Menu::enqueue_design_tokens() on its own load- hook for either. Registering only top level items never builds the Jetpack menu.

Security

Need to report a security vulnerability? Go to https://automattic.com/security/ or directly to our security bug bounty site https://hackerone.com/automattic.

License

admin-ui is licensed under GNU General Public License v2 (or later)