add-a-context-menu-item.md

Add a Context Menu Item

To follow this tutorial you'll need to have [installed the SDK](dev-guide/tutorials/installation.html) and learned the [basics of `cfx`](dev-guide/tutorials/getting-started-with-cfx.html).

To add items and submenus to the Firefox context menu, use the context-menu module.

Here's an add-on that adds a new context menu item. The item is displayed whenever something in the page is selected. When it's clicked, the selection is sent to the main add-on code, which just logs it:

 var contextMenu = require("context-menu");
 var menuItem = contextMenu.Item({
  label: "Log Selection",
  context: contextMenu.SelectionContext(),
  contentScript: 'self.on("click", function () {' +
                 '  var text = window.getSelection().toString();' +
                 '  self.postMessage(text);' +
                 '});',
  onMessage: function (selectionText) {
    console.log(selectionText);
  }
});

Try it: run the add-on, load a web page, select some text and right-click. You should see the new item appear:

Click it, and the selection is logged to the console:

info: elephantine lizard

All this add-on does is to construct a context menu item. You don't need to add it: once you have constructed the item, it is automatically added in the correct context. The constructor in this case takes four options: label, context, contentScript, and onMessage.

label

The label is just the string that's displayed.

context

The context describes the circumstances in which the item should be shown. The context-menu module provides a number of simple built-in contexts, including this SelectionContext(), which means: display the item when something on the page is selected.

If these simple contexts aren't enough, you can define more sophisticated contexts using scripts.

contentScript

This attaches a script to the item. In this case the script listens for the user to click on the item, then sends a message to the add-on containing the selected text.

onMessage

The onMessage property provides a way for the add-on code to respond to messages from the script attached to the context menu item. In this case it just logs the selected text.

So:

1. the user clicks the item
2. the content script's click event fires, and the content script retrieves the selected text and sends a message to the add-on
3. the add-on's message event fires, and the add-on code's handler function is passed the selected text, which it logs

Learning More

To learn more about the context-menu module, see the context-menu API reference.