doc/index.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>JSDoc: Home</title>
<script src="scripts/prettify/prettify.js"> </script>
<script src="scripts/prettify/lang-css.js"> </script>
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
<link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
</head>
<body>
<div id="main">
<h1 class="page-title">Home</h1>
<h3> </h3>
<section>
<article><h1>Audero Context Menu</h1><p><a href="https://codeclimate.com/github/AurelioDeRosa/Audero-Context-Menu"><img src="https://codeclimate.com/github/AurelioDeRosa/Audero-Context-Menu/badges/gpa.svg" alt="Code Climate"></a>
<a href="https://travis-ci.org/AurelioDeRosa/Audero-Context-Menu"><img src="https://travis-ci.org/AurelioDeRosa/Audero-Context-Menu.svg?branch=master" alt="Build Status"></a>
<a href="https://coveralls.io/github/AurelioDeRosa/Audero-Context-Menu?branch=master"><img src="https://coveralls.io/repos/AurelioDeRosa/Audero-Context-Menu/badge.svg?branch=master&service=github" alt="Coverage Status"></a></p>
<p><a href="https://github.com/AurelioDeRosa/Audero-Context-Menu">Audero Context Menu</a> is a cross-browser jQuery plugin that
allows you to show a custom context menu on one or more specified elements.</p>
<h2>Demo</h2><p>A live demo is available
<a href="http://htmlpreview.github.io/?https://github.com/AurelioDeRosa/Audero-Context-Menu/blob/master/demo/index.html">here</a>.</p>
<h2>Requirements</h2><p>Being a jQuery plugin, the only requirement is <a href="http://www.jquery.com">jQuery</a> starting from version <strong>1.7</strong>.</p>
<h2>Compatibility</h2><p>It has been tested and works on all the major browsers, including Internet Explorer 6 and later.</p>
<p>Audero Context Menu follows the <a href="https://github.com/umdjs/umd">UMD (Universal Module Definition)</a> pattern to work
seamlessly with module systems such as AMD and CommonJS, and the browser.</p>
<h2>Installation</h2><p>You can install Audero Context Menu by using <a href="https://www.npmjs.com">npm</a>:</p>
<pre class="prettyprint source"><code>npm install audero-context-menu</code></pre><p>Alternatively, you can install it via <a href="http://bower.io">Bower</a>:</p>
<pre class="prettyprint source"><code>bower install audero-context-menu</code></pre><p>Alternatively, you can manually download it.</p>
<p>Remember to include the JavaScript file <strong>after</strong> the <a href="http://www.jquery.com">jQuery</a> library, ideally before the
closing <code>body</code> tag:</p>
<pre class="prettyprint source lang-html"><code> <script src="path/to/jquery.js"></script>
<script src="path/to/jquery.auderoContextMenu.js"></script>
</body></code></pre><p>The CSS file should be placed in the <code>head</code> of your web page as shown below:</p>
<pre class="prettyprint source lang-html"><code><head>
<link rel="stylesheet" href="path/to/auderoContextMenu.css" /></code></pre><h3>Inclusion with Browserify</h3><p>To use Audero Context Menu with Browserify, you have to write:</p>
<pre class="prettyprint source lang-js"><code>require('audero-context-menu')();</code></pre><p>If you want to specify the global environment and augment a specific version of jQuery, you can pass both to
the plugin:</p>
<pre class="prettyprint source lang-js"><code>var jQuery = require('jquery');
require('audero-context-menu')(window, jQuery);</code></pre><h2>Usage</h2><p>Once you have all the files in place, you have to create the menu and choose the element(s) that will interact with it.
The menu is a simple unordered list having <code>audero-context-menu</code> as class and an arbitrary ID (for example
<code>context-menu-1</code>).</p>
<p>An example of how you can write the menu is shown below:</p>
<pre class="prettyprint source lang-html"><code><ul id="context-menu-1" class="audero-context-menu">
<li><a href="http://www.audero.it" target="_blank">Audero</a></li>
<li><a href="https://twitter.com/AurelioDeRosa" target="_blank">Aurelio De Rosa on Twitter</a></li>
<li><a href="https://github.com/AurelioDeRosa" target="_blank">Aurelio De Rosa on GitHub</a></li>
</ul></code></pre><p>Now that you created the menu, you have to attach it to one or more elements. To achieve this goal, you have to call
the <code>auderoContextMenu()</code> method, passing the id of the menu, on the desired element(s).</p>
<p>For example, let that you have the following code:</p>
<pre class="prettyprint source lang-html"><code><div id="area-1" class="area">
Right-click here to show the custom menu.<br />
Left-click here or click outside this area and the menu will disappear.
</div></code></pre><p>A basic call to the plugin is:</p>
<pre class="prettyprint source lang-html"><code><script>
$(document).ready(function() {
$('#area-1').auderoContextMenu('context-menu-1');
});
</script></code></pre><p>Please note that the previous snippet is a shortcut for:</p>
<pre class="prettyprint source lang-html"><code><script>
$(document).ready(function() {
$('#area-1').auderoContextMenu({
idMenu: 'context-menu-1'
});
});
</script></code></pre><p>You can read more on the meaning of <code>idMenu</code> and the other options available in the <a href="#options">Options</a> section.</p>
<h3>Destroy</h3><p>In some cases, you may want to remove the effect of this plugin. To achieve this goal, you can call the
<code>auderoContextMenu()</code> method passing the string <code>destroy</code>.</p>
<p>Let's say that you want to delete the effect of the plugin on an element having ID <code>area-1</code> as soon as a button having
ID <code>button-destroy</code> is clicked. To do that, you can write a code like the following:</p>
<pre class="prettyprint source lang-html"><code><script>
$('#button-destroy').click(function() {
$('#area-1').auderoContextMenu('destroy');
});
</script></code></pre><h2>Options</h2><p>Audero Context Menu has few options you can set during the call to the <code>auderoContextMenu()</code> method. The options are:</p>
<ul>
<li><code>idMenu</code> (<code>string</code>. Default: <code>''</code>): The ID of the menu that has to be shown.</li>
<li><code>posX</code> (<code>number</code>. Default: <code>null</code>): The X coordinate used to show the menu. If the value is not set or is <code>null</code>
the current position of the mouse will be used.</li>
<li><code>posY</code> (<code>number</code>. Default: <code>null</code>): The Y coordinate used to show the menu. If the value is not set or is <code>null</code>
the current position of the mouse will be used.</li>
<li><code>bindLeftClick</code> (<code>boolean</code>. Default: <code>false</code>): If the menu has to be shown also on mouse left button click.</li>
</ul>
<h3>Override default values</h3><p><a href="https://github.com/AurelioDeRosa/Audero-Context-Menu">Audero Context Menu</a> has been developed following the
current best practices in developing plugins for jQuery. Therefore, it exposes the previously cited options through
the <code>defaults</code> object, allowing you to override the properties' default value. Changing the default values, you don't
need to specify them again when you call the <code>auderoContextMenu()</code> method. For example, let that you have the following
code:</p>
<pre class="prettyprint source lang-html"><code><script>
$(document).ready(function() {
$('#area-1').auderoContextMenu({
idMenu: 'context-menu-1',
bindLeftClick: true
});
$('#area-2').auderoContextMenu({
idMenu: 'context-menu-2',
bindLeftClick: true
});
});
</script></code></pre><p>Overriding the default values you can turn it into the following:</p>
<pre class="prettyprint source lang-html"><code><script>
$(document).ready(function() {
$.fn.auderoContextMenu.defaults.bindLeftClick = true;
$('#area-1').auderoContextMenu({
idMenu: 'context-menu-1'
});
$('#area-2').auderoContextMenu({
idMenu: 'context-menu-2'
});
});
</script></code></pre><h2>Advanced Examples</h2><h3>Menu with fixed position</h3><p>This example shows you how, with few changes, you can display the menu in a fixed position. All you have to do is
to place the menu (the <code><ul></code>) inside the element you want to attach the plugin and set the CSS position attribute
of the latter to <code>relative</code>.</p>
<p>So, your HTML code should look like this:</p>
<pre class="prettyprint source lang-html"><code><div id="area-2" class="area">
Right-click here to show another custom menu with <b>fixed position</b>.<br />
Left-click here or click outside this area and the menu will disappear.
<ul id="context-menu-2" class="audero-context-menu">
<li><a href="http://www.audero.it" target="_blank">Audero</a></li>
<li><a href="https://www.jquery.com" target="_blank">jQuery.com</a></li>
</ul>
</div></code></pre><p>Then, you need to have the following style somewhere in your page:</p>
<pre class="prettyprint source lang-css"><code>#area-2
{
position: relative;
}</code></pre><p>Finally, to show the menu at <code>10px</code> from the left margin and <code>20px</code> from the top margin of the element position, you
have to write the following code:</p>
<pre class="prettyprint source lang-html"><code><script>
$(document).ready(function() {
$('#area-2').auderoContextMenu({
idMenu: 'context-menu-2',
posX: 10,
posY: 20
});
});
</script></code></pre><h3>Bind left click</h3><p>This example shows how you can have the custom context menu also for the mouse left button click event. Let's that
you have the same HTML code listed in the <a href="#usage">Usage</a> section, you have to write:</p>
<pre class="prettyprint source lang-html"><code><script>
$(document).ready(function() {
$('#area-1').auderoContextMenu({
idMenu: 'context-menu-1',
bindLeftClick: true
});
});
</script></code></pre><h2>License</h2><p><a href="https://github.com/AurelioDeRosa/Audero-Context-Menu">Audero Context Menu</a> is dual licensed under
<a href="http://www.opensource.org/licenses/MIT">MIT</a> and <a href="http://opensource.org/licenses/GPL-3.0">GPL-3.0</a>.</p>
<h2>Author</h2><p><a href="http://www.audero.it">Aurelio De Rosa</a> (<a href="https://twitter.com/AurelioDeRosa">@AurelioDeRosa</a>)</p></article>
</section>
</div>
<nav>
<h2><a href="index.html">Home</a></h2><h3>Externals</h3><ul><li><a href="external-_jQuery.fn_.html">jQuery.fn</a></li></ul><h3><a href="global.html">Global</a></h3>
</nav>
<br class="clear">
<footer>
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.4.0</a> on Sun Jan 24 2016 23:36:30 GMT+0000 (GMT Standard Time)
</footer>
<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>