webuijsf
Tag menu


     The webuijsf:menu tag is used to display a set of selectable items in the form of a  pop-up menu.
     The options to be displayed can be specified using the "items" attribute of the component.
     Each option should be represented by a com.sun.webui.jsf.model.Option instance.
     Options can also be grouped together based on some functionality in which case, the 
     com.sun.webui.jsf.model.OptionGroup should be used to specify the options.
  
     The popupMenu will not be visible by default, but can be shown by calling the open
     method on the popupMenu widget when any of the components on the page is clicked.
     The open method used to display the pop-up menu takes an event attribute as an argument. This "event" attribute 
     is the event that is generated when a keyboard or mouse action  happens on the web page
     such as clicking a hyperlink. If the style attribtute with menu positioning is defined, 
     the popupMenu widget will use that to position itself on the page. If not, it will use the event attribute
     which is passed on as an argument. Clicking an option or clicking anywhere inside the page
     will cause the menu to close. If another menu is opened, then any open menu 
     will close so that only one menu can be open at any given time. Note that a pop-up menu is not
     associated with any component present in the page. Hence, the same menu can be used along with different
     components present in the page. Note however, that in any case only the last selected item will be
     maintained with the menu irrespective of the number of components it is used with.

     Each option is uniquely identified by the value assigned to it. Hence, the value assigned to each
     option has to be unique among the whole list of options including groups. The labels however may contain
     duplicate values depending on the needs.
      
     Whenever an option is clicked, you can access the selected option through the getSelectedValue interface
     available on the menu's DOM element. This is the default behavior of the menu element.
     The default behavior does not have any form of communication with the server to inform of the selected state.
     If a communication needs to be made to the server to inform of the selected value of the popupMenu component
     then 
     
  i) Use domNode.submit(). The menu element has a submit() function set on its DOM. Invoking this function
     will cause the menu widget to send an asynchronous request to the server causing the menu component
     to update itself. The menu widget in this case appends an attribute called value to the dynamic faces
     request made. The com.sun.webui.jsf.renderkit.ajax.MenuRenderer will in this case look for 
     this particular value and update itself accordingly.
  
  ii) Set the submitForm attribute to true. This will cause the menu component to submit the form whenever an
     option is selected in the menu. All the elements in the form will be submitted and all the components present
     in the form will go through the normal JSF processing lifecycle. 
     The menu widget in this case will submit the value of the selected option similar to the way the hyperlink widget
     submits the form. It will append the selected value as a request parameter with the key being the client id of 
     the menu appended with a "_submittedValue" suffix.
  
  NOTE:- 
   To obtain the value of the option that was clicked in the menu widget, use the eventListenerExpression attribute
   and invoke the getSelectedOption method on the ValueEvent object that is passed as an argument to this method binding


Facets

None.

Theme Identifiers

None.


Client Side Javascript Functions

When the menu component is rendered, a DOM object corresponding to the menu component is created. To manipulate the menu component on the client side, you may call functions on the DOM object.

JavaScript Function Description
getProps() Use this function to get widget properties. Please see setProps() function for a list of supported properties.
refresh(execute)
Use this function to asynchronously refresh the component.
  • [optional] execute: Comma separated string containing a list of client ids against which the execute portion of the request processing lifecycle must be run.
setProps(props) Use this function to change any of the following supported properties:
  • accessKey
  • className
  • dir
  • id
  • onBlur
  • options
  • onClick
  • onDblClick
  • onFocus
  • onKeyDown
  • onKeyPress
  • onKeyUp
  • onMouseDown
  • onMouseOut
  • onMouseOver
  • onMouseUp
  • onMouseMove
  • submitForm
  • style
  • title
  • visible

submit(execute)
Use this function to asynchronously submit the component..
  • [optional] execute: Comma separated string containing a list of client ids against which the execute portion of the request processing lifecycle must be run. If omitted, the component on which the function has been invoked, is submitted.
getSelectedValue()
Use to get the selected item in the menu.
open(event) Available if you have set the popup attribute to true. In this case, you can invoke a menu for a particular component when it is clicked by calling the open function on the menu. The event object that is generated when the click event happens is to be passed on as argument.
close Invoke in order to close the menu at any time.

Client Side JavaScript Events

