Labs/Jetpack/Reboot/JEP/112

JEP 112 - Context Menu

• Champion: Drew Willcoxon - adw at mozilla.com
• Status: Accepted/In-Queue
• Bug Ticket:
• Type: API

Proposal

Provide access to the page's context menu.

This proposal recognizes the following principles:

1. The domain of browser extensions is not a single page but the set of all the user's pages.
2. The page's context menu is for UI related to the page and its content. It should not be used for contexts external to the page. It should not be used simply because it's handy.

We mention briefly that HTML5 includes a specification for menus, but no browser implements it yet, and its scope is not that of browser extensions anyway.

Use Cases

• Adding an item that acts on a portion of the page -- a node, selection, etc. Examples:
  • An image-editing extension wants to add an "Edit Image" item when the context menu is invoked on an image.
  • A search extension wants to add a "Search" item when the context menu is invoked while a selection exists.
• Adding an item that acts on the entire page. Examples:
  • An extension that makes it easy to edit page source wants to add an "Edit Page Source" item when the context menu is invoked anywhere on the page.
  • An image-editing extension wants to add an "Edit Page Images" item when the context menu is invoked anywhere on a page that has at least one image.

Non-Use Cases

• Adding an item unrelated to the page and its content. Examples:
  • A tab-related extension wants to add an item that provides access to all the user's tabs.
  • An extension wants to add an item when it's three o'clock.

Dependencies & Requirements

• Access to content pages and their DOMs.
• Access to the browser's DOM, including popupshowing and popuphiding events.

Internal Methods

This JEP doesn't export anything into the Cuddlefish Platform Library.

API Methods

Extensions should not be able to interact with each other: If two extensions both replace a menuitem M, the net effect should be that M is removed from the menu and both extensions' items are present. In other words, modifications to the menu are always performed on the unmodified menu and then merged to form the modified menu.

add(context, menuitem)

Adds an item to the context menu. The position at which the item is inserted is at the discretion of Jetpack.

context

A value describing the context under which to add the item. See #Specifying Contexts.

menuitem

The menuitem to add. See #Specifying Menuitems.

replace(context, target, menuitem)

Replaces an existing item in the context menu. If the target item does not exist, this function silently fails, and the context menu is not modified.

context

A value describing the context under which to add the item. See #Specifying Contexts.

target

A value describing the existing item to replace. See #Specifying Existing Menuitems.

menuitem

The menuitem to add. See #Specifying Menuitems.

insertBefore(context, target, menuitem)

Inserts a new item before an existing one. If the target item does not exist, this function silently fails, and the context menu not modified.

context

A value describing the context under which to add the item. See #Specifying Contexts.

target

A value describing the existing item before which to insert the new item. See #Specifying Existing Menuitems.

menuitem

The menuitem to add. See #Specifying Menuitems.

Specifying Contexts

As its name implies, the context menu should be used only when some particular context arises. The context can be related to page content or the page itself, but it should never be external to the page.

A context must be specified when modifying the menu. When the menu is invoked under a specified context, all of the context's associated modifications are applied. When the menu is invoked without matching any specified context, no modifications are applied.

Contexts may be specified with any of the following types:

string

A CSS selector. The context arises when the menu is invoked on a node that matches this selector.

function

An arbitrary predicate. The context arises when the function returns true.