🌜
🌞
jquery-contextmenu

jquery-contextmenu

v2.9.2

Management facility for context menus. Developed for a large number of triggering objects. HTML5 Polyfill

npm install jquery-contextmenu

README

jQuery contextMenu plugin & polyfill

Greenkeeper badge

Travis npm npm CDNJS npm

$.contextMenu is a management facility for - you guessed it - context menus. It was designed for an application where there are hundreds of elements that may show a context menu - so intialization speed and memory usage are kept fairly small. It also allows to register context menus without providing actual markup, as $.contextMenu generates DOMElements as needed.

features - demo - documentation

Sauce Test Status

Dependencies

  • jQuery >=1.8.2
  • jQuery UI position (optional but recommended)

Usage

register contextMenu from javascript:

$.contextMenu({
    // define which elements trigger this menu
    selector: ".with-cool-menu",
    // define the elements of the menu
    items: {
        foo: {name: "Foo", callback: function(key, opt){ alert("Foo!"); }},
        bar: {name: "Bar", callback: function(key, opt){ alert("Bar!") }}
    }
    // there's more, have a look at the demos and docs...
});

have a look at the demos.

Version 3.0 beta

Version 3.0 is a restructure of the javascript into something more sane written in ES6. It consolidates all API's so callbacks are better documented and more concise. The basics are still the same, but all callbacks are structured differently.

The goal of this refactor was mostly to make the ContextMenu easier to maintain, and make the API's more consise. It also adds JSdoc comments so the API documentation is generated from the code and it enables code completion.

Check out the 3.x branch, or install with npm install [email protected].

HTML5 Compatibility

Firefox 8 implemented contextmenu using the <menuitem> tags for menu-structure. The specs however state that <command> tags should be used for this purpose. $.contextMenu accepts both.

