webuijsf


Standard Syntax:
     <%@ taglib prefix="webuijsf" uri="http://www.sun.com/webui/webuijsf" %>

XML Syntax:
     <anyxmlelement xmlns:webuijsf="http://www.sun.com/webui/webuijsf" />

No Description

Tag Library Information
Display NameNone
Version1.1
Short Namewebuijsf
URIhttp://www.sun.com/webui/webuijsf
 

Tag Summary
accordion

Use the webuijsf:accordion tag to display an accordion component in the rendered HTML page. Think of an accordion as a vertical tab set. This set can contain one or more tabs each of which can contain virtually any HTML markup and have the following characteristics:

  • Each tab contains links to different sections(tasks) of the application.
  • Only one accordion tab can be open at any given time.
The accordion component, however, allows muliple tabs to be open simultaneously. Note: use an alternate navigational component if the number of tabs in the accordion are exceeding ten. The accordion tag also supports "expandAll" and "collapseAll" icons. An accordion can be refreshed if the application using it supports this function. Each attribute of the accordion is described in detail in the TLD document.

Unless otherwise specified the accordion dows not display the expand all, collapse all and refresh icons. To display these icons, set the toggleControls and refreshIcon attributes to true.

Facets

None.

Theme Identifiers

None.

Client Side Javascript Functions

When the Accordion component is rendered, a DOM object corresponding to the Accordion component is created. To manipulate the accordion component on the client side, you can call functions on the DOM object. To disable the component, call document.getElementById(id).setProps({multipleSelect: true}).

Function Description
getProps() Use this function to get widget properties. 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 ID 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:
  • collapseAllImage
  • expandAllImage
  • loadOnSelect
  • multipleSelect
  • refreshImage
  • tabs
  • toggleControls
  • type
  • style
  • styleClass
  • visible

subscribe(topic, obj, func) Use this function to subscribe to an event topic.
  • topic: The event topic to subscribe to.
  • obj: The object in which a function will be invoked, or null for default scope.
  • func The name of a function in context, or a function reference to invoke when topic is published.

Client Side JavaScript Events

When the accordion component is manipulated client-side, some functions may publish event topics for custom AJAX implementations to listen for. For example, you can listen for the refresh event topic by using:

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

    // Subscribe to refresh event.
    var domNode = document.getElementById("form1:test1");
    domNode.subscribe(domNode.event.refresh.endTopic, processEvents, "update");


</webuijsf:script>

The following events are supported.

Event Description
<Node>.event.refresh.beginTopic Event topic published before asynchronously refreshing the component. 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
<Node>.event.refresh.endTopic Event topic published after asynchronously refreshing the component. Supported properties include: See setProps() function.
  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage

Code Examples

Example 1: Accordion as a navigational Element.

In this example, the component is used for navigational purposes.

       <webuijsf:accordion id="acc1" style="width:70%">

<webuijsf:accordionTab id="tab1" label="Buttons and links" >
<webuijsf:hyperlink id="hyper1" text="Button Examples"
url="/faces/button/index.jsp"
target="rightFrame"/>
<br/>
<webuijsf:hyperlink id="hyper2" text="Link Examples"
url="/faces/hyperlink/index.jsp"
target="rightFrame"/>
<br/>
<webuijsf:hyperlink id="hyper3" text="Image Link Examples"
url="/faces/imagehyperlink/index.jsp"
target="rightFrame"/>
</webuijsf:accordionTab>

<webuijsf:accordionTab id="tab2" label="Input Elements" >
<webuijsf:hyperlink id="hyper1" text="CheckBoxes"
url="/faces/clientsideCheckbox/checkbox.jsp"
target="rightFrame"/>
<br/>
<webuijsf:hyperlink id="hyper2" text="CheckBox group"
url="/faces/clientsideCheckbox/index.jsp"
target="rightFrame"/>
<br/>
<webuijsf:hyperlink id="hyper3" text="Radio Button Group"
url="/faces/clientsiderbcbGroup/index.jsp"
target="rightFrame"/>
</webuijsf:accordionTab>

<webuijsf:accordionTab id="tab3" label="label1" >
<webuijsf:hyperlink id="hyper1" text="Calendar"
url="/faces/calendar/index.jsp"
target="rightFrame"/>
</webuijsf:accordionTab>

</webuijsf:accordion>

Example 2: TBD

This example shows the how Ajax is used to refresh the accordion component as a whole or simply a single AccorionTab.

<webuijsf:accordion id="acc1" toggleControls="true" refreshIcon="true">
         
                   <webuijsf:accordionTab id="tab1" title="#{msgs.accordion_tab1}" 
                     contentHeight="50px" > 
                     <webuijsf:staticText binding="#{AccordionBean.text1}"/> 
                   </webuijsf:accordionTab> 
<webuijsf:accordionTab id="tab2" title="#{msgs.accordion_tab2}" contentHeight="50px"> <webuijsf:staticText binding="#{AccordionBean.text2}"/> </webuijsf:accordionTab >
<webuijsf:accordionTab id="tab3" title="#{msgs.accordion_tab3}" contentHeight="50px" > <webuijsf:staticText binding="#{AccordionBean.text3}"/> </webuijsf:accordionTab >
<webuijsf:accordionTab id="tab4" title="#{msgs.accordion_tab4}" contentHeight="50px" > <webuijsf:staticText binding="#{AccordionBean.text4}"/> </webuijsf:accordionTab >
</webuijsf:accordion >
<webuijsf:script > function refreshAccordion1() { var acc = document.getElementById("accordionExample:acc1:tab1"); acc.refresh("accordionExample:acc1:tab1"); return false; } </webuijsf:script >

The corresponding backing bean.

public class AccordionBackingBean { 
    
    public final static String SHOW_ACCORDION = "showAccordionIndex"; 
/** Creates a new instance of AccordionBackingBean */ public AccordionBackingBean() { }
public StaticText text1 = new StaticText(); public StaticText text2 = new StaticText(); public StaticText text3 = new StaticText(); public StaticText text4 = new StaticText();
public StaticText getText1() { this.text1.setText(getTime()); return text1; }
public void setText1(StaticText text1) { this.text1 = text1; this.text1.setText(getTime()); }
public StaticText getText2() { this.text2.setText(getTime()); return text2; }
public void setText2(StaticText text2) { this.text2 = text2; this.text2.setText(getTime()); }
public StaticText getText3() { this.text3.setText(getTime()); return text3; }
public void setText3(StaticText text3) { this.text3 = text3; this.text3.setText(getTime()); }
public StaticText getText4() { this.text4.setText(getTime()); return text4; }
public void setText4(StaticText text4) { this.text4 = text4; this.text4.setText(getTime()); }
private String getTime() { Calendar calendar = Calendar.getInstance(); return calendar.getTime().toString(); }
}
accordionTab

Use the webuijsf:accordionTab tag within webuijsf:accordion to create an accordion tab within an accordion in the rendered HTML page. The webuijsf:accordionTab tag represents a container within which an arbitrary number of components can be placed. These components will render within the content area of the given tab inside the accordion.

HTML Elements and Layout

The accordionTab component renders an XHTML <div> tag.

Configuring the webuijsf:accordionTab Tag

The webuijsf:accordionTab tag should be configured to have a label that will appear in the accordion body even when the tab is not selected. The height of the content area can also be specified. Tabs with larger content can have greater height.

Facets

None.

Client Side Javascript Functions

When the accordinTab component is rendered, a DOM object corresponding to the accordionTab component is created. To manipulate the component on the client side, you can call functions on the DOM object. Call document.getElementById(id).setProps({multipleSelect: true}).

Function Description
getProps() Used to get widget properties. See the setProps() function for a list of supported properties.
refresh(execute)
Used 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) Used to change any of the following supported properties:
  • contentClass
  • contentHeight
  • contentStyle
  • label
  • labelClass
  • labelStyle
  • accordionTab
  • visible
subscribe(topic, obj, func) Use this function to subscribe to an event topic.
  • topic: The event topic to subscribe to.
  • obj: The object in which a function will be invoked, or null for default scope.
  • func The name of a function in context, or a function reference to invoke when topic is published.

Client-Side JavaScript Events

When the component is manipulated on the client side, some functions might publish event topics for custom Ajax implementations to listen for. For example, you can listen for the refresh event topic by using:

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

    // Subscribe to refresh event.
    var domNode = document.getElementById("form1:test1");
    domNode.subscribe(domNode.event.refresh.endTopic, processEvents, "update");


</webuijsf:script>

The following events are supported.

Even Description
<Node>.event.refresh.beginTopic Event topic published before asynchronously refreshing the component. 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
<Node>.event.refresh.endTopic Event topic published after asynchronously refreshing the component. Supported properties include: See setProps() function.
  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage
<Node>.event.load.beginTopic Event topic published before asynchronously loading the tab contents. Supported properties include:
  • id - The client ID to process the event for
<Node>.event.load.endTopic Event topic published after asynchronously loading the contents of an accordionTab. Supported properties include: setProps() function.
  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage
<Node>.event.title.selectTopic Event topic published when an accordionTab is selected. Supported properties include:
  • id - The client ID of the selected accordionTab

Examples

Example 1: Using the AccordionTab in an Accordion.

In this example, the accordionTab component is populated with hyperlink components that act as navigational elements.

       <webuijsf:accordion id="acc1" style="width:70%">

<webuijsf:accordionTab id="tab1" label="Buttons and links" >
<webuijsf:hyperlink id="hyper1" text="Button Examples"
url="/faces/button/index.jsp"
target="rightFrame"/>
<br/>
<webuijsf:hyperlink id="hyper2" text="Link Examples"
url="/faces/hyperlink/index.jsp"
target="rightFrame"/>
<br/>
<webuijsf:hyperlink id="hyper3" text="Image Link Examples"
url="/faces/imagehyperlink/index.jsp"
target="rightFrame"/>
</webuijsf:accordionTab>

<webuijsf:accordionTab id="tab2" label="Input Elements" >
<webuijsf:hyperlink id="hyper1" text="CheckBoxes"
url="/faces/clientsideCheckbox/checkbox.jsp"
target="rightFrame"/>
<br/>
<webuijsf:hyperlink id="hyper2" text="CheckBox group"
url="/faces/clientsideCheckbox/index.jsp"
target="rightFrame"/>
<br/>
<webuijsf:hyperlink id="hyper3" text="Radio Button Group"
url="/faces/clientsiderbcbGroup/index.jsp"
target="rightFrame"/>
</webuijsf:accordionTab>

<webuijsf:accordionTab id="tab3" label="label1" >
<webuijsf:hyperlink id="hyper1" text="Calendar"
url="/faces/calendar/index.jsp"
target="rightFrame"/>
</webuijsf:accordionTab>

</webuijsf:accordion>
addRemove

Use the webuijsf:addRemove tag to display an addRemove component in the rendered HTML page. The addRemove component can be used to construct a list and determine the order of the items in the list. List items are selected from another list and moved to the list that is being constructed.

The addRemove component presents all the items that can be included in the list, and does not permit users to add their own list items. Items are shifted from one list to the other, and can be moved up and down in the list until the user is satisfied with the list of selected items.

Another component, the editableList, also enables users to manipulate lists. However, the editableList is designed to allow users to provide their own list items. Users cannot change the order of the items after they have been added to the list.

HTML Elements and Layout

The addRemove component renders two listboxes, one for available options and one for selected options. Buttons are used to move the options between the lists, and optionally to order the selected options.

The addRemove component has a horizontal layout by default, as shown in the Horizontal layout diagram. If you set the webuijsf:addRemove tag's vertical attribute to true, the component is rendered in a vertical layout, as shown in the Vertical layout diagram. In both diagrams, the supported facets are shown in light blue. Non-facet areas are gray. The facets are described in Facets section.

Horizontal layout

In the horizontal layout, the component label (or header) is displayed next to the component by default. The header facet shows the location of the component label in the diagram. The header is displayed above the component when the webuijsf:addRemove tag's labelOnTop attribute is set to true.

header  
availableLabel
 
        addButton        
      addAllButton      
     removeButton     
   removeAllButton  
    moveUpButton    
  moveDownButton  
selectedLabel
 
footer

Vertical layout

In the vertical layout, the component label (header) is always displayed above the component.
header
availableLabel
         addButton                  addAllButton               removeButton            removeAllButton  
selectedLabel
     moveUpButton          moveDownButton  
footer

Configuring the webuijsf:addRemove Tag

Use the items attribute to associate the component with an array, collection, or map of com.sun.webui.jsf.model.Option. The contents of the items attribute are used for the items in the available items list.

Use the selected attribute to associate the component with a model object that represents the selected items. The model object must be an array of objects, whose values must be represented by the values on the com.sun.webui.jsf.model.Option.

The label attribute can be used to specify a header label for the addRemove component. The labelOnTop attribute can be used to display the label above the lists. By default the header label is displayed to the left of the list of available items. You can use the header facet to specify a custom component for the header label. The labelOnTop attribute also affects the header facet.

The availableItemsLabel attribute can be used to specify the label text that is displayed above the list of available items. The selectedItemsLabel attribute can be used to specify the label text that is displayed above the list of items that are selected. These labels are always displayed above the lists, regardless of the value of the labelOnTop attribute.

By default, only the Add and Remove buttons are displayed. You can use the moveButtons attribute to render the Move Up and Move Down buttons, which enable users to specify the order of selected list items by moving them up or down in the list. You can use the selectAll attribute to render the Add All and Remove All buttons so that the users can quickly move all items from one list to another. In addition, any of the buttons can be replaced with a facet, as described in Facets.

If you want the user to be able to add available list items to the selected list more than once set the duplicateSelections attribute. When this attribute is true, items remain displayed in the available items list after they have been added to the selected items list. The default behavior is to remove an item from one list when it is added to the other list.

The sorted attribute can be specified to automatically alphabetize items in the lists.

Facets

The webuijsf:addRemove tag supports the facets in the following table. These facets enable you to customize the layout of the component.

addButton Use the addButton facet to replace the standard Add button. When you use this facet, set the id attribute of the facet component to the webuijsf:addRemove tag's id attribute with _addButton appended to the id. For example, if the webuijsf:addRemove id is ar1, the facet component's id should be ar1_addButton.

If you want to use the JavaScript function associated with the default button, use the add() function. See Client-side JavaScript Functions below for details.
removeButton Use the removeButton facet to replace the standard Remove button. When you use this facet, set the id attribute of the facet component to the webuijsf:addRemove tag's id attribute with _removeButton appended to the id. For example, if the webuijsf:addRemove id is ar1, the facet component's id should be ar1_removeButton.
If you want to use the JavaScript function associated with the default button, use the remove() function. See Client-side JavaScript Functions below for details.
addAllButton Use the addAllButtonfacet to replace the standard Add All button. When you use this facet, set the id attribute of the facet component to the webuijsf:addRemove tag's id attribute with _addAllButton appended to the id. For example, if the webuijsf:addRemove id is ar1, the facet component's id should be ar1_addAllButton.

If you want to use the JavaScript function associated with the default button, use the addAll() function. See Client-Side JavaScript Functions below for details.
removeAllButton Use the removeAllButtonfacet to replace the standard Remove All button. When you use this facet,set the id attribute of the facet component to the webuijsf:addRemove tag's id attribute with _removeAllButton appended to the id. For example, if the webuijsf:addRemove id is ar1, the facet component's id should be ar1_removeAllButton.

If you want to use the JavaScript function associated with the default button, use the removeAll() function. See Client-Side JavaScript Functions below for details.
moveUpButton Use the moveUpButtonfacet to replace the standard Move Up button. When you use this facet,set the id attribute of the facet component to the webuijsf:addRemove tag's id attribute with _moveUpButton appended to the id. For example, if the webuijsf:addRemove id is ar1, the facet component's id should be ar1_moveUpButton.

If you want to use the JavaScript function associated with the default button, use the moveUp() function. See Client-Side JavaScript Functions below for details.
moveDownButton Use the moveDownButton facet to replace the standard Move Down button. When you use this facet,set the id attribute of the facet component to the webuijsf:addRemove tag's id attribute with _moveDownButton appended to the id. For example, if the webuijsf:addRemove id is ar1, the facet component's id should be ar1_moveDownButton.

If you want to use the JavaScript function associated with the default button, use the moveDown() function. See Client-Side JavaScript Functions below for details.
header Use the header facet to replace the component label.
footer Use the footer facet to create a footer for the component. By default there is no footer.

Theme Identifiers

None.

Client-Side JavaScript Functions

When the AddRemove component is rendered, a DOM object corresponding to the component is created. To manipulate the component on the client side, you can call functions on the DOM object. To add elements on the available list, call document.getElementById(id).add() where "id" is the DOM id of the AddRemove element.

add() The highlighted items on the available list are moved to the selected list.
addAll() All non-disabled items on the available list are moved to the selected list.
remove() The highlighted items on the selected list are moved to the available list.
removeAll() All non-disabled items on the selected list are moved to the available list.
moveUp() The highlighted items on the selected list are moved up one position.
moveDown() The highlighted items on the selected list are moved down one position.
updateButtons() This function ensures that the buttons are enabled/disabled based on the current selections in the lists. Invoke this function if you programmatically modify the selections on the available or selected list using client-side scripts. You do not need to invoke it when using any of the functions listed above, as they already invoke this function at the end.

Code Examples

Example 1: Horizontal AddRemove Component

In this example, the component gets the list options from a managed bean called AirportBean. The selections are stored in another managed bean (AirportSelectionBean). The selectAll attribute indicates that the Add All and Remove All buttons should be shown. A label for the component as a whole (label) is shown next to the component (labelOnTop is false). Labels have been specified for the list of available items and for the list of selected items. The sorted attribute indicates that the options on the list will be shown in alphabetical order. See also the sample backing bean code below.

         <webuijsf:addRemove id="list"
                       items="#{AirportBean.airports}"
                       selected="#{AirportBean.airportSel}"
                       label="Select airports"
                       availableItemsLabel="Available Airports"
                       selectedItemsLabel="Selected Airports"
                       selectAll="true"
 		      sorted="true"
                       labelOnTop="false"/>
 

Example 2: Vertical AddRemove Component

This example is similar to the previous example- with the following exceptions: The component is rendered using vertical layout (in this case, the main component label is always rendered above the component). The moveButtons attribute indicates that the Move Up and Move Down buttons should be shown. See also the sample backing bean code below.

 
         <webuijsf:addRemove id="list"
                       items="#{AirportBean.airports}"
                       selected="#{AirportBean.airportSel}"
                       label="Select some names"
                       availableItemsLabel="Available Names"
                       selectedItemsLabel="Selected Names"
                       selectAll="true"
                       moveButtons="true"
                       vertical="true"/>
 

Example 3: AddRemove Using Facets

This example uses the header facet to create a label with the webuijsf:label tag, which provides the labelLevel attribute to change the appearance of the label. The example also uses the addButton facet to replace the standard Add button. The child Button component uses the add() Javascript function on the webuijsf:button tag's onClick attribute, to enable the button to add items to the selected items list. See also the sample backing bean code below.

 
  <webuijsf:form id="arform1">
  ...
   <webuijsf:addRemove id="arlist" 
                       label="Select some names"
                       availableItemsLabel="Available Names:"
                       selectedItemsLabel="Selected Names:"
                       items="#{AirportBean.airports}"
                       selected="#{AirportBean.airportSel}"
                       labelOnTop="false" >
               <f:facet name="header">
                    <webuijsf:label id="arheader" text="Label in a Facet" for="arlist" labelLevel="1" />
               </f:facet>
               <f:facet name="addButton">
                    <webuijsf:button id="arlist_addButton" text="Add It!" onClick="document.getElementById('arform1:arlist').add()"/>
               </f:facet>
           </webuijsf:addRemove>
 ...
 </webuijsf:form>
  

Example Backing Bean Content

The following code is from the AirportBean used in the examples.
 public class BackingFileChoice {
     private static final boolean DEBUG = false;
     private String airport = "ARN";
     private String[] airportSel = { "ARN", "MNL" };
     private Option[] airports = null;
     private Option[] multibyte = null;
     public String getAirport() {
         return airport;
     }
     public void setAirport(String s) {
         airport = s;
     }
     public String[] getAirportSel() {
         return airportSel;
     }
 }
     public String getAirportSelString() {
         String s = new String();
         if(airportSel == null) return "NO Option";
         for(int i=0; i<airportSel.length; ++i) {
             s = s.concat(" " + airportSel[i]);
         }
         if(DEBUG) log("\tString is " + s);
         return s;
     }
     public void setAirportSel(String[] s) {
         if(DEBUG) { 
             log("setAirportSel() with new value");
             if(s == null) log("No value!"); 
             else {
             for(int i=0; i<s.length; ++i) 
                 log("adding value " + s[i]);
             }
         }
         airportSel = s;
     }
     public Option[] getAirports() {
         return airports;
     }
     public BackingFileChoice() {
         airports = new Option[11];
         airports[0] = new Option("SFO", "San Francisco");
         airports[1] = new Option("OAK", "Oakland");
         airports[2] = new Option("SAN", "San Diego");
         airports[3] = new Option("BOS", "Boston");
         airports[4] = new Option("ARN", "Stockholm");
         airports[5] = new Option("MNL", "Manila");
         airports[6] = new Option("CDG", "Paris");
         airports[7] = new Option("PDX", "Portland");
         airports[8] = new Option("LAX", "Los Angeles");
         airports[9] = new Option("NRT", "Tokyo");
         airports[10] = new Option("TBD", "Future Airport");
         airports[10].setDisabled(true);
     }
  }
  
alarm

Use the webuijsf:alarm tag to display a theme-specific alarm image in the rendered HTML page. The webuijsf:alarm tag can be used anywhere that an image can be displayed. Alarm images are useful in pages and tables that display the status of devices.

HTML Elements and Layout

The rendered HTML page displays an XHTML compliant <img> element with any applicable attributes.  The attributes can be specified through the <webuijsf:alarm> tag attributes.

Configuring the webuijsf:alarm tag

Use the severity attribute to specify the alarm severity, which determines the theme-specific alarm icon to render. The Alarm supports a set of Indicators which enables you to define custom types and associated images in addition to default types. Indicators also support the sorting attribute which enables sorting among Indicators depending on the sortValue value.

The text attribute is used to specify the text to be displayed next to the alarm icon, and the textPosition attribute specifies whether the text should be displayed to the left or right of the icon.

The url attribute can be used to override the theme-specific alarm icon. The image that you specify with the url attribute is always rendered, even if a severity is not specified. If you specify a theme key with the icon attribute, you must also specify a standard severity. If you do not specify a severity, the component will assume default severity. The icon is coupled with the severity, while the url is not. If you specify an icon attribute as well as a url attribute, the image specified by the url takes precedence over the image specified by the icon attribute.

Other image-related attributes, such as border, height, and width, can also be specified with the webuijsf:alarm tag attributes to override the image attributes of the icon.

Facets

None.

Theme Identifiers

The Theme provides the following alarm icon identifiers.

 DOWN_ALARM_INDICATOR
CRITICAL_ALARM_INDICATOR
MAJOR_ALARM_INDICATOR
OK_ALARM_INDICATOR
ALARM_CRITICAL_SMALL
ALARM_CRITICAL_MEDIUM
ALARM_MAJOR_SMALL
ALARM_MAJOR_MEDIUM
ALARM_MINOR_SMALL
ALARM_MINOR_MEDIUM
ALARM_DOWN_SMALL
ALARM_DOWN_MEDIUM
ALARM_MASTHEAD_CRITICAL_MEDIUM
ALARM_MASTHEAD_DOWN_MEDIUM
ALARM_MASTHEAD_MAJOR_MEDIUM
ALARM_MASTHEAD_MINOR_MEDIUM

Client-Side JavaScript Functions

When the Alarm component is rendered, a DOM object corresponding to the component is created. To manipulate the Alarm component on the client side, you can call functions on the DOM object. To disable the component, call document.getElementById(id).setProps({text: "New Alarm Text"}).

getProps() Use this function to get widget properties. 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. If omitted, no other components are executed.
setProps(props) Use this function to change any of the following supported properties:
  • className
  • dir
  • indicators
  • id
  • lang
  • onClick
  • onDblClick
  • onKeyDown
  • onKeyPress
  • onKeyUp
  • onMouseDown
  • onMouseOut
  • onMouseOver
  • onMouseUp
  • onMouseMove
  • style
  • text
  • textPosition
  • title
  • type
  • visible
subscribe(topic, obj, func) Use this function to subscribe to an event topic.
  • topic: The event topic to subscribe to.
  • obj: The object in which a function will be invoked, or null for default scope.
  • func The name of a function in context, or a function reference to invoke when topic is published.

Client-Side JavaScript Events

When the component is manipulated client side, some functions might publish event topics for custom Ajax implementations to listen for. For example, you can listen for the refresh event topic by using:

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

    // Subscribe to refresh event.
    var domNode = document.getElementById("form1:test1");
    domNode.subscribe(domNode.event.refresh.endTopic, processEvents, "update");


</webuijsf:script>

The following events are supported.

<Node>.event.refresh.beginTopic Event topic published before asynchronously refreshing the component. 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
<Node>.event.refresh.endTopic Event topic published after asynchronously refreshing the component. Supported properties include: See setProps() function.
  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage

Code Examples

Example 1: Alarm with Critical Severity.

<webuijsf:alarm id="alarm1" severity="critical" />

Example 2: Alarm with Major Severity Overriding the Alarm Image.

 <webuijsf:alarm id="alarm2" 
severity="major"
url="../images/major.gif"
height="10"
width="10"
alt="Processor Alarm:Major" />

Example 3: Using Alarms in a Table

See the Examples section in the documentation for the webuijsf:tableColumn component.

Example 4: Developer Define Types

<webuijsf:alarm id="alarm1" indicators="#{AlarmBean.customIndicator}" severity="mySeverity" text="Custom severity" />


Backing Bean for Examples

The AlarmBackingBean.java backing bean is used the examples above.

AlarmBackingBean.java

 AlarmBackingBean {
...
public List getCustomIndicator() {

FacesContext context = FacesContext.getCurrentInstance();
UIComponent comp = context.getViewRoot().findComponent("form1:alarm1");
Alarm alarm = (Alarm) comp;

Indicator indicator = new Indicator("ALARM_CRITICAL_SMALL", "mySeverity", 600);

List lst = Alarm.getDefaultIndicators();
lst.add(indicator);

return lst;
}
...
}
The example above defines "mySeverity" as a custom define severity in addition to the default severities. An Indicator object can be constructed by calling any Indicator constructors.

Indicator(String imageKey, String type, int sortValue)
or Indicator(UIComponent imageComponent, String type, int sortValue)

The third parameter of constructor enables sorting for Indicators.

Example 5: Update Client-Side Alarm Properties Using the getProps And setProps Functions

This example shows how to toggle the visible state of an alarm client side using the getProps and setProps functions. When the user clicks the radio button, the button is either shown or hidden.
<webuijsf:radioButton id="rb1" name="rb1" label="Toggle Alarm Visible" onClick="toggleVisible()"/>
<webuijsf:alarm id="alarm1" severity="major" text="#{MyBean.text}" />

<webuijsf:script>
function toggleVisible() {
var domNode = document.getElementById("form1:alarm1"); // Get alarm
return domNode.setProps({visible: !domNode.getProps().visible}); // Toggle visible state
}
</webuijsf:script>

Example 6: Asynchronously Update Alarm Using Refresh Function

This example shows how to asynchronously update an alarm using the refresh function. When the user clicks the radio button, the alarm is asynchronously updated with new data.
<webuijsf:radioButton id="rb1" name="rb1" label="Refresh Alarm" onClick="refreshAlarm()"/>
<webuijsf:alarm id="alarm1" severity="major" text="#{MyBean.text}" />
<webuijsf:script>
    function refreshAlarm() {
        var domNode = document.getElementById("form1:alarm1"); // Get alarm
        return domNode.refresh(); // Asynchronously refresh alarm
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,..."). When no parameter is given, the refresh function acts as a reset. That is, the component will be redrawn only using values set server-side.

Example 7: Asynchronously Update Alarm Using Refresh Function

This example shows how to asynchronously update an alarm using the refresh function. The execute property of the refresh function is used to define the client ID which is to be submitted and updated server-side. As the user types in the text field, the input value is updated server-side and the alarm text is updated client-side -- all without a page refresh.
<webuijsf:alarm id="alarm1" severity="major" text="#{MyBean.text}" />
<webuijsf:textField id="field1" text="#{MyBean.text}" label="Change Text"
onKeyPress="setTimeout('refreshAlarm();', 0);"/> // Field used to asynchronously update text.
<webuijsf:script>
    function
refreshAlarm() {
        var domNode = document.getElementById("form1:alarm1"); // Get alarm
        return domNode.refresh("form1:field1"); // Asynchronously refresh while submitting field value
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of IDs can be provided to update components on the server-side: refresh("form1:id1,form2:id2,...")

alarmStatus

Use the webuijsf:alarmStatus tag to display alarm information as hyperlinks. This tag is typically specified as part of the webuijsf:masthead tag's statusArea facet. The webuijsf:alarmStatus tag produces alarm information identical to the webuijsf:masthead tag's alarmCounts attribute. See the webuijsf:masthead documentation for more information about the statusArea facet.

The statusArea facet overrides the masthead's status area attributes. The webuijsf:alarmStatus tag enables you to include the alarm counts in the status area, along with your custom components. The webuijsf:jobStatus, webuijsf:timeStamp, and webuijsf:notificationPhrase tags enable you to include the other standard status area components as well.

Note that when you use the webuijsf:masthead attributes, spacing between the components is handled automatically. When you use the webuijsf:alarmStatus, webuijsf:jobStatus, webuijsf:timeStamp, and webuijsf:notificationPhrase tags in the statusArea facet, you may have to add code to handle the spacing between the components, as demonstrated in the example below.


Note that the AlarmStatus component is deprecated. Look at the examples to see how the equivalent of webuijsf:alarmStatus can be created in the masthead.

HTML Elements and Layout

The rendered HTML page includes a <span> element that contains the label for the alarm count. The label text is "Current Alarms:" by default. Immediately following the <span> element are four image hyperlinks that show the number of alarms for each severity. You can determine how the links respond when clicked by specifying attributes such as url, action, or actionListener. The links can be used to show the user more information about the alarms.

Configuring the webuijsf:alarmStatus tag

Use the text attribute to specify a title or label for the alarmStatus component. The default text is "Current Alarms:".

The immediate attribute should be set to true when this component is used in the masthead.

By default, all four alarm icons and counts are displayed. You can prevent any alarm type from being displayed by setting the following attributes to false:

  • criticalAlarms
  • downAlarms
  • majorAlarms
  • minorAlarms
You can specify the number of each type of alarm by using the attributes:
  • numCriticalAlarms
  • numDownAlarms
  • numMajorAlarms
  • numMinorAlarms

The order in which you specify the attributes does not matter because the alarms are always displayed in the order of severity: down, critical, major, minor. If the count of an alarm type is 0, a dimmed version of the icon is displayed.

You can also specify key identifiers for alternative theme image files to use for the icons. See the Theme Identifiers section.

The image-related attributes such as align, border and vspace apply to all the alarm images. The link-related attributes such as type, url, and action apply to all the alarm count links.

If you want to customize a particular alarm count icon count, you can use facets to replace any of the icons. See Facets for more information.

Facets

The webuijsf:alarmStatus tag supports the following facets.

alarmLabel Specifies a custom component to use for the label. This facet overrides the static text label that is rendered by default, and also overrides the text attribute. This facet might be used to create a hyperlink label, instead of static text.
criticalAlarms Specifies a custom component for the icon and count for critical alarms. Overrides criticalAlarms and numCriticalAlarms attributes.
downAlarms Specifies a custom component for the icon and count for down alarms. Overrides downAlarms and numDownAlarms attributes.
majorAlarms Specifies a custom component for the icon and count for major alarms. Overrides majorAlarms and numMajorAlarms attributes.
minorAlarms Specifies a custom component for the icon and count for minor alarms. Overrides minorAlarms and numMinorAlarms attributes.

For example, to replace the down alarms icon, use the following facet in the webuijsf:alarmStatus tag:

<f:facet name="downAlarms">
  <h:panelGroup id="downAlarmsPanel">
    <webuijsf:imageHyperlink id="downAlarmsLink" styleClass="#{themeStyles.MASTHEAD_ALARM_LINK}"
    icon="ALARM_DOWN_MEDIUM" text=" 3" url="downAlarms.jsp" />
    <f:verbatim>&nbsp;&nbsp;&nbsp;</f:verbatim>
  </h:panelGroup>
</f:facet>

Note that you can use the theme style class MstAlmLnk to apply appropriate spacing for links you create with facets.

Theme Identifiers

The theme provides the following alarm icon key identifiers.

 ALARM_CRITICAL_SMALL
 ALARM_CRITICAL_MEDIUM
 ALARM_MAJOR_SMALL
 ALARM_MAJOR_MEDIUM
 ALARM_MINOR_SMALL
 ALARM_MINOR_MEDIUM
 ALARM_DOWN_SMALL
 ALARM_DOWN_MEDIUM
 ALARM_MASTHEAD_CRITICAL_MEDIUM
 ALARM_MASTHEAD_CRITICAL_DIMMED
 ALARM_MASTHEAD_DOWN_MEDIUM
 ALARM_MASTHEAD_DOWN_DIMMED
 ALARM_MASTHEAD_MAJOR_MEDIUM
 ALARM_MASTHEAD_MAJOR_DIMMED
 ALARM_MASTHEAD_MINOR_MEDIUM
 ALARM_MASTHEAD_MINOR_DIMMED
 

These identifiers can be specified with the criticalIcon, majorIcon, minorIcon, downIcon attributes to vary the appearance of the icons.

Client-Side JavaScript Functions

None.

Code Examples

Example 1: Display Alarm Status Information As Part of the Masthead StatusArea facet

This example shows the webuijsf:alarmStatus tag with attributes set to indicate the numbers of each type of alarm. The example shows literal values for these attributes, but you can set them to a JavaServer Faces EL expression that resolves to a backing bean property. The f:verbatim tags are used to add style selectors that are defined in the theme style sheet.

<webuijsf:masthead id="Masthead" productImageURL="../images/webconsole.png"
         productImageDescription="Java Web Console" userInfo="user_name" 
         serverInfo="server_name">
      <f:facet name="statusArea">
        <webuijsf:panelGroup id="statusPanel" separator="">
          <webuijsf:markup tag="div" styleClass="#{themeStyles.MASTHEAD_STATUS_DIV}">
            <webuijsf:notificationPhrase text="Important info goes here" />
            <webuijsf:image icon="DOT" border="0" width="20" height="1" />
            <webuijsf:jobStatus numJobs="1" />
          </webuijsf:markup>
          <webuijsf:markup tag="div" styleClass="#{themeStyles.MASTHEAD_TIME_DIV}">
            <webuijsf:timeStamp />
          </webuijsf:markup>
          <webuijsf:markup tag="div" styleClass="#{themeStyles.MASTHEAD_ALARM_DIV}">
            <webuijsf:alarmStatus numDownAlarms="0" numCriticalAlarms="1" numMajorAlarms="2" numMinorAlarms="3" />
          </webuijsf:markup>
        </webuijsf:panelGroup>
      </f:facet>
 </webuijsf:masthead>
 

Example 2: Create the Equivalent of webuijsf:alarmStatus tag


 <f:facet name="currentAlarmsInfo">  
  <webuijsf:panelGroup id="alarmStatus">

      <webuijsf:staticText id="labelstatus" text="Current Info :" styleClass="#{themeStyles.MASTHEAD_TEXT}"/>
      <webuijsf:panelGroup id="downAlarmsPanel">
        <webuijsf:imageHyperlink id="downAlarmsLink" 
                           icon="ALARM_MASTHEAD_DOWN_DIMMED" text="0" disabled="true" >                        
          <f:param name="severity" value="down" />
          </webuijsf:imageHyperlink>
        <f:verbatimk>&nbsp;&nbsp;</f:verbatim>
      </webuijsf:panelGroup>

      <webuijsf:panelGroup id="criticalAlarmsPanel">
        <webuijsf:imageHyperlink id="criticalAlarmsLink" styleClass="#{themeStyles.MASTHEAD_ALARM_LINK}" 
                           icon="ALARM_MASTHEAD_CRITICAL_MEDIUM" text="1"  actionExpression="#{MastheadBean.alarmClicked}">
          <f:param name="severity" value="critical"/>
        </webuijsf:imageHyperlink>
     <f:verbatim>&nbsp;&nbsp;</f:verbatim>
      </webuijsf:panelGroup>                        

      <webuijsf:panelGroup id="majorAlarmsPanel">
        <webuijsf:imageHyperlink id="majorAlarmsLink" styleClass="#{themeStyles.MASTHEAD_ALARM_LINK}" 
                           icon="ALARM_MASTHEAD_MAJOR_MEDIUM" text="2" actionExpression="#{MastheadBean.alarmClicked}">
          <f:param name="severity" value="major"/>
        </webuijsf:imageHyperlink>
      <f:verbatim>&nbsp;&nbsp;</f:verbatim>
      </webuijsf:panelGroup>

      <webuijsf:panelGroup id="minorAlarmsPanel">
        <webuijsf:imageHyperlink id="minorAlarmsLink" styleClass="#{themeStyles.MASTHEAD_ALARM_LINK}" 
                           icon="ALARM_MASTHEAD_MINOR_MEDIUM" text="3" actionExpression="#{MastheadBean.alarmClicked}">
          <f:param name="severity" value="minor"/>
        </webuijsf:imageHyperlink>
        <f:verbatim>&nbsp;&nbsp;</f:verbatim>
      </webuijsf:panelGroup>
  </webuijsf:panelGroup>
</f:facet>              
               
alert

Use the webuijsf:alert tag to display an inline alert message at the top of the rendered HTML page. Inline alert messages permit users to correct problems or proceed with their work without having to dismiss a window and navigate to a new location.

HTML Elements and Layout

The alert component includes an icon, a summary message, and an optional detail message. The icon shown is determined by the type attribute, which must be set to information, success, warning, error or one of the developer define types. Alert supports a set of Indicators which enables to define custom types and associated images in addition with default types. Indicators also support the sorting attribute which enables sorting among Indicators depending on the sortValue value. A different icon is shown for each alert type. The icon is determined by the theme or could be a ImageComponent.

The component renders HTML <div> and <table> elements for the alert box and text, with an <img> element for the icon. If you include a link with the alert, an <a> element is also rendered.

Configuring the webuijsf:alert tag

The summary message is specified with the summary attribute, and is displayed prominently next to the icon. The optional detail message is specified with the detail attribute, and is displayed in less prominent text following the summary text. The detail text provides more information about the alert.

You can also include a link to further information or another window by using the linkTarget, linkText, linkToolTip, linkURL, and linkActionExpression attributes. The link is displayed below the detail text.

The icon and link can be overridden with facets.

Facets

The webuijsf:alert tag supports the following facets:

  • alertImage - use this facet to specify a custom component to use for the alert icon. For example, you might override the theme icon for the alert with the webuijsf:image component.
  • alertLink - use this facet to specify a custom component to use for the link, to add formatting or extra text, for example.

Client Side Javascript Functions

When the Alert component is rendered, a DOM object corresponding to the component is created. To manipulate the component on the client side, you call functions on the DOM object. To disable the component, call document.getElementById(id).setProps({detail: "New Detail Text"}).

getProps() Use this function to get widget properties. 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. If omitted, no other components are executed.
setProps(props) Use this function to change any of the following supported properties:
  • dir
  • lang
  • detail
  • spacerImage
  • indicators
  • id
  • summary
  • type
  • moreInfo
  • visible
subscribe(topic, obj, func) Use this function to subscribe to an event topic.
  • topic: The event topic to subscribe to.
  • obj: The object in which a function will be invoked, or null for default scope.
  • func The name of a function in context, or a function reference to invoke when topic is published.

Client Side JavaScript Events

When the component is manipulated on the client side, some functions might publish event topics for custom Ajax implementations to listen for. For example, you can listen for the refresh event topic by using:

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

    // Subscribe to refresh event.
    var domNode = document.getElementById("form1:test1");
    domNode.subscribe(domNode.event.refresh.endTopic, processEvents, "update");


</webuijsf:script>

The following events are supported.

<Node>.event.refresh.beginTopic Event topic published before asynchronously refreshing the component. 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
<Node>.event.refresh.endTopic Event topic published after asynchronously refreshing the component. Supported properties include: setProps() function.
  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage

Examples

Example 1: An Informational Alert

<webuijsf:alert id="msg1" type="information" summary="Patch Installed Successfully" detail="Patch 9997-01 was successfully installed on host alpha, beta and zed." />

Example 2: An Error Alert with Alert Link

<webuijsf:alert id="msg2" type="error" summary="Patch Installation Failed!" detail="Patch 9997-01 was not installed on host alpha, beta and zed." linkText="View Log" linkURL="/log/patch-log.txt" linkTarget="_blank" linkToolTip="Open Window Containing Error Log"/>

Example 3: Using alertImage facet

<webuijsf:alert id="msg2" type="error" summary="Patch Installation Failed!" detail="Patch 9997-01 was not installed on host alpha, beta and zed.">
    <f:facet name="alertImage">
       <webuijsf:image id="foo"
url="../images/foo.gif" />
    </f:facet>
</webuijsf:alert>

Example 4: Using Developer Define Types

<webuijsf:alert id="alert1" indicators="#{AlertBean.customIndicator}" type="myType" summary="Summary Text" />


Backing Bean for Examples

The AlertBackingBean.java backing bean is used the examples above.

AlertBackingBean.java

 AlertBackingBean {
...
public List getCustomIndicator() {

FacesContext context = FacesContext.getCurrentInstance();
UIComponent comp = context.getViewRoot().findComponent("form1:alert1");
Alert alert = (Alert) comp;

Indicator indicator = new Indicator("ALARM_CRITICAL_SMALL", "myType", 600);

List lst = Alert.getDefaultIndicators();
lst.add(indicator);

return lst;
}
...
}
The example above defines "myType" as a custom define type in addition to the default types. An Indicator object can be constructed by calling any Indicator constructors.

Indicator(String imageKey, String type, int sortValue)
or Indicator(UIComponent imageComponent, String type, int sortValue)

The third parameter of constructor enables sorting for Indicators.

Example 5: Update Client-Side Alert Properties Using the getProps and setProps Functions

This example shows how to toggle the visible state of an alert client side using the getProps and setProps functions. When the user clicks the radio button, the button is either shown or hidden.
<webuijsf:radioButton id="rb1" name="rb1" label="Toggle Alert Visible" onClick="toggleVisible()"/>
<webuijsf:alert id="alert1" type="information" summary="#{MyBean.summary}" />

<webuijsf:script>
function toggleVisible() {
var domNode = document.getElementById("form1:alert1"); // Get alert
return domNode.setProps({visible: !domNode.getProps().visible}); // Toggle visible state
}
</webuijsf:script>

Example 6: Asynchronously Update Alert Using Refresh Function - 1

This example shows how to asynchronously update an alert using the refresh function. When the user clicks the radio button, the alert is asynchronously updated with new data.
<webuijsf:radioButton id="rb1" name="rb1" label="Refresh Alert" onClick="refreshAlert()"/>
<webuijsf:alert id="alert1" type="information" summary="#{MyBean.summary}" />
<webuijsf:script>
    function refreshAlert() {
        var domNode = document.getElementById("form1:alert1"); // Get alert
        return domNode.refresh(); // Asynchronously refresh alert
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of IDs can be provided to update components server-side: refresh("form1:id1,form2:id2,..."). When no parameter is given, the refresh function acts as a reset. That is, the component will be redrawn using values set server-side, but not updated.

Example 7: Asynchronously Update Alert Using Refresh Function - 2

This example shows how to asynchronously update a alert using the refresh function. The execute property of the refresh function is used to define the client id which is submitted and updated server-side. As the user types in the text field, the input value is updated server-side and the alert text is updated client-side -- all without a page refresh.
<webuijsf:alert id="alert1" type="information" summary="#{MyBean.summary}" />
<webuijsf:textField id="field1" text="#{MyBean.summary}" label="Change Summary Text"
onKeyPress="setTimeout('refreshAlert();', 0);"/> // Field used to asynchronously update summary.
<webuijsf:script>
    function
refreshAlert() {
        var domNode = document.getElementById("form1:alert1"); // Get alert
        return domNode.refresh("form1:field1"); // Asynchronously refresh while submitting field value
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of IDs can be provided to update components server-side: refresh("form1:id1,form2:id2,...")

anchor

Use the webuijsf:anchor tag to

  • Create an anchor that traverses to the specified URL.
  • Anchor a position in the page so that you can jump to it.

The value of the id attribute of the rendered anchor element will be the component id, not the component's client id. In order to obtain the DOM node of the anchor element, on the client, the component id must be used and not the component's client id. This means that the component id must be unique in the page and not just unique within the closest NamingContainer.

Facets

None

Client Side Javascript Functions

When the component is rendered, a DOM object corresponding to the component is created. To manipulate the component on the client side, you can call functions on the DOM object. To disable the component, invoke document.getElementById(id).setProps({disabled: true}).

getProps() Use this function to get widget properties. 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. If omitted, no other components are executed.
setProps(props) Use this function to change any of the following supported properties:
  • accessKey
  • charset
  • className
  • coords
  • dir
  • disabled
  • href
  • hrefLang
  • id
  • lang
  • onFocus
  • onBlur
  • onClick
  • onDblClick
  • onKeyDown
  • onKeyPress
  • onKeyUp
  • onMouseDown
  • onMouseOut
  • onMouseOver
  • onMouseUp
  • onMouseMove
  • rev
  • rel
  • shape
  • style
  • tabIndex
  • title
  • visible
subscribe(topic, obj, func) Use this function to subscribe to an event topic.
  • topic: The event topic to subscribe to.
  • obj: The object in which a function will be invoked, or null for default scope.
  • func The name of a function in context, or a function reference to invoke when topic is published.

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. For example, you can listen for the refresh event topic by using:

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

    // Subscribe to refresh event.
    var domNode = document.getElementById("form1:test1");
    domNode.subscribe(domNode.event.refresh.endTopic, processEvents, "update");


</webuijsf:script>

The following events are supported.
 
<Node>.event.refresh.beginTopic Event topic published before asynchronously refreshing the component. 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
<Node>.event.refresh.endTopic Event topic published after asynchronously refreshing the component. Supported properties include:See setProps() function.

  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage

Code Examples

Example 1: Create an Anchor That Points to an URL

<webuijsf:anchor id="anchor1" url="http://www.sun.com"/>

Example 2: Create an Anchor That Anchors a Particular Position on the Page. 

<a id="foo" />

Note: To access this on the client side, use document.getElementById("anchor1");

Example 3: Create a Hyperlink to The Anchor Above

<webuijsf:hyperlink id="link1"url="#anchor1" > Go to Anchor </webuijsf:hyperlink >

Example 4: Create a Relative Anchor to the Anchor in Example 1

<webuijsf:anchor id="gotoAnchor1" url="/faces/hyperlink.jsp#anchor1" />

Note:  In the url attribute, you must specify a path that maps to the correct servlet. However, you do not need the context. In this example, the part of the path maps to the servlet through the JSF FacesServlet as defined in the web.xml.

Example 5: Update Client-Side Anchor Properties Using the getProps and setProps Functions

This example shows how to toggle the visible state of an anchor client side using the getProps and setProps functions. When the user clicks the button, the anchor is either shown or hidden.

<webuijsf:anchor id="anchor1" > This is an anchor </webuijsf:anchor >
<webuijsf:button id="button1" text="Hide Anchor" onClick="toggleVisible()"/>

<script type="text/javascript">
    function toggleVisible() {
        var domNode = document.getElementById("anchor1");
        var props = domNode.getProps();
        if (domNode != null) {
            domNode.setProps({"visible":!props.visible});
        }
    }
</script>

Example 6: Asynchronously Update Anchor using refresh Function

This example shows how to asynchronously update an anchor using the refresh function. When the user clicks the button, the anchor is asynchronously updated with new data.
<webuijsf:anchor id="anchor1" text="#{MyBean.text}"/>
<webuijsf:button id="button1" text="#{MyBean.text}" onClick="refreshAnchor();return false;"/>
<webuijsf:script>
    function refreshAnchor() {
        var domNode = document.getElementById("form1:anchor1"); // Get anchor
        return domNode.refresh(); // Asynchronously refresh anchor
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,..."). When no parameter is given, the refresh function acts as a reset. That is, the component will be redrawn using values set server-side, but not updated.

Example 7: Asynchronously Update Anchor Using refresh Function

This example shows how to asynchronously update an anchor using the refresh function. The execute property of the refresh function is used to define the client id which is to be submitted and updated server-side. As the user types in the text field, the input value is updated server-side and the anchor is updated client-side -- all without a page refresh.
<webuijsf:anchor id="anchor1" text="#{MyBean.text}"/>
<webuijsf:textField id="field1" text="#{MyBean.text}" label="Change Anchor Text"
onKeyPress="setTimeout('refreshAnchor();', 0);"/> // Field used to asynchronously update text.
<webuijsf:script>
    function
refreshAnchor() {
        var domNode = document.getElementById("form1:anchor1"); // Get anchor
        return domNode.refresh("form1:field1"); // Asynchronously refresh while submitting field value
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,...")

body

Using Body Tags on Pages Without Frames

If you are not using frames on your page, use the webuijsf:body tag to contain the JSP tags for the body of the JSP page. page. The webuijsf:body tag must be placed after the webuijsf:html and webuijsf:head tags. Tags for page content must be nested inside the webuijsf:body tag to ensure that the HTML elements are rendered in the necessary order.

Using Body Tags on Pages With Frames

If you are using frames in your page, use the webuijsf:frameSet tag instead of the webuijsf:body tag.

The focus can be maintained with the body tag's focus and preserveFocus attributes. The preserveFocus attribute's default value is true. This means that after the first display, the focus, will be returned to the element that had the focus when the request was made. Setting preserveFocus to false inhibits that behavior.

The focus attribute allows the developer to specify the element that should receive the focus on first display. If preserveFocus is set to false the focus attribute can control which element receives the focus on every request/response cycle.

HTML Elements and Layout

The body component creates an HTML <body> element in the rendered HTML page. Attributes that you specify with the webuijsf:body tag are used to specify the corresponding attributes in the rendered <body> element.

Client-Side Javascript Functions

None.

Code Examples

Example 1: Create a Body Tag

This example shows a simple webuijsf:body tag.

<webuijsf:page>
    <webuijsf:head title="body test" >
         <webuijsf:meta httpHead="refresh" content="5" />
    </webuijsf:head> 
    <webuijsf:body id="bodytest">
        ....your body content ...
    </webuijsf:body id="bodytest">
</webuijsf:page>

Example 2: Create a Body Tag That Sets the Focus

This example demonstrates how to set the focus in the webuijsf:body tag for a particular component in the page. When the page is first loaded, the third text field has focus.

Since preserveFocus has not been specified, if the same page is redisplayed in the response, then the focus will be set in one of two ways.

  • If the Enter key is pressed in an input field, then the focus returns to that field in the subsequent response.
  • If the page is submitted is some other fashion, for example through a submit button then the focus returns to the element that submitted the page since it was the last element to have the focus.

  <webuijsf:page>
   <webuijsf:head title="Body tests" />
    <webuijsf:body focus="form1:textTest3">
     <webuijsf:form id="form1">
      <webuijsf:textField id="textTest" label="Text Field 1:" required="true"  text="#{FieldTest.test1}"/>
      <webuijsf:textField id="textTest2" label="Text Field 2:" required="true"  text="#{FieldTest.test2}"/>
      <webuijsf:textField id="textTest3" label="Text Field 3:" required="true"  text="#{FieldTest.test3}"/>
      <webuijsf:button primary="true" id="fieldButton2" text="Submit"/>
     </webuijsf:form>
    </webuijsf:body>
  </webuijsf:page>
breadcrumbs

Use the webuijsf:breadcrumbs tag to display a set of hyperlinks that can be used as a navigation aid in the rendered HTML page. Breadcrumbs, or a parentage path, show the user's location within an application, and the physical or logical path to a page. The user can click breadcrumbs to navigate to other locations previously traversed within the application.

A breadcrumb's hyperlinks may be specified in one of two ways:

  • Directly in the JSP, by placing one or more webuijsf:hyperlink tags within the webuijsf:breadcrumbs tag. Hyperlinks specified in this manner are referred to as "child" hyperlinks.
  • Indirectly via the pages attribute. The value must a value binding expression that identifies an array of com.sun.webui.jsf.Hyperlink components. Hyperlinks specified in this manner are referred to as "bound" hyperlinks. Bound hyperlinks must be uniquely identifiable by the value of their id attribute, and this attribute must not be null. Bound hyperlinks should not be part of a view tree, and the value of their parent property should be null.
You should provide either child hyperlinks or bound hyperlinks, but not both. If both are provided, bound hyperlinks are rendered, and any child hyperlinks are ignored. Non-hyperlink children are also ignored.

Bound hyperlinks are treated as child hyperlinks for all phases of request processing, except that they are not asked to save or restore their state.

The breadcrumbs component has an immediate property, the default value of which is true. If the breadcrumbs is immediate, all action events generated by child or bound hyperlinks will be treated as though they too were immediate, whether or not the source hyperlink is immediate. If the breadcrumbs is not immediate, action events will be processed according to whether their source hyperlink is immediate or not.

HTML Elements and Layout

Breadcrumbs are rendered as a series of <a> XHTML hyperlinks separated by ">"  symbols, similar to the following: 

    Main App Page > Second level page  > Another level > Current page

The last element in the breadcrumbs should correspond to the current page, and is rendered as static text.

Separators are rendered between hyperlinks that are visible and renderable. The last child hyperlink is always assumed to refer to the current page, whether or not it is visible or renderable.

Theme Identifiers

None.

Client Side Javascript Functions

None.

Examples

Example 1: Using child components

       <webuijsf:breadcrumbs id="breadcrumbs1">
         <webuijsf:hyperlink url="http://google.com" label="Google"/>
         <webuijsf:hyperlink url="http://yahoo.com" label="Yahoo"/>
         <webuijsf:hyperlink url="http://sun.com" label="Sun"/>
       </webuijsf:breadcrumbs>
 

Example 2: Using a value binding

       <webuijsf:breadcrumbs id="breadcrumbs2" pages="#{FieldBean.pagelist}" />
 
bubble

Use the webuijsf:bubble tag to display a bubble component in the rendered HTML page. Bubble component is a pop up window which appears on screen in response to certain mouse interactions.The purpose of the bubble component is to provide detailed information to the end user when a mouse hovers on a particular screen element. To include a bubble component in the JSP page, the web application developer will include a tag as follows: <webuijsf:bubble id="bubble" title="Bubble Help Title"> <webuijsf:staticText text="Add help Text" /> </webuijsf:bubble>

Facets

None.

Theme Identifiers

None.

Client-Side JavaScript Functions

The bubble component exposes two JavaScript functions "open()" and "close()". "open()" accept "event" as argument. These two functions needs to be invoked by the component that requires a bubbleHelp. When the bubble component is rendered, a DOM object corresponding to the bubble component is created. To manipulate the component on the client side, you can call functions on the DOM object. With reference to the DOM ID, to change the helpTitle, invoke document.getElementById(id).setProps({helpTitle: "New Help Title"}).

JavaScript Function Description
open(event) Use this function to open the bubble component.
  • event: JavaScript Event object generated by the onClick of an HTML element.
close() Use this function to close bubble component.
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:
  • autoClose
  • contents
  • duration
  • id
  • title
  • width
  • style
  • styleClass
  • visible

subscribe(topic, obj, func) Use this function to subscribe to an event topic.
  • topic: The event topic to subscribe to.
  • obj: The object in which a function will be invoked, or null for default scope.
  • func The name of a function in context, or a function reference to invoke when topic is published.

Client Side JavaScript Events

When the component is manipulated on the client side, some functions might publish event topics for custom AJAX implementations to listen for. For example, you can listen for the refresh event topic by using:

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

    // Subscribe to refresh event.
    var domNode = document.getElementById("form1:test1");
    domNode.subscribe(domNode.event.refresh.endTopic, processEvents, "update");


</webuijsf:script>

The following events are supported.

Event Description
<Node>.bubble.event.refresh.beginTopic Event topic published before asynchronously refreshing the component. 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
<Node>.event.refresh.endTopic Event topic published after asynchronously refreshing the component. Supported properties include: setProps() function.
  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage

Examples

Example 1: Bubble Component for Hyperlink.

 <webuijsf:bubble id="bubble" autoClose="true" helpTitle="Bubble Help Title">
        <webuijsf:staticText text="Bubble positioning examples..." />       
</webuijsf:bubble>
<webuijsf:hyperlink id="topleft" onMouseOver="document.getElementById('form1:bubble').open(event);" 
                    onMouseOut="document.getElementById('form1:bubble').close();"   
                    text="Bubble with Left top arrow"/>

Example 2: Bubble Refresh Example

<webuijsf:bubble id="bubble" helpTitle="#{BubbleBean.titleText}">
                <webuijsf:staticText text="Bubble refresh example..." />       
        </webuijsf:bubble>
<webuijsf:textField id="field1" text="#{BubbleBean.titleText}" 
          onKeyUp="return refreshBubble();" 
          />
        <webuijsf:script>
            // Refresh bubble.
            function refreshBubble() {

                var domNode = document.getElementById("form1:bubble"); 
                               
                return domNode.refresh("form1:field1_field");
                
            }
        </webuijsf:script>
button

Use the webuijsf:button tag to display an input button in the rendered HTML page. The input button submits the associated form when activated by the user. The corresponding ActionEvent events then occur on the server.

HTML Elements and Layout

This tag creates an XHTML <input> button element with a text label.

Configuring the webuijsf:button tag 

The button component can render a button as a primary button or a secondary button. A primary button is intended to be used for buttons that are the most commonly used on a page or section of a page, and are rendered to be more visually prominent than secondary buttons. The primary attribute is false by default, which renders a secondary button.

The text attribute is used to specify the characters displayed on the buttons, which use a default button image set by the theme. The escape attribute, when set to false, causes an HTML <button> to be rendered instead of an <input> element. The <button> element, unlike the  <input> element, allows you to specify button text that will be interpreted as HTML. For example if you wanted the button to say M&M, you would have to specify M&amp;M and set escape="false".  

You can use the imageURL attribute to specify a different image for a button, or the  icon attribute to specify a theme key to a button image. When you use these attributes, the text attribute is ignored, so your button image must include any desired button text.

Note that the mini attribute at one time rendered a smaller button, but currently all buttons are the same size. The mini attribute has no effect. However, you can use style and styleClass attributes to create a smaller button if desired.

Button Actions

The button component is the most commonly used component for submitting a page. By default, the button component creates a submit button. However, you might want to use a button to go to another page in the application. In this case, you should configure the button with immediate="true" and an actionExpression that handles the navigation.

A button that is used to affect the input components on the page, such as providing initial default input, should be configured with immediate="true" and  an actionListenerExpression that updates the components.

If you want a button to submit a page, you should not set immediate, and should set an actionExpression and possibly an actionListenerExpression.   The action should get information from the managed bean and perform some business logic, and then determine what to show next on the basis of the outcome of the business logic.

If you want the button to reset all the input component values on the page, set the reset attribute to true.

Client Side Javascript Functions

When the component is rendered, a DOM object corresponding to the component is created. To manipulate the component on the client side, you may invoke functions on the DOM object. With reference to the DOM id, to disable the component, invoke document.getElementById(id).setProps({disabled: true}).

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. If omitted, no other components are executed.
setProps(props) Use this function to change any of the following supported properties:
  • accesskey
  • align
  • className
  • dir
  • disabled
  • escape
  • id
  • icon
  • lang
  • mini
  • onBlur
  • onChange
  • onClick
  • onDblClick
  • onFocus
  • onKeyDown
  • onKeyPress
  • onKeyUp
  • onMouseDown
  • onMouseMove
  • onMouseOut
  • onMouseOver
  • onMouseUp
  • primary
  • src
  • style
  • tabIndex
  • title
  • value
  • visible
subscribe(topic, obj, func) Use this function to subscribe to an event topic.
  • topic: The event topic to subscribe to.
  • obj: The object in which a function will be invoked, or null for default scope.
  • func The name of a function in context, or a function reference to invoke when topic is published.

Client Side JavaScript Events

When the component is manipulated client side, some functions may publish event topics for custom AJAX implementations to listen for. For example, listen for the refresh event topic using:

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

    // Subscribe to refresh event.
    var domNode = document.getElementById("form1:button1");
    domNode.subscribe(domNode.event.refresh.endTopic, processEvents, "update");


</webuijsf:script>

The following events are supported.

<Node>.event.refresh.beginTopic Event topic published before asynchronously refreshing the component. 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
<Node>.event.refresh.endTopic Event topic published after asynchronously refreshing the component. Supported properties include: See setProps() function.
  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage

Examples

Example 1: Create a primary button

<webuijsf:button id="button1" text="#{ButtonBean.text}" actionExpression="#{ButtonBean.success}" primary="true" />

Example 2: Create a secondary button

<webuijsf:button id="button1" text="#{ButtonBean.text}" actionExpression="#{ButtonBean.success}" />

Example 3: Create a reset button

<webuijsf:button id="button1" text="#{ButtonBean.text}" actionExpression="#{ButtonBean.success}" reset="true" />

Example 4: Create an image button

<webuijsf:button id="button1" imageURL="#{ButtonBean.image}" actionExpression="#{ButtonBean.success}" />

Example 5: Update client-side button properties using the getProps and setProps functions

This example shows how to toggle the disabled state of a button client side using the getProps and setProps functions. When the user clicks the radio button, the button is either disabled or enabled.
<webuijsf:radioButton id="rb1" name="rb1" label="Toggle Button Disabled" onClick="toggleDisabled()"/>
<webuijsf:button id="button1" text="My Button" />

<webuijsf:script>
function toggleDisabled() {
var domNode = document.getElementById("form1:button1"); // Get button
return domNode.setProps({disabled: !domNode.getProps().disabled}); // Toggle disabled state
}
</webuijsf:script>

Example 6: Asynchronously update button using refresh function

This example shows how to asynchronously update a button using the refresh function. When the user clicks on the radio button, the button is asynchronously updated with new data.
<webuijsf:radioButton id="rb1" name="rb1" label="Refresh Button" onClick="refreshButton()"/>
<webuijsf:button id="button1" text="#{MyBean.text}"/>
<webuijsf:script>
    function refreshButton() {
        var domNode = document.getElementById("form1:button1"); // Get button
        return domNode.refresh(); // Asynchronously refresh button
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,..."). When no parameter is given, the refresh function acts as a reset. That is, the component will be redrawn using values set server-side, but not updated.

Example 7: Asynchronously update button using refresh function

This example shows how to asynchronously update a button using the refresh function. The execute property of the refresh function is used to define the client id which is to be submitted and updated server-side. As the user types in the text field, the input value is updated server-side and the button text is updated client-side -- all without a page refresh.
<webuijsf:button id="button1" text="#{MyBean.text}"/>
<webuijsf:textField id="field1" text="#{MyBean.text}" label="Change Button Text"
onKeyPress="setTimeout('refreshButton();', 0);"/> // Field used to asynchronously update text.
<webuijsf:script>
    function
refreshButton() {
        var domNode = document.getElementById("form1:button1"); // Get button
        return domNode.refresh("form1:field1"); // Asynchronously refresh while submitting field value
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,...")

calendar

Use the webuijsf:calendar when the user needs to select a date. The calendar component displays a text field that expects a date as input, together with an icon that displays a small calendar when clicked. The user can either type directly into the textfield or select a date from the calendar display.

HTML Elements and Layout

The calendar component renders several elements: an optional <label>, an <input type="text"> and an <img> element for the icon. They are laid out inside a HTML <table>.

The pop-up calendar is a complex component also formatted using a HTML <table>. It has child components corresponding to <webuijsf:dropDown>, <webuijsf:iconHyperlink> (See these for details) and anchors <a> to represent the dates and the "close" button.

Configuring the webuijsf:calendar tag

Use the selectedDate attribute to associate the component with a model object that represents the current value, by setting the attribute's value to an EL expression that corresponds to a property of a backing bean.

By default, the component accepts dates between the current date and hundred years out. The years shown in the popup calendar reflect this range. If a date outside of the range is entered into the textfield, the component indicates a validation error. To specify a different range of date, use the minDate and maxDate attributes.

To optionally specify a label for the component, use the label attribute, or specify a label facet.

Facets

  • label: Use this facet to specify a custom component for the label.
  • readOnly: Use this facet to specify a custom component for displaying the value of this component when it is marked as readonly. The default is webuijsf:staticText.

Client-side JavaScript functions

When the component is rendered, a DOM object corresponding to the component is created. To manipulate the component on the client side, you can call functions on the DOM object.To disable the component, invoke document.getElementById(id).setProps({disabled: false}) where id is the DOM id of the calendar widget.

getProps() Use this function to get widget properties. 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
  • align
  • calendar
  • className
  • dir
  • disabled
  • id
  • label
  • lang
  • notify
  • onClick
  • onDblClick
  • onFocus
  • onKeyDown
  • onKeyPress
  • onKeyUp
  • onMouseDown
  • onMouseOut
  • onMouseOver
  • onMouseUp
  • onMouseMove
  • patternHelp
  • readOnly
  • required
  • style
  • tabIndex
  • title
  • valid
  • value
  • visible
subscribe(topic, obj, func) Use this function to subscribe to an event topic.
  • topic: The event topic to subscribe to.
  • obj: The object in which a function will be invoked, or null for default scope.
  • func The name of a function in context, or a function reference to invoke when topic is published.

Client Side JavaScript Events

When the calendar component is manipulated client side, some functions may publish event topics for custom Ajax implementations to listen for. For example, custom Ajax implementations can listen for the refresh event topic using:

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

    // Subscribe to refresh event.
    var domNode = document.getElementById("form1:test1");
    domNode.subscribe(domNode.event.refresh.endTopic, processEvents, "update");


</webuijsf:script>

The following events are supported.

<Node>.event.refresh.beginTopic Event topic published before asynchronously refreshing the component. 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
<Node>.event.refresh.endTopic Event topic published after asynchronously refreshing the component. Supported properties include: See setProps() function.
  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage

Code Examples

Example 1: Basic Pop-up Calendar

The component gets the options from a managed bean called CalendarBean. The value of the component selectedDate is bound to a property of the managed bean. A label for the component as a whole (label) is shown next to the component.

This example shows how to create a simple calendar.

<webuijsf:calendar id="startDate" 
               selectedDate="#{CalendarBean.startDate}"
               label="Start Date: " />

Code for the managed bean:

CalendarBean.java

import java.io.Serializable;
import java.util.Date;
import java.util.Calendar;
import javax.faces.event.ValueChangeEvent;


public class CalendarBean {
   
    public CalendarBean() {
    }
   
    private Date startDate = null;

    public Date getStartDate() {

        return this.startDate;
    }


    public void setStartDate(Date startDate) {

        this.startDate = startDate;
    }
}

The selectAll attribute indicates that the Add All and Remove All buttons should be shown. A label for the component as a whole (label) is shown next to the component (labelOnTop is false). Labels have been specified for the list of available items and for the list of selected items. The sorted attribute indicates that the options on the list will be shown in alphabetical order.

Example 2: DateFormat Pattern and Date Ranges Configured

The calendar component gets its options from a managed bean called TravelBean. The value of the attribute selectedDate is bound to a property called travelDate, that belongs to the managed bean. A label for the component as a whole (label) is shown next to the component; the label is retrieved from a message bundle.

The calendar component has been configured to use a pattern for date representation consisting of four digits for the year, two for the month, and two for the day, separated by dashes. This pattern, set using the dateFormatPattern attribute will be used regardless of locale. With this date format pattern, the default help string will be "YYYY-MM-DD", which is suitable for English, but not for other locales where other words are used. So a different message will be retrieved for each locale (dateFormatPattern).

The calendar component is also configured to restrict the range of dates that are valid, so that the first valid date is the day after the day the component is viewed, and the last valid date is six months from that date.

     <webuijsf:calendar id="travelDate" 
         selectedDate="#{TravelBean.travelDate}"
         label="#{msgs.travelDate}"
         dateFormatPattern="yyyy-MM-dd"
         dateFormatPatternHelp="#{msgs.dateFormatPattern}"
         minDate="#{TravelBean.tomorrowsDate}"
         maxDate="#{TravelBean.sixMonthsFromNow}" />
 

Example 3: Update Calendar Client Side using the getProps and setProps Functions

This example shows how to toggle the disabled state of a calendar client side using the getProps and setProps functions.

<webuijsf:calendar id="calendar1" label="Start Date:"/>
<webuijsf:button id="button1" text="Toggle Calendar Disabled" onClick="toggleDisabled(); return false"/>

<webuijsf:script>
function toggleDisabled() {
var domNode = document.getElementById("form1:calendar1");
domNode.setProps({ disabled: !domNode.getProps().disabled });
}
</webuijsf:script>

Example 4: Asynchronously Update Calendar Using refresh Function

This example shows how to asynchronously update a calendar using the refresh function. The execute property of the refresh function is used to define the client id which is to be submitted and updated server-side. As the user types in the text field, the input value is updated server-side and the calendar label is updated client-side -- all without a page refresh.
<webuijsf:calendar id="calendar1" label="#{MyBean.label}"/>
<webuijsf:textField id="field1" text="#{MyBean.label}" label="Change Calendar Label"
onKeyPress="setTimeout('refreshCalendar();', 0);"/> // Field used to asynchronously update label.
<webuijsf:script>
    function
refreshCalendar() {
        var domNode = document.getElementById("form1:calendar1"); // Get calendar
        return domNode.refresh("form1:field1"); // Asynchronously refresh while submitting field value
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,...")

checkbox

Use the webuijsf:checkbox tag to display a checkbox in the rendered HTML page. The tag can be used as a single checkbox or as one checkbox among a group of checkboxes. A group of checkboxes represents a multiple selection list which can have any number of checkboxes selected, or none selected. A checkbox can represent a value of a class type such as Boolean, Byte, Character, Double, Float, Integer, Long, Short, String or the primitive form of one of these class types. A checkbox may also represent an application defined object value.

A Boolean value is useful for indicating whether an item, such as a table row, is selected. A String value is useful for passing values for checkbox selections made in the interface. An application defined Object value or class instance can be used to hold more information related to a checkbox selection.

A single checkbox can be used to represent several types of data:

  • a boolean control
  • a string value that is related to the checkbox selection
  • an object value defined by the application

A group of checkboxes can be used to represent:

  • string values that are related to the checkbox selections
  • object values defined by the application

Note: Another tag for rendering checkboxes is webuijsf:checkboxGroup, which imposes a grid layout on a group of checkboxes. The checkbox tag is useful in situations where the checkboxGroup tag layout is not desirable, such as in a table row.

Detecting a selected checkbox

The checkbox tag uses both the selected and selectedValue attributes to pass information about the checkbox's selection status. The selected attribute is used to indicate that the checkbox is selected, and should have a check mark displayed in the page. The selectedValue attribute is used to pass a data value for the checkbox. A checkbox is considered to be selected when the value of the selected attribute is equal to the value of the selectedValue attribute. You can display a checkbox as selected on the initial viewing of the page by assigning the same value to the selectedValue and the selected attributes.

If the selectedValue attribute is not specified or its value is null then the checkbox behaves like a boolean control. If the checkbox is selected, the value of the selected attribute is a true Boolean instance. If the checkbox is not selected, the value of the selected attribute will be a false Boolean instance.

Note that a value binding expression that evaluates to a primitive value can be assigned to the selected and selectedValue attributes.

When checkboxes are part of a group, an ArrayList of selected checkboxes is maintained. If any checkboxes within a group are selected, a request attribute whose name is the value of the name attribute is created and added to the RequestMap. The request attribute value is an ArrayList containing the value of the selectedValue attribute of each selected checkbox. If no checkboxes are selected, no request attribute is created. The selected attribute of each selected checkbox within the group will also contain the value of the selectedValue attribute of the respective selected checkbox.

The Checkbox class provides a convenience method for obtaining the selected checkboxes in a group:

public static ArrayList getSelected(String groupName);

where groupName is the value of the name attribtue. Note that unlike the selected and selectedValue attributes, the return value of this method is always an ArrayList of class instances and not primitive values.

Using a checkbox tag as a boolean control

If the selectedValue attribute is not specified or its value is null then the checkbox behaves like a boolean control.

To use the checkbox tag as a boolean control, do not specify a value for the selectedValue attribute. The checkbox is selected if the selected attribute is not null and has the value of a true Boolean instance or a boolean primitive value. If the checkbox is not selected, then the value of the selected attribute is a false Boolean instance or boolean primitive.

Normally the value of the selectedValue attribute is specified as the value of the <input> HTML element. When a checkbox is behaving as a boolean control the value of the <input> element is the clientId of the checkbox.

Note that using a boolean checkbox in a group and referencing the request attribute for the selected checkboxes is not useful, since the value of the request attribute will be an ArrayList of indistinguishable true values.

Using a checkbox tag to represent an application defined value

The selectedValue attribute can be assigned an application defined object value to represent the value of a selected checkbox. If the checkbox is selected, the value of the selected attribute is assigned the value of the selectedValue attribute.

If the value of the selectedValue attribute is an application defined object, a converter must be registered to convert to and from a String value. The converter is used to encode the checkbox value as the value of the HTML <input> element and to decode the submitted value in a request. The object must also support an equals method that returns true when the value of the selectedValue attribute is compared to the selected attribute value in order to detect a selected checkbox.

Using a checkbox tag as one control in a group

The name attribute determines whether a checkbox is part of a group. A checkbox is treated as part of a group of checkboxes if the name attribute of the checkbox is assigned a value equal to the name attribute of the other checkboxes in the group. In other words, all checkboxes of a group have the same name attribute value. The group behaves like a multiple selection list, where zero or more checkboxes can be selected. The value of the name attribute must be unique within the scope of the <form> element containing the checkboxes.

Facets

The following facets are supported:

  • image If the image facet exists, it is rendered to the immediate right hand side of the checkbox.
  • label If the label facet exists, it is rendered to the immediate right of the image, or to the immediate right of the checkbox if no image is rendered.

HTML Elements and Layout

A checkbox is rendered as at least one HTML <span> element and one <input> element of type checkbox. Each checkbox may consist of the following elements and components:

  • a <span> element
  • an <input> element of type checkbox
  • an optional image, if the imageURL attribute or an image facet is specified. If the imageURL is specified and no image facet exists, then a com.sun.webui.jsf.component.ImageComponent is created and rendered. If an image facet is specified then the component specified by the facet is rendered.
  • an optional label, if the label attribute or a label facet is specified. If the label attribute is specified and no label facet exists, then a com.sun.webui.jsf.component.Label is created and rendered If a label facet is specified then the component specified by the facet is rendered.

The ID attributes for HTML elements and components are constructed as follows, where cid is the clientId of the component being rendered.

  • cid for the <span> element
  • cid_cb for the <input> element
  • cid_image for the image component if created.
  • cid_label for the label component if created.

Theme Identifiers

  • Cb for the outermost span element
  • CbDis for the outermost span element for disabled checkbox
  • CbLbl for a LABEL element of a checkbox
  • CbLblDis for a LABEL element of a disabled checkbox
  • CbImg for an IMG element of a checkbox
  • CbImgDis for an IMG element of a disabled checkbox

Client Side Javascript Functions

When the component is rendered, a DOM object corresponding to the component is created. To manipulate the component on the client side, you may invoke functions on the DOM object. With reference to the DOM ID, to disable the component, invoke document.getElementById(id).setProps({disabled: true}).

getInputElement() Use this function to access the HTML <input> element that is rendered by the component.
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. If omitted, no other components are executed.
setProps(props) Use this function to change any of the following supported properties:
  • accesskey
  • align
  • checked
  • className
  • dir
  • disabled
  • id
  • image
  • label
  • lang
  • name
  • onBlur
  • onChange
  • onClick
  • onFocus
  • onKeyDown
  • onKeyPress
  • onKeyUp
  • onMouseDown
  • onMouseMove
  • onMouseOut
  • onMouseOver
  • onMouseUp
  • onSelect
  • readOnly
  • style
  • tabIndex
  • title
  • value
  • 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.
subscribe(topic, obj, func) Use this function to subscribe to an event topic.
  • topic: The event topic to subscribe to.
  • obj: The object in which a function will be invoked, or null for default scope.
  • func The name of a function in context, or a function reference to invoke when topic is published.

Client Side JavaScript Events

When the component is manipulated client side, some functions may publish event topics for custom AJAX implementations to listen for. For example, you can listen for the refresh event topic using:

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

    // Subscribe to refresh event.
    var domNode = document.getElementById("form1:test1");
    domNode.subscribe(domNode.event.refresh.endTopic, processEvents, "update");


</webuijsf:script>

The following events are supported.
 
<Node>.event.refresh.beginTopic Event topic is published before asynchronously refreshing the component. 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
<Node>.event.refresh.endTopic Event topic is published after asynchronously refreshing the component. Supported properties include: See setProps() function.
  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage
<Node>.event.submit.beginTopic Event topic published before asynchronously submitting the component. 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
<Node>.event.submit.endTopic

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

  • props - JSON object containing messages (if any) raised by the server.In particular, valdiation messages will be present here if validation failed

Code Examples

Example 1: Single boolean checkbox with value binding

<webuijsf:checkbox id="cb1" selected="#{tldRbCbExample.selectedCb1}"/>

The value binding #{tldRbCbExample.selectedCb1} implies that there are two methods implemented in the tldRbCbExample managed bean.

  • public void setSelectedCb1(boolean selected)
  • public boolean getSelectedCb1()
The getSelectedCb1 method will be called to determine the checked state of the checkbox during rendering.
When the tag is first rendered, its initial checked state is determined by the return value of getSelectedCb1. If it returns true the checkbox will be checked on the HTML page and not checked if it returns false
When the checkbox is checked by the user the setSelectedCb1 method will be called with a boolean argument equal to true. When it is unchecked the method will be called with a boolean argument equal to false.

No image or label will be displayed by this example.

Example 2: Single boolean checkbox with value binding, that displays an image and a label

<webuijsf:checkbox id="cb2" selected="#{tldRbCbExample.selectedCb2}" imageURL="tree_server.gif label="Server"/>

The behavior of this checkbox is the same as example one.
In this example an image and a label are displayed next to the checkbox. Both the imageURL and label attributes may be assigned value binding expressions instead of literal values.

Example 3: Single String valued checkbox with value binding

<webuijsf:checkbox id="cb3" label="Printer" selectedValue="Printer" selected="#{tldRbCbExample.selectedCb3}"/>

The value binding #{tldRbCbExample.selectedCb3} implies that there are two methods implemented in the tldRbCbExample managed bean. Because the selectedValue attribute is a String the expected method signatures will be:

  • public void setSelectedCb3(String selected)
  • public String getSelectedCb3()
The getSelectedCb3 method will be called to determine the checked state of the checkbox during rendering.
When the tag is first rendered, its initial checked state is determined by the return value of getSelectedCb3. With a String valued checkbox, this checkbox will be checked only if the getSelectedCb3 method returns "Printer", since that is the value of the checkbox as dictated by the selectedValue="Printer" attribute. If the getSelectedCb3 method returns anything else, the checkbox will not be checked.
When the checkbox is checked by the user the setSelectedCb3 method will be called with a String argument equal to "Printer". When it is unchecked the method will be called with a null String argument.

Example 4: Single Object valued checkbox with value bindings and a label

<webuijsf:checkbox id="cb4" label="Printer" selectedValue="#{tldRbCbExample.selectedValueCb4}" selected="#{tldRbCbExample.selectedCb4}" converter="#{tldRbCbExample.printerConverter}"/>

The value bindings #{tldRbCbExample.selectedCb4} and #{tldRbCbExample.selectedValueCb4} imply the following methods are implemented in the tldRbCbExample managed bean. If the object value is an instance of the "Printer" class, then the expected method signatures will be:

  • public void setSelectedCb4(Printer selected)
  • public Printer getSelectedCb4()
  • public void setSelectedValueCb4(Printer selected)
  • public Printer getSelectedValueCb4()
A Printer class might look like:

     public static class Printer {
private String name;
private String location;
public Printer(String name, String location) {
this.name = name;
this.location = location;
}
public String getName() {
return name;
}
public String getLocation() {
return location;
}
public boolean equals(Printer p) {
return this.name.equals(p.getName()) &&
this.location.equals(p.getLocation());
}
};

Since this is an application defined object value, the application must supply a converter, as indicated in the example. The converter attribute's value binding expression implies a method in the tldRbCbExample managed bean called

public Converter getPrinterConverter();.

The converter class might look like:
     public class PrinterConverter implements javax.faces.convert.Converter {
public PrinterConverter() {
}
public String getAsString(FacesContext context,
UIComponent component, Object value) {
if (!(value instanceof Printer)) {
throw new ConverterException("Not a Printer value");
}
return ((Printer)value).getName();
}
public Object getAsObject(FacesContext context,
UIComponent component, String value) {
if (!value.equals("printer1")) {
throw new ConverterException("Unrecognized printer: " + value);
}
return printerDb.getPrinter("printer1");
}
};

The getSelectedCb4 method will be called to determine the checked state of the checkbox during rendering.
When the tag is first rendered, its initial state is determined by the return value of getSelectedCb4. With an Object valued checkbox, this checkbox will be checked only if the getSelectedCb4 method returns a Printer instance that equals the Printer instance returned by the getSelectedValueCb4 method.
If the getSelectedCb4 method returns a Printer instance that is not equal as determined by getSelectedValueCb4().equals(getSelectedCb4()), then the checkbox will not be checked.
When the checkbox is checked by the user the setSelectedCb4 method will be called with the Printer instance returned by the converter.

Example 5: Grouped Integer valued checkboxes in a table

The following example shows a common use case for checkboxes in a table. The checkboxes are used to select zero or more rows for processing. The checkbox state does not need to be stored. The selected row indexes can be obtained directly as Integer values from the ArrayList of selected checkboxes maintained by the checkbox in the action callback #{tldRbCbExample.table5process}.
The markup in bold is how you would specify a checkbox tag for this purpose. The selectedValue value binding, #{tldRbCbExample.currentRow1} is implemented to return the current row in the table5row1 tableRow tag.

     <webuijsf:table id="table5">
<webuijsf:tableRow id="table5row1"
sourceData="#{tldRbCbExample.table5row1data}"
sourceVar="table5data"
binding="#{tldRbCbExample.table5row1}">
<webuijsf:tableColumn id="col1">
<f:facet name="header">
<webuijsf:tableHeader id="header1"
deselectAllButton="true"
selectAllButton="true"
selectId="cb5"/>
</f:facet>

<webuijsf:checkbox id="cb5" name="cb5Grp"
selectedValue="#{tldRbCbExample.currentRow1}">
</webuijsf:checkbox>

</webuijsf:tableColumn>
<webuijsf:tableColumn id="col2">
<f:facet name="header">
<webuijsf:staticText text="Application Data"/>
</f:facet>
<webuijsf:staticText text="#{table5data.text}"/>
</webuijsf:tableColumn>
</webuijsf:tableRow>
<f:facet name="tableActionsBottom">
<webuijsf:button id="table5process"
action="#{tldRbCbExample.table5process}"
text="Process Checked"/>
</f:facet>
</webuijsf:table>

See webuijsf:table for details on using the <webuijsf:table> tag and other table child tags and facets.

Normally when checkboxes are contained within a webuijsf:tableRow the application MUST provide a value binding for the selected attribute and any attribute that is expected to maintain its state. This is because the table only creates a single instance of the checkbox for all rows. It depends on a model to provide the storage for the attribute values, as it iterates over the rows in the dataset.
In this example, we don't need to maintain the state across requests because the rows just need to be selected for processing. Once the processing is complete, the checkbox no longer needs to be checked.

The following code shows how the table5process action method obtains the selected checkbox values from the request map. It calls a static member on Checkbox to return the ArrayList

public static ArrayList getSelected(String groupName)

     public void table5process() {
// Checkbox.getSelected(String groupName) is
// a static convenience method that obtains the
// ArrayList of selected checkboxes from the request map
// ONLY when the checkboxes are part of a group.
//
ArrayList al = Checkbox.getSelected("cb5Grp");
if (al != null) {
ListIterator li = al.listIterator();
while (li.hasNext()) {
processRow(((Integer)li.next()).intValue());
}
}
}

Example 6: Grouped boolean checkboxes in a table, using value bindings to maintain the state

This example is similar to Example 5, but it maintains the state of checkboxes across requests, by specifying a value binding for the selected attribute. A simple way to store the checkbox state is to store the state with the row data.

<webuijsf:checkbox id="cb6" selected="#{table6data.selected}"> </webuijsf:checkbox>

The value binding #{table6data.selected} references a boolean member in the row data for storing and retrieving the checkbox state. Notice also that it is not necessary to group the checkboxes by specifying a value for the name attribute. It is not useful to specify boolean checkboxes in a group, in order to obtain the list of selected checkboxes from the request map. The list will consist of indistinguishable true values; one for each selected checkbox.

Example 7: Update checkbox on the client side using the getProps and setProps functions

This example shows how to toggle the disabled state of a checkbox client side using the getProps and setProps functions.

<webuijsf:checkbox id="cb1" name="cb1" label="My Checkbox"/>
<webuijsf:button id="button1" text="Toggle Checkbox Disabled" onClick="toggleDisabled(); return false"/>

<webuijsf:script>
function toggleDisabled() {
var domNode = document.getElementById("form1:cb1");
domNode.setProps({ disabled: !domNode.getProps().disabled });
}
</webuijsf:script>

Example 8: Asynchronously update a checkbox using the refresh function

This example shows how to asynchronously update a checkbox using the refresh function. When the user clicks the button, the checkbox is asynchronously updated with new data.
<webuijsf:checkbox id="cb1" name="cb1" label="#{MyBean.label}"/>
<webuijsf:button id="button1" text="Refresh Checkbox" onClick="refreshCheckbox(); return false;"/>
<webuijsf:script>
    function refreshCheckbox() {
        var domNode = document.getElementById("form1:cb1"); // Get checkbox
        return domNode.refresh(); // Asynchronously refresh checkbox
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,..."). When no parameter is given, the refresh function acts as a reset. That is, the component will be redrawn using values set server-side, but not updated.

Example 9: Asynchronously update checkbox using refresh function

This example shows how to asynchronously update a checkbox using the refresh function. The execute property of the refresh function is used to define the client ID which is to be submitted and updated on the server-side. As the user types in the text field, the input value is updated on the server-side and the checkbox label is updated on the client-side -- all without a page refresh.
<webuijsf:checkbox id="cb1" name="cb1" label="#{MyBean.label}"/>
<webuijsf:textField id="field1" text="#{MyBean.label}" label="Change Radio Button Label"
onKeyPress="setTimeout('refreshCheckbox();', 0);"/> // Field used to asynchronously update label.
<webuijsf:script>
    function
refreshcheckbox() {
        var domNode = document.getElementById("form1:cb1"); // Get radio checkbox
        return domNode.refresh("form1:field1"); // Asynchronously refresh while submitting field value
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of IDs can be provided to update components on the server-side: refresh("form1:id1,form2:id2,...")

checkboxGroup

Use the webuijsf:checkboxGroup tag to display two or more check boxes in a grid layout in the rendered HTML page. The webuijsf:checkboxGroup tag attributes that you specify determine how the checkboxes are displayed.

If the label attribute is specified a com.sun.webui.jsf.component.Label component is rendered before the first checkbox and identifies the checkbox group. The label component's for attribute is set to the id attribute of the first checkbox in the rendered HTML page.

The checkboxes are laid out in rows and columns in an HTML <table> element. The number of rows is defined by the length of the items array. The number of columns is defined by the columns attribute. The default layout is a single vertical column.

The items attribute must be a value binding expression. The value binding expression assigned to the items property evaluates to an Object array of com.sun.webui.jsf.model.Option instances. Each instance represents one checkbox. The value property of an Option instance represents the value of a selected checkbox. If the items array is empty nothing is rendered.

Zero or more check boxes may be selected. The selected attribute must also be a value binding expression that is evaluated to read and write an Object array. When an array is read from the value binding expression, it identifies the selected checkboxes. Each element in the array is an Object value. Each Object value must be equal to the value property of at least one Option instance specified in the array obtained from the value binding expression assigned to the items attribute.

The write method of the selected attribute's value binding expression is called during the UPDATE_MODEL_PHASE of the JSF lifecyle. If one or more checkboxes are selected an Object array is passed as an argument to the write method. This array contains the Object values of the selected checkboxes.

HTML Elements and Layout

A webuijsf:checkboxGroup renders one com.sun.webui.jsf.component.Checkbox component for each element in the items array. See webuijsf:checkbox for details on the HTML elements and components rendered for a checkbox.

The value of the name attribute of each Checkbox component rendered is assigned the clientId of the CheckboxGroup component instance associated with this tag. The id attribute of each Checkbox component rendered is formed as follows, where cbgrpid is the ID of the CheckboxGroup instance and N is the nth checkbox.

  • cbgrpid_N

See webuijsf:checkbox for details on how the ID properties of the components that comprise checkbox are defined.

Theme Identifiers

  • CbGrp for the TABLE element.
  • CbGrpCpt for the TD element containing the group label
  • CbGrpLbl for the LABEL element used as the CAPTION
  • CbGrpLblDis for the LABEL used as the CAPTION if the group is disabled
  • CbGrpRwEv for even TR elements
  • CbGrpRwOd for odd TR elements
  • CbGrpClEv for even TD elements
  • CbGrpClOd for odd TD elements
  • Cb for the INPUT element
  • CbDis for the INPUT element for d disabled checkbox
  • CbLbl for a LABEL element of a checkbox
  • CbLblDis for a LABEL element of a disabled checkbox
  • CbImg for an IMG element of a checkbox
  • CbImgDis for an IMG element of a disabled checkbox
  • CbGrp - for the span element that encloses the entire set of elements rendered for the checkboxGroup.

Client Side JavaScript Functions

When the component is rendered, a DOM object corresponding to the component is created. To manipulate the component on the client side, you call functions on the DOM object. To disable the component, call document.getElementById(id).setProps({disabled: true}).

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. If omitted, no other components are executed.
setProps(props) Use this function to change any of the following supported properties:
  • align
  • className
  • contents
  • dir
  • disabled
  • id
  • label
  • lang
  • name
  • readOnly
  • style
  • tabIndex
  • title
  • visible
subscribe(topic, obj, func) Use this function to subscribe to an event topic.
  • topic: The event topic to subscribe to.
  • obj: The object in which a function will be invoked, or null for default scope.
  • func The name of a function in context, or a function reference to invoke when topic is published.

Client Side JavaScript Events

When the component is manipulated client-side, some functions might publish event topics for custom Ajax implementations to listen for. For example, you can listen for the refresh event topic bye using:

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

    // Subscribe to refresh event.
    var domNode = document.getElementById("form1:test1");
    domNode.subscribe(domNode.event.refresh.endTopic, processEvents, "update");


</webuijsf:script>

The following events are supported.

<Node>.event.refresh.beginTopic Event topic is published before asynchronously refreshing the component. 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
<Node>.event.refresh.endTopic Event topic is published after asynchronously refreshing the component. Supported properties include: See setProps() function.
  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage

Code Examples

Example 1: Create a Checkbox Group

 <webuijsf:checkboxGroup items="#{rbcbGrp.selections}"
    label="#{rbcbGrp.cbGrpLabel}"
    toolTip="cbgrp-tooltip"
    disabled="false"
    tabIndex="4"
    selected="#{rbcbGrp.cbvalue}">
 </webuijsf:checkboxGroup>

This example creates a checkbox group with an identifying label for the group before the first checkbox. The data for the checkboxes is obtained from the value binding expression #{rbcbGrp.selections}. rbcbGrp is an application defined managed bean and provides the values for other attributes such as selected to receive the value of the selected checkboxes in the group.

Example 2: Update CheckboxGroup Client-Side Using the GetProps and SetProps Functions

This example shows how to toggle the disabled state of a checkboxGroup client-side using the getProps and setProps functions.

<webuijsf:checkboxGroup id="cb1" name="cb1" items="#{rbcbGrp.selections}" selected="#{rbcbGrp.cbvalue}" label="#{rbcbGrp.cbGrpLabel}"/>
<webuijsf:button id="button1" text="Toggle CheckboxGroup Disabled" onClick="toggleDisabled(); return false"/>

<webuijsf:script>
function toggleDisabled() {
var domNode = document.getElementById("form1:cb1");
domNode.setProps({ disabled: !domNode.getProps().disabled });
}
</webuijsf:script>

Example 3: Asynchronously update checkboxGroup using refresh function

This example shows how to asynchronously update a checkboxGroup using the refresh function. When the user clicks on the button, the checkboxGroup is asynchronously updated with new data.
<webuijsf:checkboxGroup id="cb1" name="cb1" items="#{rbcbGrp.selections}" selected="#{rbcbGrp.cbvalue}" label="#{rbcbGrp.cbGrpLabel}"/>
<webuijsf:button id="button1" text="Refresh CheckboxGroup" onClick="refreshGroup(); return false;"/>
<webuijsf:script>
    function refreshGroup() {
        var domNode = document.getElementById("form1:cb1"); // Get checkboxGroup
        return domNode.refresh(); // Asynchronously refresh checkboxGroup
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,..."). When no parameter is given, the refresh function acts as a reset. That is, the component will be redrawn using values that have been set server-side, but not updated.

Example 4: Asynchronously update checkboxGroup using refresh function

This example shows how to asynchronously update a checkboxGroup using the refresh function. The execute property of the refresh function is used to define the client ID which is to be submitted and updated server-side. As the user types in the text field, the input value is updated server-side and the checkboxGroup label is updated client-side -- all without a page refresh.
<webuijsf:checkboxGroup id="cb1" name="cb1" items="#{rbcbGrp.selections}" selected="#{rbcbGrp.cbvalue}" label="#{rbcbGrp.cbGrpLabel}"/>
<webuijsf:textField id="field1" text="#{rbcbGrp.cbGrpLabel}" label="Change CheckboxGroup Label"
onKeyPress="setTimeout('refreshCheckboxGroup();', 0);"/> // Field used to asynchronously update label.
<webuijsf:script>
    function
refreshCheckboxGroup() {
        var domNode = document.getElementById("form1:cb1"); // Get checkboxGroup
        return domNode.refresh("form1:field1"); // Asynchronously refresh while submitting field value
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of IDs can be provided to update components server-side: refresh("form1:id1,form2:id2,...")

commonTask

Use the webuijsf:commonTask tag to create a single task within a common tasks section or common tasks group.

Tasks can be used in the followin ways:

  • to invoke simple actions that can be performed in a single dialog
  • to start a wizard to aid in performing a complex action,
  • to quickly navigate to a particular area of the application.
The tasks can be grouped into categories of related tasks.

The common tasks section is created with the following tags:

  • webuijsf:commonTasksSection tag is used to define the structure of the common task area,
    and is a container for webuijsf:commonTasksGroup tags.

  • webuijsf:commonTasksGroup tag is used to define the groups of tasks,
    and is a container for webuijsf:commonTask tags.

  • webuijsf:commonTask tag is used to define each task.

The webuijsf:commonTasksGroup is not required as a container for webuijsf:commonTask tags. Tasks can be ungrouped by placing the webuijsf:commonTask tags directly in the webuijsf:commonTasksSection tag.

See the documentation for the webuijsf:commonTasksSection and webuijsf:commonTasksGroup tags for more information about those tags.

HTML Elements and Layout

The commonTask component renders XHTML <span> and <a> elements within table rows rendered by the commonTasksSection component. Each task is a link that can be used to redirect users to a page where they can perform a particular task.

The following diagram shows the relative locations of the common task section's areas for which you can define content, and the attributes or facets that can be used for each area. The diagram shows the default two-column layout. A single column or multiple column layout would contain similar content areas.

The areas that are specified with webuijsf:commonTask tags are highlighted in blue. The grayed out areas are controlled with webuijsf:commonTasksSection and webuijsf:commonTasksGroup tags, but are shown here for context.

Common Tasks Section Title (title attribute)
Help text (helpText attribute or help facet)
Common Task Group 1 Title (title attribute)
Common Task Group 2 Title (title attribute)
Image
(icon or
imageUrl attribute)

Common Task 1 Text
(text attribute or
taskAction facet)

Info button
(infoText or infoTitle attribute
or infoPanel facet)

Image
(icon or
imageUrl attribute)
Common Task 2 Text
(text attribute or
taskAction facet)
Info button
(infoText or infoTitle attribute
or infoPanel facet)
Areas below are displayed when the info button is clicked.
Information panel title (infoTitle attribute)

Information text (infoText attribute
or infoPanel facet)
Link to another page (infoLinkText and infoLinkUrl attributes, or infoLink facet)

Image
(icon or
imageUrl attribute
Common Task 1 Text
(text attribute or
taskAction facet)

Info button
(infoText or infoTitle attribute
or infoPanel facet)

Image
(icon or
imageUrl attribute)
Common Task 2 Text
(text attribute or
taskAction facet)

Info button
(infoText or infoTitle attribute
or infoPanel facet)

Image
(icon or
imageUrl attribute)
Common Task 3 Text
(text attribute or
taskAction facet)

Info button
(infoText or infoTitle attribute
or infoPanel facet)



Configuring the webuijsf:commonTask tag

For the basic configuration of the webuijsf:commonTask tag, you can provide the task text with the text attribute, and specify the page that must be navigated to by using the actionExpression attribute or by using one of the client side JavaScript attributes such as onClick. A link that displays the specified text value is created to invoke the action.

You can configure the webuijsf:commonTask tag so that the task includes an information icon after the task text. When the user clicks the icon, an information panel opens below the task. To cause the information icon to be rendered, you should set one or both of the infoText and infoTitle attributes. Use infoText to specify the text to display in the information panel, and infoTitle to supply a title for the information panel. You can include a link within the information panel by specifying the infoLinkText and infoLinkUrl attributes. The link is displayed at the bottom of the information panel.

You can also use facets to create the task and the information panel with other components. See the Facets section for more information.

You can display a graphic image in front of the task by using the icon attribute to specify a theme image key. The key COMMON_TASK_OVERVIEW will generate an image that can be used to mark tasks that are for overview information about the task. You can also use the imageUrl attribute to specify the URL path to an image.

Facets

The webuijsf:commonTask tag supports the following facets:

taskAction
Used to define a custom component to be displayed for the task. The component that you specify in this facet should invoke an action for the task. See Examples to learn how to use this facet.
infoLink
Used to define a custom component to be displayed in the information panel, to replace the link that is created with the infoLinkText and infoLinkUrl attributes.
infoPanel
Used to create the content of the information panel, to replace the content that is created with the infoText and infoTitle attributes. When you use this facet, the info button is rendered just as it is for the infoText and infoTitle attributes. You cannot specify your own info button. Note that you must handle the formatting of the output that appears in the infomation panel. For example, you might use webuijsf:panelGroup and CSS syles, to control spacing. See Examples to see how to use the facet.

Code Examples

Example 1: Creating tasks with tag attributes

<webuijsf:commonTasksSection id="tasks1" title = "#{tasks.tskTtl}">
   <webuijsf:commonTaskGroup id="Taskgroup1" title="#{tasks.grpTtl}" >
     <webuijsf:commonTask id="task1" text="#{tasks.tskTxt1}" actionExpression="task1" />
     <webuijsf:commonTask id="task2" text="#{tasks.tskTxt2}" actionExpression="task2"/>
     <webuijsf:commonTask id="task3" text="#(tasks.tskTxt3)" onClick="popup();return false;"/>
    </webuijsf:commonTaskGroup>
</webuijsf:commonTasksSection>


Example 2: Creating a task with the taskAction facet

<webuijsf:commonTasksSection id="tasks1" title = "#{tasks.tskTtl}">
  <webuijsf:commonTaskGroup id="Taskgroup1" title="#{tasks.grpTtl}" >
     <webuijsf:commonTask id="task1" >
       <f:facet name="taskAction" >
         <webuijsf:hyperlink id="taskLink" text="#{tasks.facetLink}" actionExpression="linkAction"/>
       </f:facet>
     </webuijsf:commonTask> 
     <webuijsf:commonTask id="task2" text="#{tasks.tskTxt2}" actionExpression="task2" />
     <webuijsf:commonTask id="task3" text="#(tasks.tskTxt3)" onClick="popup();return false;"/>
  </webuijsf:commonTaskGroup>
</webuijsf:commonTasksSection>

Example 3: Displaying a task's toggled info panel by using tag attributes

<webuijsf:commonTasksSection id="tasks1" title = "#{tasks.tskTtl}">
   <webuijsf:commonTaskGroup id="Taskgroup1" title="#{tasks.grpTtl}" >
       <webuijsf:commonTask id="task1" text="#{tasks.tskTxt1}" actionExpression="task1"
                          infoTitle = "#{tasks.tskTtl1}" infoText="#{task.tskTxt1}"
                          infoLinkText="#{tasks.lnkTxt}" infoAction="task1Help"/>
       <webuijsf:commonTask id="task2" text="#{tasks.tskTxt2}" actionExpression="task2"
                          infoTitle = "#{tasks.tskTtl2}"
                          infoLinkText="#{tasks.lnkTxt2}" infoAction="task2Help"
                          infoText="#{tasks.tskTxt2}"/>
   </webuijsf:commonTaskGroup>
</webuijsf:commonTasksSection>

Example 4: Using the infoPanel facet to display toggled info panel

<webuijsf:commonTasksSection id="tasks1" title = "#{tasks.tskTtl}">
   <webuijsf:commonTaskGroup id="Taskgroup1" title="#{tasks.grpTtl}" >
      <webuijsf:commonTask id="task1" text="#{tasks.tskTxt1}" actionExpression="task1" />
         <f:facet name="infoPanel">
          <webuijsf:panelGroup id="panelGrp1">
           <webuijsf:staticText id="staticText1" text="#{tasks.tskInf}"/>
           <webuijsf:image id="image2" url="/images/dot.gif"/>
          </webuijsf:panelGroup>
         </f:facet>
      </webuijsf:commonTask> 
      <webuijsf:commonTask id="task2" text="#{tasks.tskTxt2}"
                           actionExpression="task2" infoTitle = "#{tasks.lnkTtl2}"
                           infoText="#{tasks.tskTxt2}"/>
  </webuijsf:commonTaskGroup>
</webuijsf:commonTasksSection>

Example 5: Using the infoLink facet to add a link to info panel

<webuijsf:commonTasksSection id="tasks1" title ="#{tasks.tskTtl}">
  <webuijsf:commonTaskGroup id="Taskgroup1" title="#{tasks.grpTtl}" >
     <webuijsf:commonTask id="task1" text="#{tasks.tskTxt1}"
                          actionExpression="task1" infoTitle = "#{task.tskTtl1}"
                          infoText="#{task.tskTxt1}" infoLinkText="#{task.lnkTxt}"
                          infoAction="task1Help" />
     <webuijsf:commonTask id="task2" text="#{tasks.tskTxt2}"
                          actionExpression="task2" infoTitle = "#{task.tskTtl2}"
                          infoText="#{task.tskTxt2}">
             <f:facet name="infoLink">
                  <webuijsf:hyperlink id="link" text="#{task.PnlLnk}" url="http://www.google.com"/> 
             </f:facet>
     </webuijsf:commonTask>
  </webuijsf:commonTaskGroup>
</webuijsf:commonTasksSection>

commonTasksGroup

Use the webuijsf:commonTasksGroup tag to create a group of related tasks within a common tasks section. The common tasks * group displays the contained tasks together in the common tasks section, under an appropriate title that you specify.

The common tasks section is created with the following tags:

  • webuijsf:commonTasksSection tag is used to define the structure of the common task area,
    and is a container for webuijsf:commonTasksGroup tags.

  • webuijsf:commonTasksGroup tag is used to define the groups of tasks,
    and is a container for webuijsf:commonTask tags.

  • webuijsf:commonTask tag is used to define each task.

The webuijsf:commonTasksGroup is not required as a container for webuijsf:commonTask tags. Tasks can be grouped or ungrouped within the common tasks section.

See the documentation for the webuijsf:commonTasksSection and webuijsf:commonTask tags for more information about those tags.

HTML Elements and Layout

The commonTasksGroup component renders XHTML <div> and <span> elements. The following diagram shows the relative location of the component's areas for which you can define content, and the attributes or facets that can be used for each area. The diagram shows the default two-column layout. A single column or multiple column layout would contain similar content areas.

The areas that are specified with the webuijsf:commonTasksGroup tag are highlighted in blue. The grayed out areas are controlled with webuijsf:commonTasksSection and webuijsf:commonTask tags, but are shown here for context.


Common Tasks Section Title (title attribute)
Help text (helpText attribute or help facet)

Common Task Group 1 Title (title attribute)
Common Task Group 2 Title (title attribute)
Image
Common Task 1 Text
Info
button
Image
Common Task 2 Text
Info
button

Image
Common Task 1 Text
Info
button
Image
Common Task 2 Text
Info
button
Image
Common Task 3 Text
Info
button


Configuring the webuijsf:commonTasksGroup tag

You can specify a title for the task group by using the title attribute.

Facets

None.

Code Examples

Example1: Grouping tasks using a webuijsf:commonTasksGroup component

<webuijsf:commonTasksSection id="tasks1" title = "#{tasks.tskTtl}">
    <webuijsf:commonTaskGroup id="Taskgroup1" title="#{tasks.grpTtl}">
       <webuijsf:commonTask id="task1" text="#{tasks.tskTxt1}" action="task1" />
       <webuijsf:commonTask id="task2" text="#{tasks.tskTxt2}" action="task2" />
    </webuijsf:commonTaskGroup>
</webuijsf:commonTasksSection>


commonTasksSection

Use the webuijsf:commonTasksSection tag to create a page or area of a page to present a number of tasks that users might commonly perform in the web application. The tasks typically are intended to make it easier for users to perform actions that could also be done using various features of the application.

Tasks can be:

  • used ti invoke simple actions
  • used to start a wizard to aid in performing a complex action
  • used to quickly navigate to a particular area of the application.
The tasks can be grouped into categories of related tasks.

The common tasks section is created with the following tags:
  • webuijsf:commonTasksSection tag is used to define the structure of the common task area,
    and is a container for webuijsf:commonTasksGroup tags and webuijsf:commonTask tags.

  • webuijsf:commonTasksGroup tag is optionally used to define groups of tasks, and is a container for webuijsf:commonTask tags.

  • webuijsf:commonTask tag is used to define each task.

See the documentation for the webuijsf:commonTasksGroup and webuijsf:commonTask tags for more information about those tags.

HTML Elements and Layout

The commonTasksSection component renders XHTML <div> and <table> elements. The component will accept any number of task groups and tasks, and distribute them on the page so that they are visually balanced into columns of roughly equal size.

The following diagram shows the relative location of the component's areas for which you can define content, and the attributes or facets that can be used for each area. The diagram shows the default two-column layout. A single column or multiple column layout would contain similar content areas.

The areas that are specified with the webuijsf:commonTasksSection tag  attributes are highlighted in blue. The grayed out areas are controlled with webuijsf:commonTasksGroup and webuijsf:commonTask tags, but are shown here for context.

Common Tasks Section Title (title attribute)
Help text (helpText attribute or help facet)
Common Task Group 1 Title
Common Task Group 2 Title (title attribute)
Image
Common Task 1 Text
Info
button
Image
Common Task 2 Text
Info
button

Image
Common Task 1 Text
Info
button
Image
Common Task 2 Text
Info
button

Common Task 3 Text
Info
button

Configuring the webuijsf:commonTasksSection tag

You can configure the title, help text, and number of columns displayed in the common tasks section.

Title: The webuijsf:commonTasksSection jsp tag provides the title attribute, which you can use to specify the text to display in the Common Task Section title. If you do not specify a title, the title "Common Tasks" is rendered by default.

Help text: The help text that is displayed under the title can be specified with the helpText attribute, or the help facet. See the Facets section for more information about the facet. When you use the helpText attribute, the specified help text is displayed in a smaller font below the title. If you do not specify the help text, the default help text is displayed: "To access information about a task select the "i" info button."

Number of Columns: The common tasks section displays tasks grouped in two columns by default, when there are no task groups, or multiple task groups. If there is one task group, a single column layout is used. You can customize the number of columns on the common tasks section by setting the columns attribute to the number of columns you want to display. For example, if you specify columns="3", the common tasks groups will be displayed in three columns.

Setting the Page Background Color

In a JSP page where you use the webuijsf:commonTasksSection tag, you should set the style class to commonTaskbgColor for the body tag. For example:

 <webuijsf:body styleClass="#{themeStyles.CTS_BACKGROUND}" >

The commonTaskbgColor style class sets the page's background color to the same gradient color used in the commonTasksSection component. If this color is not used, you might see a white space after the common tasks section.

Facets

You can use the commonTasksSection component's help facet to specify a different component to use to display the help text. The help is rendered below the title by the component that you specify. See the Examples section for an example that uses the help facet. 

Code Examples

Example 1: Specifying a custom title

<webuijsf:commonTasksSection id="tasks1" title = "#{tasks.tskTtl}">
    <webuijsf:commonTaskGroup id="Taskgroup1" title="#{tasks.grpTtl}">
       <webuijsf:commonTask id="task1" text="#{tasks.tskTxt1}" actio
nExpression="task1" />
       <webuijsf:commonTask id="task2" text="#{tasks.tskTxt2}" actio
nExpression="task2" />
    </webuijsf:commonTaskGroup>
</webuijsf:commonTasksSection>


Example 2: Overriding the default inline help with the help facet

 <webuijsf:commonTasksSection id="tasks1" title = "#{tasks.tskTtl}">
    <f:facet name="help" >
       <webuijsf:helpInline id="commontaskshelp" text="#{tasks.hlpTxt}"/> 
    </f:facet> 
    <webuijsf:commonTaskGroup id="Taskgroup1" title="#{tasks.grpTtl}">
       <webuijsf:commonTask id="task1" text="#{tasks.tskTxt1}" actio
nExpression="task1" />
       <webuijsf:commonTask id="task2" text="#{tasks.tskTxt2}" actio
nExpression="task2"/>
    </webuijsf:commonTaskGroup>
 </webuijsf:commonTasksSection>


Example 3: Specifying three columns

<webuijsf:commonTasksSection id="tasks1" title = "#{tasks.tskTtl}" columns="3">
    <webuijsf:commonTaskGroup id="Taskgroup1" title="#{tasks.grpTtl}">
       <webuijsf:commonTask id="task1" text="#{tasks.tskTxt1}" actionExpression="task1" />
       <webuijsf:commonTask id="task2" text="#{tasks.tskTxt2}" actio
nExpression="task2" />
    </webuijsf:commonTaskGroup>
</webuijsf:commonTasksSection>


The Common Tasks Section component. This encapsulates a number of common task group components.
contentPageTitle

Use the webuijsf:contentPageTitle tag to display an <h1> heading as a page title, and the following optional page elements:

  • help text
  • page buttons
  • page actions
  • page view controls
  • separator image

The title text and help text can be specified by using the webuijsf:contentPageTitle tag's attributes, and also by using facets. The page buttons, page actions, and page view controls can only be specified with facets. The facets are described in the Facets section.

The separator image is displayed automatically when you use page buttons that are displayed on the bottom. You can set the separator attribute to false to prevent the separator from being rendered.

HTML Elements and Layout

The contentPageTitle component can be used to create just a title for a page, or to provide a title and structure to the content area of the web application page. The content area is the portion where the main content of the page is displayed, and the user can optionally interact with the information.

If your application page includes a masthead and breadcrumbs, the webuijsf:contentPageTitle tag should be used after the webuijsf:masthead and webuijsf:breadcrumbs tags. If you want to use the contentPageTitle component's other features, such as page buttons and actions, you should place the rest of the page content within the webuijsf:contentPageTitle tag. You can use the supported facets to place the controls in the page along with your content. If you simply want to create a title, place the page content outside the webuijsf:contentPageTitle tag.

The webuijsf:contentPageTitle tag must be placed in a form if you are using the page controls.

The following diagram shows the location of the page elements and the names of the facets you can use to specify the content for each area.

Page Title Text (or optional pageTitle facet)

Optional pageButtonsTop facet

Optional help text or pageHelp facet
Optional pageActions facet

Optional pageViews facet

 

... JSF Page Content ..

 

Optional Page Separator or pageSeparator facet

  Optional pageButtonsBottom facet

 

Facets

The webuijsf:contentPageTitle tag supports the facets in the following table.

pageTitle
Specifies a component tag to use for the title of the content page of the web application. This facet overrides the title attribute.
pageButtonsTop

Specifies the buttons to use for the page buttons at the top right of the page. By default no buttons are rendered, so you must use this facet to display top page buttons. To display two or more buttons, enclose the webuijsf:button tags within a webuijsf:panelGroup tag.

pageButtonsBottom

Specifies the buttons to use for the page buttons at the bottom right of the page. By default no buttons are rendered, so you must use this facet to display bottom page buttons. To display two or more buttons, enclose the webuijsf:button tags within a webuijsf:panelGroup tag.

pageHelp Specifies a component tag to use for brief help text that is displayed under the page title. This facet overrides the helptext attribute.
pageActions Specifies component tags to use for any components that can be used to launch actions. Tags that might be used to launch actions include webuijsf:button and webuijsf:dropDown.
pageViews
Specifies a component tag that allows the user to change the view of the page. The webuijsf:dropDown tag can be used to provide a list of views.
pageSeparator Specifies a component tag to use for the separator image, such as the webuijsf:image tag. Display of the separator is controlled by the separator attribute.

Theme Identifiers

TBA

Client Side Javascript Functions

None.

Code Examples

Example 1: Using facets for optional contentPageTitle elements

<webuijsf:contentPageTitle title="Masthead and Page Title Example" helpText="Help text would go here">
   <f:facet name="pageButtonsTop">
     <webuijsf:panelGroup id="pageButtonsGroupTop"> 
       <webuijsf:button label="Save" action="#{MastheadBean.saveClicked}" /> 
       <webuijsf:button label="Reset" secondary="true" action="#{MastheadBean.resetClicked}" />
     </webuijsf:panelGroup> 
   </f:facet> 
   <f:facet name="pageButtonsBottom">
     <webuijsf:panelGroup id="pageButtonsGroupBottom"> 
       <webuijsf:button label="Save" action="#{MastheadBean.saveClicked}" /> 
       <webuijsf:button label="Reset" secondary="true" action="#{MastheadBean.resetClicked}" />
     </webuijsf:panelGroup> 
   </f:facet> 
   <f:facet name="pageActions">
     <webuijsf:panelGroup id="pageActionsGroup">
       <webuijsf:button label="Action 1" action="#{MastheadBean.action1Clicked}" />
       <webuijsf:button label="Action 2" action="#{MastheadBean.action2Clicked}" />
       <webuijsf:button label="Action 3" action="#{MastheadBean.action3Clicked}" />
     </webuijsf:panelGroup>
   </f:facet> 
   <f:facet name="pageViews">
     <webuijsf:dropDown label="View:" items="#{MastheadBean.views}" />
   </f:facet> 
       ... JSF page content ... 
 </webuijsf:contentPageTitle>
dndContainer

Use the webuijsf:dndContainer tag to create a drag, drop or drag-and drop container. Drag container will make all contained elements draggable. Drop container will allow draggable elements to be dropped in. Drag-and-drop has qualities of the both.

  • Elements within container can be selected for single and multiple selections

  • Elements can be dropped within the same container ( rearranged) or into other dndContainers provided that the drop containers accepts drops of this particular dragType.

  • For the purpose of dragging all elements are identified with

    1. dragType – aimed to facilitate the acceptance check at the drop site. All elements inherit the same type set from the container ( in this case type set is associated with the container, and propagated down to elements)

    2. dragData – payload. The data is furnished to the drop container ( and available to the user) when new element is created there.

  • When dragged, an avatar ( moving image) is created.

  • When dropped, the new element at the destination is created: user can use default logic on creating new nodes when element is dropped( deep node clone), or provide a user's function onNodeCreateFuncthat takes care of creating DOM elements based on the data supplied by each element ( see payload above).

  • User may supply a onDropFunc to add custom logic based to the drop process.

DndContainer component represents a "render-only" component and the JSF component tree will not reflect any changes performed on the client side.

HTML Elements and Layout

The dndContainer component renders a set of nested XHTML <div> or <span> elements.

Configuring the webuijsf:dndContainer Tag

Use the dragTypes attribute to associate any of the nested components with a list of specified types, by setting the attribute's value to a comma-separated list of types or an EL expression that corresponds to a property of a backing bean. If dragTypes is not specified, container will not behave as a source of drag items.

Use the dropTypes attribute to make container a drop target and accept drops of specified types, by setting the attribute's value to a comma-separated list of accepted types or an EL expression that corresponds to a property of a backing bean. If dropTypes is not specified, container will not behave as a target of drag items.

Facets

    None

Client Side Javascript Functions

When the component is rendered, a DOM object corresponding to the component is created. To manipulate the component on the client side, you may invoke functions on the DOM object. With reference to the DOM id, to hide the component, invoke document.getElementById(id).setProps({visible: false}).

getProps()

Use this function to get widget properties. Please see setProps() function for a list of supported properties.

setProps(props)

Use this function to change any of the following supported properties:

  • style

  • visible



Examples

Example 1: Create draggable image

This example creates a drag container that contains a draggable image within. Drag item will be associated with types “words” and “sentences”.

               <webuijsf:dndContainer id="drag" 
                    dragTypes = "words, sentences" 
                    visible="true"
                    style="position: absolute; top:125px; left: 10px; width: 200px; background: #eee repeat;"
                    >
                    <img src="pond.jpg" style="width:100px;"/>
                </webuijsf:dndContainer>

Example 2: Create draggable image

In addition to the previos example, this example will container draggable staticText component, html text, and textArea.

               <webuijsf:dndContainer id="drag" 
                    dragTypes = "words, sentences" 
                    visible="true"
                    style="position: absolute; top:125px; left: 10px; width: 200px; background: #eee repeat;"
                    >
                    <img src="pond.jpg" style="width:100px;"/>  
                    <webuijsf:staticText id = "t1" text = "and they say"/>                   
some text <webuijsf:textArea text = "content" columns="3" rows = "3" label ="Directions:"/> </webuijsf:dndContainer>

Example 3: Create drop container

This example creates container that will accept drops of items with types “words” and “sentences”. Container will also display an image, but the image will not be draggable.

                   <webuijsf:dndContainer id="drag" 
                    dropTypes = "words, sentences" 
                    visible="true"
                    style="position: absolute; top:125px; left: 10px; width: 200px; background: #eee repeat;"
                    >
                    <img src="pond.jpg" style="width:100px;"/>
                </webuijsf:dndContainer>



dropDown

Use the webuijsf:dropDown tag to display a drop-down menu that enables users to select one or more items from a list. The drop-down menu occupies one line of the page, and displays one list item. The rest of the list items are displayed when the user opens the menu.

The webuijsf:dropDown tag can be configured to immediately submit the form when the user makes a selection. By default, the drop-down

HTML Elements and Layout

The dropDown component renders an XHTML <select> element with an optional <label> element. The <option> elements within the <select> element are derived from the webuijsf:dropDown tag's items attribute.

Configuring the webuijsf:dropdown tag

Use the items attribute to specify the options to be displayed in the drop-down menu. The value must be a JavaServer Faces EL expression that identifies an array, a java.util.Collection or a java.util.Map of com.sun.webui.jsf.model.Option.

The first time the component is rendered, the option that corresponds to the value of the selected model object property is marked as selected, using the equals method on the model object. On subsequent displays of the page, the previously selected option is redisplayed as the selection. If you want the menu to always show the default selection, set the forgetValue attribute to true.

To optionally specify a label for the component, use the label attribute, or specify a label facet.

Configuring a Jump Menu

A drop-down menu can be configured as a jump menu. Jump menus immediately perform an action, such as opening a window or navigating to another page, when the user selects an item. This action is accomplished by submitting the form immediately when the user changes the selection. By default, the dropDown menu is not a jump menu. The submission of the form does not occur until the user activates another component such as a button in order to submit the form.

To configure the webuijsf:dropDown tag to render a jump menu, set the submitForm attribute to true. If the jump menu is to be used to navigate to another location, you should also use the navigateToValue attribute and include outcome strings in the drop-down menu's list of options. In addition, you should set the forgetValue attribute to true to cause the dropDown's selected value to be reset when the page is redisplayed. This enables the dropDown to always display the same option initially.

If the jump menu is to perform an action other than navigation, you should use the actionListener attribute to bind to a method to handle the action.

The immediate attribute is useful in a jump menu when you do not want to submit any data entered into the form when a selection is made in the jump menu.

Using a Title in the Drop-Down Menu

You can display a non-selectable title as the first item in a drop-down menu. The title might be used to provide a brief instruction for the user, such as "Select a page".

To create a title in a drop-down menu, when you define your drop down menu items in an Option[], you must specify the first Option as type OptionTitle along with the string to display. The title is rendered as the specified string with dashes before and after the text, to differentiate the title from the selectable options.

For example, in this sample backing bean Option, the OptionTitle option is bolded.

public BackingFileDropDown() {
    pageOptions = new Option[4];
    pageOptions[0] = new OptionTitle("Select a Page");
    pageOptions[1] = new Option("indexPage", "Main Page");
    pageOptions[2] = new Option("printerPage", "Printer Status");
    pageOptions[3] = new Option("faxPage", "Fax Machines");
}

In addition, you should set the webuijsf:dropDown tag's forgetValue attribute to true, to ensure that the title is always displayed in the drop-down menu when the page is rendered.

Grouping Options in the Drop-Down Menu

The XHTML <select> element can contain an <optgroup> element to define a group of related items in a drop-down menu. The <optgroup> has a label, and the options within the group are indented in the displayed menu. You can configure the list of items created with the webuijsf:dropDown tag to be rendered with <optgroup> elements by setting up your backing bean appropriately. A backing bean object that populates the drop-down menu with grouped options might look as follows.

public BackingFileDropDown2() {
    actionOptions = new Option[5];
    actionOptions[0] = new OptionTitle("More Actions");
    actionOptions[1] = new Option("Action1", "Action 1");
    actionOptions[2] = new Option("Action2", "Action 2");
    actionOptions[2].setDisabled(true);
    actionOptions[3] = new Option("Action3", "Action 3");

    OptionGroup group = new OptionGroup();
    group.setLabel("ActionGroup");

    Option[] groupedOptions = new Option[3];
    groupedOptions[0] = new Option("Action4", "Action 4");
    groupedOptions[1] = new Option("Action5", "Action 5");
    groupedOptions[2] = new Option("Action6", "Action 6");
    groupedOptions[2].setDisabled(true);
    group.setOptions(groupedOptions);
    actionOptions[4] = group;
}

The drop-down menu that is rendered with this property will appear as follows:

The important points to note in the sample backing bean are:

  • The OptionGroup group has a setLabel method that sets the label of the <optgroup> to "ActionGroup".

  • A separator (a series of dashes) is rendered above the optgroup label. By default, the separator is rendered above each optgroup in a drop-down menu. The separators can be removed by setting the webuijsf:dropDown tag's separators attribute to false. 

  • The group is defined as the last item in the actionOptions Option instance. The setOptions method sets the options of the group to the groupedOptions object values.

  • The setDisabled method can be used to disable any of the options in the drop-down menu.

Facets

The webuijsf:dropDown tag supports a label facet. Use this facet to specify a custom component for the label. This facet overrides the label attribute.

Client-side JavaScript Functions

When the component is rendered, a DOM object corresponding to the component is created. To manipulate the component on the client side, you may invoke functions on the DOM object. With reference to the DOM ID, to disable the component, invoke document.getElementById(id).setProps({visible: false}).

getProps() Used to get widget properties. Please see setProps() function for a list of supported properties.
getSelectElement() Used to access the HTML <select> element that is rendered by the component.
getSelectedLabel() Used to get the label of the first selected option on the dropDown. If no option is selected, this function returns null.
getSelectedValue() Used to  get the value of the first selected option on the dropDown. If no option is selected, this  function returns null.
refresh(execute) Used 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. If omitted, no other components are executed.
setProps(props) Used to change any of the following supported properties:
  • id
  • dir
  • disabled
  • label
  • lang
  • multiple
  • onBlur
  • onChange
  • onClick
  • onDblClick
  • onFocus
  • onMouseDown
  • onMouseOut
  • onMouseOver
  • onMouseUp
  • onMouseMove
  • onKeyPress
  • onKeyUp
  • onSelect
  • options
  • size
  • submitForm
  • style
  • tabIndex
  • title
  • visible
submit(execute)
Used 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.
subscribe(topic, obj, func) Use this function to subscribe to an event topic.
  • topic: The event topic to subscribe to.
  • obj: The object in which a function will be invoked, or null for default scope.
  • func The name of a function in context, or a function reference to invoke when topic is published.

Client-side JavaScript Events

When the component is manipulated client-side, some functions might publish event topics for custom Ajax implementations to listen for. For example, you can listen for the refresh event topic by using:

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

    // Subscribe to refresh event.
    var domNode = document.getElementById("form1:test1");
    domNode.subscribe(domNode.event.refresh.endTopic, processEvents, "update");


</webuijsf:script>

The following events are supported.

<Node>.event.refresh.beginTopic Event topic published before asynchronously refreshing the component. 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
<Node>.event.refresh.endTopic Event topic published after asynchronously refreshing the component. Supported properties include:
  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage
<Node>.event.submit.beginTopic Event topic published before asynchronously submitting the component. 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
<Node>.event.submit.endTopic

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

  • props - JSON object containing messages (if any) raised by the server.In particular, valdiation messages will be present here if validation failed

Examples

Example 1: Drop-Down Menu Using Backing Beans

This example uses several backing beans. The options to display in the drop-down menu are provided in the items attribute, which is set to an EL expression that resolves to an airports array in the dataBean. The tag generates a drop-down menu with a label, which is specified with the label attribute, and the label text is obtained from the chooseDepartureAirport property of a msgs bean. The tooltip text is provided in a similar way. The selected attribute specifies the option to show as selected in the menu, with the value stored in the leaveAirport property of the flightSearch backing bean.

     <webuijsf:dropDown selected="#{flightSearch.leaveAirport}" 
items="#{dataBean.airports}"
id="leaveAirport"
tooltip="#{msgs.chooseAirport}"
label="#{msgs.chooseDepartureAirport}" />

The dataBean backing bean would include the following definition for the "airports" items:

     private Option[] airports = null;
// Creates a new instance of backing bean //
public DataBean() {
airports = new Option[11];
airports[0] = new Option("SFO", "San Francisco");
airports[1] = new Option("OAK", "Oakland");
airports[2] = new Option("SAN", "San Diego");
airports[3] = new Option("BOS", "Boston");
airports[4] = new Option("ARN", "Stockholm");
airports[5] = new Option("MNL", "Manila");
airports[6] = new Option("CDG", "Paris");
airports[7] = new Option("PDX", "Portland");
airports[8] = new Option("LAX", "Los Angeles");
airports[9] = new Option("NRT", "Tokyo");
airports[10] = new Option("TBD", "Future Airport");
airports[10].setDisabled(true);
}
public Option[] getAirports() {
return airports;
}

Example 2: Drop-Down Menu With Label Facet

This example is the same as Example 1 except that it uses the label facet, which contains a webuijsf:label tag.

     <webuijsf:dropDown selected="#{flightSearch.leaveAirport}" 
items="#{dataBean.airports}"
id="leaveAirport"
tooltip="#{msgs.chooseAirport}" >
<f:facet name="label">
<webuijsf:label text="#{msgs.chooseDepartureAirport}" for="menuform1:leaveAirport"/>
</f:facet>
</webuijsf:dropDown>

Example 3: Jump Drop-Down Menu

This example shows a drop-down menu that submits the form as soon as the user makes a selection. The action of this dropDown component does not move to another page (no action or navigation rule has been configured). When the form is submitted, the selected value is updated. After submitting the form, the value of the DropDown is displayed by the staticText component.

 <webuijsf:dropDown items="#{dataBean.airports}"
submitForm="true"
required="true"
id="airport"
selected="#{dataBean.airport}">
<f:facet name="label">
<webuijsf:label text="Set airport:" for="menuform1:airport"/>
</f:facet>
</webuijsf:dropDown>
<p>
<webuijsf:label text="Current airport: ">
<webuijsf:staticText text="#{dataBean.airport}" id="blah" />
</webuijsf:label>

Example 4: Jump Drop-Down Menu Used For Navigation

This example shows a drop-down menu that allows the user to jump to the page indicated by the selected item. The component is configured with navigateToValue="true", so the action value returned by the component is the value of the selected item. The selected value should be an outcome string that is declared in a navigation rule in the faces-config.xml file.

<webuijsf:dropDown submitForm="true" 
navigateToValue="true"
items="#{DropDownBean.pageOptions}"
id="airport"
label="Choose your page:"/>
The DropDownBean defines the menu items as shown below.
                             
public BackingFileDropDown3() {
pageOptions = new Option[4];
pageOptions[0] = new OptionTitle("Select a Page" );
pageOptions[1] = new Option("indexPage", "Test App Index" );
pageOptions[2] = new Option("hyperlinkPage", "HyperLink Test Page");
pageOptions[3] = new Option("tablePage", "Table Test Page");
}

Example 5: Update Client-Side Drop-Down Menu Properties Using getProps and setProps Functions

This example shows how to toggle the disabled state of a drop-down menu client side using the getProps and setProps functions. When the user selects the Hide Menu option, the drop-down menu is either disabled or enabled.

<webuijsf:radioButton id="rb1" name="rb1" label="Hide Menu" onClick="hideMenu()"/>
<webuijsf:dropDown
id="menu1"
    items="#{dataBean.airports}"
    label="#{msgs.chooseDepartureAirport}"
    selected="#{flightSearch.leaveAirport}"
    tooltip="#{msgs.chooseAirport}"/>

<webuijsf:script>
    function toggleDisabled() {
        var domNode = document.getElementById("form1:
menu1"); // Get menu
        return domNode.setProps({disabled: !domNode.getProps().disabled}); // Toggle disabled state
    }
</webuijsf:script>

Example 6: Asynchronously Update Drop-Down Menu Using Refresh Function

This example shows how to asynchronously update a drop-down menu using the refresh function. When the user selects the Refresh Menu option, the drop-down menu is asynchronously updated with new data.

<webuijsf:radioButton id="rb1" name="rb1" label="Refresh Menu" onClick="refreshMenu()"/>
<webuijsf:dropDown id="menu1"
    items="#{dataBean.airports}"
    label="#{msgs.chooseDepartureAirport}"
    selected="#{flightSearch.leaveAirport}"
    tooltip="#{msgs.chooseAirport}"/>

<webuijsf:script>
    function refreshMenu() {
        var domNode = document.getElementById("form1:menu1"); // Get menu
        return domNode.refresh(); // Asynchronously refresh menu
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,..."). When no parameter is given, the refresh function acts as a reset. That is, the component will be redrawn using values set server-side, but not updated.

Example 7: Asynchronously Update Drop-Down Menu Using Refresh Function

This example shows how to asynchronously update a drop-down menu using the refresh function. The execute property of the refresh function is used to define the client ID which is to be submitted and updated server-side. As the user types in the text field, the input value is updated server-side and the drop-down menu label is updated client-side -- all without a page refresh.

<webuijsf:dropDown id="menu1"
    items="#{dataBean.airports}"
    label="
#{MyBean.label}"
    selected="#{flightSearch.leaveAirport}"
    tooltip="#{msgs.chooseAirport}"/>
<webuijsf:textField id="field1"
    text="#{MyBean.label}"
    label="Change Menu Label"
    onKeyPress="setTimeout('refreshMenu();', 0);"/> // Field used to asynchronously update label.

<webuijsf:script>
    function
refreshMenu() {
        var domNode = document.getElementById("form1:menu1"); // Get menu
        return domNode.refresh("form1:field1"); // Asynchronously refresh while submitting field value
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of IDs can be provided to update components server-side: refresh("form1:id1,form2:id2,...")

editableField

Use the webuijsf:editableField tag to create an input field for a single line of text.

HTML Elements and Layout

The editableField component renders a borderless readonly XHTML <input type="text">element that can be edited inline. An initial ( read-only ) state resembles regular static text, and it can be edited by using the onDblClick event or when the <SPACE> key is pressed. Once the field looses the focus ( as a result of onBlur event), it enters a read-only state again.

If the editable field is modified and if autoSave is set to its default value, which is true, the updated data will be automatically submitted to the server by an Ajax request.

The EditableField component inherits most of the functionality and attributes from TextField. See the webuijsf:textField component description for details and examples.

Configuring the webuijsf:editableField Tag

See the webuijsf:editableField component description for details and examples. With the exception of the autoValidate, all of the usage and attribute examples for textField can be used with editableField by replacing tag into webuijsf:editableField .

Client Side Javascript Functions

When the editableField component is rendered, a DOM object is created. To manipulate the editableField component on the client side, you may invoke functions on this DOM object. For example, ir ordet to disable the component, invoke document.getElementById(id).setProps({disabled: true}).
The following table offers description of additional functions available on the editableField DOM node.
JavaScript Function Description
getInputElement() Accesses the HTML <input> element that is rendered by the component.
getProps() Gets widget properties. Please see setProps() function for a list of supported properties.
refresh(execute)
Asynchronously refreshes 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, no other components are executed.
setProps(props) Changes any of the following supported properties:
  • accesskey
  • autoSave
  • className
  • dir
  • disabled
  • id
  • label
  • lang
  • onClick
  • onDblClick
  • onFocus
  • onKeyDown
  • onKeyPress
  • onKeyUp
  • onMouseDown
  • onMouseMove
  • onMouseOut
  • onMouseOver
  • onMouseUp
  • readOnly
  • required
  • size
  • style
  • tabIndex
  • title
  • valid
  • value
  • visible
submit(execute)
Asynchronously submits 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.
subscribe(topic, obj, func) Use this function to subscribe to an event topic.
  • topic: The event topic to subscribe to.
  • obj: The object in which a function will be invoked, or null for default scope.
  • func The name of a function in context, or a function reference to invoke when topic is published.

Client Side JavaScript Events

When the component is manipulated client side, some functions may publish event topics for custom AJAX implementations to listen for. For example, subscribe to any of these events in order to add custom logic to the editableField behavior. For example:

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

    // Subscribe to refresh event.
    var domNode = document.getElementById("form1:test1");
    domNode.subscribe(domNode.event.refresh.endTopic, processEvents, "update");


</webuijsf:script>

The following events are supported.

Event Description
<Node>.event.refresh.beginTopic Event topic published before asynchronously refreshing the component. 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
<Node>.event.refresh.endTopic

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

  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage
<Node>.event.submit.beginTopic Event topic published before asynchronously submitting the component. 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
<Node>.event.submit.endTopic

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

  • props - JSON object containing messages (if any) raised by the server.In particular, valdiation messages will be present here if validation failed.

Examples

Example 1: Update the Client-Side EditableField Properties Using the GetProps and SetProps Functions

This example shows how to toggle the disabled state of a editable field client side using the getProps and setProps functions. When the user clicks the radio button, the text field is either disabled or enabled.
<webuijsf:radioButton id="rb1" name="rb1" label="Toggle Field Disabled" onClick="toggleDisabled()"/>
<webuijsf:editableField id="field1" text="My Text Field" />

<webuijsf:script>
function toggleDisabled() {
var domNode = document.getElementById("form1:field1"); // Get field
return domNode.setProps({disabled: !domNode.getProps().disabled}); // Toggle disabled state
}
</webuijsf:script>

Example 2: Asynchronously Update the EditableField Using Refresh Function

This example shows how to asynchronously update a editable field using the refresh function. When the user clicks on the radio button, the text field is asynchronously updated with new data.
<webuijsf:radioButton id="rb1" name="rb1" label="Refresh Text Field" onClick="refreshField()"/>
<webuijsf:editableField id="field1" text="#{MyBean.text}" />
<webuijsf:script>
    function refreshField() {
        var domNode = document.getElementById("form1:field1"); // Get field
        return domNode.refresh(); // Asynchronously refresh field
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,..."). When no parameter is given, the refresh function acts as a reset. That is, the component will be redrawn using values set server-side, but not updated.

Example 3: Asynchronously Update EditableField Using Refresh Function

This example shows how to asynchronously update a editable field using the refresh function. The execute property of the refresh function is used to define the client id which is to be submitted and updated server-side. When the user clicks on the radio button, the input value is updated server-side and the text field is updated client-side -- all without a page refresh.
<webuijsf:radioButton id="rb1" name="rb1" label="Refresh Text Field" onClick="refreshField()"/>
<webuijsf:editableField id="field1" text="#{MyBean.text}" /> // Field used to asynchronously update text.
<webuijsf:script>
    function
refreshField() {
        var domNode = document.getElementById("form1:field1"); // Get field
        return domNode.refresh("form1:rb1"); // Asynchronously refresh while submitting radio button value
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,...")

editableList

Use the webuijsf:editableList tag to display a component that allows users to create and modify an array of strings.

HTML Elements and Layout

The editableList component consists of a text input field with an Add button, and a list with a Remove button. To add items to the list, the user types text strings in the input field and clicks Add. To remove items from the list, the user selects items and clicks Remove. An optional Search button can be implemented with a facet to allow the user to search for items to add to the list.

The rendered HTML page uses the <input> and <select> XHTML elements within <table>, <div>, and <span> elements to display the editable list.

Configuring the webuijsf:editableList tag

The content of the list must be maintained in a managed bean, so you must use the list attribute to bind the component to a model. The value of the list attribute must be an EL expression that corresponds to a managed bean or a property of a managed bean, and it must evaluate to an array of java.lang.String.

To set the label of the text field, use the fieldLabel attribute. To set the label of the list box, use the listLabel attribute. To validate new items as they are entered, use the fieldValidatorExpression attribute to specify a validator method. To validate the contents of the list once the user has finished adding and removing items, use the listValidatorExpression attribute to specify a validator method.

By default, the list box is rendered below the input text field. The listOnTop attribute can be set to true to render the list above the input text field. You can also enable users to select more than one item at a time by setting the multiple attribute to true.

Facets

The webuijsf:editableList tag supports the facets in the following table. These facets enable you to customize the layout of the component.

fieldLabel Specifies a custom component for the text field label.
listLabel Specifies a custom component for the label next to the list box.
search
Specifies a custom component for the Search button. The component is rendered on the same row as the text field and the Add button, after the Add button. The button should be used to provide a way for users to identify an appropriate value to be passed back and displayed in the text field.
readOnly
Specifies a custom component for displaying a read-only version of the component
header
Specifies a header to be rendered in a table row above the component.
footer
Specifies a header to be rendered in a table row below the component.

Client-side JavaScript Functions

None.

Examples

Example 1: An editable list that is sorted and input is validated

This example uses a backing bean called ListBean with a property list that represents a list of items. The labels for the input field and list are obtained from a backing bean called msgs. The list items are automatically sorted, and the items and the list are validated with methods from the ListBean.

   <webuijsf:editableList id="compid"
                    list="#{ListBean.list}" 
                    fieldLabel="#{msgs.textfield_label}"
                    listLabel="#{msgs.list_label}"
                    sorted="true" 
                    fieldValidatorExpression="#{ListBean.validateNewItem}"
                    listValidatorExpression="#{ListBean.validateList}"/>
 

Example 2: An editable list with a search button

This example uses the search facet to render a Search button. The button executes a JavaScript function which is defined by the developer. The list allows multiple selections, and is rendered with the list on top.

   <webuijsf:editableList id="list2"
                    list="#{ListBean.list}" 
                    fieldLabel="#{msgs.textfield_label}"
                    listLabel="#{msgs.list_label}"
                    listOnTop="true" 
                    multiple="true"
                    toolTip="List of your items"/>
                    <f:facet name="search">
                       <webuijsf:button primary="true"  text="Search" onClick="addEntity();"/>
                    </f:facet>
             </webuijsf:editableList>
 
fileChooser

Use the webuijsf:fileChooser tag to display a component that shows files and folders in a local file system hierachy, and allows the web application user to select files and folders.

The list of displayed files is determined by the filesystem access rules that are in place in the given environment.

The filechooser model

This tag can also be used to navigate and select resources other than files. One has to implement the com.sun.webui.jsf.model.ResourceModel for that purpose. A default implementation of this interface for File ojects in the local filesystem has been provided. The implementation class is com.sun.webui.jsf.model.FileChooserModel.

The ResourceModel supplies an array of com.sun.webui.jsf.model.ResourecItem objects that are consumed by the filechooser for displaying the list of selectable files. If the component is being used for resources other than files an implementation of this interface should also be supplied. In order to make the component behave as a folderchooser, where only folders can be selected, invoke the setFolderChooser(true) method on the model instance in your backing bean. -->

HTML Elements and Layout

The rendered fileChooser component is an XHTML <table> element that contains several text fields, a drop-down, a listbox, and buttons. The layout is similar to the following:


Browse Server
 
Server Name:  SomeServer  (static text)
Look In: /some/directory  (text field)  
File Filter: *     (text field)  
  To apply a new field value, press Enter in that field  
    Sort By: (dropDown)
List of files/folders  (list box)




    Up One Level
(button)
Open Folder
(button)
Selected File: some_filename   (text field)    

The fileChooser component can be used to render a file chooser or a folder chooser. A file chooser displays files and folders, and allows you to select files and open folders, but not to select folders. A folder chooser also displays files and folders, but the files are displayed as disabled and cannot be selected. A folder chooser allows only folders to be selected. With both types of choosers, you can open folders by selecting a folder and clicking the Open Folder button, or by double-clicking the folder name.

Configuring the webuijsf:fileChooser tag

Use the modelattribute to associate the model with the component. By default the FileChooser model described above will be used.

-->

The fileChooser component displays files in the local filesystem only. The directory whose files and folders should be displayed is specified with a webuijsf:fileChooser tag's lookin attribute. The list of displayed files is determined by the filesystem access rules that are in effect in the given environment.

By default, the component is rendered as a file chooser. To specify a folder chooser, set the webuijsf:fileChooser tag's folderChooser attribute to true. The folder chooser displays the labels Folder Filter and Selected Folders instead of the file chooser's File Filter and Selected Files.

Use the multiple attribute to specify whether multiple resources (files or folders) can be selected. By default the multiple attribute is set to false.

The web app user can sort the list of files and folders shown in the file chooser by selecting a sort option from the "Sort By" dropdown menu. By default, the list is sorted alphabetically. To specify which sort is used when the component is initially rendered, use the sortField attribute. Valid sortField attribute values are:

  • "alphabetic" to sort alphabetically
  • "size" to sort by file size
  • "date" to sort by last modified date

By default, the initial sort order is ascending: A-Z, or smallest file size first, or oldest file first. Set the descending attribute to true to specify a descending sort order.

The input to the fileChooser component is the model object. The output of this component is the list of selected files or folders. This is the value of the component. The backing bean associated with selected attribute will be set with the value of the component after each submit. -->

The input to the fileChooser is the value of the lookin attribute. This attribute sets the initial value of the "Look In" text field which determines the initial contents of the chooser's list.

The output of the fileChooser component is the list of selected files or folders. This is the value of the component. The managed bean associated with the selected attribute is updated with the value when the setChooseButton JavaScript function causes the form to be submitted or the form is submitted in a non "immediate" manner. See the sections "Client-side JavaScript functions" and "Form Submit Behavior" for more details.

The webuijsf:fileChooser tag supports several facets that you can use to replace the default content for some areas of the component. The facets are listed in the Facets section.

Form Submit Behavior

The fileChooser's form submit behavior conforms to the JSF lifecycle, with respect to the fileChooser's value (assigned to the selected attribute), and the values of the fileChooser facets. This means that the fileChooser's value and its facets' values are only updated if the form is submitted with the intent of updating the application's model values.

In other words, the fileChooser elements that submit the form do so in an "immediate" JSF fashion, so that the submitted values of the fileChooser and facets are validated, but the values are not updated. Only the local values are set.

The fileChooser's selected value and the value of the facet components are updated only when the following actions occur on a page that uses the fileChooser component:

  • A list box file entry is double clicked. (The value is updated only when the fileChooser component is in "file chooser" mode, where the folderChooser attribute is false.)
  • The Return key is pressed in the Selected File field.
  • The HTML element specified for the setChooserButton function is clicked or otherwise submits the page.
  • The form is submitted by an HTML element that is on the same page as the file chooser, and the submit is not "immediate".

Facets

The fileChooser component supports the following facets.

Note Specifying facets to replace the default components rendered by the file chooser for facet roles, is an advanced use of this tag. This is especially true for the TextField and Button facets such as lookinField, selectedField, filterField, upButton, and openButton. The component specified for a given facet role must take on the responsibilities expected by the fileChooser. Not satisifying those responsibilities can cause the fileChooser to function incorrectly.

fileChooserLabel

Specify a custom label to replace the File Chooser component label. By default the label is a localized value meaning "Browse Server" in English.
serverLabel Specify a custom component to replace the Server Name label. 
serverNameText Specify a custom component to replace the Server Name static text.
lookinField

Specify a custom component for the Look In text field. The id attribute of the facet component should be set to the webuijsf:fileChooser tag's id attribute with _lookinField appended to the id. For example, if the webuijsf:fileChooser id is fc1, the facet component's id should be fc1_lookinField.

You should use the function enterKeyPressed(this) as the value of the onKeyPress attribute of the facet component. See Client-side JavaScript functions  for details.

lookinLabel Specify a custom label for the Look In field of the component.
filterField

Specify a custom component to replace the File Filter or Folder Filter text field. The id attribute of the facet's component should be set to the webuijsf:fileChooser tag's id attribute, with _filterField appended to the id. For example, if the webuijsf:fileChooser id is fc1, the facet component's id should be fc1_filterField.

You should use the function enterKeyPressed(this) as the value of the onKeyPress attribute of the facet component. See Client-side JavaScript functions for details.

filterLabel Specify a custom label for the File Filter or Folder Filter text field of the component. 
enterPressHelp Specify a custom inline help message to describe the effect of pressing the Enter key after entering data in the "Look In" and "Filter On" fields. By default the following inline help message is displayed:
"To apply a new field value, press Enter in that field."
multiSelectHelp Specify a custom inline help message about choosing multiple files. By default the following inline help message is displayed:
"To select multiple items, use Shift-click or Control-click."
selectedField

Specifies a custom component to replace the Selected Files or Selected Folders field. The id attribute of the facet component should be set to the webuijsf:fileChooser tag's id attribute, with _selectedField appended to the id. For example, if the webuijsf:fileChooser id is fc1, the facet component's id should be fc1_selectedField.

You should use the function enterKeyPressed(this) as the value of the onKeyPress attribute of the facet component. See Client-side JavaScript functions  for details.

selectedLabel

Specify a custom label for the Selected Files or Selected Folders field of the component.

upButton

Specifies a custom component to replace the Up One Level button. When clicked, this button causes the list of files from a level above the currently displayed directory to be displayed. The id attribute of the custom component should be set to the webuijsf:fileChooser tag's id attribute with _upButton appended to the id. For example, if the webuijsf:fileChooser id is fc1, the facet component's id should be fc1_upButton.
If you want to use the JavaScript function associated with the default button's onClick event use the moveUpButtonClicked() function with the custom component's onClick attribute. See Client-side JavaScript functions below for details.

openButton

Specifies a custom component to replace the Open Folder button. When clicked, this button causes the currently selected folder's contents to be displayed. The id attribute of the custom component should be set to the webuijsf:fileChooser tag's id attribute with _openButton appended to the id. For example, if the webuijsf:fileChooser id is fc1, the custom component's id should be fc1_openButton.

If you want to use the JavaScript function associated with the default button's onClick event use the  openFolderClicked() function with the custom component's onClick attribute. See Client-side JavaScript functions below for details.

sortMenu

Specifies a custom component to replace the Sort By drop-down menu of the component.

Client-side JavaScript Functions

When the component is rendered, a DOM object corresponding to the component is created. To manipulate the component on the client side, you may invoke functions on the DOM object. With reference to the DOM id, to obtain a list of selected option elements, invoke document.getElementById(id).getSelectedOptions().

openFolderClicked() Displays the list of files and/or folders in the currently selected folder.
handleOnChange() Handles all activities when the onChange event occurs for the listbox that lists the files and folders.
handleDblClick() Invoked when the user double clicks on a file or folder in the list.
enterKeyPressed(userAction) Invoked when the user changes the value of any of the text fields in the file chooser and hits the Enter key.
setChooseButton() Use this function to assign a DOM element id of the element that submits the form to update the file chooser's selections. The state of this element will be controlled by the state of the file chooser. For example if there are no selections, the element will be disabled.
Note: Any  action in the file chooser that submits the form with the intent of updating the file chooser value, will call the "click" function of this element.
getCurrentDirectory() Convenience function to get the current directory without going to the server.
getOptionElements() Convenience function to get the list of option elements.
getSelectedOptions() Convenience function to get the list of selected option elements.

Examples

Example 1: Simple FileChooser

This example shows a simple fileChooser. The page includes a separate button that is used with the fileChooser's setChooseButton function. <webuijsf:fileChooser id="_fc1" model="#{fileList.model}" selected="#{fileList.fileSelected}" sortField="size" descending="false" multiple="false"> <f:facet name="selectedField"> <webuijsf:textField id="_fc1_selectedField"/> </f:facet> </webuijsf:fileChooser > <webuijsf:fileChooser server="#{fileList.server}" model="#{fileList.model}" selected="#{fileList.files}" sortfield="alphabetic" descending="true" toolTip="#{fileList.tooltip}" /> -->

     <webuijsf:fileChooser id="filechooser"
 		 lookin="#{fileList.lookin}"
                  selected="#{fileList.selected}"
                  sortField="alphabetic"
                  descending="true" />
     <webuijsf:button id="fileChooseButton"
 	 primary="true" 
          text="Choose File"
 	 actionListener="#{fileList.chooseFile}"/>
     </webuijsf:markup>
     <script type="text/javascript">
         document.getElementById(form1:filechooser).setChooseButton('form1:fileChooseButton');
     </script>
 

Backing Bean for fileList Managed Bean

The example uses the following backing bean.

 import java.io.File;
 import javax.faces.event.ActionEvent;
 // Mapped to managed bean "fileList" in faces-config.xml
 // This managed bean is session scoped.
 //
 public class FileList {
     public static final String WINDOWS_OS = "WINDOW";
     private File lookin = null;
     // Creates a new instance of FileList
     public FileList() {
         String osName = System.getProperty("os.name").toUpperCase();
         if (osName.startsWith(WINDOWS_OS)) {
             lookin = new File("c:\\\\windows");
         } else {
             lookin = new File("/usr");
         }
     }
     public File getLookin() {
 	return lookin;
     {
     private File selected;
     public File getSelected() {
         return fileSelected;  }
     public void setSelected(File selected) {
 	this.selected = selected;
     }
     public void chooseFile(ActionEvent event) {
 	// do something useful with the selected files
 	// when the "Choose File" button is clicked.
     }
 }
  
form

Use the webuijsf:form tag to create an HTML <form> element. The form can be submitted via a button or hyperlink control (in which case an ActionEvent will be generated on the server), or via client side scripting.

The virtualFormsConfig attribute can be used to configure virtual forms. A virtual form defines a group of input components ("participants") and submission components ("submitters") on a page, such that when the user interacts with one of the submitters, the participants are processed exclusively while the remaining inputs on the page are ignored. An input component is any component that implements EditableValueHolder. A submission component is any component that causes the web page to be submitted (such as a button, hyperlink, or any input component that submits the page via the webui.suntheme.common.timeoutSubmitForm scripting function). Processing an input means converting and validating it, firing any value change events associated with the input, and mapping the input onto its binding target (if the component is bound). Virtual forms provide an alternative to the immediate property. They are more powerful than immediate because they let you specify multiple groups of inputs to be selectively processed (that is, you can specify multiple virtual forms on a page). They are also easier to use than immediate because they do not alter the JavaServer Faces lifecycle.


HTML Elements and Layout

The rendered HTML page contains an HTML <form> tag and its associated attributes. The rendered form includes a hidden field for use in determining which form submitted the page.


Client Side Javascript Functions

None.

Examples

Example 1: Using a Form

<webuijsf:page>
    <webuijsf:html>
        <webuijsf:head id="head" title="Hyperlink Test Page" />
        <webuijsf:body>
            <webuijsf:form id="form1">
                <webuijsf:hyperlink  id="hyperlinkSubmitsPage" 
                           label="#{HyperlinkBean.label}"
                           action="#{HyperlinkBean.determineWhatToDoFunction}" />
             </webuijsf:form>
       </webuijsf:body>
    </webuijsf:html>
</webuijsf:page>

Example 2: A Page with Three Virtual Forms

<webuijsf:page>
    <webuijsf:html>
        <webuijsf:head id="head" title="Shipping and Billing Information" />
        <webuijsf:body>
            <webuijsf:form id="form1" virtualFormsConfig="shipping | shippingAddressTextField | updateShippingButton , creditCard | creditCardDropDown | creditCardDropDown , billing | billingAddressTextfield creditCardDropDown | updateBillingButton">
                <webuijsf:label for="shippingAddressTextField" id="shippingAddressLabel" style="left: 48px; top: 48px; position: absolute" text="Shipping Address:"/>
                <webuijsf:textField id="shippingAddressTextField" required="true" style="left: 48px; top: 72px; position: absolute"/>                
                <webuijsf:button id="updateShippingButton" style="left: 48px; top: 120px; position: absolute" text="Update Shipping Address"/>
                <webuijsf:label id="creditCardLabel" for="creditCardDropDown" style="left: 48px; top: 192px; position: absolute" text="Credit Card to Use:"/>
                <webuijsf:dropDown id="creditCardDropDown" items="#{SessionBean1.creditCards}" style="left: 48px; top: 216px; position: absolute"/>
                <webuijsf:label id="billingAddressLabel" for="billingAddressTextfield" style="left: 48px; top: 264px; position: absolute" text="Credit Card Billing Address:"/>
                <webuijsf:textField id="billingAddressTextfield" required="true" style="left: 48px; top: 288px; position: absolute"/>
                <webuijsf:button id="updateBillingButton" style="left: 48px; top: 336px; position: absolute" text="Update Billing Address"/>
                <webuijsf:button id="updateAllButton" style="left: 48px; top: 432px; position: absolute" text="Update All Information"/>
             </webuijsf:form>
       </webuijsf:body>
    </webuijsf:html>
</webuijsf:page>

frame

Use the webuijsf:frame tag inside a webuijsf:frameSet tag to denote a new XHTML frame.
HTML Elements and Layout

If you use a webuijsf:frame and webuijsf:frameSet tags you should set the webuijsf:page tag's frame attribute to "true".

This tag renders an xhtml compliant <frame> tag. 

Client Side Javascript Functions

None.

Example

Example 1: Using the webuijsf:frame tag appropriately in a JSP page:

<?xml version="1.0" encoding="UTF-8"?>
<jsp:root version="1.2" xmlns:f="http://java.sun.com/jsf/core" xmlns:h="http://java.sun.com/jsf/html" xmlns:jsp="http://java.sun.com/JSP/Page" xmlns:webuijsf="http://www.sun.com/web/webuijsf">
    <jsp:directive.page contentType="text/html;charset=ISO-8859-1" pageEncoding="UTF-8"/><f:view>
        <webuijsf:page frame="true">
           <webuijsf:html>
               <webuijsf:head title="blah" />
               <webuijsf:frameSet rows="10%,*" cols="10%,*" style="color:blue" styleClass="blue" toolTip="blah">
                <webuijsf:frame toolTip="blah" url="../faces/hyperlink/hyperlink.jsp" frameBorder="true" noResize="false"/>
                <webuijsf:frame toolTip="blah1" url="../faces/hyperlink/nextpage.jsp" frameBorder="true" noResize="false"/>
                
                <webuijsf:frame toolTip="blah2" url="http://www.google.com" frameBorder="true" noResize="false"/>
                <webuijsf:frame toolTip="blah3" url="http://www.yahoo.com" frameBorder="true" noResize="false"/>
                </webuijsf:frameSet>
           </webuijsf:html>
        </webuijsf:page>
    </f:view>
</jsp:root>
frameSet

Use the webuijsf:frameSet tag to define a new set of frames in the rendered HTML page.
When using webuijsf:frameSet and webuijsf:frame tags in your application, you must also set the webuijsf:page tag's frame attribute to "true".

HTML Elements and Layout

The rendered HTML page contains an XHTML-compliant <frameset> element.

Theme Identifiers

None

Client Side Javascript Functions

None. 

Examples

Example 1: Creating a frameset of two rows and two columns

<?xml version="1.0" encoding="UTF-8"?>
<jsp:root version="1.2" xmlns:f="http://java.sun.com/jsf/core" xmlns:h="http://java.sun.com/jsf/html" xmlns:jsp="http://java.sun.com/JSP/Page" xmlns:ui="http://www.sun.com/web/ui">
    <jsp:directive.page contentType="text/html;charset=ISO-8859-1" pageEncoding="UTF-8"/><f:view>
       <webuijsf:page frame="true">
           <webuijsf:html>
               <webuijsf:head title="blah" />
               <webuijsf:frameSet rows="10%,*" cols="10%,*" style="color:blue" styleClass="blue" toolTip="blah">
                <webuijsf:frame toolTip="blah" url="../faces/hyperlink/hyperlink.jsp" frameBorder="true" noResize="false"/>
                <webuijsf:frame toolTip="blah1" url="../faces/hyperlink/nextpage.jsp" frameBorder="true" noResize="false"/>
                
                <webuijsf:frame toolTip="blah2" url="http://www.google.com" frameBorder="true" noResize="false"/>
                <webuijsf:frame toolTip="blah3" url="http://www.yahoo.com" frameBorder="true" noResize="false"/>
                </webuijsf:frameSet>
           </webuijsf:html>
       </webuijsf:page>
    </f:view>
</jsp:root>
head

Use the webuijsf:head tag to provide information about the document, to be used in the <head> element of the rendered HTML page.  The webuijsf:head tag must be placed immediately after the webuijsf:html tag, within the webuijsf:page tag.  The following tags can be used as children of the webuijsf:head tag:

HTML Elements and Layout

The <head> element is rendered in the HTML page, and can include information that is valid for inclusion in the HTML <head> element. For example, if you use the webuijsf:link tag in the webuijsf:head tag, you can provide the URL to a style sheet. The style sheet link  will be rendered as a <link> element in the <head> element of the HTML page.  In addition this tag will output the appropriate stylesheets for the included components on the page.

The browser does not display the information in the <head> element to the user, with the exception of the title that is used in the browser's title bar.  

Facets

The Head component supports the following facet
title

Specify customized title that needs to rendered

Client Side Javascript Functions

None.

Example

Example 1: Create a head tag

<webuijsf:page>
    <webuijsf:html>
       
<webuijsf:head title="Name of the page..title is required">
           <webuijsf:link url="/relativepath/x.css" />
               <webuijsf:script url="/relativepath/x.js" />
       
</webuijsf:head>
       
<webuijsf:body>
           
....your page content....
       
</webuijsf:body>
   
</webuijsf:html></webuijsf:page>  
helpInline

Use the <webuijsf:helpInline> tag to display inline help in the rendered HTML page. The tag supports two types of inline help: page help and field help. Page help is displayed in a medium size font and is intended for information about the page or section as a whole. Field help is displayed in a smaller font and is intended for information about individual fields in the page.

You can make links to additional help that is displayed in a secondary browser window by embedding the webuijsf:helpWindow tag in the webuijsf:helpInline tag's text.

HTML Elements and Layout

The rendered HTML page displays the body content of the <webuijsf:helpInline> tag inside of an XHTML compliant <div> element. An appropriate style class will be set for the <div> element based upon the helpInline type (page or field).

Client Side Javascript Functions

None.

Examples

Example 1: Inline page help

This example shows how to use the webuijsf:helpInline tag to create page level inline help. The type attribute is not specified because the default type is page.

<webuijsf:helpInline id="pageHelp" text="This is page inline help." />

Example 2: Inline field help

This example sets the type attribute to specify field help.

<webuijsf:helpInline id="fieldHelp" type="field" text="This is field inline help." />

Example 3: Add a HelpWindow link in inline help

This example shows how to create a hyperlink within the inline help text of an application page to open the help window. This approach is used to provide more detailed help on a topic.

<webuijsf:helpInline id="pageHelp1" type="page"
    text="Page inline help can be enhanced by a link to
       provide more information using webuijsf:helpWindow tag.">
   
    <webuijsf:helpWindow windowTitle="Window Title Param"
            pageTitle="Page Title Param"
            mastheadImageUrl="/images/webconsole.png"
            mastheadImageDescription="Sun Java Web Console Logo"           
            helpFile="accessibility.html"
            toolTip="Help for This Page (Opens a New Window)"
            linkIcon="true" linkText="Click for more about Accessibility." />
</webuijsf:helpInline>
helpWindow

Use the <webuijsf:helpWindow> tag to display a link to a help window. When a user clicks the link, a popup window opens to display an online JavaHelp 2.0 system. See http://java.sun.com/products/javahelp for more information about JavaHelp 2.0 online help.

HTML Elements and Layout

The helpWindow component renders an XHTML <a> hyperlink element that references the main help window JSP page. The link uses an onclick attribute to execute JavaScript that opens a popup window to display a JavaHelp browser window.

The help window is displayed with a masthead that is similar to the masthead used in application pages. The mastheadImageUrl and mastheadImageDescription attributes can be used to provide content for the masthead. Below the masthead is a banner in which the optional pageTitle attribute value can be displayed to provide a title for the help file. The Close button is displayed in the page title banner.

The help window includes two panes. The left pane is a navigation page with tabs for Contents, Index, and Search. The right frame shows the help content pages. The following is a rough diagram of the help window.

Masthead

Page title banner
Close
JavaHelp Navigation tabs (Contents, Index, Search)
JavaHelp Toolbar icons (back, forward, print)  
Navigation pane
Content Pane

Help content goes here.








Configuring the <webuijsf:helpWindow> tag

The <webuijsf:helpWindow> tag relies on a backing bean and a set of JSP pages that are provided with the Sun Java Web UI Components. You must supply a JavaHelp 2.0 help set to be displayed by the helpWindow component.

You must complete the following configuration steps to use the <webuijsf:helpWindow> tag.

  1. Add a managed bean declaration for the JavaHelpBean backing bean.

  2. The <webuijsf:helpWindow> tag retrieves data from a managed bean called JavaHelpBean. You must add a <managed-bean> declaration for the JavaHelpBean to your web application's faces-config.xml file  so that the helpWindow component can access the bean at run time. Add the XML code shown below to your application's faces-config.xml file:

    <managed-bean>
        <description>The backing bean for the Java Help component</description>
        <managed-bean-name>JavaHelpBean</managed-bean-name>
        <managed-bean-class>com.sun.webui.jsf.bean.HelpBackingBean</managed-bean-class>
        <managed-bean-scope>request</managed-bean-scope>
    </managed-bean>

    Note that this managed bean should have request scope.

  3. Deploy the helpWindow component's Java Server Pages.

  4. The <webuijsf:helpWindow> tag requires several JSP pages that are included with the component SDK in webui/jsp/help. The JSP pages are used to create the help popup window. The helpWindow component expects these JSP pages to be deployed to the absolute directory /com_sun_webui_jsf/help in your web application.

    If a prefix mapping (such as /faces) must be prepended to the default component JSP path of /com_sun_webui_jsf/help, specify the prefix with the <webuijsf:helpWindow> tag's jspPathPrefix attribute. Then add a <managed-property> entry to the <managed-bean> declaration for JavaHelpBean in your faces-config.xml file.

    For example, if the actual mapping for the help JSP at run time is /faces/com_sun_webui_jsf/help, add the managed-property as shown below:


    <managed-bean>
        <description>The backing bean for the Java Help component</description>
        <managed-bean-name>JavaHelpBean</managed-bean-name>
        <managed-bean-class>com.sun.webui.jsf.bean.HelpBackingBean</managed-bean-class>
        <managed-bean-scope>request</managed-bean-scope>
        <managed-property>
            <property-name>jspPath</property-name>
            <value>/faces</value>
        </managed-property>
    </managed-bean>

    Note: If you deploy the helpWindow component's JSPs to a directory that is not covered by the FacesServlet mapping for your application, you must include an additional FacesServlet mapping to the help JSP directory in your application's web.xml file.

  5. Deploy the JavaHelp-compliant help set.

  6. You must provide a JavaHelp-compliant help set that can be used to populate the display of the <webuijsf:helpWindow> tag's online help system. The help set is expected to be located in the relative directory /html/currentLocale/help where currentLocale represents the abbreviation for a supported run time locale (such as en for English locale users).

    If a prefix mapping is required, you should specify the prefix with the  <managed-property> entry for the helpSetPathproperty to the <managed-bean> declaration for JavaHelpBean in your faces-config.xml file.

    For example, if your help files are located in the absolute directory of /yourApp/helpfiles/html/en/help, add the <managed-property> element in the faces-config.xml file as shown in the following example.

    <managed-bean>
        <description>The backing bean for the JavaHelp component</description>
        <managed-bean-name>JavaHelpBean</managed-bean-name>
        <managed-bean-class>com.sun.webui.jsf.bean.HelpBackingBean</managed-bean-class>
        <managed-bean-scope>request</managed-bean-scope>
        <managed-property>
            <property-name>helpSetPath</property-name>
            <value>/helpfiles</value>
        </managed-property>
    </managed-bean>

Facets

None.

Theme Identifiers

The helpWindow component uses the following theme image identifiers for the buttons and icons in the help window.

 HELP_BACK
 HELP_BACK_HEIGHT
 HELP_BACK_WIDTH
 HELP_BACK_DISABLED
 HELP_BACK_DISABLED_HEIGHT
 HELP_BACK_DISABLED_WIDTH
 HELP_FORWARD
 HELP_FORWARD_HEIGHT
 HELP_FORWARD_WIDTH
 HELP_FORWARD_DISABLED
 HELP_FORWARD_DISABLED_HEIGHT
 HELP_FORWARD_DISABLED_WIDTH
 HELP_PRINT
 HELP_PRINT_HEIGHT
 HELP_PRINT_WIDTH
 HELP_PRINT_DISABLED
 HELP_PRINT_DISABLED_HEIGHT
 HELP_PRINT_DISABLED_WIDTH
 HELP_BTNNAV_GRADIENT
 HELP_BTNNAV_GRADIENT_HEIGHT
 

Client Side Javascript Functions

None.

Examples

Example 1: Add a HelpWindow link to the masthead

This example shows how to use the webuijsf:helpWindow tag in the webuijsf:masthead tag's helplink facet. These tags add the Help hyperlink to the top right side of the masthead of the application page.

<webuijsf:masthead id="Masthead" productImageURL="../images/productimage.jpg"
        productImageDescription="Java Web Console">
    <f:facet name="helpLink">
        <webuijsf:helpWindow windowTitle="Help Window" pageTitle="Help"
                jspPathPrefix="/faces"
                mastheadImageUrl="/images/webconsole.png"
                helpFile="sunwebconsole.html"                 
                mastheadImageDescription="Sun Java Web Console Logo"
                toolTip="Help for This Page (Opens a New Window)"/>
    </f:facet>               
</webuijsf:masthead>

Example 2: Add a HelpWindow link as part of inline help

This example shows how to create a hyperlink within the inline help text of an application page to open the help window. This approach is used to provide more detailed help on a topic.

<webuijsf:helpInline id="pageHelp1" type="page"
    text="Page inline help can be enhanced by a link to
       provide more information using webuijsf:helpWindow tag.">
   
    <webuijsf:helpWindow windowTitle="Window Title Param"
            pageTitle="Page Title Param"
            mastheadImageUrl="/images/webconsole.png"
            mastheadImageDescription="Sun Java Web Console Logo"           
            helpFile="accessibility.html"
            toolTip="Help for This Page (Opens a New Window)"
            linkIcon="true" linkText="Click for more about Accessibility." />
</webuijsf:helpInline>
hiddenField

Use the webuijsf:hiddenField tag to create a hidden field, which is present in the HTML, but not displayed to the user. Hidden fields are useful for saving state information.

HTML Elements and Layout

The hiddenField component renders an XHTML <input type="hidden"> element.

Configuring the webuijsf:hiddenField Tag

Use the value attribute to associate the component with a model object that represents the current value, by setting the attribute's value to a JavaServer Faces EL expression that corresponds to a property of a backing bean.

Facets

This component has no facets.

Theme Identifiers

This component does not use any style classes from the theme.

Client Side Javascript Functions

When the component is rendered, a DOM object corresponding to the component is created. To manipulate the component on the client side, you may invoke functions on the DOM object. With reference to the DOM id, to disable the component, invoke document.getElementById(id).setProps({disabled: true}).

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. If omitted, no other components are executed.
setProps(props) Use this function to change any of the following supported properties:
  • disabled
  • id
  • name
  • value
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.
subscribe(topic, obj, func) Use this function to subscribe to an event topic.
  • topic: The event topic to subscribe to.
  • obj: The object in which a function will be invoked, or null for default scope.
  • func The name of a function in context, or a function reference to invoke when topic is published.

Client Side JavaScript Events

When the component is manipulated client side, some functions may publish event topics for custom AJAX implementations to listen for. For example, you can listen for the refresh event topic using:

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

    // Subscribe to refresh event.
    var domNode = document.getElementById("form1:test1");
    domNode.subscribe(domNode.event.refresh.endTopic, processEvents, "update");


</webuijsf:script>

The following events are supported.

<Node>.event.refresh.beginTopic Event topic published before asynchronously refreshing the component. 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
<Node>.event.refresh.endTopic Event topic published after asynchronously refreshing the component. Supported properties include: See setProps() function.
  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage
<Node>.event.submit.beginTopic Event topic published before asynchronously submitting the component. 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
<Node>.event.submit.endTopic

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

  • props - JSON object containing messages (if any) raised by the server.In particular, valdiation messages will be present here if validation failed

Examples

Example 1:

This example uses a backing bean FieldTest with a property counter. The property is an int but it is not necessary to specify a converter since the default JavaServer Faces converter will be used. The value of the hidden field may be updated through a JavaScript. The tag generates an HTML input element.

 <webuijsf:hiddenField id="counter" value="#{FieldTest.counter}"/>

Example 2: Update client-side hiddenField properties using the getProps and setProps functions

This example shows how to toggle the disabled state of a hidden field client side using the getProps and setProps functions. When the user clicks the radio button, the hidden field is either disabled or enabled.
<webuijsf:radioButton id="rb1" name="rb1" label="Toggle Field Disabled" onClick="toggleDisabled()"/>
<webuijsf:textField id="field1" value="#{MyBean.value}" />

<webuijsf:script>
function toggleDisabled() {
var domNode = document.getElementById("form1:field1"); // Get field
return domNode.setProps({disabled: !domNode.getProps().disabled}); // Toggle disabled state
}
</webuijsf:script>

Example 3: Asynchronously update hiddenField using refresh function

This example shows how to asynchronously update a text field using the refresh function. When the user clicks on the radio button, the text field is asynchronously updated with new data.
<webuijsf:radioButton id="rb1" name="rb1" label="Refresh Text Field" onClick="refreshField()"/>
<webuijsf:hiddenField id="field1" value="#{MyBean.value}" />
<webuijsf:script>
    function refreshField() {
        var domNode = document.getElementById("form1:field1"); // Get field
        return domNode.refresh(); // Asynchronously refresh field
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,..."). When no parameter is given, the refresh function acts as a reset. That is, the component will be redrawn using values set server-side, but not updated.

Example 4: Asynchronously update hiddenField using refresh function

This example shows how to asynchronously update a text field using the refresh function. The execute property of the refresh function is used to define the client id which is to be submitted and updated server-side. When the user clicks on the radio button, the input value is updated server-side and the text field is updated client-side -- all without a page refresh.
<webuijsf:radioButton id="rb1" name="rb1" label="Refresh Text Field" onClick="refreshField()"/>
<webuijsf:hiddenField id="field1" value="#{MyBean.value}" /> // Field used to asynchronously update value.
<webuijsf:script>
    function
refreshField() {
        var domNode = document.getElementById("form1:field1"); // Get field
        return domNode.refresh("form1:rb1"); // Asynchronously refresh while submitting radio button value
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,...")

html

Use the webuijsf:html tag to create an <html> element in the rendered HTML page. The webuijsf:html tag must be used as a child of the webuijsf:page tag, following immediately after the webuijsf:page tag.  This tag is required for pages that are not in a portal enviroment and not subviews.

HTML Elements and Layout

The rendered HTML page includes an <html> tag that uses attributes indicated by the attributes you specify with the webuijsf:html tag in the JSP page.

Theme Identifiers

None.

Client Side Javascript Functions

None.

Examples

Example 1: Using a webuijsf:html tag

<webuijsf:page>
    <webuijsf:html>
       <webuijsf:head id="blah" title="hyperlink test page" />
       <webuijsf:body>
          <webuijsf:form id="form1">
               <webuijsf:hyperlink  id="hyperlinkSubmitsPage" 
                           label="#{HyperlinkBean.label}"
                           action="#{HyperlinkBean.determineWhatToDoFunction}" />
           </webuijsf:form>
      </webuijsf:body>
    </webuijsf:html>
</webuijsf:page>



hyperlink

Use the webuijsf:hyperlink tag to display a HTML hyperlink to a URL, or a link that submits a form.

  • If the url attribute is specified, an anchor widget is created on the client side. Clicking on this anchor will take the user to the url specified.
  • If the actionExpression attribute is specified and the url attribute is not specified, an hyperlink widget will be created on the client side which will submit the form when it is clicked.
  • If both the url and actionExpression attributes are specified, the url attribute takes preference.
  • If none of the attributes are specified, an hyperlink widget will be created on the client side and the form will be submitted when the hyperlink is clicked.

If you intend to use the hyperlink for navigating to a different page by using the url attribute, consider using the webuijsf:anchor component instead of the hyperlink component.

If UIParameter components are specified as children to the hyperlink component and an url attribute exists, then the behavior of the url here is similar to the one observed with the anchor component. The name, value pairs of the UIParameter components are added as request parameters to the url attribute. If no url is specified for the hyperlink, then this will be passed on to the hyperlink widget as a JSON array where these name/value pairs will be appended as request parameters when the hyperlink is clicked and the form is submitted.

If the disabled attribute of the hyperlink is set to true, clicking the hyperlink on the browser will not generate a request and hence the form will not be submitted or the page will not navigate to the specified url depending on whether the url has been specified or not.

HTML Elements and Layout

The rendered HTML page displays an XHTML <a> element. If the link submits the form the onclick will have some additional behavior that the user should be aware of. See the onClick attribute below.

Client Side Javascript Functions

When the component is rendered, a DOM object corresponding to the component is created. To manipulate the component on the client side, you may invoke functions on the DOM object. With reference to the DOM id, to disable the component, invoke document.getElementById(id).setProps({disabled: true}).

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. If omitted, no other components are executed.
setProps(props) Use this function to change any of the following supported properties:
  • id
  • className
  • dir
  • disabled
  • href
  • hrefLang
  • lang
  • onFocus
  • onBlur
  • onClick
  • onDblClick
  • onKeyDown
  • onKeyPress
  • onKeyUp
  • onMouseDown
  • onMouseOut
  • onMouseOver
  • onMouseUp
  • onMouseMove
  • style
  • tabIndex
  • title
  • visible
subscribe(topic, obj, func) Use this function to subscribe to an event topic.
  • topic: The event topic to subscribe to.
  • obj: The object in which a function will be invoked, or null for default scope.
  • func The name of a function in context, or a function reference to invoke when topic is published.

Client Side JavaScript Events

When the component is manipulated client side, some functions may publish event topics for custom AJAX implementations to listen for. For example, you can listen for the refresh event topic using:

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

    // Subscribe to refresh event.
    var domNode = document.getElementById("form1:test1");
    domNode.subscribe(domNode.event.refresh.endTopic, processEvents, "update");


</webuijsf:script>

The following events are supported.

<Node>.event.refresh.beginTopic Event topic published before asynchronously refreshing the component. 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
<Node>.event.refresh.endTopic Event topic published after asynchronously refreshing the component. Supported properties include: See setProps() function.
  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage

Examples

Example 1: Create a hyperlink that submits the form

<webuijsf:hyperlink id="hyperlinktest1" text="#{HyperlinkBean.text}" actionExpression="#{HyperlinkBean.success}" />

Note: id can be used as a unique identifier if the hyperlink is programatically addressed.

Example 2: Create a hyperlink that goes to another page

This example sets the url attribute, which signifies that this link will not submit to the server and will be a straight hyperlink.

<webuijsf:hyperlink id="hyperlinktest2" text="#{HyperlinkBean.text}" url="http://www.google.com" />

Example 3: Using the body of a hyperlink to render text

This example shows how to use other components as children of the hyperlink tag.

<webuijsf:hyperlink id="hyperlinktest3" url="http://www.sun.com">
   <webuijsf:image url="myyahoo.gif" />
   <webuijsf:staticText text="more text" />
</webuijsf:hyperlink>

Example 4: Using f:params to add additional request parameters when the hyperlink action is invoked

When this link is clicked, the page will be submitted and the request parameter map will have two additional items in it: testingParam1 and testingParam2, with their associated values.

<webuijsf:hyperlink  id="hyperlinktest1"  text="#{HyperlinkBean.label}" actionExpression="#{HyperlinkBean.success}" >
    <f:param name="testingParam1" value="success!"/>
    <f:param name="testingParam2" value="failure!"/>
</webuijsf:hyperlink>

Example 5: Update client-side hyperlink using the setProps and getProps functions

This example shows how to toggle the visible state of a hyperlink client side using the getProps and setProps functions. When the user clicks the button, the hyperlink is either shown or hidden

<webuijsf:hyperlink id="form1:hyperlink1" text="#{HyperlinkBean.text}" actionExpression="#{hyperlinkBean.action}" /> Click here </webuijsf:hyperlink>
<webuijsf:button id="button1" text="Hide hyperlink" onClick="toggleVisible()"/>

< script type="text/javascript">
    function toggleVisible() {
        var domNode = document.getElementById("form1:hyperlink1");
        var props = domNode.getProps();
        if (domNode != null) {
            domNode.setProps({"visible":!props.visible});
        }
    }
</script>

Example 6: Asynchronously update hyperlink using refresh function

This example shows how to asynchronously update a hyperlink using the refresh function. When the user clicks on the button, the hyperlink is asynchronously updated with new data.
<webuijsf:hyperlink id="hyperlink1" text="#{MyBean.text}"/>
<webuijsf:button id="button1" text="#{MyBean.text}" onClick="refreshHyperlink();return false;"/>
<webuijsf:script>
    function refreshHyperlink() {
        var domNode = document.getElementById("form1:hyperlink1"); // Get hyperlink
        return domNode.refresh(); // Asynchronously refresh hyperlink
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,..."). When no parameter is given, the refresh function acts as a reset. That is, the component will be redrawn using values set server-side, but not updated.

Example 7: Asynchronously update hyperlink using refresh function

This example shows how to asynchronously update a hyperlink using the refresh function. The execute property of the refresh function is used to define the client id which is to be submitted and updated server-side. As the user types in the text field, the input value is updated server-side and the hyperlink is updated client-side -- all without a page refresh.
<webuijsf:hyperlink id="hyperlink1" text="#{MyBean.text}"/>
<webuijsf:textField id="field1" text="#{MyBean.text}" label="Change hyperlink Text"
onKeyPress="setTimeout('refreshHyperlink();', 0);"/> // Field used to asynchronously update text.
<webuijsf:script>
    function refreshHyperlink() {
        var domNode = document.getElementById("form1:hyperlink1"); // Get hyperlink
        return domNode.refresh("form1:field1"); // Asynchronously refresh while submitting field value
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,...")

iframe

Use the webuijsf:iframe tag  to create an inline frame in the rendered HTML page. The webuijsf:iframe tag inserts a frame in which another web page can be displayed inside the web application page.

HTML Elements and Layout

The iframe component is rendered as an <iframe> XHTML element.  The webuijsf:iframe tag can be configured by using the tag's attributes, which map to the <iframe> properties and are similarly named.

Theme Identifiers

None.

Client Side Javascript Functions

None.

Example

Example 1: Using the webuijsf:iframe tag appropriately in a JSP page:

<?xml version="1.0" encoding="UTF-8"?>
<jsp:root version="1.2" xmlns:f="http://java.sun.com/jsf/core" xmlns:h="http://java.sun.com/jsf/html" xmlns:jsp="http://java.sun.com/JSP/Page" xmlns:webuijsf="http://www.sun.com/web/webuijsf">
    <jsp:directive.page contentType="text/html;charset=ISO-8859-1" pageEncoding="UTF-8"/><f:view>
       <webuijsf:page frame="true">
           <webuijsf:html>
               <webuijsf:head title="blah" />
               <webuijsf:body>
                 <webuijsf:staticText id="text1" text="Below is a frame within this page without a frameset" />
                 <webuijsf:markup tag="br" singleton="true" />
                 <webuijsf:iframe url="http://google.com" />
              </webuijsf:body>
           </webuijsf:html>
       </webuijsf:page>
    </f:view>
</jsp:root>
image

Use the webuijsf:image tag to display an inline image in the rendered HTML page. The url attribute is used to specify the URL to the image file that is to be displayed.

The webuijsf:image tag can be used to display a theme-specific image in the rendered HTML page. The icon attribute used in the webuijsf:imagetag is a key value that is mapped to a URL in theme properties file. The key is used to look up the appropriate image source and related attributes from the current theme. By specifying a key, you avoid the need to specify predefined constants such as height and width. The image can also be seamlessly changed when a different theme is selected.

Note:
- Currently the list of icons that you can use is not publicly supported, but the icon names are specified in the/com/sun/webui/jsf/suntheme/SunTheme.properties file. The names are listed as resource keys of the format image.ICON_NAME. Use only the part of the key that follows image. For example, if the key isimage.ALARM_CRITICAL_SMALL, you should specifyALARM_CRITICAL_SMALL as the value of the icon attribute of thewebuijsf:icon tag. A list of supported icon values will be published in the near future.

- If you use an image that is a PNG type, this component will output the correct format for an <img> tag to display a PNG correctly in Internet Explorer. In order to use this feature you must set the height and width properties of the image. If you do not specify a height or width property, a generic default value will be used for each unspecified property. The default height and width may produce an unsatisfactory image in IE.

HTML Elements and Layout

The rendered HTML page displays an XHTML compliant <img> element with any applicable element attributes. The attributes can be specified through the <webuijsf:image> tag attributes.

Client Side Javascript Functions

When the component is rendered, a DOM object corresponding to the component is created. To manipulate the component on the client side, you may invoke functions on the DOM object. With reference to the DOM id, to disable the component, invoke document.getElementById(id).setProps({title: "My Image"}).

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. If omitted, no other components are executed.
setProps(props) Use this function to change any of the following supported properties:
  • alt
  • align
  • border
  • className
  • dir
  • height
  • hspace
  • id
  • lang
  • longDesc
  • onClick
  • onDblClick
  • onKeyDown
  • onKeyPress
  • onKeyUp
  • onMouseDown
  • onMouseMove
  • onMouseOut
  • onMouseOver
  • onMouseUp
  • src
  • style
  • tabIndex
  • title
  • visible
  • vspace
  • width
subscribe(topic, obj, func) Use this function to subscribe to an event topic.
  • topic: The event topic to subscribe to.
  • obj: The object in which a function will be invoked, or null for default scope.
  • func The name of a function in context, or a function reference to invoke when topic is published.

Client Side JavaScript Events

When the component is manipulated client side, some functions may publish event topics for custom AJAX implementations to listen for. For example, you can listen for the refresh event topic using:

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

    // Subscribe to refresh event.
    var domNode = document.getElementById("form1:test1");
    domNode.subscribe(domNode.event.refresh.endTopic, processEvents, "update");


</webuijsf:script>

The following events are supported.

<Node>.event.refresh.beginTopic Event topic published before asynchronously refreshing the component. 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
<Node>.event.refresh.endTopic Event topic published after asynchronously refreshing the component. Supported properties include: See setProps() function.
  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage

Examples

Example 1: Create an image

<webuijsf:image id="image1" url="../images/dot.gif" />

This will generate the following markup:
  
<img src="../images/dot.gif" alt="" />

Example 2: Create a theme specific image

<webuijsf:image id="image2" icon="ALARM_CRITICAL_SMALL" />

Example 3: Update client-side image properties using the getProps and setProps functions

This example shows how to toggle the visible state of an image client side using the getProps and setProps functions. When the user clicks the radio button, the image is either shown or hidden.
<webuijsf:radioButton id="rb1" name="rb1" label="Toggle Image Visible" onClick="toggleVisible()"/>
<webuijsf:image id="image1" url="../images/dot.gif" />

<webuijsf:script>
function toggleVisible() {
var domNode = document.getElementById("form1:image1"); // Get image
return domNode.setProps({visible: !domNode.getProps().visible}); // Toggle visible state
}
</webuijsf:script>

Example 4: Asynchronously update image using refresh function

This example shows how to asynchronously update an image using the refresh function. When the user clicks on the radio button, the image is asynchronously updated with new data.
<webuijsf:radioButton id="rb1" name="rb1" label="Refresh Image" onClick="refreshImage()"/>
<webuijsf:image id="image1" url="#{MyBean.imageSrc}" />
<webuijsf:script>
    function refreshImage() {
        var domNode = document.getElementById("form1:image1"); // Get image
        return domNode.refresh(); // Asynchronously refresh image
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,..."). When no parameter is given, the refresh function acts as a reset. That is, the component will be redrawn using values set server-side, but not updated.

Example 5: Asynchronously update image using refresh function

This example shows how to asynchronously update an image using the refresh function. The execute property of the refresh function is used to define the client id which is to be submitted and updated server-side. As the user tabs out of the text field, the input value is updated server-side and the image is updated client-side -- all without a page refresh.
<webuijsf:image id="image1" url="#{MyBean.imageSrc}" />
<webuijsf:textField id="field1" text="#{MyBean.imageSrc}" label="Change Image Source"
onBlur="refreshImage()"/> // Field used to asynchronously update image.
<webuijsf:script>
    function
refreshImage() {
        var domNode = document.getElementById("form1:image1"); // Get image
        return domNode.refresh("form1:field1"); // Asynchronously refresh while submitting field value
    }
</webuijsf:script>


Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,...")

imageHyperlink

Use the webuijsf:imageHyperlink tag to display a clickable image in the rendered HTML page. The image is surrounded by an HTML hyperlink, allowing the image to function as a hyperlink.  This tag is based on a webuijsf:hyperlink tag and functions the same way.  The main difference is this tag will format an image with a surrounding hyperlink.  See the webuijsf:hyperlink tag for more examples on using a hyperlink.

The webuijsf:imageHyperlink component can be also be used to submit forms. If the actionExpression attribute is used, the form is submitted. If the url attribute is used, the link is a normal hyperlink that sends the browser to a new location.

The webuijsf:imageHyperlink can display a clickable icon image from the current theme in the rendered HTML page using the "icon" attribute. Take a look at the webuijsf:image tag to see how the icon attribute is to be used. The image that is specified as a part of the imageUrl or the icon attribute is shown for the enabled state of the imageHyperlink. If a disabledImage facet is specified, then that image will be shown when the imageHyperlink changes to the disabled state. If not, the image specified for the enabled state will be shown.

HTML Elements and Layout

The rendered HTML page contains an XHTML <a> element with an <img> element inside. Image attributes that are specified with the webuijsf:imageHyperlink tag are used as attributes in the <img>  element.

Facets

The imageHyperlink supports the following facets

disabledImage

Specify the image to be shown when the imageHyperlink is disabled.

Theme Identifiers

None

Client Side Javascript Functions

When the component is rendered, a DOM object corresponding to the component is created. To manipulate the component on the client side, you may invoke functions on the DOM object. With reference to the DOM id, to disable the component, invoke document.getElementById(id).setProps({disabled: true}).

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. If omitted, no other components are executed.
setProps(props) Use this function to change any of the following supported properties:
  • id
  • className
  • dir
  • disabled
  • disabledImage
  • enabledImage
  • href
  • hrefLang
  • imagePosition
  • lang
  • onFocus
  • onBlur
  • onClick
  • onDblClick
  • onKeyDown
  • onKeyPress
  • onKeyUp
  • onMouseDown
  • onMouseOut
  • onMouseOver
  • onMouseUp
  • onMouseMove
  • style
  • tabIndex
  • visible
subscribe(topic, obj, func) Use this function to subscribe to an event topic.
  • topic: The event topic to subscribe to.
  • obj: The object in which a function will be invoked, or null for default scope.
  • func The name of a function in context, or a function reference to invoke when topic is published.

Client Side JavaScript Events

When the component is manipulated client side, some functions may publish event topics for custom AJAX implementations to listen for. For example, you can listen for the refresh event topic using:

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

    // Subscribe to refresh event.
    var domNode = document.getElementById("form1:test1");
    domNode.subscribe(domNode.event.refresh.endTopic, processEvents, "update");


</webuijsf:script>

The following events are supported.

<Node>.event.refresh.beginTopic Event topic published before asynchronously refreshing the component. 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
<Node>.event.refresh.endTopic Event topic published after asynchronously refreshing the component. Supported properties include: See setProps() function.
  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage

Examples

Example 1: Create an imageHyperlink with yahoo gif

<webuijsf:imageHyperlink id="imagehyperlinktest1" imageURL="../myyahoo.gif" action="#{HyperlinkBean.getRequiredHelp}" />

Example 2: Create an IconHyperlink using the required indicator icon

<webuijsf:iconHyperlink id="iconhyperlinktest1"
              icon="LABEL_REQUIRED_ICON"
              action="#{HyperlinkBean.getRequiredHelp}" />

Example 3: Using disabledImage facet.

<webuijsf:imageHyperlink id="iconhyperlink" url="/faces/calendar/index.jsp"   alt="Go to Calendar tests" icon="ALARM_MAJOR_MEDIUM" text="Calendar Test">
<f:facet name="disabledImage">
    <webuijsf:image id="disabledImage" icon="ALARM_MASTHEAD_MAJOR_DIMMED"/> </f:facet> </webuijsf:imageHyperlink>

Example 4: Update client-side image hyperlink using the setProps and getProps functions

This example shows how to toggle the visible state of an image hyperlink client side using the getProps and setProps functions. When the user clicks the button, the image hyperlink is either shown or hidden

<webuijsf:imageHyperlink id="form1:hyperlink1" icon="ALARM_MAJOR_MEDIUM" text="#{HyperlinkBean.text}"
          actionExpression="#{hyperlinkBean.action}" /> Click here </webuijsf:imageHyperlink>

<webuijsf:button id="button1" text="Hide hyperlink" onClick="toggleVisible()"/>

< script type="text/javascript">
    function toggleVisible() {
        var domNode = document.getElementById("form1:hyperlink1");
        var props = domNode.getProps();
        if (domNode != null) {
            domNode.setProps({"visible":!props.visible});
        }
    }
</script>

Example 5: Asynchronously update image hyperlink using refresh function

This example shows how to asynchronously update an image hyperlink using the refresh function. When the user clicks on the button, the image hyperlink is asynchronously updated with new data.
<webuijsf:imageHyperlink id="hyperlink1" icon="ALARM_MAJOR_MEDIUM" text="#{MyBean.text}"/>
<webuijsf:button id="button1" text="#{MyBean.text}" onClick="refreshHyperlink();return false;"/>
<webuijsf:script>
    function refreshHyperlink() {
        var domNode = document.getElementById("form1:hyperlink1"); // Get hyperlink
        return domNode.refresh(); // Asynchronously refresh hyperlink
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,..."). When no parameter is given, the refresh function acts as a reset. That is, the component will be redrawn using values set server-side, but not updated.

Example 6: Asynchronously update hyperlink using refresh function

This example shows how to asynchronously update an image hyperlink using the refresh function. The execute property of the refresh function is used to define the client id which is to be submitted and updated server-side. As the user types in the text field, the input value is updated server-side and the hyperlink is updated client-side -- all without a page refresh.
<webuijsf:imageHyperlink id="hyperlink1" icon="ALARM_MAJOR_MEDIUM" text="#{MyBean.text}"/>
<webuijsf:textField id="field1" text="#{MyBean.text}" label="Change hyperlink Text"
onKeyPress="setTimeout('refreshHyperlink();', 0);"/> // Field used to asynchronously update text.
<webuijsf:script>
    function refreshHyperlink() {
        var domNode = document.getElementById("form1:hyperlink1"); // Get hyperlink
        return domNode.refresh("form1:field1"); // Asynchronously refresh while submitting field value
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,...")

jobStatus

Use the webuijsf:jobStatus tag to display the number of jobs currently running or a link to detailed information about the number of jobs currently running. This tag is typically specified as part of the webuijsf:masthead tag's statusArea facet.

The webuijsf:jobStatus tag produces job information identical to the webuijsf:masthead tag's jobCount attribute.

See the webuijsf:masthead documentation for more information about the statusArea facet.

The statusArea facet overrides the masthead's status area attributes. The webuijsf:jobStatus tag enables you to include the job count in the status area, along with your custom components. The webuijsf:notificationPhrase, webuijsf:timeStamp, and webuijsf:alarmStatus tags enable you to include the other standard status area components as well.

Note that when you use the webuijsf:masthead attributes, spacing between the components is handled automatically. When you use the webuijsf:alarmStatus, webuijsf:jobStatus, webuijsf:timeStamp, and webuijsf:notificationPhrase tags in the statusArea facet, you may have to add code to handle the spacing between the components, as demonstrated in the example below.

Note: The jobStatus component has been deprecated. Take a look at the examples section to see how to create an equivalent of the webuijsf:jobStatus

HTML Elements and Layout

The rendered HTML page includes an <img> element for the status icon, adjacent to an <a> hyperlink containing the job status text label, and number of jobs running.

Configuring the webuijsf:jobStatus tag

The default text label is "Jobs running: ", but you can specify your own text label with the text attribute. Specify the number of jobs with the numJobs attribute. Use other attibutes, such as url, action, or actionListener to provide detailed information about the number of jobs currently running.

The immediate attribute should be set to true when this component is used in the masthead.

Theme Identifiers

The theme provides the following icon identifier, which is used for the job status image.

MASTHEAD_STATUS_ICON

Client Side Javascript Functions

None.

Examples

Example 1: Display job status information as part of the masthead statusArea facet

This example uses webuijsf:panelGroup to enclose the tags for the status items. The components are also enclosed in f:verbatim tags that specify <div> elements with a class selector that applies the correct spacing around the component in the masthead.

<webuijsf:masthead id="Masthead" productImageURL="../images/webconsole.png"
         productImageDescription="Java Web Console" userInfo="user_name" 
         serverInfo="server_name">
     <f:facet name="statusArea">
       <webuijsf:panelGroup id="statusPanel" separator="">
         <webuijsf:markup tag="div" styleClass="#{themeStyles.MASTHEAD_STATUS_DIV}">
         <webuijsf:notificationPhrase text="Important info goes here" />
         <webuijsf:image icon="DOT" border="0" width="20" height="1" />
         <webuijsf:jobStatus immediate="true" numJobs="1" />
         </webuijsf:markup>
         <webuijsf:markup tag="div" styleClass="#{themeStyles.MASTHEAD_TIME_DIV}">
         <webuijsf:timeStamp />
         </webuijsf:markup>
         <webuijsf:markup tag="div" styleClass="#{themeStyles.MASTHEAD_ALARM_DIV}">
         <webuijsf:alarmStatus immediate="true" numDownAlarms="0" numCriticalAlarms="1" numMajorAlarms="2" numMinorAlarms="3" />
         </webuijsf:markup>
       </webuijsf:panelGroup>
     </f:facet>
 </webuijsf:masthead>
 

Example 2:Create an equivalent of webuijsf:jobStatus


    <f:facet name="jobsInfo">
    <webuijsf:panelGroup id="jobStatusInfo">                              
         <webuijsf:image id="jobStatusimage" icon="MASTHEAD_STATUS_ICON" height="17" width="17"/>
         <f:verbatim>;&nbsp </f:verbatim>
         <webuijsf:hyperlink id="link2" url="#"  styleClass="#{themeStyles.MASTHEAD_PROGRESS_LINK}" >
         <webuijsf:staticText id="text2" styleClass="#{themeStyles.MASTHEAD_TEXT}"
         text="#{MastheadBean.jobStatus}"/>
         </webuijsf:hyperlink>
     </webuijsf:panelGroup>           
    </f:facet>
label

Use the webuijsf:label tag to display a label for a component. To specify which component the label belongs to you may either:

  • Place the labelled component in the body of webuijsf:label; or
  • Set the value of the for attribute of webuijsf:label to the id of the labelled component.

If the tags are adjacent on the page, the first option should be preferred as it is simpler to configure the tag this way.

Note that many components in this library have labellabelLevel attributes (and sometimeslabelOnTop) which can be used instead of webuijsf:label. The main reason to use webuijsf:label is if you need to specify the appearance of the label beyond what these attributes permit.

HTML Elements and Layout

The webuijsf:label tag results in a HTML label or span element. A span element is rendered if no labelled component could be found.

If the tag has a body, the body must consists of tags corresponding to JSF components only. The corresponding JSF components become children of the Label component. All the child components are rendered after the label element.

If the tag has a body but no for attribute, alabel is printed, and its for attribute is set to the element ID of the first child component which is an EditableValueHolder.

Theme Identifiers

None.

Client Side Javascript Functions

When the component is rendered, a DOM object corresponding to the component is created. To manipulate the component on the client side, you may invoke functions on the DOM object. With reference to the DOM id, to disable the component, invoke document.getElementById(id).setProps({level: 2}).

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. If omitted, no other components are executed.
setProps(props) Use this function to change any of the following supported properties:
  • accesskey
  • className
  • contents
  • dir
  • errorImage
  • htmlFor
  • id
  • lang
  • level
  • onClick
  • onDblClick
  • onFocus
  • onKeyDown
  • onKeyPress
  • onKeyUp
  • onMouseDown
  • onMouseMove
  • onMouseOut
  • onMouseOver
  • onMouseUp
  • required
  • style
  • title
  • valid
  • value
  • visible
subscribe(topic, obj, func) Use this function to subscribe to an event topic.
  • topic: The event topic to subscribe to.
  • obj: The object in which a function will be invoked, or null for default scope.
  • func The name of a function in context, or a function reference to invoke when topic is published.

Client Side JavaScript Events

When the component is manipulated client side, some functions may publish event topics for custom AJAX implementations to listen for. For example, you can listen for the refresh event topic using:

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

    // Subscribe to refresh event.
    var domNode = document.getElementById("form1:test1");
    domNode.subscribe(domNode.event.refresh.endTopic, processEvents, "update");


</webuijsf:script>

The following events are supported.

<Node>.event.refresh.beginTopic Event topic published before asynchronously refreshing the component. 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
<Node>.event.refresh.endTopic Event topic published after asynchronously refreshing the component. Supported properties include: See setProps() function.
  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage

Examples

Example 1: webuijsf:label with for attribute

<webuijsf:label id="label1" text="Label 1:" for="field1" labelLevel="2"/>
<webuijsf:field id="field1" text="#{Bean.value}" type="text" trim="true"/>

Example 2: webuijsf:label with labelled component in tag body

<webuijsf:label id="label2" text="Label 2:" labelLevel="2"/>
<webuijsf:field id="field2" text="#{Bean.value}" type="text"
trim="true"/></webuijsf:label>

Example 3: Using the label attribute instead of webuijsf:label

<webuijsf:field id="field3" text="#{Bean.value}" type="text" 
trim="true" label="Label 3:" labelLevel="2"/>

Example 4: Update client-side label properties using the getProps and setProps functions

This example shows how to toggle the visible state of a label client side using the getProps and setProps functions. When the user clicks the radio button, the laebl is either show n or hidden.
<webuijsf:radioButton id="rb1" name="rb1" label="Toggle Label Visible" onClick="toggleVisible()"/>
<webuijsf:label id="label1" text="My Label" />

<webuijsf:script>
function toggleVisible() {
var domNode = document.getElementById("form1:label1"); // Get label
return domNode.setProps({visible: !domNode.getProps().visible}); // Toggle visible state
}
</webuijsf:script>

Example 5: Asynchronously update label using refresh function

This example shows how to asynchronously update a label using the refresh function. When the user clicks on the radio button, the label is asynchronously updated with new data.
<webuijsf:radioButton id="rb1" name="rb1" label="Refresh Label" onClick="refreshLabel()"/>
<webuijsf:label id="label1" text="#{MyBean.text}" />
<webuijsf:script>
    function refreshLabel() {
        var domNode = document.getElementById("form1:label1"); // Get label
        return domNode.refresh(); // Asynchronously refresh label
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,..."). When no parameter is given, the refresh function acts as a reset. That is, the component will be redrawn using values set server-side, but not updated.

Example 6: Asynchronously update label using refresh function

This example shows how to asynchronously update a label using the refresh function. The execute property of the refresh function is used to define the client id which is to be submitted and updated server-side. As the user types in the text field, the input value is updated server-side and the label is updated client-side -- all without a page refresh.
<webuijsf:label id="label1" text="#{MyBean.text}"/>
<webuijsf:textField id="field1" text="#{MyBean.text}" label="Change Label"
onKeyPress="setTimeout('refreshLabel();', 0);"/> // Field used to asynchronously update label.
<webuijsf:script>
    function
refreshLabel() {
        var domNode = document.getElementById("form1:label1"); // Get label
        return domNode.refresh("form1:field1"); // Asynchronously refresh while submitting field value
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,...")

legend

Use the webuijsf:legend tag to display a legend, typically at the top of a page.
The webuijsf:legend tag has one facet:
   legendImage - this allows the developer to place their own image and/or text in the legend.

HTML Elements and Layout

A legend consists of an icon/image followed by explanatory text describing the icon/image.

Client Side Javascript Functions

None.

Examples

Example 1: An example showing the default (indicates required field) legend:
<webuijsf:legend id="legend1" />

Example 2: An example showing a custom icon, text, styles:
 <webuijsf:legend id="legend2" text="Critical Alarms" 
     style="position: absolute; left:100px; color:red; font-weight:bold"/>
   <f:facet name="legendImage">
     webuijsf:image id="alarmimage" icon="ALARM_CRITICAL_SMALL" alt="Critical Alarm"/>
   </f:facet>
 </webuijsf:legend>
 
 

link

Use the webuijsf:link tag to insert header references to other documents related to this HTML page. The webuijsf:link tag must be used inside the webuijsf:head tag, and can be used multiple times for references to multiple documents. A common use for the webuijsf:link tag is to link to an external stylesheet, but it can also be used to provide information about the document's relationship to other documents.  There are a number of useful defaults making it simpler to specify an HTML link using this tag.

HTML Elements and Layout

The rendered HTML page contains <link> element, along with any attributes specified through the webuijsf:link tag attributes. 

Theme Identifiers

None.

Client Side Javascript Functions

None.

Example

Example 1: Create a context relative link to a stylesheet

<webuijsf:page>
    <webuijsf:html>
       <webuijsf:head id="blah" title="hyperlink test page">
          <webuijsf:link url="/context-relative-path/tomyfile/stylesheet.css">
       </webuijsf:head>
       <webuijsf:body>
       </webuijsf:body>
    </webuijsf:html>
</webuijsf:page>
listbox

Use the webuijsf:listbox tag to display in the rendered HTML page a box that allows users to select one or more items from a list. The list box shows more than one list option at a time. Use the webuijsf:dropDown tag if you want to display one line and open the list when the user selects it.

HTML Elements and Layout

The listbox component is rendered as an XHTML <select> element. The <option> elements within the <select> element are derived from the webuijsf:listbox tag's items attribute.

Configuring the webuijsf:listbox tag

Use the items attribute to specify the options to be displayed in the listbox. The value of the items attribute must be a JavaServer Faces EL expression that identifies an array, a java.util.Collection or a java.util.Map of com.sun.webui.jsf.Option.

Use the multiple attribute to specify that a user can select more than one item. By default multiple is set to false. If multiple selections are allowed, the model object property that is specified in the selected attribute must be either an array of primitives, an array of objects, or a subclass of java.util.List.

Use the selected attribute to associate the component with a model object that represents the current choice, by setting the value to a JavaServer Faces EL expression that corresponds to a property of a managed bean. The first time the component is rendered, the options that correspond to the value of the selected model object property are marked as selected, using the equals method on the model object.

Use the rows attribute to specify the number of list items that can be seen at once, without scrolling.

The list items will be rendered using a monospace font if the monospace attribute is set to true.

To optionally specify a label for the component, use the label attribute, or specify a label facet.

Grouping Options in the Listbox

The XHTML <select> element can contain an <optgroup> element to define a group of related items in a listbox. The <optgroup> has a label, and the options within the group are indented in the displayed listbox. You can configure the list of items created with the webuijsf:listbox tag to be rendered with <optgroup> elements by setting up your backing bean to use a com.sun.webui.jsf.model.OptionGroup model bean. A backing bean object that populates the listbox from an array with grouped options might look as follows.
 public BackingFileChoice() {
airports = new Option[3];
OptionGroup groupCA = new OptionGroup();
groupCA.setLabel("California");
caAirports = new Option[4];
caAirports[0] = new Option("SFO", "San Francisco");
caAirports[1] = new Option("OAK", "Oakland");
caAirports[2] = new Option("SAN", "San Diego");
caAirports[3] = new Option("LAX", "Los Angeles");
groupCA.setOptions(caAirports);
airports[0] = groupCA;
OptionGroup groupNY = new OptionGroup();
groupNY.setLabel("New York");
nyAirports = new Option[4];
nyAirports[0] = new Option("ALB", "Albany");
nyAirports[1] = new Option("JFK", "New York, JFK");
nyAirports[2] = new Option("LGA", "New York, LaGuardia");
nyAirports[3] = new Option("BUF", "Buffalo");
groupNY.setOptions(nyAirports);
airports[1] = groupNY;
OptionGroup group = new OptionGroup();
group.setLabel("Other airports");
otherAirports = new Option[3];
otherAirports[0] = new Option("PDX", "Portland"); otherAirports[1] = new Option("NRT", "Tokyo");
otherAirports[2] = new Option("TBD", "Future Airport");
otherAirports[2].setDisabled(true);
group.setOptions(otherAirports);
airports[2] = group;
}

The listbox that is rendered with this backing bean will appear as follows:


The important points to note in the sample backing bean are:
  • The OptionGroups each have a setLabel method that sets the label of the corresponding <optgroup>.

  • A separator (a series of dashes) is rendered above the optgroup labels. By default, the separator is rendered above each optgroup in a listbox. The separators can be removed by setting the webuijsf:listbox tag's separators attribute to false.

  • The setOptions method sets the options of each subgroup to the appropriate array values.

  • The setDisabled method can be used to disable any of the options in the listbox.

Facets

The label facet is used to specify a custom component for the label. The label facet overrides the label attribute.

Theme Identifiers

TBA

Client-side JavaScript Functions

When the component is rendered, a DOM object corresponding to the component is created. To manipulate the component on the client side, you may invoke functions on the DOM object. With reference to the DOM id, to disable the component, invoke document.getElementById(id).setProps({visible: false}).

getProps() Use this function to get widget properties. Please see setProps() function for a list of supported properties.
getSelectElement() Use this function to access the HTML <select> element that is rendered by the component.
getSelectedLabel() Use this function to get the label of the first selected option on the listbox. If no option is selected, this function returns null.
getSelectedValue() Use this function to get the value of the first selected option on the listbox. If no option is selected, this  function returns null.
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. If omitted, no other components are executed.
setProps(props) Use this function to change any of the following supported properties:
  • id
  • dir
  • disabled
  • label
  • lang
  • multiple
  • monospace
  • onBlur
  • onChange
  • onClick
  • onDblClick
  • onFocus
  • onMouseDown
  • onMouseOut
  • onMouseOver
  • onMouseUp
  • onMouseMove
  • onKeyPress
  • onKeyUp
  • onSelect
  • options
  • size
  • style
  • tabIndex
  • 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.
subscribe(topic, obj, func) Use this function to subscribe to an event topic.
  • topic: The event topic to subscribe to.
  • obj: The object in which a function will be invoked, or null for default scope.
  • func The name of a function in context, or a function reference to invoke when topic is published.

Client Side JavaScript Events

When the component is manipulated client side, some functions may publish event topics for custom AJAX implementations to listen for. For example, you can listen for the refresh event topic using:

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

    // Subscribe to refresh event.
    var domNode = document.getElementById("form1:test1");
    domNode.subscribe(domNode.event.refresh.endTopic, processEvents, "update");


</webuijsf:script>

The following events are supported.

<Node>.event.refresh.beginTopic Event topic published before asynchronously refreshing the component. 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
<Node>.event.refresh.endTopic Event topic published after asynchronously refreshing the component. Supported properties include: See setProps() function.
  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage
<Node>.event.submit.beginTopic Event topic published before asynchronously submitting the component. 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
<Node>.event.submit.endTopic

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

  • props - JSON object containing messages (if any) raised by the server.In particular, valdiation messages will be present here if validation failed

Examples

Example 1: Listbox with single selection

     <webuijsf:listbox selected="#{flightSearch.leaveAirport}" 
items="#{dataBean.airports}"
rows="6"
id="leaveAirport"
toolTip="#{msgs.chooseAirport}"
label="#{msgs.chooseDepartureAirport)" />

Example 2: Listbox that uses a label facet

                 
<webuijsf:listbox selected="#{flightSearch.leaveAirport}"
items="#{dataBean.airports}"
rows="6"
id="leaveAirport"
toolTip="#{msgs.chooseAirport}"
label="#{msgs.chooseDepartureAirport)" >
<f:facet name="label">
<webuijsf:label id="aplabel" text="#{msgs.chooseDepartureAirport)"
for="leaveAirport" labelLevel="2"/>
</f:facet>
</webuijsf:listbox>

Example 3: Update client-side listbox properties using the getProps and setProps functions

This example shows how to toggle the disabled state of a listbox client side using the getProps and setProps functions. When the user clicks the radio button, the listbox is either disabled or enabled.

<webuijsf:radioButton id="rb1" name="rb1" label="Hide Listbox" onClick="toggleDisabled()"/>
<webuijsf:listbox
id="list1"
    items="#{dataBean.airports}"
    label="#{msgs.chooseDepartureAirport}"
    selected="#{flightSearch.leaveAirport}"
    tooltip="#{msgs.chooseAirport}"/>

<webuijsf:script>
    function toggleDisabled() {
        var domNode = document.getElementById("form1:list
1"); // Get list
        return domNode.setProps({disabled: !domNode.getProps().disabled}); // Toggle disabled state
    }
</webuijsf:script>

Example 4: Asynchronously update button using refresh function

This example shows how to asynchronously update a listbox using the refresh function. When the user clicks on the radio button, the listbox is asynchronously updated with new data.

<webuijsf:radioButton id="rb1" name="rb1" label="Refresh Listbox" onClick="refreshList()"/>
<webuijsf:listbox id="list1"
    items="#{dataBean.airports}"
    label="#{msgs.chooseDepartureAirport}"
    selected="#{flightSearch.leaveAirport}"
    tooltip="#{msgs.chooseAirport}"/>

<webuijsf:script>
    function refreshList() {
        var domNode = document.getElementById("form1:list1"); // Get list
        return domNode.refresh(); // Asynchronously refresh list
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,..."). When no parameter is given, the refresh function acts as a reset. That is, the component will be redrawn using values set server-side, but not updated.

Example 5: Asynchronously update button using refresh function

This example shows how to asynchronously update a listbox using the refresh function. The execute property of the refresh function is used to define the client id which is to be submitted and updated server-side. As the user types in the text field, the input value is updated server-side and the listbox label is updated client-side -- all without a page refresh.

<webuijsf:listbox id="list1"
    items="#{dataBean.airports}"
    label="
#{MyBean.label}"
    selected="#{flightSearch.leaveAirport}"
    tooltip="#{msgs.chooseAirport}"/>
<webuijsf:textField id="field1"
    text="#{MyBean.label}"
    label="Change list Label"
    onKeyUp="refreshList()"/> // Field used to asynchronously update label.

<webuijsf:script>
    function
refreshList() {
        var domNode = document.getElementById("form1:list1"); // Get list
        return domNode.refresh("form1:field1"); // Asynchronously refresh while submitting field value
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,...")
 

login

Use the webuijsf:login component to authenticate users. By default the tag is linked to a JAAS(Java Authentication and Authorization Service) based infrastructure. Application developers can write LoginModule implementations suited to their needs. For more details on how to write JAAS LoginModule applications see the following link: http://java.sun.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html. The JAAS configuration containing the LoginModule impl entries should be added to the config file if one exists or a new file should be created and specified using the appropriate Djava parameter. The webuijsf:login tag allows you to insert HTML elements like textfield, statictext, dropdowns, listboxes, labels to prompt users to enter authentication data. The prompts that need to be displayed are usually controlled at the server side by the loginModule implementation classes.

Configuring the login tag

Use the serviceName attribute to identify the underlying authentication service.

Use the value to capture the resuolt of the authentication process. For the default JAAS based backend the value of the authentication process is the Subject object representing the authenticated Principal and credential objects.

Use the redirectURL to specify a URL to redirect to after successful authentication.

Set the autoStart attribute to true to initiate the authentication process on its own without any client side intervention or wait for some other client side entity to start the authentication process. By default this attribute is set to true. In situations where the authentication process needs to start based on other events happening on the client side this attribute should be set to false and the appropriate client side API used to fire up the process.


Client-side JavaScript Functions

When the component is rendered, a DOM object corresponding to the component is created. Subscribing to well known events is the only way to interact with the login widget. The widget publishes events announcing success or failure of the authentication process. Applications should use these events to figure out what to do next. Applications can also use the authenticate() function to kick start the authentication process.

getProps() Use this function to get widget properties. Please see setProps() function for a list of supported properties.
authenticate() Use this function to start the authentication process if you do not want the process to start when the page loads.
setProps(props) Use this function to change any of the following supported properties. Generally, setProps() should only be called by function that is handling the result of an authentication to the underlying server side.
  • id - ID of the login widget.
  • loginState - State of the authentication process.
  • autoStart - Flag indicating if authentication process should start on page load.
  • userData - JSON object containing user data that needs to be displayed as user prompt.
  • keys - JSON object representing the key value mapping for user data fields
  • style
  • tabIndex
  • className
subscribe(topic, obj, func) Use this function to subscribe to an event topic.
  • topic: The event topic to subscribe to.
  • obj: The object in which a function will be invoked, or null for default scope.
  • func The name of a function in context, or a function reference to invoke when topic is published.

Client Side JavaScript Events

Based on the result of the authentication process, some functions may publish event topics for custom AJAX implementations to listen for. See example2 below.


The following events are supported.

<Node>.event.authenticate.beginTopic Event topic published before asynchronously authenticating the component. Supported properties include:
id: this.id, loginState: this.loginState, keys: this.keys, endTopic: <Node>.event.authenticate.endTopic
  • loginState - the current state of the authentication process
  • keys - the set of key value pairs representing user/credential information
  • id - The client id to process the event for
<Node>.event.authenticate.endTopic Event topic published after asynchronously authenticating the component. Supported properties include: See setProps() function.
  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage
<Node>.event.result.successTopic Event topic published when the asynchronously submitted authentication process has succeeded. Supported properties include:
  • id - The client id to process the event for
<Node>.event.result.failureTopic

Event topic published when the asynchronously submitted authentication process has failed. Supported properties include:

  • id - The client id to process the event for

Examples

For all the examples below one of the following JAAS configuration entries have been used.

AppLogin1 {
com.sun.webui.jsf.example.login.TestLoginModule optional;
};

AppLogin2 {
com.sun.webui.jsf.example.login.TestLoginModule2 requisite;
com.sun.webui.jsf.example.login.TestLoginModule3 requisite;
};

Example 1: Basic login example with single LoginModule

<webuijsf:login id="login1" redirectURL="/example/faces/login/result.jsp"
serviceName="AppLogin1" value="#{LoginBean.value}" />

Example 2: Login example showing use of events


<webuijsf:script>
    function init() {
        var domNode = document.getElementById("form1:login3");
        if (domNode == null || domNode.event == null) {
            return setTimeout('init();', 10);
        }
        domNode.subscribe(domNode.event.result.successTopic, this, handleEvent);
        domNode.subscribe(domNode.event.result.failureTopic, this, handleFailureEvent);
    }

    this.handleEvent = function(id) {
        var loc = document.location;
        var newURL = loc.protocol + "//" + loc.host;
        newURL = newURL + "/example/faces/login/result.jsp";
        document.location.href = newURL;
    }

    this.handleFailureEvent = function(id) {
        var loc = document.location;
        var newURL = loc.protocol + "//" + loc.host;
        newURL = newURL + "/example/faces/login/failed.jsp";
        document.location.href = newURL;
    }
</webuijsf:script>

<webuijsf:body onLoad="init();">
<webuijsf:form id="form1">
<webuijsf:masthead id="Masthead" productImageURL="/images/webconsole.png"
  productImageDescription="Java Web Console" userInfo="test_user"
  serverInfo="test_server" />

<webuijsf:login id="login3" value="#{LoginBean.value}" serviceName="AppLogin1"/>

</webuijsf:form>
</webuijsf:body>


Example 3: Login example using two LoginModule implementations.


<webuijsf:login id="login2" value="#{LoginBean.value}" serviceName="AppLogin2" />

Example 4: Secondary login example

<webuijsf:head>
<webuijsf:script>
    function init() {
        var domNode = document.getElementById("form1:secondary");
        if (domNode == null || domNode.event == null) {
            return setTimeout('init();', 10);
        }
        domNode.subscribe(domNode.event.result.successTopic, this, handleSuccessEvent);
        domNode.subscribe(domNode.event.result.failureTopic, this, handleFailureEvent);
    }

    this.handleSuccessEvent = function(id) {
        // show the common task page after successful authentication
        var cts = document.getElementById("form1:ctp1");
        cts.style.display = "block";
    }

    this.handleFailureEvent = function(id) {
        // show the retry button
        var loginDiv = document.getElementById("form1:secondary");
        loginDiv.style.display = "none";
        var btn = document.getElementById("form1:retry");
        btn.style.display = "block";
    }
<webuijsf:script>

</webuijsf:head>
<webuijsf:body id="body" onLoad="init();" styleClass="#{themeStyles.CTS_BACKGROUND}">
  <webuijsf:form id="form1">

    <webuijsf:login id="secondary" value="#{LoginBean.value}" serviceName="AppLogin1" />

    <webuijsf:button id="retry" text="Authentication Failed, Retry"
      toolTip="Try Authenticating Again" style="display:none"
      onClick="var login = document.getElementById('form1:login1'); login.style.display='block'; login.authenticate();" />

    <webuijsf:commonTasksSection style="display:none" id="ctp1">
        <webuijsf:commonTasksGroup id="taskGroup1" title="#{msgs.commontask_group1}">
            <webuijsf:commonTask id="task1" text="#{msgs.commontask_task1}"
              toolTip="#{msgs.commontask_task1}" actionExpression="#{commonTask.taskAction}"
              target="_blank" icon="CTS_OVERVIEW">
            <webuijsf:commonTask>
            <webuijsf:commonTask id="task2" text="#{msgs.commontask_task2}" toolTip="#{msgs.commontask_task2}"
              onClick="popup();return false;" infoTitle="#{msgs.commontask_task2infotitle}"
              infoText="#{msgs.commontask_task2infotext}" />
        </webuijsf:commonTasksGroup>
        <webuijsf:commonTasksGroup id="taskGroup2" title="#{msgs.commontask_group2}">
            <webuijsf:commonTask id="task3" text="#{msgs.commontask_task3}" toolTip="#{msgs.commontask_task3}"
               onClick="popup();return false; " infoLinkUrl="/faces/commontask/sample.jsp"
               infoLinkText="#{msgs.commontask_infolinktext}" infoTitle="#{msgs.commontask_task3infotitle}"
               infoText="#{msgs.commontask_task3infotext}"/>
            <webuijsf:commonTask id="task4" text="#{msgs.commontask_task4}" onClick="popup();return false;"
               toolTip="#{msgs.commontask_task4}"/>
            <webuijsf:commonTask id="task5" text="#{msgs.commontask_task5}"
               onClick="popup();return false;" infoTitle="#{msgs.commontask_task5infotitle}"
               toolTip="#{msgs.commontask_task5}" infoText="#{msgs.commontask_task5infotext}"/>
         </webuijsf:commonTasksGroup>
          ...
</webuijsf:body>
<webuijsf:script type="text/javascript">
    function popup() {
        var popupWin = window.open('/example/faces/commontask/sample.jsp', 'Test Page',
        'scrollbars,resizable,width=650,height=500,top='+((screen.height - (screen.height/1.618)) - (500/2))+',left='+((screen.width-650)/2) );
        popupWin.focus();
    }
<webuijsf:script>


markup

Use the webuijsf:markup tag to insert any type of XML markup in the rendered HTML page. The webuijsf:markup tag allows you to insert HTML elements into the JSP page where HTML is not permitted inside a JSF tag. 

Configuring the markup tag

Use the tag attribute to specify the type of HTML element to insert.  For instance, to insert a <p> tag, set the attribute to tag="p" in the webuijsf:markup tag.  Note that you do not include the angle brackets.

If the HTML element you are inserting is a singleton element, you must specify the singleton attribute.  The singleton attribute causes the trailing /> to be generated in the rendered HTML. For example, the  <br> element is a singleton element, which must be rendered as <br /> to be XHTML compliant.

If you want to specify additional HTML attributes for the element you are inserting, use the extraAttributes attribute.

HTML Elements and Layout

The rendered HTML page includes the HTML element that was specified in the webuijsf:markup tag's tag attribute, along with any HTML attributes that were included in the extraAttributes attribute.

Theme Identifiers

None.

Client Side Javascript Functions 

None.

Examples

Example 1:  Insert a singleton element

<webuijsf:markup tag="br" singleton="true" />

This generates <br />.

Example 2: Insert a <div> element with a style attribute

   <webuijsf:markup tag="div" style="color:blue" />

This generates <div style="color:blue" >

Example 3: Insert a <h3> with HTML attributes

    <webuijsf:markup tag="h3" extraAttributes="onclick='alert(&quot;foobar&quot;);'" >
        <webuijsf:staticText text="Example" />
    </webuijsf:markup>
This generates a level 3 head titled Example that will display the alert with "foobar" in it when clicked.
mastFooter

Use the webuijsf:mastFooter tag to display a a footer, at the bottom of each rendered HTML page of the web application. The footer signifies the end of the display for that page. The footer should correspond to a masthead that is usually displayed at the top of each rendererd HTML page.

HTML Elements and Layout

In the rendered HTML page, the mastFooter is created with <div> elements. The footer consists of a corporate image which could be supplied by using the corporateImageURL attribute or a corporateImage facet:

  • mastFooter code sample

    • Simple use case:

      <webuijsf:footer id="myfoot"/>
    • Using the corporateImage attribute:

      <webuijsf:mastFooter id="myFoot" corporateImageURL="/path/to/image/foo.jpg" />
    • Using the corporateImage Facet:

      <webuijsf:mastFooter id="myFoot">
      <f:facet name="corporateImage">
      <webuijsf:image src="/path/to/image/foo.jpg" height="hh" width="ww"/>
      </f:facet>
      </webuijsf:mastFooter>
masthead

Use the webuijsf:masthead tag to display a masthead, or page banner, at the top of each rendered HTML page of the web application. The masthead can be used to display information about the application, the current user and server, and include various links and status information. If you use the image attributes of this tag and the images are PNG file type, then you must set the height and width attributes of this tag for them to display properly on Internet Explorer.

The webuijsf:masthead tag must be used as a child of the webuijsf:form tag.

The webuijsf:mastFooter tag is intended to be used in pages that use the masthead, to provide a matching footer that contains the corporate branding image.

HTML Elements and Layout

In the rendered HTML page, the masthead is created with <table> elements. The masthead consists of the following areas:

  • Utility Bar - The masthead's top row, which spans across the width of the masthead. The utility bar contains links that you specify with the utilities attribute or with various facets. See the Utility Bar section for more information.

  • User Info - Displays the name of the user running the application, which is specified with the userInfo attribute. By default the label is User but this can be changed with the userInfoLabel attribute. The userInfo facet can be used to replace both user info fields with other components.

  • Server Info - Displays the name of the server where the application is running, which is specified with the serverInfo attribute. By default the label is Server, but this can be changed with the serverInfoLabel attribute. The serverInfo facet can be used to replace both server info fields with other components.

  • Product Info - Displays the graphic file for the product name, which is specified with the productImageURL attribute. The productImageDescription attribute is used to provide text to be used as alt text for the image, and productImageHeight and productImageWidth can be used to provide the dimensions of the image when necessary.

  • Status Area - Displays system messages, job information, date/time, and alarm counts by default. These items are specified with the attributes notificationMsg, jobCount, dateTime, and alarmCounts. The status area content can also be specified with various facets. See the Status Area section for more information.

  • Brand Image - Displays the graphic file for a brand for the application. By default, this is an image that is specified in the theme, but can be overridden with the brandImageURL attribute. The brandImageDescription attribute is used to provide text to be used as alt text for the image, and brandImageHeight and brandImageWidth can be used to provide the dimensions of the image when necessary.

The following diagram shows the locations of the masthead areas, and the attributes and facets you can use to provide the content for each area.

Utility Bar  utilityBar facet
consoleLink
facet
versionLink
facet
search facet
 Links specified with utilities attribute  logoutLink
facet
helpLink
facet
User Info
userInfo, userInfoLabel attributes or userInfo facet
Server Info
serverInfo, serverInfoLabel attributes or serverInfo facet
(empty)
Brand Image
brandImageURL and related attributes, or brandImage facet
Product Info
productImageURL
and related attributes, or productInfo facet
Status Area  statusArea facet
notificationMsg attribute
notificationInfo facet
jobCount attribute
jobsInfo facet
dateTime attribute
dateTimeInfo facet
 alarmCounts attribute
currentAlarmsInfo facet 

Utility Bar

The content of the Utility Bar can be specified with the following individual facets:

  • consoleLink - by default displays an Applications button. This button can be used to provide a link back to some "home" location, such as an application launch page, or a main console page.

  • versionLink - by default displays a Version button, which can be used to provide a popup window that displays information about the application version. You can use the webuijsf:versionPage tag to display version information in the JSP for the popup window.

  • search - displays components that you specify to provide search capability.  You must provide the action method to perform the search.  The theme provides an icon with the key MASTHEAD_SEARCH that can be used for a search button.  See the Examples for more details about using the search facet.
  • logoutLink - by default displays a Logout button, which can be used to log the user out of the application.

  • helpLink - by default displays a Help button, which can be used to open a popup window that displays help for the application. You can use the webuijsf:helpWindow tag as a child of the helpLink facet to implement the help window.

The child components of the facets can override the labels of the buttons by specifying their own text values.

These facets can be used along with the utilities attribute, which specifies additional custom links to display in the utility bar. The utilities attribute must be bound to an array of Hyperlink components. If no style has been set on the hyperlinks bound to the utilities attribute, the masthead component applies styles that are used for the Logout and Help links. The links that you specify with the utilities attribute are displayed to the left of the Logout and Help buttons.

utilityBar Facet

The Utility Bar content can also be specified with the utilityBar facet, which overrides all other attributes and facets supported for the Utility Bar area. If you want to specify more than one component in the utilityBar facet, you must enclose the component tags in a container such as the webuijsf:panelGroup tag.

Status Area

The Status Area can display the status items shown in the following table. Each status item can be configured with an attribute of the webuijsf:masthead tag, or a facet, or as a component in the statusArea facet. The attributes provide the default display of the status items, and adhere to UI guidelines. The individual facets allow you to customize an individual status item, while using the attributes for other status items to obtain the default display style. You can use the statusArea facet to customize the entire status area, by adding your own custom tags in the facet. See the statusArea Facet section for more information.

Status items Attributes Individual Facets Components in statusArea facet
A notification message notificationMsg notificationInfo webuijsf:notificationPhrase
The number of jobs running jobCount

jobsInfo webuijsf:jobStatus
The current date and time dateTime

dateTimeInfo webuijsf:timeStamp
The current number of down, critical, major and minor alarms alarmCounts

currentAlarmsInfo webuijsf:alarmStatus

statusArea Facet

The statusArea facet overrides all the attributes and individual facets for the status items. In addition to your own tags, you can use component tags in the statusArea facet to add functionality that is similar to functionality provided by the attributes. If you want to specify more than one component in the statusArea facet, you must enclose the component tags inside a container such as the webuijsf:panelGroup tag. You should also enclose the components within <div> tags to specify a class selector that properly sets the spacing around the components within the masthead.  For example:

  • <webuijsf:markup tag="div" styleClass="#{themeStyles.MASTHEAD_STATUS_DIV}">  Sets padding and alignment for status/progress information in status area of masthead

  • <webuijsf:markup tag="div" styleClass="#{themeStyles.MASTHEAD_TIME_DIV}">  Sets padding and alignment for time stamp information in status area of masthead

  • <webuijsf:markup tag="div" styleClass="#{themeStyles.MASTHEAD_ALARM_DIV}"> Sets padding and alignment for alarm information in status area of masthead                  

See the Examples section for sample code that uses the statusArea facet.

Theme Identifiers

See the Theme package javadoc for the constants that can be used to specify masthead theme elements.

Client Side Javascript Functions

None.

Examples

The examples use the MastheadBean, which is shown after the examples.

Example 1:  Create a masthead using individual facets for links in the Utility Bar

This example uses the utility bar facets to add UI-guideline compliant links to the top of the masthead.
  <webuijsf:page>
    <webuijsf:html>
        <webuijsf:head id="foo" title="Foo Page" />
        <webuijsf:body>
            <webuijsf:form id="form1">
                <webuijsf:masthead id="Masthead" productImageURL="../images/webconsole.png"
                 productImageDescription="Java Web Console" productImageHeight="40"
                 productImageWidth="165" userInfo="user_name" serverInfo="server_name"
                 jobCount="0" dateTime="true" notificationMsg="Beer is good"                
                 alarmCounts="#{MastheadBean.alarms}">
                    <f:facet name="helpLink">
                      <webuijsf:hyperlink action="#{MastheadBean.helpClicked}" />
                    </f:facet>
                    <f:facet name="consoleLink">
                      <webuijsf:hyperlink action="#{MastheadBean.consoleClicked}" />
                    </f:facet>
                    <f:facet name="versionLink">
                      <webuijsf:hyperlink action="#{MastheadBean.versionClicked}" />
                    </f:facet>
                    <f:facet name="logoutLink">
                      <webuijsf:hyperlink action="#{MastheadBean.logoutClicked}" />
                    </f:facet>
                </webuijsf:masthead>
             </webuijsf:form>
       </webuijsf:body>
    </webuijsf:html>
</webuijsf:page>

Example 2: Create a masthead using the statusArea facet 

This example uses webuijsf:panelGroup to enclose the tags for the status items. The components are also enclosed in webuijsf:markup tags that specify <div> elements with a class selector that applies the correct spacing around the component in the masthead.

<webuijsf:page>
    <webuijsf:html>
        <webuijsf:head id="foo" title="Foo Page" />
        <webuijsf:body>
            <webuijsf:form id="form1">
               <webuijsf:masthead id="Masthead" productImageURL="../images/webconsole.png"
                   productImageDescription="Java Web Console" userInfo="user_name"
                   serverInfo="server_name">
                 <f:facet name="statusArea">
                   <webuijsf:panelGroup id="statusPanel" separator="">
                     <webuijsf:markup tag="div" styleClass="#{themeStyles.MASTHEAD_STATUS_DIV}">
                       <webuijsf:notificationPhrase text="Important info goes here" />
                       <webuijsf:image icon="DOT" border="0" width="20" height="1" />
                       <webuijsf:jobStatus numJobs="1" />
                     </webuijsf:markup>
                     <webuijsf:markup tag="div" styleClass="#{themeStyles.MASTHEAD_TIME_DIV}">
                       <webuijsf:timeStamp />
                     </webuijsf:markup>
                     <webuijsf:markup tag="div" styleClass="#{themeStyles.MASTHEAD_ALARM_DIV}">
                       <webuijsf:alarmStatus numDownAlarms="0" numCriticalAlarms="1" numMajorAlarms="2" numMinorAlarms="3" />
                     </webuijsf:markup>
                   </webuijsf:panelGroup>
                 </f:facet>
               </webuijsf:masthead>
             </webuijsf:form>
       </webuijsf:body>
    </webuijsf:html>
</webuijsf:page>

Example 3: Create a masthead with custom links and search capability in the Utility Bar

This example shows how to create custom links in the utility bar, along with the links produced with the facets. This example also shows how you might add search with the search facet, and use the versionLink facet to open a version popup page. 

<webuijsf:page>
    <webuijsf:html>
       <webuijsf:head id=foo title="Foo Page"/>
       <webuijsf:body>
            <webuijsf:form id="form1">
            <webuijsf:masthead id="Masthead" productImageURL="../images/webconsole.png"
                 productImageDescription="Java Web Console" userInfo="user_name"
                 serverInfo="server_name" jobCount="0" dateTime="true"
                 notificationMsg="Beer is good" utilities="#{MastheadBean.links}"
                 alarmCounts="#{MastheadBean.alarms}">                
              
               <f:facet name="helpLink">
                 <webuijsf:hyperlink action="#{MastheadBean.helpClicked}" />
               </f:facet>              
               <f:facet name="consoleLink">
                 <webuijsf:hyperlink action="#{MastheadBean.consoleClicked}" />
               </f:facet>
               <f:facet name="search">
                 <webuijsf:panelGroup >
                  <webuijsf:textField id="searchText"
                                     text="#{MastheadBean.searchCriteria}"/>

                  <webuijsf:button icon="MASTHEAD_SEARCH" id="searchButton"
                                   text="Search" style="vertical-align:bottom"
                                   actionExpression="#{MastheadBean.doSearch}" />
                 </webuijsf:panelGroup>
               </f:facet>              
               <f:facet name="versionLink">
                 <webuijsf:hyperlink  toolTip="Display Product Version. (Opens a new window)"
                                onClick="javascript: var versionWin = window.open('../faces/version/version.jsp','VersionWindow','scrollbars,resizable,width=650,height=500,top='+((screen.height - (screen.height/1.618)) - (500/2))+',left='+((screen.width-650)/2) ); versionWin.focus()" />
               </f:facet>
               <f:facet name="logoutLink">
                 <webuijsf:hyperlink action="#{MastheadBean.logoutClicked}" />
               </f:facet>
               <f:facet name="userInfo">
                 <webuijsf:hyperlink text="user_name" styleClass="#{themeStyles.MASTHEAD_USER_LINK}" action="#{MastheadBean.userClicked}" />
               </f:facet>
               <f:facet name="serverInfo">
                 <webuijsf:hyperlink text="s" styleClass="#{themeStyles.MASTHEAD_USER_LINK}" action="#{MastheadBean.serverClicked}" />
               </f:facet>
            </webuijsf:masthead>   
          </webuijsf:form>
       </webuijsf:body>
    </webuijsf:html>
</webuijsf:page>

MastheadBean used in the examples

import com.sun.webui.jsf.component.Hyperlink;
import com.sun.webui.jsf.component.DropDown;
import com.sun.webui.jsf.model.Option;

import javax.el.MethodExpression;

import javax.faces.component.UIComponent;
import javax.faces.context.FacesContext;
import javax.faces.event.ActionEvent;
import javax.faces.event.AbortProcessingException;

import util.JSFUtilities;

/**
 *
 * @author Administrator
 */
public class MastheadBean{   
    String message = "foobar";
    Hyperlink[] links = null;
    int[] alarms = new int[] {1, 2, 3, 4};
    String selectedItem = "view1";
    private Option[] views = null;
    String helpText = "This very, very, very, very, very, very, very, very, " +
        "very, very, very, very, very, very, very, very, very, very, very " +
        "very, very, long help text sentence should line wrap.";
   
    /** Creates a new instance of JumpBackingBean */
    public MastheadBean() {

        links = new Hyperlink[2];

    FacesContext context = FacesContext.getCurrentInstance();
       
        links[0] = new Hyperlink();
        links[0].setText("One");
        //links[0].setUrl("#");      
    JSFUtilities.setMethodExpression(links[0], "actionExpression",
        "#{MastheadBean.extraOneClicked}");

    //
        links[1] = new Hyperlink();
        links[1].setText("Two");
        //links[1].setUrl("#");       
    JSFUtilities.setMethodExpression(links[1], "actionExpression",
        "#{MastheadBean.extraTwoClicked}");
       
       
        views = new Option[3];
        views[0] = new Option("view1", "View 1");
        views[1] = new Option("view2", "View 2");
        views[2] = new Option("view3", "View 3");

    /*
    for (Option view : views) {
        JSFUtilities.setMethodExpression(view, "actionExpression",
        "#{MastheadBean.viewChanged}");
    }
    */
    }
   
    public String getSelectedItem() {
        return selectedItem;
    }
   
    public void setSelectedItem(String s) {
        selectedItem = s;
    }
   
    public String getHelpText() {
        return helpText;
    }
   
    public Option[] getViews() {
        return views;
    }
   
    public String getMessage() {
        return message;
    }
   
    public void setMessage(String msg) {
        message = msg;
    }   
   
    public Hyperlink[] getLinks() {
        return links;
    }
   
    public void setLinks(Hyperlink[] links) {
        this.links = links;
    }
   
    public int[] getAlarms() {
        return alarms;
    }
   
    public void setAlarms(int[] alarms) {
        this.alarms = alarms;
    }
   
    public String extraOneClicked() {       
        message = "Extra link one was clicked";
        return "";
    }
   
    public String extraTwoClicked() {
        message = "Extra link two was clicked";
        return "";
    }
   
    public String consoleClicked() {
        message = "Console link was clicked";
       
        return "";
    }
   
    public String versionClicked() {
        message = "Version link was clicked";
       
        return "";
    }
   
    public String logoutClicked() {
        message = "Logout link was clicked";
       
        return "";
    }
   
    public String helpClicked() {
        message = "Help link was clicked";
       
        return "";
    }
   
    public String userClicked() {
        message = "User link was clicked";
       
        return "";
    }
   
    public String serverClicked() {
        message = "Server link was clicked";
       
        return "";
    }
   
    public String saveClicked() {
       
        System.out.println("Save clicked");
       
        message = "Save page button was clicked";
       
        return "";
    }
   
    public String resetClicked() {
        message = "Reset page button was clicked";
       
        return "";
    }
   
    public String action1Clicked() {
        message = "Page action 1 was clicked";
       
        return "";
    }
   
    public String action2Clicked() {
        message = "Page action 2 was clicked";
       
        return "";
    }
   
    public String action3Clicked() {
        message = "Page action 3 was clicked";
       
        return "";
    }
   
    public String viewChanged() {
        message = "View menu was changed";
       
        return "";
    }
   
    private String searchCriteria = "*";
   
    public String getSearchCriteria() {
        return searchCriteria;
    }
   
    public void setSearchCriteria(String s) {
        searchCriteria = s;
    }
   
    public String doSearch() {
        System.out.println("doSearch called");
        message = "Search was clicked with criteria " + searchCriteria;
       
        return "";
    }
   
    public void menuChanged(ActionEvent e) throws AbortProcessingException {
        UIComponent c = e.getComponent();
       
        DropDown menu = (DropDown) c;
       
        message = "View menu was changed to value " + menu.getValue();
    }
}

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.
subscribe(topic, obj, func) Use this function to subscribe to an event topic.
  • topic: The event topic to subscribe to.
  • obj: The object in which a function will be invoked, or null for default scope.
  • func The name of a function in context, or a function reference to invoke when topic is published.

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. For example, you can listen for the refresh event topic using:

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

    // Subscribe to refresh event.
    var domNode = document.getElementById("form1:test1");
    domNode.subscribe(domNode.event.refresh.endTopic, processEvents, "update");


</webuijsf:script>

JavaScript Event Description
<Node>.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
<Node>.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
<Node>.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
<Node>.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;
    }
    
    
message The Message component is used to display error and warning messages for another component.
messageGroup

Use the webuijsf:messageGroup tag to display a list of messages that are not associated with a specific component. The MessageGroup component displays error messages for all components on the page, and for the JSP page itself. Generally, the tag should be used at the top or bottom of the page.

Note that the messages displayed with the webuijsf:messageGroup tag do not indicate which component the messages are associated with. Use the webuijsf:message tag to associate error messages with specific components.

HTML Elements and Layout

A message group consists of a list of messages. The messages are listed in the order in which they are queued as the page is processed by the server. There is no indication of which component has the error. You should use the webuijsf:message tag to display error messages next to the affected components.

Configuring the webuijsf:messageGroup tag

Use the showGlobalOnly attribute to show only the messages that are not associated with a particular component. This attribute can be used to avoid redundant display of error messages which can occur if you also use the webuijsf:message tag in the same page. Use the showSummary and showDetail tag attributes to specify whether to include summary text and detailed text.

Messages are defined in a resource bundle, which can include keys for summary text and detailed text for messages.

Theme Identifiers

TBA

Client Side Javascript Functions

None.

Examples

Example 1: Display global errors at the top of the page

This example shows where you might position the webuijsf:messageGroup tag to display errors at the top of the page. The example uses the showGlobalOnly attribute to avoid duplicating the errors displayed by the webuijsf:message tag that is included in this page.

 <webuijsf:page>
   <webuijsf:html>
    <webuijsf:head title="A title" />
      <webuijsf:body>
      <webuijsf:form ....>
      <webuijsf:masthead ... >
      <webuijsf:breadcrumbs >
      </webuijsf:breadcrumbs >
       
       <webuijsf:messageGroup showGlobalOnly="true"/>
       <webuijsf:staticText text="Validator checks that the value is between 0-10 inclusive. />
       <webuijsf:message for="form1:textTest1"/>
       <webuijsf:textField id="textTest1" label="Enter a number:" 
                        text="#{FieldTest.number}" 
                        validator="#{FieldTest.checkNumber}"/>
       ....
 
metaUse the webuijsf:meta tag to create an HTML <meta> element in the rendered HTML page. The <meta> element provides meta-information about your page, such as descriptions and keywords for search engines and refresh rates.  The webuijsf:meta tag must be inside a webuijsf:head tag.
 

HTML Elements and Layout

The rendered HTML page contains an HTML <meta> tag and its associated attributes.

Theme Identifiers

None.

Client Side Javascript Functions

None.

Example

Example 1: Create a Meta tag

....
<webuijsf:head title="meta example" >
   <webuijsf:meta httpEquiv="refresh" content="5" />
</webuijsf:head>
....

notificationPhrase

Use the webuijsf:notificationPhrase tag to display notification information. This tag is typically specified as part of the webuijsf:masthead tag's statusArea facet. The webuijsf:notificationPhrase tag produces notification information identical to the webuijsf:masthead tag's notificationMsg attribute. See the webuijsf:masthead documentation for more information about the statusArea facet. This component should be marked as "immediate=true" so that it does not interfere with the masthead or any other component's JSF lifecycle.

The statusArea facet overrides the masthead's status area attributes. The webuijsf:notificationPhrase tag enables you to include notification messages in the status area, along with your custom components. The webuijsf:jobStatus, webuijsf:timeStamp, and webuijsf:alarmStatus tags enable you to include the other standard status area components as well.

Note that when you use the webuijsf:masthead attributes, spacing between the components is handled automatically. When you use the webuijsf:alarmStatus, webuijsf:jobStatus, webuijsf:timeStamp, and webuijsf:notificationPhrase tags in the statusArea facet, you may have to add code to handle the spacing between the components, as demonstrated in the example below.

Note that the notificationPhrase component is deprecated. Take a look at the examples section to see how to create an equivalent of the webuijsf:notificationPhrase.

HTML Elements and Layout

The rendered HTML page includes an <img> element for the information icon, adjacent to an <a> hyperlink containing the notification message.

Configuring the webuijsf:notificationPhrase tag

Specify the notification message with the text attribute. Use the icon attribute to specify a different theme identifier to use for the image, or imageURL to specify a non-theme image. Use other attibutes, such as url, action, or actionListenerExpression to provide detailed information about the notification message or take other action.

The immediate attribute should be set to true when this component is used in the masthead.

Theme Identifiers

The theme provides the following notification icon identifiers.

ALERT_INFO_LARGE
ALERT_INFO_MEDIUM
ALERT_INFO_SMALL

Client Side Javascript Functions

None.

Examples

Example 1: Display a notification phrase as part of the masthead statusArea facet

This example uses webuijsf:panelGroup to enclose the tags for the status items. The components are also enclosed in f:verbatim tags that specify <div> elements with a class selector that applies the correct spacing around the component in the masthead.

<webuijsf:masthead id="Masthead" productImageURL="../images/webconsole.png"
         productImageDescription="Java Web Console" userInfo="user_name" 
         serverInfo="server_name">
     <f:facet name="statusArea">
       <webuijsf:panelGroup id="statusPanel" separator="">
         <webuijsf:markup tag="div" styleClass="#{themeStyles.MASTHEAD_STATUS_DIV}">
         <webuijsf:notificationPhrase text="Important info goes here" />
         <webuijsf:image icon="DOT" border="0" width="20" height="1" />
         <webuijsf:jobStatus numJobs="1" />
         </webuijsf:markup>
         <webuijsf:markup tag="div" styleClass="#{themeStyles.MASTHEAD_TIME_DIV}">
         <webuijsf:timeStamp />
         </webuijsf:markup>
         <webuijsf:markup tag="div" styleClass="#{themeStyles.MASTHEAD_ALARM_DIV}">
         <webuijsf:alarmStatus numDownAlarms="0" numCriticalAlarms="1" numMajorAlarms="2" numMinorAlarms="3" />
         </webuijsf:markup>
       </webuijsf:panelGroup>
     </f:facet>
 </webuijsf:masthead>
 

Example 2: Create an equivalent of webuijsf:alarmStatus tag


<f:facet name="notificationInfo">
      <webuijsf:panelGroup id="notificationInfo">                             
          <webuijsf:image id="notificationImage" icon="ALERT_INFO_MEDIUM" align="middle"/>
          <f:verbatim>&nbsp; </f:verbatim>
          <webuijsf:hyperlink id="link1" url="#" styleClass="#{themeStyles.MASTHEAD_PROGRESS_LINK}">
          <webuijsf:staticText id="text1" styleClass="#{themeStyles.MASTHEAD_TEXT}"
         text="#{msgs.masthead_notificationText}"/>
          </webuijsf:hyperlink>
      </webuijsf:panelGroup>
  </f:facet>
orderableList

Use the webuijsf:orderableList tag to create a list with buttons that allow the items on the list to be reordered. The values for the list items are provided in the orderableList component. If you want to allow the user to add and remove list items, see the webuijsf:editableList and webuijsf:addRemove tags.

HTML Elements and Layout

The textField component renders an XHTML fragment consisting of a selectelement representing a list, an input type="hidden" element which represents the current order of the list items, two or four input type="submit" elements for the buttons, and a label element for the label. The buttons are organized using a table, and the whole component is laid out using divs.

The rendered HTML page displays a listbox with adjacent Move Up and Move Down buttons, and optionally displays Move to Top and Move to Bottom buttons.

The orderableList component renders an XHTML fragment that consists of:

  • a <select> element representing a list
  • a hidden field in an <input type="hidden"> element, which holds a string that specifies the current order of the list items
  • two or four <input type="submit"> elements for the buttons, which are organized in a <table>
  • a <label> element for the label
  • <div> elements to layout the whole component

Configuring the webuijsf:orderableList Tag

Use the list attribute to associate the component with a set of orderable items. The value of the list attribute must be a JavaServer Faces EL expression that evaluates to an array of Objects or to a java.util.List.

To allow users to select more than one item to move at a time, set multiple to true. To display buttons that can be used to move the selected items to the top and bottom of the list, set moveTopBottom to true.

To specify a label for the component, use the label attribute, or specify a label facet. To place the label above the component, set labelOnTop to true.

Facets

The orderableList component supports the facets shown in the following table.

label
Specify a custom component for the label.
readOnly Specify a custom component for displaying the value of this component when it is marked as readonly. The default is a webuijsf:staticText.
moveUpButton Specify a custom component for the button that moves items up one step.
moveDownButton Specify a custom component for the button that moves items down one step.
moveTopButton Specify a custom component for the button that moves items to the top.
moveBottomButton Specify a custom component for the button that moves items to the bottom.

Client-side JavaScript functions

The functions below must be invoked on the JavaScript object that corresponds to the orderableList. The name of this object is OrderableList_id where id is the DOM ID of the OrderableList component (the id of the outermost div with the colons replaced by underscores, e.g. OrderableList_form_taskOrder).

object.updateValue() Use this method to update the hidden field which represents the component value in any JavaScript function that changes the order of the items on the list.
object.moveUp() Moves the selected items up one step and updates the component value.
object.moveDown() Moves the selected items down one step and updates the component value.
object.moveTop() Moves the selected items to the top of the list and updates the component value.
object.moveBottom() Moves the selected items to the bottom of the list and updates the component value.
object.updateButtons() Use this method to update which buttons are selected in any JavaScript method that programmatically selects elements on the list.

Examples

Example 1: OrderableList with Move to Top and Move to Bottom Buttons

This example uses a backing bean called AutomatedTasks with a property taskList that represents a list of tasks. Users are allowed to select more than one task to move. Buttons to move the items to the top and to the bottom are shown in addition to the default Move Up and Move Down buttons.

     <webuijsf:orderableList id="taskOrder"
                       list="#{AutomatedTasks.taskList}"
                       label="Task execution order: "
                       multiple="true"
                       moveTopBottom="true"/>
 

Example 2: OrderableList with Move to Top and Move to Bottom Buttons

This example uses a backing bean called Volunteers and a property rotationOrder, which is an ordered list of objects that represent individual persons. A converter is used to derive a string representation of the person. Only the default Move Up and Move Down buttons are shown.

     <webuijsf:orderableList id="callUpOrder"
                       list="#{Volunteers.rotationOrder}"
                       label="Call Up Order:" 
                       converter="org.example.Person">
     <webuijsf:orderableList>
 
page

Use the webuijsf:page tag to indicate the beginning of the part of the JSP page that is used by the Sun Java Web UI Components. All the JSF components used in the page must be nested within the webuijsf:page tag. You must use the webuijsf:html and webuijsf:head tags first, after the opening of the webuijsf:page tag.  Then you must use either the webuijsf:body tag or the webuijsf:frameset tag.  The webuijsf:page tag takes care of generating the preamble for the HTML page.

HTML Elements and Layout

If the application is used in a portlet environment, nothing is rendered for the webuijsf:page tag but it is still necessary to include it.

If the application is used in a servlet environment, the rendered HTML will include <?xml> and <!DOCTYPE> headers. The content of the headers is determined by the webuijsf:page attributes that you specify.  Use the frameset and xhtml attributes to create the <!DOCTYPE> header that you want.  For example, if you set frameset and xhtml attributes to true, the rendered <!DOCTYPE> header will indicate XHTML Frameset, as in the following example:

<!DOCTYPE HTML 
PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">

If you set both attributes to false,  the rendered <!DOCTYPE> header will indicate HTML Transitional,  as in the following example:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

You can also use the frameset and xhtml attributes to specify  XHTML Transitional and HTML Frameset.

Client Side Javascript Functions

None.

Example

Example 1: Using the page tag appropriately in a JSP page:

<?xml version="1.0" encoding="UTF-8"?>
<jsp:root version="1.2" xmlns:f="http://java.sun.com/jsf/core" xmlns:h="http://java.sun.com/jsf/html" xmlns:jsp="http://java.sun.com/JSP/Page" xmlns:webuijsf="http://www.sun.com/web/webuijsf">
<jsp:directive.page contentType="text/html;charset=ISO-8859-1" pageEncoding="UTF-8"/>
<f:view>
  <webuijsf:page>
    <webuijsf:html>
       ......
    <
/webuijsf:html>
  </webuijsf:page>
</f:view>
pageAlert

Use the webuijsf:pageAlert tag to display a full page alert. A page alert differs from the inline alert (see webuijsf:alert) in that the content of the page that invokes the pageAlert is replaced by the alert page. An inline alert is a smaller alert that is inserted in the page that invokes the alert.

HTML Elements and Layout

A page alert consists of:

  • an icon depicting the type of alert - question, information, warning, or error
  • a page title next to the icon
  • a detailed message
  • one input component - (one text field, one text area, one checkbox, one set of radio buttons, one drop-down menu, or one scrolling list)
  • a page separator line
  • a set of page level buttons


The input field and the set of buttons are optional items, which must be specified with facets.

The following diagram shows the locations of each of the page alert areas, and the facets that are supported for specified areas.

Alert Icon (or optional pageAlertImage facet) Title text                                                                                                                
(Optional pageAlertTitle facet)
Detailed message
Optional pageAlertInput facet
Page separator (or optional pageAlertSeparator facet)
Optional pageAlertButtons facet

 

Facets

The webuijsf:pageAlert tag supports the following facets.

pageAlertTitle Specifies a custom component to use to display the title of the alert.  The title for a full page alert consists of both an alert icon image and the title text. The default image and the formatting of the title are designed to adhere to Sun UI guidelines.  Use the pageAlertTitle facet to replace the default alert icon and title with another component. This facet overrides the title and type attributes.  Note that you can define a different image by using the pageAlertImage facet. 
pageAlertImage
Specifies a component to use to display the alert icon. The component included in this facet replaces the default icon.
pageAlertInput Specifies a component to use in the body of the full page alert. This facet can be used to display an input component for the user to perform tasks related to the alert, for example.
pageAlertButtons Specifies components to use for the buttons at the bottom of the alert page. This facet can be used to display a back button, for example. If you want to specify more than one button, you might find it helpful to enclose the button components in a webuijsf:panelGroup component.
pageAlertSeparator
Specifies a component to use for the page separator that is displayed above the page buttons. The component included in this facet replaces the default page separator.

Client Side Javascript Functions

None.

Examples

Example 1:  Simple example, with alert message and a back button.

	<webuijsf:pageAlert id="pagealert" title="Error!" type="error"
detail="The server jurassic is not responding. Verify that the power cable is connected.">
<f:facet name="pageAlertButtons">
<webuijsf:button text="Back" actionExpression="indexPage" />
</f:facet>
</webuijsf:pageAlert>

Example 2: With input field and one page button.

	<webuijsf:pageAlert id="pagealert" title="Password Expired!" type="warning"
detail="Your password has expired. Enter a new password">
<f:facet name="pageAlertButtons">
<webuijsf:button text="Go to Login Page" actionExpression="success" />
</f:facet>
<f:facet name="pageAlertInput">
<webuijsf:panelGroup id="pageAlertStuff">
<webuijsf:label text="New Password:" for="passwordField"/>
<webuijsf:passwordField id="passwordField" />
</webuijsf:panelGroup>
</f:facet>
</webuijsf:pageAlert>
pageSeparator

Use the webuijsf:pageSeparator tag to create a horizontal line that separates items on the page.  The tag can be used as a standalone tag to insert a new horizontal line in a page, or used within the facet of another tag to override a default page separator.  For example, the webuijsf:pageSeparator tag can be used in the webuijsf:pageAlert tag's pageAlertSeparator facet.

HTML Elements and Layout

This tag renders a horizontal line inside an HTML table that will size according to the size of the page.

Theme Identifiers

TBD

Client Side Javascript Functions

None.

Example

Example 1: Using a standalone webuijsf:pageSeparator tag
<?xml version="1.0" encoding="UTF-8"?>
<jsp:root version="1.2" xmlns:f="http://java.sun.com/jsf/core" xmlns:h="http://java.sun.com/jsf/html" xmlns:jsp="http://java.sun.com/JSP/Page" xmlns:webuijsf="http://www.sun.com/webui/webuijsf">
    <jsp:directive.page contentType="text/html;charset=ISO-8859-1" pageEncoding="UTF-8"/><f:view>
        <webuijsf:page frame="true">
            <webuijsf:html>
                <webuijsf:head title="blah" />
                <webuijsf:body>
                   <webuijsf:pageSeparator id="mypageseparator" />
                </webuijsf:body>
            </webuijsf:html>
        </webuijsf:page>
    </f:view>
</jsp:root>


panelGroup

Use the webuijsf:panelGroup tag to display a group of components that are separated by a common separator. This is often useful for providing a consistently formatted layout of a group of components.

HTML Elements and Layout

The PanelGroup component defines and renders a group of components. The group of components are defined in the body of thewebuijsf:panelGroup tag, or by specifying children of the PanelGroup component. The child components do not have to be of like type. The separator is defined by the separator property, or the separator facet. The separator may be an empty string, a space, text / character(s), markup, or a component defined by the separator facet.

By default the PanelGroup component is rendered with a<span> surrounding the group of child components. This may be changed to a <div> by setting theblock property to true.

PanelGroup is a NamingContainer.

Theme Identifiers

Not Applicable

Client Side Javascript Functions

Not Applicable

Examples:

Example 1: Simple example showing 4 buttons using the default separator (a return character).

<webuijsf:panelGroup id="myPanelGroup1">
    <webuijsf:button id="button1" text="Button 1" />
    <webuijsf:button id="button2" text="Button 2" />
    <webuijsf:button id="button3" text="Button 3" />
    <webuijsf:button id="button4" text="Button 4" />
</webuijsf:panelGroup>

Example 2: Same example except using the separator attribute to specify '|' (pipe) as the separator.

<webuijsf:panelGroup id="myPanelGroup2" separator=" | ">
    <webuijsf:button id="button1" text="Button 1" />
    <webuijsf:button id="button2" text="Button 2" />
    <webuijsf:button id="button3" text="Button 3" />
    <webuijsf:button id="button4" text="Button 4" />
</webuijsf:panelGroup>

Example 3: Same example except using the separator facet to specify the separator. This example also demonstrates theblock property.

<webuijsf:panelGroup id="myPanelGroup3" block="true">
    <facet name="separator">
        <h:outputText value="==" />
    </f:facet>
    <webuijsf:button id="button1" text="Button 1" />
    <webuijsf:button id="button2" text="Button 2" />
    <webuijsf:button id="button3" text="Button 3" />
    <webuijsf:button id="button4" text="Button 4" />
</webuijsf:panelGroup>
panelLayout

Use the webuijsf:panelLayout tag to display a group of components that are related, in either flow layout, or using absolute positioning. This tag is often useful for providing a consistently formatted layout of a group of components.

passwordField

Use the webuijsf:passwordField tag to create an input field where the characters entered are echoed back with a replacement character, so as to mask the input. PasswordField can be bound to the server side expressions, but for the security purposes it will never render server-side data as part of the field but will display empty field instead.

HTML Elements and Layout

PasswordField inherits most of the functionality(with the exception of refresh, submit and autoValidate) and attributes from TextField. See webuijsf:textField component description for details and examples.

Configuring the webuijsf:passwordField Tag

See webuijsf:textField component description for additional details and examples. With the exception for refresh, submit and autoValidate, all of the usage and attribute examples for textField can be used with editField by replacing tag into webuijsf:textField .

Client Side Javascript Functions

When the component is rendered, a DOM object corresponding to the component is created. To manipulate the component on the client side, you may invoke functions on the DOM object. With reference to the DOM id, to disable the component, invoke document.getElementById(id).setProps({disabled: true}).

getInputElement() Use this function to access the HTML <input> element that is rendered by the component.
getProps() Use this function to get widget properties. Please see setProps() function for a list of supported properties.
setProps(props) Use this function to change any of the following supported properties:
  • accesskey
  • autoSave
  • className
  • dir
  • disabled
  • id
  • label
  • lang
  • onClick
  • onDblClick
  • onFocus
  • onKeyDown
  • onKeyPress
  • onKeyUp
  • onMouseDown
  • onMouseMove
  • onMouseOut
  • onMouseOver
  • onMouseUp
  • readOnly
  • required
  • size
  • style
  • tabIndex
  • title
  • valid
  • value
  • visible
subscribe(topic, obj, func) Use this function to subscribe to an event topic.
  • topic: The event topic to subscribe to.
  • obj: The object in which a function will be invoked, or null for default scope.
  • func The name of a function in context, or a function reference to invoke when topic is published.


Examples

Example 1: Update client-side editableField properties using the getProps and setProps functions

This example shows how to toggle the disabled state of a editable field client side using the getProps and setProps functions. When the user clicks the radio button, the text field is either disabled or enabled.
<webuijsf:radioButton id="rb1" name="rb1" label="Toggle Field Disabled" onClick="toggleDisabled()"/>
<webuijsf:passwordField id="field1" text="My Text Field" />

<webuijsf:script>
function toggleDisabled() {
var domNode = document.getElementById("form1:field1"); // Get field
return domNode.setProps({disabled: !domNode.getProps().disabled}); // Toggle disabled state
}
</webuijsf:script>
progressBar

Use the webuijsf:progressBar to render a progress indicator that provides user feedback about a task or job in progress. 

The Progress Bar component supports the following types of progress indicators:

  • Determinate -- An animated horizontal bar used to show the percentage of the task that has been completed.

  • Indeterminate -- An animated horizontal bar used to show that a task is progressing, when it is not possible to determine the task completion percentage.

  • Busy -- A smaller animation used to indicate activity for events that cannot be synchronized to the backend process, and where space is constrained.

The progress bars can include details such as a description and status of the operation, and controls such as Pause, Resume, and Cancel buttons for controlling the running of the task. 

HTML Elements and Layout

In the rendered HTML page, the progress bar is created with <div> elements and JavaScript functions.

The progress bar component consists of  the dynamic graphical progress animation, and the following optional areas:

  • Description, used to describe the overall operation being monitored.
  • Customizable control elements that can be used to add buttons or other controls for managing the task.
  • Status message to display dynamic text that describes the current state of the operation.
  • Log message text area that can be used to display log messages.
The following diagram shows the location of each area of the progressBar component, and the attributes and facets that can be used for each area.

Description (description attribute or progressTextTop facet)
Progress animation (type attribute)
Controls (progressControlRight facet)
Status message (status attribute or progressTextBottom facet)
Controls (progressControlBottom facet)
Log message (logMessage attribute)

Configuring the webuijsf:progressBar tag

By default, the webuijsf:progressBar renders a determinate type progress bar with a refresh rate of 3 seconds. You can use the type attribute to specify one of the indicators DETERMINATE, INDETERMINATE, or BUSY to determine the kind of progress indicator to render.  You can add elements to the basic progress indicator by using the attributes and facets shown in the diagram, and customize other aspects of the components behavior with a few other attributes (described later in this document). 

The component doesn't display any buttons by default. To include buttons, you must use the progressControlRight or progressControlBottom facet. The progressBar component provides JavaScript functions for the control elements that you can call to control the underlying task on the back end.

You can further customize the component with some additional attributes:

  • The progress attribute value can be bound to data that updates as the task progresses, and should resolve to an integer value that indicates the percentage of task completion.
  • The status attribute can be bound to data that updates as the task progresses, and should reflect the current status; for example, the status could be a string used to indicate the percent completed or time remaining.

  • The taskState attribute is used to specify the state of the task.  For example, if the task fails, the taskState would be set to failed. The taskState attribute supports several values, which are listed in the attribute descriptions later in this document.   Note that in the Examples section, the taskState value is used in the backing bean to determine the value of the status attribute, but is not used as a tag attribute in the webuijsf:progressBar tag.  
  • The refreshRate attribute is used to specify the number of milliseconds between updates of the animation through Ajax.  The default rate is 3000 milliseconds.
  • The overlayAnimation attribute is used to render the percentage completion text on a determinate progress bar, instead of on a line below the progress bar.  This technique is useful  in tables, for example, or other locations where space is limited. 
  • The progressImageUrl attribute is used to specify a different animated image to be used for the progress bar.  This image must be an animated GIF.

  • The ajaxify attribute is true by default, to enable the asynchronous JavaScript capabilities of the component, which are responsible for implementing its dynamic behavior. When the default Ajax functionality is added to the page, it will automatically subscribe to an event that is published according to the specified refreshRate.  When the event is received, an Ajax request is generated using the DynaFaces JavaScript library. This same implementation will also listen for the Ajax response. When the response is returned, the progress bar is updated as needed.  Set ajaxify to false if you want to provide your own implementation of Ajax behavior.

Facets

The webuijsf:progressBar tag supports the following facets, which can be used to define the specified areas.

Facet Name
Area of Progress Bar
progressTextTop Descriptive text displayed at the top of the progress bar.
progressTextBottom Status text displayed at the bottom of the progress bar.
progressControlRight Control elements displayed to the right side of the progress bar.
progressControlBottom Control elements displayed at the bottom of the progress bar.

Client Side Javascript Functions

When the progressBar component is rendered, a DOM object corresponding to the progressBar component is created. To manipulate the progressBar component on the client side, you may call functions on the DOM object. With reference to the DOM ID, to disable the component, call document.getElementById(id).setProps({disabled: true}).

JavaScript Function Description
cancel() Handles the Cancel button event.
getProps() Use this function to get widget properties. Please see setProps() function for a list of supported properties.
isBottomControlVisible() Tests the controls area on the bottom, if it was hidden.
isFailedStateMessageVisible() Tests the area for the icon and message indicating a failed state, if it was hidden.
isLogMsgVisible() Tests the log message area, if it was hidden.
isOperationTextVisible() Tests the description of the operation that is being monitored.
isProgressBarContainerVisible() Tests if the progress bar container if it was hidden.
isProgressBarVisible() Tests if the progress bar if it was hidden.
isRightControlVisible() Tests the controls area on the right side, if it was hidden.
isStatusTextVisible() Tests the status message area, if it was hidden.
pause() Handles the Pause button event.
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. If omitted, no other components are executed.
resume() Handles the Resume button event.
setOnCancel() Invokes a developer-defined function for the Cancel button event.
setOnComplete() Invokes a developer-defined function that handles the event for task completion.
setOnFail() Invokes a developer-defined function that handles the event for task failure.
setBottomControlVisible() Displays the controls area that displays on the bottom of the component.
setFailedStateMessageVisible() Displays the area that displays the icon and message indicating a failed state.
setLogMsgVisible() Displays the log message area.
setOperationTextVisible() Displays the description of the operation that is being monitored.
setProgressBarContainerVisible() Displays the progress bar container.
setProgressBarVisible() Hides the progress bar.
setProps(props) Use this function to change any of the following supported properties:
  • accesskey
  • align
  • className
  • dir
  • disabled
  • escape
  • id
  • icon
  • lang
  • mini
  • onBlur
  • onChange
  • onClick
  • onDblClick
  • onFocus
  • onKeyDown
  • onKeyPress
  • onKeyUp
  • onMouseDown
  • onMouseMove
  • onMouseOut
  • onMouseOver
  • onMouseUp
  • primary
  • src
  • style
  • tabIndex
  • title
  • value
  • visible
setRightControlVisible() Displays the controls area that displays on the right side of the component.
setStatusTextVisible() Displays the status message area.
stop() Handles the Stop button event.
subscribe(topic, obj, func) Use this function to subscribe to an event topic.
  • topic: The event topic to subscribe to.
  • obj: The object in which a function will be invoked, or null for default scope.
  • func The name of a function in context, or a function reference to invoke when topic is published.

Client-Side JavaScript Events

When the component is manipulated on the client side, some functions might publish event topics for custom AJAX implementations to listen for. For example, you can listen for the refresh event topic by using:

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

    // Subscribe to refresh event.
    domNode.subscribe(domNode.event.refresh.endTopic, processEvents, "update");


</webuijsf:script>

The following events are supported.

Event Description
<Node>.event.refresh.beginTopic Event topic published before asynchronously refreshing the component. 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
<Node>.event.refresh.endTopic Event topic published after asynchronously refreshing the component. Supported properties include: setProps() function.
  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage

Examples

Example 1:  Simple Determinate Progress Bar with Control Buttons and Log Message

This example creates a determinate type progress bar with Pause, Resume, and Cancel buttons, which are defined with the progressControlBottom facet, at the bottom of the progress bar. The component also displays a text area for log messages because the logMessage attribute is specified.

The buttons are set up to call various JavaScript functions of the progressBar component when clicked:  resume(), pause() , stop(), cancel(). For example, the Resume button calls: document.getElementById(component id).resume(); 

Notereturn false; is called on all control elements in order to prevent page submission when the controls are clicked.  Also, notice that the Pause and Resume buttons are enabled and disabled through JavaScript when the buttons are clicked.

See also the ProgressBean.java backing bean used with this example.

<webuijsf:progressBar type="DETERMINATE" id="pb1" progress="#{ProgressBean.progressRate}"
                      refreshRate="2000"
                      description="Progress Bar 1 with Log Message"
                      status="#{ProgressBean.status}"
                      logMessage="#{ProgressBean.logMsg}!!"> 

                      <f:facet name="progressControlBottom">
                              <webuijsf:panelGroup id="statusPanel" separator="">
                                <webuijsf:button mini="true" id="pauseButton" text="Pause"
                                   onClick="document.getElementById('form1:statusPanel:resumeButton').disabled=false;
                                   this.disabled=true;document.getElementById('form1:pb1').pause();return false;"  />
                                <webuijsf:button mini="true" id="resumeButton" text="Resume"
                                   onClick="document.getElementById('form1:statusPanel:pauseButton').disabled=false;
                                   this.disabled=true;document.getElementById('form1:pb1').resume();return false;"  />
                              <webuijsf:button mini="true" id="cancelButton" text="Cancel"
                                   onClick="document.getElementById('form1:pb1').cancel();return false;" />
                             </webuijsf:panelGroup>
                     </f:facet>
 
</webuijsf:progressBar>


Example 2:   Indeterminate Progress Bar

This example shows how to create a simple indeterminate progress bar, an animated horizontal bar without a completion percentage.  The example shows a description and the buttons Pause, Resume, and Cancel.

<webuijsf:progressBar type="INDETERMINATE" id="pb2"
                      refreshRate="3000"
                      description="Indeterminate Type ProgressBar" >
                     
                     <f:facet name="progressControlRight">
                         <webuijsf:panelGroup id="statusPanel" separator="">
                             <webuijsf:button mini="true" id="pauseButton" text="Pause"
                                      onClick="document.getElementById('form1:statusPanel:resumeButton').disabled=false;
                                      this.disabled=true;document.getElementById('form1:pb2').pause();return false;"  />
                             <webuijsf:button mini="true" id="resumeButton" text="Resume"
                                      onClick="document.getElementById('form1:statusPanel:pauseButton').disabled=false;
                                      this.disabled=true;document.getElementById('form1:pb2').resume();return false;"  /> 
                             <webuijsf:button mini="true" id="cancelButton" text="Cancel"
                                      onClick="document.getElementById('form1:pb2').cancel();return false;" />
                         </webuijsf:panelGroup>
                    </f:facet>
</webuijsf:progressBar>

 

Example 3: Busy Progress Bar

This example creates a simple Busy progress indicator.  Although this example does not show it, you can specify a description, status message, log message in a Busy progress indicator. 

<webuijsf:progressBar type="BUSY" id="pb3"
                      refreshRate="3000"
</webuijsf:progressBar>

Example 4: Overlay Animation Progress Bar 

This example creates a determinate progress bar with overlay animation, in which the percentage complete is displayed within the progress bar.  This technique is often used in tight spaces, where the size of the indicator must be kept to a minimum. However, you can also use the overlay animation when you use a more expansive progress bar with a description, status, log message, and control buttons.
See also the ProgressBean.java backing bean.

<webuijsf:progressBar type="DETERMINATE" id="pb5" 
progress="#{ProgressBean.progressRate}"
refreshRate="2000"
overlayAnimation="true" >
</webuijsf:progressBar>

Backing Bean for Examples

The ProgressBean.java backing bean is used the examples above.

ProgressBean.java

This backing bean is used in Example 1 and Example 4

/*
 * ProgressBean.java
 */

package progressbar;

import com.sun.webui.jsf.component.ProgressBar;
import javax.faces.component.UIComponent;
import javax.faces.context.FacesContext;


public class ProgressBean2 {
    
    private int progressRate = 0;
    
    private String status = "0% complete";
    
    /** Creates a new instance of ProgressBean */
    public ProgressBean2() {
        
    }
    
    public int getProgressRate() {
        
        String task = "";
        if (getComponentInstance() != null)
            task = getComponentInstance().getTaskState();
        
        if(task != null) {
            if (task.equals(ProgressBar.TASK_PAUSED)) {
                status = "Task Paused ...";
                return progressRate;
                
            }
            if (task.equals(ProgressBar.TASK_CANCELED)) {
                status = "Task Canceled ..";
                return progressRate;
            }
        }
        
        progressRate = progressRate + 3;
        status = progressRate + "% complete";
        
        if (progressRate > 99) {
            progressRate = 100;
        }
        
        if (progressRate == 100) {
            
            getComponentInstance().setTaskState(ProgressBar.TASK_COMPLETED);
            status = "Task Completed successfully ..";
        }
        
        return progressRate;
    }
    
    
    public String getStatus() {
        
        return status;
    }
    
    public ProgressBar getComponentInstance() {
        FacesContext context = FacesContext.getCurrentInstance();
        UIComponent comp = context.getViewRoot().findComponent("form1:pb2");
        ProgressBar pb = (ProgressBar) comp;
        
        return pb;
    }
    
    public String action() {
        getComponentInstance().setTaskState(ProgressBar.TASK_NOT_STARTED);
        progressRate = 0;
        status = "";
        return "progressbar";
    }   
}

Example 5: Update Client-Side ProgressBar Properties Using the getProps and setProps functions

This example shows how to toggle the visible state of a progress bar client side using the getProps and setProps functions. When the user clicks the button, the progress bar is either shown or hidden.

<webuijsf:progressBar type="BUSY" id="pb1"/>
<webuijsf:button id="button1" text="Hide Progress Bar" onClick="hideProgressBar()"/>

<script type="text/javascript">
    function hideProgressBar() {
        var domNode = document.getElementById("pb1");
        var props = domNode.getProps();
        if (domNode != null) {
            domNode.setProps({"visible":!props.visible});
        }
    }
</script>

Example 6: Asynchronously Update ProgressBar Using refresh function

This example shows how to asynchronously update an anchor using the refresh function. When the user clicks on the button, the progress bar is asynchronously updated with new data.
<webuijsf:progressBar type="BUSY" id="pb1" description="#{MyBean.text}"/>
<webuijsf:button id="button1" text="#{MyBean.text}" onClick="refreshProgressBar();return false;"/>
<webuijsf:script>
    function refreshProgressBar() {
        var domNode = document.getElementById("form1:pb1"); // Get progress bar
        return domNode.refresh(); // Asynchronously refresh progress bar
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,..."). When no parameter is given, the refresh function acts as a reset. That is, the component will be redrawn using values set server-side, but not updated.

Example 7: Asynchronously Update ProgressBar Using refresh function

This example shows how to asynchronously update a progress bar using the refresh function. The execute property of the refresh function is used to define the client id which is to be submitted and updated server-side. As the user types in the text field, the input value is updated server-side and the progress bar is updated client-side -- all without a page refresh.
<webuijsf:progressBar type="BUSY" id="pb1" description="#{MyBean.text}"/>
<webuijsf:textField id="field1" text="#{MyBean.text}" label="Change Progress Bar Description"
onKeyPress="setTimeout('refreshProgressBar();', 0);"/> // Field used to asynchronously update text.
<webuijsf:script>
    function refreshProgressBar() {
        var domNode = document.getElementById("form1:pb1"); // Get progress bar

        return domNode.refresh("form1:field1"); // Asynchronously refresh while submitting field value
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of IDs can be provided to update components server-side: refresh("form1:id1,form2:id2,...")

property

Use the webuijsf:property tag inside the webuijsf:propertySheetSection tag to lay out a property in a webuijsf:propertySheet. The webuijsf:property tag allows you to encapsulate a logical property and help you lay it out on the page.

HTML Elements and Layout

The properties in a property sheet are rendered as rows in a two-column table by default. The content of each webuijsf:property tag is rendered as one row. The first column is reserved for the property label, which can be specified with either the webuijsf:property tag's label attribute or the label facet. The label facet provides more control over the content of the label area.

The second column is the content area, which contains the components that are specified as the content of the webuijsf:property tag. Each webuijsf:property tag can include multiple tags for UI components such as webuijsf:textField, webuijsf:dropdown, webuijsf:checkbox, or any other component. You can label these content components by using their label attributes or the webuijsf:label tag. These labels are displayed within the content area.

The tags for a property's content can be specified as child tags of the webuijsf:property tag, or enclosed in the webuijsf:property tag's content facet. There is no rendering difference between the two approaches.

Help text can be provided for each property with the webuijsf:property tag's helpText attribute. The help text is displayed below the content of the property in smaller text. If you want more control over the type of content provided in the help text area, you can use the helpText facet.

Several attributes can be used to change the formatting of the property label:

  • overlapLabel can be used to overwrite the label area with an expanded content area. If a property label is specified when this attribute is set to true, the label is not rendered.
  • labelAlign can be used to align the label to the left or right of the label column. For example, labelAlign="right" aligns the property label to the right side of the column, close to the content area.
  • noWrap can be used to prevent the label text from wrapping to a new line

The attributes are described in greater detail in the list of attributes below.

Facets

The webuijsf:property tag supports the facets described below.

content
Specifies the components to include for the content of the property component. The content facet is not required, and the components can be specified as child tags. However, if both child components and the content facet are supplied, only the content facet content is displayed.
label
Specifies the component and content to use for the label, overriding the label attribute.
helpText
Specifies the component and content to use for the help text, overriding the helpText attribute.

Client Side Javascript Functions

None.

Examples

Example 1: Content Specified with Child Tags

The label is specified via the label attribute. The components of the content area are specified as children of the webuijsf:property tag.

 
   <webuijsf:property id="prop1" label="Log file name: ">           
       <webuijsf:textField id="logfile" required="true"/>
       <h:message id="logfile_error" for="logfile" showDetail="true"/> 
   </webuijsf:property>

Example 2: Using the Label Facet

The components of the content area are specified as children of the webuijsf:property tag. The label is specified via a label facet, to label the dropDown in the content area.

            
   <webuijsf:property id="prop2">    
       <f:facet name="label">
           <webuijsf:label id="prop2label" 
                     text="Select update frequency"
                     for="unit"/>
       </f:facet>   
       <webuijsf:textField id="frequency" 
                     text="#{Logger.frequency.number}"
                     label="Every "/>
       <webuijsf:dropDown id="unit" 
                    selected="#{Logger.frequency.unit}"  
                    items="#{Logger.frequency.units}"  
                    required="true"/>
       <h:message id="msg1"_msg4b" for="frequency" showDetail="true"/> 
       <h:message id="msg2" for="unit" showDetail="true"/> 
   </webuijsf:property>

Example 3: Using webuijsf:panelGroup for Content Component Layout

The components of the content area are specified inside a PanelGroup child component.

 
   <webuijsf:property id="prop3" label="Admin Server URI"> 
       <webuijsf:panelGroup id="pg">
           <webuijsf:textField id="uri" text="#{Server.uri}" required="true"/>
           <h:message id="msg3" for="uri" showDetail="true"/> 
       </webuijsf:panelGroup>                               
   </webuijsf:property>

Example 4: Using the content Facet

The components of the content area are specified inside a PanelGroup inside a facet.

 
   <webuijsf:property id="prop3" label="Admin Server URI"> 
       <f:facet name="content">
           <webuijsf:panelGroup id="pg">
               <webuijsf:textField id="uri" text="#{Server.uri}" required="true"/>
               <h:message id="msg3" for="uri" showDetail="true"/> 
           </webuijsf:panelGroup>                               
       </f:facet>                       
   </webuijsf:property>

propertySheet

Use the webuijsf:propertySheet tag to create a layout container for a property sheet. A property sheet is a content page that shows an object's properties and allows the user to edit the properties.

The webuijsf:propertySheet tag is a naming container for webuijsf:propertySheetSection tags. The webuijsf:propertySheetSection tag is a container for code>webuijsf:property tags, which define properties to be displayed with input or read-only components. The three property sheet tags are used to construct a property sheet that has a defined layout with sections.

A property sheet should contain one webuijsf:propertySheet tag and one or more webuijsf:propertSheetSection tags, each containing any number of webuijsf:property tags.

You might find it useful to place the webuijsf:propertySheet tag within the webuijsf:contentPageTitle tag to include a title and page controls for the property sheet.

HTML Elements and Layout

The propertySheet component functions mostly as a container and is rendered with an XHTML <div> element. The component can also be configured to render <a> hyperlink elements to create jump links in the page by setting the webuijsf:propertySheet tag's jumpLinks attribute to true. The links provide a quick way for the user to jump to each section in the page. The text of the jump links includes the section label text, if specified in the webuijsf:propertySheetSection tags. Additional links for jumping back to the top of the page are rendered at the end of each section.

Client Side Javascript Functions

None.

Examples

Example 1: A simple property sheet that contains two property sheet sections

This example shows a property sheet with jump links and a required field legend.

	<webuijsf:propertySheet id="propSheetExample1" jumpLinks="true" requiredFields="true" >
	    <webuijsf:propertySheetSection id="firstSection" label="Search Criteria">
		<webuijsf:property id="Property1" label="Instance Name: " labelAlign="right" noWrap="true" overlapLabel="false">
		    <webuijsf:dropDown id="servers" required="true" items="#{BackingFileChoice.servers}" />
		    <f:verbatim>&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;</f:verbatim>
		    <webuijsf:label id="logFileLabel" labelLevel="2" text="Log File: " />
		    <webuijsf:dropDown id="logFile" items="#{BackingFileChoice.archivedLogFiles}" />
		</webuijsf:property>
		<webuijsf:property id="Property2" label="Log Level: " labelAlign="right" noWrap="true" overlapLabel="false" helpText="#{bundle.['log.level.help']}">
		    <f:facet name="content">
			<webuijsf:dropDown id="logLevel" items="#{BackingFileChoice.logLevel}" />
		    </f:facet>
		</webuijsf:property>
	    </webuijsf:propertySheetSection>
	    <webuijsf:propertySheetSection id="secondSection" label="Advanced Options">
		<webuijsf:property id="Property3" label="Logger: " labelAlign="right" noWrap="true" overlapLabel="false" helpText="Select one or more module logs to view">
		    <webuijsf:listbox id="logger" items="#{BackingFileChoice.loggers}" rows="5" />
		</webuijsf:property>
		<webuijsf:property id="Property4" noWrap="true" overlapLabel="false" helpText="Select one or more module logs to view">
		    <webuijsf:checkbox id="limitLongLogs" label="Limit excessively long messages" />
		</webuijsf:property>
	    </webuijsf:propertySheetSection>
	</webuijsf:propertySheet>
    

propertySheetSection

Use the webuijsf:propertySheetSection tag to create a section in a property sheet. The webuijsf:propertySheetSection tag must be contained in a webuijsf:propertySheet tag. You can place webuijsf:property tags inside the webuijsf:propertySheetSection tag to create the property page content.

The webuijsf:propertySheetSection tag allows you to group related properties together on a property page. Note that you must include at least one webuijsf:propertySheetSection tag in the webuijsf:propertySheet tag, even if the page is a single section.

HTML Elements and Layout

The propertySheetSection component functions as a container for the property components and is rendered with XHTML <div> components. You can provide a descriptive label for the section by setting the webuijsf:propertySheetSection tag's label attribute. The label is displayed at the beginning of the section in the rendered HTML page.

Note that although the label is optional, the label text is used for hyperlink text when you configure the webuijsf:propertySheet tag to create jump links. If you do not provide labels for the sections, the text for the jump links does not properly indicate the link's target to the user.

Client Side Javascript Functions

None.

Examples

See the example in the webuijsf:propertySheet documentation.

radioButton

Use the webuijsf:radioButton tag to display a radio button in the rendered HTML page. The tag can be used as a single radio button or as one radio button among a group of radio buttons. A group of radio buttons represents a single selection list. A radio button can represent a value of a class type such as Boolean, Byte, Character, Double, Float, Integer, Long, Short, String or the primitive form of one of these class types. A radio button may also represent an application defined object value.

A Boolean value is useful for indicating whether an item, such as a table row, is selected. A String value is useful for passing a value for the radio button selection made in the interface. An application defined Object value or class instance can be used to hold more information related to the radio button selection.

A group of radio buttons is the common way to use the the radioButton tag. It can be used to represent different types of data:

  • a group of boolean controls where only one control is selected at a time.
  • string values that are related to the radio button selection
  • object values defined by the application

Note: It is not common to use a radioButton tag that is not in a group. If a single radio button is not in a group, once it is selected by the user in the interface, the user cannot deselect it. This is because a radio button is defined to be a single selection among several where one radio button is always selected. Since there are no other radio buttons grouped with the single radio button, the user cannot select an alternative, to cause the selected radio button to be deselected.

Note: Another tag for rendering radio buttons is webuijsf:radioButtonGroup, which imposes a grid layout on a group of radio buttons. The radioButton tag is useful in situations where the radioButtonGroup tag layout is not desirable, such as in a table row where only one row among several may be selected.

Detecting a selected radio button

The radioButton tag uses both the selected and selectedValue attributes to pass information about the radio button's selection status. The selected attribute is used to indicate that the radio button is selected, and should have a check mark displayed in the page. The selectedValue attribute is used to pass a data value for the radio button. A radio button is considered to be selected when the value of the selected attribute is equal to the value of the selectedValue attribute. You can display a radio button as selected on the initial viewing of the page by assigning the same value to the selectedValue and the selected attributes.

If the selectedValue attribute is not specified or its value is null then the radio button behaves like a boolean control. If the radio button is selected, the value of the selected attribute is a true Boolean instance. If the radio button is not selected, the value of the selected attribute will be a false Boolean instance.

Note that a value binding expression that evaluates to a primitive boolean value can be assigned to the selected and selectedValue attributes.

When a radio button is part of a group, the value of the selected radio button is maintained as a request attribute value in the RequestMap. The attribute name is the value of the name attribute. The value of the request attribute is the value of the selectedValue attribute of the selected radio button. The value of the selected attribute will also be equal to the selectedValue attribute of the selected radio button. If no radio button is selected, no request attribute will be created.
The RadioButton class provides a convenience method for obtaining the selected radio button in a group:

public static Object getSelected(String groupName);

where groupName is the value of the name attribtue. Note that unlike the selected and selectedValue attributes, the return value of this method is always a class instance and not a primitive value.

Note that the radioButton does not enforce that at least one radio button is always be selected. The application must ensure this behavior if necessary.

Using a radioButton tag as a boolean control

If the selectedValue attribute is not specified or its value is null then the radio button behaves like a boolean control.

To use the radioButton tag as a boolean control, do not specify a value for the selectedValue attribute. The radio button is selected if the selected attribute is not null and has the value of a true Boolean instance or boolean primitive. If the radio button is not selected, then the value of the selected attribute is a false Boolean instance or boolean primitive.

Normally the value of the selectedValue attribute is specified as the value of the <input> HTML element. When a radio button is behaving as a boolean control the value of the <input> element is the clientId of the radio button.

Note that using a boolean radio button in a group and referencing the request attribute for the selected radio button is not useful, since the value of the request attribute will be an indistinguishable Boolean true value.

Using a radioButton tag to represent an application defined value

The selectedValue attribute can be assigned an application defined object value to represent the value of a selected radio button. If the radio button is selected, the value of the selected attribute is assigned the value of the selectedValue attribute.

If the value of the selectedValue attribute is an application defined object, a converter must be registered to convert to and from a String value. The converter is used to encode the radio button value as the value of the HTML <input> element and to decode the submitted value in a request. In addition the object must support an equals method that returns true when the value of the selectedValue attribute is compared to the selected attribute value in order to detect a selected radio button.

Using a radioButton tag as one control in a group

The name attribute determines whether a radio button is part of a group. A radio button is treated as part of a group of radio buttons if the name attribute of the radio button is assigned a value equal to the name attribute of the other radio buttons in the group. In other words, all radio buttons of a group have the same name attribute value. The group behaves like a single selection list, where only one radio button can be selected. The value of the name attribute must be unique within the scope of the <form> element containing the radio buttons.

Facets

The following facets are supported:

  • image If the image facet exists, it is rendered to the immediate right hand side of the radio button.
  • label If the label facet exists, it is rendered to the immediate right of the image, or to the immediate right of the radio button if no image is rendered.

HTML Elements and Layout

A radioButton is rendered as at least one HTML <span> element and one <input> element of type radio. Each radio button may consist of the following elements:

  • a <span> element
  • an <input> element of type radio
  • an optional image if the imageURL attribute or an image facet is specified. If the imageURL attribute is specified a com.sun.webui.jsf.component.ImageComponent component is created and rendered. If an image facet is specified then the component specified by the facet is rendered.
  • an optional label if a label attribute or a label facet is specified. If the label attribute is specified a com.sun.webui.jsf.component.Label component is created and rendered. If a label facet is specified then the component specified by the facet is rendered.

The id attributes for HTML elements are constructed as follows, where rid is the clientId of the component being rendered.

  • rid_span for the <span> element
  • rid for the <input element
  • rid_image for the image component if created.
  • rid_label for the label component if created.

Note that the value of the style and styleClass attributes of a radio button will be assigned to the containing <span> HTML element's style and class attributes respectively.

Theme Identifiers

  • Rb for the INPUT element
  • RbDis for the INPUT element for disabled radio button
  • RbLbl for a LABEL element of a radio button
  • RbLblDis for a LABEL element of a disabled radio button
  • RbImg for an IMG element of a radio button
  • RbImgDis for an IMG element of a disabled radio button
  • Client Side Javascript Functions

    When the component is rendered, a DOM object corresponding to the component is created. To manipulate the component on the client side, you may invoke functions on the DOM object. With reference to the DOM id, to disable the component, invoke document.getElementById(id).setProps({disabled: true}).

    getInputElement() Use this function to access the HTML <input> element that is rendered by the component.
    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. If omitted, no other components are executed.
    setProps(props) Use this function to change any of the following supported properties:
    • accesskey
    • align
    • checked
    • className
    • dir
    • disabled
    • id
    • image
    • label
    • lang
    • name
    • onBlur
    • onChange
    • onClick
    • onFocus
    • onKeyDown
    • onKeyPress
    • onKeyUp
    • onMouseDown
    • onMouseMove
    • onMouseOut
    • onMouseOver
    • onMouseUp
    • onSelect
    • readOnly
    • style
    • tabIndex
    • title
    • value
    • 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.
    subscribe(topic, obj, func) Use this function to subscribe to an event topic.
    • topic: The event topic to subscribe to.
    • obj: The object in which a function will be invoked, or null for default scope.
    • func The name of a function in context, or a function reference to invoke when topic is published.

    Client Side JavaScript Events

    When the component is manipulated client side, some functions may publish event topics for custom AJAX implementations to listen for. For example, you can listen for the refresh event topic using:

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

        // Subscribe to refresh event.
        var domNode = document.getElementById("form1:test1");
        domNode.subscribe(domNode.event.refresh.endTopic, processEvents, "update");


    </webuijsf:script>

    The following events are supported.

    <Node>.event.refresh.beginTopic Event topic published before asynchronously refreshing the component. 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
    <Node>.event.refresh.endTopic Event topic published after asynchronously refreshing the component. Supported properties include: See setProps() function.
    • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage
    <Node>.event.submit.beginTopic Event topic published before asynchronously submitting the component. 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
    <Node>.event.submit.endTopic

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

    • props - JSON object containing messages (if any) raised by the server.In particular, valdiation messages will be present here if validation failed

    Examples

    Example 1: Two grouped boolean radio buttons with value bindings

    <webuijsf:radioButton id="rb0" name="rb1grp" selected="#{tldRbCbExample.selectedRb0}"/>
    <br/>
    <webuijsf:radioButton id="rb1" name="rb1grp" selected="#{tldRbCbExample.selectedRb1}"/>

    The value bindings imply that there are two methods implemented in the tldRbCbExample managed bean for each value binding.

    • public void setSelectedRb0(boolean selected)
    • public boolean getSelectedRb0()
    • public void setSelectedRb1(boolean selected)
    • public boolean getSelectedRb1()

    The "getSelected" methods will be called to determine the checked state of the radio buttons during rendering.
    When the tags are first rendered, the initial checked state is determined by the return value of the "getSelected" methods, only one of which should return true. The radio button whose "getSelected" method returns true will be checked in the HTML page and not checked if it returns false. When one of the radio buttons is checked by the user its "setSelected" method will be called with a boolean argument equal to true. The other radio button's "setSelected" method will be called with a boolean argument equal to false.

    No image or label will be displayed by this example.

    Example 2: Two grouped boolean radio buttons with value bindings, that display an image and a label

    <webuijsf:radioButton id="rb2" name="rb2grp" imageURL="tree_server.gif" label="Server" selected="#{tldRbCbExample.selectedRb2}"/>
    <br/>
    <webuijsf:radioButton id="rb3" name="rb2grp" imageURL="pool_tree.gif" label="Pool" selected="#{tldRbCbExample.selectedRb3}"/>

    The behavior of these radio buttons is the same as example one.
    In this example an image and a label are displayed next to both radio buttons. Both the imageURL and label attributes may be assigned value binding expressions instead of literal values.

    Example 3: Two grouped String valued radio buttons with value bindings and labels

    <webuijsf:radioButton id="rb4" name="rb3grp" label="Print" selectedValue="Print" selected="#{tldRbCbExample.selectedRb4}"/>
    <br/>
    <webuijsf:radioButton id="rb5" name="rb3grp" label="Fax" selectedValue="Fax" selected="#{tldRbCbExample.selectedRb5}"/>

    The value bindings imply that there are two methods implemented in the tldRbCbExample managed bean for each value binding. Because the selectedValue attribute is a String the expected method signatures will be:

    • public void setSelectedRb4(String selected)
    • public String getSelectedRb4()
    • public void setSelectedRb5(String selected)
    • public String getSelectedRb5()

    The "getSelected" methods will be called to determine the checked state of the radio buttons during rendering.
    When the tags are first rendered, the initial checked state is determined by the return value of the "getSelected" methods.
    With a String valued radio button, a radio button will be checked only if the "getSelected" method returns the value of its selectedValue attribute.
    For example if getSelectedRb4 returns "Print", the radio button "rb4" will be checked. getSelectedRb5 must not return "Fax" and should return null in order for "rb4" to remain checked.
    Alternatively if getSelectedRb4 returns null getSelectedRb5 should return "Fax", and radio button "rb5" will be checked.

    When the radio button is checked by the user the "setSelected" methods will be called with a String argument equal to the value of the selectedValue attribute of the radio button.
    When it is unchecked the method will be called with a null String argument.
    For example if radio button "rb4" is checked by the user setSelectedRb4 will be called with "Print" as the argument and setSelectedRb5 will be called with a null argument.

    Example 4: Two grouped object valued radio buttons with value bindings and labels

    <webuijsf:radioButton id="rb6" name="rb4grp" label="Print" selectedValue="#{tldRbCbExample.selectedValueRb6}" selected="#{tldRbCbExample.selectedRb6}" converter="#{tldRbCbExample.rbConverter}"/>
    <br/>
    <webuijsf:radioButton id="rb7" name="rb4grp" label="Fax" selectedValue="#{tldRbCbExample.selectedValueRb7}" selected="#{tldRbCbExample.selectedRb7}" converter="#{tldRbCbExample.rbConverter}"/>

    The value bindings imply that there are two methods implemented in the tldRbCbExample managed bean for each value binding. Let's say the object value for "rb6" is an instance of the "Printer" class, and "rb7" an instance of the "Fax" class, then the expected method signatures will be:

    • public void setSelectedRb6(Printer selected)
    • public Printer getSelectedRb6()
    • public void setSelectedValueRb7(Fax selected)
    • public Printer getSelectedValueRb7()
    A Printer class might look like:

         public class Printer implements Device {
    private String name;
    private String location;
    public Printer(String name, String location) {
    this.name = name;
    this.location = location;
    }
    public String getName() {
    return name;
    }
    public String getLocation() {
    return location;
    }
    public int getType() {
    return Device.PRINTER;
    }
    public boolean equals(Printer p) {
    return this.name.equals(p.getName()) &&
    this.location.equals(p.getLocation()) &&
    p.getType() == Device.PRINTER;
    }
    };
    A Fax class might look like:

         public class Fax implements Device {
    private String name;
    private String phoneNumber;
    public Printer(String name, String phoneNumber) {
    this.name = name;
    this.phoneNumber = phoneNumber;
    }
    public String getName() {
    return name;
    }
    public String getPhoneNumber() {
    return phoneNumber;
    }
    public int getType() {
    return Device.FAX;
    }
    public boolean equals(Fax f) {
    return this.name.equals(f.getName()) &&
    this.phoneNumber.equals(f.getPhoneNumber()) &&
    f.getType() == Device.FAX;
    }
    };

    Since this radio button represents an application defined object value, the application must provide a converter instance. The converter attribute's value binding expression implies a method in the tldRbCbExample managed bean called

    public Converter getRbConverter();

    The converter class might look like:
         public class RbConverter implements javax.faces.convert.Converter {
    public RbConverter() {
    }
    public String getAsString(FacesContext context,
    UIComponent component, Object value) {
    if (!value instanceof Device) {
    throw new ConverterException("Not a Device value");
    }
    return String.valueOf(((Device)value).getType());
    }
    public Object getAsObject(FacesContext context,
    UIComponent component, String value) {
    if (value == null) {
    return null;
    }
    // value is the String representation of "getType"
    //
    int type = Integer.parseInt(value);
    switch (type) {
    case Device.PRINTER:
    return deviceDb.getClosestPrinter();
    break;
    case Device.FAX:
    return deviceDb.getFax();
    break;
    default:
    throw new ConverterException("No such device : " + value);
    break;
    }
    }
    };

    The "getSelected" methods will be called to determine the checked state of the radio buttons during rendering. When the tags are first rendered, the initial checked state is determined by the return value of the "getSelected" methods. With Object valued radio buttons, a radio button will be checked only if the "getSelected" method returns an object instance that equals the object instance returned by the "getSelectedValue" method. For example if getSelectedRb6 returns the Printer instance value of "rb6"'s selectedValue attribute, then "rb6" will be checked. getSelectedRb7 should return null. If the getSelectedRb6 method returns a Printer instance that is not equal as determined by getSelectedValueRb6().equals(getSelectedRb6()) the radio button will not be checked. When the radio button is checked by the user the "setSelectedValue" methods will be called with the object instance returned by the converter. For example if "rb6" is checked by the user, setSelectedRb6 will be called with a Printer instance returned by the converter. setSelectedRb7 will be called with a null argument.

    Note that when radio buttons are part of a group the value of the selected radio button can be obtained directly from the request map. For example, processing the selection could take place in the action method of a submit button tag:

         public void submit() {
    // RadioButton.getSelected(String groupName) is
    // a static convenience method that obtains the
    // selected radio button value from the request map
    // ONLY when the radio button is part of a group.
    //
    Object selection = RadioButton.getSelected("rb4grp");
    // Assume at least one radio button will be selected.
    //
    processSelection((Device)selection);
    }

    Example 5: Grouped Integer valued radio buttons in a table

    The following example shows a common use case for radio buttons in a table. The radio buttons are used to select at most one row for processing. The radio button state does not need to be stored. The selected row index can be obtained directly in the #{tldRbCbExample.table5process} method, using the RadioButton.getSelected(String groupName) convenience method. The markup in bold is how you would specify a radio button tag for this purpose. The selectedValue value binding, #{tldRbCbExample.currentRow1} is implemented to return the current row in the table5row1 tableRow tag.

    Note that this example will not initially select a radio button which is normally not the way radio buttons are used; one is usually always checked.

         <webuijsf:table id="table5">
    <webuijsf:tableRow id="table5row1"
    sourceData="#{tldRbCbExample.table5row1data}"
    sourceVar="table5data"
    binding="#{tldRbCbExample.table5row1}">
    <webuijsf:tableColumn id="col1">
    <f:facet name="header">
    <webuijsf:tableHeader id="header1"
    deselectAllButton="true"
    selectAllButton="true"
    selectId="rb5"/>
    </f:facet>

    <webuijsf:radioButton id="rb8" name="rb5grp"
    selectedValue="#{tldRbCbExample.currentRow1}">
    </webuijsf:radioButton>

    </webuijsf:tableColumn>
    <webuijsf:tableColumn id="col2">
    <f:facet name="header">
    <webuijsf:staticText text="Application Data"/>
    </f:facet>
    <webuijsf:staticText text="#{table5data.text}"/>
    </webuijsf:tableColumn>
    </webuijsf:tableRow>
    <f:facet name="tableActionsBottom">
    <webuijsf:button id="table5process"
    action="#{tldRbCbExample.table5process}"
    text="Process Checked"/>
    </f:facet>
    </webuijsf:table>

    See webuijsf:table for details on using the <webuijsf:table> tag and other table child tags and facets.

    Normally when radio buttons are contained within a webuijsf:tableRow the application MUST provide a value binding for the selected attribute and any attribute that is expected to maintain its state. This is because the table only creates a single instance of the radio button for all rows. It depends on a model to provide the storage for the attribute values, as it iterates over the rows in the dataset.
    In this example, we don't need to maintain the state across requests because a row is only selected for processing. Once the processing is complete, the radio button no longer needs to be checked.

    The following code shows how the table5process action method obtains the selected radio button value from the request map. It calls a static member on RadioButton to return the Integer row index.

         public void table5process() {
    // RadioButton.getSelected(String groupName) is
    // a static convenience method that obtains the
    // selected radio button value from the request map
    // ONLY when the radio button is part of a group.
    //
    Integer row = (Integer)RadioButton.getSelected("rb5grp");
    if (row != null) {
    processRow(row.intValue());
    }
    }

    Example 6: Grouped boolean radio buttons in a table, using value bindings to maintain the state

    This example is similar to Example 5, but it maintains the state of the radio buttons across requests, by specifying a value binding for the selected attribute. A simple way to store the radio button state, is to store the state with the row data. The following code replaces the "webuijsf:radioButton" code in the previous example.

    <webuijsf:radioButton id="rb6" name="rb6grp" selected="#{table6data.selected}"> </webuijsf:radioButton>

    The value binding #{table6data.selected} references a boolean member in the row data for storing and retrieving the radio button state.

    Example 7: Update radioButton client side using the getProps and setProps functions

    This example shows how to toggle the disabled state of a radio button client side using the getProps and setProps functions.

    <webuijsf:radioButton id="rb1" name="rb1" label="My Radio Button"/>
    <webuijsf:button id="button1" text="Toggle Radio Button Disabled" onClick="toggleDisabled(); return false"/>

    <webuijsf:script>
    function toggleDisabled() {
    var domNode = document.getElementById("form1:rb1");
    domNode.setProps({ disabled: !domNode.getProps().disabled });
    }
    </webuijsf:script>

    Example 8: Asynchronously update radioButton using refresh function

    This example shows how to asynchronously update a radio button using the refresh function. When the user clicks on the button, the radio button is asynchronously updated with new data.
    <webuijsf:radioButton id="rb1" name="rb1" label="#{MyBean.label}"/>
    <webuijsf:button id="button1" text="Refresh Radio Button" onClick="refreshRadioButton(); return false;"/>
    <webuijsf:script>
        function refreshRadioButton() {
            var domNode = document.getElementById("form1:rb1"); // Get radio button
            return domNode.refresh(); // Asynchronously refresh button
        }
    </webuijsf:script>

    Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,..."). When no parameter is given, the refresh function acts as a reset. That is, the component will be redrawn using values set server-side, but not updated.

    Example 9: Asynchronously update radioButton using refresh function

    This example shows how to asynchronously update a radio button using the refresh function. The execute property of the refresh function is used to define the client id which is to be submitted and updated server-side. As the user types in the text field, the input value is updated server-side and the radio button label is updated client-side -- all without a page refresh.
    <webuijsf:radioButton id="rb1" name="rb1" label="#{MyBean.label}"/>
    <webuijsf:textField id="field1" text="#{MyBean.label}" label="Change Radio Button Label"
    onKeyPress="setTimeout('refreshRadioButton();', 0);"/> // Field used to asynchronously update label.
    <webuijsf:script>
        function
    refreshRadioButton() {
            var domNode = document.getElementById("form1:rb1"); // Get radio button
            return domNode.refresh("form1:field1"); // Asynchronously refresh while submitting field value
        }
    </webuijsf:script>

    Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,...")

    radioButtonGroup

    Use the webuijsf:radioButtonGroup tag to display two or more radio buttons in a grid layout in the rendered HTML page. The webuijsf:radioButtonGroup tag attributes that you specify determine how the radio buttons are displayed.

    If the label attribute is specified a com.sun.webui.jsf.component.Label component is rendered before the first radio button and identifies the radio button group. The label component's for attribute is set to the id attribute of the first radio button in the rendered HTML page.

    The radio buttons are laid out in rows and columns in an HTML <table> element. The number of rows is defined by the length of the items array. The number of columns is defined by the columns attribute. The default layout is a single vertical column.

    The items attribute must be a value binding expression. The value binding expression assigned to the items property evaluates to an Object array of com.sun.webui.jsf.model.Option instances. Each instance represents one radio button. The value property of an Option instance represents the value of a selected radio button. If the items array is empty nothing is rendered.

    At least one radio button should be selected by the application. The selected attribute must also be a value binding expression that is evaluated to read and write an Object. When an Object value is read from the value binding expression, it identifies the selected radio button. The Object value must be equal to the value property of at least one Option instance specified in the array obtained from the value binding expression assigned to the items attribute.

    The write method of the selected attribute value binding expression is called during the UPDATE_MODEL_PHASE of the JSF lifecyle. If a radio button is selected an Object value is passed as an argument to the write method. The Object value is the value of the selected radio button.

    HTML Elements and Layout

    A webuijsf:radioButtonGroup renders one com.sun.webui.jsf.component.RadioButton component for each element in the items array. See webuijsf:radioButton for details on the HTML elements and components rendered for a radio button.

    The value of the name attribute of each RadioButton component rendered is assigned the clientId of the RadioButtonGroup component instance associated with this tag. The id attribute of each RadioButton component rendered is formed as follows, where rbgrpid is the id of the RadioButtonGroup instance and N is the nth radio button.

    • rbgrpid_N

    See webuijsf:radioButton for details on how the id properties of the components that make up the radio button are defined.

    Theme Identifiers

    • RbGrp for the TABLE element.
    • RbGrpCpt for the TD element containing the group label
    • RbGrpLbl for the LABEL element used as the CAPTION
    • RbGrpLblDis for the LABEL used as the CAPTION if the group is disabled
    • RbGrpRwEv for even TR elements
    • RbGrpRwOd for odd TR elements
    • RbGrpClEv for even TD elements
    • RbGrpClOd for odd TD elements
    • Rb for the INPUT element
    • RbDis for the INPUT element for disabled radio button
    • RbLbl for a LABEL element of a radio button
    • RbLblDis for a LABEL element of a disabled radio button
    • RbImg for an IMG element of a radio button
    • RbImgDis for an IMG element of a disabled radio button

    Client Side Javascript Functions

    When the component is rendered, a DOM object corresponding to the component is created. To manipulate the component on the client side, you may invoke functions on the DOM object. With reference to the DOM id, to disable the component, invoke document.getElementById(id).setProps({disabled: true}).

    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. If omitted, no other components are executed.
    setProps(props) Use this function to change any of the following supported properties:
    • align
    • className
    • contents
    • dir
    • disabled
    • id
    • label
    • lang
    • name
    • readOnly
    • style
    • tabIndex
    • title
    • visible
    subscribe(topic, obj, func) Use this function to subscribe to an event topic.
    • topic: The event topic to subscribe to.
    • obj: The object in which a function will be invoked, or null for default scope.
    • func The name of a function in context, or a function reference to invoke when topic is published.

    Client Side JavaScript Events

    When the component is manipulated client side, some functions may publish event topics for custom AJAX implementations to listen for. For example, you can listen for the refresh event topic using:

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

        // Subscribe to refresh event.
        var domNode = document.getElementById("form1:test1");
        domNode.subscribe(domNode.event.refresh.endTopic, processEvents, "update");


    </webuijsf:script>

    The following events are supported.

    <Node>.event.refresh.beginTopic Event topic published before asynchronously refreshing the component. 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
    <Node>.event.refresh.endTopic Event topic published after asynchronously refreshing the component. Supported properties include: See setProps() function.
    • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage

    Examples

    Example 1: Create a radio button group

     <webuijsf:radioButtonGroup items="#{rbcbGrp.selections}"
        label="#{rbcbGrp.rbGrpLabel}"
        toolTip="rbgrp-tooltip"
        tabIndex="1"
        columns="3"
        labelLevel="2"
        selected="#{rbcbGrp.selection}">
     </webuijsf:radioButtonGroup>

    This example creates a radio button group with an identifying label for the group before the first radio button. The data for the radio buttons is obtained from the value binding expression #{rbcbGrp.selections} where rbcbGrp is an application defined managed bean. The bean provides the values for other attributes such as selected to receive the value of the selected radio button in the group.

    Example 2: Update radioButtonGroup client side using the getProps and setProps functions

    This example shows how to toggle the disabled state of a radioButtonGroup client side using the getProps and setProps functions.

    <webuijsf:radioButtonGroup id="rb1" name="rb1" items="#{rbcbGrp.selections}" selected="#{rbcbGrp.cbvalue}" label="#{rbcbGrp.cbGrpLabel}"/>
    <webuijsf:button id="button1" text="Toggle radioButtonGroup Disabled" onClick="toggleDisabled(); return false"/>

    <webuijsf:script>
    function toggleDisabled() {
    var domNode = document.getElementById("form1:rb1");
    domNode.setProps({ disabled: !domNode.getProps().disabled });
    }
    </webuijsf:script>

    Example 3: Asynchronously update radioButtonGroup using refresh function

    This example shows how to asynchronously update a radioButtonGroup using the refresh function. When the user clicks on the button, the radioButtonGroup is asynchronously updated with new data.
    <webuijsf:radioButtonGroup id="rb1" name="rb1" items="#{rbcbGrp.selections}" selected="#{rbcbGrp.cbvalue}" label="#{rbcbGrp.cbGrpLabel}"/>
    <webuijsf:button id="button1" text="Refresh radioButtonGroup" onClick="refreshGroup(); return false;"/>
    <webuijsf:script>
        function refreshGroup() {
            var domNode = document.getElementById("form1:cb1"); // Get radioButtonGroup
            return domNode.refresh(); // Asynchronously refresh radioButtonGroup
        }
    </webuijsf:script>

    Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,..."). When no parameter is given, the refresh function acts as a reset. That is, the component will be redrawn using values set server-side, but not updated.

    Example 4: Asynchronously update radioButtonGroup using refresh function

    This example shows how to asynchronously update a radioButtonGroup using the refresh function. The execute property of the refresh function is used to define the client id which is to be submitted and updated server-side. As the user types in the text field, the input value is updated server-side and the radioButtonGroup label is updated client-side -- all without a page refresh.
    <webuijsf:radioButtonGroup id="rb1" name="rb1" items="#{rbcbGrp.selections}" selected="#{rbcbGrp.cbvalue}" label="#{rbcbGrp.cbGrpLabel}"/>
    <webuijsf:textField id="field1" text="#{rbcbGrp.cbGrpLabel}" label="Change radioButtonGroup Label"
    onKeyPress="setTimeout('refreshRadioButtonGroup();', 0);"/> // Field used to asynchronously update label.
    <webuijsf:script>
        function
    refreshRadioButtonGroup() {
            var domNode = document.getElementById("form1:cb1"); // Get radioButtonGroup
            return domNode.refresh("form1:field1"); // Asynchronously refresh while submitting field value
        }
    </webuijsf:script>


    Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,...")

    scheduler

    Use the webuijsf:scheduler tag to display a calendar and the input controls that are used for selecting a date and time. The webuijsf:scheduler tag's attributes allow you to associate the component with a value (a com.sun.webui.jsf.model.ScheduledEvent), and to configure how the input controls are rendered.

    HTML Elements and Layout

    The Scheduler component displays a monthly calendar, consisting of a <table> element with cells that contain hyperlinks for each day of the month. When a date link is clicked, the associated date is displayed in the Start Date field. The current month is displayed initially by default, and the user can select a different month by using a drop-down menu. Hyperlinked icons to the left and right of the Month menu can be used to go to the previous and next months. Another drop-down menu can be used to select a different year.

    The Start Time is always rendered by the component, and consists of separate drop-down menus for the hour and minute. The user is required to enter values for Start Date and Start Time, so those subcomponents of the Scheduler are annotated as required by default.

    Additional input controls for End Time, Repeat Interval, and Repeat Limit are rendered by default to allow detailed scheduling control by the user. These input controls can be removed by setting webuijsf:scheduler tag attributes. The Scheduler component also renders a button to allow users to preview their scheduled events in the calendar, where days with scheduled events appear as highlighted cells in the table.

    The following diagram shows the layout of the Scheduler component. The diagram represents the default calendar, which includes all available input controls.

     
    * Indicates required field
     < 
     > 
     
    S M T W T F S
    1 2 3 4 5 6 7
    8 9 10 11 12 13 14
    15 16 17 18 19 20 21
    22 23 24 25 26 27 28
    29 30 31 1 2 3 4
     
    mm/dd/yyyy
       
    : GMT-05:00
       
    : GMT-05:00
     
       
     
       
         
    Blank value repeats forever
       
     

    Configuring the webuijsf:scheduler Tag

    Use the value attribute to associate the component with a model object that represents the current value. The model object must be of type com.sun.webui.jsf.model.ScheduledEvent.

    Schedule data entered by the user is automatically converted to and from the ScheduledEvent.

    You can use webuijsf:scheduler tag attributes to configure the appearance of the Scheduler. By default, input elements for Start Date, Start Time, End Time, Repeat Interval, and Repeat Limit are shown. You can specify your own labels for the input elements. You can also suppress the display of most of the elements. All but the Start Date are optional. To suppress the End Time element, set endTimerepeating to false; to suppress just the Repeat Limit controls, set limitRepeating to false.

    You can also prevent display of the Preview in Calendar button by setting previewButton to false.

    To configure a range of dates that can be selected, specify the minDate and maxDate attributes.

    The range of years available in the Calendar display is derived from the the minDate and maxDate attributes.

    Facets

    None.

    Client-side JavaScript Functions

    None.

    Examples

    Example 1: Basic Scheduler

    This example uses all the input elements, but changes the labels for the dates and times.

     
         <webuijsf:scheduler id="scheduler" 
                       dateLabel="Date: " 
                       startTimeLabel="Start: "
                       endTimeLabel="End: " 
                       value="#{SchedulerBean.event}"/>
     

    Example 2: Scheduler without End Time or Repeating Events

    This example disables the End Time, Repeat Interval, and Repeat Limit controls.

     
         <webuijsf:scheduler id="scheduler" 
                       dateLabel="Date: " 
                       startTimeLabel="Start: "
                       repeating="false"
                       endTime="false"
                       value="#{SchedulerBean.event}"/>
     

    SchedulerBean Used in Examples

    import com.sun.webui.jsf.model.ScheduledEvent;

    public class SchedulerBean {

       // Creates a new instance of SchedulerBean

        public SchedulerBean() {
        }

      //
      // Holds value of property event.
      //
        private ScheduledEvent event = null;

        //
        // Getter for property event.
        // @return Value of property event.
        //
        public ScheduledEvent getEvent() {

            return this.event;
        }

        //
        // Setter for property event.
        // @param event New value of property event.
        //
     
        public void setEvent(ScheduledEvent event) {

            this.event = event;
        }

        ...

    }

    scriptUse the webuijsf:script tag to create a <script> element in the rendered HTML page. The webuijsf:script tag must be used within the webuijsf:head tag, or within the webuijsf:body tag.  The webuijsf:script tag can be used to refer to a Javascript file, by using the url attribute. The tag can also be used embed Javascript code within the rendered HTML page.

    The client-side script allows you to perform some interactive functions such as input checking before the page is submitted.

    HTML Elements and Layout

    The rendered HTML page contains a <script> element with any attributes specified through the webuijsf:script tag attributes. 

    Theme Identifiers

    None.

    Client Side Javascript Functions

    None.

    Example

    Example 1: Create a script tag to a file

    <webuijsf:script url="/pathtomyjs/myjavascript.js" />

    Example 2: Create a script tag with embedded script (Not Recommended)

    <webuijsf:script>
      function foo(text) {
          alert(text);
      }
    </webuijsf:script>
    skipHyperlinkUse the webuijsf:skipLink tag to render a single-pixel transparent image (not visible within the browser page) which is hyperlinked to an anchor beyond the section to skip. This tag is used to achieve 508-compliance (paragraph o). It is designed to be used by components such as masthead, tabs, calendar and other components with repetitive links.

    HTML Elements and Layout

    The rendered HTML page displays an image hyperlink at the top, followed by an anchor at the end of the region to skip.

    Theme Identifiers

    None.

    Client-side JavaScript functions

    None.

    Examples

    Example 1: An example showing how to skip over the masthead:
    <webuijsf:skipHyperlink id="skip1234" description="skip over the masthead" > <webuijsf:masthead id=masthead1" productImageURL="../images/webconsole.png" productImageDescription="Java Web Console" userInfo="test_user" serverInfo="test_server" /> </webuijsf: skipHyperlink>
    staticText

    Use the webuijsf:staticText tag to display text that is not interactive in the rendered HTML page.  The text can be plain static text, or be formatted using parameters to insert variable text in the rendered HTML. The JSF core tag f:param can be used along with view beans to provide the variable data.

    If there are one or more params, the component will convert the list of parameter values to an Object array, and call MessageFormat.format(), passing the value of the param of this component as the first argument, the value of the array of parameter values as the second argument, and render the result. See MessageFormat.format()for details.Otherwise, render the text of this component unmodified.

    HTML Elements and Layout

    The rendered HTML page includes a <span> element that contains the resulting text.  In the <span> element, the class and style attribute values are set to the values specified with the webuijsf:staticText tag's styleclass and style attributes.

    Client Side Javascript Functions

    When the component is rendered, a DOM object corresponding to the component is created. To manipulate the component on the client side, you may invoke functions on the DOM object. With reference to the DOM id, to disable the component, invoke document.getElementById(id).setProps({value: "My Text"}).

    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. If omitted, no other components are executed.
    setProps(props) Use this function to change any of the following supported properties:
    • className
    • dir
    • escape
    • id
    • lang
    • onClick
    • onDblClick
    • onMouseDown
    • onMouseMove
    • onMouseOut
    • onMouseOver
    • onMouseUp
    • style
    • title
    • value
    • visible
    subscribe(topic, obj, func) Use this function to subscribe to an event topic.
    • topic: The event topic to subscribe to.
    • obj: The object in which a function will be invoked, or null for default scope.
    • func The name of a function in context, or a function reference to invoke when topic is published.

    Client Side JavaScript Events

    When the component is manipulated client side, some functions may publish event topics for custom AJAX implementations to listen for. For example, you can listen for the refresh event topic using:

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

        // Subscribe to refresh event.
        var domNode = document.getElementById("form1:test1");
        domNode.subscribe(domNode.event.refresh.endTopic, processEvents, "update");


    </webuijsf:script>

    The following events are supported.

    <Node>.event.refresh.beginTopic Event topic published before asynchronously refreshing the component. 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
    <Node>.event.refresh.endTopic Event topic published after asynchronously refreshing the component. Supported properties include: See setProps() function.
    • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage

    Examples

    Example 1: Render plain old text

    <webuijsf:staticText id="statictext1" text="#{bean.someText}" />
    <webuijsf:staticText id="statictext1" text="some text to display" />

    Example 2: Use Params to format a whole line

          <webuijsf:staticText id="blah" text="At {1,time} on {1,date}, there was {2} on planet {0,number,integer}.">
              <f:param id="b1" value="#{HyperlinkBean.myInt}"/>
              <f:param id="b2" value="#{HyperlinkBean.date}"/>
              <f:param id="b3" value="2 fools"/>                 
          </webuijsf:staticText>

    The above will render:  "At 8:36:18 AM on Dec 13, 2004, there was 2 fools on planet 7."

    Example 3: Update client-side text properties using the getProps and setProps functions

    This example shows how to toggle the disabled state of text client side using the getProps and setProps functions. When the user clicks the radio button, the text is either hown or hidden.
    <webuijsf:radioButton id="rb1" name="rb1" label="Toggle Text Visible" onClick="toggleVisible()"/>
    <webuijsf:staticText id="text1" text="My Text" />

    <webuijsf:script>
    function toggleVisible() {
    var domNode = document.getElementById("form1:text1"); // Get text
    return domNode.setProps({visible: !domNode.getProps().visible}); // Toggle visible
    }
    </webuijsf:script>

    Example 4: Asynchronously update text using refresh function

    This example shows how to asynchronously update text using the refresh function. When the user clicks on the radio button, the text is asynchronously updated with new data.
    <webuijsf:radioButton id="rb1" name="rb1" label="Refresh Button" onClick="refreshText()"/>
    <webuijsf:staticText id="text1" text="#{MyBean.text}"/>
    <webuijsf:script>
        function refreshText() {
            var domNode = document.getElementById("form1:text1"); // Get text
            return domNode.refresh(); // Asynchronously refresh text
        }
    </webuijsf:script>

    Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,..."). When no parameter is given, the refresh function acts as a reset. That is, the component will be redrawn using values set server-side, but not updated.

    Example 5: Asynchronously update text using refresh function

    This example shows how to asynchronously update text using the refresh function. The execute property of the refresh function is used to define the client id which is to be submitted and updated server-side. As the user types in the text field, the input value is updated server-side and the text is updated client-side -- all without a page refresh.
    <webuijsf:staticText id="text1" text="#{MyBean.text}"/>
    <webuijsf:textField id="field1" text="#{MyBean.text}" label="Change Text"
    onKeyPress="setTimeout('refreshText();', 0);"/> // Field used to asynchronously update text.
    <webuijsf:script>
        function
    refreshText() {
            var domNode = document.getElementById("form1:text1"); // Get text
            return domNode.refresh("form1:field1"); // Asynchronously refresh while submitting field value
        }
    </webuijsf:script>


    Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,...")

    tab

    Use the webuijsf:tab within the webuijsf:tabSet tag to create a tab within a set of tabs in the rendered HTML page. The webuijsf:tab tag extends the webuijsf:hyperlink tag. The webuijsf:tab tag differs from webuijsf:hyperlink tag in the value rendered by default for the class attribute of the rendered HTML anchor.

    HTML Elements and Layout

    The tab component renders an XHTML <a href> tag.

    Configuring the webuijsf:tab Tag

    The webuijsf:tab tag can be configured with many of the same attributes as the webuijsf:hyperlink tag. The tab can be configured to display its associated JSP page using the url or action attributes. The tab can be configured to perform an action such as updating data displayed in the page using the actionListener attribute.

    If you add child Tab components to a Tab component, making a multiple level set of tabs, you can use the selectedChildId to specify the initially selected child tab.

    Facets

    None.

    Client Side Javascript Functions

    None.

    Examples

    See the webuijsf:tabSet documentation for an example of defining tabs by using a TabSet component binding.

    Example 1: Defining three tabs in a tab set

    <webuijsf:tabSet id="MyTabs" selected="tab1" >
         <webuijsf:tab id="tab1" text="Tab 1" action="#{TabSetBean.tab1Clicked}" />
         <webuijsf:tab id="tab2" text="Tab 2" action="#{TabSetBean.tab2Clicked}" />
         <webuijsf:tab id="tab3" text="Tab 3" action="#{TabSetBean.tab3Clicked}" />
    </webuijsf:tabSet >

    tabSet

    Use the webuijsf:tabSet tag to create a set of tabs in the rendered HTML page. The tabs are used for navigation in the web application, and do not contain page content. The individual tabs in the set can be specified with webuijsf:tab tags used as children of the webuijsf:tabSet tag. The tab set and tabs can alternatively be specified in a backing bean.

    You can make multiple levels of tabs by nesting tab components within other tab components, inside a single tab set component.

    The TabSet component keeps track of the currently selected child tab, and applies any specified ActionListener to each child tab.

    HTML Elements and Layout

    The tabSet component renders <div> and <table> elements, which will contain the hyperlinks produced by the Tab component.

    Configuring the webuijsf:tabSet Tag

    The webuijsf:tabSet tag can be used in either of the following ways:

    • set the component binding to a TabSet component and group of child Tab components that are defined in a backing bean. This approach is especially useful for using a single set of tabs among multiple pages.

    • specify the TabSet and child Tabs directly in your JSP.

    Examples of both approaches are shown in the Examples section below.

    In either approach, the webuijsf:tabSet tag attributes can be specified in the JSP page. The initial selection for the TabSet component is specified with the selected attribute. You can use the mini and lite attributes to create tabs that are smaller and lighter in appearance. The mini attribute can be used to make smaller tabs. The lite attribute can be used with the mini attribute to create small tabs that have less shading and bolding. Note that mini tab sets will not display properly if more than one level of tabs are specified.

    If you specify an actionListener attribute for the TabSet component, the specified listener is applied to the action listener list of each of the child Tab components.

    The lastSelectedChildSaved attribute can be used to enable the tab set to maintain the selected state of its child tabs. This enables the selection to be "remembered" when the user goes to another tab level. When the user returns to first set of tabs, the originally selected tab is still selected.

    Content of Tabs

    The Tab component itself does not have any content, but is used to display another page or update something in the current page when the tab is clicked. Use the url or action attributes to specify another JSP page that corresponds to the clicked tab. Use the actionListener to update data in the page when a given tab is clicked.

    For example, you might define a single TabSet instance in a backing bean that is shared among many pages. The tabs in those pages would each specify an appropriate url that contains the content for the corresponding tab. See Example 1.

    Alternatively, you might have a single page containing a TabSet and a Table of data corresponding to the currently selected Tab. When the TabSet selection changes, the actionListener on the clicked Tab is invoked and the Table is updated to display the appropriate data for the tab that is clicked. See Example 2.

    Facets

    None.

    Client Side Javascript Functions

    None.

    Examples

    Example 1: Define the TabSet in a Backing Bean and Use TabSet in a Single JSP Page
        TabsBean Backing Bean for Example 1
    Example 2: Define TabSet in Backing Bean and Use in Multiple JSP Pages
        TabSetBackingBean for Example 2
    Example 3: Define the TabSet in your JSP Page

    Example 1: Define the TabSet in a Backing Bean and Use TabSet in a Single JSP Page

    This example shows how to create a JSF component binding to a TabSet instance that is defined in a backing bean. The webuijsf:tabSet tag is used in only one JSP page. When the tabs in this page are clicked, their associated action events are launched. In this example, the action is simply to display the id of the tab clicked and the tab selected. The action event approach might be used to update table data when the tab is clicked, for example.

    The tabs.jsp file

    <f:view>
      <webuijsf:page>
        <webuijsf:html>
        <webuijsf:head title="Tabs Example Page" />
        <webuijsf:body>
          <webuijsf:form id="tabsexample">
            <webuijsf:masthead id="Masthead" productImageURL="../images/webconsole.png"
                productImageDescription="Java Web Console" userInfo="test_user"
                serverInfo="test_server" />
                    <webuijsf:breadcrumbs id="breadcrumbs">
            <webuijsf:hyperlink url="../index.jsp" text="Tests Index"/>
            <webuijsf:hyperlink url="../tabs/index.jsp" text="Tab Tests"/>
             <webuijsf:hyperlink url="../tabs/tabs.jsp" text="Test 1"/>
          </webuijsf:breadcrumbs>

            <webuijsf:tabSet binding="#{TabsBean.sportsTabs}" />
            <p align="center">
              <strong><webuijsf:staticText escape="false" text="#{TabsBean.message}" /></strong>
             </p>

          </webuijsf:form>
        </webuijsf:body>
        </webuijsf:html>
      </webuijsf:page>
    </f:view>

    TabsBean Backing Bean

    The backing bean code for this example is shown below.

    import java.util.List;
    import java.lang.Class;
    import javax.faces.FactoryFinder;
    import javax.faces.el.MethodBinding;
    import javax.faces.event.ActionEvent;
    import javax.faces.application.Application;
    import javax.faces.application.ApplicationFactory;
    import com.sun.webui.jsf.component.Tab;
    import com.sun.webui.jsf.component.TabSet;

    public class TabsBean {
        private TabSet sportsTabs = null;

        // Creates a new instance of TabsBean
        public TabsBean() {
           
            sportsTabs = new TabSet();
            List kids = sportsTabs.getChildren();

            Tab level1Tab = new Tab("Baseball");
            level1Tab.setId("Baseball");
            Tab level2Tab = addTab(level1Tab, "National");
            addTab(level2Tab, "Mets");
            addTab(level2Tab, "Pirates");
            addTab(level2Tab, "Cubs");

            level2Tab = addTab(level1Tab, "American");
            addTab(level2Tab, "Yankees");
            addTab(level2Tab, "Tigers");
            addTab(level2Tab, "Mariners");

            level2Tab = addTab(level1Tab, "AAA");
            addTab(level2Tab, "Spinners");
            addTab(level2Tab, "Renegades");
            addTab(level2Tab, "Clippers");

            kids.add(level1Tab);

            level1Tab = new Tab("Football");
            level1Tab.setId("Football");
            level2Tab = addTab(level1Tab, "NFC");
            addTab(level2Tab, "Giants");
            addTab(level2Tab, "Bears");
            addTab(level2Tab, "Falcons");

            level2Tab = addTab(level1Tab, "AFC");
            addTab(level2Tab, "Jets");
            addTab(level2Tab, "Patriots");
            addTab(level2Tab, "Colts");

            level2Tab = addTab(level1Tab, "College");
            addTab(level2Tab, "Wolverines");
            addTab(level2Tab, "Hurricanes");
            addTab(level2Tab, "Buckeyes");

            kids.add(level1Tab);

            level1Tab = new Tab("Hockey");
            level1Tab.setId("Hockey");
            level2Tab = addTab(level1Tab, "East");
            addTab(level2Tab, "Islanders");
            addTab(level2Tab, "Rangers");
            addTab(level2Tab, "Bruins");

            level2Tab = addTab(level1Tab, "West");
            addTab(level2Tab, "Oilers");
            addTab(level2Tab, "Blackhawks");
            addTab(level2Tab, "Blues");

            level2Tab = addTab(level1Tab, "Minors");
            addTab(level2Tab, "Phantoms");
            addTab(level2Tab, "Monsters");
            addTab(level2Tab, "Freeze");

            kids.add(level1Tab);

            Class[] args = new Class[] { ActionEvent.class };
            MethodBinding binding = createBinding("#{TabsBean.tabClicked}", args);

            sportsTabs.setActionListener(binding);

            sportsTabs.setSelected("Jets");

                }

        private MethodBinding createBinding(String expr, Class[] args) {
            ApplicationFactory factory = (ApplicationFactory)
                FactoryFinder.getFactory(FactoryFinder.APPLICATION_FACTORY);
            Application app = factory.getApplication();

            return app.createMethodBinding(expr, args);
        }

        private Tab addTab(Tab parent, String newTabLabel) {
            Tab tab = new Tab(newTabLabel);
            tab.setId(newTabLabel);

            parent.getChildren().add(tab);

            return tab;
        }
                   
        public TabSet getSportsTabs() {
            return sportsTabs;
        }

        public void setSportsTabs(TabSet tabs) {
            sportsTabs = tabs;
        }

        public void tabClicked(ActionEvent event) {
            message = "Action listener invoked! <br/> <br/> Tab clicked has id of ";
            message += event.getComponent().getId();
            message += ". Selected tab id is " + sportsTabs.getSelected();
        }

        public String getMessage() {
            return message;
        }

        public void setMessage(String m) {
            message = m;
        } 

    Example 2: Define TabSet in Backing Bean and Use in Multiple JSP Pages

    In this example, each tab has its own JSP page. The example below shows a JSP page for "Tab 1". The selected attribute of the webuijsf:tabSet is set to the id of Tab 1, and the content to be displayed when Tab 1 is clicked is provided after the webuijsf:tabSet tag. The JSP pages for the other tabs in the set would be very similar, with the references to the specific tab updated appropriately, e.g. "Tab 2" and "tab2" and so on.

    The tab1.jsp file

    <f:view>
      <webuijsf:page>
        <webuijsf:html>
        <webuijsf:head title="Tab 1 Page" />
        <webuijsf:body>
          <webuijsf:form id="tabsexample">
            <webuijsf:masthead id="Masthead" productImageURL="../images/webconsole.png"
                productImageDescription="Java Web Console" userInfo="test_user"
                serverInfo="test_server" />
          <webuijsf:breadcrumbs id="breadcrumbs">
            <webuijsf:hyperlink url="../index.jsp" text="Tests Index"/>
            <webuijsf:hyperlink url="../tabs/index.jsp" text="Tab Tests"/>
             <webuijsf:hyperlink url="../tabs/tabs.jsp" text="Test 5"/>
          </webuijsf:breadcrumbs>

            <webuijsf:tabSet binding="#{TabsBean.myTabSet}" selected="tab1" />

            <p align="center"><strong>Tab 1</strong></p>

            ... other stuff for this tab...

          </webuijsf:form>
        </webuijsf:body>
        </webuijsf:html>
      </webuijsf:page>
    </f:view>

    TabSetBackingBean for Example 2

    The backing bean that defines this TabSet creates the tabs named Tab 1 through Tab 4, and sets their url properties to tab1.jsp through tab4.jsp.

    public class TabSetBackingBean {
        ...

        public TabSet getMyTabSet() {
        TabSet = new TabSet();
            tabSet.setId("myTabSet");
        
        for (int i = 1; i < 5; i++) {
            Tab tab = new Tab("Tab " + i);
            tab.setId("tab" + i);
            tab.setUrl("tab" + i + ".jsp");
            tabSet.getChildren().add(tab);
        }

        return tabSet;
        }

        ...
    }

    Example 3: Define the TabSet in your JSP Page

    This example shows how to define the tab set completely in a JSP file. It defines a set of tabs that includes three level-1 tabs (labeled "One", "Two" and "Three"). Each level-1 tab also has two level-2 tab children, labelled "XxxA" and "XxxB" where Xxx is the top level tab number. The initially selected tab for this tab set will be "TwoA".

    <webuijsf:tabSet selected="TwoA">
        <webuijsf:tab id="One" text="One">
            <webuijsf:tab id="OneA" text="One A" />
            <webuijsf:tab id="OneB" text="One B" />
        </webuijsf:tab>
        <webuijsf:tab id="Two" text="Two">
            <webuijsf:tab id="TwoA" text="Two A" />
            <webuijsf:tab id="TwoB" text="Two B" />
        </webuijsf:tab>
        <webuijsf:tab id="Three" text="Three">
            <webuijsf:tab id="ThreeA" text="Three A" />
            <webuijsf:tab id="ThreeB" text="Three B" />
        </webuijsf:tab>
    </webuijsf:tabSet>

    table

    Use the webuijsf:table tag to create a table that can be configured to perform actions on objects in the table, and to manipulate the rows and columns of the table. The table component features behaviors that let the user sort, filter, and paginate the table objects, and provides actions that can be performed on selected objects. The component also allows you to implement developer-defined custom actions.

    Note that the webuijsf:table tag is not intended to be used to create HTML tables that are used purely to handle page layout. The table component renders a table with a well-defined structure, including a title, column headings, and borders. You can use tags such as webuijsf:propertySheet and webuijsf:panelGroup for page layout if possible.

    The table component implements Sun's user interface (UI) guidelines for web applications. The guidelines describe in detail how the table should appear and behave, including the placement of titles, group headers, and actions. The table component's default behavior implements the UI guidelines. The component is also extensible through JavaServer Faces facets to allow the component to be used for tables that do not need to adhere strictly to the UI guidelines.

    The webuijsf:table tag must be used with the webuijsf:tableRowGroup and webuijsf:tableColumn tags. The webuijsf:table tag is used to define the structure and actions of the table, and is a container for webuijsf:tableRowGroup tags.  The webuijsf:tableRowGroup tag is used to define the rows of the table, and is a container for webuijsf:tableColumn tags. The webuijsf:tableColumn tag is used to define the columns of the table.

    HTML Elements and Layout

    The table component renders an XHTML <table> element.  Depending upon the attributes specified with the webuijsf:table tag, the table component can also render a title in a <caption> element, and image hyperlinks for the various buttons for sorting and pagination.  The table component does not render table rows except for the rows that contain the view-changing and pagination controls.

    Table Structure

    Tables are composed of several discrete areas. You can use  webuijsf:table tag attributes to cause the table component to create the default layout for each area. The default layout strictly adheres to UI guidelines.  The layout for each area can also be customized by using facets.  Some areas require you to use facets to implement the content you want in those areas. Descriptions of the table areas are shown below, followed by a diagram that shows the placement of the areas.

    • Title - displays a title for the table, which you can also use to include information about paginated rows and applied filters. Use the title attribute to specify the title content. Use the itemsText attribute to specify the text displayed for the table title for an unpaginated table.  Use the filterText attribute to specify text to include in the title about the filter that is applied.  You can override the default implementation of the title bar with a different component by using the title facet. 

    • Action Bar (top) - in the first row of the table, displays controls that operate on the table and its data. This area contains the following sub areas:

      • Actions - displays local actions that apply to the objects in the table. You must provide the components for each action, by specifying them in the actionsTop facet.  You can specify the same actions for the Action Bar (bottom) area in the actionsBottom facet.

      • View-Changing Controls - displays controls for changing the view of the table data, such as custom filtering and sorting. This area contains the following  sub areas:

        • Filter - displays a drop-down menu of filter options, which allow users to select criteria to be used to determine the items to display. The component provides a default implementation for adding options when the Custom filter becomes active, to display the filter panel, etc. However, you must implement your filters through custom options. An example filter is shown in Filter.java.

        • Clear Sort - displays a button that is used to remove all sorting of the table.  Use the clearTableSortButton attribute to display the clear table sort button.
        • Sort - displays a toggle button for the sort panel. Clicking this button opens and closes an embedded panel with custom sort options. The panel opens inside the table below the Action Bar (top).  Use the sortPanelToggleButton attribute to display the default sort button with a default layout of the sort panel.  You can provide custom content for the sort panel by using the sortPanel facet.

        • Preferences - displays a toggle button for setting the user's preferences. Clicking this button opens and closes an embedded panel with view preferences. The preferences panel opens inside the table below the Action Bar (top). You must provide the content of the preferences panel by using the preferencesPanel facet. There is no default implementation of the preferences panel content, and therefore no attribute to specify that the button should be displayed.

      • Vertical Pagination - The Vertical Pagination area displays a paginate button, which allows users to switch between viewing the table as multiple pages, or as a single scrolling page.  You can specify the paginateButton  attributes to display the default paginate button.  Note that the Vertical Pagination area is limited to this button. You cannot use extra pagination controls in this area, as you can in the bottom Pagination area. 

    • Action Bar (bottom)

      • Actions - displays local actions that apply to the objects in the table. You must provide the implementation for each table action, by using the actionsBottom facet . The same actions can exist for the Table both the "Action Bar (top)" and "Action Bar (bottom)" sections

      • Pagination Controls - displays controls for pagination, including the paginate button, which allows users to switch between viewing the table as multiple pages, or as a single scrolling page. The Pagination area also includes buttons for turning the pages in sequence, jumping to a specific page, and jumping to the first or last page. You can specify the paginateButton and paginateControls attributes to display the default layout  of the Pagination area.

    • Footer -  displays a footer across all columns at the bottom of the table. You can specify the footerText attribute to display footer content with a default layout, or specify a component for the footer by using the footer facet.

    The following diagram shows the relative location of the table areas and facets that can be used for each area. The areas that are specified with the webuijsf:table tag  attributes are highlighted in blue.  The grayed out area is controlled with webuijsf:tableRowGroup and webuijsf:tableColumn tags, but is shown here for context.


    Title Bar title
    Action Bar (top)  
    Actions actionsTop View-Changing Controls
    Filter
    filter
    Sort
    Clear Sort Preferences
    Vertical Pagination
    Embedded Panels filterPanel sortPanel preferencesPanel
    Column Header
    Column Header
    Group Header Bar 
    Table data



    Table data
    Column Footer Column Footer
    Group Footer Bar 
    Table Column Footer Table Column Footer
    Action Bar (bottom)
    Actions actionsBottom
    Pagination Controls
    Footer

    Buttons and Controls

    The following attributes can be specified to add buttons and controls to the table:
    • clearSortButton adds a button to the View-Changing Controls area that clears any sorting of the table.

    • deselectMultipleButton  adds a button for tables in which multiple rows can be selected, to allow users to deselect all table rows that are currently displayed.

    • deselectSingleButton adds a button for tables in which only a single table row can be selected at a time, to allow users to deselect a column of radio buttons

    • paginateButton adds a button to allow users to switch between viewing all data on a single page (unpaginated) or to see data in multiple pages (paginated).

    • paginationControls adds table pagination controls to allow users to change which page is displayed.

    • selectMultipleButton adds a button that is used for selecting multiple rows. 

    • sortPanelToggleButton  adds a button that is used to open and close the sort panel.

    Cell Spacing and Shading

    The following attribute can be specified to change the spacing and shading weight of the table:

    • cellPadding  specifies the amount of whitespace that should be placed between the cell contents and the cell borders in all the cells of the table.

    • cellSpacing  specifies the amount of whitespace that should be placed between cells, and between the edges of the table content area and the sides of the table.

    • lite  renders the table in a style that makes the table look lighter weight.

    Headers

    The table component allows for multiple headers. The following types of headers are supported:

    • Column header - confined to the column for which it is defined, and displayed by default at the top of the table, below the Action Bar and above all row groups.  Column headers are controlled with attributes in the webuijsf:tableColumn tag. User interface guidelines recommend that column headers are rendered once for each table. In tables with multiple groups, the column headers should be defined in the webuijsf:tableColumn tags that are contained in the first webuijsf:tableRowGroup tag. See the webuijsf:tableColumn documentation for more information.
    • Group header - spans across all table columns, and is displayed above each row group. The first group header is displayed below the column headers, above the table data.  Group headers for any other groups specified in the table are displayed above the data rows for the group. Group headers are set in the webuijsf:tableRowGroup tag.  See the webuijsf:tableRowGroup documentation for more information.

    Footers

    The table component allows for multiple footers. The following types of footers are supported:

    • Footer - spans the full width of the table, and displayed at the bottom of the table. Only one table footer is displayed in each table. The table footer  is defined in the webuijsf:table tag.

    • Column footer - confined to the column for which it is defined, and displayed by default at the bottom of the column. In tables with multiple groups of rows, each group can display its own column footer. The column footer is defined in webuijsf:tableColumn tags. See the webuijsf:tableColumn documentation for more information.

    • Table column footer - confined to the column for which it is defined, and displayed by default near the bottom of the table, below all row groups, and above the Action Bar (bottom). User interface guidelines recommend that table column footers are rendered once for each table. In tables with multiple groups, the table column footers should be defined in the webuijsf:tableColumn tags that are contained in the first webuijsf:tableRowGroup tag. See the webuijsf:tableColumn documentation for more information.

    Facets

    The webuijsf:table tag supports the following facets, which allow you to customize the layout  of the component.


    Facet Name
    Table Item Implemented by the Facet
    actionsBottom Actions area of the Action Bar (bottom).
    actionsTop Actions area of the Action Bar (top).
    filter Drop down menu for selecting a filter, in the Filter area of the Action Bar (top).
    filterPanel Embedded panel for specifying custom filter options, which is displayed when user selects the Custom Filter option from the filter drop down menu. The Custom Filter option is a recommended option that you can provide in the drop down component that you specify in the filter facet.  The Custom Filter can be used to give users greater control over filtering. The Filter example explains filters in more detail.
    footer Footer that spans the width of the table.
    preferencesPanel Panel displayed when the preferences toggle button is clicked, to allow users to specify preferences for viewing the table.
    sortPanel Panel displayed when the sort toggle button is clicked, to allow users to specify sort options.
    title Title in the top bar of the table.

    Client-side JavaScript Functions

    The following JavaScript functions are available in any page that uses the webuijsf:table tag. After the table is rendered, the functions you specify in the JSP page can be invoked directly on the rendered HTML elements. For example:

    var table = document.getElementById("form1:table1");
    var count = table.getAllSelectedRowsCount();

    Note: To use the JavaScript functions, formElements.js file must be included in the page. The file is automatically included by the basic components such as the button and dropDown components.


    Function Name
    Purpose
    confirmSelectedRows(message)
    Confirm the number of selected rows affected by an action such as edit, archive, etc.
    confirmDeleteSelectedRows() Confirm the number of selected rows affected by a delete action.
    filterMenuChanged() Toggle the filter panel when the user selects Custom Filter in the Filter menu.
    getAllSelectedRowsCount() Get the number of selected rows in the table, including the rows that are rendered in the current page, and rows that are hidden from view on other pages.
    getAllHiddenSelectedRowsCount() Get the number of selected rows in the table that are on pages that are not currently displayed.
    getAllRenderedSelectedRowsCount() Get the number of selected rows that are currently rendered in the table. This function does not count the rows that are hidden from view on other pages. Note that rows might be rendered but not visible, and invisible rows are counted.  See the description of the visible and rendered attributes.
    initAllRows() Initialize all rows displayed in the table when the state of selected components change, such as when checkboxes or radiobuttons are used to select or deselect all rows.
    toggleFilterPanel() Open and close the custom filter panel.
    togglePreferencesPanel() Open and close the table preferences panel.

    Notes about webuijsf:table tag

    Life Cycle

    See the Lifecycle description in the documentation for the webuijsf:tableRowGroup component.

    Layout Tables

    You should not use the webuijsf:table tag for page layout. The table component renders elements for a table title, columns headers, and row headers. These elements should not be used in a layout table, and create an accessibility issue.  Use a standard HTML <table> element, a webuijsf:propertySheet tag, or the JavaServer Faces h:dataTable tag to perform page layout. If your application needs to iterate over the same components as in jato:tiledView, use a custom tag.  The JSP Standard Tag Library (JSTL) forEach tag might also be useful, but there are interoperability issues with JSTL and JavaServer Faces, so use with caution.

    Nested Tables

    Although it is technically possible to nest tables with the webuijsf:table tag, you should not use the table component to layout multiple tables for the following reasons:
    • Nested tables create accessibility issues, as described in Layout Tables.

    • UI guidelines do not support nested tables.

    • Styles used by the table component might not display properly because they are not intended to be nested.

    • Table sorting is not supported in nested tables.  The table component does not support complex components that maintain state not defined by the JavaServer Faces EditableValueHolder interface. Since a single component instance is used when iterating over DataProvider rows, only the state of an EditableValueHolder can be maintained.


    If you need to display similar types of data using the same table layout, you should use a group table. Sorting is supported for group tables because they are configured using separate tableRowGroup instances.

    Validation

    To maintain state, the table component submits the surrounding form. For example, when the table is sorted, the form is submitted to update checkbox values. Likewise, the form might be submitted to update text field values when the table component must display a new page of a paginated table.  These components cannot be updated if validation fails for any reason. If a component requires a value to be entered, and no value is entered, validation fails. 

    Consider the case where a required text field and table appear on the same page. If the user clicks on a table sort button while the required text field has no value, the sort action is never invoked because a value was required and validation failed.

    To prevent this validation issue, you can do either of the following:

    • Place the table and the required component in separate forms, to allow the table data to be submitted separately from the required field. The table can then be sorted without triggering a validation failure on a required text field that has no value because the text field's form is not submitted.  However, the values of one form are lost when the other form is submitted, which is expected HTML behavior. In this example, if a user places a value in a required text field and then sorts the table, the value in the text field is lost. 
    • Place the table in a virtual form by setting the internalVirtualForm method of the Table component to true.  For example:

           // Set table component.
          public void setTable(Table table) {
              this.table = table;

              // This binding is used only for the internal virtual form example.
              table.setInternalVirtualForm(true);
          }


      A virtual form allows the table data to be submitted separately from the other components on the page, just as using two separate HTML forms would allow.  Placing the table in a virtual form allows the table sort action to complete because validation for the required text field is not processed. This behavior is similar to that caused by setting the immediate property of a button, but allows table children to be updated so that selected checkbox values may be sorted, for example. The advantage to using a virtual form is that the values of the other components on the page are not lost when table data is submitted.

    Value Bindings

    Value expressions that use DataProviders must use the following syntax:
    #{sourceVar['PERSON.NAME']}
    #{sourceVar.value['PERSON.NAME']}

    Note that the word value is between the DataProvider and the FieldKey to bind. The  brackets [] are required only if the FieldKey contains dot syntax. 

    For example:
    • To bind to a FieldKey named last, where the sourceVar property of the table component is names:

      #{names.value.last}


    • To bind to a property named test, where the backing bean is named TableBean.
    #{TableBean.test}

    Method Bindings

    A JavaServer Faces issue prevents method bindings from working in a DataProvider. To work around the issue, you can bind to a method in a backing bean, and use that method to retrieve values from the DataProvider.

    For example, the following syntax to bind to a DataProvider does not work:

    <webuijsf:hyperlink text="#{name.last}" action="#{name.action}"/>

    Instead of using a DataProvider to handle the action (which breaks the MVC paradigm), bind the action to a method in the backing bean. For example:

    <webuijsf:hyperlink text="#{name.last}" action="#{TableBean.action}"/>

    In the TableBean.action method, you may invoke the following code to retrieve values from the DataProvider:

    public String action() {
        FacesContext context = FacesContext.getCurrentInstance();
        ValueBinding vb = context.getApplication().createValueBinding("#{name.first}");
        String first = (String) (vb.getValue(context));
        return "whatever";
    }


    If you have an instance of the DataProvider, you can also invoke the following code to retrieve values:

    public String action() {
        FacesContext context = FacesContext.getCurrentInstance();
        ValueBinding vb = context.getApplication().createValueBinding("#{name.tableRow}");
        RowKey row = (RowKey) (vb.getValue(context));
        String first = (String) provider.getFieldKey("first"), row)
    }

    Logging

    To see messages logged by the table component, set the following global defaults in your JDK's "jre/lib/logging.properties" file. Alternatively, you can use a different file by specifying a filename with the java.util.logging.config.file system property (e.g., setenv CATALINA_OPTS -Djava.util.logging.config.file=myFile).

    java.util.logging.ConsoleHandler.level = FINE
    com.sun.webui.jsf.event.TablePaginationActionListener.level = FINE
    com.sun.webui.jsf.event.TableSelectPhaseListener.level = FINE
    com.sun.webui.jsf.event.TableSortActionListener.level = FINE
    com.sun.webui.jsf.component.Table.level = FINE
    com.sun.webui.jsf.component.TableActions.level = FINE
    com.sun.webui.jsf.component.TableColumn.level = FINE
    com.sun.webui.jsf.component.TableFooter.level = FINE
    com.sun.webui.jsf.component.TableHeader.level = FINE
    com.sun.webui.jsf.component.TablePanels.level = FINE
    com.sun.webui.jsf.component.TableRowGroup.level = FINE
    com.sun.webui.jsf.renderkit.html.TableActionsRenderer.level = FINE
    com.sun.webui.jsf.renderkit.html.TableColumnRenderer.level = FINE
    com.sun.webui.jsf.renderkit.html.TableFooterRenderer.level = FINE
    com.sun.webui.jsf.renderkit.html.TableHeaderRenderer.level = FINE
    com.sun.webui.jsf.renderkit.html.TablePanelsRenderer.level = FINE
    com.sun.webui.jsf.renderkit.html.TableRenderer.level = FINE
    com.sun.webui.jsf.renderkit.html.TableRowGroupRenderer.level = FINE

    Examples

    The following examples use a backing bean called TableBean and some utility classes, which are included after the examples.  Additional examples are shown in the webuijsf:tableRowGroup and webuijsf:tableColumn documents.

    Examples in this file:

    Example 1: Basic Table

    Example 2: Custom Title in Table

    Example 3: Paginated Table

    Example 4: Table Sort Panel

    Example 5: Table Preferences

    Example 6: Table Filter

    Example 7: Table Actions

    Supporting files:

    TableBean backing bean

    Utility classes used in the examples

    Example 1: Basic Table

    This example shows how to create a basic table.

    <!-- Basic Table -->
    <webuijsf:table id="table1" title="Basic Table">
      <webuijsf:tableRowGroup id="rowGroup1"
          sourceData="#{TableBean.groupB.names}" sourceVar="name">
        <webuijsf:tableColumn id="col1"
            alignKey="last" headerText="Last Name" rowHeader="true">
          <webuijsf:staticText text="#{name.value.last}"/>
        </webuijsf:tableColumn>
        <webuijsf:tableColumn id="col2" alignKey="first" headerText="First Name">
          <webuijsf:staticText text="#{name.value.first}"/>
        </webuijsf:tableColumn>
      </webuijsf:tableRowGroup>
    </webuijsf:table>


    Example 2: Custom Title
    This example shows how to create a custom title for a table, using the title facet. When you use the title attribute as shown in the BasicTable example, the component provides a default title implementation which can include information regarding paginated rows and applied filters. This example implements the title with a webuijsf:staticText tag in the title facet.

    <!-- Custom Title -->
    <webuijsf:table id="table1">
      <webuijsf:tableRowGroup id="rowGroup1"
          sourceData="#{TableBean.groupB.names}" sourceVar="name">
        <webuijsf:tableColumn id="col1"
            alignKey="last" headerText="Last Name" rowHeader="true">
          <webuijsf:staticText text="#{name.value.last}"/>
        </webuijsf:tableColumn>
        <webuijsf:tableColumn id="col2" alignKey="first" headerText="First Name">
          <webuijsf:staticText text="#{name.value.first}"/>
        </webuijsf:tableColumn>
      </webuijsf:tableRowGroup>
      <!-- Title -->
      <f:facet name="title">
        <webuijsf:staticText text="Custom Title"/>
      </f:facet>
    </webuijsf:table>

    Example 3: Paginated Table

    This example shows how to create a paginated table. The default number of rows to be displayed for a paginated table is 25 per page. You can override this value with the rows attribute in the webuijsf:tableRowGroup tag.

    Note: The rows attribute is used only for paginated tables.

    <!-- Paginated Table -->
    <webuijsf:table id="table1"
        paginateButton="true"
        paginationControls="true"
        title="Paginated Table">
      <webuijsf:tableRowGroup id="rowGroup1"
          sourceData="#{TableBean.groupA.names}" sourceVar="name" rows="5">
        <webuijsf:tableColumn id="col1"
            alignKey="last" headerText="Last Name" rowHeader="true">
          <webuijsf:staticText text="#{name.value.last}"/>
        </webuijsf:tableColumn>
        <webuijsf:tableColumn id="col2" alignKey="first" headerText="First Name">
          <webuijsf:staticText text="#{name.value.first}"/>
        </webuijsf:tableColumn>
      </webuijsf:tableRowGroup>
    </webuijsf:table>

    Example 4: Sort Panel

    This example shows how to add the sort panel. You can use the default sort panel by setting the sortPanelToggleButton attribute to true. This button opens an embedded panel in the table, displaying a default implementation.   The default implementation shows one, two, or three drop down menus that represent the primary, secondary, and tertiary sorts. The menus list the column headers for each sortable column. If a column is not sortable, it is not shown as a sortable option. If there are only two sortable columns, only the primary and secondary drop down menus are shown. If there is only one sort, only the primary drop down menu is shown. Next to each sort menu is a menu to select ascending or descending sort order.

    <!-- Sort Panel -->
    <webuijsf:table id="table"
        clearSortButton="true"
        sortPanelToggleButton="true"
        title="Sort Panel">
      <!-- Insert tableRowGroup tag here -->
    </webuijsf:table>


    To override the default sort panel, use the sortPanel facet.  The sort panel toggle button is shown when you use the facet, so you do not need to specify the sortPanelToggleButton attribute.

    Example 5: Table Preferences

    This example shows how to add the preferences toggle button and the table panel. The preferences panel toggle button is shown only when you use the preferencesPanel facet. The button opens an embedded panel in the table, displaying the contents that you provide in the preferencesPanel facet.

    In this example, the preferences panel is used to set the number of paginated rows with the rows attribute of webuijsf:tableRowGroup. See the Preferences.java example utility class, which provides functionality for preferences for this example.

    <!-- Preferences -->
    <webuijsf:table id="table1" paginationControls="true" title="Preferences">
      <webuijsf:tableRowGroup id="rowGroup1"
          rows="#{TableBean.groupA.preferences.rows}"
          sourceData="#{TableBean.groupA.names}"
          sourceVar="name">
        <webuijsf:tableColumn id="col1"
            alignKey="last" headerText="Last Name" rowHeader="true">
          <webuijsf:staticText text="#{name.value.last}"/>
        </webuijsf:tableColumn>
        <webuijsf:tableColumn id="col2" alignKey="first" headerText="First Name">
          <webuijsf:staticText text="#{name.value.first}"/>
        </webuijsf:tableColumn>
      </webuijsf:tableRowGroup>

      <!-- Preferences Panel -->
      <f:facet name="preferencesPanel">
        <f:subview id="preferencesPanel">
          <jsp:include page="preferencesPanel.jsp"/>
        </f:subview>
      </f:facet>
    </webuijsf:table>


    preferencesPanel.jsp

    This example shows the contents of the preferencesPanel.jsp file included in the JSP page example above.

    <!-- Preferences Panel -->
    <webuijsf:textField id="rows"
        columns="5"
        label="Rows Per Page:"
        labelLevel="2"
        onKeyPress="if (event.keyCode==13) {var e=document.getElementById('form1:table1:preferencesPanel:submit'); if (e != null) e.click(); return false}"
        text="#{TableBean.groupA.preferences.preference}"/>
    <webuijsf:markup tag="div" styleClass="#{themeStyles.TABLE_PANEL_BUTTON_DIV}">
      <webuijsf:button id="submit"
          action="#{TableBean.groupA.preferences.applyPreferences}"
          mini="true"
          primary="true"
          text="OK"/>
      <webuijsf:button id="cancel"
          mini="true"
          onClick="togglePreferencesPanel(); return false"
          text="Cancel"/>
    </webuijsf:markup>

    <!-- Note: If the user presses the enter key while the text field has focus,
         the page will be submitted incorrectly, unless we capture the onKeyPress
         event and invoke the click method of the submit button. -->


    preferences.js

    This example shows the contents of the preferences.js file used in the tablePreferencesPanel.jsp  example above. The togglePreferencesPanel() JavaScript function is used with the onClick attribute of a webuijsf:button tag.

    // Use this function to toggle the preferences panel open or closed. This
    // functionality requires the filterId of the table component to be set.
    function togglePreferencesPanel() {
        var table = document.getElementById("form1:table1");
        table.togglePreferencesPanel();
    }

    Example 6: Table Filter

    This example shows how to add filters using a filter drop down menu and the filter panel. In this example, the filter panel is used to set a custom filter. The custom filter removes all rows from the view that do not match the given last name. See the Filter.java example, which provides the  functionality for filters for this example.

    Basic filters are filters that you define for the users of your application. Custom filters enable users to specify the data to be used by the table component to determine which table entries to display.  You specify the basic filter names as items in a webuijsf:dropDown tag in the filter facet. If you want to allow users to use a custom filter, include a "Custom Filter" item as one of the webuijsf:dropDown items.

    If you include a "Custom Filter" item in the Filter drop down menu, you can allow users to open a filter panel to filter the table data using a custom filter.  When the Custom Filter option is selected, an embedded panel in the table is opened, displaying the contents that you provide in the filterPanel facet. The default custom filter functionality requires you to use the filterMenuChanged JavaScript function for the onChange event in the webuijsf:dropDown tag.  After the custom filter is applied, you should display a non-selectable "Custom Filter Applied" item in the filter drop down menu,  to indicate that a custom filter has been applied. You should also set the filterText attribute. The table component updates the table title to indicate that a basic or custom filter has been applied by inserting the text <filterText> Filter Applied.

    The default custom filter functionality depends on a specific value assigned to the Custom Filter item in the dropDown component. The table component provides a method named getFilterOptions() to add the item text and value for the custom filter option to the drop down list. You can use getFilterOptions() in your backing bean to append either the "Custom Filter" or "Custom Filter Applied" item to the basic filter items.

    In the Filter.java util example, the "Custom Filter" and "Custom Filter Applied" items are assigned based on the boolean value provided to getFilterOptions(). If this value is true, the "Custom Filter Applied" item value is added. If the value is false, "Custom Filter" item value is added. The filterMenuChanged JavaScript function, assigned to the dropDown component's onChange event,  behaves differently depending on which item is added.  See the comments in filters.js for more information.

    The default custom filter functionality also depends on the id of the webuijsf:dropDown tag in the filter facet. Note that if you use the webuijsf:dropDown tag as the only component in the filter facet, the filterId is optional. If you use a custom component, or use the webuijsf:dropDown as a child component, you must specify a filterID.

    The table implements functionality to reset the dropDown menu. If you use the filterId attribute, the menu can be reset whenever the sort and preferences toggle buttons are clicked. You can also use the filterMenuChanged JavaScript function to reset the menu at some other time.   Note: This functionality requires the selected value of the webuijsf:dropDown tag to be set in order to restore the default selected value when the embedded filter panel is closed.

    The filter code can be placed in a util class, as shown in the Filter.java example, or in a backing bean.

    <!-- Filter -->
    <webuijsf:table id="table1"
        filterText="#{TableBean.groupA.filter.filterText}"
        paginateButton="true"
        paginationControls="true"
        title="Filter">
      <webuijsf:tableRowGroup id="rowGroup1"
          binding="#{TableBean.groupA.tableRowGroup}"
          rows="5"
          sourceData="#{TableBean.groupA.names}"
          sourceVar="name">
        <webuijsf:tableColumn id="col1"
            alignKey="last" headerText="Last Name" rowHeader="true">
          <webuijsf:staticText text="#{name.value.last}"/>
        </webuijsf:tableColumn>
        <webuijsf:tableColumn id="col2" alignKey="first" headerText="First Name">
          <webuijsf:staticText text="#{name.value.first}"/>
        </webuijsf:tableColumn>
      </webuijsf:tableRowGroup>

      <!-- Filter -->
      <f:facet name="filter">
        <webuijsf:dropDown submitForm="true" id="filter"
            action="#{TableBean.groupA.filter.applyBasicFilter}"
            items="#{TableBean.groupA.filter.filterOptions}"
            onChange="if (filterMenuChanged() == false) return false"
            selected="#{TableBean.groupA.filter.basicFilter}"/>
      </f:facet>

      <!-- Filter Panel -->
      <f:facet name="filterPanel">
        <f:subview id="filterPanel">
          <jsp:include page="filterPanel.jsp"/>
        </f:subview>
      </f:facet>
    </webuijsf:table>


    filterPanel.jsp

    This example shows the contents of the filterPanel.jsp file included in the JSP page in the example above.

    <!-- Filter Panel -->
    <webuijsf:textField id="customFilter"
        columns="50"
        label="Show only rows containing last name:"
        labelLevel="2"
        onKeyPress="if (event.keyCode==13) {var e=document.getElementById('form1:table1:filterPanel:submit'); if (e != null) e.click(); return false}"
        text="#{TableBean.groupA.filter.customFilter}"/>
    <webuijsf:markup tag="div" styleClass="#{themeStyles.TABLE_PANEL_BUTTON_DIV}">
      <webuijsf:button id="submit"
          action="#{TableBean.groupA.filter.applyCustomFilter}"
          mini="true"
          primary="true"
          text="OK"/>
      <webuijsf:button id="cancel"
          mini="true"
          onClick="toggleFilterPanel(); return false"
          text="Cancel"/>
    </webuijsf:markup>

    <!-- Note: If the user presses the enter key while the text field has focus,
         the page will be submitted incorrectly, unless we capture the onKeyPress
         event and invoke the click method of the submit button. -->


    filters.js

    This example shows the contents of the filters.js file used in the filterPanel.jsp
    example above. The toggleFilterPanel() JavaScript function is used with the onClick attribute of a webuijsf:button tag to allow the user to close the filter panel without specifying a filter.

    // Toggle the filter panel from the filter menu.
    //
    // If the "Custom Filter" option has been selected, the filter panel is
    // toggled. In this scenario, false is returned indicating the onChange event,
    // generated by the filter menu, should not be allowed to continue.
    //
    // If the "Custom Filter Applied" option has been selected, no action is taken.
    // Instead, the filter menu is reverted back to the original selection. In this
    // scenario, false is also returned indicating the onChange event, generated by
    // the filter menu, should not be allowed to continue.
    //
    // For all other selections, true is returned indicating the onChange event,
    // generated by the filter menu, should be allowed to continue.
    function filterMenuChanged() {
        var table = document.getElementById("form1:table1");
        return table.filterMenuChanged();
    }

    // Use this function to toggle the filter panel open or closed. This
    // functionality requires the filterId of the table component to be set. In
    // addition, the selected value must be set as well to restore the default
    // selected value when the embedded filter panel is closed.
    function toggleFilterPanel() {
        var table = document.getElementById("form1:table1");
        table.toggleFilterPanel();
    }

    Example 7: Table Actions

    This example shows how to add actions to a table by using the actionsTop and actionsBottom facets. Four buttons and a drop down menu are added to the Action Bar (top) and Action Bar (bottom). When the page is initially displayed, all actions are disabled. When the user selects at least one checkbox, the actions are enabled. If the user deselects all checkboxes, the actions are disabled again.

    Note that this example defines a JavaScript function called disableActions, which is shown in actions.js. The
    disableActions function is defined by the developer, and is not part of the table component.

    When the user clicks on a checkbox, a JavaScript disableActions function is invoked with the onClick event.  The JavaScript setTimeout function is used to ensure checkboxes are selected immediately, instead of waiting for the JavaScript function to complete. See the Actions.java example, which provides functionality for table actions in this example.

    <!-- Actions -->
    <webuijsf:table id="table1"
        deselectMultipleButton="true"
        deselectMultipleButtonOnClick="setTimeout('disableActions()', 0)"
        paginateButton="true"
        paginationControls="true"
        selectMultipleButton="true"
        selectMultipleButtonOnClick="setTimeout('disableActions()', 0)"
        title="Actions">
      <webuijsf:tableRowGroup id="rowGroup1"
          binding="#{TableBean.groupA.tableRowGroup}"
          rows="5"
          selected="#{TableBean.groupA.select.selectedState}"
          sourceData="#{TableBean.groupA.names}"
          sourceVar="name">
        <webuijsf:tableColumn id="col0"
            selectId="select"
            sort="#{TableBean.groupA.select.selectedState}">
          <webuijsf:checkbox id="select"
              onClick="setTimeout('initAllRows(); disableActions()', 0)"
              selected="#{TableBean.groupA.select.selected}"
              selectedValue="#{TableBean.groupA.select.selectedValue}"/>
        </webuijsf:tableColumn>
        <webuijsf:tableColumn id="col1"
            alignKey="last" headerText="Last Name" rowHeader="true">
          <webuijsf:staticText text="#{name.value.last}"/>
        </webuijsf:tableColumn>
        <webuijsf:tableColumn id="col2" alignKey="first" headerText="First Name">
          <webuijsf:staticText text="#{name.value.first}"/>
        </webuijsf:tableColumn>
      </webuijsf:tableRowGroup>

      <!-- Actions (Top) -->
      <f:facet name="actionsTop">
        <f:subview id="actionsTop">
          <jsp:include page="actionsTop.jsp"/>
        </f:subview>
      </f:facet>

      <!-- Actions (Bottom) -->
      <f:facet name="actionsBottom">
        <f:subview id="actionsBottom">
          <jsp:include page="actionsBottom.jsp"/>
        </f:subview>
      </f:facet>
    </webuijsf:table>


    actionsTop.jsp

    This example shows the contents of the actionsTop.jsp file included  in the actionsTop facet in the JSP page in the example above.

    <!-- Actions (Top) -->
    <webuijsf:button id="action1"
        action="#{TableBean.groupA.actions.delete}"
        disabled="#{TableBean.groupA.actions.disabled}"
        onClick="if (confirmDeleteSelectedRows() == false) return false"
        text="Delete"/>
    <webuijsf:button id="action2"
        action="#{TableBean.groupA.actions.action}"
        disabled="#{TableBean.groupA.actions.disabled}"
        onClick="if (confirmSelectedRows() == false) return false"
        text="Action 2"/>
    <webuijsf:button id="action3"
        action="#{TableBean.groupA.actions.action}"
        disabled="#{TableBean.groupA.actions.disabled}"
        onClick="if (confirmSelectedRows() == false) return false"
        text="Action 3"/>
    <webuijsf:button id="action4"
        action="#{TableBean.groupA.actions.action}"
        disabled="#{TableBean.groupA.actions.disabled}"
        onClick="if (confirmSelectedRows() == false) return false"
        text="Action 4"/>
    <webuijsf:dropDown submitForm="true" id="moreActions"
        action="#{TableBean.groupA.actions.moreActions}"
        disabled="#{TableBean.groupA.actions.disabled}"
        items="#{TableBean.groupA.actions.moreActionsOptions}"
        selected="#{TableBean.groupA.actions.moreActions}"/>


    actionsBottom.jsp

    This example shows the contents of the actionsBottom.jsp file included  in the actionsBottom facet in the JSP page in the example above.

    <!-- Actions (Bottom) -->
    <webuijsf:button id="action1"
        action="#{TableBean.groupA.actions.delete}"
        disabled="#{TableBean.groupA.actions.disabled}"
        onClick="if (confirmDeleteSelectedRows() == false) return false"
        text="Delete"/>
    <webuijsf:button id="action2"
        action="#{TableBean.groupA.actions.action}"
        disabled="#{TableBean.groupA.actions.disabled}"
        onClick="if (confirmSelectedRows() == false) return false"
        text="Action 2"/>
    <webuijsf:button id="action3"
        action="#{TableBean.groupA.actions.action}"
        disabled="#{TableBean.groupA.actions.disabled}"
        onClick="if (confirmSelectedRows() == false) return false"
        text="Action 3"/>
    <webuijsf:button id="action4"
        action="#{TableBean.groupA.actions.action}"
        disabled="#{TableBean.groupA.actions.disabled}"
        onClick="if (confirmSelectedRows() == false) return false"
        text="Action 4"/>
    <webuijsf:dropDown submitForm="true" id="moreActions"
        action="#{TableBean.groupA.actions.moreActions}"
        disabled="#{TableBean.groupA.actions.disabled}"
        items="#{TableBean.groupA.actions.moreActionsOptions}"
        selected="#{TableBean.groupA.actions.moreActions}"/>


    select.js

    This example shows the contents of the select.js file used in the example above.

    // Use this function to initialize all rows displayed in the table when the
    // state of selected components change (i.e., checkboxes or radiobuttons used to
    // de/select rows of the table). This functionality requires the selectId
    // property of the tableColumn component to be set.
    //
    // Note: Use setTimeout when invoking this function. This will ensure that
    // checkboxes and radiobutton are selected immediately, instead of waiting for
    // the onClick event to complete. For example:
    //
    // onClick="setTimeout('initAllRows(); disableActions()', 0)"
    function initAllRows() {
        // Disable table actions by default.
        var table = document.getElementById("form1:table1");
        table.initAllRows();
    }


    actions.js

    This example shows the contents of the actions.js file used in the example above.

    // Set disabled state of table actions. If a selection has been made, actions
    // are enabled. If no selection has been made, actions are disabled.
    //
    // Note: Use setTimeout when invoking this function. This will ensure that
    // checkboxes and radiobutton are selected immediately, instead of waiting for
    // the onClick event to complete. For example:
    //
    // onClick="setTimeout('initAllRows(); disableActions()', 0)"
    function disableActions() {
        // Disable table actions by default.
        var table = document.getElementById("form1:table1");
        var selections = table.getAllSelectedRowsCount(); // Hidden & visible selections.
        var disabled = (selections > 0) ? false : true;

        // Set disabled state for top actions.
        document.getElementById("form1:table1:actionsTop:action1").setDisabled(disabled);
        document.getElementById("form1:table1:actionsTop:action2").setDisabled(disabled);
        document.getElementById("form1:table1:actionsTop:action3").setDisabled(disabled);
        document.getElementById("form1:table1:actionsTop:action4").setDisabled(disabled);
        webui.suntheme.dropDown.setDisabled("form1:table1:actionsTop:moreActions", disabled);

        // Set disabled state for bottom actions.
        document.getElementById("form1:table1:actionsBottom:action1").setDisabled(disabled);
        document.getElementById("form1:table1:actionsBottom:action2").setDisabled(disabled);
        document.getElementById("form1:table1:actionsBottom:action3").setDisabled(disabled);
        document.getElementById("form1:table1:actionsBottom:action4").setDisabled(disabled);
        webui.suntheme.dropDown.setDisabled("form1:table1:actionsBottom:moreActions", disabled);
    }

    //
    // Use this function to confirm the number of selected components (i.e.,
    // checkboxes or radiobuttons used to de/select rows of the table), affected by
    // a delete action. This functionality requires the selectId property of the
    // tableColumn component and hiddenSelectedRows property of the tableRowGroup
    // component to be set.
    //
    // If selections are hidden from view, the confirmation message indicates the
    // number of selections not displayed in addition to the total number of
    // selections. If selections are not hidden, the confirmation message indicates
    // only the total selections.
    function confirmDeleteSelectedRows() {
        var table = document.getElementById("form1:table1");
        return table.confirmDeleteSelectedRows();
    }

    // Use this function to confirm the number of selected components (i.e.,
    // checkboxes or radiobuttons used to de/select rows of the table), affected by
    // an action such as edit, archive, etc. This functionality requires the
    // selectId property of the tableColumn component and hiddenSelectedRows
    // property of the tableRowGroup component to be set.
    //
    // If selections are hidden from view, the confirmation message indicates the
    // number of selections not displayed in addition to the total number of
    // selections. If selections are not hidden, the confirmation message indicates
    // only the total selections.
    function confirmSelectedRows() {
        var table = document.getElementById("form1:table1");
        return table.confirmSelectedRows("\n\nArchive all selections?");
    }

    faces_config.xml Entry for Managed Bean

    The previous examples are based on managed beans, such as the example below, added to the faces_config.xml file.

    <!DOCTYPE faces-config PUBLIC
        '-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.0//EN'
        'http://java.sun.com/dtd/web-facesconfig_1_1.dtd'>

    <faces-config>
        <managed-bean>
            <description>The backing bean for the table example</description>
            <managed-bean-name>TableBean</managed-bean-name>
            <managed-bean-class>table.TableBean</managed-bean-class>
            <managed-bean-scope>session</managed-bean-scope>
        </managed-bean>
    </faces-config>

    TableBean

    package table;

    import com.sun.webui.jsf.component.Alarm;

    import java.util.ArrayList;

    import table.util.Group;
    import table.util.Name;

    // Backing bean for table examples.
    public class TableBean {
        // Group util for table examples.
        private Group groupA = null; // List (rows 0-19).
        private Group groupB = null; // Array (rows 0-9).
        private Group groupC = null; // Array (rows 10-19).

        // Alarms.
        private static final Alarm down = new Alarm(Alarm.SEVERITY_DOWN);
        private static final Alarm critical = new Alarm(Alarm.SEVERITY_CRITICAL);
        private static final Alarm major = new Alarm(Alarm.SEVERITY_MAJOR);
        private static final Alarm minor = new Alarm(Alarm.SEVERITY_MINOR);
        private static final Alarm ok = new Alarm(Alarm.SEVERITY_OK);

        // Data for table examples.
        protected static final Name[] names = {
            new Name("William", "Dupont", down),
            new Name("Anna", "Keeney", critical),
            new Name("Mariko", "Randor", major),
            new Name("John", "Wilson", minor),
            new Name("Lynn", "Seckinger", ok),
            new Name("Richard", "Tattersall", down),
            new Name("Gabriella", "Sarintia", critical),
            new Name("Lisa", "Hartwig", major),
            new Name("Shirley", "Jones", minor),
            new Name("Bill", "Sprague", ok),
            new Name("Greg", "Doench", down),
            new Name("Solange", "Nadeau", critical),
            new Name("Heather", "McGann", major),
            new Name("Roy", "Martin", minor),
            new Name("Claude", "Loubier", ok),
            new Name("Dan", "Woodard", down),
            new Name("Ron", "Dunlap", critical),
            new Name("Keith", "Frankart", major),
            new Name("Andre", "Nadeau", minor),
            new Name("Horace", "Celestin", ok),
        };

        // Default constructor.
        public TableBean() {
        }

        // Get Group util created with a List containing all names.
        public Group getGroupA() {
            if (groupA != null) {
                return groupA;
            }
            // Create List with all names.
            ArrayList newNames = new ArrayList();
            for (int i = names.length - 1; i >= 0; i--) {
                newNames.add(names[i]);
            }
            return (groupA = new Group(newNames));
        }

        // Get Group util created with an array containing a subset of names.
        public Group getGroupB() {
            if (groupB != null) {
                return groupB;
            }
            // Create an array with subset of names (i.e., 0-9).
            Name[] newNames = new Name[10];
            System.arraycopy(names, 0, newNames, 0, 10);
            return (groupB = new Group(newNames));
        }

        // Get Group util created with an array containing a subset of names.
        public Group getGroupC() {
            if (groupC != null) {
                return groupC;
            }
            // Create an array with subset of names (i.e., 10-19).
            Name[] newNames = new Name[10];
            System.arraycopy(names, 10, newNames, 0, 10);
            return (groupC = new Group(newNames));
        }
    }

    Utility Classes used in the examples

    The following utility classes are used in the examples for the table tags: webuijsf:table, webuijsf:tableRowGroup, and webuijsf:tableColumn.

    Group.java
    Actions.java
    Filter.java
    Name.java
    Select.java
    Preferences.java

    Group.java Utility Class

    package table.util;

    import com.sun.data.provider.TableDataProvider;
    import com.sun.data.provider.impl.ObjectArrayDataProvider;
    import com.sun.data.provider.impl.ObjectListDataProvider;
    import com.sun.webui.jsf.component.Checkbox;
    import com.sun.webui.jsf.component.TableRowGroup;

    import java.util.List;

    // This class contains data provider and util classes. Note that not all util
    // classes are used for each example.
    public class Group {
        private TableRowGroup tableRowGroup = null; // TableRowGroup component.
        private TableDataProvider provider = null; // Data provider.
        private Checkbox checkbox = null; // Checkbox component.
        private Preferences prefs = null; // Preferences util.
        private Messages messages = null; // Messages util.
        private Actions actions = null; // Actions util.
        private Filter filter = null; // Filter util.
        private Select select = null; // Select util.
        private Clean clean = null; // Clean util.

        // Default constructor.
        public Group() {
            actions = new Actions(this);
            filter = new Filter(this);
            select = new Select(this);
            clean = new Clean(this);
            prefs = new Preferences();
            messages = new Messages();
        }

        // Construct an instance using given Object array.
        public Group(Object[] array) {
            this();
            provider = new ObjectArrayDataProvider(array);
        }

        // Construct an instance using given List.
        public Group(List list) {
            this();
            provider = new ObjectListDataProvider(list);
        }

        // Get data provider.
        public TableDataProvider getNames() {
            return provider;
        }

        // Get Actions util.
        public Actions getActions() {
            return actions;
        }

        // Get Filter util.
        public Filter getFilter() {
            return filter;
        }

        // Get Messages util.
        public Messages getMessages() {
            return messages;
        }

        // Get Preferences util.
        public Preferences getPreferences() {
            return prefs;
        }

        // Get Select util.
        public Select getSelect() {
            return select;
        }

        // Get tableRowGroup component.
        public TableRowGroup getTableRowGroup() {
            return tableRowGroup;
        }

        // Set tableRowGroup component.
        public void setTableRowGroup(TableRowGroup tableRowGroup) {
            this.tableRowGroup = tableRowGroup;
        }

        // Get checkbox component.
        public Checkbox getCheckbox() {
            return checkbox;
        }

        // Set checkbox component.
        public void setCheckbox(Checkbox checkbox) {
            this.checkbox = checkbox;
        }
    }

    Actions.java Utility Class

    package table.util;

    import com.sun.data.provider.FieldKey;
    import com.sun.data.provider.RowKey;
    import com.sun.data.provider.TableDataProvider;
    import com.sun.data.provider.impl.ObjectListDataProvider;
    import com.sun.webui.jsf.model.Option;

    import java.util.List;
    import java.util.Map;

    import javax.faces.context.FacesContext;

    // This class provides functionality for table actions.
    public class Actions {
        private Group group = null; // Group util.

        // Action menu items.
        protected static final Option[] moreActionsOptions = {
            new OptionTitle("More Actions"),
            new Option("ACTION1", "Action 1"),
            new Option("ACTION2", "Action 2"),
            new Option("ACTION3", "Action 3"),
            new Option("ACTION4", "Action 4"),
        };

        // Default constructor.
        public Actions(Group group) {
            this.group = group;
        }

        // Action button event.
        public void action() {
            String message = null;

            // Get hyperlink parameter used for embedded actions example.
            Map map = FacesContext.getCurrentInstance().getExternalContext()
                .getRequestParameterMap();
            String param = (String) map.get("param");
            if (param != null) {
                message = "Embedded Action Selected: Parameter = " + param;
            } else {
                message = "Table Action Selected";
            }

            group.getMessages().setMessage(message);
        }

        // Action to remove rows from ObjectListDataProvider.
        public void delete() {
            // Since mutiple examples are using the same beans, the binding
            // simply tells us that checkbox state is maintained arcoss pages.
            if (group.getSelect().isKeepSelected()) {
                // If we got here, then we're maintaining state across pages.
                delete(group.getTableRowGroup().getSelectedRowKeys());
            } else {
                // If we got here, then we're using the phase listener and must
                // take filtering, sorting, and pagination into account.
                delete(group.getTableRowGroup().getRenderedSelectedRowKeys());
            }
        }

        // Set disabled value for table actions.
        public boolean getDisabled() {
            // If there is at least one row selection, actions are enabled.
            boolean result = true;
            if (group.getTableRowGroup() == null) {
                return result;
            }

            // Since mutiple examples are using the same beans, the binding
            // simply tells us that checkbox state is maintained arcoss pages.
            if (group.getSelect().isKeepSelected()) {
                // If we got here, then we're maintaining state across pages.
                result = group.getTableRowGroup().getSelectedRowsCount() < 1;
            } else {
                // If we got here, then we're using the phase listener and must
                // take filtering, sorting, and pagination into account.
                result = group.getTableRowGroup().getRenderedSelectedRowsCount() < 1;
            }
            return result;
        }

        // Get action.
        public String getMoreActions() {
            // Per the UI guidelines, always snap back to "More Actions...".
            return "ACTION0";
        }

        // Get action menu options.
        public Option[] getMoreActionsOptions() {
            return moreActionsOptions;
        }

        // Action menu event.
        public void moreActions() {
            group.getMessages().setMessage("More Actions Menu Selected");
        }

        // Set action.
        public void setMoreActions(String action) {
            // Do nothing.
        }

        // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        // Private methods
        // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        // Action to remove rows from ObjectListDataProvider.
        private void delete(RowKey[] rowKeys) {
            if (rowKeys == null) {
                return;
            }
            TableDataProvider provider = group.getNames();
            for (int i = 0; i < rowKeys.length; i++) {
                RowKey rowKey = rowKeys[i];
                if (provider.canRemoveRow(rowKey)) {
                    provider.removeRow(rowKey);
                }
            }
            ((ObjectListDataProvider) provider).commitChanges(); // Commit.
            group.getSelect().clear(); // Clear phase listener.
        }
    }

    Filter.java Utility Class

    package table.util;

    import com.sun.data.provider.FilterCriteria;
    import com.sun.data.provider.impl.CompareFilterCriteria;
    import com.sun.webui.jsf.component.Table;
    import com.sun.webui.jsf.model.Option;

    // This class provides functionality for table filters.
    //
    // This util class sets filters directly on the TableRowGroup component using
    // FilterCriteria; however, there is also a FilteredTableDataProvider class that
    // can used for filtering outside of the table. The table will pick up what ever
    // filter has been applied automatically, for example:
    //
    // // Some choice of TableDataProvider.
    // TableDataProvider provider = new ...
    //
    // // This wraps and filters an existing TableDataProvider.
    // FilteredTableDataProvider filteredProvider = new FilteredTableDataProvider();
    // filteredProvider.setTableDataProvider(provider);
    //
    // // Set FilteredTableDataProvider in the TableRowGroup component.
    // tableRowGroup.setSourceData(filteredProvider);
    //
    // The table component itself has no idea that there is any filtering going on,
    // but the filtering functionality has been encapsulated in the data provider.
    // The developer can then use different FilterCriteria types to apply filters,
    // for example:
    //
    // CompareFilterCriteria cfc = new ...
    // RegexFilterCriteria rxfc = new ...
    // filteredProvider.setFilterCriteria(new FilterCriteria[] { cfc, fxfc });
    public class Filter {
        private String customFilter = null; // Custom filter.
        private String basicFilter = null; // Basic filter menu option.
        private String filterText = null; // Filter text.
        private Group group = null; // Group util.

        // Filter menu items.
        protected static final Option[] filterOptions = {
            new Option("FILTER0", "All Items"),
            new Option("FILTER1", "Filter 1"),
            new Option("FILTER2", "Filter 2"),
        };

        // Default constructor.
        public Filter(Group group) {
            this.group = group;
        }

        // UI guidelines state that a "Custom Filter" option should be added to the
        // filter menu, used to open the table filter panel. Thus, if the
        // CUSTOM_FILTER option is selected, Javascript invoked via the onChange
        // event will open the table filter panel.
        //
        // UI guidelines also state that a "Custom Filter Applied" option should be
        // added to the filter menu, indicating that a custom filter has been
        // applied. In this scenario, set the selected property of the filter menu
        // as CUSTOM_FILTER_APPLIED. This selection should persist until another
        // menu option has been selected.
        //
        // Further, UI guidelines state that the table title should indicate that a
        // custom filter has been applied. To add this text to the table title, set
        // the filter property.

        // Basic filter event.
        public void applyBasicFilter() {
            if (basicFilter.equals("FILTER1")) {
                filterText = "Filter 1";
            } else if (basicFilter.equals("FILTER2")) {
                filterText = "Filter 2";
            } else {
                filterText = null;
            }

            // Clear all filters since we don't have an example here.
            //
            // Note: TableRowGroup ensures pagination is reset per UI guidelines.
            group.getTableRowGroup().setFilterCriteria(null);
        }

        // Custom filter event.
        public void applyCustomFilter() {
            basicFilter = Table.CUSTOM_FILTER_APPLIED; // Set filter menu option.
            filterText = "Custom";

            // Filter rows that do not match custom filter.
            CompareFilterCriteria criteria = new CompareFilterCriteria(
                group.getNames().getFieldKey("last"), customFilter);

            // Note: TableRowGroup ensures pagination is reset per UI guidelines.
            group.getTableRowGroup().setFilterCriteria(
                new FilterCriteria[] {criteria});
        }

        // Get basic filter.
        public String getBasicFilter() {
            // Note: the selected value must be set to restore the default selected
            // value when the embedded filter panel is closed. Further, the selected
            // value should never be set as "Custom Filter...".
            return (basicFilter != null && !basicFilter.equals(Table.CUSTOM_FILTER))
                ? basicFilter : "FILTER0";
        }

        // Set basic filter.
        public void setBasicFilter(String value) {
            basicFilter = value;
        }

        // Get custom filter.
        public String getCustomFilter() {
            return customFilter;
        }

        // Set custom filter.
        public void setCustomFilter(String value) {
            customFilter = value;
        }

        // Get filter menu options.
        public Option[] getFilterOptions() {
            // Get filter options based on the selected filter menu option.
            return Table.getFilterOptions(filterOptions,
                basicFilter == Table.CUSTOM_FILTER_APPLIED);
        }

        // Get filter text.
        public String getFilterText() {
            return filterText;
        }
    }

    Name.java Utility Class

    package table.util;

    import com.sun.webui.jsf.component.Alarm;
    import com.sun.webui.jsf.theme.ThemeImages;

    public class Name {
        private String last = null; // Last name.
        private String first = null; // First name.
        private Alarm alarm = null; // Alarm.
       
        // Default constructor.
        public Name(String first, String last) {
            this.last = last;
            this.first = first;
        }

        // Construct an instance with given alarm severity.
        public Name(String first, String last, Alarm alarm) {
            this(first, last);
            this.alarm = alarm;
        }

        // Get first name.
        public String getFirst() {
            return first;
        }

        // Set first name.
        public void setFirst(String first) {
            this.first = first;
        }

        // Get last name.
        public String getLast() {
            return last;
        }

        // Set last name.
        public void setLast(String last) {
            this.last = last;
        }

        // Get alarm.
        public Alarm getAlarm() {
            return alarm;
        }

        // Get alarm.
        public void setAlarm(Alarm alarm) {
            this.alarm = alarm;
        }

        // Get alarm severity.
        public String getSeverity() {
            return alarm.getSeverity();
        }

        // Get alarm severity.
        public void setSeverity(String severity) {
            alarm.setSeverity(severity);
        }
    }

    Select.java Utility Class

    package table.util;

    import com.sun.data.provider.FieldKey;
    import com.sun.data.provider.RowKey;
    import com.sun.data.provider.TableDataProvider;
    import com.sun.webui.jsf.event.TableSelectPhaseListener;

    import javax.faces.context.FacesContext;
    import javax.faces.el.ValueBinding;

    // This class provides functionality for select tables.
    //
    // Note: UI guidelines recomend that rows should be unselected when no longer in
    // view. For example, when a user selects rows of the table and navigates to
    // another page. Or, when a user applies a filter or sort that may hide
    // previously selected rows from view. If a user invokes an action to delete
    // the currently selected rows, they may inadvertently remove rows not
    // displayed on the current page. Using TableSelectPhaseListener ensures
    // that invalid row selections are not rendered by clearing selected state
    // after the render response phase.
    public class Select {
        private TableSelectPhaseListener tspl = null; // Phase listener.
        private Group group = null; // Group util.

        // Default constructor.
        public Select(Group group) {
            this.group = group;
            tspl = new TableSelectPhaseListener();
        }

        // Clear selected state from phase listener (e.g., when deleting rows).
        public void clear() {
            tspl.clear();
        }

        // Test flag indicating that selected objects should not be cleared.
        public boolean isKeepSelected() {
            return tspl.isKeepSelected();
        }

        // Set flag indicating that selected objects should not be cleared.
        public void keepSelected(boolean keepSelected) {
            tspl.keepSelected(keepSelected);
        }

        // Get selected property.
        public Object getSelected() {
        return tspl.getSelected(getTableRow());
        }

        // Set selected property.
        public void setSelected(Object object) {
            RowKey rowKey = getTableRow();
            if (rowKey != null) {
                tspl.setSelected(rowKey, object);
            }
        }

        // Get selected value property.
        public Object getSelectedValue() {
            RowKey rowKey = getTableRow();
            return (rowKey != null) ? rowKey.getRowId() : null;
        }

        // Get the selected state -- Sort on checked state only.
        public boolean getSelectedState() {
            // Typically, selected state is tested by comparing the selected and
            // selectedValue properties. In this example, however, the phase
            // listener value is not null when selected.
            return getSelectedState(getTableRow());
        }

        // Get the selected state.
        public boolean getSelectedState(RowKey rowKey) {
            return tspl.isSelected(rowKey);
        }

        // Get current table row.
        //
        // Note: To obtain a RowKey for the current table row, the use the same
        // sourceVar property given to the TableRowGroup component. For example, if
        // sourceVar="name", use "#{name.tableRow}" as the expression string.
        private RowKey getTableRow() {
            FacesContext context = FacesContext.getCurrentInstance();
            ValueBinding vb = context.getApplication().createValueBinding(
                "#{name.tableRow}");
            return (RowKey) vb.getValue(context);
        }
    }

    Preferences.java Utility Class

    package table.util;

    // This class provides functionality for table preferences.
    public class Preferences {
        private String preference = null; // Rows preference.
        private int rows = 5; // Rows per page.

        // Default constructor.
        public Preferences() {
        }

        // Table preferences event.
        public void applyPreferences() {
            try {
                int rows = Integer.parseInt(preference);
                if (rows > 0) {
                    this.rows = rows;
                }
            } catch (NumberFormatException e) {}
        }

        // Get rows per page.
        public int getRows() {
            return rows;
        }

        // Get preference.
        public String getPreference() {
            return Integer.toString(rows);
        }

        // Set preference.
        public void setPreference(String value) {
            preference = value;
        }
    }

    table2Component that represents a table.
    table2ColumnComponent that represents a table column.
    table2RowGroupComponent that represents a group of table rows.
    tableColumnUse the webuijsf:tableColumn tag to define the column cells of a table, inside a webuijsf:table tag.  A webuijsf:tableRowGroup must include at least one webuijsf:tableColumn tag.

    The webuijsf:table tag is used to define the structure and actions of the table, and is a container for webuijsf:tableRowGroup which define the rows of a table.  The webuijsf:tableRowGroup tag is a container for webuijsf:tableColumn tags, which are used to define the columns of the table.  The documentation for the webuijsf:table tag contains detailed information about the table component.  This page provides details about how to define table columns only.

    HTML Elements and Layout

    The tableColumn component is used to define attributes for XHTML <td> elements, which are used to display table data cells. However, the rendering of column headers and footers is handled by the tableRowGroup component. The diagram shows the table layout, and highlights the areas that are defined with the webuijsf:tableColumn tag.


    Title Bar 
    Action Bar (top)  
    Column Header (specified with headerText attribute or header facet in first webuijsf:tableColumn tag in  webuijsf:tableRowGroup tag) Column Header (specified with headerText attribute or header facet in second webuijsf:tableColumn tag in webuijsf:tableRowGroup tag)
    Group Header Bar 
    Table data




    Table data
    Column Footer (specified with footerText attribute or footer facet in first webuijsf:tableColumn tag in webuijsf:tableRowGroup tag) Column Footer (specified with footerText attribute or footer facet in second webuijsf:tableColumn tag in webuijsf:tableRowGroup tag)
    Group Footer Bar 
    Table Column Footer (specified with tableFooterText attribute or tableFooter facet in webuijsf:tableColumn tag) Table Column Footer (specified with tableFooterText attribute or tableFooter facet in webuijsf:tableColumn tag)
    Action Bar (bottom) 
    Footer

    Column Header

    The Column Header area displays a header for each table column.  If you specify the text of a column header with the headerText attribute in the webuijsf:tableColumn tag, the default implementation of the header is rendered. You can specify a separate component to provide column header content by using the header facet, which overrides the headerText attribute.  You can add extra HTML code to the header's rendered <td> element with the extraHeaderHtml attribute.

    The following webuijsf:tableColumn attributes can be used to change the appearance and behavior for sorting of the Column Header:
    • sort specifies a sort key and makes a column sortable. 

    • sortIcon specifies a theme identifier to select a different image to use as the sort icon that is displayed in the header of a sortable column.

    • sortImageURL specifies the path to an image to use as the sort icon that is displayed in the header of a sortable column.

    • descending when set to true causes the column to be sorted in descending order.

    • severity specifies the severity of an alarm in each cell, and causes the column to  sort on the severity value if used with the sort attribute.

    Column Footer

    The Column Footers area displays a footer for each table column. If you specify the text of a column footer with the footerText attribute in the webuijsf:tableColumn tag, the default implementation of the footer is rendered. You can specify a separate component to provide footer content by using the footer facet, which overrides the footerText attribute.  You can add extra HTML code to the footer's rendered <td> element with the extraFooterHtml attribute.

    Table Column Footer

    The Table Column Footers area displays column footers at the bottom of the table. The table column footers are useful in tables with multiple groups of rows. If you specify the text of table column footers with the tableFooterText attribute, the default implementation of the footer is rendered.  You can specify a separate component to provide the content for a table column footer by using the tableFooter facet, which overrides the tableFooterText attribute.  You can add extra HTML code to the table footer's rendered <td> element with the extraTableFooterHtml attribute.

    Alignment and Formatting of Cells

    In addition to defining the headers and footers for columns, the webuijsf:tableColumn tag can be used to set other aspects of the table's appearance and  behavior. 

    The following attributes affect the alignment of table cells:
    • align specifies the horizontal alignment for the cell data in the column
    • alignKey specifies a particular data element on which to align the cell data
    • valign specifies the vertical alignment for the content of each cell
    Attributes that can be used to make the column headers more accessible for adaptive technologies include:
    • scope set to a keyword to specify the portion of the table that this header applies to.
    • rowHeader set to true to specify that the content of the column's cells applies to the row in which the cell is located.
    Attributes that affect other aspects of cells include:
    • abbr  specifies an abbreviated form of the cell's content, to be used when the browser has little space to render the content.
    • embeddedActions when set to true causes separators to be rendered between multiple action hyperlinks.
    • emptyCell when set to true causes an unexpectedly empty cell to be rendered with an appropriate image.
    • spacerColumn when set to true causes the column to be rendered as a blank column to enhance table spacing.
    • height specifies the height of a column's cells.
    • width specifies the width of a column's cells.
    • nowrap prevents the content of the cell from wrapping to a new line.

    Selection Column

    To make table rows selectable, the first column of the table should display only checkboxes or radio buttons that the user clicks to select the row. When you set the selectId attribute in the webuijsf:tableColumn tag and include a webuijsf:checkbox or webuijsf:radioButton tag as a child of the webuijsf:tableColumn tag, the first column is rendered appropriately.  See the Select Single Row example for more information.

    Facets

    The webuijsf:tableColumn tag supports the following facets, which allow you to customize the layout of the component.

    Facet Name
    Table Item Implemented by the Facet
    footer         
    Footer that is displayed at the bottom of the column within the group of rows. The footer applies to the column of cells that are defined by the webuijsf:tableColumn tag.  This facet can be used to replace the default footer for the column.
    header Header that applies to the column of cells that are defined by the webuijsf:tableColumn tag. This facet can be used to replace the default header for the column.
    tableFooter
    Footer that is displayed at the bottom of the table, below the last group of rows, above the Action Bar and overall table footer. The table footer content should apply to the column for all the groups of rows in the table.  This facet can be used to replace the default table footer for the column.

    Client Side JavaScript Functions

    See the webuijsf:table tag's JavaScript documentation.  The same functions are used for the webuijsf:tableColumn tag.

    Examples

    The following examples use a backing bean called TableBean, which is shown in the webuijsf:table tag documentation. Utility classes used in the examples are included in this page, after the examples.  Additional examples are shown in the webuijsf:table and webuijsf:tableRowGroup documents.

    All examples assume that the webuijsf:table tag is contained within an HTML <form> element so that actions can submit form data.

    Examples in this file:

    Example 1: Sortable Table

    Example 2: Select Single Row

    Example 3: Select Multiple Rows

    Example 4: Hidden Selected Rows

    Example 5: Spacer Columns

    Example 6: Empty Cells

    Example 7:  Embedded Actions

    Example 8: Alarms

    Example 9: Multiple Column Headers and Footers

    Supporting files:

    TableBean backing bean in webuijsf:table documentation

    Utility classes in webuijsf:table documentation

    Example 1: Sortable Table

    This example shows how to implement table sorting, and uses the TableBean and Name.java code shown in the webuijsf:table documentation. Notice that the webuijsf:table tag includes the clearSortButton attribute to enable users to clear any sorts applied to the table.

    The value binding objects that you assign to the sort attribute in webuijsf:tableColumn must be the proper data type for sorting to work as expected. For example, you should not use String objects for numeric data because the digits will be sorted according to their ASCII values. Sorting the numbers as strings causes the number 2 to be displayed before the number 11, for example.  Be sure to sort using objects such as Number, Character, Date, Boolean, etc.


    You can use a FieldKey id or value binding to define criteria for sorting the contents of TableDataProvider. However, when sorting a column of checkboxes or radio buttons, you must use a value binding because values are external to the data (i.e., TableDataProvider does not contain FieldKey ids for a selected checkbox value). 

    User interface guidelines recommend not setting a default initial sort. However, if you want to set a default initial sort, you can do so by using the addSort(SortCriteria) method of TableRowGroup. When the table is rendered, the data is sorted and the primary sort column is highlighted. 


    <!-- Sortable Table -->
    <webuijsf:table id="table1"
        clearSortButton="true"
        sortPanelToggleButton="true"
        title="Sortable Table">
      <webuijsf:tableRowGroup id="rowGroup1"
          sourceData="#{TableBean.groupB.names}" sourceVar="name">
        <webuijsf:tableColumn id="col1"
            alignKey="last"
            headerText="Last Name"
            rowHeader="true"
            sort="last">
          <webuijsf:staticText text="#{name.value.last}"/>
        </webuijsf:tableColumn>
        <webuijsf:tableColumn id="col2"
            alignKey="first"
            headerText="First Name"
            sort="first">
          <webuijsf:staticText text="#{name.value.first}"/>
        </webuijsf:tableColumn>
      </webuijsf:tableRowGroup>
    </webuijsf:table>

    Example 2: Select Single Row

    This example shows a column of radioButton components that are used to select a single table row. Dynamic row highlighting is set by invoking an initAllRows() JavaScript function whenever the state of the radio button changes. The initAllRows() function is defined in select.js shown below. The radio button state is maintained through the selected attribute of the webuijsf:tableRowGroup tag. This example does not maintain state across paginated pages.

    Note: UI guidelines recommend that items should not remain selected when they cannot be seen by the user. Using the com.sun.webui.jsf.event.TableSelectPhaseListener object ensures that rows that are hidden from view are deselected because the phase listener clears the selected state after the rendering phase. The TableSelectPhaseListener object is used in this example in Select.java in the webuijsf:table documentation.  Also refer to the JavaDoc for TableSelectPhaseListener for more information. 

    <!-- Single Select Row -->
    <webuijsf:table id="table1"
        deselectSingleButton="true"
        paginateButton="true"
        paginationControls="true"
        title="Select Single Row">
      <webuijsf:tableRowGroup id="rowGroup1"
          selected="#{TableBean.groupA.select.selectedState}"
          sourceData="#{TableBean.groupA.names}"
          sourceVar="name" rows="5">
        <webuijsf:tableColumn id="col0"
            onClick="setTimeout('initAllRows()', 0)"
            selectId="select"
            sort="#{TableBean.groupA.select.selectedState}">
          <webuijsf:radioButton id="select"
              name="select"
              selected="#{TableBean.groupA.select.selected}"
              selectedValue="#{TableBean.groupA.select.selectedValue}"/>
        </webuijsf:tableColumn>
        <webuijsf:tableColumn id="col1"
            alignKey="last" headerText="Last Name" rowHeader="true">
          <webuijsf:staticText text="#{name.value.last}"/>
        </webuijsf:tableColumn>
        <webuijsf:tableColumn id="col2" alignKey="first" headerText="First Name">
          <webuijsf:staticText text="#{name.value.first}"/>
        </webuijsf:tableColumn>
      </webuijsf:tableRowGroup>
    </webuijsf:table>


    select.js

    This example shows the contents of the select.js file used in the example above.

    // Use this function to initialize all rows displayed in the table when the
    // state of selected components change (i.e., checkboxes or radiobuttons used to
    // de/select rows of the table). This functionality requires the selectId
    // property of the tableColumn component to be set.
    //
    // Note: Use setTimeout when invoking this function. This will ensure that
    // checkboxes and radiobutton are selected immediately, instead of waiting for
    // the onClick event to complete. For example:
    //
    // onClick="setTimeout('initAllRows(); disableActions()', 0)"
    function initAllRows() {
        // Disable table actions by default.
        var table = document.getElementById("form1:table1");
        table.initAllRows();
    }

    Example 3: Select Multiple Rows

    This example shows a column of checkbox components that are used to select multiple table rows. Dynamic row highlighting is set by invoking an initAllRows() JavaScript function whenever the state of the checkbox changes. The initAllRows() function is defined in  select.js in the previous example. The checkbox state is maintained through the selected attribute of the webuijsf:tableRowGroup tag. This example does not maintain state across paginated pages.

    Note: UI guidelines recommend that items should not remain selected when they cannot be seen by the user. Using the com.sun.webui.jsf.event.TableSelectPhaseListener object ensures that rows that are hidden from view are deselected because the phase listener clears the selected state after the rendering phase. The TableSelectPhaseListener object is used in this example in
    Select.java, shown in the webuijsf:table documentation.  Also refer to the JavaDoc for TableSelectPhaseListener for more information. 

    <!-- Select Multiple Rows -->
    <webuijsf:table id="table1"
        deselectMultipleButton="true"
        selectMultipleButton="true"
        paginateButton="true"
        paginationControls="true"
        title="Select Multiple Rows">
      <webuijsf:tableRowGroup id="rowGroup1"
          selected="#{TableBean.groupA.select.selectedState}"
          sourceData="#{TableBean.groupA.names}"
          sourceVar="name" rows="5">
        <webuijsf:tableColumn id="col0"
            selectId="select" sort="#{TableBean.groupA.select.selectedState}">
          <webuijsf:checkbox id="select"
              onClick="setTimeout('initAllRows()', 0)"
              selected="#{TableBean.groupA.select.selected}"
              selectedValue="#{TableBean.groupA.select.selectedValue}"/>
        </webuijsf:tableColumn>
        <webuijsf:tableColumn id="col1"
            alignKey="last" headerText="Last Name" rowHeader="true">
          <webuijsf:staticText text="#{name.value.last}"/>
        </webuijsf:tableColumn>
        <webuijsf:tableColumn id="col2" alignKey="first" headerText="First Name">
          <webuijsf:staticText text="#{name.value.first}"/>
        </webuijsf:tableColumn>
      </webuijsf:tableRowGroup>
    </webuijsf:table>

    Example 4: Hidden Selected Rows

    This example is the same as Example 3: Select Multiple Rows except that it maintains state across paginated pages, and shows how to deal appropriately with the possibility of hiding rows that have been selected.  As in the previous example, the first column is a column of checkboxes that can be used to select multiple rows. The checkbox state is maintained through the selected attribute of the webuijsf:tableRowGroup tag.  Dynamic row highlighting is set by invoking an initAllRows() JavaScript function whenever the state of the checkbox changes. The initAllRows() function is defined in  select.js in the previous example.

    If your table must maintain state, you must set the hiddenSelectedRows attribute to true in the webuijsf:table tag as shown in this example. The attribute causes text to be displayed in the table title and footer to indicate the number of selected rows that are currently hidden from view.  See the Select.java utility class in the webuijsf:table documentation.

    <!-- Hidden Selected Rows -->
    <webuijsf:table id="table1"
        deselectMultipleButton="true"
        deselectMultipleButtonOnClick="setTimeout('disableActions()', 0)"
        hiddenSelectedRows="true"
        paginateButton="true"
        paginationControls="true"
        selectMultipleButton="true"
        selectMultipleButtonOnClick="setTimeout('disableActions()', 0)"
        title="Hidden Selected Rows">
      <webuijsf:tableRowGroup id="rowGroup1"
          binding="#{TableBean.groupA.tableRowGroup}"
          selected="#{TableBean.groupA.select.selectedState}"
          sourceData="#{TableBean.groupA.names}"
          sourceVar="name" rows="5">
        <webuijsf:tableColumn id="col0"
            selectId="select"
            sort="#{TableBean.groupA.select.selectedState}">
          <webuijsf:checkbox id="select"
              binding="#{TableBean.groupA.checkbox}"
              onClick="setTimeout('initAllRows(); disableActions()', 0)"
              selected="#{TableBean.groupA.select.selected}"
              selectedValue="#{TableBean.groupA.select.selectedValue}"/>
        </webuijsf:tableColumn>
        <webuijsf:tableColumn id="col1"
            alignKey="last" headerText="Last Name" rowHeader="true">
          <webuijsf:staticText text="#{name.value.last}"/>
        </webuijsf:tableColumn>
        <webuijsf:tableColumn id="col2" alignKey="first" headerText="First Name">
          <webuijsf:staticText text="#{name.value.first}"/>
        </webuijsf:tableColumn>
      </webuijsf:tableRowGroup>

      <!-- Actions (Top) -->
      <f:facet name="actionsTop">
        <f:subview id="actionsTop">
          <jsp:include page="actionsTop.jsp"/>
        </f:subview>
      </f:facet>

      <!-- Actions (Bottom) -->
      <f:facet name="actionsBottom">
        <f:subview id="actionsBottom">
          <jsp:include page="actionsBottom.jsp"/>
        </f:subview>
      </f:facet>
    </webuijsf:table>

    Example 5: Spacer Column

    This example shows how to create a blank column to use for spacing in a table. The spacer column is especially useful in two-column tables. A property table, which is used to display properties for a single object, typically includes two data columns. The first column identifies the properties of the object, and the second column displays the values for each of the properties. Because tables created with the webuijsf:table tag expand to the width of the browser window, the two data columns might become so wide that the properties and their values are not close together, and readability is reduced. To solve this problem, you can add a spacer column to one side of the table.

    In the example, the third column includes the spacerColumn attribute set to true, and the width attribute set to 70%. The column has no header or footer text, and no data. This column acts to always keep the data of the first two columns in close proximity.  If a column header and footer are required, provide an empty string for the headerText and footerText attributes. Set the width attribute to a value that achieves the desired spacing.


    <!-- Spacer Column -->
    <webuijsf:table id="table1" title="Spacer Column">
      <webuijsf:tableRowGroup id="rowGroup1"
          sourceData="#{TableBean.groupB.names}" sourceVar="name">
        <webuijsf:tableColumn id="col1"
            alignKey="last"
            footerText="Column Footer"
            headerText="Last Name"
            rowHeader="true">
          <webuijsf:staticText text="#{name.value.last}"/>
        </webuijsf:tableColumn>
        <webuijsf:tableColumn id="col2"
            alignKey="first"
            footerText="Column Footer"
            headerText="First Name">
          <webuijsf:staticText text="#{name.value.first}"/>
        </webuijsf:tableColumn>
        <webuijsf:tableColumn id="col3" spacerColumn="true" width="70%"/>
      </webuijsf:tableRowGroup>
    </webuijsf:table>

    Example 6: Empty Cells

    This example shows how to display a theme-specific icon that indicates an empty cell, when the content of a table cell is not applicable or is unexpectedly empty. UI guidelines suggest that the empty cell icon should not be used for a value that is truly null, such as an empty alarm cell or a comment field that is blank. In addition, the icon should not be used for cells that contain user interface elements such as checkboxes or drop-down lists when these elements are not applicable. Instead, the elements should not be displayed so the cell is left empty.

    In this example, the emptyCell attribute is set to an expression that evaluates to true in every fifth row. In your application, it is up to you to decide how to test if the cell is truly empty. For example, you could use this syntax: emptyCell="#{name.value.last == null}"

    <!-- Empty Cells -->
    <webuijsf:table id="table1" title="Empty Cells">
      <webuijsf:tableRowGroup id="rowGroup1"
          selected="#{TableBean.groupB.select.selectedState}"
          sourceData="#{TableBean.groupB.names}"
          sourceVar="name" rows="5">
        <webuijsf:tableColumn id="col0"
            emptyCell="#{name.tableRow.rowId % 5 == 0}"
            selectId="select">
          <webuijsf:checkbox id="select"
              onClick="setTimeout('initAllRows()', 0)"
              selected="#{TableBean.groupB.select.selected}"
              selectedValue="#{TableBean.groupB.select.selectedValue}"/>
        </webuijsf:tableColumn>
        <webuijsf:tableColumn id="col1"
            emptyCell="#{name.tableRow.rowId % 5 == 0}"
            alignKey="last"
            headerText="Last Name"
            rowHeader="true">
          <webuijsf:staticText text="#{name.value.last}"/>
        </webuijsf:tableColumn>
        <webuijsf:tableColumn id="col2"
            emptyCell="#{name.tableRow.rowId % 5 == 0}"
            alignKey="first"
            headerText="First Name">
          <webuijsf:staticText text="#{name.value.first}"/>
        </webuijsf:tableColumn>
      </webuijsf:tableRowGroup>
    </webuijsf:table>

    Example 7: Embedded Actions

    This example shows how to add embedded actions to a table. If the webuijsf:tableColumn tag contains more than one tag such as webuijsf:hyperlink that are used as embedded actions, you should set the webuijsf:tableColumn tag's embeddedActions attribute to true. This attribute causes an action separator image to be displayed between each of the rendered hyperlinks, as recommended in UI guidelines.

    <!-- Embedded Actions -->
    <webuijsf:table id="table1" title="Embedded Actions">
      <webuijsf:tableRowGroup id="rowGroup1"
          sourceData="#{TableBean.groupB.names}" sourceVar="name">
        <webuijsf:tableColumn id="col0" embeddedActions="true" headerText="Actions">
          <webuijsf:hyperlink id="action1"
              action="#{TableBean.groupB.actions.action}"
              text="Action 1">
            <f:param name="param" value="#{name.value.last}"/>
          </webuijsf:hyperlink>
          <webuijsf:hyperlink id="action2"
              action="#{TableBean.groupB.actions.action}"
              text="Action 2">
            <f:param name="param" value="#{name.tableRow.rowId}"/>
          </webuijsf:hyperlink>
        </webuijsf:tableColumn>
        <webuijsf:tableColumn id="col1"
            alignKey="last" headerText="Last Name" rowHeader="true">
          <webuijsf:staticText text="#{name.value.last}"/>
        </webuijsf:tableColumn>
        <webuijsf:tableColumn id="col2" alignKey="first" headerText="First Name">
          <webuijsf:staticText text="#{name.value.first}"/>
        </webuijsf:tableColumn>
      </webuijsf:tableRowGroup>
    </webuijsf:table>

    Example 8: Alarms

    This example shows how to add alarms to table data cells. The second webuijsf:tableColumn tag includes a webuijsf:alarm tag to render the alarm icon. The webuijsf:tableColumn tag's severity  attribute is set to true, which causes the table data cell to appear highlighted according to level of severity.  Note also that the column is set to sort on the severity of the alarms. See the TableBean backing bean and  Name.java utlity class example in the webuijsf:table documentation for the model data.

    <!-- Alarms -->
    <webuijsf:table id="table1" title="Alarms">
      <webuijsf:tableRowGroup id="rowGroup1"
          sourceData="#{TableBean.groupB.names}" sourceVar="name">
        <webuijsf:tableColumn id="col1"
            alignKey="last"
            headerText="Last Name"
            rowHeader="true"
            sort="last">
          <webuijsf:staticText text="#{name.value.last}"/>
        </webuijsf:tableColumn>
        <webuijsf:tableColumn id="col2"
            alignKey="first"
            headerText="First Name"
            severity="#{name.value.severity}"
            sort="alarm">
          <webuijsf:alarm id="alarm" severity="#{name.value.severity}" text="#{name.value.first}"/>
        </webuijsf:tableColumn>
      </webuijsf:tableRowGroup>
    </webuijsf:table>

    Example 9: Multiple Column Headers & Footers

    This example shows how to use nested tableColumn components to create multiple headers and footers. The column header of the parent tableColumn component will span the nested tableColumn children. Not all attributes are supported in this configuration. Typically, only the header, footer, tableFooter, and sort would apply to a header and spaning multuple columns. Sorting is supported, but is recommended only for tableColumn children. Further, nesting tableColumn components will render; however, the styles used here support one level of nexting.

    This example shows how to use nested webuijsf:tableColumn tags to create multiple headers and footers. The third webuijsf:tableColumn (col3) contains four nested columns col3a, col3b, col3c, and col3d. The column header specified in col3 spans the four nested columns.  However, not all webuijsf:tableColumn attributes are supported when the tags are nested. Typically, only the header, footer, tableFooter, and sort would apply to a header and spaning multiple columns. Sorting in the parent tableColumn is supported, but for usability, sorting is recommended only for tableColumn children. In addition, nesting of more than one level of tableColumn components will render, but the CSS styles only support one level of nesting.   

    <!-- Multiple Headers &amp; Footers -->
    <webuijsf:table id="table1"
        clearSortButton="true"
        deselectMultipleButton="true"
        deselectMultipleButtonOnClick="setTimeout('disableActions()', 0)"
        footerText="Table Footer"
        paginateButton="true"
        paginationControls="true"
        selectMultipleButton="true"
        selectMultipleButtonOnClick="setTimeout('disableActions()', 0)"
        sortPanelToggleButton="true"
        title="Multiple Headers &amp; Footers">
      <webuijsf:tableRowGroup id="rowGroup1"
          binding="#{TableBean.groupA.tableRowGroup}"
          rows="#{TableBean.groupA.preferences.rows}"
          selected="#{TableBean.groupA.select.selectedState}"
          sourceData="#{TableBean.groupA.names}"
          sourceVar="name">
        <webuijsf:tableColumn id="col0"
            selectId="select"
            sort="#{TableBean.groupA.select.selectedState}">
          <webuijsf:checkbox id="select"
              onClick="setTimeout('initAllRows(); disableActions()', 0)"
              selected="#{TableBean.groupA.select.selected}"
              selectedValue="#{TableBean.groupA.select.selectedValue}"/>
        </webuijsf:tableColumn>
        <webuijsf:tableColumn id="col1"
            alignKey="last"
            headerText="Last Name"
            rowHeader="true">
          <webuijsf:staticText text="#{name.value.last}"/>
        </webuijsf:tableColumn>
        <webuijsf:tableColumn id="col2"
            alignKey="first" headerText="First Name">
          <webuijsf:staticText text="#{name.value.first}"/>
        </webuijsf:tableColumn>
        <webuijsf:tableColumn id="col3" headerText="Task Status">
         
          <!-- Nested Columns -->
          <webuijsf:tableColumn id="col3a"
              headerText="A"
              footerText="ColFtrA"
              sort="last"
              sortIcon="ALARM_CRITICAL_MEDIUM"
              tableFooterText="TblFtrA">
            <webuijsf:staticText text="a"/>
          </webuijsf:tableColumn>
          <webuijsf:tableColumn id="col3b"
              headerText="B"
              footerText="ColFtrB"
              sort="first"
              sortIcon="ALARM_MAJOR_MEDIUM"
              tableFooterText="TblFtrB">
            <webuijsf:staticText text="b"/>
          </webuijsf:tableColumn>
          <webuijsf:tableColumn id="col3c"
              headerText="C"
              footerText="ColFtrC"
              sortIcon="ALARM_MINOR_MEDIUM"
              tableFooterText="TblFtrC">
            <webuijsf:staticText text="c"/>
          </webuijsf:tableColumn>
          <webuijsf:tableColumn id="col3d"
              headerText="D"
              footerText="ColFtrD"
              sortIcon="ALARM_DOWN_MEDIUM"
              tableFooterText="TblFtrD">
            <webuijsf:staticText text="d"/>
          </webuijsf:tableColumn>
        </webuijsf:tableColumn>
      </webuijsf:tableRowGroup>
    </webuijsf:table>

    faces_config.xml Entry for Managed Beans

    The examples use the TableBean managed bean, which requires the following entry to be added to the faces_config.xml file.

    <!DOCTYPE faces-config PUBLIC
        '-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.0//EN'
        'http://java.sun.com/dtd/web-facesconfig_1_1.dtd'>

    <faces-config>
        <managed-bean>
            <description>The backing bean for the table example</description>
            <managed-bean-name>TableBean</managed-bean-name>
            <managed-bean-class>table.TableBean</managed-bean-class>
            <managed-bean-scope>session</managed-bean-scope>
        </managed-bean>
    </faces-config>

    tableRowGroup/** Use the webuijsf:tableRowGroup tag to define the rows of a table, inside a webuijsf:table tag.  A table must include at least one tableRowGroup component to contain the table row content.

    The webuijsf:table tag is used to define the structure and actions of the table, and is a container for webuijsf:tableRowGroup tags.  The webuijsf:tableRowGroup tag is a container for webuijsf:tableColumn tags, which are used to define the columns of the table.  The documentation for the webuijsf:table tag contains detailed information about the table component.  This page provides details about how to create table rows only.

    When you use one webuijsf:tableRowGroup tag in the webuijsf:table tag, you create a basic table.  Examples of basic tables are shown in the webuijsf:table tag documentation. When you use multiple webuijsf:tableRowGroup tags, you create a group table, which is discussed in detail in this document.

    HTML Elements and Layout

    The tableRowGroup component is used to define attributes for XHTML <tr>   elements, which are used to display rows of data. You can specify multiple webuijsf:tableRowGroup tags to create groups of rows. Each group is visually separate from the other groups, but all rows of the table can be sorted and filtered at once, within their respective groups.

    UI guidelines recommend that column headers and table column footers are only rendered once for each table. Column headers typically appear at the top of the table, below the Action Bar and above all row groups. Table column footers appear only at the bottom of the table, below all row groups. The column headers and table column footers are defined in the headerText and tableFooterText attributes of the webuijsf:tableColumn tags. To ensure that these headers and footers are rendered only once, you should define the  headerText and tableFooterText attributes only in the webuijsf:tableColumn tags inside the first webuijsf:tableRowGroup tag in the table.  See the
    webuijsf:tableColumn documentation for more information.

    The following diagram shows the placement of the areas of a table, and highlights the areas that are defined with webuijsf:tableRowGroup tags. This diagram depicts two row groups.



    Title Bar 
    Action Bar (top)  
    Column Header
    Column Header
    Group Header Bar (specified with headerText attribute and header facet in first webuijsf:tableRowGroup tag)
    Table data specified in webuijsf:tableRowGroup



    Table data specified in webuijsf:tableRowGroup
    Column Footer Column Footer
    Group Footer Bar 
    Group Header Bar
    Table data specified in webuijsf:tableRowGroup




    Table data specified in webuijsf:tableRowGroup
    Column Footer
    Column Footer
    Group Footer Bar
    Table Column Footer Table Column Footer
    Action Bar (bottom) 
    Footer

    Group Header Bar

    The Group Header Bar displays a header by default at the top of each group of rows.  The text of the group header is specified with the headerText attribute. You can specify a separate component to provide header content by using the header facet, which overrides the headerText attribute.  You can use the following webuijsf:tableRowGroup attributes to change the appearance of the group header:
    • aboveColumnHeader set to true makes the group header display above the column header.

    • selectMultipleToggleButton set to true adds a checkbox that allows users to select and deselect all rows in the group

    • collapsed set to true causes the group to be rendered with the rows hidden, and only the group header is visible. 

    • groupToggleButton set to true adds a button image that allows users to expand and collapse the group of rows. When the group collapses, all the rows are hidden and only the header is visible.

    • extraHeaderHtml can be used to append HTML code to the <tr> element that is rendered for the group header

    Note: Detailed descriptions of the attributes are in the attributes table at the end of this document.

    Group Footer Bar

    The Group Footer Bar displays an optional footer below each group of rows. The text of the group footer is specified with the footerText attribute. You can specify a separate component to provide the footer content by using the footer facet, which overrides the footerText attribute.  You can use the following webuijsf:tableRowGroup attributes to change the appearance of the group footer:

    • aboveColumnFooter set to true makes the group footer display above the column footer.
    •  extraFooterHtml can be used to append HTML code to the <tr> element that is rendered for the group footer

    Table Data

    The table data is specified with the sourceData and sourceVar attributes. The sourceData attribute specifies the source of the data that populates the table. The sourceVar attribute specifies the name of the request-scope variable to use for exposing the model data when iterating over table rows. Each table in a JSP page must use a unique sourceVar value. See the Life Cycle section for more information about these attributes.   

    Facets

    The webuijsf:tableRowGroup tag supports the following facets, which allow you to customize the layout  of the component.

    Facet Name
    Table Item Implemented by the Facet
    footer         
    Footer that applies to the group of rows defined by the webuijsf:tableRowGroup tag.  This facet can be used to  replace the default footer.
    header Header that applies to the group of rows defined by the webuijsf:tableRowGroup tag. This facet can be used to replace the default header.

    Client Side JavaScript Functions

    See the webuijsf:table tag's JavaScript documentation.  The same functions are used for the webuijsf:tableRowGroup tag.

    Notes for the webuijsf:tableRowGroup tag

    All examples assume that the webuijsf:table tag is contained within a HTML <form> element so actions can submit form data. For basic table and sort examples, see the webuijsf:table tag documentation and webuijsf:tableColumn documentation.

    Life Cycle

    The sourceData property of tableRowGroup is invoked at least twice during the JavaServer Faces life cycle. The sourceData is invoked once during one of the Apply Request Values, Process Validations, or Update Model Values phases, and once during the Render Response phase. In order to process the previously displayed children during the Apply Request Values, Process Validations, or Update Model Values phases, the table must use the same DataProvider that was used to render the previous page. For example, suppose that sorting, filtering, and pagination were applied on the previous page, and rows 10-20 of 1000 were currently displayed. You want to update only the currently displayed components, rows 10-20. To do this, you must not update the DataProvider until the Invoke Application phase or Render Response phases, when it is safe to render new data.

    Note that if the underlying DataProvider has changed in any way, processing of the previously displayed children might not be possible during the Apply Request Values, Process Validations, or Update Model Values phases. In addition, if the DataProvider is null or empty, no children will be processed and their processDecodes(), processValidators(), and processUpdates() methods will not be invoked. If a component has not been decoded (in the Apply Request Values phase), action events might not be received and component properties such as hyperlink query parameters cannot be retrieved.  Also, if a component has not been updated (in the Update Model Values phase), submitted values cannot be retrieved for checkboxes, radio buttons, etc.

    When obtaining data is expensive, consider caching the DataProvider. A cached DataProvider persists across requests if the backing bean uses session scope, or if the application uses server-side state saving and the TableRowGroup.setSourceData method is set. Note that a phase listener may be used to initialize the DataProvider during the Invoke Application Phase. However, when the underlying DataProvider has changed in any way, UI guidelines recommend that pagination is reset to the first page. You can use the tableRowGroup component's setFirst() method to set the first row to be displayed.

    Examples

    The following examples use a backing bean called TableBean, which is shown in the webuijsf:table tag documentation. Utility classes used in the examples are included in this webuijsf:tableRowGroup page, after the examples.  Additional examples are shown in the webuijsf:table and webuijsf:tableColumn documents.

    Examples in this file:

    Example 1: Group Table

    Example 2: Dynamic Table

    Example 3: Dynamic Group Table

    Supporting files:

    TableBean backing bean in webuijsf:table documentation

    Utility classes used in the examples

    Example 1: Group Table

    This example shows how to create a group table. A group table contains rows of data that are arranged in discrete sections or groups within the table.  In a basic table, each column typically has a header and perhaps a footer. However, in a group table, each group of rows can have its own header and footer. In addition, a group table can display table column footers and an overall table footer below all data groups.  The table column footers are specified in webuijsf:tableColumn tags and the overall footer is specified in the webuijsf:table tag. See the diagram of the table areas.

    Additional attributes should be used in the webuijsf:tableColumn tags within each webuijsf:tableRowGroup tag to specify functionality. For example, the selectId and sort  attributes allow column headers to sort on all row groups at once. 

    The example uses the backing bean called TableBean for the table data. See the
    TableBean backing bean in webuijsf:table documentation.

    Note: UI guidelines recommend that items should not remain selected when they cannot be seen by the user. Using the com.sun.webui.jsf.event.TableSelectPhaseListener object ensures that rows that are hidden from view are deselected because the phase listener clears the table state after the rendering phase. Although pagination is not used for a group table, the TableSelectPhaseListener object is used in this example in the Select util, which is shown in Select.java in the webuijsf:table documentation.  Also refer to the JavaDoc for TableSelectPhaseListener for more information. 

    <!-- Group Table -->
    <webuijsf:table id="table1"
        clearSortButton="true"
        deselectMultipleButton="true"
        selectMultipleButton="true"
        sortPanelToggleButton="true"
        footerText="Table Footer">

      <!-- Title -->
      <f:facet name="title">
        <webuijsf:staticText text="Group Table"/>
      </f:facet>

      <webuijsf:tableRowGroup id="rowGroup1"
          binding="#{TableBean.groupB.tableRowGroup}"
          footerText="Group Footer"
          headerText="Group Header"
          selected="#{TableBean.groupB.select.selectedState}"
          selectMultipleToggleButton="true"
          sourceData="#{TableBean.groupB.names}"
          sourceVar="name"
          groupToggleButton="true">

        <webuijsf:tableColumn id="col0"
            extraHeaderHtml="nowrap='nowrap'"
            extraFooterHtml="nowrap='nowrap'"
            extraTableFooterHtml="nowrap='nowrap'"
            footerText="ColFtr"
            selectId="select"
            sort="#{TableBean.groupB.select.selectedState}">
          <webuijsf:checkbox id="select"
              onClick="setTimeout('initAllRows()', 0)"
              selected="#{TableBean.groupB.select.selected}"
              selectedValue="#{TableBean.groupB.select.selectedValue}"/>
        </webuijsf:tableColumn>
        <webuijsf:tableColumn id="col1"
            extraHeaderHtml="nowrap='nowrap'"
            alignKey="last"
            footerText="Column Footer"
            headerText="Last Name"
            rowHeader="true"
            sort="last">
          <webuijsf:staticText text="#{name.value.last}"/>
        </webuijsf:tableColumn>
        <webuijsf:tableColumn id="col2"
            alignKey="first"
            footerText="Column Footer"
            headerText="First Name"
            sort="first">
          <webuijsf:staticText text="#{name.value.first}"/>
        </webuijsf:tableColumn>
      </webuijsf:tableRowGroup>

      <webuijsf:tableRowGroup id="rowGroup2"
          binding="#{TableBean.groupC.tableRowGroup}"
          collapsed="true"
          selected="#{TableBean.groupC.select.selectedState}"
          selectMultipleToggleButton="true"
          sourceData="#{TableBean.groupC.names}"
          sourceVar="name"
          groupToggleButton="true">

        <!-- Row group header -->
        <f:facet name="header">
          <webuijsf:panelGroup id="groupHeader">
            <webuijsf:markup tag="span" extraAttributes="class='#{themeStyles.TABLE_GROUP_HEADER_LEFT}'">
              <webuijsf:staticText styleClass="#{themeStyles.TABLE_GROUP_HEADER_TEXT}" text="Group Header"/>
            </webuijsf:markup>
            <webuijsf:markup tag="span" extraAttributes="class='#{themeStyles.TABLE_GROUP_HEADER_RIGHT}'">
              <webuijsf:staticText styleClass="#{themeStyles.TABLE_GROUP_MESSAGE_TEXT}" text="Right-Aligned Text"/>
            </webuijsf:markup>
          </webuijsf:panelGroup>
        </f:facet>

        <!-- Row group footer -->
        <f:facet name="footer">
          <webuijsf:staticText styleClass="#{themeStyles.TABLE_GROUP_FOOTER_TEXT}" text="Group Footer"/>
        </f:facet>

        <webuijsf:tableColumn id="col0"
            extraHeaderHtml="nowrap='nowrap'"
            extraFooterHtml="nowrap='nowrap'"
            extraTableFooterHtml="nowrap='nowrap'"
            footerText="ColFtr"
            selectId="select"
            sort="#{TableBean.groupC.select.selectedState}"
            tableFooterText="TblColFtr">
          <webuijsf:checkbox id="select"
              onClick="setTimeout('initAllRows()', 0)"
              selected="#{TableBean.groupC.select.selected}"
              selectedValue="#{TableBean.groupC.select.selectedValue}"/>
        </webuijsf:tableColumn>
        <webuijsf:tableColumn id="col1"
            alignKey="last"
            footerText="Column Footer"
            rowHeader="true"
            sort="last"
            tableFooterText="Table Column Footer">
          <webuijsf:staticText text="#{name.value.last}"/>
        </webuijsf:tableColumn>
        <webuijsf:tableColumn id="col2"
            alignKey="first"
            footerText="Column Footer"
            sort="first"
            tableFooterText="Table Column Footer">
          <webuijsf:staticText text="#{name.value.first}"/>
        </webuijsf:tableColumn>
      </webuijsf:tableRowGroup>
    </webuijsf:table>


    select.js

    This example shows the contents of the select.js file used in the example above.

    // Use this function to initialize all rows displayed in the table when the
    // state of selected components change (i.e., checkboxes or radiobuttons used to
    // de/select rows of the table). This functionality requires the selectId
    // property of the tableColumn component to be set.
    //
    // Note: Use setTimeout when invoking this function. This will ensure that
    // checkboxes and radiobutton are selected immediately, instead of waiting for
    // the onClick event to complete. For example:
    //
    // onClick="setTimeout('initAllRows(); disableActions()', 0)"
    function initAllRows() {
        // Disable table actions by default.
        var table = document.getElementById("form1:table1");
        table.initAllRows();
    }

    Example 2: Dynamic Table

    This example shows how to use the webuijsf:table tag to create a binding to a backing bean to dynamically create a table layout. The dynamic table is created as needed and can be changed each time the page is rendered.  

    <webuijsf:table id="table1" binding="#{DynamicTableBean.table}"/>


    The backing bean, DynamicTableBean, is shown in the following DynamicTableBean.java class. This bean is used only to create the table layout, and shows how to use the tableRowGroup component directly through Java code instead of through the JSP tag  webuijsf:tableRowGroup. The Dynamic.java utility class provides the functionality for adding properties to the table.  The table also uses methods that are defined in the TableBean shown in the webuijsf:table documentation.

    DynamicTableBean.java Backing Bean

    package table;

    import com.sun.webui.jsf.component.Table;
    import com.sun.webui.jsf.component.TableRowGroup;

    import table.util.Dynamic;

    // Backing bean for dynamic table examples.
    //
    // Note: To simplify the example, this bean is used only to create the table
    // layout. The resulting table will use methods already defined in TableBean.
    public class DynamicTableBean {
        private Dynamic dynamic = null; // Dynamic util.
        private Table table = null; // Table component.

        // Default constructor.
        public DynamicTableBean() {
            dynamic = new Dynamic();
        }

        // Get Table component.
        public Table getTable() {
            if (table == null) {
                // Get table row group.
                TableRowGroup rowGroup1 = dynamic.getTableRowGroup("rowGroup1",
                    "#{TableBean.groupB.names}",
                    "#{TableBean.groupB.select.selectedState}", null);

                // Set table row group properties.
                dynamic.setTableRowGroupChildren(rowGroup1,
                    "#{TableBean.groupB.select.selectedState}",
                    "#{TableBean.groupB.select.selected}",
                    "#{TableBean.groupB.select.selectedValue}",
                    "#{TableBean.groupB.actions.action}", true);

                // Get table.
                table = dynamic.getTable("table1", "Dynamic Table");
                table.getChildren().add(rowGroup1);
            }
            return table;
        }

        // Set Table component.
        //
        // @param table The Table component.
        public void setTable(Table table) {
            this.table = table;
        }
    }

    Example 3: Dynamic Group Table

    This example shows how to use the webuijsf:table tag to create a binding to a backing bean to dynamically create a group table layout. The dynamic group table is created as needed and can be changed each time the page is rendered.

    <webuijsf:table id="table1" binding="#{DynamicGroupTableBean.table}"/>

    The backing bean, DynamicGroupTableBean, is shown in the following DynamicGroupTableBean.java class. This bean is used only to create the table layout, and shows how to use the tableRowGroup component directly through Java code instead of through the JSP tag  webuijsf:tableRowGroup. The Dynamic.java utility class provides the functionality for adding properties to the table.  The table also uses methods that are defined in the TableBean shown in the webuijsf:table documentation.

    DynamicGroupTableBean.java Backing Bean

    package table;

    import table.util.Dynamic;

    import com.sun.webui.jsf.component.StaticText;
    import com.sun.webui.jsf.component.Table;
    import com.sun.webui.jsf.component.TableRowGroup;

    // Backing bean for dynamic group table examples.
    //
    // Note: To simplify the example, this bean is used only to create the table
    // layout. The resulting table will use methods already defined in TableBean.
    public class DynamicGroupTableBean {
        private Dynamic dynamic = null; // Dynamic util.
        private Table table = null; // Table component.

        // Default constructor.
        public DynamicGroupTableBean() {
            dynamic = new Dynamic();
        }

        // Get Table component.
        public Table getTable() {
            if (table == null) {
                // Get table row group.
                TableRowGroup rowGroup1 = dynamic.getTableRowGroup("rowGroup1",
                    "#{TableBean.groupB.names}",
                    "#{TableBean.groupB.select.selectedState}",
                    "Group Header");
                TableRowGroup rowGroup2 = dynamic.getTableRowGroup("rowGroup2",
                    "#{TableBean.groupC.names}",
                    "#{TableBean.groupC.select.selectedState}",
                    "Group Header");

                // Set table row group properties.
                dynamic.setTableRowGroupChildren(rowGroup1,
                    "#{TableBean.groupB.select.selectedState}",
                    "#{TableBean.groupB.select.selected}",
                    "#{TableBean.groupB.select.selectedValue}", null, true);
                dynamic.setTableRowGroupChildren(rowGroup2,
                    "#{TableBean.groupC.select.selectedState}",
                    "#{TableBean.groupC.select.selected}",
                    "#{TableBean.groupC.select.selectedValue}", null, false);

                // Set select and row group toggle buttons.
                rowGroup1.setSelectMultipleToggleButton(true);
                rowGroup2.setSelectMultipleToggleButton(true);
                rowGroup1.setGroupToggleButton(true);
                rowGroup2.setGroupToggleButton(true);

                // Get table.
                table = dynamic.getTable("table1", null);
                table.getChildren().add(rowGroup1);
                table.getChildren().add(rowGroup2);

                // Add title facet.
                StaticText title = new StaticText();
                title.setText("Dynamic Group Table");
                table.getFacets().put(Table.TITLE_FACET, title);
            }
            return table;
        }

        // Set Table component.
        //
        // @param table The Table component.
        public void setTable(Table table) {
            this.table = table;
        }
    }

    faces_config.xml Entry for Managed Beans

    The examples are based on managed beans, such as the example below, added to the faces_config.xml file.

    <!DOCTYPE faces-config PUBLIC
        '-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.0//EN'
        'http://java.sun.com/dtd/web-facesconfig_1_1.dtd'>

    <faces-config>
        <managed-bean>
            <description>Backing bean for the group table example</description>
            <managed-bean-name>TableBean</managed-bean-name>
            <managed-bean-class>table.TableBean</managed-bean-class>
            <managed-bean-scope>session</managed-bean-scope>
        </managed-bean>

        <managed-bean>
            <description>Backing bean for the dynamic table example</description>
            <managed-bean-name>DynamicTableBean</managed-bean-name>
            <managed-bean-class>table.DynamicTableBean</managed-bean-class>
            <managed-bean-scope>session</managed-bean-scope>
        </managed-bean>

        <managed-bean>
            <description>Backing bean for the dynamic group table example</description>
            <managed-bean-name>DynamicGroupTableBean</managed-bean-name>
            <managed-bean-class>table.DynamicGroupTableBean</managed-bean-class>
            <managed-bean-scope>session</managed-bean-scope>
        </managed-bean>
    </faces-config>

    Utility Classes used in the examples

    The  following utility class is used in the group table examples shown in this page.

    Dynamic.java

    The following utility classes are shown in the webuijsf:table documentation, and used in the examples for the table tags webuijsf:table, webuijsf:tableRowGroup, and webuijsf:tableColumn.

    Group.java
    Name.java
    Select.java

    Dynamic.java Utility Class

    package table.util;

    import com.sun.webui.jsf.component.Checkbox;
    import com.sun.webui.jsf.component.Hyperlink;
    import com.sun.webui.jsf.component.StaticText;
    import com.sun.webui.jsf.component.Table;
    import com.sun.webui.jsf.component.TableColumn;
    import com.sun.webui.jsf.component.TableRowGroup;

    import javax.faces.context.FacesContext;
    import javax.faces.component.UIComponent;
    import javax.faces.component.UIParameter;
    import javax.faces.el.ValueBinding;

    // This class provides functionality for dynamic tables.
    public class Dynamic {
        public static final String CHECKBOX_ID = "select";
        public static final String HYPERLINK_ID = "link";

        // Default constructor.
        public Dynamic() {
        }

        // Note: When using tags in a JSP page, UIComponentTag automatically creates
        // a unique id for the component. However, when dynamically creating
        // components, via a backing bean, the id has not been set. In this
        // scenario, allowing JSF to create unique Ids may cause problems with
        // Javascript and components may not be able to maintain state properly.
        // For example, if a component was assigned "_id6" as an id, that means
        // there were 5 other components that also have auto-generated ids. Let us
        // assume one of those components was a complex component that, as part of
        // its processing, adds an additional non-id'd child before redisplaying the
        // view. Now, the id of this component will be "_id7" instead of "_id6".
        // Assigning your own id ensures that conflicts do not occur.

        // Get Table component.
        //
        // @param id The component id.
        // @param title The table title text.
        public Table getTable(String id, String title) {
            // Get table.
            Table table = new Table();
            table.setDeselectMultipleButton(true); // Show deselect multiple button.
            table.setSelectMultipleButton(true); // Show select multiple button.
            table.setTitle(title); // Set title text.

            return table;
        }

        // Get TableRowGroup component with header.
        //
        // @param id The component id.
        // @param sourceData Value binding expression for model data.
        // @param selected Value binding expression for selected property.
        // @param header Value binding expression for row group header text.
        public TableRowGroup getTableRowGroup(String id, String sourceData,
                String selected, String header) {
            // Get table row group.
            TableRowGroup rowGroup = new TableRowGroup();
            rowGroup.setId(id); // Set id.
            rowGroup.setSourceVar("name"); // Set source var.
            rowGroup.setHeaderText(header); // Set header text.
            setValueBinding(rowGroup, "selected", selected); // Set row highlight.
            setValueBinding(rowGroup, "sourceData", sourceData); // Set source data.

            return rowGroup;
        }

        // Get TableColumn component.
        //
        // @param id The component id.
        // @param sort Value binding expression for column sort.
        // @param align The field key for column alignment.
        // @param header The column header text.
        // @param selectId The component id used to select table rows.
        public TableColumn getTableColumn(String id, String sort, String align,
                String header, String selectId) {
            // Get table column.
            TableColumn col = new TableColumn();
            col.setId(id); // Set id.
            col.setSelectId(selectId); // Set id used to select table rows.
            col.setHeaderText(header); // Set header text.
            col.setAlignKey(align); // Set align key.
            setValueBinding(col, "sort", sort); // Set sort.

            return col;
        }

        // Get Checkbox component used for select column.
        //
        // @param id The component id.
        // @param selected Value binding expression for selected property.
        // @param selectedValue Value binding expression for selectedValue property.
        public Checkbox getCheckbox(String id, String selected,
                String selectedValue) {
            // Get checkbox.
            Checkbox cb = new Checkbox();
            cb.setId(id); // Set id here and set row highlighting below.
            cb.setOnClick("setTimeout('initAllRows()', 0)");
            setValueBinding(cb, "selected", selected); // Set selected.
            setValueBinding(cb, "selectedValue", selectedValue); // Set selected value.

            return cb;
        }

        // Get Hyperlink component.
        //
        // @param id The component id.
        // @param text Value binding expression for text.
        // @param action Method binding expression for action.
        // @param parameter Value binding expression for parameter.
        public Hyperlink getHyperlink(String id, String text, String action,
                String parameter) {
            // Get hyperlink.
            Hyperlink hyperlink = new Hyperlink();
            hyperlink.setId(id); // Set id.
            setValueBinding(hyperlink, "text", text); // Set text.
            setMethodBinding(hyperlink, "action", action); // Set action.

            // Create paramerter.
            UIParameter param = new UIParameter();
            param.setId(id + "_param");
            param.setName("param");
            setValueBinding(param, "value", parameter); // Set parameter.
            hyperlink.getChildren().add(param);

            return hyperlink;
        }

        // Get StaticText component.
        //
        // @param text Value binding expression for text.
        public StaticText getText(String text) {
            // Get static text.
            StaticText staticText = new StaticText();
            setValueBinding(staticText, "text", text); // Set text.

            return staticText;
        }

        // Set TableRowGroup children.
        //
        // @param rowGroup The TableRowGroup component.
        // @param cbSort Value binding expression for cb sort.
        // @param cbSelected Value binding expression for cb selected property.
        // @param cbSelectedValue Value binding expression for cb selectedValue property.
        // @param action The Method binding expression for hyperlink action.
        // @param showHeader Flag indicating to display column header text.
        public void setTableRowGroupChildren(TableRowGroup rowGroup, String cbSort,
            String cbSelected, String cbSelectedValue, String action,
                boolean showHeader) {
            // UI guidelines recomend no headers for second row group.
            String header1 = showHeader ? "Last Name" : null;
            String header2 = showHeader ? "First Name" : null;

            // Get columns.
            TableColumn col1 = getTableColumn(
                "col0", cbSort, null, null, CHECKBOX_ID);
            TableColumn col2 = getTableColumn(
                "col1", "#{name.value.last}", "last", header1, null);           
            TableColumn col3 = getTableColumn(
                "col2", "#{name.value.first}", "first", header2, null);

            // Get column components.
            Checkbox cb = getCheckbox(CHECKBOX_ID, cbSelected, cbSelectedValue);
            StaticText firstName = getText("#{name.value.first}");
          
            // If action was provided, add a hyperlink; otherwise, use static text.
            if (action != null) {
                Hyperlink lastName = getHyperlink(HYPERLINK_ID,
                    "#{name.value.last}", action,
                    "#{name.value.last}");
                col2.getChildren().add(lastName);
            } else {
                StaticText lastName = getText("#{name.value.last}");
                col2.getChildren().add(lastName);
            }

            // Add Children.
            col1.getChildren().add(cb);
            col3.getChildren().add(firstName);
            rowGroup.getChildren().add(col1);
            rowGroup.getChildren().add(col2);
            rowGroup.getChildren().add(col3);
        }

        // Helper method to set value bindings.
        //
        // @param component The UIComponent to set a value binding for.
        // @param name The name of the value binding.
        // @param value The value of the value binding.
        protected void setValueBinding(UIComponent component, String name,
                String value) {
            if (value == null) {
                return;
            }
            FacesContext context = FacesContext.getCurrentInstance();
            component.setValueBinding(name, context.getApplication().
                createValueBinding(value));
        }

        // Helper method to set method bindings.
        //
        // @param component The UIComponent to set a value binding for.
        // @param name The name of the method binding.
        // @param action The action of the method binding.
        protected void setMethodBinding(UIComponent component, String name,
                String action) {
            if (action == null) {
                return;
            }
            FacesContext context = FacesContext.getCurrentInstance();
            component.getAttributes().put(name, context.getApplication().
                createMethodBinding(action, new Class[0]));
        }
    }


    textArea

    Use the webuijsf:textArea tag to create a multiple-line input field for text.

    HTML Elements and Layout

    The textArea component renders an HTML <textarea> element.

    Configuring the webuijsf:textArea Tag

    Use the text attribute to associate the component with a model object that represents the current value, by setting the attribute's value to a JavaServer Faces EL expression that evaluates to a backing bean or a backing bean property.

    To optionally specify a label for the component, use the label attribute, or specify a label facet.

    Facets

    • label: use this facet to specify a custom component for the label.

    Theme Identifiers

    The input element has a style class "TxtAra", or "TxtAraDis" when the field is disabled. If a label attribute is specified, the label element's class attribute is set to "LstAln" followed by "LblLvl1Txt", "LblLvl2Txt" or "LblLvl3Txt" depending on the label level.

    Client Side Javascript Functions

    When the component is rendered, a DOM object corresponding to the component is created. To manipulate the component on the client side, you may invoke functions on the DOM object. With reference to the DOM id, to disable the component, invoke document.getElementById(id).setProps({disabled: true}).

    getInputElement() Use this function to access the HTML <input> element that is rendered by the component.
    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. If omitted, no other components are executed.
    setProps(props) Use this function to change any of the following supported properties:
    • accesskey
    • className
    • dir
    • disabled
    • id
    • label
    • lang
    • onClick
    • onDblClick
    • onFocus
    • onKeyDown
    • onKeyPress
    • onKeyUp
    • onMouseDown
    • onMouseMove
    • onMouseOut
    • onMouseOver
    • onMouseUp
    • readOnly
    • required
    • size
    • style
    • tabIndex
    • title
    • valid
    • value
    • 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.
    subscribe(topic, obj, func) Use this function to subscribe to an event topic.
    • topic: The event topic to subscribe to.
    • obj: The object in which a function will be invoked, or null for default scope.
    • func The name of a function in context, or a function reference to invoke when topic is published.

    Client Side JavaScript Events

    When the component is manipulated client side, some functions may publish event topics for custom AJAX implementations to listen for. For example, you can listen for the refresh event topic using:

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

        // Subscribe to refresh event.
        var domNode = document.getElementById("form1:test1");
        domNode.subscribe(domNode.event.refresh.endTopic, processEvents, "update");


    </webuijsf:script>

    The following events are supported.

    <Node>.event.refresh.beginTopic Event topic published before asynchronously refreshing the component. 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
    <Node>.event.refresh.endTopic

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

    • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage
    <Node>.event.submit.beginTopic Event topic published before asynchronously submitting the component. 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
    <Node>.event.submit.endTopic

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

    • props - JSON object containing messages (if any) raised by the server.In particular, valdiation messages will be present here if validation failed

    Examples

    Example 1: Text area with label and required icon

    This example uses a backing bean FieldTest with a property string. The tag generates a label followed by text input field. The required attribute is set to true, which causes an icon to be rendered next to the label to indicate that the application user must enter a value in the text field. The icon, label and input elements are enclosed by a span.

         <webuijsf:textArea id="textArea" label="Enter a value:" 
    text="#{FieldTest.string}"
    required="true"/>

    Example 2: Update client-side textArea properties using the getProps and setProps functions

    This example shows how to toggle the disabled state of a text field client side using the getProps and setProps functions. When the user clicks the radio button, the text area is either disabled or enabled.
    <webuijsf:radioButton id="rb1" name="rb1" label="Toggle Field Disabled" onClick="toggleDisabled()"/>
    <webuijsf:textArea id="field1" text="My Text Field" />

    <webuijsf:script>
    function toggleDisabled() {
    var domNode = document.getElementById("form1:field1"); // Get field
    return domNode.setProps({disabled: !domNode.getProps().disabled}); // Toggle disabled state
    }
    </webuijsf:script>
    Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,..."). When no parameter is given, the refresh function acts as a reset. That is, the component will be redrawn using values set server-side, but not updated.

    Example 3: Asynchronously update textArea using refresh function

    This example shows how to asynchronously update a text area using the refresh function. When the user clicks on the radio button, the text field is asynchronously updated with new data.
    <webuijsf:radioButton id="rb1" name="rb1" label="Refresh Text Field" onClick="refreshField()"/>
    <webuijsf:textArea id="field1" text="#{MyBean.text}" />

    <webuijsf:script>
        function refreshField() {
            var domNode = document.getElementById("form1:field1"); // Get field
            return domNode.refresh(); // Asynchronously refresh field
        }
    </webuijsf:script>


    Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,...")

    Example 4: Asynchronously submit textArea using submit function

    This example shows how to asynchronously submit a text area using the submit function. When the user clicks on the radio button, the input value is updated server-side
    <webuijsf:radioButton id="rb1" name="rb1" label="submit Text Field" onClick="submitField()"/>
    <webuijsf:textArea id="field1" text="#{MyBean.text}" /> // Field used to asynchronously update text.

    webuijsf:script>
        function
    submitField() {
            var domNode = document.getElementById("form1:field1"); // Get field
            return domNode.submit();
        }
    </webuijsf:script>

    Note that the submit function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: submit("form1:id1,form2:id2,...")

    textField

    Use the webuijsf:textField tag to create an input field for a single line of text.

    HTML Elements and Layout

    The textField component renders an XHTML <input type="text">element.

    Configuring the webuijsf:textField Tag

    Use the value attribute to associate the component with a model object that represents the current value, by setting the attribute's value to an EL expression that corresponds to a property of a backing bean.

    To optionally specify a label for the component, use the label attribute, or specify a label facet.

    Attribute submitForm can be used to alter the default browser behavior on form submission when Enter key is pressed within a text field. Value of true will force the form submission, value of false will prevent it, and if submitForm is not specified, the default browser behavior ( that differs for different browsers) will take an effect.

    Facets

    • label: use this facet to specify a custom component for the label.

    Client Side Javascript Functions

    When the component is rendered, a DOM object corresponding to the component is created. To manipulate the component on the client side, you may invoke functions on the DOM object. With reference to the DOM id, to disable the component, invoke document.getElementById(id).setProps({disabled: true}).

    getInputElement() Use this function to access the HTML <input> element that is rendered by the component.
    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. If omitted, no other components are executed.
    setProps(props) Use this function to change any of the following supported properties:
    • accesskey
    • className
    • dir
    • disabled
    • id
    • label
    • lang
    • onClick
    • onDblClick
    • onFocus
    • onKeyDown
    • onKeyPress
    • onKeyUp
    • onMouseDown
    • onMouseMove
    • onMouseOut
    • onMouseOver
    • onMouseUp
    • readOnly
    • required
    • size
    • style
    • tabIndex
    • title
    • valid
    • value
    • 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.
    subscribe(topic, obj, func) Use this function to subscribe to an event topic.
    • topic: The event topic to subscribe to.
    • obj: The object in which a function will be invoked, or null for default scope.
    • func The name of a function in context, or a function reference to invoke when topic is published.

    Client Side JavaScript Events

    When the component is manipulated client side, some functions may publish event topics for custom AJAX implementations to listen for. For example, you can listen for the refresh event topic using:

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

        // Subscribe to refresh event.
        var domNode = document.getElementById("form1:test1");
        domNode.subscribe(domNode.event.refresh.endTopic, processEvents, "update");


    </webuijsf:script>

    The following events are supported.

    <Node>.event.refresh.beginTopic Event topic published before asynchronously refreshing the component. 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
    <Node>.event.refresh.endTopic

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

    • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage
    <Node>.event.submit.beginTopic Event topic published before asynchronously submitting the component. 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
    <Node>.event.submit.endTopic

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

    • props - JSON object containing messages (if any) raised by the server.In particular, valdiation messages will be present here if validation failed
    <Node>.event.validation.beginTopic Event topic published before asynchronously submitting the component. 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
    <Node>.event.validation.endTopic

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

    • props - JSON object containing messages (if any) raised by the server. In particular, valdiation messages will be present here if validation failed

    Examples

    Example 1: Text field with label and required icon

    This example uses a backing bean FieldTest with a property string. The tag generates a label followed by text input field. The required attribute is set to true, which causes an icon to be rendered next to the label to indicate that the application user must enter a value in the text field. The icon, label and input elements are enclosed by a span.

     <webuijsf:textField id="textfield" label="Enter a value:" 
    text="#{FieldTest.string}"
    required="true"/>

    Example 2: Text field using a validator

    This example uses a backing bean FieldTest with a property number. The number property is an int, which means that the value must be converted to be displayed. It is not necessary to specify a Converter instance, however, since standard JSF conversion deals with this case. A Validator has been set to verify that any value entered by the user is within a certain range. The HTML elements are rendered as in example 1.

     <webuijsf:textField id="test2" label="Enter a number:" 
    text="#{FieldTest.number}"
    validator="#{FieldTest.checkNumberRange}"/>

    Example 3: Auto-Validation

    This example shows how to enable auto-validation on the field using server side validator. Attribute autoValidate specifies that validation will be triggered on onBlur event, initiating Ajax call to the server to validate data.
    <webuijsf:textField 
    id="textFieldA"
    text="4111 1111 1111 1111"
    label="Enter Credit Card Number"
    columns="20"
    required="true"
    autoValidate="true"
    validatorExpression="#{Payment.cardValidator}"/>

    Validator Payment will be invoked, and when result comes back, the validation message is available to the developer. One can get hold of returned validation message by subscribing to the following event and providing a call back closure (in this case closure called processEvents with update function) :

    <webuijsf:script>
     // --- this closure is used for validation callback --- 
    var processEvents = {
    update: function(props) {
    var domNode = document.getElementById("form1:textFieldA");

    // The following data reflecting validation results is available in props:
    // props.valid ( true | false )
    // props.summary
    // props.detail

    // The default auto-validation will ONLY invalidate (make it red) the label
    // on the text field.

    // As an example, we will change the prefix before the label on the text field
    // to display detail message of the error, or successful validation upon success
    var date = (new Date()).toLocaleString();
    document.getElementById('messageId').innerHTML =
    ((props.valid == true)
    ? '[validated OK]'
    : '['+ props.detail+ ']' ) + ' on ' + date;
    }
    }

    // --- Subscribe to validation event. ---
    var domNode = document.getElementById("form1:textFieldA");
        domNode.subscribe(domNode.event.endTopic, processEvents, "update");

    </webuijsf:script>

    Example 4: Auto-Validation with notify

    This example shows how to dynamically update a label and alert during text field auto-validation events. Although these components are decoupled from the text
    field, they can both be updated automatically via the notify tag attribute.
     <webuijsf:alert id="alert1" type="error" visible="false"/>
    <webuijsf:label id="label1" text="Enter Credit Card Number" for="textField1"/>
    <webuijsf:textField
    id="textField1"
    text="4111 1111 1111 1111"
    columns="20"
    required="true"
    autoValidate="true"
    validatorExpression="#{Payment.cardValidator}"
    notify="form1:alert1,form1:label1"/>

    Example 5: Update client-side textField properties using the getProps and setProps functions

    This example shows how to toggle the disabled state of a text field client side using the getProps and setProps functions. When the user clicks the radio button, the text field is either disabled or enabled.
    <webuijsf:radioButton id="rb1" name="rb1" label="Toggle Field Disabled" onClick="toggleDisabled()"/>
    <webuijsf:textField id="field1" text="My Text Field" />

    <webuijsf:script>
    // Toggle field disabled.
    function toggleDisabled() {
    var domNode = document.getElementById("form1:field1"); // Get field
    return domNode.setProps({disabled: !domNode.getProps().disabled}); // Toggle disabled state
    }
    </webuijsf:script>

    Example 6: Asynchronously update textField using refresh function

    This example shows how to asynchronously update a text field using the refresh function. When the user clicks on the radio button, the text field is asynchronously updated with new data.
    <webuijsf:radioButton id="rb1" name="rb1" label="Refresh Text Field" onClick="refreshField()"/>
    <webuijsf:textField id="field1" text="#{MyBean.text}" />
    <webuijsf:script>
        function refreshField() {
            var domNode = document.getElementById("form1:field1"); // Get field
            return domNode.refresh(); // Asynchronously refresh field
        }
    </webuijsf:script>


    Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,..."). When no parameter is given, the refresh function acts as a reset. That is, the component will be redrawn only using values set server-side.

    Example 7: Asynchronously update textField using refresh function

    This example shows how to asynchronously update a text field using the refresh function. The execute property of the refresh function is used to define the client id which is to be submitted and updated server-side. When the user clicks on the radio button, the input value is updated server-side and the text field is updated client-side -- all without a page refresh.
    <webuijsf:radioButton id="rb1" name="rb1" label="Refresh Text Field" onClick="refreshField()"/>
    <webuijsf:textField id="field1" text="#{MyBean.text}" /> // Field used to asynchronously update text.
    <webuijsf:script>
        function
    refreshField() {
            var domNode = document.getElementById("form1:field1"); // Get field
            return domNode.refresh("form1:rb1"); // Asynchronously refresh while submitting radio button value
        }
    </webuijsf:script>

    Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,...")

    Example 8: Asynchronously submit textField using submit function

    This example shows how to asynchronously submit a text field using the submit function. When the user clicks on the radio button, the input value is updated server-side
    <webuijsf:radioButton id="rb1" name="rb1" label="submit Text Field" onClick="submitField()"/>
    <webuijsf:textField id="field1" text="#{MyBean.text}" /> // Field used to asynchronously update text.

    <webuijsf:script>
        function
    submitField() {
            var domNode = document.getElementById("form1:field1"); // Get field
            return domNode.submit();
        }
    </webuijsf:script>

    Note that the submit function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: submit("form1:id1,form2:id2,...")

    themeLinks The ThemeLicnks component is used to create references to theme resources on a page in a portlet environment, where the Head component cannot be used.
    timeStamp The TimeStamp component is used to display a text string that contains a time stamp, which indicates the date and time that the current page was last updated or displayed. This tag is typically specified as part of the Masthead component's statusArea facet.
    tree

    Use the webuijsf:tree tag to display a tree structure in the rendered HTML page. The nodes of the tree are defined with webuijsf:treeNode tags. Trees are often used for navigating in a web application.

    HTML Elements and Layout

    The Tree component defines and renders a tree structure. A tree structure is commonly used for navigation through data, as in file system navigators. The base, or root, of the tree is shown at the top, with the branches going downward. The webuijsf:tree tag defines the root of the tree.

    The tree is rendered with <div> XHTML elements which define rows as well as nesting within the tree.

    The webuijsf:tree tag is the root of the tree, and is also a container for the webuijsf:treeNode tags. The webuijsf:treeNode tags add branches, or nodes, to the tree. The webuijsf:tree tag is also a special type of webuijsf:treeNode that has the ability to create a title bar for the root. The root of the tree is only visible when it includes a title bar.

    In the rendered web page, a node can be expanded and collapsed when you click on the small icon next to the node, or when you click the node's hyperlink text. In addition, the node is highlighted when you click on the node's hyperlink to indicate the node has focus.

    When the root of the tree is visible, it does not have handle icons, and cannot be expanded and collapsed.

    Configuring the webuijsf:tree Tag

    The webuijsf:tree tag creates the topmost tree node and can optionally render a title bar. If the title bar is not rendered, the tree component is not visible in the rendered HTML page. See Defining a Title Bar for more information.

    The webuijsf:tree tag provides the ability to render the tree root in any of the following ways:

    • As a single root, with a title bar to make the root visible. You must specify attributes or facets in the webuijsf:tree tag to allow the title bar to be rendered. See Defining a Title Bar for more information.

    • As a single root, without a title bar. The root is invisible, and a treeNode component is used as a single "root". This treeNode is like any other container node in the tree, and includes handle icons for expanding and collapsing. You must omit attributes and facets in the webuijsf:tree tag, and specify a single webuijsf:treeNode as the root node, with other webuijsf:treeNode tags contained within the first webuijsf:treeNode.

    • As a multi-root tree, without a title bar. There is no single top node, but two or more at the same level. You must omit attributes and facets in the webuijsf:tree tag and include multiple webuijsf:treeNode tags. See Defining a Tree with Multiple Roots for more information.

    Defining a Title Bar

    The title bar consists of the following elements:

    • A shaded background color determined by the theme.
    • An optional graphic to the left of the title bar's text.
    • Text or a hyperlink for the content of the title bar.

    The title bar can be defined with either webuijsf:tree tag attributes or facets. The title bar is rendered if the tree component includes imageURL property for the graphic, the text property for the title text, the content facet, or the image facet.

    The title bar can be defined with either webuijsf:tree tag attributes or facets. The title bar is rendered if the tree component includes any of the following: the imageURL attribute for the graphic, the text attribute for the title text, the content facet, or the image facet.

    Defining a Tree with Multiple Roots

    To define a tree that has multiple roots rather than a single top root, you must use the webuijsf:tree tag only as a container. You should not specify attributes for the graphic or title text, or use facets in the webuijsf:tree tag.

    You can use webuijsf:treeNode tags as containers for other webuijsf:treeNode tags, but should not use one to contain all the others to avoid the appearance of a single root.

    Client-side and Server-side Trees

    The webuijsf:tree tag can be used to create a client-side tree or server-side tree. By default the rendered tree is a server-side tree, and a request will be made to the server each time the tree is expanded or collapsed. Set the clientSide attribute to true to create a tree that handles expanding and collapsing in the browser. Client-side trees are most useful for navigating through the application.

    If your tree needs to maintain its state across requests, you should use the server side tree. The server side tree also provides the ability to fire events when the node handles are clicked.

    Dynamically Adding and Removing Tree Nodes

    The webuijsf:tree and webuijsf:treeNode tags can be used to dynamically populate tree structures, by using the binding attribute to create Tree and TreeNode component instances programmatically through a backing bean. This approach is useful when tree data is not static, but must be calculated when the page is rendered. Another reason to dynamically populate a tree is to decrease the time needed to initially render a tree by waiting until a user opens a folder before adding the folder's child nodes. See the Examples section for sample code that implements dynamic nodes.

    Facets

    The Tree component supports the following facets:

    content Replaces the default title bar with a custom component. When the content facet is used, the action, target, text, url, and toolTip attributes are ignored.
    image Specifies the image area. When the image facet is used, the imageURL, action, target, url, and toolTip attributes are ignored.

    Theme Identifiers

    The following image keys might be useful for including theme images in tree nodes. To use these keys, use the image facet with a child component that supports the icon attribute, such as webuijsf:image and webuijsf:imageHyperlink.

    TREE_BLANK
    TREE_DOCUMENT
    TREE_FOLDER
    TREE_FOLDER_ALARM_MINOR
    TREE_FOLDER_ALARM_MAJOR
    TREE_FOLDER_ALARM_DOWN
    TREE_FOLDER_ALARM_CRITICAL
    TREE_SERVER
    TREE_SERVER_CRITICAL
    TREE_SERVER_DOWN
    TREE_SERVER_MAJOR
    TREE_SERVER_MINOR
    TREE_STORAGE
    TREE_STORAGE_MAJOR

    Client Side Javascript Functions

    The JavaScript functions listed in the following table are defined in a file that is referenced automatically by the Tree component. The functions are called automatically in the rendered HTML. You can also call these functions independently; you may choose to do this to select or expand/collapse a TreeNode on the client.

    clearHighlight(treeNode) This function clears the highlighting for a particular TreeNode. The treeNode passed in is the id of the <div> element that surrounds the HTML code for the TreeNode. This id can be obtained by calling getElementById("<TreeNode.getClidentId()>").
    expandCollapse(treeNode, event) This function expands or collapses the given tree node. The function expects the source of the given event object to be a tree handle image. The function swaps images that depict the node as expanded or collapsed. The handle image points right when the node is collapsed, and points down when the node is expanded.  This implementation requires the file names of the images to include the strings "tree_handleright" and "tree_handledown" to enable the images to be accurately displayed by swapping "right" and "down" in the name of the image file that is rendered.
    getParentTreeNode(treeNode) This function returns the parent TreeNode of the given TreeNode.
    getSelectedTreeNode(treeId) This function returns the selected TreeNode given the treeId of the Tree.
    getTree(treeNode) This function provides access to the Tree object containing the given TreeNode.
    highlight(treeNode) This function highlights the given TreeNode.The treeNode passed in is the id of the <div> element that surrounds the HTML code for the TreeNode. This id can be obtained by calling getElementById("<TreeNode.getClidentId()>").
    highlightParent(treeNode) This function highlights the parent TreeNode of the given TreeNode, only if the given TreeNode is not visible. The parent is considered the first visible parent of this TreeNode. The treeNode passed in is the id of the <div> element that surrounds the HTML code for the child TreeNode. This id can be obtained by calling getElementById("<TreeNode.getClidentId()>").
    isAnHref(event) This function checks to see if the event target is an href, or if any of the parent nodes which contain it is an href. To be considered an href, the target or parent node must be an <a> element with an href="..."  attribute that contains at least four characters. (Note: Browsers will add on the protocol if you supply a relative URL such as one starting with a '#', '/', or filename).
    isTreeHandle(event) This function determines if the event source is a tree handle image. This implementation depends on the tree handle image file name containing "tree_handle". No other images can contain this string.
    onTreeNodeClick(treeNode, event) This function handles TreeNode onClick events. The treeNode passed in is the id of the <div> element that surrounds the TreeNode that was clicked, in order to process the highlighting changes that are necessary. This id can be obtained by calling getElementById("<TreeNode.getClidentId()>"). If this function is invoked from the TreeNode <div> object itself (as is the case when this method is implicitly called), the TreeNode object is simply the this variable.
    selectTreeNode(treeNode) This function may be used to select the given TreeNode. The function clears the previous TreeNode and selects the given one.
    treeNodeIsExpanded(treeNode) This function determines if the given TreeNode is expanded. The function returns true if the node is expanded, or false if collapsed.
    unhighlightParent(treeNode) This function removes parent highlighting from the parent TreeNode of the given TreeNode, only if the given TreeNode is not visible. The parent is considered the first visible parent of this TreeNode. The treeNode passed in is the id of the <div> element that surrounds the HTML code for the child TreeNode. This id can be obtained by calling getElementById("<TreeNode.getClidentId()>").
    updateHightlight(id) This function updates the highlighting for the given Tree client id. This function provides a way to restore the highlighting when a Tree is reloaded in a window (necessary for each page load).

    Examples

    The following examples are included:

    Example 1: Multi-Root Tree

    This example shows a simple multiple root tree.

    <webuijsf:tree id="TreeExample1" >
            <webuijsf:treeNode id="node0" expanded="false" text="Accessibility" url="#">
                <webuijsf:treeNode id="node0_1" text="Access Key" url="#">
                </webuijsf:treeNode>
            </webuijsf:treeNode>
            <webuijsf:treeNode id="node1" expanded="false" text="Getting Started with Solaris" url="#">
                <webuijsf:treeNode id="node1_1" text="Registering with Sun Microsystems, Inc." url="#">
                </webuijsf:treeNode>
            </webuijsf:treeNode>
            <webuijsf:treeNode id="node2" expanded="true" text="Storage Management" url="#">
                <webuijsf:treeNode id="node2_1" text="Getting Started with Storage" url="#">
                <webuijsf:treeNode id="node2_1_1" text="Checking Volume Status" url="#">
                </webuijsf:treeNode>
                </webuijsf:treeNode>
                <webuijsf:treeNode id="node2_2" text="Storage Hardware" url="#">
                </webuijsf:treeNode>
                <webuijsf:treeNode id="node2_3" text="RAID Levels" url="#">
                </webuijsf:treeNode>
                <webuijsf:treeNode id="node2_4" text="Choosing Storage" url="#">
                </webuijsf:treeNode>
                <webuijsf:treeNode id="node2_5" text="Random I/O" url="#">
                </webuijsf:treeNode>
            </webuijsf:treeNode>

    </webuijsf:tree>

    Example 2: Client-side Tree

    This example shows a client-side tree with nodes that use actions, urls, or static text. The example also uses the image facet to use a theme icon in the tree title bar.

     <webuijsf:tree id="TreeExample1" text="Client-side Tree" url="#" clientSide="true">
            <f:facet name="image">
                <webuijsf:image id="image" icon="TREE_FOLDER_ALARM_CRITICAL" />
            </f:facet>
            <webuijsf:treeNode id="node0" expanded="true"
                          text="Node with action set to navigation rule" action="hyperlinkPage">
                <f:facet name="image">
                <webuijsf:image id="image" icon="TREE_FOLDER_ALARM_CRITICAL" />
                </f:facet>
                <webuijsf:treeNode id="node1" expanded="true"
                              text="Node with action set to managed bean method"
                    action="#{HyperlinkBean.success}">
                <f:facet name="image">
                    <webuijsf:image id="image" icon="TREE_FOLDER_ALARM_CRITICAL" />
                </f:facet>
                <webuijsf:treeNode id="node1_1" text="Node with static text">
                    <f:facet name="image">
                    <webuijsf:image id="image" icon="TREE_SERVER" />
                    </f:facet>
                </webuijsf:treeNode>
                <webuijsf:treeNode id="node1_2" text="Node with a URL" url="http://www.google.com/">
                    <f:facet name="image">
                    <webuijsf:image id="image" icon="TREE_SERVER_CRITICAL" />
                    </f:facet>
                </webuijsf:treeNode>
                </webuijsf:treeNode>
                <webuijsf:treeNode id="node2" text="Building 10" url="#">
                <f:facet name="image">
                    <webuijsf:image id="image" icon="TREE_FOLDER" />
                </f:facet>
                <webuijsf:treeNode id="node1_2" text="Skippy" url="#">
                    <f:facet name="image">
                    <webuijsf:image id="image" icon="TREE_SERVER" />
                    </f:facet>
                </webuijsf:treeNode>
                </webuijsf:treeNode>
            </webuijsf:treeNode>
            <webuijsf:treeNode id="node3" expanded="true" text="Building 2" url="#">
                <f:facet name="image">
                <webuijsf:image id="image" icon="TREE_FOLDER" />
                </f:facet>
                <webuijsf:treeNode id="node3_1" text="Arizona" url="#">
                <f:facet name="image">
                    <webuijsf:image id="image" icon="TREE_SERVER" />
                </f:facet>
                </webuijsf:treeNode>
            </webuijsf:treeNode>
            </webuijsf:tree>

    Example 3: Server-Side Tree with content Facet

    This example shows a server-side tree that uses a webuijsf:dropDown tag to create the content area in the title bar of the tree.

     <webuijsf:tree id="TreeExample3" url="#">
            <f:facet name="content">
                <webuijsf:dropDown id="airport" submitForm="true" items="#{BackingFileChoice.airports}" />
            </f:facet>
            <webuijsf:treeNode id="node0" expanded="true" text="Paducah" url="#">
                <f:facet name="image">
                   <webuijsf:image id="image" icon="TREE_FOLDER_ALARM_MINOR" />
                </f:facet>
                <webuijsf:treeNode id="node1" expanded="true" text="Building 1" url="#">
                  <f:facet name="image">
                    <webuijsf:image id="image" icon="TREE_FOLDER_ALARM_MINOR" />
                  </f:facet>
                <webuijsf:treeNode id="node1_1" text="Kenga">
                  <f:facet name="image">
                    <webuijsf:image id="image" icon="TREE_SERVER" />
                  </f:facet>
                </webuijsf:treeNode>
                <webuijsf:treeNode id="node1_2" text="Crocker" url="#">
                  <f:facet name="image">
                    <webuijsf:image id="image" icon="TREE_SERVER_MINOR" />
                  </f:facet>
                </webuijsf:treeNode>
            </webuijsf:treeNode>
           
            <webuijsf:treeNode id="node5" expanded="true" text="Building 4" url="#">
                <f:facet name="image">
                  <webuijsf:image id="image" icon="TREE_FOLDER_ALARM_MAJOR" />
                </f:facet>
                <webuijsf:treeNode id="node5_1" text="Neptune" url="#">
                  <f:facet name="image">
                    <webuijsf:image id="image" icon="TREE_STORAGE_MAJOR" />
                  </f:facet>
                </webuijsf:treeNode>
                <webuijsf:treeNode id="node5_2" text="Zeus" url="#">
                <f:facet name="image">
                    <webuijsf:image id="image" icon="TREE_STORAGE" />
                </f:facet>
                </webuijsf:treeNode>
               </webuijsf:treeNode>
            </webuijsf:treeNode>   
     </webuijsf:tree>

    Example 4: Dynamic Tree

    This example shows how to dynamically add or remove nodes from the tree. It also shows one way to dynamically add nodes to a folder when that folder is expanded. Each time a user expands Folder 3, three new nodes are added to it. The backing bean used in this example is included after the example.

    Note that you cannot delete nodes that are declared in the JSP. In this example, you cannot delete the root node (defined by webuijsf:tree) and the first three child nodes, folder1, folder2, and folder3 (defined by webuijsf:treeNode tags).

    <webuijsf:tree id="dynamicTree" binding="#{TestTreeBean.dynamicTree}">
      <webuijsf:treeNode id="folder1" binding="#{TestTreeBean.folder1}" />   
      <webuijsf:treeNode id="folder2" binding="#{TestTreeBean.folder2}" />       
      <webuijsf:treeNode id="folder3" text="Folder3" url="#" actionListener="#{TestTreeBean.nodeExpanded}" >
        <webuijsf:treeNode id="folder3Child1" text="Folder 3 Child 1" url="#" />
      </webuijsf:treeNode>
    </webuijsf:tree>

    <webuijsf:button id="addButton" text="Add Child to Selected Node" action="#{TestTreeBean.addNode}" />
    <webuijsf:button id="deleteButton" text="Delete Selected Node" action="#{TestTreeBean.deleteNode}" />

    TestTreeBean.java Backing Bean

    The following backing bean is used by the Dynamic Tree example.

    public class TestTreeBean {

        ... other code removed for readability ....

        private Tree dynamicTree = null;

        public Tree getDynamicTree() {
            if (dynamicTree == null) {
                dynamicTree = new Tree();
                dynamicTree.setText("Dynamic Tree Behavior Test");
            }

            return dynamicTree;
        }

        public void setDynamicTree(Tree t) {
            dynamicTree = t;
        }

        private TreeNode folder1 = null;

        public TreeNode getFolder1() {
            if (folder1 == null) {
                folder1 = new TreeNode();
                folder1.setUrl("#");
                folder1.setText("Folder 1");
                folder1.setExpanded(true);
            }

            return folder1;
        }

        public void setFolder1(TreeNode n) {
            folder1 = n;
        }

        private TreeNode folder2 = null;

        public TreeNode getFolder2() {
            if (folder2 == null) {
                folder2 = new TreeNode();
                folder2.setUrl("#");
                folder2.setText("Folder 2");
                folder2.setExpanded(true);
            }

            return folder2;
        }

        public void setFolder2(TreeNode n) {
            folder2 = n;
        }

        // int counter to name new nodes with
        int i = 0;

        ⁄**
         * This action listener method will be called when Folder 3's
         * turner IconHyperlink is clicked.
         *⁄
        public void nodeExpanded(ActionEvent event) {
            TreeNode node = (TreeNode) event.getComponent();

            if (!node.isExpanded()) {
                for (int j = 0; j < 3; j++) {
                    TreeNode newNode = createNode(i++);
                    node.getChildren().add(newNode);
                }
            }
        }

        private TreeNode createNode(int id) {
            TreeNode node = new TreeNode();
            node.setId("node" + i);
            node.setText("Node " + i);
            node.setUrl("#");

            return node;
        }

        ⁄**
         * This action method is called when the "Add Child to Selected
         * Node" button is pressed.
         *⁄
        public String addNode() {

            String nodeId = getDynamicTree().getSelected();

            if (nodeId == null) {
                return "";
            }

            UIComponent node = getDynamicTree().findComponent(":" + nodeId);

            if (node != null) {
                TreeNode newNode = createNode(i++);
                node.getChildren().add(newNode);
            }

            return "";
        }

        ⁄**
         * This action method is called when the "Delete Selected Node"
         * button is pressed.
         *⁄
        public String deleteNode() {
            String nodeId = (String) getDynamicTree().getSelected();

            if (nodeId == null) {
                return "";
            }

            UIComponent node = getDynamicTree().findComponent(":" + nodeId);

            if (node != null) {
                UIComponent parent = node.getParent();

                List kids = parent.getChildren();
                kids.remove((Object) node);
            }

            return "";
        }

    treeNode

    Use the webuijsf:treeNode tag to insert a node in a tree structure. The webuijsf:treeNode tag can be used within a webuijsf:tree tag or another webuijsf:treeNode tag.

    The webuijsf:treeNode tag is used as a child of a webuijsf:tree component or another webuijsf:treeNode component to form a tree structure. When the tree structure is rendered, the TreeNode component represents a node in the tree.

    HTML Elements and Layout

    The TreeNode component renders the following:

    • A row of the tree lines that connect to other tree nodes.

    • Small graphic images of "handles" that are used to open and close branches of the tree. The TreeNode component calls the imageHyperlink component, which displays clickable handle icons that are used to expand and collapse the node. The handle icons are rendered only if the TreeNode contains other TreeNodes.

    • Optional graphic images that pertain to the content of the tree node, such as a folder image. The TreeNode component calls the imageHyperlink component to render the image. Images are rendered if you specify the image attribute or use the image facet.

    • Text or a hyperlink for the content of the TreeNode. The default display of the content is rendered when you specify the text and url attributes. You can use the content facet to specify a component to render custom content for the node.

    Using the webuijsf:treeNode tag

    Use the text attribute to provide the content of the node in the default static text. Use the url attribute with the text attribute to make the content a hyperlink. The expanded attribute can be set to true to display a node in the expanded state on initial rendering of the tree. You can use the action attributes to perform an action when the user clicks the text hyperlink. You can use the actionListener attributes to perform an action when the user clicks the handle image hyperlink.

    Facets

    The TreeNode component supports the following facets:

    content Specifies the text or url for the node. The content facet overrides the text and url attributes.
    image Specifies the optional graphic displayed with the node. The image facet overrides the imageURL attribute.
    Note that using either of these facets causes some deviation from the normal behavior. If the content or the image is supplied as an attribute of the treeNode tag clicking on the text or icon of a branch always opens that branch as well as displays appropriate content in the right pane. But when facets are used, this behavior is lost. The developer has to explicitly add this behavior to the facets.

    Theme Identifiers

    The following image keys might be useful for including theme images in tree nodes. To use these keys, use the image facet with a child component that supports the icon attribute, such as webuijsf:image and webuijsf:imageHyperlink.

     TREE_BLANK
     TREE_DOCUMENT
     TREE_FOLDER
     TREE_FOLDER_ALARM_MINOR
     TREE_FOLDER_ALARM_MAJOR
     TREE_FOLDER_ALARM_DOWN
     TREE_FOLDER_ALARM_CRITICAL
     TREE_SERVER
     TREE_SERVER_CRITICAL
     TREE_SERVER_DOWN
     TREE_SERVER_MAJOR
     TREE_SERVER_MINOR
     TREE_STORAGE
     TREE_STORAGE_MAJOR

    Client Side Javascript Functions

    The TreeNode component does not provide JavaScript functions. See the documentation for the <webuijsf:tree> tag for JavaScript functions supported by the Tree component.

    Example

    See the <webuijsf:tree>documentation.

    upload

    Use the webuijsf:upload tag to create a component that can be used to browse the local file system for a file, and upload a copy of the file's contents to the web application.

    HTML Elements and Layout

    The Upload component produces an XHTML <input type="file"> element, which displays a text input field with an adjacent Browse button. The user can type a file name or click the Browse button to select a file. When the form is submitted, the file is uploaded. Note that this tag requires the use of a filter.

    Configuring the UploadFilter

    In order for the webuijsf:upload tag to work, you must configure the web application to use the com.sun.webui.jsf.util.UploadFilter. Configure the filter by declaring a filter element in the web application's deployment descriptor, web.xml.

     
      <filter>
        <filter-name>UploadFilter</filter-name>
        <filter-class>com.sun.webui.jsf.util.UploadFilter</filter-class>
      </filter>
     

    Map the filter to the FacesServlet by adding the following filter mapping in the same file, for example

      <filter-mapping>
        <filter-name>UploadFilter</filter-name>
        <servlet-name>FacesServlet</servlet-name>
      </filter-mapping>
     

    The UploadFilter uses the Apache commons fileupload package and woodstock implemented subclasses. The UploadFilterDiskFileUpload class can be configured, as needed, by specifying UploadFilter init parameters. The following parameters are available:

    • maxSize The maximum allowed upload size in bytes. If negative, there is no maximum. The default value is 1MB
    • sizeThresholdThe implementation of the uploading functionality uses temporary storage of the file contents before the Upload component stores them per its configuration. In the temporary storage, smaller files are stored in memory while larger files are written directly to disk . Use this parameter to specify an integer value of the cut-off where files should be written to disk. The default value is 4096 bytes.
    • tmpDir Use this directory to specify the directory to be used for temporary storage of files. The default behaviour is to use the directory specified in the system property "java.io.tmpdir".

    The UploadedFile model object

    The contents of the uploaded file, together with some information about it are stored in an instance of com.sun.webui.jsf.model.UploadedFile. Using this object you can get the content of the file as a String or write the contents to disk, as well as get properties such as the name and the size of the file. In the interest of conserving memory, the contents and file data are only available during the HTTP request in which the file was uploaded.

    UploadedFile Method Summary
     void dispose()
              Dispose of the resources associated with the file upload (this will happen automatically when the resource is garbage collected).
     java.lang.String getAsString()
              Use this method to retrieve the contents of the file as a String
     byte[] getBytes()
              Use this method to retrieve the contents of the file as an array of bytes.
     java.lang.String getContentType()
              Get the content-type that the browser communicated with the request that included the uploaded file.
     java.io.InputStream getInputStream()
              Returns a InputStream for reading the file.
     java.lang.String getOriginalName()
              Use this method to retrieve the name that the file has on the web application user's local system.
     long getSize()
              The size of the file in bytes
     void write(java.io.File file)
              Write the contents of the uploaded file to a file on the server host.
     

    Configuring the webuijsf:upload tag

    To access the contents of the uploaded file from the webuijsf:upload tag you have two options:

    • Bind the uploadedFile attribute to managed bean property of type com.sun.webui.jsf.model.UploadedFile. Have the setter or an action method process the file.
    • Specify a valueChangeListener on the Upload component. The method invoked by the value change listener has access to the new value of the component. method.

    To optionally specify a label for the component, use the label attribute, or specify a label facet.

    Client Side Javascript Functions

    In all the functions below, <id> should be the generated id of the Upload component.
    field_setDisabled(<id>, <disabled>) Enable/disable the field. Set <disabled> to true to disable the component, or false to enable it.
    field_setValue(<id>, <newValue>) Set the value of the field to <newValue>.
    field_getValue(<id>) Get the value of the field.
    field_getInputElement(<id>) Get hold of a reference to the input element rendered by this component.
    component_setVisible(<id>) Hide or show this component.

    Examples

    Get the contents of the file as a String (using a managed bean)

    On the form that controls the upload:

     
    <webuijsf:upload id="upload2"
               uploadedFile = "#{FileUploadBean.uploadedFile}"
               label="Choose a file: "
               required="true"/>
    

    On the page that displays the results of the upload:

     
    <webuijsf:staticText id="text"
                   text ="File contents are bound to string: " >
    <webuijsf:staticText id="text"
                   text ="#{FileUploadBean.stringContent}"/>
    
    

    The managed bean looks like this:

     
    import java.io.Serializable;
    import com.sun.webui.jsf.model.UploadedFile;
    
    public class FileUploadBean implements Serializable {
            
         //
         // Holds value of property uploadedFile.
         //
        transient private UploadedFile uploadedFile;
    
         //
         // Getter for property stringContent.
         // @return Value of property stringContent.
         //
        public String getStringContent() {
            return uploadedFile.getAsString();
        }
    
         //
         // Getter for property uploadedFile.
         // @return Value of property uploadedFile.
         //
        public UploadedFile getUploadedFile() {
            return this.uploadedFile;
        }
    
         //
         // Setter for property uploadedFile.
         // @param uploadedFile New value of property uploadedFile.
         //
        public void setUploadedFile(UploadedFile uploadedFile) {
            this.uploadedFile = uploadedFile;
        }
    }
    

    Write the contents of the file to disk (using a ValueChangeListener)

    On the form that controls the upload:

     
    <webuijsf:upload id="upload1"
               label="Choose a file: "
               valueChangeListener="#{FileUploadedListener.processValueChange}"/>
    

    Code for the ValueChangeListener

    import java.io.File; 
    import java.io.Serializable;
    import javax.faces.event.AbortProcessingException; 
    import javax.faces.event.ValueChangeEvent;
    import com.sun.webui.jsf.model.UploadedFile;
    
    public class FileUploadedListener implements ValueChangeListener, Serializable {
        
            public void processValueChange(ValueChangeEvent event) 
            throws AbortProcessingException {
            Object value = event.getNewValue(); 
            if(value != null && value instanceof UploadedFile) {
                UploadedFile uploadedFile = (UploadedFile)value;
                         
                String name = uploadedFile.getOriginalName();
                if(name == null || name.length() == 0) {
                    name = "tmp.tmp";
                }
                String suffix = name.substring(name.indexOf("."));
                if(suffix.length() == 0) {
                    suffix = ".tmp";
                }
                String prefix = name.substring(0, name.indexOf("."));
                try {
                    File tmpFile = File.createTempFile(prefix, suffix);
                    uploadedFile.write(tmpFile);
                } catch(Exception ex) {
                    // report the problem
                }         
            }
        }
    }
    
    versionPage

    Use the <webuijsf:versionPage> tag to display a version page.
    A version page is usually launched in a popup window from the masthead (see webuijsf:masthead).

    HTML Elements and Layout

    A version page consists of:
    • a product name image
    • a version string
    • copyright information
    • a close button

    The application version and copyright can be specified in directly on the jsp page or within a version information file.

     

    Client Side Javascript Functions

    none.
    wizard

    Use the webuijsf:wizard tag to create a popup wizard. A popup wizard is a secondary window that displays a series of steps in a user task. The wizard leads the user through the task one step at a time, requesting a series of responses and finally executing the task based on those responses.

    The webuijsf:wizard tag is the container for the webuijsf:wizardStep tags, which define the content of each step in the task. Simple wizards can be implemented with the webuijsf:wizard and webuijsf:wizardStep tags. See webuijsf:wizardStep for details on using the webuijsf:wizardStep tag.

    More complex wizards can be implemented to include steps that branch, in which the user's response determines which of two or more paths to take in completing a task. Use the webuijsf:wizardSubstepBranch, webuijsf:wizardBranch, and webuijsf:wizardBranchSteps for building more complex wizards with steps that branch.

    The wizard component implements Sun's user interface (UI) guidelines for web application wizards. The guidelines describe in detail how a wizard should appear and behave. The wizard component's default behavior implements the UI guidelines.

    Note: You should launch the wizard from a page in your application. For example, you could include a webuijsf:button tag whose onClick attribute is set to a JavaScript function that opens a popup to display the wizard JSP page. See the Examples section for more information.

    HTML Elements and Layout

    The wizard component is rendered with <div> and <table> XHTML elements, and within those elements are any number of XHTML elements that vary according to the components specified in the individual steps of the wizard.

    The default wizard contains the following areas:

    • Wizard Title - The wizard title occupies the first row of the wizard and spans the width of the wizard. The title text is specified with the webuijsf:wizard tag's title attribute.

    • Steps Pane - The Steps pane, displayed on the left side of the wizard, enumerates the steps of the wizard to show the user's current position in the wizard task, and to provide links back to preceding steps. The current step is indicated with an arrow displayed to the left of the step's number. Steps that precede the current step are displayed as hyperlinks, and the steps following are displayed as static text. The text displayed in the Steps pane for each step is specified with the summary attribute of each webuijsf:wizardStep tag.

      The Steps pane can also display help for the wizard, if you specify the help attribute in any of the wizard's webuijsf:wizardStep tags. When the help attribute is specified, the following tabs are displayed:

      • Steps tab - The tab is displayed in the left side of the Steps pane, and is selected by default. The Steps tab contains the same content that was described for the Steps pane.

      • Help tab - The tab is displayed to the right side of the Steps page, and shows the text that is assigned to the help attribute for the current step. The supplied text should provide information about completing the step.

      If no help attributes are specified in any of the steps, no tabs are displayed and only a steps list appears in the Steps pane.

    • Step Content - The step content area consists of the following areas:

      • Step Title - The title of the step, with the Step x: step number prefix. For example: Step 1: Title of the First Step. The text for the step title ("Title of the First Step") is specified with the webuijsf:wizardStep tag's title attribute, while the step number prefix is automatically generated by the wizard component.

      • Step Detail - Brief instructions or statements about the step, specified with the webuijsf:wizardStep tag's detail attribute

      • Step Input Controls - The input controls used to gather input from the user, such as text input fields, checkboxes, radiobuttons, drop down lists. See the webuijsf:wizardStep documentation for more more information about the step content.

    • Navigation Controls - The navigation buttons include Previous, Next or Finish, and Cancel or Close, which control the progression of the wizard steps. The finish attribute of the webuijsf:wizardStep tag causes the Finish button to be displayed instead of the Next button. The results attributes of the webuijsf:wizardStep tag causes the Close button to be displayed instead of the Cancel button.

    The following diagram shows the relative location of the wizard areas. The areas that are controlled with the webuijsf:wizard tag are highlighted in light blue. The grayed out areas are controlled with webuijsf:wizardStep tags, but are shown here for context.

    Wizard Title (title attribute)
    Steps Pane
    Steps Tab






    Help Tab
    Step Content Pane
    Step Title
    Step Detail
    Step Input Controls


    Navigation Controls                    

    Using the webuijsf:wizard Tag

    The webuijsf:wizard tag and its child tags are intended to be used in a JSP page whose sole purpose is to define a popup wizard. The JSP page should not include a masthead or breadcrumbs, for example, because the wizard will not render as desired when these components are used in the page.

    For the simplest wizards, which gather data to be used by the web application, you can simply define wizardSteps that contain their own child component tags. The child components' attributes can be bound to backing beans that store data entered by the user. When the wizard closes, that data is available to the application.

    Less simple wizards might require some action to be taken when the wizard closes. For example, you might want the wizard to send a request to the page that launched the wizard, to redirect the browser or refresh the page. The onPopupDismiss attribute can be used to perform this function. The value of onPopupDismiss must be a JavaScript statement that is executed during the response to a request that closes the window. The close request might occur as a result of the user clicking the Close, Cancel, Finish buttons, or some controlled application event that causes the the wizard to complete.

    Note: The JavaScript attributes (such as onCancel, onClose) must not be used to close the wizard popup window. Doing so will prevent the application from receiving the request that informs the application and the wizard framework that it should continue or exit (close, cancel) gracefully. The onPopupDismiss attribute is available for performing application-specific behavior on the client when the wizard is complete. The JavaScript attributes are useful for processing of data from actions the user has taken on the current step, such as client side validation.

    Wizard Buttons

    The wizard component handles the creation of the appropriate navigation buttons in each wizard step. For example, the first step is rendered with a disabled Previous button, a highlighted Next button, and an enabled Cancel button that is not highlighted. You must create an event listener to respond to events generated when the user clicks the buttons. You can also use tag attributes to specify JavaScript that is executed when a particular button is clicked.

    Event Listeners

    Events are executed as the user leaves the step. The webuijsf:wizard tag's eventListener attribute is used to specify the wizard event listener. The eventListener attribute must be bound to a value binding that evaluates to an object instance that implements the com.sun.webui.jsf.event.WizardEventListener interface. Note that the webuijsf:wizardStep tag also provides an eventListener attribute. You can choose to use the eventListener attribute on either or both the wizard or wizardStep component. The wizardStep event listener implementation might be more efficient. If you use event listeners on both the wizard and wizardStep components, the wizardStep's event listener is called first, and then the wizard's event listener is called. See the Examples section for an example of a wizard event listener class.

    Client-side JavaScript Functions

    When the component is rendered, a DOM object corresponding to the component is created. To manipulate the component on the client side, you may invoke functions on the DOM object. With reference to the DOM id, to close the wizard popup window, invoke document.getElementById(id).closePopup().

    The wizard component supports the following JavaScript functions, which can be used with the onPopupDismiss attribute.

    Function Purpose
    closeAndForward(openerForm,submitTo,clearState) Close the wizard popup window and forward a request to the specified page. This function accepts three arguments:
    • openerForm is a form that must exist in the window that opened the wizard popup window
    • submitTo is a URI that will replace the action property of the openerForm form.
    • clearState is a flag that should be set to true if the application is configured for client side state saving, and submitTo is a different page than the page that contains the openerForm form.
    closePopup() Close the wizard popup window. This function should only be used with popup wizards.
    wizOnLoad() This method must be assigned to the onload handler of the onLoad attribute of the webuijsf:body tag if the wizard is to operate properly on IE.

    For example, to alter the behavior when the wizard popup closes, specify the following JavaScript as the value of the onPopupDismiss attribute:

    onPopupDismiss="document.getElementById('form1:wizard1').closeAndForward('openerForm',
     '/app/faces/wizardResults.jsp',true);"

     

    This JavaScript invokes the JavaScript wizard object's closeAndForward() method with a form DOM id from the window that opened the popup, and submits that form with the action set to the specified JSP page.

    JavaScript Function for Correct Wizard Rendering on IE 6

    If your web application will be used in Internet Explorer 6, you must specify the document.getElementById('form1:wizard1').wizOnLoad() function in the webuijsf:body tag in your JSP page. This function enables the wizard to be rendered correctly. For example:

    <webuijsf:body
           onLoad="document.getElementById('form1:wizard1').wizOnLoad()">

    The argument to the document.getElementById('form1:wizard1').wizOnLoad() function is the DOM id that results from the ids of the form and wizard components.

    Examples

    The example shown here is for creating a simple wizard. This example includes:

    The webuijsf:wizardBranch documentation shows an example of a more complex wizard.

    Example 1: Simple Popup Wizard

    This example shows a complete JSP page that uses a simple wizard. This wizard has no overview page or results page, and contains no branching or substeps. Notice that the webuijsf:body tag includes the attribute onload="document.getElementById('form1:wizard1').wizOnLoad()", which is needed for the wizard to display correctly in Internet Explorer.

    <jsp:root version="1.2"
               xmlns:jsp="http://java.sun.com/JSP/Page"
               xmlns:f="http://java.sun.com/jsf/core"
               xmlns:h="http://java.sun.com/jsf/html"
               xmlns:webuijsf="http://www.sun.com/webui/webuijsf">
     <jsp:directive.page contentType="text/html;charset=UTF-8"
                         pageEncoding="UTF-8"/>
     <f:view>
         <webuijsf:page>
     	<webuijsf:html>
     	    <webuijsf:head title="Wizard Example" />
     	    <webuijsf:body
                      onLoad="document.getElementById('form1:wizard1').wizOnLoad()">		
                 <webuijsf:form id="form1">
     <!-- Simplest Wizard 
         Order of steps is order of evaluation of children.
         No Overview page.
         No Results page.
         Demonstrates how a wizard step's content is defined.
         Value bindings are supported. -->
         <webuijsf:wizard id="wizard1"
     	title="Create Account">
     	<webuijsf:wizardStep id="step1"
     	    summary="Choose Account Type"
     	    title="New Account Setup"
     	    detail="Select the type of account you would like to set up:"
     	    help="In order to receive messages, you first need to set up a Mail or Newsgroup account. 
                       This Wizard will collect the information necessary to set up a Mail or Newsgroup 
                       account. If you do not know the information requested, please contact your System 
                       Administrator or Internet Service Provider.">
     	    <webuijsf:markup tag="p" extraAttributes="style='margin-left:2%'">
     	    <webuijsf:radioButton id="email" name="account"
     		label="Email account"
     		selectedValue="EmailAccount"
     		selected="#{emailAccount.acctType}"/>
     	    <webuijsf:markup tag="br" singleton="true"/>
     	    <webuijsf:radioButton id="movemail" name="account"
     		label="Movemail"
     		selectedValue="MoveMail"
     		selected="#{emailAccount.acctType}"/>
     	    <webuijsf:markup tag="br" singleton="true"/>
     	    <webuijsf:radioButton id="rss" name="account"
     		label="RSS News and Blogs"
     		selectedValue="RSSNewsAndBlogs"
     		selected="#{emailAccount.acctType}"/>
     	    <webuijsf:markup tag="br" singleton="true"/>
     	    <webuijsf:radioButton id="news" name="account"
     		label="Newsgroup account"
     		selectedValue="Newsgroup"
     		selected="#{emailAccount.acctType}"/>
     	    </webuijsf:markup>
     	</webuijsf:wizardStep>
     	<webuijsf:wizardStep id="step2"
     	    summary="Specify Email Identity"
     	    title="Identity"
     	    detail="Enter outgoing email name and email address."
     	    help="Each account has an identity, which is the information that identifies 
                       you to others when they receive your messages. Enter the name you would 
                       like to appear in the From field of your outgoing messages, for example, 
                       John Smith. Then enter your email address. This is the address others 
                       will use to send email to you, for example john.smith@sun.com.">
     	    <webuijsf:markup tag="p" extraAttributes="style='margin-left:2%'">
     	    <webuijsf:label id="namelbl" text="Your Name"/>
     	    <webuijsf:textField id="namefld"
     		required="true"
     		validator='#{emailAccount.validate}'
     		text='#{emailAccount.userName}'/>
     	    <webuijsf:markup tag="br" singleton="true"/>
     	    <webuijsf:label id="eaddrlbl" text="Email Address"/>
     	    <webuijsf:textField id="eaddrfld"
     		required="true"
     		validator='#{emailAccount.validate}'
     		text='#{emailAccount.emailAddr}'/>
     	    </webuijsf:markup>
     	</webuijsf:wizardStep>
     	<webuijsf:wizardStep id="step3"
     	    summary="Specify Email Server"
     	    title="Email Server Information"
     	    detail="Select the type of incoming server and server name."
     	    help="Select the type of the incoming server you are using. 
                       Then enter the name of your incoming server, for example, mail.sun.com.">
     	    <webuijsf:markup tag="p" extraAttributes="style='margin-left:2%'">
     	    <webuijsf:radioButton id="pop" name="mailservertype"
     		label="POP"
     		selectedValue="Pop"
     		selected="#{emailAccount.serverType}"/>
     	    <webuijsf:markup tag="br" singleton="true"/>
                 <webuijsf:radioButton id="imap" name="mailservertype"
     		label="IMAP"
     		selectedValue="Imap"
     		selected="#{emailAccount.serverType}"/>
     	    <webuijsf:markup tag="br" singleton="true"/>
     	    <webuijsf:label id="inserverlbl" text="Incoming Server"/>
     	    <webuijsf:textField id="inserverfld"
     		required="true"
     		validator='#{emailAccount.validate}'
     		text='#{emailAccount.inServer}'/>
     	    <webuijsf:markup tag="br" singleton="true"/>
     	    <webuijsf:label id="outserverlbl" text="Outgoing Server"/>
     	    <webuijsf:textField id="outserverfld"
     		required="true"
     		validator='#{emailAccount.validate}'
     		text='#{emailAccount.outServer}'/>
     	    </webuijsf:markup>
     	</webuijsf:wizardStep>
     	<webuijsf:wizardStep id="step4"
     	    summary="Specify User Name"
     	    title="User Names"
     	    detail="Enter email provider assigned user name."
     	    help="Enter your existing outgoing and incoming (SMTP) username, 
                  for example jsmith. You can modify outgoing server settings by choosing 
                   Account Settings from the Tools menu.">
     	    <webuijsf:markup tag="p" extraAttributes="style='margin-left:2%'">
     	    <webuijsf:label id="innamelbl" text="Incoming User Name"/>
     	    <webuijsf:textField id="innamefld"
     		required="true"
     		validator='#{emailAccount.validate}'
     		text='#{emailAccount.inName}'/>
     	    <webuijsf:markup tag="br" singleton="true"/>
     	    <webuijsf:label id="outnamelbl" text="Outgoing User Name"/>
                 <webuijsf:textField id="outnamefld"
     		required="true"
     		validator='#{emailAccount.validate}'
     		text='#{emailAccount.outName}'/>
     	    </webuijsf:markup>
     	</webuijsf:wizardStep>
     	<webuijsf:wizardStep id="step5"
     	    summary="Specify Account Name"
     	    title="Account Name"
     	    detail="The name of the account."
     	    help="Enter the name by which you would like to refer to this account, 
                    for example Work Account, Home Account, or News Account, etc.">
     	    <webuijsf:markup tag="p" extraAttributes="style='margin-left:2%'">
     	    <webuijsf:label id="acctnamelbl" text="Account Name"/>
     	    <webuijsf:textField id="acctnamefld"
     		required="true"
     		validator='#{emailAccount.validate}'
     		text='#{emailAccount.acctName}'/>
     	    </webuijsf:markup>
     	</webuijsf:wizardStep>
     	<webuijsf:wizardStep id="step6"
     	    summary="Verify Information"
     	    title="Verify Account Information"
     	    detail="Verify the information below is correct."
     	    help="Click finish to create the account and previous if corrections are required."
                 finish="true">
     	    <webuijsf:markup tag="p" extraAttributes="style='margin-left:2%'">
     	    <webuijsf:label id="v_accttypelbl" text="Accout Type:"/>
     	    <webuijsf:staticText id="v_accttypetxt"
     		text='#{emailAccount.acctType}'/>
     	    <webuijsf:markup tag="br" singleton="true"/>
     	    <webuijsf:label id="v_usernamelbl" text="User Name:"/>
     	    <webuijsf:staticText id="v_usernametxt"
     		text='#{emailAccount.userName}'/>
     	    <webuijsf:markup tag="br" singleton="true"/>
     	    <webuijsf:label id="v_acctnamelbl" text="Account Name:"/>
     	    <webuijsf:staticText id="v_acctnametxt"
     		text='#{emailAccount.acctName}'/>
     	    <webuijsf:markup tag="br" singleton="true"/>
     	    <webuijsf:label id="v_eaddrlbl" text="Email Address:"/>
     	    <webuijsf:staticText id="v_eaddrtxt"
     		text='#{emailAccount.emailAddr}'/>
     	    <webuijsf:markup tag="br" singleton="true"/>
     	    <webuijsf:label id="v_innamelbl" text="Incoming User Name:"/>
     	    <webuijsf:staticText id="v_innametxt"
     		text='#{emailAccount.inName}'/>
     	    <webuijsf:markup tag="br" singleton="true"/>
     	    <webuijsf:label id="v_insrvnamelbl" text="Incoming Server Name:"/>
     	    <webuijsf:staticText id="v_insrvnametxt"
     		text='#{emailAccount.inServer}'/>
     	    <webuijsf:markup tag="br" singleton="true"/>
     	    <webuijsf:label id="v_insrvtypelbl" text="Incoming Server Type:"/>
     	    <webuijsf:staticText id="v_insrvtypetxt"
     		text='#{emailAccount.serverType}'/>
     	    <webuijsf:markup tag="br" singleton="true"/>
     	    <webuijsf:label id="v_outnamelbl" text="Outgoing User Name:"/>
     	    <webuijsf:staticText id="v_outnametxt"
     		text='#{emailAccount.outName}'/>
     	    <webuijsf:markup tag="br" singleton="true"/>
     	    <webuijsf:label id="v_outsrvnamelbl" text="Outgoing Server Name:"/>
     	    <webuijsf:staticText id="v_outsrvnametxt"
     		text='#{emailAccount.outServer}'/>
     	    </webuijsf:markup>
     	</webuijsf:wizardStep>
         </webuijsf:wizard>
     		</webuijsf:form>
     	    </webuijsf:body>
             </webuijsf:html>
         </webuijsf:page>
     </f:view>
     </jsp:root>
     

    EmailAccount.java Backing Bean

    The emailAccount backing bean is used by the example JSP shown in the previous section. The bean defines getters and setters for the component properties and defines the EmailAccountWizardEventListener, which implements the WizardEventListener interface.

    package wizard;
     import javax.faces.application.FacesMessage;
     import javax.faces.context.FacesContext;
     import javax.faces.component.UIComponent;
     import javax.faces.validator.Validator;
     import javax.faces.validator.ValidatorException;
     import com.sun.webui.jsf.event.WizardEvent;
     import com.sun.webui.jsf.event.WizardEventListener;
     import com.sun.webui.jsf.component.Wizard;
     import com.sun.webui.jsf.component.WizardStep;
     public class EmailAccountBean {
         private String acctType;
         private String userName;
         private String acctName;
         private String emailAddr;
         private String inName;
         private String inServer;
         private String serverType;
         private String outName;
         private String outServer;
         private boolean globalInbox = true;
         private Validator wizardValidator;
         public EmailAccountBean() {
     	this.acctType = "EmailAccount";
     	this.serverType= "Pop";
     	this.wizardValidator = new WizardValidator();
         }
         public void validate(FacesContext context,
     	    UIComponent component, Object value) 
     	    throws ValidatorException {
     	wizardValidator.validate(context, component, value);
         }
         public String getAcctType() {
     	return acctType;
         }
         public String getUserName() {
     	return userName;
         }
         public String getAcctName() {
     	return acctName;
         }
         public String getEmailAddr() {
     	return emailAddr;
         }
         public String getInName() {
     	return inName;
         }
         public String getInServer() {
     	return inServer;
         }
         public String getServerType() {
     	if (acctType.equals("MoveMail")) {
     	    return "MoveMail";
     	} else {
     	    return serverType;
     	}
         }
         public String getOutName() {
     	if (acctType.equals("MoveMail") || acctType.equals("Newsgroup")) {
     	    return emailAddr.substring(0, emailAddr.indexOf("@"));
     	} else {
     	    return outName;
     	}
         }
         public String getOutServer() {
     	return outServer;
         }
         // One of 
         // "EmailAccount"
         // "MoveMail"
         // "RSSNewsAndBlogs"
         // "Newsgroup"
         //
         public void setAcctType(String acctType) {
     	if (acctType != null && acctType.length() != 0) {
     	    this.acctType = acctType;
     	}
         }
         public void setUserName(String userName) {
     	this.userName = userName;
         }
         public void setAcctName(String acctName) {
     	this.acctName = acctName;
         }
         public void setEmailAddr(String emailAddr) {
     	this.emailAddr = emailAddr;
         }
         public void setInName(String inName) {
     	this.inName = inName;
         }
         public void setInServer(String inServer) {
     	this.inServer = inServer;
         }
         public void setServerType(String serverType) {
     	if (serverType != null && serverType.length() != 0) {
     	    this.serverType = serverType;
     	}
         }
         public void setOutName(String outName) {
     	this.outName = outName;
         }
         public void setOutServer(String outServer) {
     	this.outServer = outServer;
         }
         public void setGlobalInbox(boolean globalInbox) {
     	this.globalInbox = globalInbox;
         }
         public boolean getglobalInbox() {
     	return globalInbox;
         }
         public WizardEventListener getWizardEventListener() {
     	return new EmailAccountWizardEventListener();
         }
         public WizardEventListener getWizardStepEventListener() {
     	return new EmailAccountWizardEventListener();
         }
     }
     class EmailAccountWizardEventListener implements WizardEventListener {
     	// If this method returns false, the event is not forwarded to 
     	// the wizard model and the wizard will remain on the same
     	// step that triggered this event.
     	//
     	// The step event listener is called first then the 
     	// wizard's event listener. If the wizard's event listener
     	// returns false, even if the step listener returned true,
     	// the wizard will remain on the same step that triggered
     	// this event.
     	//
     	// If an exception is thrown, the wizard model is forwarded
     	// the WizardEvent.CANCEL event, and the wizard behaves as
     	// if the user clicked the cancel button.
     	//
         public boolean handleEvent(WizardEvent event) {
     	WizardStep step = event.getStep();
     	Wizard wizard = event.getWizard();
     	switch (event.getNavigationEvent()) {
     	// The START and COMPLETE events are special events that are only 
     	// broadcast to the wizard's event listener.
     	// 
     	// The START event is broadcast only once when the wizard is first
     	// rendered. This event will only be broadcast again, if the
     	// same Wizard component instance is rendered again after having
     	// broadcast the COMPLETE event.
     	//
     	case WizardEvent.START:
     	break;
     	// The COMPLETE event is broadcast only once after the wizard's
     	// last response is written, and the wizard popup has been 
     	// closed. If this Wizard component instance is rendered again, the 
     	// START event will be broadcast.
     	//
     	case Wizardevent.COMPLETE:
     	    // These statements might be necessary if the application
     	    // is configured with server side state saving.
     	    // 
     	    // In some situations a value entered by a user may "stick"
     	    // across different wizard sessions. It can happen if a
     	    // user enters data into an input field and then cancels
     	    // the wizard session or something occurs that causes
     	    // the wizard to skip the validation phase and then the
     	    // wizard is cancelled. The next time the wizard is rendered
     	    // it may display the previous value. 
     	    //
     	    // One way to remedy this situation is to perform the following
     	    // during the COMPLETE event.
     	    //
     	    // This works because new instances of the wizard's step
     	    // components are recreated. The step children are not 
     	    // typically recreated when an application is configured
     	    // with server side state saving.
     	    //
     	    Wizard wizard = (Wizard)event.getSource();
     	    wizard.getChildren().clear();
     	break;
     	case WizardEvent.NEXT:
     	break;
     	case WizardEvent.PREVIOUS:
     	break;
     	case WizardEvent.CANCEL:
     	break;
     	case WizardEvent.FINISH:
     	break;
     	case WizardEvent.CLOSE:
     	break;
     	case WizardEvent.HELPTAB:
     	break;
     	case WizardEvent.STEPSTAB:
     	break;
     	case WizardEvent.GOTOSTEP:
     	    String gotoStepId = event.getGotoStepId();
     	break;
     	case WizardEvent.NOEVENT:
     	break;
     	}
     	return true;
         }
         public void setTransient(boolean transientFlag) {
         }
         public Object saveState(FacesContext context) {
     	return null;
         }
         public void restoreState(FacesContext context, Object state) {
         }
         public boolean isTransient() {
     	return false;
         }
     }
     

    JSP for Launching the Wizard

    This example shows how you might launch a wizard, using JavaScript enabled buttons.

    <jsp:root version="1.2"
               xmlns:jsp="http://java.sun.com/JSP/Page"
               xmlns:f="http://java.sun.com/jsf/core"
               xmlns:h="http://java.sun.com/jsf/html"
               xmlns:webuijsf="http://www.sun.com/webui/webuijsf">
     <jsp:directive.page contentType="text/html;charset=UTF-8"
                         pageEncoding="UTF-8"/>
     <f:view>
         <webuijsf:page>
     	<webuijsf:html>
     	    <webuijsf:head title="Wizard Example" />
     	    <webuijsf:body>
     	    <webuijsf:form id="form1">
     		<webuijsf:breadcrumbs id="breadcrumbs">
     		    <webuijsf:hyperlink url="../faces/index.jsp"
     			text="TestApp Index"/>
     		    <webuijsf:hyperlink url="../faces/wizard/index.jsp"
     		    text="Wizard"/>
     		</webuijsf:breadcrumbs>
     		<f:verbatim><![CDATA[
     		<script type="text/javascript">
     	    function golden_mean_top(height) {
     		return ((screen.height-(screen.height/1.618))-(height/2));
     	    }
     	    function golden_mean_left(width) {
     		return ((screen.width-width)/2);
     	    }
     	    function wizard_popup(url, name, height, width) {
     		var top=golden_mean_top(height);
     		var left=golden_mean_left(width);
     		var newurl = url + "?&amp;WIZARD_NAME=" + name;
     		var args= "height=" + height + ",width=" + width +
     			    ",top=" + top + ",left=" + left;
     		window.open(newurl, name, args);
     		return false;
     	    }
     	    function wizard_launch(url) {
     		wizard_popup("../faces/wizard/" + url,
     			"Wizard", 400, 600);
     	    }
     		</script>]]>
     		</f:verbatim>
     	<webuijsf:panelGroup style="margin-left:10px"
     	    id="linkGroup" separator="&lt;br/&gt;&lt;br/&gt;">
     	    <webuijsf:button primary="true"
     	id="wizard_popup3" text="Create Email Account (Simple)"
     	    onClick="wizard_launch('emailaccount.jsp'); return false;"/>
     	    <webuijsf:button primary="true"  id="wizard_popup1"
     		text="Launch Submitting Steps Wizard"
                     onClick="wizard_launch('wizard-submit-component-steps.jsp'); return false;"/>
     	</webuijsf:panelGroup>
     	    </webuijsf:form>
     	    </webuijsf:body>
             </webuijsf:html>
         </webuijsf:page>
     </f:view>
     </jsp:root>
     
    wizardBranch

    Use the webuijsf:wizardBranch tag to define a branch of steps within a wizard.  The webuijsf:wizardBranch tag must be used as a child of the webuijsf:wizard tag, or as a child of another webuijsf:wizardBranch tag.

    The webuijsf:wizardBranch tag is a container for webuijsf:wizardBranchSteps, which define the different branch sequences that can be followed. The content of each step of a branch sequence is then defined with webuijsf:wizardStep tags.

    The webuijsf:wizardBranch tag should be used when the paths from the branch diverge, and never return to a common step after the branch. If you want the branches to return to a common step in the major sequence of steps in the wizard, you should use the webuijsf:wizardSubstepBranch tag. See the webuijsf:wizardSubstepBranch documentation.

    See the Sun Web Application Guidelines 3.0 for more information about deciding which type of branching to use.

    HTML Elements and Layout

    No HTML elements are rendered for the webuijsf:wizardBranch tag. The webuijsf:wizardBranch tag's function is to contain the branch sequences, and to provide a way to conditionally render one of the sequences.

    When the user progresses through a wizard and arrives at a step that is followed by a branch, the Steps pane displays placeholder text for that step. The placeholder text is used instead of the summary text that would normally be shown for a step, because the steps to be taken are at this point undetermined.  The placeholder text is replaced by the step summary text after the branch path is chosen.

    Using the webuijsf:wizardBranch tag

    The webuijsf:wizardBranch tag lets you define multiple branches that contain sequences of steps, and to determine whether the branch should be taken.

    The value of the webuijsf:wizardBranch tag's taken attribute determines whether the branch is followed. When taken is set to true, the branch is followed. If taken is false, the branch is not followed. The value of the taken attribute should be set to an expression that uses the user's response in a preceding step, to determine whether the branch should be followed.

    The placeholderText attribute is used to specify text that is to be displayed in the Steps pane when the branching step is displayed. The branching step gathers responses from the user so that the wizard can determine which branch to take, if any. The placeholderText value is displayed only while the taken attribute is false. Typically, you would want the taken attribute to evaluate to false when the branching step is initially displayed, before the user makes a response that can be used in setting the value of the taken attribute.

    The webuijsf:wizardBranchSteps tag is used for each possible sequence that can be followed in the branch.

    The following pseudocode shows the relationship of the wizard components when using the wizardBranch:

    <webuijsf:wizard>
        ... (initial steps where no branching is needed)

        <webuijsf:wizardStep>
                 The user's choice in this wizardStep should be used to
                 determine whether the branch is followed.  Note that the
                 wizardBranch is NOT a child of the wizardStep component.

        </webuijsf:wizardStep>
     
        <webuijsf:wizardBranch>
                 The wizard framework uses the wizardBranch's taken attribute value
                 to decide whether to process the branch.

            <webuijsf:wizardBranchSteps>
                 This wizardBranchSteps component represents the first choice
                 available to the user in
    a wizardStep that occurs before the branch.
                 <webuijsf:wizardStep>

                   These steps are only rendered when this branch is taken.

                 </webuijsf:wizardStep>


                
    <webuijsf:wizardStep>
                  ...

                 </webuijsf:wizardStep>


                 <webuijsf:wizardStep>
                  ...

                 </webuijsf:wizardStep>

                 ...
           </webuijsf:wizardBranchSteps>
      
           <webuijsf:wizardBranchSteps>
                 This wizardBranchSteps component represents the second choice
                 available to the user in a wizardStep that occurs before the branch.

                
    <webuijsf:wizardStep>
                  ...

                 </webuijsf:wizardStep>

                <webuijsf:wizardStep>
                 </webuijsf:wizardStep>

                 ...
           </webuijsf:wizardBranchSteps>

        </webuijsf:wizardBranch>

    </webuijsf:wizard>

          

    Client-side JavaScript Functions

    None.

    Examples

    The example shown here is for creating a branching wizard. This example uses the following files:

    Example 1: Branching Wizard

    This emailaccount-branch.jsp example shows a complete JSP page that uses webuijsf:wizardBranch.

    This wizard includes:

    • a branch
    • a Finish page to allows users to verify information before submitting
    • a View Results page to give feedback to users that the wizard task completed
    • step content specified though f:subview tags

    emailaccount-branch.jsp

    <jsp:root version="1.2"
    xmlns:jsp="http://java.sun.com/JSP/Page"
    xmlns:f="http://java.sun.com/jsf/core"
    xmlns:h="http://java.sun.com/jsf/html"
    xmlns:webuijsf="http://www.sun.com/webui/webuijsf">
    <jsp:directive.page contentType="text/html;charset=UTF-8"
    pageEncoding="UTF-8"/>
    <f:view>
    <webuijsf:page>
    <webuijsf:html>
    <webuijsf:head title="Wizard Example" />
    <webuijsf:body
    onLoad="document.getElementById('form1:wizard1').wizOnLoad()">
    <webuijsf:form id="form1">

    <webuijsf:wizard id="wizard1" title="Create Account"
    eventListener="#{emailAccount.wizardEventListener}" >


    <!-- The first step, user chooses an account type.
    This example is contrived in that you would never
    have the first step as a choice and then branch.
    You would have separate wizards, that shared jsp
    pages, but the choice on a main page that would
    launch the appropriate wizard.

    -->

    <webuijsf:wizardStep id="step1"
    summary="Choose Account Type"
    title=" New Account Setup"
    detail="Select the type of account you would like to set up:"
    help="In order to receive messages, you first need to set up a Mail or
    Newsgroup account. This Wizard will collect the information necessary
    to set up a Mail or Newsgroup account. If you do not know the information
    requested, please contact your System Administrator or Internet Service Provider.">

    <jsp:include page="../wizard/acct-steps/accttype.jsp"/>

    </webuijsf:wizardStep>

    <!-- Take the branch if a choice was made on the first step.
    wizardBranchSteps are taken based on the choice made.
    -->
    <webuijsf:wizardBranch id="branch"
    taken='#{emailAccount.acctType != ""}'
    placeholderText="The steps that will follow are determined based on the type of account chosen" >

    <webuijsf:wizardBranchSteps id="bs0"
    taken='#{emailAccount.acctType == "EmailAccount" || emailAccount.acctType == "MoveMail" || emailAccount.acctType == "Newsgroup"}'>

    <webuijsf:wizardStep id="step2"
    eventListener="#{emailAccount.wizardStepEventListener}"
    summary="Specify Email Identity"
    title="Identity"
    detail="Enter outgoing email name and email address."
    help="Each account has an identity, which is the information that
    identifies you to others when they receive your messages. Enter the
    name you would like to appear in the From field of your outgoing messages,
    for example, John Smith. Then enter your email address. This is the address
    others will use to send email to you, for example john.smith@sun.com.">

    <jsp:include page="../wizard/acct-steps/identity.jsp"/>

    </webuijsf:wizardStep>

    </webuijsf:wizardBranchSteps>

    <webuijsf:wizardBranchSteps id="bs1"
    taken='#{emailAccount.acctType == "EmailAccount"}'>

    <webuijsf:wizardStep id="step3"
    summary="Specify Email Server"
    title="Email Server Information"
    detail="Select the type of incoming server and outgoing server name."
    help="&lt;p&gt;Select the type of the incoming server you are using. Then enter the name
    of your incoming server, for example, mail.sun.com.&lt;/p&gt;&lt;p&gt;Then enter the
    outgoing (SMTP) server name, for example, smtp.sun.com&lt;/p&gt;">

    <jsp:include page="../wizard/acct-steps/emailserver.jsp"/>

    </webuijsf:wizardStep>


    <webuijsf:wizardStep id="step4"
    summary="Specify User Name"
    title="User Names"
    detail="Enter email provider assigned user name."
    help="Enter your existing outgoing and incoming (SMTP) username,
    for example jsmith. You can modify outgoing server settings by
    choosing Account Settings from the Tools menu.">

    <jsp:include page="../wizard/acct-steps/username.jsp"/>

    </webuijsf:wizardStep>

    </webuijsf:wizardBranchSteps>

    <!-- For a movemail account only an outgoing server is needed.-->

    <webuijsf:wizardBranchSteps id="bs2"
    taken='#{emailAccount.acctType == "MoveMail"}'>

    <webuijsf:wizardStep id="step3"
    summary="Specify Outgoing Server"
    title="Outgoing Server Information"
    detail="Specify the outgoing server name."
    help="Enter the outgoing (SMTP) server name, for example, smtp.sun.com.">

    <jsp:include page="../wizard/acct-steps/outgoingserver.jsp"/>

    </webuijsf:wizardStep>

    </webuijsf:wizardBranchSteps>

    <webuijsf:wizardBranchSteps id="bs3"
    taken='#{emailAccount.acctType == "Newsgroup"}'>

    <webuijsf:wizardStep id="step3"
    summary="Specify News Server"
    title="News Server Information"
    detail="Specify the news server name."
    help="Enter the news (NNTP) server name, for example, news.sun.com.">
    <jsp:include page="../wizard/acct-steps/newsserver.jsp"/>

    </webuijsf:wizardStep>

    </webuijsf:wizardBranchSteps>

    <!-- Always taken -->

    <webuijsf:wizardStep id="step5"
    summary="Specify Account Name"
    title="Account Name"
    detail="The name of the account."
    help="Enter the name by which you would like to refer to this account,
    for example Work Account, Home Account, or News Account, etc.">

    <jsp:include page="../wizard/acct-steps/acctname.jsp"/>

    </webuijsf:wizardStep>

    <webuijsf:wizardStep id="step6"
    finish="true"
    summary="Verify Information"
    title="Verify Account Information"
    detail="Verify the information below is correct."
    help="Click finish to create the account and previous if corrections are required."
    onFinish="alert('WizardStep onFinish')">

    <jsp:include page="../wizard/acct-steps/verifyfinish.jsp"/>

    </webuijsf:wizardStep>

    <webuijsf:wizardStep id="step7"
    results="true"
    summary="Results"
    title="Results"
    detail="Congratualations. Account Created."
    help="Click close to end the wizard session."
    onClose="alert('WizardStep onClose')">

    <jsp:include page="../wizard/acct-steps/verifyfinish.jsp"/>

    </webuijsf:wizardStep>
    </webuijsf:wizardBranch>

    </webuijsf:wizard>

    </webuijsf:form>
    </webuijsf:body>
    </webuijsf:html>
    </webuijsf:page>
    </f:view>
    </jsp:root>

    Included JSP Pages

    The JSP pages shown here provide the content of the steps in wizard that is used in the emailaccount-branch.jsp.

    acctname.jsp

    <jsp:root version="1.2"
    xmlns:jsp="http://java.sun.com/JSP/Page"
    xmlns:f="http://java.sun.com/jsf/core"
    xmlns:h="http://java.sun.com/jsf/html"
    xmlns:webuijsf="http://www.sun.com/webui/webuijsf">
    <jsp:directive.page contentType="text/html;charset=ISO-8859-1"
    pageEncoding="UTF-8"/>

    <f:subview id="sv_acctname">

    <webuijsf:markup tag="p" extraAttributes="style='margin-left:2%'">

    <webuijsf:label id="acctnamelbl" text="Account Name"/>
    <webuijsf:textField id="acctnamefld"
    required="true"
    validator='#{emailAccount.validate}'
    text='#{emailAccount.acctName}'/>
    <h:message id="acctnamefld_msg" for="acctnamefld"
    showDetail="true"/>

    </webuijsf:markup>

    </f:subview>
    </jsp:root>

    accttype.jsp

    <jsp:root version="1.2"
    xmlns:jsp="http://java.sun.com/JSP/Page"
    xmlns:f="http://java.sun.com/jsf/core"
    xmlns:h="http://java.sun.com/jsf/html"
    xmlns:webuijsf="http://www.sun.com/webui/webuijsf">
    <jsp:directive.page contentType="text/html;charset=ISO-8859-1"
    pageEncoding="UTF-8"/>

    <f:subview id="sv_accttype">

    <webuijsf:markup tag="p" extraAttributes="style='margin-left:2%'">

    <webuijsf:radioButton id="email" name="account"
    label="Email account"
    selectedValue="EmailAccount"
    selected="#{emailAccount.acctType}"/>

    <webuijsf:markup tag="br" singleton="true"/>

    <webuijsf:radioButton id="movemail" name="account"
    label="Movemail"
    selectedValue="MoveMail"
    selected="#{emailAccount.acctType}"/>

    <webuijsf:markup tag="br" singleton="true"/>

    <webuijsf:radioButton id="rss" name="account"
    label="RSS News and Blogs"
    selectedValue="RSSNewsAndBlogs"
    selected="#{emailAccount.acctType}"/>

    <webuijsf:markup tag="br" singleton="true"/>

    <webuijsf:radioButton id="news" name="account"
    label="Newsgroup account"
    selectedValue="Newsgroup"
    selected="#{emailAccount.acctType}"/>

    </webuijsf:markup>
    </f:subview>
    </jsp:root>

    emailserver.jsp

    <jsp:root version="1.2"
    xmlns:jsp="http://java.sun.com/JSP/Page"
    xmlns:f="http://java.sun.com/jsf/core"
    xmlns:h="http://java.sun.com/jsf/html"
    xmlns:webuijsf="http://www.sun.com/webui/webuijsf">
    <jsp:directive.page contentType="text/html;charset=ISO-8859-1"
    pageEncoding="UTF-8"/>

    <f:subview id="sv_emailserver">

    <webuijsf:markup tag="p" extraAttributes="style='margin-left:2%'">

    <webuijsf:radioButton id="pop" name="mailservertype"
    label="POP"
    selectedValue="Pop"
    selected="#{emailAccount.serverType}"/>

    <webuijsf:markup tag="br" singleton="true"/>

    <webuijsf:radioButton id="imap" name="mailservertype"
    label="IMAP"
    selectedValue="Imap"
    selected="#{emailAccount.serverType}"/>

    <webuijsf:markup tag="br" singleton="true"/>

    <webuijsf:label id="inserverlbl" text="Incoming Server"/>
    <webuijsf:textField id="inserverfld"
    required="true"
    validator='#{emailAccount.validate}'
    text='#{emailAccount.inServer}'/>
    <h:message id="inserverfld_msg" for="inserverfld"
    showDetail="true"/>

    <jsp:include page="../../wizard/acct-steps/outgoingserver.jsp"/>

    </webuijsf:markup>

    </f:subview>
    </jsp:root>

    identity.jsp

    <jsp:root version="1.2"
    xmlns:jsp="http://java.sun.com/JSP/Page"
    xmlns:f="http://java.sun.com/jsf/core"
    xmlns:h="http://java.sun.com/jsf/html"
    xmlns:webuijsf="http://www.sun.com/webui/webuijsf">
    <jsp:directive.page contentType="text/html;charset=ISO-8859-1"
    pageEncoding="UTF-8"/>

    <f:subview id="sv_identity">

    <webuijsf:markup tag="p" extraAttributes="style='margin-left:2%'">

    <webuijsf:label id="namelbl" text="Your Name"/>
    <webuijsf:textField id="namefld"
    required="true"
    validator='#{emailAccount.validate}'
    text='#{emailAccount.userName}'/>
    <h:message id="namefld_msg" for="namefld"
    showDetail="true"/>

    <webuijsf:markup tag="br" singleton="true"/>

    <webuijsf:label id="eaddrlbl" text="Email Address"/>
    <webuijsf:textField id="eaddrfld"
    required="true"
    validator='#{emailAccount.validate}'
    text='#{emailAccount.emailAddr}'/>
    <h:message id="eaddrfld_msg" for="eaddrfld"
    showDetail="true"/>

    </webuijsf:markup>


    </f:subview>
    </jsp:root>

       

    inboxtype.jsp

    <jsp:root version="1.2"
    xmlns:jsp="http://java.sun.com/JSP/Page"
    xmlns:f="http://java.sun.com/jsf/core"
    xmlns:h="http://java.sun.com/jsf/html"
    xmlns:webuijsf="http://www.sun.com/webui/webuijsf">
    <jsp:directive.page contentType="text/html;charset=ISO-8859-1"
    pageEncoding="UTF-8"/>

    <f:subview id="sv_inboxtype">

    <webuijsf:markup tag="p" extraAttributes="style='margin-left:2%'">

    <webuijsf:checkbox id="inbox" name="inboxtype"
    label="Use Global Inbox (store mail in Local Folders)"
    selected="#{emailAccount.globalInbox}"/>

    </webuijsf:markup>


    </f:subview>
    </jsp:root>

    movemailserver.jsp

    <jsp:root version="1.2"
    xmlns:jsp="http://java.sun.com/JSP/Page"
    xmlns:f="http://java.sun.com/jsf/core"
    xmlns:h="http://java.sun.com/jsf/html"
    xmlns:webuijsf="http://www.sun.com/webui/webuijsf">
    <jsp:directive.page contentType="text/html;charset=ISO-8859-1"
    pageEncoding="UTF-8"/>

    <f:subview id="sv_mvmailserver">

    <webuijsf:markup tag="p" extraAttributes="style='margin-left:2%'">

    <webuijsf:label id="outserverlbl" text="Outgoing Server"/>
    <webuijsf:textField id="outserverfld"
    required="true"
    validator='#{emailAccount.validate}'
    text='#{emailAccount.outServer}'/>
    <h:message id="outserverfld_msg" for="outserverfld"
    showDetail="true"/>

    </webuijsf:markup>

    </f:subview>
    </jsp:root>

    newsserver.jsp

    <jsp:root version="1.2"
    xmlns:jsp="http://java.sun.com/JSP/Page"
    xmlns:f="http://java.sun.com/jsf/core"
    xmlns:h="http://java.sun.com/jsf/html"
    xmlns:webuijsf="http://www.sun.com/webui/webuijsf">
    <jsp:directive.page contentType="text/html;charset=ISO-8859-1"
    pageEncoding="UTF-8"/>

    <f:subview id="sv_newsserver">

    <webuijsf:markup tag="p" extraAttributes="style='margin-left:2%'">

    <webuijsf:markup tag="br" singleton="true"/>

    <webuijsf:label id="outserverlbl" text="News Server"/>
    <webuijsf:textField id="outserverfld"
    required="true"
    validator='#{emailAccount.validate}'
    text='#{emailAccount.outServer}'/>
    <h:message id="outserverfld_msg" for="outserverfld"
    showDetail="true"/>

    </webuijsf:markup>

    </f:subview>
    </jsp:root>

    outgoingserver.jsp

    <jsp:root version="1.2"
    xmlns:jsp="http://java.sun.com/JSP/Page"
    xmlns:f="http://java.sun.com/jsf/core"
    xmlns:h="http://java.sun.com/jsf/html"
    xmlns:webuijsf="http://www.sun.com/webui/webuijsf">
    <jsp:directive.page contentType="text/html;charset=ISO-8859-1"
    pageEncoding="UTF-8"/>

    <f:subview id="sv_outgoingserver">

    <webuijsf:markup tag="p" extraAttributes="style='margin-left:2%'">

    <webuijsf:markup tag="br" singleton="true"/>

    <webuijsf:label id="outserverlbl" text="Outgoing Server"/>
    <webuijsf:textField id="outserverfld"
    required="true"
    validator='#{emailAccount.validate}'
    text='#{emailAccount.outServer}'/>
    <h:message id="outserverfld_msg" for="outserverfld"
    showDetail="true"/>

    </webuijsf:markup>

    </f:subview>
    </jsp:root>

    username.jsp

    <jsp:root version="1.2"
    xmlns:jsp="http://java.sun.com/JSP/Page"
    xmlns:f="http://java.sun.com/jsf/core"
    xmlns:h="http://java.sun.com/jsf/html"
    xmlns:webuijsf="http://www.sun.com/webui/webuijsf">
    <jsp:directive.page contentType="text/html;charset=ISO-8859-1"
    pageEncoding="UTF-8"/>

    <f:subview id="sv_username">

    <webuijsf:markup tag="p" extraAttributes="style='margin-left:2%'">

    <webuijsf:label id="innamelbl" text="Incoming User Name"/>
    <webuijsf:textField id="innamefld"
    required="true"
    validator='#{emailAccount.validate}'
    text='#{emailAccount.inName}'/>
    <h:message id="innamefld_msg" for="innamefld"
    showDetail="true"/>

    <webuijsf:markup tag="br" singleton="true"/>

    <webuijsf:label id="outnamelbl" text="Outgoing User Name"/>
    <webuijsf:textField id="outnamefld"
    required="true"
    validator='#{emailAccount.validate}'
    text='#{emailAccount.outName}'/>
    <h:message id="outnamefld_msg" for="outnamefld"
    showDetail="true"/>

    </webuijsf:markup>

    </f:subview>
    </jsp:root>

    verifyfinish.jsp

    <jsp:root version="1.2"
    xmlns:jsp="http://java.sun.com/JSP/Page"
    xmlns:f="http://java.sun.com/jsf/core"
    xmlns:h="http://java.sun.com/jsf/html"
    xmlns:webuijsf="http://www.sun.com/webui/webuijsf">
    <jsp:directive.page contentType="text/html;charset=ISO-8859-1"
    pageEncoding="UTF-8"/>

    <f:subview id="sv_verifyfinish">

    <webuijsf:markup tag="p" extraAttributes="style='margin-left:2%'">

    <!-- account type -->
    <webuijsf:label id="v_accttypelbl" text="Account Type:"/>
    <webuijsf:staticText id="v_accttypetxt"
    text='#{emailAccount.acctType}'/>
    <webuijsf:markup tag="br" singleton="true"/>
    <!-- account type -->

    <!-- user name -->
    <webuijsf:label id="v_usernamelbl" text="User Name:"
    rendered='#{emailAccount.acctType == "EmailAccount" || emailAccount.acctType == "MoveMail" || emailAccount.acctType == "Newsgroup"}'/>
    <webuijsf:staticText id="v_usernametxt"
    text='#{emailAccount.userName}'
    rendered='#{emailAccount.acctType == "EmailAccount" || emailAccount.acctType == "MoveMail" || emailAccount.acctType == "Newsgroup"}'/>
    <webuijsf:markup tag="br" singleton="true"
    rendered='#{emailAccount.acctType == "EmailAccount" || emailAccount.acctType == "MoveMail" || emailAccount.acctType == "Newsgroup"}'/>
    <!-- user name -->

    <!-- account name -->
    <webuijsf:label id="v_acctnamelbl" text="Account Name:"/>
    <webuijsf:staticText id="v_acctnametxt"
    text='#{emailAccount.acctName}'/>
    <webuijsf:markup tag="br" singleton="true"/>
    <!-- account name -->

    <!-- email address -->
    <webuijsf:label id="v_eaddrlbl" text="Email Address:"
    rendered='#{emailAccount.acctType == "EmailAccount" || emailAccount.acctType == "MoveMail" || emailAccount.acctType == "Newsgroup"}'/>
    <webuijsf:staticText id="v_eaddrtxt"
    text='#{emailAccount.emailAddr}'
    rendered='#{emailAccount.acctType == "EmailAccount" || emailAccount.acctType == "MoveMail" || emailAccount.acctType == "Newsgroup"}'/>
    <webuijsf:markup tag="br" singleton="true"
    rendered='#{emailAccount.acctType == "EmailAccount" || emailAccount.acctType == "MoveMail" || emailAccount.acctType == "Newsgroup"}'/>
    <!-- email address -->

    <!-- incoming user name -->
    <webuijsf:label id="v_innamelbl" text="Incoming User Name:"
    rendered='#{emailAccount.acctType == "EmailAccount"}'/>
    <webuijsf:staticText id="v_innametxt"
    text='#{emailAccount.inName}'
    rendered='#{emailAccount.acctType == "EmailAccount"}'/>
    <webuijsf:markup tag="br" singleton="true"
    rendered='#{emailAccount.acctType == "EmailAccount"}'/>
    <!-- incoming user name -->

    <!-- incoming server name -->
    <webuijsf:label id="v_insrvnamelbl" text="Incoming Server Name:"
    rendered='#{emailAccount.acctType == "EmailAccount"}'/>
    <webuijsf:staticText id="v_insrvnametxt"
    text='#{emailAccount.inServer}'
    rendered='#{emailAccount.acctType == "EmailAccount"}'/>
    <webuijsf:markup tag="br" singleton="true"
    rendered='#{emailAccount.acctType == "EmailAccount"}'/>
    <!-- incoming server name -->

    <!-- incoming server type -->
    <webuijsf:label id="v_insrvtypelbl" text="Incoming Server Type:"
    rendered='#{emailAccount.acctType == "EmailAccount" || emailAccount.acctType == "MoveMail"}'/>
    <webuijsf:staticText id="v_insrvtypetxt"
    text='#{emailAccount.serverType}'
    rendered='#{emailAccount.acctType == "EmailAccount" || emailAccount.acctType == "MoveMail"}'/>
    <webuijsf:markup tag="br" singleton="true"
    rendered='#{emailAccount.acctType == "EmailAccount" || emailAccount.acctType == "MoveMail"}'/>
    <!-- incoming server type -->

    <!-- global inbox -->
    <webuijsf:label id="v_glbinblbl" text="Pop Inbox Type:"
    rendered='#{emailAccount.acctType == "EmailAccount" &amp;&amp; emailAccount.serverType == "Pop"}'/>
    <webuijsf:staticText id="v_glbinbtxt0"
    text='Inbox in Local Folders'
    rendered='#{emailAccount.acctType == "EmailAccount" &amp;&amp; emailAccount.serverType == "Pop" &amp;&amp; emailAccount.globalInbox == "true"}'/>
    <webuijsf:staticText id="v_glbinbtxt1"
    text='Inbox in Top Level Account'
    rendered='#{emailAccount.acctType == "EmailAccount" &amp;&amp; emailAccount.serverType == "Pop" &amp;&amp; emailAccount.globalInbox == "false"}'/>
    <webuijsf:markup tag="br" singleton="true"
    rendered='#{emailAccount.acctType == "EmailAccount" &amp;&amp; emailAccount.serverType == "Pop"}'/>
    <!-- global inbox -->

    <!-- outgoing user name -->
    <webuijsf:label id="v_outnamelbl" text="Outgoing User Name:"
    rendered='#{emailAccount.acctType == "EmailAccount" || emailAccount.acctType == "MoveMail" || emailAccount.acctType == "Newsgroup"}'/>
    <webuijsf:staticText id="v_outnametxt"
    text='#{emailAccount.outName}'
    rendered='#{emailAccount.acctType == "EmailAccount" || emailAccount.acctType == "MoveMail" || emailAccount.acctType == "Newsgroup"}'/>
    <webuijsf:markup tag="br" singleton="true"
    rendered='#{emailAccount.acctType == "EmailAccount" || emailAccount.acctType == "MoveMail" || emailAccount.acctType == "Newsgroup"}'/>
    <!-- outgoing user name -->

    <!-- outgoing server name -->
    <webuijsf:label id="v_outsrvnamelbl" text="Outgoing Server Name:"
    rendered='#{emailAccount.acctType == "EmailAccount" || emailAccount.acctType == "MoveMail"}'/>
    <webuijsf:label id="v_outsrvnamelbl0" text="News Server Name:"
    rendered='#{emailAccount.acctType == "Newsgroup"}'/>
    <webuijsf:staticText id="v_outsrvnametxt"
    text='#{emailAccount.outServer}'
    rendered='#{emailAccount.acctType == "EmailAccount" || emailAccount.acctType == "MoveMail" || emailAccount.acctType == "Newsgroup"}'/>
    <!-- outgoing server name -->

    </webuijsf:markup>

    </f:subview>
    </jsp:root>

    wizardBranchSteps

    Use the webuijsf:wizardBranchSteps tag to define a sequence of steps within a branch of a wizard, which is specified with a webuijsf:wizardBranch tag. For each choice a user might make, use one webuijsf:wizardBranchSteps tag. Within a webuijsf:wizardBranchSteps tag, use one or more webuijsf:wizardStep tags. See the webuijsf:wizardBranch tag documentation for more information.

    HTML Elements and Layout

    No HTML elements are rendered for the wizardBranchSteps component. The webuijsf:wizardBranchSteps tag's function is to contain the step tags of each branch sequence, and to provide a way to conditionally render the sequence.

    Client-side JavaScript Functions

    None.

    Examples

    See the webuijsf:wizardBranch tag examples.

    wizardStep

    Use the webuijsf:wizardStep tag to define a single step of a wizard.

    In a simple wizard, the webuijsf:wizardStep tag is a child of the webuijsf:wizard tag. In a branching wizard, the webuijsf:wizardStep tag can be used as a child of the webuijsf:wizardBranchSteps tag or webuijsf:wizardSubstepBranch tag.

    HTML Elements and Layout

    The only HTML element that is rendered specifically for the WizardStep component is <webuijsf:markup tag="div" styleClass="#{themeStyles.WIZARD_TASK}">.  The WizTsk class selector is not defined by the suntheme or the defaulttheme, so the <div> uses default rendering. The <div> contains the HTML that is rendered for the child tags that are contained in the webuijsf:wizardStep tag.

    The values that are specified in the summary and help attributes are displayed in the Steps tab and Help tab. The title value is displayed in the Step Title area, and the detail value is displayed in the Step Instructions area in the Step Content pane. The input components, labels, and so on that you specify as child components in the webuijsf:wizardStep are displayed in the Step Input Controls area in the Step Content pane. See the webuijsf:wizard documentation for a detailed description of all the wizard areas.

    The following diagram shows the relative location of the wizardStep areas. The areas that are controlled with the webuijsf:wizardStep tag are highlighted in light blue. The grayed out areas are controlled with the webuijsf:wizard tag, but are shown here for context.

    Wizard Title 
    Steps Pane
    Steps Tab






    Help Tab
    Step Content Pane
    Step Title 
    Step Instructions
    Step Input Controls


    Navigation Controls                    


    Using the webuijsf:wizardStep Tag

    Use the webuijsf:wizardStep tag attributes to provide information about the step, such as the title, summary, detail, and help. These attributes are used in the wizard layout as described in the previous section.

    The finish attribute is used to indicate that the Navigation Controls area of the step should contain a Finish button that will execute the wizard task when clicked.

    The results attribute is used to indicate that the step is a View Results page, which should contain a Close button in the Navigation Controls area. A View Results page comes after the Finish page, and is used to summarize the work that the wizard has performed, and lists any actions users should take after closing the wizard.

    The webuijsf:wizardStep tag also provides attributes (onCancel, onClose, etc.) for specifying client-side JavaScript to be executed when the user clicks on the various buttons and tabs. These attributes take precedence over similar attributes in the webuijsf:wizard tag. For example, if the onNext attribute is specified in both the webuijsf:wizard and webuijsf:wizardStep tags, only the JavaScript assigned to the webuijsf:wizardStep tag's onNext attribute is applied to the rendered Next button. However, for any steps in the wizard that do not specify the onNext attribute, the webuijsf:wizard tag's onNext attribute would be used.

    The eventListener attribute is used to specify an event listener for the step, which is executed as the user leaves the step and the form is submitted. See the Event Listeners section in the wizard tag documentation for more information.

    Within the webuijsf:wizardStep tag, specify the tags for child components such as webuijsf:staticText, webuijsf:textField, webuijsf:checkbox, webuijsf:radioButton, and webuijsf:dropDown to create the content of the step.

    You can specify the content tags in a step in either of the following ways:

    • Specify the step content tags within the body of the webuijsf:wizardStep tag, as shown in the following example.

        <webuijsf:wizard ...>
          <webuijsf:wizardStep ...>
          ...
            <webuijsf:textField id="name"     ... />
            <webuijsf:textField id="address" ... />
          ...
          </webuijsf:wizardStep>
        </webuijsf:wizard>

    • Specify the step content tags within a JSF <f:subview> tag in a separate JSP file. Use the <jsp:include> standard action in the webuijsf:wizardStep tag to include the JSP that contains the step content.  In the example below, the subview tags are defined in the step1.jsp page.

        <webuijsf:wizard ...>
          <webuijsf:wizardStep ...>
            <jsp:include page="steps/step1.jsp" />
          </webuijsf:wizardStep>
        </webuijsf:wizard>

    The <f:subview> tag in step1.jsp contains:

      <f:subview id=sv_step1>
         
    ...
         
    <webuijsf:textField id="name" ... />
         
    <webuijsf:textField id="address" ... />
          ...
      /f:subview>

    Wizard Steps in a Branch

    A wizard uses a branch when the sequence of steps is determined by the user's input. For example, the wizard can allow a user to choose one of two options, and that choice causes the wizard to proceed through one sequence of steps. If the user chooses the other option, the wizard proceeds through a different sequence.

    Note that you might be able to avoid branching, and simplify the wizard, if you can structure your application so that the user's choice is made before launching the wizard. You can use the user's choice to launch a different wizard to present each sequence of steps, which would require only the webuijsf:wizard and webuijsf:wizardStep tags.

    See the webuijsf:wizardBranchSteps documentation and webuijsf:wizardSubstepBranch documentation for more information about how to implement branching. The webuijsf:wizardStep tag can be used a child of these branching tags, to create the steps in the branching sequence.

    Client-side JavaScript Functions

    None.

    Examples

    See the webuijsf:wizard tag example for a simple wizard. See the webuijsf:wizardBranch tag example for a more complex wizard that uses branching.

    wizardSubstepBranch

    Use the webuijsf:wizardSubstepBranch tag to define a substep branch within a step sequence of a webuijsf:wizard tag. A substep branch is a series of steps that are subordinate to a major step, and always followed by the next major step in the step sequence. A substep branch may or may not be taken.

    A webuijsf:wizardSubstepBranch tag should be used when a step branches to related substeps before returning to the major step sequence. If the branched steps diverge and never return to a common step in the main step sequence, you should use the webuijsf:wizardBranch tag instead. See the webuijsf:wizardBranch documentation. Also see the Sun Web Application Guidelines 3.0 for more information about deciding which type of branching to use.

    A webuijsf:wizardSubstepBranch tag must be used as a child of a webuijsf:wizard tag or a webuijsf:wizardBranchSteps tag. The steps within the substep branch sequence are defined by webuijsf:wizardStep tags within the body of the webuijsf:wizardSubstepBranch tag.

    If the taken attribute is false, the webuijsf:wizardStep children are not presented to the user. Typically substep branches are not shown in the step list unless it is determined that the substeps are to be displayed.

    HTML Elements and Layout

    No HTML elements are rendered for the wizardSubstepBranch component. The content that is displayed for the substeps is specified in webuijsf:wizardStep tags.

    Substeps are initially hidden in the Steps pane of the wizard. The substeps are displayed in the Steps pane only when the application determines that the wizardSubstepBranch should be followed. Typically the user's response to the preceding step would be used to determine whether the branch should be followed. When the substeps are displayed in the Steps pane, they are indented under the associated major step, and numbered as subordinate to that step, such as 4.1, 4.2, 4.3 under a major step number 4. In the content pane, the wizardStep child components for both major steps and substeps are displayed.

    Using the webuijsf:wizardSubstepBranch tag

    The value of the webuijsf:wizardSubstepBranch tag's taken attribute determines whether the substep branch is followed. When taken is set to true, the branch is followed. If taken is false, the branch is not followed. The value of the taken attribute could be set to an expression that uses the user's response in a preceding step, to determine whether the branch should be followed.

    The following pseudocode shows the relationship of the wizard components when using the webuijsf:wizardSubstepBranch:

    <webuijsf:wizard>
        ... (initial steps where no branching is needed)

        <webuijsf:wizardStep>
                 The user's choice in this wizardStep should be used to
                 determine whether the substep branch is followed.  Note that the
                 wizardSubstepBranch is NOT a child of the wizardStep component.

        </webuijsf:wizardStep>
       
        <webuijsf:wizardSubstepBranch>
                 The wizard framework uses the wizardSubstepBranch's taken attribute value
                 to decide whether to process the branch.

           
    <webuijsf:wizardStep>
                 These steps are the substeps that are rendered only when the wizardSubstepBranch
                 is taken.

            </webuijsf:wizardStep>
     
            <webuijsf:wizardStep>... </webuijsf:wizardStep>

            <webuijsf:wizardStep>... </webuijsf:wizardStep>

            

        </webuijsf:wizardSubstepBranch>

        <webuijsf:wizardStep>
                 This step represents the major step that is always followed after the
                 substep branch.  

        </webuijsf:wizardStep>

    </webuijsf:wizard>

    Client-side JavaScript Functions

    None.

    Examples

    Example 1: Substep Branching Wizard

    This emailaccount-substep.jsp example shows a complete JSP page that uses webuijsf:wizardSubstepBranch. The wizard uses the emailAccount backing bean shown in the webuijsf:wizard tag documentation.

    emailaccount-substep.jsp

    <jsp:root version="1.2"
    xmlns:jsp="http://java.sun.com/JSP/Page"
    xmlns:f="http://java.sun.com/jsf/core"
    xmlns:h="http://java.sun.com/jsf/html"
    xmlns:webuijsf="http://www.sun.com/webui/webuijsf">
    <jsp:directive.page contentType="text/html;charset=UTF-8"
    pageEncoding="UTF-8"/>
    <f:view>
    <webuijsf:page>
    <webuijsf:html>
    <webuijsf:head title="Wizard Substeps Example" />
    <webuijsf:body
    onLoad="document.getElementById('form1:wizard1').wizOnLoad()">
    <webuijsf:form id="form1">

    <webuijsf:wizard id="wizard1" title="Create Account">

    <webuijsf:wizardStep id="step1"
    summary="Choose Account Type"
    title="New Account Setup"
    detail="Select the type of account you would like to set up:"
    help="In order to receive messages, you first need to set up a Mail or
    Newsgroup account. This Wizard will collect the information necessary
    to set up a Mail or Newsgroup account. If you do not know the information
    requested, please contact your System Administrator or Internet Service Provider.">

    <webuijsf:markup tag="p" extraAttributes="style='margin-left:2%'">

    <webuijsf:radioButton id="email" name="account"
    label="Email account"
    selectedValue="EmailAccount"
    selected="#{emailAccount.acctType}"/>

    <webuijsf:markup tag="br" singleton="true"/>

    <webuijsf:radioButton id="movemail" name="account"
    label="Movemail"
    selectedValue="MoveMail"
    selected="#{emailAccount.acctType}"/>

    <webuijsf:markup tag="br" singleton="true"/>

    <webuijsf:radioButton id="rss" name="account"
    label="RSS News and Blogs"
    selectedValue="RSSNewsAndBlogs"
    selected="#{emailAccount.acctType}"/>

    <webuijsf:markup tag="br" singleton="true"/>

    <webuijsf:radioButton id="news" name="account"
    label="Newsgroup account"
    selectedValue="Newsgroup"
    selected="#{emailAccount.acctType}"/>

    </webuijsf:markup>

    </webuijsf:wizardStep>

    <webuijsf:wizardStep id="step2"
    summary="Specify Email Identity"
    title="Identity"
    detail="Enter outgoing email name and email address."
    help="Each account has an identity, which is the information that
    identifies you to others when they receive your messages. Enter the
    name you would like to appear in the From field of your outgoing messages,
    for example, John Smith. Then enter your email address. This is the address
    others will use to send email to you, for example john.smith@sun.com.">

    <webuijsf:markup tag="p" extraAttributes="style='margin-left:2%'">

    <webuijsf:label id="namelbl" text="Your Name"/>
    <webuijsf:textField id="namefld"
    required="true"
    validator='#{emailAccount.validate}'
    text='#{emailAccount.userName}'/>


    <webuijsf:markup tag="br" singleton="true"/>

    <webuijsf:label id="eaddrlbl" text="Email Address"/>
    <webuijsf:textField id="eaddrfld"
    required="true"
    validator='#{emailAccount.validate}'
    text='#{emailAccount.emailAddr}'/>


    </webuijsf:markup>

    </webuijsf:wizardStep>

    <webuijsf:wizardStep id="step3"
    summary="Specify Email Server"
    title="Email Server Information"
    detail="Select the type of incoming server and server name."
    help="&lt;p&gt;Select the type of the incoming server you are using. Then enter the name
    of your incoming server, for example, mail.sun.com.&lt;/p&gt;&lt;p&gt;Then enter the
    outgoing (SMTP) server name, for example, smtp.sun.com&lt;/p&gt;">

    <webuijsf:markup tag="p" extraAttributes="style='margin-left:2%'">

    <webuijsf:radioButton id="pop" name="mailservertype"
    label="POP"
    selectedValue="Pop"
    selected="#{emailAccount.serverType}"/>

    <webuijsf:markup tag="br" singleton="true"/>

    <webuijsf:radioButton id="imap" name="mailservertype"
    label="IMAP"
    selectedValue="Imap"
    selected="#{emailAccount.serverType}"/>

    <webuijsf:markup tag="br" singleton="true"/>

    <webuijsf:label id="inserverlbl" text="Incoming Server"/>
    <webuijsf:textField id="inserverfld"
    required="true"
    validator='#{emailAccount.validate}'
    text='#{emailAccount.inServer}'/>


    <webuijsf:markup tag="br" singleton="true"/>

    <webuijsf:label id="outserverlbl" text="Outgoing Server"/>
    <webuijsf:textField id="outserverfld"
    required="true"
    validator='#{emailAccount.validate}'
    text='#{emailAccount.outServer}'/>


    </webuijsf:markup>

    </webuijsf:wizardStep>


    <webuijsf:wizardSubstepBranch id="POPsubstep"
    taken='#{emailAccount.serverType == "Pop"}'>

    <webuijsf:wizardStep id="step3_1"
    summary="Choose Inbox Account Type"
    title="Choose Inbox Account Type"
    detail="Choose Between Top Level Account or Local Folders Inbox Account"
    help="Uncheck this checkbox to store email for this account in its own directory.
    That will make this account appear as a top-level account. Otherwise, it
    will be part of the Local Folders Global Inbox account.">

    <webuijsf:markup tag="p" extraAttributes="style='margin-left:2%'">

    <webuijsf:checkbox id="inbox" name="inboxtype"
    label="Use Global Inbox (store mail in Local Folders)"
    selected="#{emailAccount.globalInbox}"/>

    </webuijsf:markup>

    </webuijsf:wizardStep>

    </webuijsf:wizardSubstepBranch>

    <webuijsf:wizardStep id="step4"
    summary="Specify User Name"
    title="User Names"
    detail="Enter email provider assigned user name."
    help="Enter your existing outgoing and incoming (SMTP) username,
    for example jsmith. You can modify outgoing server settings by
    choosing Account Settings from the Tools menu.">

    <webuijsf:markup tag="p" extraAttributes="style='margin-left:2%'">

    <webuijsf:label id="innamelbl" text="Incoming User Name"/>
    <webuijsf:textField id="innamefld"
    required="true"
    validator='#{emailAccount.validate}'
    text='#{emailAccount.inName}'/>


    <webuijsf:markup tag="br" singleton="true"/>

    <webuijsf:label id="outnamelbl" text="Outgoing User Name"/>
    <webuijsf:textField id="outnamefld"
    required="true"
    validator='#{emailAccount.validate}'
    text='#{emailAccount.outName}'/>


    </webuijsf:markup>

    </webuijsf:wizardStep>

    <webuijsf:wizardStep id="step5"
    summary="Specify Account Name"
    title="Account Name"
    detail="The name of the account."
    help="Enter the name by which you would like to refer to this account,
    for example Work Account, Home Account, or News Account, etc.">

    <webuijsf:markup tag="p" extraAttributes="style='margin-left:2%'">

    <webuijsf:label id="acctnamelbl" text="Account Name"/>
    <webuijsf:textField id="acctnamefld"
    required="true"
    validator='#{emailAccount.validate}'
    text='#{emailAccount.acctName}'/>

    </webuijsf:markup>

    </webuijsf:wizardStep>

    <webuijsf:wizardStep id="step6"
    finish="true"
    summary="Verify Information"
    title="Verify Account Information"
    detail="Verify the information below is correct."
    help="Click finish to create the account and previous if corrections are required."
    onFinish="alert('WizardStep onFinish')">

    <webuijsf:markup tag="p" extraAttributes="style='margin-left:2%'">

    <webuijsf:label id="v_accttypelbl" text="Accout Type:"/>
    <webuijsf:staticText id="v_accttypetxt"
    text='#{emailAccount.acctType}'/>

    <webuijsf:markup tag="br" singleton="true"/>

    <webuijsf:label id="v_usernamelbl" text="User Name:"/>
    <webuijsf:staticText id="v_usernametxt"
    text='#{emailAccount.userName}'/>

    <webuijsf:markup tag="br" singleton="true"/>

    <webuijsf:label id="v_acctnamelbl" text="Account Name:"/>
    <webuijsf:staticText id="v_acctnametxt"
    text='#{emailAccount.acctName}'/>

    <webuijsf:markup tag="br" singleton="true"/>

    <webuijsf:label id="v_eaddrlbl" text="Email Address:"/>
    <webuijsf:staticText id="v_eaddrtxt"
    text='#{emailAccount.emailAddr}'/>

    <webuijsf:markup tag="br" singleton="true"/>

    <webuijsf:label id="v_innamelbl" text="Incoming User Name:"/>
    <webuijsf:staticText id="v_innametxt"
    text='#{emailAccount.inName}'/>

    <webuijsf:markup tag="br" singleton="true"/>

    <webuijsf:label id="v_insrvnamelbl" text="Incoming Server Name:"/>
    <webuijsf:staticText id="v_insrvnametxt"
    text='#{emailAccount.inServer}'/>

    <webuijsf:markup tag="br" singleton="true"/>

    <webuijsf:label id="v_insrvtypelbl" text="Incoming Server Type:"/>
    <webuijsf:staticText id="v_insrvtypetxt"
    text='#{emailAccount.serverType}'/>

    <webuijsf:markup tag="br" singleton="true"/>

    <webuijsf:label id="v_outnamelbl" text="Outgoing User Name:"/>
    <webuijsf:staticText id="v_outnametxt"
    text='#{emailAccount.outName}'/>

    <webuijsf:markup tag="br" singleton="true"/>

    <webuijsf:label id="v_outsrvnamelbl" text="Outgoing Server Name:"/>
    <webuijsf:staticText id="v_outsrvnametxt"
    text='#{emailAccount.outServer}'/>

    </webuijsf:markup>

    </webuijsf:wizardStep>

    </webuijsf:wizard>

    </webuijsf:form>
    </webuijsf:body>
    </webuijsf:html>
    </webuijsf:page>
    </f:view>
    </jsp:root>
     


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