Logo
doctype [?]
[strict] [loose] [none]

jQuery ContextMenu Plugin

Documentation

The date.js library extends the built-in Date object in javascript by adding class methods and instance methods. No global identifiers are used, so the global namespace stays clean. The goal of the library is to provide additional features for Date objects. The available methods are explained in detail below.

Usage:

$(function() {
  $(".context").contextMenu( [menu] , {options} );
});

Please see the examples!

Menu Array Structure

A menu structure is an Array of objects that define the content and functionality of the menu.

[
  // Key = Option Content, Value = function to execute when option is clicked
  { 'Option Content' : function(menuItemClicked,menuObject) { } } ,

  // A constant to represent a separator item
  $.contextMenu.separator,

  // A more complex option with each option declared explicitly
  // Key = Option Content, Value = Object defining properties
  { 'Advanced Option' : 
    {
      // All attributes are optional

      // The function to be executed when the option is clicked.
      // Arguments passed to this function are:
      //   menuItemClicked - A reference to the DIV containing the option clicked
      //   menuObject - A reference to the contextMenu object
      // Return false to not close the menu when the option is clicked.
      //   Return anything else (or nothing) for normal behavior
      onclick: function(menuItemClicked,menuObject) { },

      // An additional class name to apply to the option
      className: 'name',

      // The class name to apply to the option when it is hovered over
      hoverClassName: 'name',

      // The background-image to use for this icon.
	  // If a theme doesn't support background images, it won't be displayed.
	  // A theme's CSS should explicitly take this into account.
      icon: 'image.gif',

      // Set to true to disable an option. 
      disabled: false,

      // Title attribute text to show when the mouse is over an option 
      title: 'Title Text',

      // Function to call when this option is hovered over.
      // Arguments passed to this function are:
      //   className - The class name (string) that is defined in the options 
	  //               to be applied for hover
      hoverItem: function(className) { },

      // Function to call when this option is no longer hovered over.
      // Arguments passed to this function are:
      //   className - The class name (string) that is defined in the options 
	  //               to be removed
      hoverItemOut: function(className) { }
	}
  }
]

Options

A second argument may be passed to the contextMenu() call. It is a javascript Object defining options which can override the defaults. All are optional.

The default options are shown in the example below

