PopupMenu |
||||||||||||||||||||||||||||
Developer’s Guide Home
Installation and Configuration Common Concepts Components Index Border Layout Panel Calendar Chart Command Button Command Link Confirmation Data Table Date Chooser Day Table Drop Down Field Dynamic Image Folding Panel For Each Graphic Text Hint Label Input Text Input Textarea Layered Pane Popup Layer Popup Menu Select Boolean Checkbox Select Many Checkbox Select One Radio Spinner Suggestion Field Tabbed Pane Tab Set Tree Table Two List Selection Window Focus Load Bundle Scroll Position Ajax Framework Validation Framework Tag Reference API Reference |
Key Features
Basic UsageThe simplest way to create a PopupMenu component is to place the <o:popupMenu> tag into a component to which the PopupMenu should be attached. This will make the PopupMenu to be shown when the user clicks the right mouse button over the parent component (that is the menu is attached to the parent's "contextmenu" event by default). The parent component's event which should invoke the popup menu can be customized using the event attribute of the <o:popupMenu> tag. Popup menu's items are specified by placing one or more <o:menuItem> tags into the <o:popupMenu> tag. Here's a simple example of declaring the PopupMenu component for a <h:panelGroup> component: <h:panelGroup id="itemView" ...> <o:popupMenu> <o:menuItem value="Select Item" onclick="selectItem();"/> <o:menuItem value="Unselect Item" onclick="unselectItem();"/> <o:menuSeparator/> <o:menuItem value="Update This View" action="#{MyBean.updateView}" render="itemView"/> <o:menuSeparator/> <o:menuItem value="Show Main View" action="#{MyBean.showMainView}"/> </o:popupMenu> ... </h:panelGroup> As you can see from the example above, using <o:menuItem> is very similar to using ordinary command components such as <h:commandButton> or <h:commandLink> – the text displayed in the item is specified with the value attribute, and you can define the menu item activation event handler in different ways:
You can turn on the Ajax mode and configure the button to reload the specified set of components instead of reloading the whole page by specifying its render attribute. This attribute is specified as a space-separated list of component Ids in the same way as the render attribute of the Ajax component. Specifying this attribute will also make action and/or actionListener specified for the button to be executed during the Ajax request as well. If the Ajax mode is turned on for the button it doesn't submit data for form's components for processing on the server by default, so if you'd like to include some particular components into the Ajax request, for their data to be available during action execution or be saved through bindings, you can specify the execute attribute. Like the action attribute, this attribute is specified as a space-delimited list of component Ids in the same way as for the Ajax component. The separator between menu items can be specified with the <o:menuSeparator> tag. Besides using the PopupMenu component with mouse, it allows item navigation with Up/Down keys, sub-menu navigation with Left/Right keys and item selection with the Enter key. Among the other frequently-used ways of customizing the PopupMenu are the possibilities to add sub-menus, place the icon besides a menu icon, and specify a non-text item content. Sub-menu can be added just by placing another <o:popupMenu> tag inside of the appropriate <o:menuItem> tag. The iconUrl attribute specified for the <o:menuItem> tag lets you specify the icon that should be displayed in the menu's indent area to the left of the menu item. And finally, in cases when you need to specify a more sophisticated item's content than just plain text, which might be required to fulfill some specific design requirements, you can skip using the value attribute, and specify any components that should be displayed in a menu item as child tags for the <o:menuItem> tag. Here's an example that shows declaring a menu with sub-menus, icons besides menu items, and the content of the root items displayed with images instead of text. <o:popupMenu> <o:menuItem> <o:graphicImage url="icons/new.png"> <o:popupMenu> <o:menuItem iconUrl="icons/newItem.png" value="Item" onclick="newItem();"/> <o:menuItem iconUrl="icons/newCategory.png" value="Category" onclick="newCategory();"/> </o:popupMenu> </o:menuItem> <o:menuItem> <o:graphicImage url="icons/edit.png"> <o:popupMenu> <o:menuItem iconUrl="icons/cut.png" value="Cut" onclick="cut();"/> <o:menuItem iconUrl="icons/copy.png" value="Copy" onclick="copy();"/> <o:menuItem iconUrl="icons/paste.png" value="Paste" onclick="paste();"/> </o:popupMenu> </o:menuItem> <o:menuSeparator/> <o:menuItem> <o:graphicImage url="icons/editItem.png"> </o:menuItem> <o:menuItem> <o:graphicImage url="icons/deleteItem.png"> </o:menuItem> </o:popupMenu> There are also some attributes that define certain aspects of PopupMenu's behavior. The disabled attribute of <o:menuItem> tag allows disabling a menu item so that it cannot be activated by the user. The submenuShowDelay and submenuHideDelay attributes of <o:popupMenu> tag allow customizing the period between mouse movement over (or out) the parent menu item and automatic menu showing (or hiding). These values are specified in milliseconds and the default value for both is 500, which corresponds to a half of a second. You can turn off automatic sub-menu showing and/or hiding by specifying -1 in the appropriate attribute(s). The Three Invocation ModesAs it was described in the previous section, the simplest way of invoking the PopupMenu is binding it for automatic invocation by placing it into a component for which it should be invoked. By default, the PopupMenu will be invoked when "contextmenu" event is triggered into the parent component, which basically means showing the PopupMenu on right mouse click (or via ctrl-click in Opera browser where right mouse click cannot be intercepted). The event to which the PopupMenu is attached can be customized with the event attribute of <o:popupMenu> tag. Be sure to specify the event name without the "on" prefix, for example you should use the "click" value instead of "onclick", like this: <h:panelGroup ...>
<o:popupMenu event="click">
...
</o:popupMenu>
...
</panelGroup>
Albeit simple, the first approch of automatic PopupMenu binding by adding it inside of a component works only for JSF components and can't be used if you need to bind a PopupMenu to an HTML tag that is just part of page's markup and is not a JSF component. The second way of how PopupMenu invocation can be configured is placing the <popupMenu> tag outisde of the component or HTML element to which it should be attached, and referring that component/element by declaring the for attribute of the <popupMenu> tag. The for attribute should be assigned with the id of a JSF component or id of any HTML element, whose event should be listened to. Here's a formal description of how this attribute should be defined:
And finally, there's one more way of invoking the PopupMenu component called a "standalone" invocation mode, where a PopupLayer can be declared anywhere on the page and then shown programmatically using client-side API, which provides the full control over how and when the PopupLayer should be shown and/or hidden. This mode is turned on by declaring the standalone attribute with a value of "true". Doing so turns off automatic PopupMenu binding to a parent component (or a component referred to by the for attribute). The PopupMenu in the standalone mode can be shown using one of the following methods: show(), showAtXY(x, y), or showForEvent(event). You can choose the method that suits the desired PopupMenu positioning algorithm (see the Client-Side API section for the description of these methods). Regardless of the mode, the PopupMenu is hidden automatically when a menu item is chosen, Esc pressed, or mouse clicked outside of the PopupMenu, and it's also possible to hide the PopupMenu programmatically with the client-side hide() function. Study the Client-Side API section for the full list of methods that can be used to inspect and manipulate the state of the PopupMenu component. Customizing Menu AppearanceBy default, a PopupMenu displays an indent area on the left of the menu for menu item icons. Visibility for the indent area can be customized using the indentVisible attribute of the <o:popupMenu> tag, and its style is customized with the indentStyle/indentClass attributes. You can learn the full set of customization options by readingthe tag library documentation for <o:popupMenu>, <o:menuItem> and <o:menuSeparator>. Client-Side APIAll client-side API methods are listed in the following table:
|
|||||||||||||||||||||||||||
© 2009 TeamDev Ltd. | ![]() |