--- currentMenu: options --- # Documentation - [Register new contextMenu](#register-new-contextmenu) - [Options (at registration)](#options-at-registration) - [selector](#selector) - [items](#items) - [appendTo](#appendto) - [trigger](#trigger) - [reposition](#reposition) - [delay](#delay) - [autoHide](#autohide) - [zIndex](#zindex) - [className](#classname) - [classNames](#classnames) - [animation](#animation) - [events](#events) - [position](#position) - [determinePosition](#determineposition) - [callback](#callback) - [build](#build) ## Register new contextMenu To register a new contextMenu: ```javascript $.contextMenu( options ); ``` ## Options (at registration) ### selector The jQuery selector matching the elements to trigger on. This option is mandatory. `selector`: `string` #### Example ```javascript $.contextMenu({ selector: 'span.context-menu' }); ``` ### items Object with [items](docs/items.html) to be listed in contextMenu. See [items](docs/items.html) for a full documentation on how to build your menu items. `items`: `object` Object containing [items](docs/items.html) objects. #### Example ```javascript $.contextMenu({ selector: '.context-menu', items: { copy: { name: "Copy", callback: function(key, opt){ alert("Clicked on " + key); } } } }); ``` ### appendTo Specifies the selctor string or DOMElement the generated menu is to be appended to. `appendTo`: `string` or `DOMElement` default: `document.body` #### Example ```javascript // select the container with a selector $.contextMenu({ selector: 'span.context-menu', appendTo: 'div#context-menus-container' }); // select the container with a dom element var element = document.getElementById('#context-menus-container'); $.contextMenu({ selector: 'span.context-menu', appendTo: element }); ``` ### trigger Specifies what event on the element specified in the [selector](#selector) triggers the contextmenu. `appendTo`: `string` default: `'right'` Value | Description ---- | ---- `right` | Right mouse button `left` | Left mouse button `hover` | Hover the element `none` | No trigger #### Example ```javascript // trigger with left mouse button $.contextMenu({ selector: 'span.context-menu', trigger: 'left' }); // trigger on hover var element = document.getElementById('#context-menus-container'); $.contextMenu({ selector: 'span.context-menu', trigger: 'hover' }); ``` ### reposition Specifies if a menu should be repositioned (`true`) or rebuilt (`false`) if a second [trigger](#trigger) event (like a right click) is performed on the same element (or its children) while the menu is still visible. `reposition`: `boolean` default: `true` Value | Description ---- | ---- `true` | Reposition menu when triggered `false` | Rebuild menu when triggered #### Example ```javascript $.contextMenu({ selector: 'span.context-menu', reposition: false }); ``` ### delay Specifies the time in milliseconds to wait before showing the menu. Only applies to [trigger](#trigger): "hover" `delay`: `int` default: `200` #### Example ```javascript $.contextMenu({ selector: 'span.context-menu', delay: 500 }); ``` ### autoHide Specifies if the menu must be hidden when the mouse pointer is moved out of the [trigger](#trigger) and [menu items](#items). `autoHide`: `boolean` default: `false` Value | Description ---- | ---- `true` | Hide the menu on mouseout `false` | Do not hide the menu on mouseout #### Example ```javascript $.contextMenu({ selector: 'span.context-menu', autoHide: true }); ``` ### zIndex Specifies the offset to add to the calculated zIndex of the [trigger](#trigger) element. Set to `0` to prevent zIndex manipulation. Can be a function that returns an int to calculate the zIndex on build. `zIndex`: `int`|`function` default: `1` #### Example ```javascript $.contextMenu({ selector: 'span.context-menu', zIndex: 10 }); $.contextMenu({ selector: 'span.context-menu', zIndex: function($trigger, opt){ return 120; }); ``` ### className Specifies additional classNames to add to the menu element. Seperate multiple classes by using spaces. `className`: `string` #### Example ```javascript $.contextMenu({ selector: 'span.context-menu', className: 'contextmenu-custom contextmenu-custom__highlight' }); ``` ### classNames Specifies the base class names of the contextmenu elements. This can be used to change the class names of some classes that might conflict with frameworks like Bootstrap. `classNames`: `object` ```javascript // Classname configuration to be able avoid conflicts in frameworks var options = { classNames : { hover: 'hover', // Item hover disabled: 'disabled', // Item disabled visible: 'visible', // Item visible notSelectable: 'not-selectable', // Item not selectable icon: 'context-menu-icon', // Base icon class iconEdit: 'context-menu-icon-edit', iconCut: 'context-menu-icon-cut', iconCopy: 'context-menu-icon-copy', iconPaste: 'context-menu-icon-paste', iconDelete: 'context-menu-icon-delete', iconAdd: 'context-menu-icon-add', iconQuit: 'context-menu-icon-quit' } } ``` ### animation Animation properties take effect on showing and hiding the menu. Duration specifies the duration of the animation in milliseconds. `show` and `hide` specify [jQuery methods](http://api.jquery.com/category/effects/) to show and hide elements. `animation`: `object` default: `{duration: 500, show: 'slideDown', hide: 'slideUp'}` #### Example ```javascript $.contextMenu({ selector: 'span.context-menu', animation: `{duration: 250, show: 'fadeIn', hide: 'faseOut'}` }); ``` ### events The `show` and `hide` events are triggered *before* the menu is shown or hidden. The event handlers are executed in the context of the triggering object. This will thus reference the jQuery handle of the [trigger](#trigger) object. A reference to the current options object is passed, the options object is a collection of current options and references to the DOM nodes of the menu. The event handlers may return `false` to prevent the `show` or `hide` process. `events`: `object` Value | Description ---- | ---- `events.show` | Called before show of the contextmenu `events.hide` | Called before hide of the contextmenu #### Example ```javascript $.contextMenu({ selector: 'span.context-menu', events: { show : function(options){ // Add class to the menu this.addClass('currently-showing-menu'); // Show an alert with the selector of the menu if( confirm('Open menu with selector ' + opt.selector + '?') === true ){ return true; } else { // Prevent the menu to be shown. return false; } }, show : function(options){ if( confirm('Hide menu with selector ' + opt.selector + '?') === true ){ return true; } else { // Prevent the menu to be hidden. return false; } } }); ``` ### position Callback to overide how the position the context menu is de. The function is executed in the context of the trigger object. The first argument is the `$menu` jQuery object, which is the menu element. The second and third arguments are `x` and `y` coordinates provided by the `show` event. The `x` and `y` may either be integers denoting the offset from the top left corner, `undefined`, or the string `"maintain"`. If the string `"maintain"` is provided, the current position of the `$menu` must be used. If the coordinates are `undefined`, appropriate coordinates must be determined. An example of how this can be achieved is provided with [determinePosition](#determinePosition). `position`: `function(opt.$menu, x, y)` Value `x` or `y` | Description ---- | ---- `int` | Offset in pixels from top-left of trigger element. `"maintain"` | Maintain current `x` or `y` coordinate `undefined` | Unknown, [determinePosition](#determinePosition) is called. #### Example ```javascript $.contextMenu({ selector: 'span.context-menu', position: function(opt, x, y){ opt.$menu.css({top: 123, left: 123}); } }); ``` ### determinePosition Determine the position of the menu in respect to the given [trigger](#trigger) object, this function is called when there is no `x` and `y` set on the [position](#position) call. `determinePosition`: `function(opt.$menu)` #### Example ```javascript $.contextMenu({ selector: 'span.context-menu', determinePosition: function($menu){ // Position using jQuery.ui.position // http://api.jqueryui.com/position/ $menu.css('display', 'block') .position({ my: "center top", at: "center bottom", of: this, offset: "0 5"}) .css('display', 'none'); } }); ``` ### callback Specifies the default callback to be used in case an [item](#items) does not expose its own callback. The default callback behaves just like item.callback. `callback`: `function(itemKey, opt)` #### Example ```javascript $.contextMenu({ selector: 'span.context-menu', callback: function(itemKey, opt){ // Alert the key of the item and the trigger element's id. alert("Clicked on " + itemKey + " on element " + opt.$trigger.attr("id")); // Do not close the menu after clicking an item return false; } }); ``` ### build The callback is executed with two arguments given: the jQuery reference to the triggering element and the original contextemnu event. It is executed without context (so this won't refer to anything useful). If the build callback is found at registration, the menu is not built right away. The menu creation is delayed to the point where the menu is actually called to show. Dynamic menus don't stay in the DOM. After a menu created with build is hidden, its DOM-footprint is destroyed. With build, only the options [selector](#selector) and [trigger](#trigger) may be specified in the [options](#options-at-registration) object. All other options need to be returned from the build callback. the build callback may return a boolean false to signal contextMenu to not display a context menu `build`: `function($triggerElement, event)` #### Example ```javascript $.contextMenu({ selector: 'span.context-menu', build: function($triggerElement, e){ return { callback: function(){}, items: { menuItem: {name: "My on demand menu item"} } }; } }); ```