NAP-6 — Contributable Menus#
- Author:
Draga Doncila Pop <ddoncila@gmail.com>
- Created:
2022-12-02
- Resolution:
TBD
- Resolved:
TBD
- Status:
Draft
- Type:
Standards Track
- Version effective:
TBD
Abstract#
Since the initial release of npe2 infrastructure has been in place for
plugin developers to declare menu contributions. These contributions
add new items to menus in napari that have been deemed contributable.
Until now, only the layer context menu (available through right clicking on a layer in the layer list) has been contributable, but much discussion has occurred on the list of menus we wish to open up for contribution and the guiding principles behind the organization of this list.
This NAP defines an overall structure for contributable menus, an initial list of contributable menus that are to be opened up for plugin developers, and a process for users and plugin developers to propose new contributable menus to be added to the existing list.
Motivation and Scope#
Currently plugin developers can provide processing and analysis extensions strictly through
dock widget contributions. These are exposed to the user under the Plugins menu, either
directly at the top level if a plugin only provides a single widget, or in a submenu labelled
with the plugin’s display name when a plugin provides multiple widgets.
This Plugins menu quickly becomes difficult to parse with increasing number of plugins
installed in an environment, and does not provide sufficient structure for a user to be
able to quickly and coherently navigate through the extensions available to them.
The vast majority of plugins (217 out of 263) available today provide at least one widget contribution.
Of these, 140 provide just a single widget 19 provide more than five widgets and 9 provide more than 10.
This means that while it is important to provide structure within an individual plugin’s widgets,
we must also provide cross-plugin structure so that users with many plugins installed can find widgets
by the action they want to perform, rather than by hunting across
endless plugin submenus, or attempting to discern what a plugin’s widget might do from its title.
Without meaningful places to put their contributions, plugin developers are coming up with their own way to organize contributions, whether through numbering widgets in their menu, mangling names to achieve a certain order, or coming up with their own unsupported solutions for adding new menu items.
The goal of this NAP, therefore, is to provide a structured set of contributable menus that is easy to navigate, semantically organized and intuitive for both users and plugin developers.
Note
It is highly likely that with growing numbers of plugins, widgets and menus, menu navigation itself becomes more burdensome when hunting for a specific action. Searchability of menu items is not within scope for this NAP, but will be made available to users via a command palette.
What is a Menu Contribution?#
A MenuItem contribution in the npe2 manifest
adds a new item to one of the napari menus (defined by an ID). When this item is clicked,
the associated command is executed. Additionally, enablement clauses can be defined
that control when this menu item is available for clicking and when it is disabled. Similarly,
a when clause can be used to control whether the menu item is visible in the menu at all.
In addition to the menu items themselves, Submenu contributions can also be defined,
which add a new submenu to a contributable menu which can be populated with new
MenuItem contributions.
Currently, the only napari menu to which items can be contributed in this way is the
layer context menu, accessible by right clicking on a layer in the LayerList as shown
in the screenshot below. The new menu items and submenu are produced by the following code snippet:
name: napari-demo
display_name: Demo plugin
contributions:
commands:
- id: napari-demo.menu_item
title: A new menu item
python_name: napari_demo:menu_item
- id: napari-demo.submenu_item
title: A new item in a submenu
python_name: napari_demo:submenu_item
menus:
napari/layers/context:
- submenu: context_submenu
- command: napari-demo.menu_item
context_submenu:
- command: napari-demo.submenu_item
submenus:
- id: context_submenu
label: A new submenu
This NAP proposes new menu IDs and new top level menus to open for contribution.
Detailed Description#
We propose an initial set of contributable menus organized by the napari object being acted upon by the actions within the menu, and the likely output of those actions.
Items that Don’t Fit?#
Where a plugin developer feels that none of the submenus of a given menu are suitable
for their purpose, they should add their item to the deepest applicable menu. For
example, a widget that takes a layer and produces a new layer through random perturbations
would not fit under Layers -> Generate -> Segmentation but could fit under
Layers -> Generate.
Where a plugin developer feels no top level menu or submenu is suitable for their purpose,
they should add their item to their own plugin’s submenu under Plugins -> Your Plugin,
and consider requesting a new contributable menu via the process described below.
The top level menu bar in napari is not open for contribution, and new top level
menus can only be added via the process described below.
Implementation#
Add list of menus to
napari/constants/_menus.py, warning for invalid IDs and new top level menus as per #5153Implement menu contribution interface that allows plugins to refer to their own plugin submenu
Add functionality for opening widgets from a menu item
Expose menu contribution reference in
npe2Write menu contribution guide in
npe2
Backward Compatibility#
This work does not have any backward compatibility considerations for existing features.
In future, backward compatibility concerns could arise when a menu name/ID is
changed in napari, or when napari removes a menu that was previously
contributable.
In the first case, no change is required in plugin manifests, as napari
can simply maintain logic for migrating old IDs to new ones.
If a contributable napari submenu is removed, this should be highlighted
first by a deprecation warning. Once the submenu is deprecated, contributions
that refer to this submenu should instead be placed in the higher level
menu. For example, if Layers -> Generate -> Segmentation is removed,
existing contributions referring to this ID will be placed under
Layers -> Generate.
If a contributable napari top level menu is removed, this should be highlighted
first by a deprecation warning. Before the submenu is deprecated, core developers
must work to identify plugins that will need migration and aid the migration
process by opening issues and PRs as required. Top level menus should not be removed
without a clear migration guide of where these contributions should be placed in
the future. After the menu is deprecated, contributions referring to this menu
should raise a warning, and be placed in the plugin’s own submenu at the highest
level.
Plugin contributions to non contributable menus will raise warnings and be placed in the plugin’s submenu at the top level.
Future Work#
As mentioned above, a key feature to support rapid browsing for actions is the search functionality via the command palette. This is actively being worked on and is essential for navigation.
Once more contribution types are exposed for users, it’s important that users
are aware why certain actions are disabled when the user doesn’t meet the
requisite context declared in the contribution’s enablement clause. Since
the syntax for declaring these contexts is strictly defined, we should be
able to surface information to suers about what is required for the action
to be enabled and functional. For example, an action could declare itself
enabled only when a points layer and an image layer are selected. If
the user has only selected an image layer, we could indicate the missing
context to the user e.g. “Action takes a points and image layer, but no
points layer is selected”.
A desired attribute of these menu items is that users always know what
will happen when they click a menu item. Does a widget open? Is the layer
edited? Is a new layer added to the Viewer? Once more contribution
types are exposed, we should be able to either add this information
as metadata in the manifest file, or infer it from return type
annotations of contribution commands, and also expose this to the user.
Finally, the number of actions in each menu is heavily dependent on
the plugins installed in the user’s environment. Given a complete set of
contributable menus, we could dynamically inspect how many menu items
each submenu contains, and group them appropriately for the user while
limiting unnecessary depth. For example, if the user’s environment has
six plugins installed that each provide a Watershed segmentation,
we could display a Layers -> Generate -> Segmentation -> Watershed
submenu. If the user has just one Watershed segmentation plugin
installed, this submenu would not appear. This would require very careful
design to ensure the user still knows what to expect when they load up
the Viewer.
Alternatives#
The main alternative is the proposed Tools menu from npe2 #161.
This is a single top level menu containing the same submenus as our proposed list, but organized roughly in order of when actions may be performed in a standard image processing workflow.
General feedback from the community and the core developers is that this menu structure, while mostly containing individual submenus that make sense:
is too long and therefore difficult to parse at a glance
does not give the user a good indication of what inputs an action takes and what its output will be
is not semantically structured and is rather just a one stop shop for “plugin stuff”
will be difficult to extend further in meaningful ways as we develop more complex viewer interactions and plugin contributions e.g. multi canvas
Discussion#
May 8 2022: npe2 #160 is opened and merged during core dev hackathon. Allows arbitrary menu locations in npe2 to support plugins contributing to other plugins, etc. Validation would happen elsewhere.
May 8 2022: npe2 #161 is opened with almost instant approvals. Initial feedback is that it’s difficult for people to know the input/output of menu items, suggests creating a NAP. Complexity arises with desire to declare contributable menus but still allow plugins to contribute to other plugin’s menus.
Jun 2 2022: npe2 #161 After further discussion (on zulip and in PR), this schema is identified as potentialy too limiting and there is mention that #160 may need to be reverted. A NAP is once again suggested as this is an influential decision with lots of opinions.
Jun 13 2022: npe2 #161 is closed and #160 is reverted, with comment for follow up over in the napari repo.
Sep 30 2022: napari #5153 opened with same list as in npe2, minimal discussion and input.
Oct 28 2022: napari #5153 discussion on core devs zulip stream begins. Developers mostly agree on the inidividual menu items but don’t like how deep the
Toolsmenu already is, and the lack of semantic meaning in its structure.
References and Footnotes#
All NAPs should be declared as dedicated to the public domain with the CC0
license [1], as in Copyright, below, with attribution encouraged with
CC0+BY [2].
Copyright#
This document is dedicated to the public domain with the Creative Commons CC0 license [1]. Attribution to this source is encouraged where appropriate, as per CC0+BY [2].