Menu item

Adds an item to a JSFMenu.

A JSFmenu is populated with JSFMenuItems. JSFMenuItems are added to a JSFMenu to form the top-level menu of a menu bar. JSFMenuItems are added to other JSFMenuItems to form sub-menus. A menu is all the JSFMenuItems that share the same parent.

A JSFMenuItem can be:
  • Any span or span-equivalent (for example a link) or table defined within the containing form. The item is moved into the menu.
  • A span or span-equivalent or table specified as an attribute to the constructor (the span/table is created by the constructor and moved into the menu).
  • A separator (which can be graphical or textual or both).

A JSF menu bar is defined by one JSFMenu component and one or more JSFMenuItem components. Each item in the menu bar is defined by one JSFMenu item.

A menu item is added to the page as a subcomponent, that is, as a child of another component. A menu is all the menu items that share the same parent. A menu item may be added to either a JSFMenu or to a JSFMenuItem component. Menu items added to a JSFMenu form the top or main menu. Items added to other JSFMenuItem components form submenus.

Menu items are added to the page using the hX_5.addSubComponent call. The call has two forms:
hX_5.addSubComponent("parent-id", "this-id",  new hX_5.JSFMenuItem(attributes), position);
or
hX_5.addSubComponent("parent-id", [new hX_5.JSFMenuItem(attributes), new hX_5.JSFMenuItem(attributes), ...]);

With the first form, you specify the parent and specify the ID to be assigned to this menu item. In the second form, you specify the parent and multiple menu items. The ids for the menu items are generated by appending -1, -2, -3, to the parent ID. With either form, menu items are added to the menu in the order specified, the first add call adds the first item to the menu, the second call adds the second item. Explicit control over where the item is added is possible with the first syntax (only) by adding a fourth argument that specifies the zero-based position for the item in the menu. A menu item can be removed from a menu using the hX_5.removeSubComponent call (this is deprecated).

The content of a menu item can be supplied three different ways:
  1. As a string of text or HTML.
  2. As the ID of a tag elsewhere within the form that is to be used as the item.
  3. As a string of text or HTML designated to be used as a separator.

Note that the second form (using an ID) should be used if the menu bar is made up of JSF components as JSF tag may emit multiple lines of HTML.

In any case, the HTML that is supplied should be either a run of inline HTML (for example spans, images, and link) or a table. The HTML may also define an HTML button. HTML that defines other forms of input and select may render correctly but it will generally not respond correctly to mouse/keyboard actions.

Each menu item will behave as either a parent, a leaf, or a separator. A separator does not respond to the mouse/keyboard actions. Both parent and leaf items responds to the mouse/keyboard. When you click/mouse on a parent item, the corresponding submenu is displayed (that is, a parent is an item that has other items added to it). When you click on a leaf, an action is taken. The most common action is to go to a specified page.

If you define a menu item by specifying a string of text or HTML and it is a leaf, you supply the action to be taken by specifying the JSF action to be taken (for example, GOTO) and the target of the action (for example, url('index.jsp')). Alternatively you can specify a JavaScriptâ„¢ function to be called. If you define a menu item by specifying the ID of a tag elsewhere on the page, the specified tag should know how to respond to a click. For example, it could be an <a> tag or a <span> with an onclick event handler.

Normally a parent item does not have an assigned action. Normally a leaf item has an assigned action. If a parent item has an action assigned to it, it will first behave like a parent (the submenu displayed) and then as an action (if clicked). The action-click parameter can be used to override this behavior and force the parent to only perform the action (useful if the action is going to go to another page or submit).

JSF tags that emit the component

Base HTML

  • none
  • <a id="id">
  • <input type="submit" id="id">
  • <input type="reset" id="id">
  • <input type="button" id="id">
  • <img src="src" id="id">
  • any container tag such as <div id="id"><span id="id"> or <table id="id"> that contains the above and/or text

All attributes set on the base tag are supported.

As a rule, event handlers associated with the tag are not supported. However, a behavior can be attached to the onclick event.

JavaScript constructor

