Mobile/Fennec/Extensions/UserInterface/Site Menu

Introduction

The site menu is displayed when a user taps on the favicon (or Site Identity button) next the address bar. It's purpose is to provide more detail and options related to the page the user is viewing.

By default it shows security information, controls to add a search providers and clear site-specific preferences, and commands to share, save, or find within the page.

Add-ons can use the site panel to display additional information or actions related to the current page. To extend the site menu, add a new pageaction element within the #pageactions-container hbox.

Adding to the Site Menu

To add a command to the site menu, add a pageaction element to the #pageactions-container box. For example, in a XUL overlay you could write:

 <hbox id="pageactions-container">
   <pageaction id="sayhello-action"
     title="Say Hello"
     description="Display a greeting" 
     onclick="alert('Hello!');"/>
 </hbox>

Changing Site Menu items

If you want to enable, disable, or change your pageaction, you can register a method to be called each time the menu appears. Use the PageActions.register function.

PageActions.register API

PageActions.register(id, callback, thisObject);

id

The ID of your pageaction element. (Remember, your IDs should include a string that is unique to your add-on, to avoid conflicting with Fennec code or other add-ons.)

callback

A function that takes a pageaction element and returns a boolean: true if the pageaction should be visible, false if it should be hidden.

thisObject

(optional) An object to use as "this" in the callback function.

Example

PageActions.register("sayhello-action", function(element) {
  // Hide the menu item if we're in a blank tab.
  if (getBrowser().currentURI == "about:blank")
    return false;

  // Change the pageaction title.
  element.setAttribute("title", "Say hello to " + getBrowser().contentTitle);

  return true;
});

Examples

• For a basic XUL example, see the Read Later source code.
• See the Mobile Tools source code for an add-on that inserts a new pageaction using JavaScript.
• See the PageActions.init function in Fennec's browser-ui.js for examples using the PageActions.register API.