Improved documention

Author: mar10

README.md

@@ -9,37 +9,47 @@ A jQuery plugin that provides a context menu (based on the standard [jQueryUI me
 
 
 ## Status
-Pre-alpha *not* ready for production
+Beta: *not* ready for production.
+
 
 ## Demo
 
-[Sample page](http://mar10.github.com/jquery-contextmenu/sample-widget.html)
+[Live demo page](http://mar10.github.com/jquery-contextmenu/sample-widget.html)
 
 
 ## Example
 
 Say we have some HTML elements that we want to attach a popup menu to:
 
 ```html
-    <div id="container">
-        <div class="hasmenu">AAA</div>
-        <div class="hasmenu">BBB</div>
-        <div class="hasmenu">CCC</div>
-    </div>
+<div id="container">
+    <div class="hasmenu">AAA</div>
+    <div class="hasmenu">BBB</div>
+    <div class="hasmenu">CCC</div>
+</div>
 ```
 
 
 now we can enable a contextmenu like so:
 
 ```js
 $("#container").contextmenu({
-        delegate : ".hasmenu",
-        menu : "#options",
-        select : function(event, ui) {
-            var menuId = ui.item.find(">a").attr("href");
-            alert("select " + menuId);
-        }
-    });
+    delegate: ".hasmenu",
+    menu: "#options",
+    select: function(event, ui) {
+        var menuId = ui.item.find(">a").attr("href"),
+            target = event.relatedTarget;
+        alert("select " + menuId + " on " + $(target).text());
+    }
+});
+```
+
+To apply the selector globally, pass `document` as context:
+
+```js
+$(document).contextmenu({
+    delegate: ".hasmenu",
+    [...]
 });
 ```
 
@@ -61,4 +71,88 @@ structure (see [jQueryUI menu] for details):
 ```
 
 
+## API documentation
+### Options
+<dl>
+<dt>delegate</dt>
+<dd>
+    `{String}` jQuery selector describing the elements that trigger the context menu.    
+</dd>
+<dt>menu</dt>
+<dd>
+    `{String | jQuery | function}` jQuery object or selector (or function returning such) describing the menu definition.    
+</dd>
+</dl>
+
+
+### Methods
+<dl>
+<dt>open(target)</dt>
+<dd>
+    Open context menu on a specific target (must match options.delegate).
+</dd>
+</dl>
+
+
+### 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:
+```js
+$("#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 equivaent:
+```js
+$("#container").bind("contextmenuselect", function(event, ui) {
+    var menuId = ui.item.find(">a").attr("href"),
+        target = event.relatedTarget;
+    alert("select " + menuId + " on " + $(target).text());
+}
+```
+
+<dl>
+<dt>beforeopen(event)</dt>
+<dd>
+    Menu about to open; return `false` to prevent opening.
+</dd>
+<dt>blur(event, ui)</dt>
+<dd>
+    menu option lost focus
+</dd>
+<dt>close(event, ui)</dt>
+<dd>
+    menu was closed
+</dd>
+<dt>create(event, ui)</dt>
+<dd>
+    menu was initialized
+</dd>
+<dt>focus(event, ui)</dt>
+<dd>
+    menu option got focus
+</dd>
+<dt>init(event, ui)</dt>
+<dd>
+    ui-contextmenu was initialized
+</dd>
+<dt>open(event, ui)</dt>
+<dd>
+    menu was opened
+</dd>
+<dt>select(event, ui)</dt>
+<dd>
+     menu option was selected; return `false` to prevent closing.
+</dd>
+</dl>
+
 [jQueryUI menu]: http://jqueryui.com/menu/

jquery.contextmenu.js

@@ -15,11 +15,10 @@
 		return $menu.data("ui-menu") || $menu.data("menu");
 	}
 	$.widget("ui.contextmenu", {
-		version: "0.0.1pre",
+		version: "0.1.0",
 		options: {
 			delegate: "[data-menu]",  // selector
 			menu: null,      // selector or jQuery or a function returning such
-//			preventBuiltinMenu: true,
 			// Events:
 			beforeopen: $.noop, // menu about to open; return `false` to prevent opening
 			blur: $.noop,       // menu option lost focus
@@ -32,11 +31,6 @@
 		},
 		_create: function () {
 		    this.element.delegate(this.options.delegate, "contextmenu.contextmenu", $.proxy(this._openMenu, this));
-//		    if(this.options.preventBuiltinMenu){
-//		        this.element.delegate(this.options.delegate, "contextmenu.contextmenu", function(event){
-//		            return false;
-//		        });
-//		    }
 			this._trigger("init");
 		},
 		/** Return menu jQuery object. */
@@ -78,7 +72,7 @@
 					create: $.proxy(this.options.create, this),
 					focus: $.proxy(this.options.focus, this),
 					select: function(event, ui){
-//					    // Also pass the target that the menu was triggered on:
+					    // Also pass the target that the menu was triggered on:
 					    event.relatedTarget = openEvent.target;
 						if( self._trigger.call(self, "select", event, ui) !== false ){
 							self._closeMenu.call(self);