path: root/tools/addon-sdk-1.5/packages/addon-kit/docs/context-menu.md

<!-- This Source Code Form is subject to the terms of the Mozilla Public
   - License, v. 2.0. If a copy of the MPL was not distributed with this
   - file, You can obtain one at http://mozilla.org/MPL/2.0/. -->

<!-- contributed by Drew Willcoxon [adw@mozilla.com]  -->
<!-- edited by Noelle Murata [fiveinchpixie@gmail.com]  -->

The `context-menu` module lets you add items to Firefox's page context menu.


Introduction
------------

The `context-menu` API provides a simple, declarative way to add items to the
page's context menu.  You can add items that perform an action when clicked,
submenus, and menu separators.

Instead of manually adding items when particular contexts occur and then
removing them when those contexts go away, you *bind* items to contexts, and the
adding and removing is automatically handled for you.  Items are bound to
contexts in much the same way that event listeners are bound to events.  When
the user invokes the context menu, all of the items bound to the current context
are automatically added to the menu.  If no items are bound, none are added.
Likewise, any items that were previously in the menu but are not bound to the
current context are automatically removed from the menu.  You never need to
manually remove your items from the menu unless you want them to never appear
again.

For example, if your add-on needs to add a context menu item whenever the
user visits a certain page, don't create the item when that page loads, and
don't remove it when the page unloads.  Rather, create your item only once and
supply a context that matches the target URL.


Specifying Contexts
-------------------

As its name implies, the context menu should be reserved for the occurrence of
specific contexts.  Contexts can be related to page content or the page itself,
but they should never be external to the page.

For example, a good use of the menu would be to show an "Edit Image" item when
the user right-clicks an image in the page.  A bad use would be to show a
submenu that listed all the user's tabs, since tabs aren't related to the page
or the node the user clicked to open the menu.

### The Page Context

First of all, you may not need to specify a context at all.  When an item does
not specify a context, the page context applies.

The *page context* occurs when the user invokes the context menu on a
non-interactive portion of the page.  Try right-clicking a blank spot in this
page, or on text.  Make sure that no text is selected.  The menu that appears
should contain the items "Back", "Forward", "Reload", "Stop", and so on.  This
is the page context.

The page context is appropriate when your item acts on the page as a whole.  It
does not occur when the user invokes the context menu on a link, image, or other
non-text node, or while a selection exists.

### Declarative Contexts

You can specify some simple, declarative contexts when you create a menu item by
setting the `context` property of the options object passed to its constructor,
like this:

    var cm = require("context-menu");
    cm.Item({
      label: "My Menu Item",
      context: cm.URLContext("*.mozilla.org")
    });

These contexts may be specified by calling the following constructors.  Each is
exported by the `context-menu` module.

<table>
  <tr>
    <th>Constructor</th>
    <th>Description</th>
  </tr>
  <tr>
    <td><code>
      PageContext()
    </code></td>
    <td>
      The page context.
    </td>
  </tr>
  <tr>
    <td><code>
      SelectionContext()
    </code></td>
    <td>
      This context occurs when the menu is invoked on a page in which the user
      has made a selection.
    </td>
  </tr>
  <tr>
    <td><code>
      SelectorContext(selector)
    </code></td>
    <td>
      This context occurs when the menu is invoked on a node that either matches
      <code>selector</code>, a CSS selector,  or has an ancestor that matches.
      <code>selector</code> may include multiple selectors separated by commas,
      e.g., <code>"a[href], img"</code>.
    </td>
  </tr>
  <tr>
    <td><code>
      URLContext(matchPattern)
    </code></td>
    <td>
      This context occurs when the menu is invoked on pages with particular
      URLs.  <code>matchPattern</code> is a match pattern string or an array of
      match pattern strings.  When <code>matchPattern</code> is an array, the
      context occurs when the menu is invoked on a page whose URL matches any of
      the patterns.  These are the same match pattern strings that you use with
      the <a href="packages/addon-kit/docs/page-mod.html"><code>page-mod</code></a>
      <code>include</code> property.
      <a href="packages/api-utils/docs/match-pattern.html">Read more about patterns</a>.
    </td>
  </tr>
  <tr>
    <td>
      array
    </td>
    <td>
      An array of any of the other types.  This context occurs when all contexts
      in the array occur.
    </td>
  </tr>
</table>

Menu items also have a `context` property that can be used to add and remove
declarative contexts after construction.  For example:

    var context = require("context-menu").SelectorContext("img");
    myMenuItem.context.add(context);
    myMenuItem.context.remove(context);

