Confirmed users
764
edits
Labs/Jetpack/Reboot/JEP/112: Difference between revisions
no edit summary
m (→Example Usage) |
No edit summary |
||
| Line 14: | Line 14: | ||
# The domain of browser extensions is not a single page but the set of all the user's pages. | # The domain of browser extensions is not a single page but the set of all the user's pages. | ||
# 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. | # 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. | ||
Multiple extensions may simultaneously modify the context menu, but their modifications should not conflict. For example, 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 place of M. Modifications to the menu are always performed on the unmodified menu and then merged to form the modified menu. | |||
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. | 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. | ||
| Line 42: | Line 44: | ||
=== API Methods === | === API Methods === | ||
==== add(context, menuitem) ==== | ==== add(context, menuitem) ==== | ||
| Line 50: | Line 50: | ||
; context : A value describing the context under which to add the item. See [[#Specifying Contexts]]. | ; context : A value describing the context under which to add the item. See [[#Specifying Contexts]]. | ||
; menuitem : The menuitem to add. See [[#Specifying Menuitems]]. | ; menuitem : The menuitem to add. See [[#Specifying New Menuitems]]. | ||
==== replace(context, target, menuitem) ==== | ==== replace(context, target, menuitem) ==== | ||
| Line 58: | Line 58: | ||
; context : A value describing the context under which to add the item. See [[#Specifying Contexts]]. | ; 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]]. | ; target : A value describing the existing item to replace. See [[#Specifying Existing Menuitems]]. | ||
; menuitem : The menuitem to add. See [[#Specifying Menuitems]]. | ; menuitem : The menuitem to add. See [[#Specifying New Menuitems]]. | ||
==== insertBefore(context, target, menuitem) ==== | ==== insertBefore(context, target, menuitem) ==== | ||
| Line 66: | Line 66: | ||
; context : A value describing the context under which to add the item. See [[#Specifying Contexts]]. | ; 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]]. | ; 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]]. | ; menuitem : The menuitem to add. See [[#Specifying New Menuitems]]. | ||
==== Specifying Contexts ==== | ==== Specifying Contexts ==== | ||
As its name implies, the context menu should be used only when some particular context arises. | As its name implies, the context menu should be used only when some particular context arises. 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. | 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. | ||
| Line 79: | Line 79: | ||
; function : An arbitrary predicate. The context arises when the function returns true. | ; function : An arbitrary predicate. The context arises when the function returns true. | ||
==== Specifying New Menuitems ==== | |||
New menuitems are specified using the following types: | |||
; string: A simple menuitem with the given string label. | |||
; null: A simple menu separator. (Note that any falsey value will suffice, including <tt>undefined</tt>, <tt>null</tt>, and the empty string. <tt>null</tt> is recommended because it stands out.) | |||
; object: A menuitem with specific properties. The object may define any of the following properties: | |||
<blockquote> | |||
; command: A function that will be called when the menuitem is clicked. If the <tt>menu</tt> property is present, <tt>command</tt> will instead be called when any of the item's descendents is clicked. In that case, the commands of descendants will be invoked first. In either case, it is called as <tt>command(context, data)</tt>. <tt>data</tt> is the <tt>data</tt> property of the item that was selected or <tt>undefined</tt> if the selected item has no data. <tt>context</tt> is an object describing the context in which the menu was invoked. It has the following properties: | |||
<blockquote> | |||
; node: The node the user clicked to invoke the menu. | |||
; document: The document containing <tt>node</tt>, i.e., <tt>node.ownerDocument</tt>. | |||
; window: The window containing <tt>document</tt>, i.e., <tt>node.ownerDocument.defaultView</tt>. | |||
</blockquote> | |||
; data: An arbitrary string that the extension may associate with the menuitem. | |||
; icon: The URL of an icon to display in the menuitem. Note that some environments, [https://bugzilla.mozilla.org/show_bug.cgi?id=527253 notably Gnome 2.28], do not support menuitem icons either by default or at all. | |||
; label: The label of the menuitem, a string. | |||
; menu: An array. If defined, the menuitem expands into a submenu. Each element in the array must be a menuitem. | |||
</blockquote> | |||
==== Specifying Existing Menuitems ==== | |||
Existing menuitems are always identified using targets. A target is either a string or regular expression. A string target is case-insensitively matched against the labels and IDs of menuitems. A regular expression target is tested against labels and IDs. | |||
Multiple items in a menu may match a target, but action is only ever taken on the first matching item. | |||
=== Example Usage === | === Example Usage === | ||
| Line 88: | Line 128: | ||
contextMenu.add("img", { | contextMenu.add("img", { | ||
label: "Edit Image", | label: "Edit Image", | ||
command: function ( | command: function (context) { | ||
editImage(context.node.src); | editImage(context.node.src); | ||
} | } | ||
| Line 107: | Line 147: | ||
{ label: "Wikipedia", data: "http://en.wikipedia.org/wiki/" } | { label: "Wikipedia", data: "http://en.wikipedia.org/wiki/" } | ||
], | ], | ||
command: function ( | command: function (context, data) { | ||
context.window.location.href = | context.window.location.href = data + selection.text; | ||
} | } | ||
} | } | ||
| Line 120: | Line 160: | ||
{ | { | ||
label: "Edit Page Source", | label: "Edit Page Source", | ||
command: function ( | command: function (context) { | ||
editSource(context.document.URL); | editSource(context.document.URL); | ||
} | } | ||
| Line 133: | Line 173: | ||
{ | { | ||
label: "Edit Page Images", | label: "Edit Page Images", | ||
command: function ( | command: function (context) { | ||
editPageImages(context.document.URL); | editPageImages(context.document.URL); | ||
} | } | ||