API: menu YAHOO.widget.MenuItem (YUI Library)

# Yahoo! UI Library

### Menu 2.9.0

Yahoo! UI Library > menu > YAHOO.widget.MenuItem
Search:
Filters Show Private Show Protected Show Deprecated

## Class YAHOO.widget.MenuItem

Known Subclasses:
  YAHOO.widget.MenuBarItem YAHOO.widget.ContextMenuItem

Creates an item for a menu.

### Constructor

YAHOO.widget.MenuItem `( p_oObject , p_oConfig )`

Parameters:
  `p_oObject <HTML>` Markup for the menu item content. The markup is inserted into the DOM as HTML, and should be escaped by the implementor if coming from an external source.
  `p_oObject <HTMLLIElement>` Object specifying the `<li>` element of the menu item.
  `p_oObject <HTMLOptGroupElement>` Object specifying the `<optgroup>` element of the menu item.
  `p_oObject <HTMLOptionElement>` Object specifying the `<option>` element of the menu item.
  `p_oConfig <Object>` Optional. Object literal specifying the configuration for the menu item. See configuration class documentation for more details.

### Properties

#### _oAnchor - `private HTMLAnchorElement`

Object reference to the menu item's `<a>` element.
Default Value: null

#### _oHelpTextEM - `private HTMLElement`

Object reference to the menu item's help text `<em>` element.
Default Value: null

#### _oOnclickAttributeValue - `private Object`

Object reference to the menu item's current value for the "onclick" configuration attribute.
Default Value: null

#### _oSubmenu - `private YAHOO.widget.Menu`

Object reference to the menu item's submenu.
Default Value: null

#### _sClassName - `private String`

The current value of the "classname" configuration attribute.
Default Value: null

#### browser - `String`

String representing the browser.
Deprecated: Use YAHOO.env.ua

#### constructor - `YAHOO.widget.MenuItem`

Object reference to the menu item's constructor function.
Default Value: YAHOO.widget.MenuItem

#### CSS_CLASS_NAME - `final String`

String representing the CSS class(es) to be applied to the `<li>` element of the menu item.
Default Value: "yuimenuitem"

#### CSS_LABEL_CLASS_NAME - `final String`

String representing the CSS class(es) to be applied to the menu item's `<a>` element.
Default Value: "yuimenuitemlabel"

#### element - `HTMLLIElement`

Object reference to the menu item's `<li>` element.
Default Value: HTMLLIElement

#### groupIndex - `Number`

Number indicating the index of the group to which the menu item belongs.
Default Value: null

#### id - `String`

Id of the menu item's root `<li>` element. This property should be set via the constructor using the configuration object literal. If an id is not specified, then one will be created using the "generateId" method of the Dom utility.
Default Value: null

#### index - `Number`

Number indicating the ordinal position of the menu item in its group.
Default Value: null

#### parent - `YAHOO.widget.Menu`

Object reference to the menu item's parent menu.
Default Value: null

#### srcElement - `HTMLLIElement| HTMLOptGroupElement|HTMLOptionElement`

Object reference to the HTML element (either `<li>`, `<optgroup>` or `<option>`) used create the menu item.
Default Value: HTMLLIElement|HTMLOptGroupElement|HTMLOptionElement

#### SUBMENU_TYPE - `final YAHOO.widget.Menu`

Object representing the type of menu to instantiate and add when parsing the child nodes of the menu item's source HTML element.

#### value - `Object`

Object reference to the menu item's value.
Default Value: null

### Methods

#### _createKeyListener

`private void _createKeyListener ( type , args , keyData )`
"show" event handler for a Menu instance - responsible for setting up the KeyListener instance for a MenuItem.

Parameters:
  `type <String>` String representing the name of the event that was fired.
  `args <Array>` Array of arguments sent when the event was fired.
  `keyData <Array>` Array of arguments sent when the event was fired.

#### _createRootNodeStructure

`private void _createRootNodeStructure ( )`
Creates the core DOM structure for the menu item.

#### _dispatchClickEvent

`private void _dispatchClickEvent ( )`
Dispatches a DOM "click" event to the anchor element of a MenuItem instance.

#### _dispatchDOMClick

`protected void _dispatchDOMClick ( el )`
Utility method to dispatch a DOM click event on the HTMLElement passed in

Parameters:
  `el <HTMLElement>`

#### _initSubTree

`private void _initSubTree ( )`
Iterates the source element's childNodes collection and uses the child nodes to instantiate other menus.