When a menu item is bound to more than one context, it appears in the menu when
all of those contexts occur.

### In Content Scripts

The declarative contexts are handy but not very powerful.  For instance, you
might want your menu item to appear for any page that has at least one image,
but declarative contexts won't help you there.

When you need more control control over the context in which your menu items are
shown, you can use content scripts.  Like other APIs in the SDK, the
`context-menu` API uses
[content scripts](dev-guide/addon-development/web-content.html) to let your
add-on interact with pages in the browser.  Each menu item you create in the
top-level context menu can have a content script.

A special event named `"context"` is emitted in your content scripts whenever
the context menu is about to be shown.  If you register a listener function for
this event and it returns true, the menu item associated with the listener's
content script is shown in the menu.

For example, this item appears whenever the context menu is invoked on a page
that contains at least one image:

    require("context-menu").Item({
      label: "This Page Has Images",
      contentScript: 'self.on("context", function (node) {' +
                     '  return !!document.querySelector("img");' +
                     '});'
    });

Note that the listener function has a parameter called `node`.  This is the node
in the page that the user context-clicked to invoke the menu.  You can use it to
determine whether your item should be shown.

You can both specify declarative contexts and listen for contexts in a content
script.  In that case, the declarative contexts are evaluated first.  If they
are not current, then your context listener is never called.

This example takes advantage of that fact.  The listener can be assured that
`node` will always be an image:

    require("context-menu").Item({
      label: "A Mozilla Image",
      context: contextMenu.SelectorContext("img"),
      contentScript: 'self.on("context", function (node) {' +
                     '  return /mozilla/.test(node.src);' +
                     '});'
    });

Your item is shown only when all declarative contexts are current and your
context listener returns true.


Handling Menu Item Clicks
-------------------------

In addition to using content scripts to listen for the `"context"` event as
described above, you can use content scripts to handle item clicks.  When the
user clicks your menu item, an event named `"click"` is emitted in the item's
content script.

Therefore, to handle an item click, listen for the `"click"` event in that
item's content script like so:

    require("context-menu").Item({
      label: "My Item",
      contentScript: 'self.on("click", function (node, data) {' +
                     '  console.log("Item clicked!");' +
                     '});'
    });

Note that the listener function has parameters called `node` and `data`.  `node`
is the node that the user context-clicked to invoke the menu.  You can use it
when performing some action.  `data` is the `data` property of the menu item
that was clicked.  Since only top-level menu items have content scripts, this
comes in handy for determining which item in a `Menu` was clicked:

    var cm = require("context-menu");
    cm.Menu({
      label: "My Menu",
      contentScript: 'self.on("click", function (node, data) {' +
                     '  console.log("You clicked " + data);' +
                     '});',
      items: [
        cm.Item({ label: "Item 1", data: "item1" }),
        cm.Item({ label: "Item 2", data: "item2" }),
        cm.Item({ label: "Item 3", data: "item3" })
      ]
    });

Often you will need to collect some kind of information in the click listener
and perform an action unrelated to content.  To communicate to the menu item
associated with the content script, the content script can call the
`postMessage` function attached to the global `self` object, passing it some
JSON-able data.  The menu item's `"message"` event listener will be called with
that data.

    require("context-menu").Item({
      label: "Edit Image",
      context: contextMenu.SelectorContext("img"),
      contentScript: 'self.on("click", function (node, data) {' +
                     '  self.postMessage(node.src);' +
                     '});',
      onMessage: function (imgSrc) {
        openImageEditor(imgSrc);
      }
    });


Updating a Menu Item's Label
----------------------------

Each menu item must be created with a label, but you can change its label later
using a couple of methods.

The simplest method is to set the menu item's `label` property.  This example
updates the item's label based on the number of times it's been clicked:

    var numClicks = 0;
    var myItem = require("context-menu").Item({
      label: "Click Me: " + numClicks,
      contentScript: 'self.on("click", self.postMessage);',
      onMessage: function () {
        numClicks++;
        this.label = "Click Me: " + numClicks;
        // Setting myItem.label is equivalent.
      }
    });

Sometimes you might want to update the label based on the context.  For
instance, if your item performs a search with the user's selected text, it would
be nice to display the text in the item to provide feedback to the user.  In
these cases you can use the second method.  Recall that your content scripts can
listen for the `"context"` event and if your listeners return true, the items
associated with the content scripts are shown in the menu.  In addition to
returning true, your `"context"` listeners can also return strings.  When a
`"context"` listener returns a string, it becomes the item's new label.

