Adding items to menus: Difference between revisions

From MozillaZine Knowledge Base
Jump to navigationJump to search
mNo edit summary
m (→‎Resources: remove dlink to xulplanet)
 
(14 intermediate revisions by 8 users not shown)
Line 1: Line 1:
{{extdev}}
{{extdev}}
:''Note: Information in this section applies to Mozilla Suite, Firefox and Thunderbird and other XUL-based applications. When I say Mozilla, I mean one of these three applications.''


==Adding items to Mozilla menus==
This tutorial describes steps necessary to add a static or a dynamic menu item to Mozilla from an [[Extension development|extension]]. It's created for beginner extension developers; if you're a user, you probably want to search for existing extensions that do what you need.
''Note: Information in this section applies to Mozilla, Mozilla Firefox and Mozilla Thunderbird. When I say Mozilla I mean one of these three applications.''


To add an item to Mozilla menu without editing its source files, you first need to create an [[Dev : Extensions : Overlays|overlay]].  
==Creating the overlay==
To add an item to an existing menu of a Mozilla-based application without editing its source files, you first need to create an [[Overlays|overlay]].  


The following lines in the overlay will add two items to ''contentAreaContextMenu'' popup menu (the menu that appears when you right-click a web page):
The following lines in the overlay will add two items to <code>contentAreaContextMenu</code> popup menu (the menu that appears when you right-click a web page):
<pre><popup id="contentAreaContextMenu">
<pre><popup id="contentAreaContextMenu">
   <menuitem id="context-item1" label="Item 1" oncommand="alert('Item1');"/>
   <menuitem id="context-item1" label="Item 1" oncommand="alert('Item1');"/>
Line 12: Line 13:
</popup></pre>
</popup></pre>


These lines in the overlay add an item to Firefox ''Tools'' menu:
These lines in the overlay add an item to Firefox ''"Tools"'' menu:
<pre><menupopup id="menu_ToolsPopup">
<pre><menupopup id="menu_ToolsPopup">
   <menuitem id="example-item" oncommand="alert("Hello!");" label="Hi" accesskey="i"/>
   <menuitem id="example-item" oncommand="alert('Hello!');" label="Hi" accesskey="i"/>
</menupopup></pre>
</menupopup></pre>