When the component is manipulated on the client side, some functions may publish event topics for custom Ajax implementations to listen for. Using the Dojo event system, listen for the refresh event topic using:

<webuijsf:script>
    var processEvents = {                       
        update: function(props) {
            // Do something...
        }
    }

    // Subscribe to refresh event.
   
// For popupMenu widgets (popup = true) it would be dojo.subscribe(webui.suntheme.widget.popupMenu.<eventname>.endTopic, processEvents, "update");


</webuijsf:script>

JavaScript Event Description
webui.suntheme.widget.popupMenu.event.refresh.beginTopic Event topic published before asynchronously refreshing the popupMenu widget. Supported properties include:
  • [optional] execute - list of the components to be executed along with this component
  • id - The client id to process the event for
webui.suntheme.widget.popupMenu.event.refresh.endTopic

Event topic published after asynchronously refreshing the popupMenu widget. Supported properties include:

  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage
webui.suntheme.widget.popupMenu.event.submit.beginTopic Event topic published before asynchronously submitting the popupMenu widget. Supported properties include:
  • [optional] execute - list of the components to be executed along with this component
  • id - The client id to process the event for
webui.suntheme.widget.popupMenu.event.submit.endTopic

Event topic published after asynchronously submitting the popupMenu widget. Supported properties include:

  • props - JSON object containing messages (if any) raised by the server.

Code Examples

Example 1: Creating a Pop-Up Menu

<webuijsf:actionenu id="popup1" items="#{popUp.optionItems1}" eventListener="#{popUp.selectedItem}"  onChange="setTimeout('changeEvent();', 0);"/>
         <webuijsf:textField id="verifier" label="Selected item:" text="#{popUp.selectedItem}" disabled="true"/>