This item implements the aforementioned search example:

    var cm = require("context-menu");
    cm.Item({
      label: "Search Google",
      context: cm.SelectionContext(),
      contentScript: 'self.on("context", function () {' +
                     '  var text = window.getSelection().toString();' +
                     '  if (text.length > 20)' +
                     '    text = text.substr(0, 20) + "...";' +
                     '  return "Search Google for " + text;' +
                     '});'
    });

The `"context"` listener gets the window's current selection, truncating it if
it's too long, and includes it in the returned string.  When the item is shown,
its label will be "Search Google for `text`", where `text` is the truncated
selection.


More Examples
-------------

For conciseness, these examples create their content scripts as strings and use
the `contentScript` property.  In your own add-on, you will probably want to
create your content scripts in separate files and pass their URLs using the
`contentScriptFile` property.  See
[Working with Content Scripts](dev-guide/addon-development/web-content.html)
for more information.

<div class="warning">
<p>Unless your content script is extremely simple and consists only of a
static string, don't use <code>contentScript</code>: if you do, you may
have problems getting your add-on approved on AMO.</p>
<p>Instead, keep the script in a separate file and load it using
<code>contentScriptFile</code>. This makes your code easier to maintain,
secure, debug and review.</p>
</div>

Show an "Edit Page Source" item when the user right-clicks a non-interactive
part of the page:

    require("context-menu").Item({
      label: "Edit Page Source",
      contentScript: 'self.on("click", function (node, data) {' +
                     '  self.postMessage(document.URL);' +
                     '});',
      onMessage: function (pageURL) {
        editSource(pageURL);
      }
    });

Show an "Edit Image" item when the menu is invoked on an image:

    require("context-menu").Item({
      label: "Edit Image",
      context: contextMenu.SelectorContext("img"),
      contentScript: 'self.on("click", function (node, data) {' +
                     '  self.postMessage(node.src);' +
                     '});',
      onMessage: function (imgSrc) {
        openImageEditor(imgSrc);
      }
    });

Show an "Edit Mozilla Image" item when the menu is invoked on an image in a
mozilla.org or mozilla.com page:

    var cm = require("context-menu");
    cm.Item({
      label: "Edit Mozilla Image",
      context: [
        cm.URLContext(["*.mozilla.org", "*.mozilla.com"]),
        cm.SelectorContext("img")
      ],
      contentScript: 'self.on("click", function (node, data) {' +
                     '  self.postMessage(node.src);' +
                     '});',
      onMessage: function (imgSrc) {
        openImageEditor(imgSrc);
      }
    });

Show an "Edit Page Images" item when the page contains at least one image:

    require("context-menu").Item({
      label: "Edit Page Images",
      // This ensures the item only appears during the page context.
      context: contextMenu.PageContext(),
      contentScript: 'self.on("context", function (node) {' +
                     '  var pageHasImgs = !!document.querySelector("img");' +
                     '  return pageHasImgs;' +
                     '});' +
                     'self.on("click", function (node, data) {' +
                     '  var imgs = document.querySelectorAll("img");' +
                     '  var imgSrcs = [];' +
                     '  for (var i = 0 ; i < imgs.length; i++)' +
                     '    imgSrcs.push(imgs[i].src);' +
                     '  self.postMessage(imgSrcs);' +
                     '});',
      onMessage: function (imgSrcs) {
        openImageEditor(imgSrcs);
      }
    });

Show a "Search With" menu when the user right-clicks an anchor that searches
Google or Wikipedia with the text contained in the anchor:

    var cm = require("context-menu");
    var googleItem = cm.Item({
      label: "Google",
      data: "http://www.google.com/search?q="
    });
    var wikipediaItem = cm.Item({
      label: "Wikipedia",
      data: "http://en.wikipedia.org/wiki/Special:Search?search="
    });
    var searchMenu = cm.Menu({
      label: "Search With",
      context: contextMenu.SelectorContext("a[href]"),
      contentScript: 'self.on("click", function (node, data) {' +
                     '  var searchURL = data + node.textContent;' +
                     '  window.location.href = searchURL;' +
                     '});',
      items: [googleItem, wikipediaItem]
    });


<api name="Item">
@class
A labeled menu item that can perform an action when clicked.
<api name="Item">
@constructor
  Creates a labeled menu item that can perform an action when clicked.