hX_5.addSubComponent("parent-id", "this-id", new hX_5.JSFMenuItem(attributes), position); or hX_5.addSubComponent("parent-id", [new hX_5.JSFMenuItem(attributes), new hX_5.JSFMenuItem(attributes), ...]); where

parent-id

ID of the JSF Component that is the parent of this subcomponent.

this-id

The ID to give to this ID. Must be unique within the page.

attributes

Comma separated list of attributes where each attribute is a quoted string consisting of the attribute name and value separated by a colon, for example "label:MyLabel".

position

Position of this subcomponent relative to other subcomponents with the same parent. If omitted, the subcomponent is appended.

When using the second syntax to add multiple items with one call, the added items are assigned the IDs made by appending "-1" (-2, -3, -4, ...) to the parent ID.

Attributes

Table 1. Menu item attributes

Attribute name

Description

label

The text to display for the object.

separator

Indicates this menu item is a non-clickable separator. If no value is provided, a an empty table cell is rendered (which can be styled to look like a line or box). Alternatively, simple text or in-line HTML can be provided which is rendered in the table cell. Either a label or a separator or an item must be provided.

item

The ID of an inline HTML tag or table tag located within the form that contains the menu. The tag (and its children) are moved into the menu item. For JSF components (which may emit multiple HTML tags), this is the recommended way of specifying a menu item. Either a label or a separator or an item must be provided.
Note: To reduce flicker on the page, items that are going to be moved into menu items should be enclosed in an absolutely positioned div with the style set to display:none.

disabled

Specifies if the object is available.

alt-class

Specifies that the alternate class should be used to style this menu item. This allows for items in a menu to have different styles.

onchange

If provided, the function is called whenever a leaf is clicked (an action is taken). The function is called after the menu item is clicked (for example, if the menu item is a link, the link will be clicked and then this function called). The function should have the usual signature function(thisObj, thisEvt). thisObj will always refer to the div that represents the menu bar. The menu-item ID of the item which was selected (last clicked) can be found in the event object as thisEvt.objSelected or if the selection hidden field is on the page, it can equally be retrieved from the value of this field.

action

An action (or a set of actions) to be performed when a click-able entity is clicked. A target for the action (or a set of targets) are normally required.

target

If supplied, the ID of an input type='text' field in the page. Whenever something is selected in the menu, the text of the menu item is set as the value of the specified field. This is normally only used when making a popup menu which is emulating a combo-box (that is you have an input field with an adjacent menu where the top-level of the menu is a single button, clicking the button displays the menu, choosing an item from the menu sets the value of the input field.)

action-click

A menu item is either a parent or a leaf. A parent menu item is a menu item that has an associated submenu (the sub--menu is displayed when the menu item is moused/clicked). A leaf menu item does not have an associated submenu, instead it should be something which responds to a click event (for example, a link). If a menu-item is created using an item, if it is a leaf, then the item should be something that will respond to a click (for example, a link or button). If a menu-item is created using a label and an onchange or action is provided, it will be treated as a link (the label will be automatically enclosed in an <a> tag and the provided function/action will be run when the item is clicked. It is possible to define a menu item that is both a parent and a leaf. For example, if the menu item is a label and has an action associated with it and has a submenu defined for it, it is both a parent and a leaf. Similarly, if a menu item is an item and the item is a link and the menu item has a submenu defined for it, it is both a parent and a leaf. When an item is both a parent and a leaf, when a user clicks on the item, the submenu will be displayed and then the action will be run. If action-click is specified, when an item is both a parent and a leaf, the submenu will not be displayed, instead, only the action will be run. This attribute should be set whenever the action of the leaf will cause a submit so as to prevent the submenu from opening just before the submit occurs.

CSS classes

None. CSS is specified on the JSFMenu component.

API calls

Table 2. Menu item API calls

API call

Description

object = setAttribute(attribute)

Sets an attribute or changes its value (if it was set previously).

string = getAttribute(attribute-name)

Retrieves the current value of an attribute.

Limitations


Feedback