You can customize the menus of widget fields, widgets, and lists to provide additional functionality to editors, e.g. splitting or joining widgets, translating or converting their content, etc. See below for a fully functional example of how to insert an item into widget menus.

For accessing the menu object of a DOM element that represents a piece of CMS content, scrivito("menu") is available. Currently, this only applies to DOM elements that represent either widgets (the element has a data-scrivito-widget-obj-class attribute) or widget fields (the data-scrivito-field-type equals widgetlist). The menu object has several methods.

Adding new items

Use add to create new menu items:

The first argument, my_app.my_menu_item in the example above, is the menu item id to be used for referencing your command. If commands are used in more than one application, you should namespace their IDs and use dots to separate namespace components. The top-level namespace (i.e. an ID without “dots”) is reserved for the application and should not be used by libraries. For example, all menu items the SDK provides have the scrivito.sdk. prefix as in scrivito.sdk.copy_widget.

The following options are accepted:

• title (String) The menu item title shown to the user.
• execute (Function) A callback that is invoked when the user clicks the menu item.
• present (Function, optional) A callback that controls whether the menu item should be present. It is executed as the user opens the widget or widget field menu. If the function returns false, the menu does not include the menu item. By default, menu items are present.
• disabled (Function, optional) A callback that controls whether the menu item should be disabled. It is executed as the user opens the menu. If the function returns true or a string, the menu item is disabled, i.e. visible but not clickable. If a string is returned, it will be shown to the user as an explanation of why the item is not selectable. By default, menu items are not disabled.
• icon (String, optional) A name of a built-in icon. Currently, Scrivito includes the following icons:
  

Manipulating menu items

There are various methods for manipulating menu items:

You can determine the list of available command IDs using $("...").scrivito("menu").list():

Configuring item order

Using menu_order, the order of the items contained in a menu can be specified. The menu_order is an array of strings. Each string may be either the fully qualified ID of a menu item or a namespace referring to several menu items, followed by a wildcard (*):

The example above defines that the special_command menu item is to be the first item (if it is present in a menu), followed by the scrivito.editors.cool_stuff menu item. Afterwards, all menu items originating from the scrivito.sdk namespace are inserted into the menu. Finally, the remaining menu items from the scrivito.editors namespace are added to it.

Note that menu_order defines a global order for all menu items in the application. An individual menu is sorted using this configuraton, even though individual menus typically only feature a subset of the menu items present in menu_order. Menu items not specified in menu_order are inserted at the end of the menu, in the order they were added to the respective individual menu. Menu items matched by a namespace wildcard are also inserted in the order they were added to the menu referenced.

menu_order is intended to be set once by the application, it should not be called by gems. Instead, gems should provide their menu items in a sensible default order (by adding them in that order using add) and by providing a common namespace to group the items. This allows the application developer to easily specify the position of all menu items originating from a gem by inserting a namespace wildcard into the menu_order of the application.

Hello World!

In the example below, a “Hello World!” menu item displaying an alert when clicked is added to every widget menu (using CoffeeScript). For this, a handler for the content event is provided that iterates over the widget DOM elements and adds the menu item to each of them. Finally, the menu item order is changed to make the new item the first one of the menus.

Page menus can be extended in a way similar to widget menus to make global or page-related functionality available to editors. The JavaScript API method for this is scrivito.page_menu:

Analogous to widget menus, you can use list, remove, update, and replace to manipulate menu items. Page menu items can also be sorted using scrivito.menu_order.

Two more examples on how to add page menu items:

You can determine the list of available command IDs using scrivito.page_menu().list():