{
  // true|false to turn the menu shadow on or off
  shadow:true,
  
  // The shadow offset to use for both X and Y. If this is set, it overrides
  // The individual X and Y values
  shadowOffset:0,
  
  // The number of pixels to offset the shadow to the right/downwards 
  // (this can be negative)
  shadowOffsetX:5,
  shadowOffsetY:5,
  
  // The shadow will by default be the size of the menu. These values adjust 
  // that size to make the shadow larger or smaller. The default value here 
  // of -3 looks best.
  shadowWidthAdjust:-3,
  shadowHeightAdjust:-3,
  
  // How transparent the shadow is
  shadowOpacity:.2,
  
  // The class to apply to the created DIV object that will be the shadow
  shadowClass:'context-menu-shadow',
  
  // The color of the shadow
  shadowColor:'black',

  // The number of pixels to move the menu left/down from where the mouse clicked
  offsetX:0,
  offsetY:0,
  
  // The jQuery selector to use to choose which DOM element to attach the menu to
  appendTo:'body',
  
  // The direction (up|down) the menu will display
  direction:'down',
  
  // Keep the menu within the visible area of the screen. If the menu would go 
  // off the left or the bottom, it will be pushed left and/or displayed 
  // upwards rather than downwards.
  constrainToScreen:true,

  // The jQuery transitions to use for showing and hiding the menu
  showTransition:'show',
  hideTransition:'hide',
  
  // The speed to use for transitions - slow/normal/fast/#ms
  showSpeed:'',
  hideSpeed:'',
  
  // Function to run after the show/hide transitions have completed
  showCallback:null,
  hideCallback:null,

  // CSS class names to apply to the generated menu HTML. 
  // See http://www.JavascriptToolbox.com/lib/contextmenu/#themes
  className:'context-menu',
  itemClassName:'context-menu-item',
  itemHoverClassName:'context-menu-item-hover',
  disabledItemClassName:'context-menu-item-disabled',
  disabledItemHoverClassName:'context-menu-item-disabled-hover',
  separatorClassName:'context-menu-separator',
  innerDivClassName:'context-menu-item-inner',
  // The class name prefix to prepend to the theme name for css styling
  themePrefix:'context-menu-theme-',
  
  // Theme name. Included themes are: 'default','xp','vista','osx','human','gloss'
  // Multiple themes may be applied with a comma-separated list.
  theme:'default',

  // A flag to determine if an iframe shim should be used for <=IE6 on Windows
  // This is to prevent selectbox/flash/etc bleed-thru.
  // If animations cause problems in <=IE6 and you don't _need_ an iframe, 
  // set this to false.
  useIframe:/*@cc_on @*//*@if (@_win32) true, @else @*/false,/*@end @*/

  // This is the constructor for the contextMenu object 
  // Arguments:
  //   menu: Either String, Function, or Array
  //         String - a jQuery selector used to get the menu content on the page
  //         Function - Function to run each time menu is displayed. This 
  //                    function should return an Array of menu options
  //         Array - An array of options in the required format
  //   opts: An Object of options, overriding any or all of the options here
  // Returns:
  //    contextMenu object
  create: function(menu,opts) { },

  // Create the iframe object to show behind the menu.
  // Arguments: none
  // Returns: iframe object
  createIframe: function() { } ,

  // Accept an Array representing a menu structure and turn it into HTML
  // Arguments:
  //   menu: The Array of options
  //   cmenu: The contextMenu object
  // Returns:
  //   DOM object containing the html for the menu
  createMenu: function(menu,cmenu) { },

  // Create the DOM object for an individual option, called by createMenu
  // Arguments:
  //   label: The text to display
  //   obj: Either a Function or an Object
  //        Function - runs when the option is clicked
  //        Object - an Option structure as described in Menu Array Structure
  // Returns:
  //    DOM object containing html for a single option
  createMenuItem: function(label,obj) { },

  // Create a separator row
  // Arguments: none
  // Returns:
  //    DOM object containing html for the separator
  createSeparator: function() { },

  // Determine if an individual item is currently disabled. This is called each 
  // time the item is hovered or clicked because the disabled status may change 
  // at any time. You can override this function with app-specific functionality
  // to determine which options should be disabled based on business rules.
  // Arguments:
  //   item: DOM object of the Option being checked
  // Returns:
  //   boolean
  isItemDisabled: function(item) { },

  // Functions to fire on hover over and out
  // no return value
  // Arguments:
  //   className: The hover class to apply or remove
  // Returns:
  //   none
  hoverItem: function(className) { },
  hoverItemOut: function(className) { },

  // Create the shadow DOM object to place behind the menu
  // Arguments:
  //   cmenu: contextMenu object
  // Returns:
  //   DOM object containing html for the shadow
  createShadow: function(cmenu) { },

  // Display the shadow object, given the position of the menu itself.
  // Arguments:
  //   x: The x (left) position of the menu
  //   y: The y (top) position of the menu
  //   e: The event that triggered the context menu
  // Returns:
  //   none
  showShadow: function(x,y,e) { },

  // A hook to call before the menu is shown, in case special processing needs 
  // to be done. Using this you can modify the menu contents, etc on the fly.
  // Arguments:
  //   none
  // Returns:
  //   boolean: false to cancel the default show operation, true to work as normal
  beforeShow: function() { return true; },

  // Make the context menu visible, using specified transitions
  // Arguments:
  //   target: The object that originally caught the contextmenu event
  //   e: The original event
  // Returns:
  //   none
  show: function(target,e) { },

  // Find the position where the menu should appear, given an x,y of the click event.
  // Arguments:
  //   clickX: The x (left) position of the click event
  //   clickY: The y (top) position of the click event
  //   cmenu: The contextMenu object
  //   e: The original event
  // Returns:
  //   An Object specifying the x,y position to show the menu: {'x':x,'y':y}
  getPosition: function(clickX,clickY,cmenu,e) { },

  // Hide the menu
  // Arguments:
  //   none
  // Returns:
  //   none
  hide: function() { }
  
}

Setting Default Options

You can define the default values for any/all options by modifying the plugin namespace itself.

// Turn off shadows for all context menus
$.contextMenu.shadow = false; 

// Set the default theme for all menus to be 'xp'
$.contextMenu.theme = 'xp'; 

These options only apply to conext menus created after these defaults have been defined.