You can specify position of the item being inserted with '''insertafter'''/'''insertbefore'''/'''position''' attributes [http://xulplanet.com/references/elemref/ref_XULElement.html#attr_insertafter]
You can specify position of the item being inserted with <code>insertafter</code>/<code>insertbefore</code>/<code>position</code> attributes [http://xulplanet.com/references/elemref/ref_XULElement.html#attr_insertafter]


To find out ''id'' of specific Mozilla menu, use [[DOM Inspector]]. The ''Tools'' menu in Firefox is ''menu_ToolsPopup'', in Seamonkey and in Thunderbird (as of 07/2004) it's ''taskPopup''.
To find out <code>id</code> of specific menu, use [[DOM Inspector]]. The ''"Tools"'' menu in Firefox is <code>menu_ToolsPopup</code>, in Seamonkey and in Thunderbird it's <code>taskPopup</code>.


The simplest extension that adds an item to content area context menu is BugMeNot. Adding items to Tools menu example can be seen in QuickNote. Read more about <popup>, <menupopup> and <menuitem> at XulPlanet. See Resources section below.
The simplest extension that adds an item to content area context menu is BugMeNot. Adding items to Tools menu example can be seen in QuickNote. Read more about <code><popup></code>, <code><menupopup></code> and <code><menuitem></code> at XUL Planet. See Resources section below.


===Making context menu items appear only when on link, image etc.===
==Dynamically showing context menu items==
The simplest example extension is ShowImage.
The simplest example extension is ShowImage.
<ol><li>Add a JS [[Dev : Extensions : Scripts|script]] to your overlay.</li>
<ol><li>Add a JS script to your overlay.</li>
<li>Add the following line in the beginning of the script. This line gets executed when the overlay is being loaded and it tells Mozilla to call the ''initOverlay()'' function when the window your overlay is attached to finishes loading. Note, you should give your real function more unique name than initOverlay(). See [http://www.pikey.me.uk/mozilla/?extension=sfu Show Failed URL] extension by Pike as the simplest real-life example of using ''window.addEventListener("load")''.<pre>window.addEventListener("load", initOverlay, false);</pre></li>
<li>Add the following line in the beginning of the script. This line gets executed when the overlay is being loaded and it tells Mozilla to call the <code>initOverlay()</code> function when the window your overlay is attached to finishes loading. Note, you should give your real function a more unique name than <code>initOverlay()</code>.
<li>In the initOverlay() function add a popupshowing event listener for the menu you are extending, like this:
<pre>window.addEventListener("load", initOverlay, false);</pre>
</li>
 
<li>In the <code>initOverlay()</code> function add a <code>popupshowing</code> event listener for the menu you are extending, like this:
<pre>function initOverlay() {
<pre>function initOverlay() {
   var menu = document.getElementById("contentAreaContextMenu");
   var menu = document.getElementById("contentAreaContextMenu");
   menu.addEventListener("popupshowing", contextPopupshowing, false);
   menu.addEventListener("popupshowing", contextPopupShowing, false);
}</pre>
}</pre>
This tells Mozilla to call contextPopupShowing() every time the contentAreaContextMenu popup is about to show.</li>
This tells Mozilla to call <code>contextPopupShowing()</code> every time the <code>contentAreaContextMenu</code> popup is about to show.</li>
<li>In the contextPopupShowing() function adjust visibility of the menu items - either manually:
 
<li>You are now in a position to adjust the visibility of the menu items for the popup menu, within the <code>contextPopupShowing()</code> function. Visibility will often be determined on the basis of some browser condition or selected page element. In the example below, the menu item will only appear when some page text is selected. Setting visibility can either be done manually:
<pre>function contextPopupShowing() {
<pre>function contextPopupShowing() {
   var menuitem = document.getElementById("context-item1");
   var menuitem = document.getElementById("context-item1");
Line 39: Line 44:
     menuitem.hidden = !gContextMenu.isTextSelected;
     menuitem.hidden = !gContextMenu.isTextSelected;
}</pre>
}</pre>
...or using a convenience function nsContextMenu.showItem():
...or by using the convenience function <code>nsContextMenu.showItem()</code>:
<pre>function contextPopupShowing() {
<pre>function contextPopupShowing() {
   gContextMenu.showItem("context-item1", gContextMenu.isTextSelected);
   gContextMenu.showItem("context-item1", gContextMenu.isTextSelected);
}</pre>
}</pre>
Look in nsContextMenu.js (Seamonkey) or browser.js (Firefox) for the definition of nsContextMenu.
Look in <tt>nsContextMenu.js</tt> (Seamonkey) or <tt>browser.js</tt> (Firefox) for the definition of <code>nsContextMenu</code>.
</li></ol>
</li></ol>


(remember that you need to use [[Dev : Javascript coding guidelines|unique identifiers]] instead of generic <tt>contextPopupShowing</tt> to aviod clashing with other extensions)
(remember that you need to use [[Javascript coding guidelines|unique identifiers]] instead of generic <code>contextPopupShowing</code> to avoid conflicts with other extensions)


==Resources==
==Resources==
*XulPlanet:
**[http://xulplanet.com/references/elemref/ref_menuitem.html menuitem], [http://xulplanet.com/references/elemref/ref_menupopup.html menupopup], [http://xulplanet.com/references/elemref/ref_popup.html popup] elements reference;
**Main Tutorial pages on [http://www.xulplanet.com/tutorials/xultu/menubar.html simple menu bars]  and [http://xulplanet.com/tutorials/xultu/popups.html popup menus].
*nsContextMenu (gContextMenu is an object of that type) definition: [http://lxr.mozilla.org/aviarybranch/source/browser/base/content/browser.js#3537 Firefox 1.0], [http://lxr.mozilla.org/seamonkey/source/xpfe/communicator/resources/content/nsContextMenu.js Mozilla], [http://lxr.mozilla.org/seamonkey/source/browser/base/content/browser.js#3537 Firefox tunk]
*Sample extensions:  
*Sample extensions:  
**[http://bugmenot.mozdev.org/ BugMeNot]
**[http://bugmenot.mozdev.org/ BugMeNot]
Line 58: Line 59:
**[http://quicknote.mozdev.org/ QuickNote]
**[http://quicknote.mozdev.org/ QuickNote]


[[Category:Development]]
[[Category:Example code]]

Latest revision as of 18:38, 22 April 2015

This page is part of the extension development documentation project.

Ask your questions in MozillaZine Forums. Also try browsing example code.

Note: development documentation is in process of being moved to Mozilla Development Center (MDC).

Note: Information in this section applies to Mozilla Suite, Firefox and Thunderbird and other XUL-based applications. When I say Mozilla, I mean one of these three applications.

This tutorial describes steps necessary to add a static or a dynamic menu item to Mozilla from an extension. It's created for beginner extension developers; if you're a user, you probably want to search for existing extensions that do what you need.

Creating the overlay

To add an item to an existing menu of a Mozilla-based application without editing its source files, you first need to create an overlay.

The following lines in the overlay will add two items to contentAreaContextMenu popup menu (the menu that appears when you right-click a web page):

<popup id="contentAreaContextMenu">
  <menuitem id="context-item1" label="Item 1" oncommand="alert('Item1');"/>
  <menuitem id="context-item2" label="Item 2" oncommand="alert('Item2');"/>
</popup>

These lines in the overlay add an item to Firefox "Tools" menu:

<menupopup id="menu_ToolsPopup">
  <menuitem id="example-item" oncommand="alert('Hello!');" label="Hi" accesskey="i"/>
</menupopup>

You can specify position of the item being inserted with insertafter/insertbefore/position attributes [1]

To find out id of specific menu, use DOM Inspector. The "Tools" menu in Firefox is menu_ToolsPopup, in Seamonkey and in Thunderbird it's taskPopup.

The simplest extension that adds an item to content area context menu is BugMeNot. Adding items to Tools menu example can be seen in QuickNote. Read more about <popup>, <menupopup> and <menuitem> at XUL Planet. See Resources section below.

Dynamically showing context menu items

The simplest example extension is ShowImage.

  1. Add a JS script to your overlay.
  2. Add the following line in the beginning of the script. This line gets executed when the overlay is being loaded and it tells Mozilla to call the initOverlay() function when the window your overlay is attached to finishes loading. Note, you should give your real function a more unique name than initOverlay().
    window.addEventListener("load", initOverlay, false);
  3. In the initOverlay() function add a popupshowing event listener for the menu you are extending, like this:
    function initOverlay() {
      var menu = document.getElementById("contentAreaContextMenu");
      menu.addEventListener("popupshowing", contextPopupShowing, false);
    }
    This tells Mozilla to call contextPopupShowing() every time the contentAreaContextMenu popup is about to show.
  4. You are now in a position to adjust the visibility of the menu items for the popup menu, within the contextPopupShowing() function. Visibility will often be determined on the basis of some browser condition or selected page element. In the example below, the menu item will only appear when some page text is selected. Setting visibility can either be done manually:
    function contextPopupShowing() {
      var menuitem = document.getElementById("context-item1");
      if(menuitem)
        menuitem.hidden = !gContextMenu.isTextSelected;
    }

    ...or by using the convenience function nsContextMenu.showItem():

    function contextPopupShowing() {
      gContextMenu.showItem("context-item1", gContextMenu.isTextSelected);
    }

    Look in nsContextMenu.js (Seamonkey) or browser.js (Firefox) for the definition of nsContextMenu.

(remember that you need to use unique identifiers instead of generic contextPopupShowing to avoid conflicts with other extensions)

Resources