@param options {object}
  An object with the following keys:
  @prop label {string}
    The item's label.  It must either be a string or an object that implements
    `toString()`.
  @prop [image] {string}
    The item's icon, a string URL.  The URL can be remote, a reference to an
    image in the add-on's `data` directory, or a data URI.
  @prop [data] {string}
    An optional arbitrary value to associate with the item.  It must be either a
    string or an object that implements `toString()`.  It will be passed to
    click listeners.
  @prop [context] {value}
    If the item is contained in the top-level context menu, this declaratively
    specifies the context under which the item will appear; see Specifying
    Contexts above.  Ignored if the item is contained in a submenu.
  @prop [contentScript] {string,array}
    If the item is contained in the top-level context menu, this is the content
    script or an array of content scripts that the item can use to interact with
    the page.  Ignored if the item is contained in a submenu.
  @prop [contentScriptFile] {string,array}
    If the item is contained in the top-level context menu, this is the local
    file URL of the content script or an array of such URLs that the item can
    use to interact with the page.  Ignored if the item is contained in a
    submenu.
  @prop [onMessage] {function}
    If the item is contained in the top-level context menu, this function will
    be called when the content script calls `self.postMessage`.  It will be
    passed the data that was passed to `postMessage`.  Ignored if the item is
    contained in a submenu.
</api>

<api name="label">
@property {string}
  The menu item's label.  You can set this after creating the item to update its
  label later.
</api>

<api name="image">
@property {string}
  The item's icon, a string URL.  The URL can be remote, a reference to an image
  in the add-on's `data` directory, or a data URI.  You can set this after
  creating the item to update its image later.  To remove the item's image, set
  it to `null`.
</api>

<api name="data">
@property {string}
  An optional arbitrary value to associate with the item.  It must be either a
  string or an object that implements `toString()`.  It will be passed to
  click listeners.  You can set this after creating the item to update its data
  later.
</api>

<api name="context">
@property {list}
  A list of declarative contexts for which the menu item will appear in the
  context menu.  Contexts can be added by calling `context.add()` and removed by
  called `context.remove()`.  This property is meaningful only for items
  contained in the top-level context menu.
</api>

<api name="parentMenu">
@property {Menu}
  The item's parent `Menu`, or `null` if the item is contained in the top-level
  context menu.  This property is read-only.  To add the item to a new menu,
  call that menu's `addItem()` method.
</api>

<api name="contentScript">
@property {string,array}
  The content script or the array of content scripts associated with the menu
  item during creation.  This property is meaningful only for items contained in
  the top-level context menu.
</api>

<api name="contentScriptFile">
@property {string,array}
  The URL of a content script or the array of such URLs associated with the menu
  item during creation.  This property is meaningful only for items contained in
  the top-level context menu.
</api>

<api name="destroy">
@method
  Permanently removes the item from its parent menu and frees its resources.
  The item must not be used afterward.  If you need to remove the item from its
  parent menu but use it afterward, call `removeItem()` on the parent menu
  instead.
</api>

<api name="message">
@event
If you listen to this event you can receive message events from content
scripts associated with this menu item. When a content script posts a
message using `self.postMessage()`, the message is delivered to the add-on
code in the menu item's `message` event.

@argument {value}
Listeners are passed a single argument which is the message posted
from the content script. The message can be any
<a href = "dev-guide/addon-development/content-scripts/using-port.html#json_serializable">JSON-serializable value</a>.
</api>

</api>

<api name="Menu">
@class
A labeled menu item that expands into a submenu.

<api name="Menu">
@constructor
  Creates a labeled menu item that expands into a submenu.
@param options {object}
  An object with the following keys:
  @prop label {string}
    The item's label.  It must either be a string or an object that implements
    `toString()`.
  @prop items {array}
    An array of menu items that the menu will contain.  Each must be an `Item`,
    `Menu`, or `Separator`.
  @prop [image] {string}
    The menu's icon, a string URL.  The URL can be remote, a reference to an
    image in the add-on's `data` directory, or a data URI.
  @prop [context] {value}
    If the menu is contained in the top-level context menu, this declaratively
    specifies the context under which the menu will appear; see Specifying
    Contexts above.  Ignored if the menu is contained in a submenu.
  @prop [contentScript] {string,array}
    If the menu is contained in the top-level context menu, this is the content
    script or an array of content scripts that the menu can use to interact with
    the page.  Ignored if the menu is contained in a submenu.
  @prop [contentScriptFile] {string,array}
    If the menu is contained in the top-level context menu, this is the local
    file URL of the content script or an array of such URLs that the menu can
    use to interact with the page.  Ignored if the menu is contained in a
    submenu.
  @prop [onMessage] {function}
    If the menu is contained in the top-level context menu, this function will
    be called when the content script calls `self.postMessage`.  It will be
    passed the data that was passed to `postMessage`.  Ignored if the item is
    contained in a submenu.
