jquery.ui-contextmenu

A jQuery plugin that provides a context menu (based on the standard jQueryUI menu widget).

Define menus from <ul> element or definition list (i.e. [{title: "Paste", cmd: "paste"}, ...]).
Themable using jQuery ThemeRoller.
Supports delegation (i.e. can be bound to elements that don't exist at the time the context menu is initialized).
Exposes events from jQueryUI menu: blur, create, focus, select.
Optional support for touch devices.

Status

Beta. Please report issues.

Latest release is available for download at The jQuery Plugin Registry.

Demo

Live demo page.

Example

Say we have some HTML elements that we want to attach a popup menu to:

<div id="container">
    <div class="hasmenu">AAA</div>
    <div class="hasmenu">BBB</div>
    <div class="hasmenu">CCC</div>
</div>

now we can enable a context menu like so:

$("#container").contextmenu({
	delegate: ".hasmenu",
	menu: [
		{title: "Copy", cmd: "copy", uiIcon: "ui-icon-copy"},
		{title: "Paste", cmd: "paste", disabled: true },
		{title: "----"},
		{title: "More", children: [
			{title: "Sub 1", cmd: "sub1"},
			{title: "Sub 2", cmd: "sub1"}
			]}
		],
	select: function(event, ui) {
		var menuId = ui.item.find(">a").attr("href");
		alert("select " + menuId + " on " + $(event.relatedTarget).text());
	}
});

To attach menus to all elements on the page that have class="hasmenu", we use document as context:

$(document).contextmenu({
    delegate: ".hasmenu",
    ...
});

Initialize menu from an existing `<ul>` element

In this case menu must point to the markup:

$(document).contextmenu({
    delegate: ".hasmenu",
    menu: "#options",
    select: function(event, ui) {
    	...
    }
});

We also have to provide some HTML markup that defines the context menu structure (see jQueryUI menu for details):

<ul id="options" class="ui-helper-hidden">
    <li><a href="#copy"><span class="ui-icon ui-icon-copy"></span>Copy</a>
    <li class="ui-state-disabled"><a href="#paste">Paste</a>
    <li>----
    <li><a>More</a>
        <ul>
            <li><a href="#sub1">Sub 1</a>
            <li><a href="#sub2">Sub 2</a>
        </ul>
</ul>

API documentation

Options

delegate

Type: String
A selector to filter the elements that trigger the context menu.

hide

Type: Boolean | Number | String | Object, default: { effect: "fadeOut", duration: "fast"}
Effect applied when hiding the popup.
See sample for possible option values.

ignoreParentSelect

Type: Boolean, default: true
If true, a click on a menu item that contains a sub-menu, will not trigger the select event.

menu

Type: Object[] | String | jQuery
jQuery object or selector of HTML markup that defines the context menu structure (see jQueryUI menu for details).

If an array of objects is passed, it will be used to generate
such markup on the fly.

preventSelect

Type: Boolean, default: false
Prevent accidental text selection of potential menu targets on doubleclick or drag.

show

Type: Boolean | Number | String | Object, default: { effect: "slideDown", duration: "slow"}
Effect applied when showing the popup.
See sample for possible option values.

taphold

Type: Boolean, default: false
Open menu on taphold events, which is especially useful for touch devices (but may require external plugins to generate taphold events).

Methods

close(): Close context menu if open.
Call like $(...).contextmenu("close");.
enableEntry(cmd, flag): Enable or disable the entry. `flag` defaults to `true`
Call like $(...).contextmenu("enableEntry", "paste", false);.
open(target): Open context menu on a specific target (target must match the options.delegate filter).
Call like $(...).contextmenu("open", target);.
replaceMenu(menu): Replace the whole menu definition.
Call like $(...).contextmenu("replaceMenu", "#menu2");.
**TODO**: this is currently not implemented for <ul> definition mode.
setEntry(cmd, data): Redefine menu entry (title or all of it).
`data` may be a title string or a menu definition object.
Call like $(...).contextmenu("setEntry", "paste", "Paste link");.
showEntry(cmd, flag): Show or hide the entry. `flag` defaults to `true`
Call like $(...).contextmenu("showEntry", "paste", false);.

Events

jquery-contextmenu exposes events from jQueryUI menu: blur, create, focus, select. However, since the event.target parameter contains the menu item, we additionally pass the element that was right-clicked in event.relatedTarget.

Events may be handled by defining a handler option:

$("#container").contextmenu({
    [...]
    select: function(event, ui) {
        var menuId = ui.item.find(">a").attr("href"),
            target = event.relatedTarget;
        alert("select " + menuId + " on " + $(target).text());
    }
});

Alternatively a handler may be bound, so this is equivalent:

$("#container").bind("contextmenuselect", function(event, ui) {
    var menuId = ui.item.find(">a").attr("href"),
        target = event.relatedTarget;
    alert("select " + menuId + " on " + $(target).text());
}

beforeOpen(event): Triggered just before the popup menu is opened.
Return false to prevent opening.
This is also a good place to modify the menu (i.e. hiding, disabling, or renaming entries, or replace the menu altogether).
blur(event, ui): Triggered when the menu loses focus.
close(event): Triggered when the menu is closed.
create(event, ui): Triggered when the menu is created.
focus(event, ui): Triggered when a menu gains focus or when any menu item is activated.
init(event): Triggered when the contextmenu widget is initialized.
open(event): Triggered when the menu is opened.
select(event, ui): Triggered when a menu item is selected.
Return false to prevent closing the menu.

jdaltemus / jquery-ui-contextmenu Goto Github PK