Skip to content

user-guide.md

Latest commit

 

History

History
133 lines (93 loc) · 5.22 KB

user-guide.md

File metadata and controls

133 lines (93 loc) · 5.22 KB
Raw

Maestro User Guide

Maestro edits the WordPress admin menu in place. It stores global, cosmetic menu customizations as a sparse delta over the menu WordPress already builds.

Enter Edit Mode

After activating the plugin, open any admin page and choose Edit Menu in the admin bar. The admin menu stays expanded while editing so the available items are visible and stable.

Choose Exit Menu Editing when you are done. If an autosave is pending, the plugin finishes it before reloading the page.

Select A Menu Item

Click a top-level or submenu item to select it. A shared controls panel opens for the selected item.

Keyboard users can focus a menu item and press Enter or Space to select it. Once selected, focus moves into the controls panel.

Rename Items

Select an item and edit its label in the controls panel. Press Enter to commit the new label, or Escape to restore the previous label.

Renames are saved automatically after a short pause. The status indicator shows when a save is in progress and when it has finished.

Reorder Items

Drag menu rows to reorder them.

Top-level items can be reordered among other top-level items. Submenu items can be reordered within their current parent menu. Moving items between top-level and submenu positions is not included in this version.

Reordering with the keyboard

You can reorder without a mouse:

  1. Select an item by clicking it or pressing Enter / Space on its row.
  2. Bring focus back to the menu row anchor (press Shift+Tab from the rename field, or click the row).
  3. Press Alt+ArrowUp or Alt+ArrowDown to move the item one position.
  4. Listen for the position announcement ("Posts moved down, position 3 of 8"). Pressing the shortcut again moves the item further; focus stays on the row so you can chain multiple presses.
  5. If the item is already at the top or bottom, you will hear an assertive announcement ("Posts is already last") and the order will not change.

The shortcut is also exposed as aria-keyshortcuts on the selected row, so screen readers that surface shortcut metadata can discover it automatically. Changes are autosaved after each move.

Change Icons

Top-level menu items can use custom icons. Select a top-level item and open the icon picker.

The picker includes Dashicons, bundled Bootstrap Icons, search, and a No icon option. The saved icon value is validated server-side and may use any native WordPress icon form:

  • a Dashicon class
  • none
  • a base64 image data URI
  • an image URL

Submenu items do not have separate WordPress admin menu icons, so the icon control appears only for top-level items.

Configure Role Visibility

Select an item and open the visibility control. Check the roles that should not see the selected item in the admin menu.

Visibility settings are global. If an item is hidden from the Author role, it is hidden from all Author users. Custom roles registered by other plugins appear in the same control.

Visibility Is Not Access Control

Role visibility only declutters the menu. It does not prevent access to the underlying admin page.

WordPress protects admin pages with capabilities registered by WordPress core, themes, and plugins. If a user has the required capability and knows the URL, that page can still load even when its menu item is hidden.

For real access control, pair Maestro with a capability manager such as User Role Editor or PublishPress Capabilities.

Language Support

Maestro is translation-ready with the maestro text domain. The plugin ships a translation template plus starter language packs for Spanish (es_ES), German (de_DE), Japanese (ja), French (fr_FR), Portuguese (Brazil) (pt_BR), and Italian (it_IT). These catalogs cover the admin-bar toggle, editor buttons, picker labels, save status messages, and reset prompts. WordPress.org language packs can still override and extend the bundled translations; native-speaker and WordPress Polyglots review is welcome.

Seeing What You Changed

In edit mode, any item that differs from its WordPress default shows a small bullet indicator (•) on its row. The indicator uses a visible glyph plus screen-reader text, so it is perceivable without relying on color alone.

The indicator refreshes live as you make and undo changes: it appears the moment you commit a rename, change an icon, or toggle a visibility role, and it disappears when you reset that item.

Resetting One Item

Use Reset this item in the controls panel to remove customizations for the currently selected item. The button is visible whenever an item is selected and is highlighted when the item has been modified.

To reset with the keyboard: select the item, then Tab to the Reset this item button and press Enter or Space. The modified indicator will clear and the item's overrides will be removed from the saved configuration.

Resetting Everything

Use Reset all to delete the saved Maestro configuration and return the menu to the defaults generated by WordPress and active plugins.

Because the plugin stores sparse deltas instead of a rebuilt menu, reset is safe: when the saved option is removed, the natural menu returns automatically.