main-menu

Menus

Add a Menu to the main app.

One major concept of the Lumino library on which JupyterLab is built is the notion of Commands as explained in the commands example. One of the possibilities offered to the user to trigger that command is to call it from a menu item.

Since JupyterLab 3.1, the preferred way to define menus is through a description stored in plugin settings file. On the Typescript code, you only need to define the commands to be displayed in the menu(s). The code to add a command will first be described.

// src/index.ts#L17-L32

const { commands } = app;

// Add a command
const command = 'jlab-examples:main-menu';
commands.addCommand(command, {
  label: 'Execute jlab-examples:main-menu Command',
  caption: 'Execute jlab-examples:main-menu Command',
  execute: (args: any) => {
    console.log(
      `jlab-examples:main-menu has been called ${args['origin']}.`
    );
    window.alert(
      `jlab-examples:main-menu has been called ${args['origin']}.`
    );
  }
});

Now that the command is defined, you need to add the definition of the menu in the plugin settings file.

Tip: when using the extension template for JupyterLab extension, you can request initial settings to be created.

The creation of a settings file is described in the settings example. Here only the needed keys to add a menu will describe.

// schema/plugin.json#L4-L20

"jupyter.lab.menus": {
  "main": [
    {
      "id": "jp-mainmenu-example-menu",
      "label": "Main Menu Example",
      "rank": 80,
      "items": [
        {
          "command": "jlab-examples:main-menu",
          "args": {
            "origin": "from the menu"
          }
        }
      ]
    }
  ]
},

Main menu can be added and edited through the main property of the special key jupyter.lab.menus. That property accepts a list of menus; each item will have an entry in the main menu bar.

A menu is described by:

• an id: Unique menu identifier
• a label: The text to be displayed in the menu bar
• some items: The commands available under that menu
• a rank: (optional) number to order the menu items in the menu bar

The items are a list of objects with the following attributes:

• type: Type of the item
  • command: (default) If the item triggers a command
  • separator: if the item is a menu separator
  • submenu: if the item is a submenu
• command: (needed for command type item) the unique command id to be trigger by the menu entry
• args: (optional for command item) arguments to be passed to the command
• rank: (optional) number to order the menu entries

The label displayed for a command will be given by the label attribute coded in Typescript; in this example:

// src/index.ts#L22-L22

label: 'Execute jlab-examples:main-menu Command',

To add items to an existing menu, you will need to use the id of the default menu. An example to add an item to the New submenu of the File menu is available in the launcher example.

The list of default menu ids is available in the documentation.

See also the documentation.

WARNING The extension id must contain the package name and the schema file name:

// src/index.ts#L12-L12

id: '@jupyterlab-examples/main-menu:plugin',

• @jupyterlab-examples/main-menu is the package name in package.json file
• :plugin come from the schema file schema/plugin.json

With this extension installed, a new menu Main Menu Example should be present. And when clicking on the menu item jlab-examples:main-menu, the following text should appear in the web browser console.

jlab-examples:main-menu has been called from the menu.

WARNING The schema must be included in the final bundle, and the location of the schema directory needs to be provided to the JupyterLab extension build system.

To achieve this, the package.json must include:

• "schema/*.json" entry in the files section
• schemaDir key with path to the schema directory in the jupyterlab section

// package.json#L16-L20

"files": [
    "lib/**/*.{d.ts,eot,gif,html,jpg,js,js.map,json,png,svg,woff2,ttf}",
    "style/**/*.{css,js,eot,gif,html,jpg,json,png,svg,woff2,ttf}",
    "schema/*.json"
],

// package.json#L94-L98

"jupyterlab": {
    "extension": true,
    "outputDir": "jupyterlab_examples_main_menu/labextension",
    "schemaDir": "schema"
},