#### _onSubmenuBeforeHide

`private void _onSubmenuBeforeHide ( p_sType , p_aArgs )`
"beforehide" Custom Event handler for a submenu.

Parameters:
  `p_sType <String>` String representing the name of the event that was fired.
  `p_aArgs <Array>` Array of arguments sent when the event was fired.

#### addClassNameForState

`private void addClassNameForState ( state )`
Applies a class name to a MenuItem instance's <LI> and <A> elements that represents a MenuItem's state - "disabled," "checked," etc.

Parameters:
  `state <String>` String representing a state - "disabled," "checked," etc.

#### blur

`void blur ( )`
Causes the menu item to lose focus and fires the blur event.

#### configChecked

`void configChecked ( p_sType , p_aArgs , p_oItem )`
Event handler for when the "checked" configuration property of the menu item changes.

Parameters:
  `p_sType <String>` String representing the name of the event that was fired.
  `p_aArgs <Array>` Array of arguments sent when the event was fired.
  `p_oItem <YAHOO.widget.MenuItem>` Object representing the menu item that fired the event.

#### configClassName

`void configClassName ( p_sType , p_aArgs , p_oItem )`
Event handler for when the "classname" configuration property of a menu item changes.

Parameters:
  `p_sType <String>` String representing the name of the event that was fired.
  `p_aArgs <Array>` Array of arguments sent when the event was fired.
  `p_oItem <YAHOO.widget.MenuItem>` Object representing the menu item that fired the event.

#### configDisabled

`void configDisabled ( p_sType , p_aArgs , p_oItem )`
Event handler for when the "disabled" configuration property of the menu item changes.

Parameters:
  `p_sType <String>` String representing the name of the event that was fired.
  `p_aArgs <Array>` Array of arguments sent when the event was fired.
  `p_oItem <YAHOO.widget.MenuItem>` Object representing the menu item that fired the event.

#### configEmphasis

`void configEmphasis ( p_sType , p_aArgs , p_oItem )`
Event handler for when the "emphasis" configuration property of the menu item changes.

Parameters:
  `p_sType <String>` String representing the name of the event that was fired.
  `p_aArgs <Array>` Array of arguments sent when the event was fired.
  `p_oItem <YAHOO.widget.MenuItem>` Object representing the menu item that fired the event.

#### configHelpText

`void configHelpText ( p_sType , p_aArgs , p_oItem )`
Event handler for when the "helptext" configuration property of the menu item changes.

Parameters:
  `p_sType <String>` String representing the name of the event that was fired.
  `p_aArgs <Array>` Array of arguments sent when the event was fired.
  `p_oItem <YAHOO.widget.MenuItem>` Object representing the menu item that fired the event.

#### configKeyListener

`void configKeyListener ( p_sType , p_aArgs )`
Event handler for when the "keylistener" configuration property of a menu item changes.

Parameters:
  `p_sType <String>` String representing the name of the event that was fired.
  `p_aArgs <Array>` Array of arguments sent when the event was fired.

#### configOnClick

`void configOnClick ( p_sType , p_aArgs , p_oItem )`
Event handler for when the "onclick" configuration property of the menu item changes.

Parameters:
  `p_sType <String>` String representing the name of the event that was fired.
  `p_aArgs <Array>` Array of arguments sent when the event was fired.
  `p_oItem <YAHOO.widget.MenuItem>` Object representing the menu item that fired the event.

#### configSelected

`void configSelected ( p_sType , p_aArgs , p_oItem )`
Event handler for when the "selected" configuration property of the menu item changes.

Parameters:
  `p_sType <String>` String representing the name of the event that was fired.
  `p_aArgs <Array>` Array of arguments sent when the event was fired.
  `p_oItem <YAHOO.widget.MenuItem>` Object representing the menu item that fired the event.

#### configStrongEmphasis

`void configStrongEmphasis ( p_sType , p_aArgs , p_oItem )`
Event handler for when the "strongemphasis" configuration property of the menu item changes.

Parameters:
  `p_sType <String>` String representing the name of the event that was fired.
  `p_aArgs <Array>` Array of arguments sent when the event was fired.
  `p_oItem <YAHOO.widget.MenuItem>` Object representing the menu item that fired the event.

#### configSubmenu

`void configSubmenu ( p_sType , p_aArgs , p_oItem )`
Event handler for when the "submenu" configuration property of the menu item changes.