</api>

<api name="label">
@property {string}
  The menu's label.  You can set this after creating the menu to update its
  label later.
</api>

<api name="items">
@property {array}
  An array containing the items in the menu.  The array is read-only, meaning
  that modifications to it will not affect the menu.  However, setting this
  property to a new array will replace all the items currently in the menu with
  the items in the new array.
</api>

<api name="image">
@property {string}
  The menu's icon, a string URL.  The URL can be remote, a reference to an image
  in the add-on's `data` directory, or a data URI.  You can set this after
  creating the menu to update its image later.  To remove the menu's image, set
  it to `null`.
</api>

<api name="context">
@property {list}
  A list of declarative contexts for which the menu will appear in the context
  menu.  Contexts can be added by calling `context.add()` and removed by called
  `context.remove()`.  This property is meaningful only for menus contained in
  the top-level context menu.
</api>

<api name="parentMenu">
@property {Menu}
  The menu's parent `Menu`, or `null` if the menu is contained in the top-level
  context menu.  This property is read-only.  To add the menu to a new menu,
  call that menu's `addItem()` method.
</api>

<api name="contentScript">
@property {string,array}
  The content script or the array of content scripts associated with the menu
  during creation.  This property is meaningful only for menus contained in the
  top-level context menu.
</api>

<api name="contentScriptFile">
@property {string,array}
  The URL of a content script or the array of such URLs associated with the menu
  during creation.  This property is meaningful only for menus contained in the
  top-level context menu.
</api>

<api name="addItem">
@method
  Appends a menu item to the end of the menu.  If the item is already contained
  in another menu or in the top-level context menu, it's automatically removed
  first.
@param item {Item,Menu,Separator}
  The `Item`, `Menu`, or `Separator` to add to the menu.
</api>

<api name="removeItem">
@method
  Removes the given menu item from the menu.  If the menu does not contain the
  item, this method does nothing.
@param item {Item,Menu,Separator}
  The menu item to remove from the menu.
</api>

<api name="destroy">
@method
  Permanently removes the menu from its parent menu and frees its resources.
  The menu must not be used afterward.  If you need to remove the menu from its
  parent menu but use it afterward, call `removeItem()` on the parent menu
  instead.
</api>

<api name="message">
@event
If you listen to this event you can receive message events from content
scripts associated with this menu item. When a content script posts a
message using `self.postMessage()`, the message is delivered to the add-on
code in the menu item's `message` event.

@argument {value}
Listeners are passed a single argument which is the message posted
from the content script. The message can be any
<a href = "dev-guide/addon-development/content-scripts/using-port.html#json_serializable">JSON-serializable value</a>.
</api>

</api>

<api name="Separator">
@class
A menu separator.  Separators can be contained only in `Menu`s, not in the
top-level context menu.

<api name="Separator">
@constructor
  Creates a menu separator.
</api>

<api name="parentMenu">
@property {Menu}
  The separator's parent `Menu`.  This property is read-only.  To add the
  separator to a new menu, call that menu's `addItem()` method.
</api>

<api name="destroy">
@method
  Permanently removes the separator from its parent menu and frees its
  resources.  The separator must not be used afterward.  If you need to remove
  the separator from its parent menu but use it afterward, call `removeItem()`
  on the parent menu instead.
</api>

</api>

<api name="PageContext">
@class
<api name="PageContext">
@constructor
  Creates a page context.  See Specifying Contexts above.
</api>
</api>

<api name="SelectionContext">
@class
<api name="SelectionContext">
@constructor
  Creates a context that occurs when a page contains a selection.  See
  Specifying Contexts above.
</api>
</api>

<api name="SelectorContext">
@class
<api name="SelectorContext">
@constructor
  Creates a context that matches a given CSS selector.  See Specifying Contexts
  above.
@param selector {string}
  A CSS selector.
</api>
</api>

<api name="URLContext">
@class
<api name="URLContext">
@constructor
  Creates a context that matches pages with particular URLs.  See Specifying
  Contexts above.
@param matchPattern {string,array}
  A [match pattern](packages/api-utils/docs/match-pattern.html) string or an array of
  match pattern strings.
</api>
</api>