Menu Button Plugins

It is a special type of PopUpButtonPlugin that implements a menu. The menu options are specified by overriding the async getMenu() method.

import {
    MenuButtonPlugin,
    PaellaCorePlugins
} from 'paella-core';

export default class MyMenuButtonPlugin extends MenuButtonPlugin {
    getPluginModuleInstance() {
        return PaellaCorePlugins.Get();
    }

    get name() {
        return super.name || "es.upv.paella.myMenuButtonPlugin";
    }

    async getMenu() {
        const items = [
            { id: 0, title: "Option 1" },
            { id: 1, title: "Option 2" },
            { id: 2, title: "Option 3" },
            { id: 3, title: "Option 4" },
            { id: 4, title: "Option 5" }
        ]
        return items;
    }
}

NOTE: consider to implement your own PluginModule to group your plugins.

Each menu item returned in the async getMenu() method can contain the following elements:

• id (required): This is a unique identifier of the menu item that cannot be repeated in any of the other items. The data type is indifferent.
• title: is the text that will be displayed in the button and in the accessibility options.
• icon: the icon of the menu item, which must be a vector image in SVG format.

To load the SVG icons, it is possible to use a Paella Player utility that loads the icon and makes it ready to be added as a DOM element:

import { utils } from '@asicupv/paella-core';

...

const icon = await utils.loadSvgIcon(iconPath);

Button action

When the user selects a menu item the plugin is informed by calling the itemSelected(itemData,menuItems) method, which we can override to handle the action:

...
  itemSelected(itemData,menuItems) {
    console.log(`Item selected with identifier ${itemData.id}`);
  }
}

The itemData argument is the menu item that was returned in the async getMenu() function. The menuItems argument is the menu items, with their current settings.

When a menu item is selected, it will remain open. To close it, the closeMenu() function must be called explicitly:

...
  itemSelected(itemData,menuItems) {
    console.log(`Item selected with identifier ${itemData.id}`);
    this.closeMenu();
  }
}

Menu title

You can add a title to the menu options using the menuTitle configuration attribute, within the plugin configuration options:

{
  "plugins": {
    "myMenuPlugin": {
      "enabled": true,
      "menuTitle": "My custom title"
    }
  }
}

This title is obtained from the read-only property menuTitle, which is defined in the MenuButtonPlugin base class, and gets its value from the configuration. If we want to define a title that cannot be modified by the configuration, it is enough to also define this property in the implementation of our plugin:

export default class MyMenuPlugin extends MenuButtonPlugin {
  ...
  get menuTitle() {
    return "My custom title";
  }
}

We could also use the same technique to define a default title in case a title has not been defined in the configuration:

export default class MyMenuPlugin extends MenuButtonPlugin {
  ...
  get menuTitle() {
    return this.config.menuTitle || "My default title";
  }
}

If you override the menuTitle property, it is possible to return a DOM element instead of text:

export default class MyMenuPlugin extends MenuButtonPlugin {
  ...
  get menuTitle() {
    const myElem = document.createElement('h2');
    myElem.innerText = "My menu";
    return myElem;
  }
}

Menu type

We can create three different types of menus:

• "check": each menu item works like a check box, i.e. clicking on it will check or uncheck it depending on its status.
• "radio": each menu item works like a radio button, i.e. clicking on it will select it, and if another item is selected, it will be deselected.
• "button": each menu item will function as a button, i.e. no menu item is checked or unchecked in any case.

For all the above types of button the itemSelected(itemData,menuItems) function will be called. The selected items will include the selected: true attribute in the itemData parameter, and in the corresponding element of the menuItems array.

To determine the menu type, we override the buttonType() method, returning the string "check", "radio" or "button":

buttonType() {
  return "radio";
}

Auto close pop up

By selecting a menu item, it is possible to configure the behaviour of the pop-up to stay open or close. This behaviour can be set in the plugin configuration.

The default behaviour depends on the type of the menu button plugin.

• If the button type is radio button: the pop up will not be closed.
• If the button type is check or button: the pop up will be closed.

In addition to this, in case the button is in a pop up (see documentation on ButtonGroupPlugin), it is also possible to configure whether we want the parent container to close or remain open.

These default behaviours can be modified using the closeOnSelect and closeParentPopUp properties.`:

{
  "es.upv.paella.myMenuButtonPlugin": {
    "enabled": true,
    "closeOnSelect": true
  }
}