webuijsf
Tag 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);
     }
  }
  


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

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

The label for the list of selected items.

verticalfalsefalsejava.lang.String

Uses the vertical layout instead of the default horizontal layout. The vertical layout displays the available items list above the selected items list.

selectAllfalsefalsejava.lang.String

Show the Add All and Remove All buttons.

duplicateSelectionsfalsefalsejava.lang.String

If true, items in the available list are not removed when they are added to the selected list. The user is permitted to add an available item more than once to the list of selected items. The list of selected items would then contain duplicate entries.

moveButtonsfalsefalsejava.lang.String

Shows the Move Up and Move Down buttons.

availableItemsLabelfalsefalsejava.lang.String

The label for the list of available items.

sortedfalsefalsejava.lang.String

If true, the items on the available list are shown in alphabetical order. The items on the selected options list are also shown in alphabetical order, unless the moveButtons attribute is true, in which case the user is expected to order the elements.

toolTipfalsefalsejava.lang.String

Sets the value of the title attribute for the HTML element. The specified text will display as a tooltip if the mouse cursor hovers over the HTML element.

rowsfalsefalsejava.lang.String The number of items to display, Integer.MIN_VALUE is returned if no value has been set, or there is no value binding. Subclasses should provide a reasonable default.
converterfalsefalsejava.lang.String Specifies a method to translate native property values to String and back for this component. The converter attribute value must be one of the following:
  • A JavaServer Faces EL expression that resolves to a backing bean or bean property that implements the javax.faces.converter.Converter interface; or
  • the ID of a registered converter (a String).
requiredfalsefalsejava.lang.String Flag indicating that an input value for this field is mandatory, and failure to provide one will trigger a validation error.
labelOnTopfalsefalsejava.lang.String

If true, the label is rendered above the component. If false, the label is rendered next to the component. The default is false.

disabledfalsefalsejava.lang.String

Flag indicating that the user is not permitted to activate this component, and that the component's value will not be submitted with the form.

validatorExpressionfalsefalsejava.lang.String Used to specify a method in a backing bean to validate input to the component. The value must be a JavaServer Faces EL expression that resolves to a public method with return type void. The method must take three parameters:
  • a javax.faces.context.FacesContext
  • a javax.faces.component.UIComponent (the component whose data is to be validated)
  • a java.lang.Object containing the data to be validated.

The backing bean where the method is defined must implement java.io.Serializable or javax.faces.component.StateHolder.

The method is invoked during the Process Validations Phase.

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

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

selectedfalsefalsejava.lang.String

The object that represents the selections made from the available options. If multiple selections are allowed, this must be bound to an Object array, or an array of primitives.

immediatefalsefalsejava.lang.String Flag indicating that event handling for this component should be handled immediately (in Apply Request Values phase) rather than waiting until Invoke Application phase.
itemsfalsefalsejava.lang.String

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

labelfalsefalsejava.lang.String

If set, a label is rendered adjacent to the component with the value of this attribute as the label text.

visiblefalsefalsejava.lang.String

Indicates whether the component should be viewable by the user in the rendered HTML page. If set to false, the HTML code for the component is present in the page, but the component is hidden with style attributes. By default, visible is set to true, so HTML for the component HTML is included and visible to the user. If the component is not visible, it can still be processed on subsequent form submissions because the HTML is present.

stylefalsefalsejava.lang.String

CSS style or styles that are applied to the outermost HTML element when the component is rendered.

readOnlyfalsefalsejava.lang.String

If true, the value of the component is rendered as text, preceded by the label if one was defined.

@deprecated The attribute is deprected starting from version 4.1
valueChangeListenerExpressionfalsefalsejava.lang.String Specifies a method to handle a value-change event that is triggered when the user enters data in the input component. The attribute value must be a JavaServer Faces EL expression that resolves to a backing bean method. The method must take a single parameter of type javax.faces.event.ValueChangeEvent, and its return type must be void. The backing bean where the method is defined must implement java.io.Serializable or javax.faces.component.StateHolder.
tabIndexfalsefalsejava.lang.String

Describes the position of this element in the tabbing order of the current document. Tabbing order determines the sequence in which elements receive focus when the tab key is pressed. The value must be an integer between 0 and 32767.


Variables
No Variables Defined.


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