Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100755 572 lines (502 sloc) 30.421 kB
391e15b @rodneyrehm documentation
rodneyrehm authored
1 <!DOCTYPE html>
2 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="de" lang="de">
3 <head>
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
4 <meta charset="utf-8" />
5 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
6 <title>jQuery contextMenu Plugin</title>
7 <meta name="description" content="simple contextMenu generator for interactive web applications based on jQuery" />
8
57682c3 @rodneyrehm jQuery 1.7.1, changelog
rodneyrehm authored
9 <script src="jquery-1.7.1.min.js" type="text/javascript"></script>
17cd066 @rodneyrehm prettify, doc structure
rodneyrehm authored
10 <script src="prettify/prettify.js" type="text/javascript"></script>
11 <script src="screen.js" type="text/javascript"></script>
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
12 <link href="screen.css" rel="stylesheet" type="text/css" />
17cd066 @rodneyrehm prettify, doc structure
rodneyrehm authored
13 <link href="prettify/prettify.sunburst.css" rel="stylesheet" type="text/css" />
2c57f49 @rodneyrehm analyticsm, sorry...
rodneyrehm authored
14 <script type="text/javascript">
15
16 var _gaq = _gaq || [];
17 _gaq.push(['_setAccount', 'UA-8922143-3']);
18 _gaq.push(['_trackPageview']);
19
20 (function() {
21 var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
22 ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
23 var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
24 })();
25
26 </script>
391e15b @rodneyrehm documentation
rodneyrehm authored
27 </head>
28 <body>
a9bd1e6 @rodneyrehm github watcher
rodneyrehm authored
29 <a id="github-forkme" href="https://github.com/medialize/jQuery-contextMenu"><img src="http://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub" /></a>
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
30 <div id="container">
a9bd1e6 @rodneyrehm github watcher
rodneyrehm authored
31 <h1><a href="https://github.com/medialize/jQuery-contextMenu">jQuery contextMenu</a></h1>
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
32
33 <ul class="menu">
34 <li><a href="index.html">About</a></li>
35 <li><a href="demo.html">Demo</a></li>
36 <li class="active"><a href="docs.html">Documentation</a></li>
65936cc @rodneyrehm demos
rodneyrehm authored
37 <li><a href="http://rodneyrehm.de/en/">Author</a></li>
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
38 </ul>
39
40 <ul class="toc">
41 <li>
42 <a href="#register">Register new contextMenu</a>
43 <ul>
44 <li><a href="#options">options (at registration)</a></li>
45 <li><a href="#items">options.items</a></li>
46 <li><a href="#opt">opt (options at runtime)</a></li>
3735992 @rodneyrehm docs
rodneyrehm authored
47 <li><a href="#types">Custom Command Types</a></li>
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
48 </ul>
49 </li>
50 <li><a href="#disable-trigger">Disable a contextMenu trigger</a></li>
51 <li><a href="#enable-trigger">Enable a contextMenu trigger</a></li>
52 <li><a href="#show-trigger">Manually show a contextMenu</a></li>
3735992 @rodneyrehm docs
rodneyrehm authored
53 <li><a href="#hide-trigger">Manually hide a contextMenu</a></li>
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
54 <li><a href="#unregister-contextMenu">Unregister contextMenu</a></li>
55 <li><a href="#unregister-all">Unregister all contextMenus</a></li>
56 <li><a href="#helper-import-values">Helper: Import values for &lt;input&gt;</a></li>
57 <li><a href="#helper-export-values">Helper: Export values from &lt;input&gt;</a></li>
58 <li><a href="#events">Events</a></li>
59 <li><a href="#html5-import">HTML5 &lt;menu&gt; import</a></li>
0b762ee @rodneyrehm fixing html5 support detection
rodneyrehm authored
60 <li><a href="#html5-shiv">HTML5 &lt;menu&gt; shiv/polyfill</a></li>
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
61 <li><a href="#ui-position">$.ui.position</a></li>
62 </ul>
391e15b @rodneyrehm documentation
rodneyrehm authored
63
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
64 <h2 id="register">Register new contextMenu</h2>
65 <p>To register a new contextMenu:</p>
17cd066 @rodneyrehm prettify, doc structure
rodneyrehm authored
66 <pre class="prettyprint lang-js">$.contextMenu( options );</pre>
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
67
68 <h3 id="options">options (at registration)</h3>
69
70 <dl>
71 <dt id="options-selector"><em>(string)</em> selector</dt>
72 <dd>
73 <p>No Default Value - specification is Mandatory</p>
74 <p>The selector matching the trigger objects.</p>
75 <p>Example: <code>"span.with-context"</code>.</p>
76 </dd>
77
78 <dt id="options-items"><em>(object)</em> items</dt>
79 <dd>
80 <p>No Default Value - specification is Mandatory</p>
81 <p>Items to be listed in contextMenu. See <a href="#items">Items</a>.</p>
82 <p>Example: <code>{ one: {name: "one", callback: function(key, opt){ alert("Clicked on " + key); } }}</code></p>
83 </dd>
84
85 <dt id="options-appendTo"><em>(selector | DOMElement)</em> appendTo</dt>
86 <dd>
87 <p>default: document.body</p>
88 <p>Specifies the DOMElement the generated menu is to be appended to</p>
89 <p>Example: <code>"#context-menus-container"</code>.</p>
90 </dd>
91
92 <dt id="options-trigger"><em>(string)</em> trigger</dt>
93 <dd>
94 <p>default: <em>"right"</em></p>
95 <p>Specifies the event to show the contextMenu</p>
19f8a9a @rodneyrehm fixing repositioning of open menu (formerly an accidental re-open)
rodneyrehm authored
96 <p>Possible values: "right", "left", "hover", "none"</p>
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
97 </dd>
98
99 <dt id="options-ignoreRightClick"><em>(boolean)</em> ignoreRightClick</dt>
100 <dd>
101 <p>default: <em>false</em></p>
102 <p>Specifies if the regular right click context menu trigger should be ignored. Only applies to "left" and "hover" triggers</p>
103 </dd>
104
105 <dt id="options-delay"><em>(int)</em> delay</dt>
106 <dd>
107 <p>default: <em>200</em></p>
108 <p>Specifies the time in milliseconds to wait before showing the menu. Only applies to <code>trigger: "hover"</code></p>
109 </dd>
110
111 <dt id="options-autohide"><em>(boolean)</em> autoHide</dt>
112 <dd>
113 <p>default: <em>false</em></p>
114 <p>Specifies if the menu must be hidden when the mouse pointer is moved out of the trigger and menu elements</p>
115 </dd>
116
117 <dt id="options-zIndex"><em>(int)</em> zIndex</dt>
118 <dd>
119 <p>default: <em>1</em></p>
120 <p>Specifies the offset to add to the calculated zIndex of the trigger element. Set to <em>0</em> to prevent zIndex manipulation</p>
121 </dd>
122
123 <dt id="options-className"><em>(string)</em> className</dt>
124 <dd>
125 <p>Specifies additional classNames to add to the menu element</p>
126 </dd>
127
128 <dt id="options-animation"><em>(object)</em> animation</dt>
129 <dd>
130 <p>default: <em>{duration: 500, show: "slideDown", hide: "slideUp"}</em></p>
131 <p>
132 animation properties take effect on showing and hiding the menu.
133 <em>duration</em> specifies the duration of the animation in milliseconds.
134 <em>show</em> and <em>hide</em> specify jQuery methods to show and hide elements.
135 </p>
136 <p>Possible show and hide animations: <code>{show: "show", hide: "hide"}</code>, <code>{show: "fadeIn", hide: "fadeOut"}, …</code>
137 </dd>
138
139 <dt id="options-events"><em>(object)</em> events</dt>
140 <dd>
141 <p>The show and hide events are triggered before the menu is shown or hidden.</p>
142 <p>The event handlers are executed in the context of the triggering object. <em>this</em> will thus reference the jQuery handle of the trigger object.</p>
143 <p>A reference to the current <a href="#opt">options</a> object is passed</p>
144 <p>The event handlers may return <em>false</em> to prevent the show or hide process.</p>
145 <p>Example: <code>{show: function(opt){ this.addClass('currently-showing-menu'); alert("Selector: " + opt.selector); }}</code></p>
146 </dd>
147
148 <dt id="options-position"><em>(function)</em> position</dt>
149 <dd>
150 <p>Position the context menu.</p>
151 <p>The function is executed in the context of the trigger object.</p>
152 <p>The first argument ist the <em>$menu</em> jQuery object</p>
153 <p>The second and third arguments are <em>x</em> and <em>y</em> coordinates provided by the showing event</p>
154 <p><em>x</em> and <em>y</em> 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 <em>$menu</em> must be used. If the coordinates are undefined, appropriate coordinates must be determined. An example of how this can be achieved is provided with <a href="#options-determinePosition">determinePosition</a>.</p>
155 <p>Example: <code>{position: function($menu, x, y){$menu.css({top: 123, left: 123});}}</code></p>
156 </dd>
157
158 <dt id="options-determinePosition"><em>(function)</em> determinePosition</dt>
159 <dd>
160 <p>Determine the position of the menu in respect to the given trigger object.</p>
161 <p>Hint: <a href="http://docs.jquery.com/UI/Position">jQuery UI's position()</a> may ease things up.</p>
162 <p>Example: <code>$menu.css('display', 'block').position({ my: "center top", at: "center bottom", of: this, offset: "0 5"}).css('display', 'none');</code></p>
163 </dd>
164
165 <dt id="options-callback"><em>(function)</em> callback</dt>
166 <dd>
167 <p>Specifies the default callback to be used in case an item does not expose its own callback.</p>
168 <p>The default callback behaves just like <a href="#items-callback">item.callback</a>.</p>
6a81a76 @rodneyrehm typo in docs
rodneyrehm authored
169 <p>Example: <code>{callback: callback: function(key, opt){ alert("Clicked on " + key + " on element " + opt.$trigger.attr("id")); }}</code></p>
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
170 </dd>
90e6b35 @rodneyrehm docs for dynamic menus, doc sugar
rodneyrehm authored
171
172 <dt id="options-build"><em>(function)</em> build</dt>
173 <dd>
174 <p>Callback that's supposed to return the <em>options</em> object on demand</p>
33801a4 @rodneyrehm Fixing issue #24 - accessing contextmenu event data in build() callback
rodneyrehm authored
175 <p>The callback is executed with two arguments given: the jQuery reference to the triggering element and the original contextemnu event.
90e6b35 @rodneyrehm docs for dynamic menus, doc sugar
rodneyrehm authored
176 It is executed without context (so this won't refer to anything useful).</p>
177 <p>If the <em>build</em> 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 <em>build</em> is hidden, its DOM-footprint is destroyed.</p>
178 <p>With <em>build</em>, only the options <a href="#options-selector">selector</a> and <a href="#options-selector">ignoreRightClick</a> may be specified in the
6b21e95 @rodneyrehm version bump
rodneyrehm authored
179 options object. All other options need to be returned from the <em>build</em> callback.</p>
180 <p>the <em>build</em> callback may return a boolean <em>false</em> to signal contextMenu to not display a context menu</p>
90e6b35 @rodneyrehm docs for dynamic menus, doc sugar
rodneyrehm authored
181 <pre class="prettyprint lang-js">{selector: ".awesome-menu",
33801a4 @rodneyrehm Fixing issue #24 - accessing contextmenu event data in build() callback
rodneyrehm authored
182 build: function($trigger, e){
90e6b35 @rodneyrehm docs for dynamic menus, doc sugar
rodneyrehm authored
183 return {
184 callback: function(){},
185 items: {
186 foo: {name: "Foo"}
187 }
188 };
189 }};</pre>
190 </dd>
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
191 </dl>
192
193 <h3 id="items">options.items</h3>
194 <p>The <em>items</em> 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).</p>
17cd066 @rodneyrehm prettify, doc structure
rodneyrehm authored
195 <pre class="prettyprint lang-js">var items = {
196 command1: commandOptions,
197 separator1: "-----",
198 command2: commandOptions
391e15b @rodneyrehm documentation
rodneyrehm authored
199 }</pre>
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
200
201 <dl>
202 <dt id="items-name"><em>(string)</em> name</dt>
203 <dd>
204 <p>Specified the human readable name of the command in the menu</p>
205 <p>This is a mandatory property</p>
206 </dd>
391e15b @rodneyrehm documentation
rodneyrehm authored
207
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
208 <dt id="items-callback"><em>(function)</em> callback</dt>
209 <dd>
210 <p>Specifies the callback to execute if clicked on</p>
211 <p>
212 The Callback is executed in the context of the triggering object.
213 The first argument is the <em>key</em> of the command.
214 The second argument is the <a href="#opt">options</a> object.
215 The Callback may return <em>false</em> to prevent the menu from being hidden.
216 </p>
217 <p>Example: <code>{ command1: {name: "Foobar", callback: function(key, opt){ alert("Clicked on " + key + " on element " + opt.$trigger.id); } }}</code></p>
218 <p>If no callback and no <a href="#options-callback">default callback</a> is specified, the item will not have an action</p>
219 </dd>
391e15b @rodneyrehm documentation
rodneyrehm authored
220
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
221 <dt id="items-className"><em>(string)</em> className</dt>
222 <dd>
223 <p>Specifies additional classNames to add to the item element</p>
224 </dd>
225
226 <dt id="items-icon"><em>(string)</em> icon</dt>
227 <dd>
228 <p>Specifies the icon class to set for the item.</p>
229 <p>Icons must be defined in CSS with selectors like <code>.context-menu-item.icon-<em>edit</em></code>, where <em>edit</em> is the icon class.</p>
230 </dd>
231
232 <dt id="items-disabled"><em>(function|boolean)</em> disabled</dt>
233 <dd>
234 <p>Specifies if the command is disabled (<em>true</em>) or enabled (<em>false</em>).</p>
235 <p>
236 May be a callback returning a boolean.
f49180f @rodneyrehm Fixing Issue #16 (again) - disabled callbacks failed for sub-menus
rodneyrehm authored
237 The Callback is executed in the context of the triggering object (so <code>this</code> inside the function refers to the element the context menu was shown for).
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
238 The first argument is the <em>key</em> of the command.
f49180f @rodneyrehm Fixing Issue #16 (again) - disabled callbacks failed for sub-menus
rodneyrehm authored
239 The second argument is the <a href="#opt">options</a> object.
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
240 </p>
241 <p>Example: { command1: {name: "Foobar", callback: function(key, opt){ return true; } }}</p>
242 </dd>
243
244 <dt id="items-type"><em>(string)</em> type</dt>
245 <dd>
246 <p>Specifies the type of the command.</p>
247 <p><em>null</em>, <em>undefined</em> and the <em>empty-string</em> make the command a simple clickable item.</p>
248 <p><em>"text"</em> makes the command an &lt;input&gt; of type text. The name followed by the &lt;input&gt; are encapsulated in a &lt;label&gt;.</p>
249 <p><em>"textarea"</em> makes the command a &lt;textarea&gt;. The name followed by the &lt;input&gt; are encapsulated in a &lt;label&gt;.</p>
250 <p><em>"checkbox"</em> makes the command an &lt;input&gt; of type checkbox. The name preceeded by the &lt;input&gt; are encapsulated in a &lt;label&gt;. The checkbox-element is moved to the icon space</p>
251 <p><em>"radio"</em> makes the command an &lt;input&gt; of type radio. The name preceeded by the &lt;input&gt; are encapsulated in a &lt;label&gt;. The radio-element is moved to the icon space</p>
252 <p><em>"select"</em> makes the command a &lt;select&gt;. The name followed by the &lt;select&gt; are encapsulated in a &lt;label&gt;.</p>
253 <p><em>"html"</em> makes an non-command element.</p>
254 </dd>
255
256 <dt id="items-events"><em>(object)</em> events</dt>
257 <dd>
258 <p>Events to register on &lt;input&gt; elements</p>
259 <p>Only used with <a href="#items-type">types</a> <em>"text"</em>, <em>"textarea"</em>, <em>"radio"</em>, <em>"checkbox"</em> and <em>"select"</em>.</p>
260 <p>Example: { command1: {name: "Foobar", type: "text", events: {keyup: function(e){alert(e.keyCode);}} }}</p>
261 </dd>
391e15b @rodneyrehm documentation
rodneyrehm authored
262
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
263 <dt id="items-value"><em>(string)</em> value</dt>
264 <dd>
265 <p>The value of the &lt;input&gt; element.</p>
266 <p>Only used with <a href="#items-type">types</a> <em>"text"</em>, <em>"textarea"</em> and <em>"radio"</em>.</p>
267 </dd>
391e15b @rodneyrehm documentation
rodneyrehm authored
268
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
269 <dt id="items-selected"><em>(string|boolean)</em> selected</dt>
270 <dd>
271 <p>The selected option of a &lt;select&gt; element and the checked property for <em>"checkbox"</em> and <em>"radio"</em> types.</p>
272 <p>Expecting a boolean when used with <a href="#items-type">types</a> <em>"checkbox"</em> and <em>"radio"</em>.</p>
273 <p>Expecting a string when used with <a href="#items-type">type</a> <em>"select"</em></p>
274 </dd>
391e15b @rodneyrehm documentation
rodneyrehm authored
275
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
276 <dt id="items-radio"><em>(string)</em> radio</dt>
277 <dd>
278 <p>Specifies the group of the radio elements.</p>
279 <p>Only used with <a href="#items-type">type</a> <em>"radio"</em>.</p>
280 </dd>
391e15b @rodneyrehm documentation
rodneyrehm authored
281
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
282 <dt id="items-options"><em>(object)</em> options</dt>
283 <dd>
284 <p>Specifies the &lt;option&gt;s for the &lt;select&gt; element.</p>
285 <p>Only used with <a href="#items-type">type</a> <em>"select"</em>.</p>
286 <p>Example: <code>{name: "select box", selected: "two", options: {one: "red", two: "blue", three: "green"}}</code></p>
287 </dd>
288
289 <dt id="items-height"><em>(int)</em> height</dt>
290 <dd>
291 <p>The height in pixel &lt;textarea&gt; element. If not specified, the height is defined by CSS.</p>
292 <p>Only used with <a href="#items-type">type</a> <em>"textarea"</em>.</p>
293 </dd>
294
295 <dt id="items-items"><em>(object)</em> items</dt>
296 <dd>
297 <p>Commands to show in a sub-menu.</p>
298 </dd>
299
68e5af5 @rodneyrehm accesskeys
rodneyrehm authored
300 <dt id="items-accesskey"><em>(string)</em> accesskey</dt>
301 <dd>
302 <p>Character(s) to be used as accesskey.</p>
303 <p>
304 Considering »a b c« $.contextMenu will first try to use »a« as the accesskey, if already taken, it'll fall through to »b«.
305 Words are reduced to the first character, so »hello world« is treated as »h w«.
306 </p>
307 <p>
308 Note: Accesskeys are treated unique throughout one menu. This means an item in a sub-menu can't
309 occupy the same accesskey as an item in the main menu.
310 </p>
311 </dd>
312
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
313 <dt id="items-node"><em>(jQuery)</em> $node</dt>
314 <dd>
315 <p>Reference to the &lt;li&gt; command element</p>
316 <p>created by contextMenu on registration</p>
317 </dd>
318
319 <dt id="items-input"><em>(jQuery)</em> $input</dt>
320 <dd>
321 <p>Reference to the &lt;input&gt; or &lt;select&gt; of the command element.</p>
322 <p>Only available with <a href="#items-type">type</a> <em>"text"</em>, <em>"textarea"</em>, <em>"checkbox"</em>, <em>"radio"</em> and <em>"select"</em>.</p>
323 <p>created by contextMenu on registration</p>
324 </dd>
325
326 <dt id="items-label"><em>(jQuery)</em> $label</dt>
327 <dd>
328 <p>Reference to the &lt;label&gt; of the command element</p>
329 <p>Only available with <a href="#items-type">type</a> <em>"text"</em>, <em>"textarea"</em>, <em>"checkbox"</em>, <em>"radio"</em> and <em>"select"</em>.</p>
330 <p>created by contextMenu on registration</p>
331 </dd>
332
333 <dt id="items-node"><em>(jQuery)</em> $menu</dt>
334 <dd>
335 <p>Reference to the &lt;ul&gt; sub-menu element</p>
336 <p>created by contextMenu on registration</p>
337 </dd>
338 </dl>
339
340
341 <h3 id="opt">opt (options at runtime)</h3>
342 <p><em>opt</em> is a reference to the <em>options</em> object passed at contextMenu registration</p>
343 <dl>
344 <dt id="opt-trigger"><em>(jQuery)</em> $trigger</dt>
345 <dd>
346 <p>The element triggering the menu</p>
347 </dd>
348
349 <dt id="opt-menu"><em>(jQuery)</em> $menu</dt>
350 <dd>
351 <p>The menu element</p>
352 </dd>
353
354 <dt id="opt-callbacks"><em>(object)</em> callbacks</dt>
355 <dd>
356 <p>Registered callbacks of all commands (including those of sub-menus)</p>
357 </dd>
358
359 <dt id="opt-commands"><em>(object)</em> commands</dt>
360 <dd>
361 <p>Registered commands (including those of sub-menus)</p>
362 </dd>
363
364 <dt id="opt-inputs"><em>(object)</em> inputs</dt>
365 <dd>
366 <p>Registered commands of input-type (including those of sub-menus)</p>
367 <p>Access a specific &lt;input&gt;: <code>opt.inputs[key].$input</code></p>
368 </dd>
369
370 <dt id="opt-hasTypes"><em>(boolean)</em> hasTypes</dt>
371 <dd>
372 <p>flag denoting if the menu contains input elements</p>
373 </dd>
374
375 <dt id="opt-ns"><em>(string)</em> ns</dt>
376 <dd>
377 <p>The namespace (including leading dot) all events for this contextMenu instance were registered under</p>
378 </dd>
379 </dl>
380
3735992 @rodneyrehm docs
rodneyrehm authored
381 <h3 id="types">Custom Command Types</h3>
382 <p>Besides the built-in <a href="#items-type">command types</a> custom handlers can be defined.
383 The command generator must be placed in <code>$.contextMenu.types</code>. It is identified
384 by the key given in that object. The generator function is executed in the context of the
385 new command's &lt;li&gt; within the menu. <code>item</code> is the object passed at creation.
386 Use this to pass values from your definition to the generator. <code>opt</code> is the current
387 menu level, <code>root</code> is the menu's root-level <code>opt</code> (relevant for sub-menus only).
388 </p>
389 <p>
390 A custom command type can be whatever you like it to be, it can behave how ever you want it to behave.
391 Besides the keyboard interaction paradigm (up, down, tab, escape) key-events are passed on to the
f0326ef @rodneyrehm upgrade to jQuery 1.7, using .on() and .off()
rodneyrehm authored
392 &lt;li&gt; which can be accessed via <code>$(this).on('keydown', …);</code>
3735992 @rodneyrehm docs
rodneyrehm authored
393 </p>
394 <p>
395 Note that you'll probably want to disable default action handling (click, pressing enter) in favor of
396 the custom command's behavior.
397 </p>
398 <pre class="prettyprint lang-js">$.contextMenu.types.myType = function(item, opt, root) {
399 $('&lt;span&gt;' + item.customName + '&lt;/span&gt;').appendTo(this);
f0326ef @rodneyrehm upgrade to jQuery 1.7, using .on() and .off()
rodneyrehm authored
400 this.on('contextmenu:focus', function(e) {
3735992 @rodneyrehm docs
rodneyrehm authored
401 // setup some awesome stuff
f0326ef @rodneyrehm upgrade to jQuery 1.7, using .on() and .off()
rodneyrehm authored
402 }).on('contextmenu:blur', function(e) {
3735992 @rodneyrehm docs
rodneyrehm authored
403 // tear down whatever you did
f0326ef @rodneyrehm upgrade to jQuery 1.7, using .on() and .off()
rodneyrehm authored
404 }).on('keydown', function(e) {
3735992 @rodneyrehm docs
rodneyrehm authored
405 // some funky key handling, maybe?
406 });
407 };
408 $.contextMenu({
409 selector: '.context-menu-custom',
410 items: {
411 label: {type: "myType", customName: "Foo Bar"}
412 }
413 });</pre>
414
415
416
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
417 <h2 id="disable-trigger">Disable a contextMenu trigger</h2>
418 <p>disable contextMenu to be shown on specified trigger elements</p>
17cd066 @rodneyrehm prettify, doc structure
rodneyrehm authored
419 <pre class="prettyprint lang-js">$(".some-selector").contextMenu(false);</pre>
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
420
421 <h2 id="enable-trigger">Enable a contextMenu trigger</h2>
422 <p>enable contextMenu to be shown on specified trigger elements</p>
17cd066 @rodneyrehm prettify, doc structure
rodneyrehm authored
423 <pre class="prettyprint lang-js">$(".some-selector").contextMenu(true);</pre>
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
424
425 <h2 id="show-trigger">Manually show a contextMenu</h2>
426 <p>show the contextMenu of the first element of the selector (position determined by <a href="#options-determinePosition">determinePosition</a>):</p>
17cd066 @rodneyrehm prettify, doc structure
rodneyrehm authored
427 <pre class="prettyprint lang-js">$(".some-selector").contextMenu();</pre>
3735992 @rodneyrehm docs
rodneyrehm authored
428 <pre class="prettyprint lang-js">$(".some-selector").contextMenu({x: 123, y: 123});</pre>
429
430 <h2 id="hide-trigger">Manually hide a contextMenu</h2>
431 <p>hide the contextMenu of the first element of the selector:</p>
432 <pre class="prettyprint lang-js">$(".some-selector").contextMenu("hide");</pre>
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
433
434 <h2 id="unregister-contextMenu">Unregister contextMenu</h2>
435 <p>To unregister / destroy a specific contextMenu:</p>
17cd066 @rodneyrehm prettify, doc structure
rodneyrehm authored
436 <pre class="prettyprint lang-js">$.contextMenu( 'destroy', <em>selector</em> );</pre>
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
437 <p><em>selector</em> expects the (string) selector that the contextMenu was registered to</p>
438
439 <h2 id="unregister-all">Unregister all contextMenus</h2>
440 <p>To unregister / destroy all contextMenus:</p>
17cd066 @rodneyrehm prettify, doc structure
rodneyrehm authored
441 <pre class="prettyprint lang-js">$.contextMenu( 'destroy' );</pre>
391e15b @rodneyrehm documentation
rodneyrehm authored
442
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
443 <h2 id="helper-import-values">Helper: Import values for &lt;input&gt;</h2>
444 <p>To fill input commands with values from a map:</p>
17cd066 @rodneyrehm prettify, doc structure
rodneyrehm authored
445 <pre class="prettyprint lang-js">{events: {
c56a95d @rodneyrehm updated documentation
rodneyrehm authored
446 hide: function(opt){
447 $.contextMenu.getInputValues(opt, {command1: "foo", command2: "bar"});
448 }
449 }
450 }</pre>
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
451 <p>To fill input commands with values from data-attributes:</p>
17cd066 @rodneyrehm prettify, doc structure
rodneyrehm authored
452 <pre class="prettyprint lang-js">{events: {
c56a95d @rodneyrehm updated documentation
rodneyrehm authored
453 hide: function(opt){
454 $.contextMenu.getInputValues(opt, this.data());
455 }
456 }
457 }</pre>
391e15b @rodneyrehm documentation
rodneyrehm authored
458
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
459 <h2 id="helper-export-values">Helper: Export values from &lt;input&gt;</h2>
460 <p>To fetch values from input commands:</p>
17cd066 @rodneyrehm prettify, doc structure
rodneyrehm authored
461 <pre class="prettyprint lang-js">{events: {
c56a95d @rodneyrehm updated documentation
rodneyrehm authored
462 hide: function(opt){
463 var values = $.contextMenu.setInputValues(opt}
464 }
465 }</pre>
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
466 <p>To save values from input commands to data-attributes:</p>
17cd066 @rodneyrehm prettify, doc structure
rodneyrehm authored
467 <pre class="prettyprint lang-js">{events: {
c56a95d @rodneyrehm updated documentation
rodneyrehm authored
468 hide: function(opt){
469 $.contextMenu.setInputValues(opt, this.data()); }
470 }
471 }</pre>
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
472
473
474 <h2 id="events">Events</h2>
475 <dl>
476 <dt>contextmenu</dt>
477 <dd>
478 <p>Trigger context menu to be shown for a trigger object.</p>
479 <p>Available on <em>trigger object</em>. The Event must be supplied with coordinates for the menu: <code>{pageX: 123, pageY:123}</code></p>
17cd066 @rodneyrehm prettify, doc structure
rodneyrehm authored
480 <pre class="prettyprint lang-js">$('.context-menu-one').first().trigger(
c56a95d @rodneyrehm updated documentation
rodneyrehm authored
481 $.Event('contextmenu', {pageX: 123, pageY: 123})
482 );</pre>
17cd066 @rodneyrehm prettify, doc structure
rodneyrehm authored
483 <pre class="prettyprint lang-js">$('.context-menu-one').first().trigger("contextmenu");</pre>
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
484 <p>will invoke <a href="#options-determinePosition">determinePosition</a> to position the menu</p>
485 </dd>
486 <dt>prevcommand</dt>
487 <dd>
488 <p>Select / highlight the previous possible command</p>
489 <p>Available on <em>context menu</em>.</p>
17cd066 @rodneyrehm prettify, doc structure
rodneyrehm authored
490 <pre class="prettyprint lang-js">opt.$menu.trigger("prevcommand");</pre>
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
491 </dd>
492 <dt>nextcommand</dt>
493 <dd>
494 <p>Select / highlight the next possible command</p>
495 <p>Available on <em>context menu</em>.</p>
17cd066 @rodneyrehm prettify, doc structure
rodneyrehm authored
496 <pre class="prettyprint lang-js">opt.$menu.trigger("nextcommand");</pre>
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
497 </dd>
3735992 @rodneyrehm docs
rodneyrehm authored
498
499 <dt>contextmenu:hide</dt>
500 <dd>
501 <p>Hide the menu</p>
502 <p>Available on <em>context menu</em>.</p>
503 <pre class="prettyprint lang-js">opt.$menu.trigger("contextmenu:hide");</pre>
504 </dd>
505
506 <dt>contextmenu:focus</dt>
507 <dd>
66057c2 @rodneyrehm typo
rodneyrehm authored
508 <p>React to a command item being focused</p>
3735992 @rodneyrehm docs
rodneyrehm authored
509 <p>Triggered on <em>context menu item</em> when mouse or keyboard interaction lead to a "hover state" for that command item.</p>
f0326ef @rodneyrehm upgrade to jQuery 1.7, using .on() and .off()
rodneyrehm authored
510 <pre class="prettyprint lang-js">$(document.body).on("contextmenu:focus", ".context-menu-item",
3735992 @rodneyrehm docs
rodneyrehm authored
511 function(e){ console.log("focus:", this); });</pre>
512 </dd>
513
514 <dt>contextmenu:blur</dt>
515 <dd>
516 <p>Available on each <em>context menu item</em>.</p>
517 <p>Triggered on <em>context menu item</em> when mouse or keyboard interaction lead from a "hover state" to "default state" for that command item.</p>
f0326ef @rodneyrehm upgrade to jQuery 1.7, using .on() and .off()
rodneyrehm authored
518 <pre class="prettyprint lang-js">$(document.body).on("contextmenu:blur", ".context-menu-item",
3735992 @rodneyrehm docs
rodneyrehm authored
519 function(e){ console.log("blur:", this); });</pre>
520 </dd>
521
522 <dt>keydown</dt>
523 <dd>
524 <p>Available on each <em>context menu item</em>.</p>
525 <p>Triggered on <em>context menu item</em> when keyboard interaction could not be handled by jQuery.contextMenu.</p>
f0326ef @rodneyrehm upgrade to jQuery 1.7, using .on() and .off()
rodneyrehm authored
526 <pre class="prettyprint lang-js">$(document.body).on("keydown", ".context-menu-item",
3735992 @rodneyrehm docs
rodneyrehm authored
527 function(e){ console.log("key:", e.keyCode); });</pre>
528 </dd>
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
529 </dl>
530
531 <h2 id="html5-import">HTML5 &lt;menu&gt; import</h2>
532 <p>considering the following HTML <code>$.contextMenu.fromMenu($('#html5menu'))</code> will return a proper <a href="#items">items</a> object
17cd066 @rodneyrehm prettify, doc structure
rodneyrehm authored
533 <pre class="prettyprint lang-html">&lt;menu id=&quot;html5menu&quot; type=&quot;context&quot; style=&quot;display:none&quot;&gt;
c56a95d @rodneyrehm updated documentation
rodneyrehm authored
534 &lt;command label=&quot;rotate&quot; onclick=&quot;alert('rotate')&quot;&gt;
535 &lt;command label=&quot;resize&quot; onclick=&quot;alert('resize')&quot;&gt;
536 &lt;menu label=&quot;share&quot;&gt;
537 &lt;command label=&quot;twitter&quot; onclick=&quot;alert('twitter')&quot;&gt;
538 &lt;hr&gt;
539 &lt;command label=&quot;facebook&quot; onclick=&quot;alert('facebook')&quot;&gt;
540 &lt;/menu&gt;
17cd066 @rodneyrehm prettify, doc structure
rodneyrehm authored
541 &lt;/menu&gt;</pre>
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
542 <p><code>$.contextMenu.fromMenu()</code> will properly import (and thus handle) the following elements. Everything else is imported as <code>{type: "html"}</code></p>
543 <ul>
544 <li>&lt;menu&gt;</li>
545 <li>&lt;hr&gt;</li>
546 <li>&lt;a&gt;</li>
b7d4caf @rodneyrehm more doc stuff
rodneyrehm authored
547 <li>&lt;command type=&quot;command|radio|checkbox&quot;&gt; (W3C Specification)</li>
548 <li>&lt;menuitem type=&quot;command|radio|checkbox&quot;&gt; (Firefox 8)</li>
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
549 <li>&lt;input type=&quot;text|radio|checkbox&quot;&gt;</li>
550 <li>&lt;select&gt;</li>
551 <li>&lt;textare&gt;</li>
552 <li>&lt;label for="someId"&gt;</li>
553 <li>&lt;label&gt; the text &lt;input|textarea|select&gt;</li>
554 </ul>
555 <p>The &lt;menu&gt; must be hidden but not removed, as all command events (clicks) are passed-thru to the original command element!</p>
b716d07 @rodneyrehm fixed html5 import
rodneyrehm authored
556 <p>Note: While the specs note &lt;option&gt;s to be renderd as regular commands, $.contextMenu will render an actual &lt;select&gt;.</p>
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
557
0b762ee @rodneyrehm fixing html5 support detection
rodneyrehm authored
558 <h2 id="html5-shiv">HTML5 &lt;menu&gt; shiv/polyfill</h2>
559 <p>Engaging the HTML5 polyfill (ignoring $.contextMenu if context menus are available natively):</p>
17cd066 @rodneyrehm prettify, doc structure
rodneyrehm authored
560 <pre class="prettyprint lang-js">$(function(){ $.contextMenu("html5"); });</pre>
0b762ee @rodneyrehm fixing html5 support detection
rodneyrehm authored
561 <p>Engaging the HTML5 polyfill (ignoring browser native implementation):</p>
17cd066 @rodneyrehm prettify, doc structure
rodneyrehm authored
562 <pre class="prettyprint lang-js">$(function(){ $.contextMenu("html5", true); });</pre>
0b762ee @rodneyrehm fixing html5 support detection
rodneyrehm authored
563
74b4afd @rodneyrehm 4 spaces make one indentation. Damn TextMate�
rodneyrehm authored
564 <h2 id="ui-position">$.ui.position</h2>
565 <p>
566 The <a href="http://jqueryui.com/demos/position/">position utility of jQuery UI</a> makes relative positioning very simple. But the real beauty is <em>collision detection</em>,
567 allowing the contextMenu to be shown to the left side of the pointer, if there's not enough space to the right.
568 Its use is optional, if you want to shape off some more bytes by sacrificing usability: go ahead…
569 </p>
570 </div>
391e15b @rodneyrehm documentation
rodneyrehm authored
571 </body>
572 </html>
Something went wrong with that request. Please try again.