THIS PAGE IS A WORKING DRAFT
	The page may be difficult to navigate, and some information on its subject might be incomplete and/or evolving rapidly. If you have any questions or ideas, please add them as a new topic on the discussion page.

Native apps present menus, and webapp runtimes should enable webapps to do likewise, for consistency and parity with native platforms. But platform capabilities, standards, and conventions vary significantly; and we must balance the benefits of deep integration into native platforms with the ease of cross-platform development.

Many webapps will be mobile-centric, and they will want to present a relatively short, flat set of menuitems. For parity with mobile platforms, Gecko should provide an API that solicits and presents such a set. And for ease of cross-platform development, we should present the set on other platforms in appropriate ways.

Some webapps will be desktop-centric, and they will want to present a complex, hierarchical set of menuitems. For parity with desktop platforms, Gecko should provide an API that solicits and presents such a set. However, because there is no comparable affordance on mobile platforms, we should not present the set on those platforms.

Desktop platforms sometimes also specify default and conventional menus and menuitems. Desktop runtimes should present default menus/menuitems by default, without requiring apps to specify them (nor letting apps remove them). Desktop runtimes should also allow apps to add items to conventional menus and to register handlers for conventional menuitems.

API Fundamentals

Menus and their items are specified using a variant of the HTML5 menu specification, which defines the <menu> element; but using a <menuitem> element, as implemented in Gecko for context menus.

Application Menu

The `application` menu type identifies unary flat menu that supports the mobile-centric use case:

 <menu type="application">
   <menuitem label="About" onclick="showAbout()"></menuitem>
   <menuitem label="Search" onclick="search()"></menuitem>
   <menuitem label="Settings" onclick="goToSettings()"></menuitem>
 </menu>

All runtimes support this type, and they present it in the most suitable way for their platform. On Android, the runtime populates the options menu <http://developer.android.com/guide/topics/ui/menus.html#options-menu> with its items. On Mac, the runtime places the items into the application menu. On Windows, the runtime presents them in a unified menu like Firefox's.

Desktop Menubar

The `menubar` menu type identifies a set of hierarchical menus that supports the desktop-centric use case:

 <menu type="menubar">
   <menu label="Project">
     <menuitem label="New..." onclick="createProject()"></menuitem>
     <menuitem label="Open..." onclick="openProject()"></menuitem>
   </menu>
   <menu label="Share">
     <menuitem label="Twitter" onclick="tweet()"></menuitem>
     <menuitem label="Facebook" onclick="facebookEmDanno()"></menuitem>
     <menu label="Email">
       <menuitem label="Gmail" onclick="mail('g')"></menuitem>
       <menuitem label="Hmail" onclick="mail('h')"></menuitem>
       <menuitem label="Imail" onclick="mail('i')"></menuitem>
     </menu>
   </menu>
 </menu>

An app may have only one `menubar` menu. The `menubar` menu may only contain other <menu> elements. Each child of the `menubar` menu specifies a menu in the native menubar.

Conventional Menus and Menuitems

Additional menu types specify conventional menus on desktop platforms:

 <menu type="menubar">
   <menu type="file">
     <menuitem type="new" label="New..." onclick="create()"></menuitem>
     <menuitem type="open" label="Open..." onclick="open()"></menuitem>
     <menuitem type="save" label="Save" onclick="save()"></menuitem>
     <menuitem label="Save to Dropbox..." onclick "saveToDropbox()"></menuitem>
   </menu>
 </menu>

Conventional menus and menuitems appear in the platform-conventional location on platforms on which they are conventional, regardless of the order in which they are specified; and the runtime provides their labels, ignoring any labels the app provides. On desktop platforms where they aren't conventional, they appear as app-defined menus and menuitems, in the order in which they are specified; and the app provides their labels. Apps may mix conventional and app-defined menus and menuitems.

Conventional menu items that are common across Windows/OS X/Linux include: File, Edit, View, Tools and Help.

References

• https://bugzilla.mozilla.org/show_bug.cgi?id=617528
• http://www.w3.org/TR/html5/the-menu-element.html
• http://developer.android.com/guide/topics/ui/menus.html#options-menu
• https://developer.apple.com/library/mac/#documentation/UserExperience/Conceptual/AppleHIGuidelines/Menus/Menus.html#//apple_ref/doc/uid/TP30000356-TP6
• https://developer.apple.com/library/mac/#documentation/UserExperience/Conceptual/AppleHIGuidelines/Characteristics/Characteristics.html#//apple_ref/doc/uid/TP40002721-SW1
• https://bug617528.bugzilla.mozilla.org/attachment.cgi?id=554309
• https://bugzilla.mozilla.org/show_bug.cgi?id=617528