add

This article is in need of a technical review.

The NativeWindow object is only available to privileged code running on Firefox for Android, and is intended for use by Firefox for Android add-ons.

Summary

NativeWindow.contextmenus.add() adds a new context menu item to Firefox for Android.

Syntax

var menuID = window.NativeWindow.contextmenus.add(name, selector, callback);

name
The string displayed by the context menu item. This takes either a String or Function object. Functions take the top-most element the context menu is being shown for as an argument. For instance, to show the host of a link that is tapped on as your context menu label, you could use:
function(aElement) {
  let uri = null;
  var node = aElement;
  while (node && !uri) {
    uri = NativeWindow.contextmenus._getLink(node);
    node = node.parentNode;
  }
  return uri ? uri.host : "No uri"
}
selector

This determines when the item should be shown. The contextmenus object defines a number of built-in selectors:

SelectorContext Initialized with a CSS selector, and displays the context menu item only if the selected page element matches the selector
linkOpenableContext Displays the context menu item only if the selected page element is any link that Firefox can open (meaning, any URI scheme except mailto://, javascript://, news://, or snews://
linkShareableContext Displays the context menu item only if the selected page element is a link that it makes sense to send to someone else (meaning, any URI scheme except chrome://, about://, file://, javascript://, or resource://)
linkBookmarkableContext Displays the context menu item only if the selected page element is a link that it makes sense to bookmark (meaning, any URI scheme except mailto://)
textContext Displays the context menu item only if the selected page element is a textarea element or an HTMLInputElement element that is a text field (meaning, that it has a type attribute of email, password, search, tel, text, or url)
imageSaveableContext Displays the context menu item only if the selected page element is an image that is loaded and can be saved.
You can create your own selector by passing in any object that has a function matches(element). This function:
  • takes a DOM element as a parameter
  • returns true if the context menu item should be shown, and false otherwise.
 
 
callback
The function to be called when the item is selected. It is passed the selected page element as a DOM element.

Returns

menuID: an identifier for the context menu item. This may be used to remove the item using NativeWindow.contextmenus.remove().

Example

This example adds a context menu item only when the selected element is a link pointing to "*.mozilla.*":

var menuID;

function loadIntoWindow(window) {    
  if (!window)    
    return;
  let label = "Show Text Content";
  let selector = {
    matches: function(element) {
      var domainParts = element.hostname.split(".");
      return (element.href && domainParts[domainParts.length - 2] == "mozilla");
    }
  }
  menuID = window.NativeWindow.contextmenus.add(label, selector, function(target) {      
    window.NativeWindow.toast.show(target.text, "short");       
  });    
}

This example uses the predefined SelectorContext to display the context menu item only if the selected element is the first item in a list:

var menuID;

function loadIntoWindow(window) {    
  if (!window)    
    return;
  let label = "Show List Item";
  let selector =  window.NativeWindow.contextmenus.SelectorContext("li:first-child");
  menuID = window.NativeWindow.contextmenus.add(label, selector, function(target) {      
    window.NativeWindow.toast.show(target.outerHTML, "short");       
  });
}    

See Also

Document Tags and Contributors

Contributors to this page: wbamberg, justinpotts, Liuche
Last updated by: wbamberg,