Parameters:
  `p_sType <String>` String representing the name of the event that was fired.
  `p_aArgs <Array>` Array of arguments sent when the event was fired.
  `p_oItem <YAHOO.widget.MenuItem>` Object representing the menu item that fired the event.

#### configTarget

`void configTarget ( p_sType , p_aArgs , p_oItem )`
Event handler for when the "target" configuration property of the menu item changes.

Parameters:
  `p_sType <String>` String representing the name of the event that was fired.
  `p_aArgs <Array>` Array of arguments sent when the event was fired.
  `p_oItem <YAHOO.widget.MenuItem>` Object representing the menu item that fired the event.

#### configText

`void configText ( p_sType , p_aArgs , p_oItem )`
Event handler for when the "text" configuration property of the menu item changes.

Parameters:
  `p_sType <String>` String representing the name of the event that was fired.
  `p_aArgs <Array>` Array of arguments sent when the event was fired.
  `p_oItem <YAHOO.widget.MenuItem>` Object representing the menu item that fired the event.

#### configURL

`void configURL ( p_sType , p_aArgs , p_oItem )`
Event handler for when the "url" configuration property of the menu item changes.

Parameters:
  `p_sType <String>` String representing the name of the event that was fired.
  `p_aArgs <Array>` Array of arguments sent when the event was fired.
  `p_oItem <YAHOO.widget.MenuItem>` Object representing the menu item that fired the event.

#### destroy

`void destroy ( )`
Removes the menu item's `<li>` element from its parent `<ul>` element.

#### focus

`void focus ( )`
Causes the menu item to receive the focus and fires the focus event.

#### getClassNameForState

`private void getClassNameForState ( prefix , state )`
Returns a class name for the specified prefix and state. If the class name does not yet exist, it is created and stored in the CLASS_NAMES object to increase performance.

Parameters:
  `prefix <String>` String representing the prefix for the class name
  `state <String>` String representing a state - "disabled," "checked," etc.

#### getNextEnabledSibling

`getNextEnabledSibling ( )`
Finds the menu item's next enabled sibling.

Returns: ``
  YAHOO.widget.MenuItem

#### getNextSibling

`getNextSibling ( )`
Finds the menu item's next sibling.

Returns: ``
  YAHOO.widget.MenuItem

#### getPreviousEnabledSibling

`YAHOO.widget.MenuItem getPreviousEnabledSibling ( )`
Finds the menu item's previous enabled sibling.

#### getPreviousSibling

`YAHOO.widget.MenuItem getPreviousSibling ( )`
Finds the menu item's previous sibling.

#### hasFocus

`Boolean hasFocus ( )`
Returns a boolean indicating whether or not the menu item has focus.

#### init

`void init ( p_oObject , p_oConfig )`
The MenuItem class's initialization method. This method is automatically called by the constructor, and sets up all DOM references for pre-existing markup, and creates required markup if it is not already present.

Parameters:
  `p_oObject <HTML>` Markup for the menu item content. The markup is inserted into the DOM as HTML, and should be escaped by the implementor if coming from an external source.
  `p_oObject <HTMLLIElement>` Object specifying the `<li>` element of the menu item.
  `p_oObject <HTMLOptGroupElement>` Object specifying the `<optgroup>` element of the menu item.
  `p_oObject <HTMLOptionElement>` Object specifying the `<option>` element of the menu item.
  `p_oConfig <Object>` Optional. Object literal specifying the configuration for the menu item. See configuration class documentation for more details.

#### initDefaultConfig

`void initDefaultConfig ( )`
Initializes an item's configurable properties.

#### removeClassNameForState

`private void removeClassNameForState ( state )`
Removes a class name from a MenuItem instance's <LI> and <A> elements that represents a MenuItem's state - "disabled," "checked," etc.

Parameters:
  `state <String>` String representing a state - "disabled," "checked," etc.

#### toString

`String toString ( )`
Returns a string representing the menu item.

### Events

#### blurEvent

`blurEvent ( )`
Fires when the menu item loses the input focus.

#### clickEvent

`clickEvent ( )`
Fires when the user clicks the on the menu item. Passes back the DOM Event object as an argument.

#### destroyEvent

`destroyEvent ( )`
Fires when the menu item's `<li>` element is removed from its parent `<ul>` element.

#### focusEvent

`focusEvent ( )`
Fires when the menu item receives focus.

#### keyDownEvent

`keyDownEvent ( )`
Fires when the user presses a key when the menu item has focus. Passes back the DOM Event object as an argument.

