Extensions

Adding a new menu

The main menu bar in Firefox has the id 'main-menubar'. To add a new menu onto the main application menubar, you will need to overlay this menubar. For instance:

<menubar id="main-menubar">
  <menu label="Search" insertbefore="tools-menu">
    <menupopup>
      <menuitem label="Web"/>
      <menuitem label="Mail"/>
    </menupopup>
  </menu>
</menubar>

This menu is added to the main menu bar just before the Tools menu. The insertbefore attribute is set to 'tools-menu' to ensure that the new menu is added at the right place. Note that the menu will not appear until it has a <menupopup>.

Adding a new menuitem

You might wish to add a new item to one of the menus. This can be done by overlaying the popup to append the item to. For a list of the ids of the menus for Firefox, see Firefox Menus. For example, to add an item to the end of the Tools menu, use the following:

<menupopup id="menu_ToolsPopup">
  <menuitem label="Thesaurus"/>
</menupopup>

Note that other extensions may be adding their own items into the same menus. Because of this, the new item might not appear at the end of the menu but before a menuitem added by another extension, depending on the order in which the overlays are applied. As you cannot predict this order, you should not rely on any menuitems being in particular positions in the presence of other extensions.

Modifying the context menu

An extension may wish to modify the context menu associated with the browser area. Normally, this menu displays menu items specific to what was context clicked or focused. For instance, opening a context menu for a link displays items to open the link in a new window or tab and to save or bookmark the link. An extension may modify the context menu to show additional items that either appear always, or appear only when certain content is selected.

In Firefox, the browser area that displays web pages has only one context menu. Instead of having separate context menus depending on what type of element was the target of the context menu, only one context menu is used and items that don't apply to that type of element are hidden from the menu as needed. Thus, you can add items to the Firefox context menu by overlaying this single menu. This context menu has the id 'contentAreaContextMenu'. In this example, a single item is added to the end of the Firefox context menu.

<popup id="contentAreaContextMenu">
  <menuitem id="thumbnail-show" label="View Thumbnail" oncommand="Thumbnails.view();"/>
</popup>

Note that the popup element is used rather than the menupopup element as this is the element that Firefox uses.

The code above will append the new item at the end of the context menu. If you want to place the item at a specific location within the context menu rather than at the end, you can use either the insertbefore or insertafter attributes to insert it before or after another item specified by an id. For example, the following may be used to insert a command just after the 'Select All' command:

<popup id="contentAreaContextMenu">
  <menuitem label="Select Links" oncommand="Thumbnails.selectAllLinks();"
            insertafter="context-selectall"/>
</popup>

See Firefox Context Menu for a list of the ids of the items found on the Firefox context menu.

Showing and hiding context menu items

To have a menuitem you have added be shown or hidden based on the context, you can use an event handler that listens for the popupshowing event. For instance, if an image was context clicked, you may wish to hide the menu item you have added if the operation it performed wouldn't apply to images.

function init()
{
  var contextMenu = document.getElementById("contentAreaContextMenu");
  if (contextMenu)
    contextMenu.addEventListener("popupshowing", ThumbnailsShowHideItems, false);
}

function ThumbnailsShowHideItems(event)
{
  var show = document.getElementById("thumbnail-show");
  show.hidden = (document.popupNode.localName != "IMG");
}

The init function should be called within the handler for the load event so that the popupshowing event handler is hooked up before it would be opened by the user. In this example, the ThumbnailsShowHideItems function will be called when the popup is about to be shown. This function retrieves the menuitem with the id 'thumbnail-show' that was added by the extension and hides it if an image was not the target of the context menu. The popupNode property of the document holds the target of the context menu.

For more details about hiding and showing items on a context menu, see Hiding and Showing Menu Items based on Context.

Determining what element was context clicked

For general information about how to determine which element was the target of the context menu, that is, the element that was context clicked, see Determining what was Context Clicked

Firefox uses its own popupshowing event listener to adjust the items on the context menu. This allows the menu to have different commands for different types of targets. While the popup is open, the gContextMenu global variable is set to an object which handles all of the functionality specific to the Firefox context menu. Specifically, this object is initialized with a set of properties that indiciate the type of object that was the target of the context menu. For instance, the 'onLink' property is set to true when a link was context-clicked.

You may wish to use these properties instead of determining the type yourself, as the code already handles various special and complex cases that would take a lot of code to deal with manually. The following are the most common properties that you can check. An example follows.

In the following example, the menuitem is hidden unless the target is an image or a link.

function ThumbnailsShowHideItems(event)
{
  var show = document.getElementById("thumbnail-show");
  show.hidden = !(gContextMenu.onImage || gContextMenu.onLink);
}