Skip to content

cbroeren/ember-context-menu

Repository files navigation

ember-context-menu

npm version Build Status Ember Observer Score Code Climate

An ember-cli addon to add any right-click-menu to your components. Try it here

Compatibility

  • Ember.js v3.16 or above
  • Ember CLI v2.13 or above
  • Node.js v10 or above

Installation

In your application's directory:

$ ember install ember-context-menu

In your application.hbs add the following:

{{context-menu}}

WARNING: You need to add this to make the context-menu work, and should add it just once in your application.

Usage

Using the mixin

This mixin is designed to add a context-menu to any component. Add it to your component like this:

import Component from '@ember/component';
import contextMenuMixin from 'ember-context-menu';

export default Component.extend(contextMenuMixin, {
  // your component properties
  
  _contextMenu(e) {
    // do anything before triggering the context-menu
  }
});

Context items

Your component needs at least an array of contextItems, which should have a label and an action.

import Component from '@ember/component';

export default Component.extend(contextMenuMixin, {
  contextItems: [
    {
      label: 'do something',
      action(selection, details, event) { /* do something */ }
    }
  ]
});

Label icons

🚫 (Temporary removed from 0.2.0, back in 0.3.2)

You can optionally set an icon to show in front of the label. Just give the name of the icon.

  contextItems: [
    {
      label: 'do something',
      icon: 'search',
      action() { /* do something */ }
    }
  ]

The icons that you can use are the one from font-awesome. See http://fontawesome.io/icons/ for the icons to use. Special thanks to the ember-font-awesome addon.

Sub actions

You can add as many sub-actions as you like, but keep in mind it could blow out of your screen ;-)

  contextItems: [
    {
      label: 'multiple actions',
      subActions: [
        {
          label: 'sub action 1',
          action() { /* do something */ }
        }
      ]
    }
  ]

Selection

This context-menu can even be used in case you have to pass an item to your action. You should add it as the contextSelection. This could be one or multiple items.

  contextItems: [
    {
      label: 'do something',
      action(selection) { /* do something with the selection */ }
    }
  ],
  
  contextSelection: { foo: 'bar' }

When it's an array of multiple items, the context-menu will show the amount of items you pass to the action.

Details

If you want to pass some more details to your action, you can set is as the contextDetails. It will be passed to the action as the second argument.

  contextItems: [
    {
      label: 'do something',
      action(selection, details) { /* do something */ }
    }
  ],
  
  contextDetails: { foo: 'bar' }

Disabled actions

When your item has no action and no sub-actions, it will be disabled by default. Also you could disable it by yourself to add the disabled property. This could be either a boolean or a function which gets the selection.

  contextItems: [
    {
      label: 'foo',
      disabled: true
      action() { /* do nothing */ }
    },
    {
      label: 'bar',
      disabled(selection) {
        /* return disabled depending on selection */
      },
      action() { /* do something */ }
    }
  ]

Custom styling

The addon has some predefined styling to just get a quick start. You are able to change the styling of the complete menu by overwriting the styling for the following classes:

  • context-menu
  • context-menu--sub
  • context-menu__item
  • context-menu__item--disabled
  • context-menu__item--parent
  • context-menu__item__label

(Set up by the BEM convention)

Example screenshot Example screenshot with multiple selection

Testing

Test helpers are provided to make it easier to trigger the context menu to open.

import { triggerContextMenu } from 'ember-context-menu/test-support';

triggerContextMenu('.my-class-selector');

Special thanks to @Fabriquartz (Fabriquartz.com)

Contributing

See the Contributing guide for details.

License

This project is licensed under the MIT License.