extendMenu(menuCallback)

Customizes the top-right Scrivito menu.

Customizing the top-right Scrivito menu can make the life of editors easier. Custom menu items allow you to easily integrate editing tools like a third-party translation management system, for example. They can also simplify creating complex content by providing dialogs for navigating the editor through the required steps.

With Scrivito.extendMenu, you specify a callback that describes your changes to the top-right Scrivito menu. The argument passed to the menu callback represents an interface which provides the insert method for adding custom menu actions. This method can be called multiple times, typically there is one call per menu item.

The callback is subject to automatic loading, just like the render method of connected Scrivito components. This makes conditional and context-aware menu customizations possible, for example in conjunction with Scrivito.currentPage.

Note that the callback passed to Scrivito.extendMenu is called whenever Scrivito chooses to do so, including, but not limited to, when the Scrivito menu is opened. Thus, it must be free of side effects.

The following section illustrates how to use the insert method.

Adding a custom menu item

The insert method adds an item to the menu. A menu item has a title and a click handler. It may have a custom icon and a tooltip. The item can be positioned relative to another item or a group of items. An item can be greyed out.

Here is a fully fledged example:

The example above adds a custom action “Add a blog post” with a “circled plus” image as the menu icon, and a motivational tooltip.

The new entry is inserted underneath the “Create page” item. It belongs to the same menu group as “Create page”, thus it is shown without an extra menu separator.

Clicking the menu item in editing mode instantly presents a new blog post page to the editor. In preview mode, the item is greyed out and cannot be clicked.

Params

  • id (String) – The unique identifier of the inserted menu item. Must not be a reserved ID. Reserved IDs are system and strings starting with system..
  • description (String) – The tooltip of the menu item.
  • enabled (boolean) – If false, the menu item is greyed out. The click handler is not called for a disabled item.
  • group (String) The name of a menu item group. The group name can be a custom group name, or one of the system-defined groups (see below). For upward compatibility reasons, custom group names should not start with system. Note that group only refers to a visual aspect: Scrivito inserts separators between menu items with different group names. Specifying a group but no position does not move the item to the group.
  • icon (String) – The URL of an image representing the menu action. We recommend using SVG images. Note that Scrivito will adapt the image colors to match the Scrivito UI.
  • onClick (Function) – The menu action callback. It will be called when the user clicks the menu item. The callback receives no parameters.
  • position (Object) A key-value pair. The key must be before or after. The value should be a group name or a unique menu item ID. Note that Scrivito handles conflicting positions in a best-effort manner. If no position is given, the item is inserted at the end of the menu.
  • title (String) – The menu item’s label.

Removing a menu item

The remove method hides the menu item with the given ID from editors.

Params

  • id (String) – The unique identifier of the menu item to remove.

Example

Hide the command for adding a subpage. This is useful if your pages aren’t organized hierarchically by their path:

Changing the position and appearance of an existing menu item

The modify method can be used to reposition a system menu item or override an item’s label or icon.

Params

  • id (String) – The unique identifier of an existing menu item. If no item with the given ID exists, the call has no effect.
  • group (String) – The name of a menu item group. The item is reassigned to the specified group. See the insert options for details.
  • icon (String) – The URL of an image representing the menu action. See the insert options for details.
  • position (Object) – A key-value pair, specifying the new position of the item. See the insert options for details.
  • title (String) – The menu item’s label.

Example

Make “Share page” the first entry of the help section:

System groups and system menu items

Next to custom groups and items, the following groups with their respective items’ IDs are available for grouping and positioning. Note that items may be added or removed in future updates. Specifying a nonexistent system group name or menu item ID is handled gracefully by Scrivito.

  • system.create
    • system.createPage “Create page”
  • system.add
    • system.addSubpage “Add subpage”
    • system.duplicateObj “Duplicate page”
  • system.details
    • system.openPageDetails “Edit/View page properties”
    • system.sharePage “Share page”
  • system.clipboard
    • system.saveObjToClipboard “Copy or move page”
    • system.copyObjFromClipboard “Paste as subpage”
    • system.moveObjFromClipboard “Move here as subpage”
  • system.modify
    • system.markResolvedObj “Override concurrent changes to page”
    • system.restoreObj “Restore resource”
    • system.revertObj “Discard changes to page”
    • system.deleteObj “Delete page”
  • system.help
    • system.openUserGuide “Open help”
    • system.enableTour “Start tour”
  • system.account
    • system.openDashboard “Open dashboard”