Firefox 8 does not yet fully implement the contextmenu specification (Ticket #617528). The elements a, button, input and option usable as commands are being ignored altogether. It also doesn't (optically) distinguish between checkbox/radio and regular commands (Bug #705292).

Note: While the specs note <option>s to be renderd as regular commands, $.contextMenu will render an actual <select>. import contextMenu from HTML5 <menu>:

$.contextMenu("html5");

Interaction Principles

You're (obviously) able to use the context menu with your mouse. Once it is opened, you can also use the keyboard to (fully) navigate it.

  • ↑ (up) previous item in list, will skip disabled elements and wrap around
  • ↓ (down) next item in, will skip disabled elements and wrap around
  • → (right) dive into sub-menu
  • ← (left) rise from sub-menu
  • ↵ (return) invoke command
  • ⇥ (tab) next item or input element, will skip disabled elements and wrap around
  • ⇪ ⇥ (shift tab) previous item or input element, will skip disabled elements and wrap around
  • ⎋ (escape) close menu
  • ⌴ (space) captured and ignore to avoid page scrolling (for consistency with native menus)
  • ⇞ (page up) captured and ignore to avoid page scrolling (for consistency with native menus)
  • ⇟ (page down) captured and ignore to avoid page scrolling (for consistency with native menus)
  • ↖ (home) first item in list, will skip disabled elements
  • ↘ (end) last item in list, will skip disabled elements

Besides the obvious, browser also react to alphanumeric key strokes. Hitting r in a context menu will make Firefox (8) reload the page immediately. Chrome selects the option to see infos on the page, Safari selects the option to print the document. Awesome, right? Until trying the same on Windows I did not realize that the browsers were using the access-key for this. I would've preferred typing the first character of something, say "s" for "save" and then iterate through all the commands beginning with s. But that's me - what do I know about UX? Anyways, $.contextMenu now also supports accesskey handling.

Authors

License

$.contextMenu is published under the MIT license

Special thanks

Font-Awesome icons used from encharm/Font-Awesome-SVG-PNG.

SWIS :heart: Open Source

SWIS is a web agency from Leiden, the Netherlands. We love working with open source software.

Release Notes

3.0.0-beta.2
By Björn Brala • Published on March 16, 2018

Fixed

  • The contextmenu now checks visible on items once instead of twice. Fixes issue 612.
  • Font awesome li height is now consistent again. Fixes issue Fixes issue 612.
3.0.0-beta.1
By Björn Brala • Published on December 31, 2017

Migrating

  • To migrate, you only need to change all callback functions to the new arguments (icon, build, visible, disabled, item callback and global item callback). Also if you listen to contextmenu events, please check if you still get the correct data.

Changed

  • Restructured the code to use Webpack with Babel. Build the code with yarn run webpack.
  • Changed linting to ESLint.
  • Moved to BrowserStack for browser testing.
  • Added JSDoc for generated API documentation.
  • Added 3.x documentation on GitHub pages.
  • The previous opt and root arguments are now described as currentMenuData and rootMenuData, which are documented in ContextMenuData.
  • Defined a few callback types to illustrate the arguments with which they are called.
  • Build callback ContextMenuBuildCallback is now function(e, $currentTrigger).
  • Icon callback ContextMenuIconCallback is now function(e, $item, key, item, currentMenuData, rootMenuData).
  • The visibile, disabled, global callback and item callback ContextMenuItemCallback is now function(e, key, currentMenuData, rootMenuData).
  • If you define custom menu item types in $.contextMenu.types they get called as ContextMenuItemTypeCallback with function(e, item, currentMenuData, rootMenuData).
  • All events should always include event data containing the ContextMenuData as described in ContextMenuEvent. So if you listen to contextmenu events you should always have the data available.

Fixed

  • Add options argument to events.activates. (Issue #580)
  • Fix support for $(element).contextMenu('update') which was broken.
  • Fixed bug in checking visibility of items for menu visibility. If a menu item was defined as { item: { visible: false } } it would not stop the menu from showing.
2.9.2
By Björn Brala • Published on May 13, 2020
  • Fix reflow when adding click layer to page (fixed #721, thanks @Rhain)
2.9.1
By Björn Brala • Published on May 6, 2020

2.9.1

  • Fix error when closing the menu by clicking on the page without any element under that click point. (fixes #717)
  • Upgrades dependencies
2.9.0
By Björn Brala • Published on October 13, 2019

2.9.0

Added

  • Added dataAttr option to add arbitrary data attributes to menu items.

Changed

  • Updated dev dependencies.
2.8.1
By Björn Brala • Published on October 5, 2019

Fixed

  • Added FontAwesome fab class to known classes.

Documentation

  • Updated documentation for callback (thanks @arashdalir)
2.8.0
By Björn Brala • Published on January 16, 2019

Added

  • Added support for events.preShow so you can enable default browser menu if needed (thanks @terwarf)
2.7.1
By Björn Brala • Published on October 2, 2018

Fixed

  • A context menu appears outside the screen Under certain conditions (thanks @so-susa)
  • No font-awesome icons visible in submenu (Issue #659) thanks @betafritz and @klues
2.7.0
By Björn Brala • Published on July 12, 2018

Added

Documentation

  • Add getting started to the documentation.
  • Fixed typo in documentation which breaks the callback demo.
  • Fixed typo promis => promise (Issue #633).
  • Fixed arguments for callback option in documentation (Issue #571).
2.6.4
By Björn Brala • Published on March 16, 2018

Fixed

  • events.activated is called without optionsas argument (Issue #580).
  • LayerClick sometimes breaks when the source is not a mouseevent (Issue #132).
  • The contextmenu now checks visible on items once instead of twice. Fixes issue 612.
  • Font awesome li height is now consistent again (Issue #610).

General

License
MIT
Typescript Types
None found
Tree-shakeable
No

Popularity

GitHub Stargazers
2,182
Community Interest
3,075
Number of Forks
761

Maintenance

Commits
10/219/2206
Last Commit
Open Issues
124
Closed Issues
425
Open Pull Requests
10
Closed Pull Requests
67

Versions

Versions Released
10/219/2201
Latest Version Released
May 13, 2020
Current Tags
latest2.9.2
next3.0.0-beta.2

Contributors

bbrala
bbrala
Commits: 385
rodneyrehm
rodneyrehm
Commits: 202
RoachMech
RoachMech
Commits: 15
RareDevil
RareDevil
Commits: 12
nelson6e65
nelson6e65
Commits: 4
kccarter76
kccarter76
Commits: 4
andreasrosdal
andreasrosdal
Commits: 4
rvictory
rvictory
Commits: 3
jayzelenkov
jayzelenkov
Commits: 3
zyuhel
zyuhel
Commits: 3
anseki
anseki
Commits: 3
dtex
dtex
Commits: 3
shayanelhami
shayanelhami
Commits: 3
micnigh
micnigh
Commits: 2
adjohu
adjohu
Commits: 2