<webuijsf:button id="button3" style="position:absolute;top:400px;left:600px" text="Change option for this menu" onClick="clientUpdate();return false;"/> <script type="text/javascript"> function changeEvent() { document.getElementById("form1:popup1").submit(); // submit the selected value var domNode = document.getElementById("form1:verifier"); domNode.refresh(); // show the selected value in a text field. } function changeDisabled() { var menu = document.getElementById("form1:popup1"); if (menu != null) { var options = menu.getProps().options; options[0].disabled = !options[0].disabled; menu.setProps({options:options}); } } </script>

Backing Bean for the Above Menu

        public class PopUp {
        private Option OptionItems[];
        private Option groupOptions[];
    
        public PopUp() {
        OptionItems = new Option[5];
        OptionItems[0] = new Option("Copy", "Copy");
        OptionItems[0].setSeparator(true);
        OptionItems[0].setImage("/images/copy.gif");
        OptionItems[1] = new Option("Paste", "Paste");
        OptionItems[1].setImage("/images/paste.gif");        
        OptionItems[1].setSeparator(true);
        OptionItems[2] = new Option("Undo", "Undo");
        OptionItems[2].setSeparator(true);
        OptionItems[4] = new Option("Print", "Print");
        OptionItems[4].setSeparator(true);
        OptionItems[4].setDisabled(true);
        groupOptions = new Option[2];
        groupOptions[0] = new Option("Ascending", "Ascending");
        groupOptions[1] = new Option("Descending", "Descending");        
        group = new OptionGroup();
        group.setValue("Sort");
        group.setLabel("Sort By");
        group.setOptions(groupOptions);
        OptionItems[3] = group;
        OptionItems[3].setSeparator(true);        
        }
        
    public Option[] getOptionItems() {
        return this.OptionItems;
    }

    public void setOptionItems(Option[] OptionItems) {
        this.OptionItems = OptionItems;
    }
    
    public String getSelectedItem() {
        return this.text;
    }
    
    public void setSelectedItem(String text) {
        this.text = text;
    }
    
    public String selectedAction() {
        if(outcome.equalsIgnoreCase("Copy")) {
            return "indexPage";
        }
        if(outcome.equalsIgnoreCase("Paste")) {
            return "hyperlinkPage";
        }        
        return null;
    }
    
    public void selectOption(com.sun.webui.jsf.event.ValueEvent ae) {
        this.text = ae.getSelectedOption();
        outcome = text;
    }
    
    


Tag Information
Tag Classcom.sun.webui.jsf.component.MenuTag
TagExtraInfo ClassNone
Body ContentJSP
Display NameNone

Attributes
NameRequiredRequest-timeTypeDescription
bindingfalsefalsejava.lang.String A ValueExpression that resolves to the UIComponent that corresponds to this tag. This binding allows the Java bean that contains the UIComponent to manipulate the UIComponent, its properties, and its children.
submitFormfalsefalsejava.lang.String

When set to true, the form is immediately submitted when the user changes the selection in the menu.

onMouseDownfalsefalsejava.lang.String

Scripting code executed when the user presses a mouse button while the mouse pointer is on the component.

onDblClickfalsefalsejava.lang.String

Scripting code executed when a mouse double click occurs over this component.

onKeyPressfalsefalsejava.lang.String

Scripting code executed when the user presses and releases a key while the component has focus.

onMouseOutfalsefalsejava.lang.String

Scripting code executed when a mouse out movement occurs over this component.

renderedfalsefalsejava.lang.String Use the rendered attribute to indicate whether the HTML code for the component should be included in the rendered HTML page. If set to false, the rendered HTML page does not include the HTML for the component. If the component is not rendered, it is also not processed on any subsequent form submission.
idfalsetruejava.lang.StringNo Description
onMouseOverfalsefalsejava.lang.String

Scripting code executed when the user moves the mouse pointer into the boundary of this component.

htmlTemplatefalsefalsejava.lang.String

Alternative HTML template to be used by this component.

onKeyUpfalsefalsejava.lang.String

Scripting code executed when the user releases a key while the component has focus.

onMouseMovefalsefalsejava.lang.String

Scripting code executed when the user moves the mouse pointer while over the component.

onMouseUpfalsefalsejava.lang.String

Scripting code executed when the user releases a mouse button while the mouse pointer is on the component.

styleClassfalsefalsejava.lang.String

CSS style class or classes to be applied to the outermost HTML element when this component is rendered.

itemsfalsefalsejava.lang.String

Specifies the items that the web application user can choose from. The value must be one of an array, Map or Collection whose members are all subclasses ofcom.sun.webui.jsf.model.Option.

onChangefalsefalsejava.lang.String

Scripting code executed when the element value of this component is changed.

stylefalsefalsejava.lang.String

CSS style or styles to be applied to the outermost HTML element when this component is rendered.

visiblefalsefalsejava.lang.String

Use to indicate whether the component should be viewable by the user in the rendered HTML page. If set to false, the HTML code for the component is present in the page, but the component is hidden with style attributes. By default,this setting is false, so HTML for the component HTML is rendered but the menu is not visible to user. Note that, even If the component is not visible, it can still be processed on subsequent form submissions because the HTML is present.

onKeyDownfalsefalsejava.lang.String

Scripting code executed when the user presses down on a key while the component has focus.

onClickfalsefalsejava.lang.String

Scripting code executed when a mouse click occurs over this component.The Menu element has a function called getSelectedOption which can be invoked by onClick function handlers to know which option has been selected. This will return the name of the option that was clicked.

immediatefalsefalsejava.lang.String

The immediate flag. If set to true, the processing of the menu's event will happen ahead of processing other validators and converters present in the page whose components' immediate attributes are not set to true. Tihs attribute will be meaningful only if a page submit occurs (i.e. submitForm attribute set to true)

phaseIdfalsefalsejava.lang.String The PhaseId in which events should be broadcast. The default is PhaseId.INVOKE_APPLICATION or PhaseId.ANY if isImmediate returns true
eventListenerExpressionfalsefalsejava.lang.String

Used to specify a method to handle an menu event that is triggered when this component is activated by the user. Value must be a JavaServer Faces EL expression that resolves to a method in a backing bean. The method must take a single parameter that is an event, and its return type must be void. The class that defines the method must implement the java.io.Serializable interface or javax.faces.component.StateHolder interface.

eventExpressionfalsefalsejava.lang.String

The {@link MethodExpression} that, when invoked, yields a literal outcome value.


Variables
No Variables Defined.


Output Generated by Tag Library Documentation Generator. Java, JSP, and JavaServer Pages are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries. Copyright 2002-4 Sun Microsystems, Inc. 4150 Network Circle Santa Clara, CA 95054, U.S.A. All Rights Reserved.