#### keyPressEvent

`keyPressEvent ( )`
Fires when the user presses an alphanumeric key when the menu item has focus. Passes back the DOM Event object as an argument.

#### keyUpEvent

`keyUpEvent ( )`
Fires when the user releases a key when the menu item has focus. Passes back the DOM Event object as an argument.

#### mouseDownEvent

`mouseDownEvent ( )`
Fires when the user mouses down on the menu item. Passes back the DOM Event object as an argument.

#### mouseOutEvent

`mouseOutEvent ( )`
Fires when the mouse has left the menu item. Passes back the DOM Event object as an argument.

#### mouseOverEvent

`mouseOverEvent ( )`
Fires when the mouse has entered the menu item. Passes back the DOM Event object as an argument.

#### mouseUpEvent

`mouseUpEvent ( )`
Fires when the user releases a mouse button while the mouse is over the menu item. Passes back the DOM Event object as an argument.

### Configuration Attributes

#### checked `- Boolean`

Boolean indicating if the menu item should be rendered with a checkmark.
Default Value: false

#### classname `- String`

CSS class to be applied to the menu item's root `<li>` element. The specified class(es) are appended in addition to the default class as specified by the menu item's CSS_CLASS_NAME constant.
Default Value: null

#### disabled `- Boolean`

Boolean indicating if the menu item should be disabled. (Disabled menu items are dimmed and will not respond to user input or fire events.)
Default Value: false

#### emphasis `- Boolean`

Boolean indicating if the text of the menu item will be rendered with emphasis.
Deprecated Use the "text" configuration property to add emphasis. For example: `oMenuItem.cfg.setProperty("text", "<em>Some Text</em>");`
Default Value: false

#### helptext `- HTML| HTMLElement`

String or markup specifying additional instructional text to accompany the text for the menu item. The helptext is inserted into the DOM as HTML, and should be escaped by the implementor if coming from an external source.
Deprecated Use "text" configuration property to add help text markup. For example: `oMenuItem.cfg.setProperty("text", "Copy <em class=\"helptext\">Ctrl + C</em>");`
Default Value: null

#### keylistener `- Object`

Object literal representing the key(s) that can be used to trigger the MenuItem's "click" event. Possible attributes are shift (boolean), alt (boolean), ctrl (boolean) and keys (either an int or an array of ints representing keycodes).
Default Value: null

#### onclick `- Object`

Object literal representing the code to be executed when the item is clicked. Format:
`{
fn: Function, // The handler to call when the event fires.
obj: Object, // An object to pass back to the handler.
scope: Object // The object to use for the scope of the handler.
}`
Default Value: null

#### selected `- Boolean`

Boolean indicating if the menu item should be highlighted.
Default Value: false

#### strongemphasis `- Boolean`

Boolean indicating if the text of the menu item will be rendered with strong emphasis.
Deprecated Use the "text" configuration property to add strong emphasis. For example: `oMenuItem.cfg.setProperty("text", "<strong> Some Text</strong>");`
Default Value: false

#### submenu `- Menu|String|Object| HTMLElement`

Object specifying the submenu to be appended to the menu item. The value can be one of the following:

- Object specifying a Menu instance.
- Object literal specifying the menu to be created. Format: `{ id: [menu id], itemdata: [array of values for items] }`.
- String specifying the id attribute of the `<div>` element of the menu.
- Object specifying the `<div>` element of the menu.

Default Value: null

#### target `- String`

String specifying the value for the "target" attribute of the menu item's anchor element. Specifying a target will require the user to click directly on the menu item's anchor node in order to cause the browser to navigate to the specified URL. When building a menu from existing HTML the value of this property will be interpreted from the menu's markup. The target is inserted into the DOM as an attribute value, and should be escaped by the implementor if coming from an external source.
Default Value: null

#### text `- HTML`

String or markup specifying the text label for the menu item. When building a menu from existing HTML the value of this property will be interpreted from the menu's markup. The text is inserted into the DOM as HTML, and should be escaped by the implementor if coming from an external source.
Default Value: ""

#### url `- String`

String specifying the URL for the menu item's anchor's "href" attribute. When building a menu from existing HTML the value of this property will be interpreted from the menu's markup. Markup for the menu item content. The url is inserted into the DOM as an attribute value, and should be escaped by the implementor if coming from an external source.
Default Value: "#"

Copyright © 2011 Yahoo! Inc. All rights reserved.