MenuModification

Modifying a Menu

Menus have a number of methods which may be used to add and remove items.

Adding Items to a Menu

The appendItem method may be used to append a new item to the end of the popup associated with a menu. This method will create a new menuitem element and insert it into the popup. This method may only be used with the menu element.

<script>
function addToMenu()
{
  var menu = document.getElementById("edit-menu");
  menu.appendItem("Insert", "insert");
}
</script>
<menu id="edit-menu"/>
<button label="Add" oncommand="addToMenu()"/>

In this example, the addToMenu function is called when the button is pressed. This function appends a new item to the menu's popup with the label Insert. The first argument to appendItem is the label of the menuitem, and the second argument is a value to associate with the item. This value be set as the menuitem's value attribute and can be used for whatever purpose is desired. Note how in this example, the menu does not have a child menupopup. The appendItem method will create a menupopup element if it doesn't already exist. If the menu already has a menupopup, the new menuitem will be appended to this existing one.

While the appendItem method always adds the new item to the end of the menu, the insertItemAt method may be used in a similar fashion to insert an item into the menu elsewhere.

menu.insertItemAt(0, "Delete", "delete");

In this example, the insertItemAt method is used to insert a new 'Delete' item at the beginning of the menu's popup. The first argument is the index where the new item should be inserted. In this case, 0 is supplied as the index, which means before the first item. Indicies are counted starting at 0, so to insert an item before the fourth item pass 3 as the argument. The second and third arguments to insertItemAt are the label and value for the new item, as with appendItem.

Both the appendItem and insertItemAt methods return the new menuitem, so you can further modify it, for instance to add an access key, as in the following example:

var item = menu.appendItem("Insert", "insert");
item.accessKey = "I";

Appending Submenus

There is no built-in method to append submenus to a menu. To do this, we instead need to use the inherited node modification methods available for all elements. First, we need to retrieve the menupopup for the menu, and then use the appendChild method to append a new item.

<script>
function addSubMenu()
{
  var popup = document.getElementById("file-popup");
  var newmenu = document.createElement("menu");
  popup.appendChild(newmenu);
  newmenu.label = "New";
  newmenu.appendItem("Document", "doc");
  newmenu.appendItem("Image", "image");
}
</script>
<menu label="File" onpopupshowing="addSubMenu()">
  <menupopup id="file-popup"/>
</menu>

The addSubMenu function is called during the popupshowing event, which will be fired when an attempt to open the menu is made. This function retrieves a reference to the popup with the id 'file-popup'. A new element is created using the createElement method. The createElement method takes one argument, the tag of the element to create. This menu is created and appended to the popup. The label is set appropriately, and now, as we have a menu, we can use the appendItem method to append two items to the submenu. The effect is that a submenu with two items is added dynamically to the menu.

The appendChild method is available for all elements, and is used to add new nodes within another node. The appendItem method is specific to menus, as well as some other specific elements, and is simpler to use to append new menuitem elements to a menu.

If we were to use the example above, we would also want to make sure to remove the items again in a popuphiding event listener. Otherwise, a new submenu would be added every time the menu is opened, which is clearly not desirable. Another possibility is to ensure that the menu is only added once. The following shows how the addSubMenu function above might be rewritten to handle this case.

<script>
function addSubMenu()
{
  var popup = document.getElementById("file-popup");
  if (popup.hasChildNodes())
    return;
  var newmenu = document.createElement("menu");
  popup.appendChild(newmenu);
  newmenu.label = "New";
  newmenu.appendItem("Document", "doc");
  newmenu.appendItem("Image", "image");
}
</script>

The hasChildNodes method may be used to check if a node has any children. The first time the function is called, the hasChildNodes method will return false, however the second time, the method will return true as the items have already been added to the menu.

Removing Items from a Menu

To remove an item from the menu, use the removeItemAt method. It takes a single argument, the index of the item to remove. In this example, an item is appended to a menu, and then immediately removed again.

menu.appendItem("Open", "");
menu.removeItemAt(menu.itemCount - 1);

The itemCount property holds the number of items within the menu.

To remove all of the items from a menu, you may wish to simply remove the menupopup directly, instead of removing each item individually.