Items

options.items
- name
- callback
- className
- icon
- disabled
- visible
- type
- events
- value
- selected
- radio
- options
- height
- items
- accesskey
- dataAttr

The items map contains the commands to list in the menu. Each command has a unique key identifying an item object. The value may either be an item (properties explained below), or a string (which will insert a separator, disregarding the string's content). It is also possible to define a seperator the same as an item, and use the type:cm_separator to define it.

var items = {
  firstCommand: itemOptions,
  separator1: "-----",
  separator2: { "type": "cm_separator" },
  command2: itemOptions
}

Since 2.3 it is also possible to use a promise as item, so you can build submenu's based on a snynchronous promis.

Check out the demo using a promise for an example how to use this. The example uses jQuery deferred, but any promise should do. Promised can only be used in combination with the build option.

options.items

name

Specify the human readable name of the command in the menu. This is used as the label for the option.

May be a callback returning a string, so the label can be updated at runtime (e.g. via $.contextMenu('update')). The callback receives the same arguments as icon, and is re-evaluated whenever the menu is created or updated.

name: string or function(opt, $itemElement, itemKey, item)

Example

var items = {
    firstCommand: {
        name: "Copy"
    },
    secondCommand: {
        name: function(opt, $itemElement, itemKey, item){
            // Compute the label dynamically, e.g. based on some external state.
            return isEnabled ? "Disable" : "Enable";
        }
    }
}

isHtmlName

When truthy, the defined name value is HTML.

The value will be rendered using $.html() instead of $.text().

Note: Cannot be used with the accesskey option in the same item.

isHtmlName: boolean

Example

var items = {
    firstCommand: {
        name: "Copy <span style='font-weight: bold'>Text</span>",
        isHtmlName: true
    }
}

callback

Specifies the callback to execute if clicked on

The Callback is executed in the context of the triggering object. The first argument is the key of the command. The second argument is the options object. The Callback may return false to prevent the menu from being hidden.

If no callback and no default callback is specified, the item will not have an action

callback: function(itemKey, opt, originalEvent)

Example

var items = {
    firstCommand: {
        name: "Copy",
        callback: function(itemKey, opt, e){
            // Alert the key of the item and the trigger element's id.
            alert("Clicked on " + itemKey + " on element " + opt.$trigger.id);
             
            // Do not close the menu after clicking an item
            return false;             
        }       
    }
}

className

Specifies additional classNames to add to the menu item. Seperate multiple classes by using spaces.

className: string

Example

var items = {
    firstCommand: {
        name: "Copy",
        className: 'contextmenu-item-custom contextmenu-item-custom__highlight'
    }
}

icon

Specifies the icon class to set for the item.

When using a string icons must be defined in CSS with selectors like .context-menu-item.context-menu-icon-edit, where edit is the icon class specified.

When using a callback you can return a class string to use that as the class on the item. You can also modify the element by using the $itemElement argument.

The callback is invoked every time the menu is shown or updated, not only when it is first built, so that the icon can reflect current state. A returned class string may therefore change between calls, and the previously returned one is removed from the item before the new one is applied.

Anything the callback does to $itemElement itself is not undone that way, so write that part to be idempotent: replacing the item's content (as in the example below) is safe, while adding to it needs a guard so repeated opens do not stack up duplicates. See using your own SVG icons for that pattern.

icon: string or function(opt, $itemElement, itemKey, item)

Example

var items = {
    firstCommand: {
        name: "Copy",
        icon: function(opt, $itemElement, itemKey, item){
            // Set the content to the menu trigger selector and add an bootstrap icon to the item.
            $itemElement.html('<span class="glyphicon glyphicon-star" aria-hidden="true"></span> ' + opt.selector);
            
            // Add the context-menu-icon-updated class to the item
            return 'context-menu-icon-updated';
        }
    },
    secondCommand: {
        name: "Paste",
        icon: "paste" // Class context-menu-icon-paste is used on the menu item.
    }
}

disabled

Specifies if the command is disabled (true) or enabled (false).

May be a callback returning a boolean. The callback is executed in the context of the triggering object (so this inside the function refers to the element the context menu was shown for). The first argument is the key of the command. The second argument is the options object.

The callback is re-evaluated every time the menu is shown, so there is no need to call $.contextMenu('update') from an events.show handler to pick up a state change.

disabled: boolean or function(itemKey, opt)

Example

var items = {
    firstCommand: {
        name: "Copy",
        disabled: function(key, opt){        
            // Disable this item if the menu was triggered on a div
            if(opt.$trigger.nodeName === 'div'){
                return true;
            }            
        }
    }
}

visible

Specifies if the command is visible (true) or not (false).

May be a callback returning a boolean. The callback is executed in the context of the triggering object (so this inside the function refers to the element the context menu was shown for). The first argument is the key of the command. The second argument is the options object.

visible: boolean or function(itemKey, opt)

Example

var items = {
    firstCommand: {
        name: "Copy",
        visible: function(key, opt){        
            // Hide this item if the menu was triggered on a div
            if(opt.$trigger.nodeName === 'div'){
                return false;
            }            
        }
    }
}

type

Specifies the type of the command.

type: null, undefined, text, textarea, checkbox, radio, select, html default: null

Value	Description
`null`, `undefined` , `""`	The command is a simple clickable item.
`"text"`	Makes the command an `<input>` of type `text`. The name followed by the `<input>` are encapsulated in a `<label>`.
`"textarea"`	Makes the command a `<textarea>`. The name followed by the `<input>` are encapsulated in a `<label>`.
`"checkbox"`	Makes the command an `<input>` of type checkbox. The name preceeded by the `<input>` are encapsulated in a `<label>`. The checkbox-element is moved to the icon space
`"radio"`	Makes the command an `<input>` of type radio. The name preceeded by the `<input>` are encapsulated in a `<label>`. The radio-element is moved to the icon space
`"select"`	Makes the command a `<select>`. The name followed by the `<select>` are encapsulated in a `<label>`.
`"html"`	Makes an non-command element. When you select `type: 'html'` add the html to the `html` property. So: `{ item: { type: 'html', html: '<span>html!</span>' } }`. You can also just use the item name with the `isHtmlName` property.

Example

$.contextMenu({
    selector: 'span.context-menu',
        items: {
            name: {
                name: "Text", 
                type: 'text', 
                value: "Hello World", 
                events: {
                    keyup: function(e) {
                        // add some fancy key handling here?
                        window.console && console.log('key: '+ e.keyCode); 
                    }
                }
            },
            sep1: "---------",
            // <input type="checkbox">
            yesno: {
                name: "Boolean", 
                type: 'checkbox', 
                selected: true
            },
            sep2: "---------",
            // <input type="radio">
            radio1: {
                name: "Radio1", 
                type: 'radio', 
                radio: 'radio', 
                value: '1'
            },
            radio2: {
                name: "Radio2", 
                type: 'radio', 
                radio: 'radio', 
                value: '2', 
                selected: true
            },
            sep3: "---------",
            // <select>
            select: {
                name: "Select", 
                type: 'select', 
                options: {1: 'one', 2: 'two', 3: 'three'}, 
                selected: 2
            },
            // <textarea>
            area1: {
                name: "Textarea with height", 
                type: 'textarea', 
                value: "Hello World", 
                height: 40
            },
            area2: {
                name: "Textarea", 
                type: 'textarea', 
                value: "Hello World"
            },
            sep4: "---------",
            key: {
                name: "Something Clickable", 
                callback: $.noop
            }
        }
});

events

Events to register on <input> elements. The contents of the options object are passed to jQuery event.data.

Only used with types text, textarea, radio, checkbox and select.

events: object

Inside a handler:

this is the <input>, <textarea> or <select> element, just like in any other jQuery event handler.
e.data is the options object of the menu the item belongs to, so e.data.$trigger is the element the menu was opened on. This also works for items in a sub-menu, and it always points at the element that opened the currently visible menu, so a single menu definition shared by many triggers still resolves to the right one.
e.data.$menu is the <ul> of the menu the item belongs to.

Example

$.contextMenu({
    selector: 'span.context-menu',
    items: {
        command1: {
            name: "Foobar", 
            type: "text", 
            events: {
                keyup: function(e){
                    alert(e.keyCode);
                    alert(e.data.$trigger.attr("id"));
                }
            } 
        }
    }
});

Example: writing a value back to the trigger

$.contextMenu({
    selector: 'button.context-menu',
    trigger: 'left',
    items: {
        label: {
            name: "Label",
            type: "text",
            events: {
                focusout: function(e){
                    // `this` is the <input>, `e.data.$trigger` is the button
                    e.data.$trigger.text($(this).val());
                }
            }
        }
    }
});

See the renaming the trigger from an input command demo.

value

The value of the <input> element.

Only used with types text, textarea, radio.

value: string

Example

$.contextMenu({
    selector: 'span.context-menu',
    command1: {
        name: "Foobar", 
        type: "text",
        value: "default value"
    }
});

selected

The selected option of a select element and the checked property for checkbox and radio types.

Only used with types select, checkbox, radio.

selected: string or boolean

Value	Description
`boolean`	Use with `checkbox` and `radio` to check.
`string`	Use with `select` to select that option.

Example

$.contextMenu({
    selector: 'span.context-menu',
    items: {
        // <select>
        select: {
            name: "Select", 
            type: 'select', 
            options: {1: 'one', 2: 'two', 3: 'three'}, 
            selected: "2"
        }
    }
});

radio

Specifies the group of the radio elements.

Only used with type radio.

radio: string

Example

$.contextMenu({
    selector: 'span.context-menu',
    items: {
        // <input type="radio">
        radio1: {
            name: "Radio1", 
            type: 'radio', 
            radio: 'radio', 
            value: '1'
        },
        radio2: {
            name: "Radio2", 
            type: 'radio', 
            radio: 'radio', 
            value: '2', 
            selected: true
        }
    }    
});

options

Specifies the <option> elements for the <select> element.

Only used with type select.

options: object

Example

$.contextMenu({
    selector: 'span.context-menu',
    items: {
       // <select>
       select: {
           name: "Select", 
           type: 'select', 
           options: {1: 'one', 2: 'two', 3: 'three'}, 
           selected: "2"
       }
    }    
});

height

The height in pixel <textarea> element. If not specified, the height is defined by CSS.

Only used with type textarea.

height: int

Example

$.contextMenu({
    selector: 'span.context-menu',
    items: {
       // <select>
       myTextarea: {
           name: "Textarea", 
           type: 'textarea', 
           height: 200
       }
    }    
});

items

Commands to show in a sub-menu. You can nest as many as you like.

items: object

Example

$.contextMenu({
    selector: 'span.context-menu',
    items: {
       // <select>
       myItemWithSubmenu: {
           name: "Textarea", 
           {
                items {
                    mySubmenu {
                        name: "Command 1"
                        callback: function(key, opt){ 
                            alert("Clicked on " + key); 
                        }
                    }
                }
           }
       }
    }    
});

accesskey

Character(s) to be used as accesskey.

Considering a b c $.contextMenu will first try to use »a« as the accesskey, if already taken, it'll fall through to »b«. Words are reduced to the first character, so »hello world« is treated as »h w«.

Note: Accesskeys are treated unique throughout one menu. This means an item in a sub-menu can't occupy the same accesskey as an item in the main menu.

accesskey: string

Example

$.contextMenu({
    selector: 'span.context-menu',
    accesskey: 'a'
    callback: function(itemKey, opt){ 
        alert('I pressed a!');
    }
});

dataAttr

Allows to pass data attributes (data-*) that get applied to the menu item. It should be passed as an object of keys and values. Every key of the object is applied.

Keys are converted from camelCase to the dashed form HTML uses, so menuTitle becomes data-menu-title and can be read back with $item.data('menuTitle'). Keys that already use dashes are left alone.

Values are set as attributes, so they are never treated as HTML. Numbers and booleans are converted to their string form, null and undefined values are skipped.

dataAttr: object

Example

var items = {
    firstCommand: {
        name: "Copy",
        dataAttr: {
            menuTitle: "My custom title",
            commandId: 42
        }
    }
}

This renders the item as:

<li class="context-menu-item" data-menu-title="My custom title" data-command-id="42">Copy</li>

The same option is available on the menu itself, where it applies the data attributes to the menu's <ul class="context-menu-list">:

$.contextMenu({
    selector: '.context-menu-one',
    dataAttr: {
        menuTitle: "My custom menu title"
    },
    items: {
        firstCommand: {name: "Copy"}
    }
});