com.sun.rave.web.ui.component
Class AddRemoveBase

java.lang.Object
  javax.faces.component.UIComponent
      javax.faces.component.UIComponentBase
          javax.faces.component.UIOutput
              javax.faces.component.UIInput
                  com.sun.rave.web.ui.component.SelectorBase
                      com.sun.rave.web.ui.component.Selector
                          com.sun.rave.web.ui.component.ListSelectorBase
                              com.sun.rave.web.ui.component.ListSelector
                                  com.sun.rave.web.ui.component.AddRemoveBase

All Implemented Interfaces:

ComplexComponent, javax.faces.component.EditableValueHolder, ListManager, SelectorManager, javax.faces.component.StateHolder, javax.faces.component.ValueHolder

Direct Known Subclasses:

AddRemove

public abstract class AddRemoveBase

extends ListSelector

About this tag

This tag renders two listboxes (one for available options, one for selected options) together with buttons to move the options between the lists, and optionally to order the selected options. Use the items attribute to associate the component with an array, collection or map of com.sun.rave.web.ui.model.Option and 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.rave.web.ui.model.Options.

Component layout and Facet structure

The component can be laid out using either horizonal layout (the default) or vertical layout (if the vertical attribute is set to true). In the diagrams below, facet child components are shown as light blue. Non-facet areas are violet.

Horizontal layout

In horizontal layout, the component label (or header) may be shown either above the component (if the labelOnTopattribute is true) or next to the component as shown in the diagram.

header

availableLabel
List of available items

addButton

addAllButton

removeButton

removeAllButton

moveUpButton

moveDownButton

selectedLabel
List of selected items

footer

Vertical layout

header

availableLabel
List of available items

addButton addAllButton removeButton removeAllButton

selectedLabel
List of selected items

moveUpButton moveDownButton

footer

Facets

• addButton: Use this facet to replace the standard "Add" button. If you use a facet to replace this component, the JSF ID of this component should be the ID given to the AddRemove component with _addButton appended at the end. If you wish to use the JavaScript function associated with the default button, use the add() function. See the section on JavaScript for details.
• removeButton: Use this facet to replace the standard "Remove" button. If you use a facet to replace this component, the JSF ID of this component should be the ID given to the AddRemove component with _removeButton appended at the end. If you wish to use the JavaScript function associated with the default button, use the remove() function. See the section on JavaScript for details.
• addAllButton: Use this facet to replace the standard "Add All" button. If you use a facet to replace this component, the JSF ID of this component should be the ID given to the AddRemove component with _addAllButton appended at the end. If you wish to use the JavaScript function associated with the default button, use the addAll() function. See the section on JavaScript for details.
• removeAllButton: Use this facet to replace the standard "Remove All" button. If you use a facet to replace this component, the JSF ID of this component should be the ID given to the AddRemove component with _removeAllButton appended at the end. If you wish to use the JavaScript function associated with the default button, use the removeAll() function. See the section on JavaScript for details.
• moveUpButton: Use this facet to replace the standard "Move Up" button. If you use a facet to replace this component, the JSF ID of this component should be the ID given to the AddRemove component with _moveUpButton appended at the end. If you wish to use the JavaScript function associated with the default button, use the moveUp() function. See the section on JavaScript for details.
• moveDownButton: Use this facet to replace the standard "Move Down" button. If you use a facet to replace this component, the JSF ID of this component should be the ID given to the AddRemove component with _moveDownButton appended at the end. If you wish to use the JavaScript function associated with the default button, use the moveDown() function. See the section on JavaScript for details.
• header: Use this facet to create a header for the component. The facet will replace the component label.
• footer: Use this facet to create a footer for the component.

Client-side JavaScript functions

When the component is rendered, a JavaScript object corresponding to the component is created. The name of the variable is AddRemove_ followed by the component's DOM id where the colons have been replaced by underscores. For example, if the id of the component is listform:addremove then the JavaScript variable name will be AddRemove_listform_addremove. To manipulate the component on the client side, you may invoke functions on the JavaScript object. With reference to the id above, to add all elements on the available list that the user has selected, invoke AddRemove_listform_addremove.add().

• 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.

Configuring the AddRemove tag

Examples

The component gets the 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.

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

As in 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.

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

Auto-generated component class. Do NOT modify; all changes will be lost!

Field Summary

Fields inherited from class com.sun.rave.web.ui.component.ListSelector

LIST_ID, listItems, VALUE_ID

Fields inherited from class com.sun.rave.web.ui.component.Selector

valueTypeEvaluator

Fields inherited from class javax.faces.component.UIInput

COMPONENT_FAMILY, COMPONENT_TYPE, CONVERSION_MESSAGE_ID, REQUIRED_MESSAGE_ID

Constructor Summary

AddRemoveBase()
Construct a new AddRemoveBase.

Method Summary

java.lang.String	getAvailableItemsLabel() The label for the available list
java.lang.String	getFamily() Return the family for this component.
java.lang.String	getSelectedItemsLabel() The label for the selected list
java.lang.String	getToolTip() Display the text as a tooltip for this component
boolean	isDuplicateSelections() Set this attribute to true if the component should allow items from the available list to be added more than one to the selected list, that is, if the selected list should allow duplicate entries.
boolean	isMoveButtons() Show the Move Up and Move Down buttons
boolean	isSelectAll() Show the Add All and Remove All buttons
boolean	isSorted() If true, the items on the available options list are shown in alphabetical order.
boolean	isVertical() Use vertical layout instead of the default horizontal one
void	restoreState(javax.faces.context.FacesContext _context, java.lang.Object _state) Restore the state of this component.
java.lang.Object	saveState(javax.faces.context.FacesContext _context) Save the state of this component.
void	setAvailableItemsLabel(java.lang.String availableItemsLabel) The label for the available list
void	setDuplicateSelections(boolean duplicateSelections) Set this attribute to true if the component should allow items from the available list to be added more than one to the selected list, that is, if the selected list should allow duplicate entries.
void	setMoveButtons(boolean moveButtons) Show the Move Up and Move Down buttons
void	setSelectAll(boolean selectAll) Show the Add All and Remove All buttons
void	setSelectedItemsLabel(java.lang.String selectedItemsLabel) The label for the selected list
void	setSorted(boolean sorted) If true, the items on the available options list are shown in alphabetical order.
void	setToolTip(java.lang.String toolTip) Display the text as a tooltip for this component
void	setVertical(boolean vertical) Use vertical layout instead of the default horizontal one

Methods inherited from class com.sun.rave.web.ui.component.ListSelector

checkSelectionModel, createListItem, getLabelComponent, getListItems, getListItems, getOptions, getPrimaryElementID, getReadOnlyValueComponent, getSeparatorLength, getValueAsReadOnly, getValueAsStringArray, mainListSubmits, markSelectedListItems, processOptions, processSelections

Methods inherited from class com.sun.rave.web.ui.component.ListSelectorBase

getRows, isLabelOnTop, isSeparators, isVisible, setLabelOnTop, setRows, setSeparators, setVisible

Methods inherited from class com.sun.rave.web.ui.component.Selector

compareValues, getConvertedValue, getLabelLevel, getRendersChildren, getValueAsReadOnly, isMultiple, setMultiple, setSelected, toString

Methods inherited from class com.sun.rave.web.ui.component.SelectorBase

getItems, getLabel, getOnBlur, getOnChange, getOnClick, getOnDblClick, getOnFocus, getOnKeyDown, getOnKeyPress, getOnKeyUp, getOnMouseDown, getOnMouseMove, getOnMouseOut, getOnMouseOver, getOnMouseUp, getOnSelect, getSelected, getStyle, getStyleClass, getTabIndex, getValueBinding, isDisabled, isReadOnly, setDisabled, setItems, setLabel, setLabelLevel, setOnBlur, setOnChange, setOnClick, setOnDblClick, setOnFocus, setOnKeyDown, setOnKeyPress, setOnKeyUp, setOnMouseDown, setOnMouseMove, setOnMouseOut, setOnMouseOver, setOnMouseUp, setOnSelect, setReadOnly, setStyle, setStyleClass, setTabIndex, setValueBinding

Methods inherited from class javax.faces.component.UIInput

addValidator, addValueChangeListener, broadcast, decode, getSubmittedValue, getValidator, getValidators, getValueChangeListener, getValueChangeListeners, isImmediate, isLocalValueSet, isRequired, isValid, processDecodes, processUpdates, processValidators, removeValidator, removeValueChangeListener, setImmediate, setLocalValueSet, setRequired, setSubmittedValue, setValid, setValidator, setValue, setValueChangeListener, updateModel, validate, validateValue

Methods inherited from class javax.faces.component.UIOutput

getConverter, getLocalValue, getValue, setConverter

Methods inherited from class javax.faces.component.UIComponentBase

addFacesListener, encodeBegin, encodeChildren, encodeEnd, findComponent, getAttributes, getChildCount, getChildren, getClientId, getFacesContext, getFacesListeners, getFacet, getFacets, getFacetsAndChildren, getId, getParent, getRenderer, getRendererType, isRendered, isTransient, processRestoreState, processSaveState, queueEvent, removeFacesListener, restoreAttachedState, saveAttachedState, setId, setParent, setRendered, setRendererType, setTransient

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.sun.rave.web.ui.component.ListManager

getRows, isVisible

Methods inherited from interface javax.faces.component.EditableValueHolder

addValidator, addValueChangeListener, getSubmittedValue, getValidator, getValidators, getValueChangeListener, getValueChangeListeners, isImmediate, isLocalValueSet, isRequired, isValid, removeValidator, removeValueChangeListener, setImmediate, setLocalValueSet, setRequired, setSubmittedValue, setValid, setValidator, setValueChangeListener

Methods inherited from interface javax.faces.component.ValueHolder

getConverter, getLocalValue, getValue, setConverter, setValue

Methods inherited from interface com.sun.rave.web.ui.component.SelectorManager

getClientId, getOnChange, getStyle, getStyleClass, getTabIndex, isDisabled, isMultiple, isReadOnly

Constructor Detail

AddRemoveBase

public AddRemoveBase()

Construct a new AddRemoveBase.

Method Detail

getFamily

public java.lang.String getFamily()

Return the family for this component.

Overrides:

getFamily in class ListSelectorBase

getAvailableItemsLabel

public java.lang.String getAvailableItemsLabel()

The label for the available list

setAvailableItemsLabel

public void setAvailableItemsLabel(java.lang.String availableItemsLabel)

The label for the available list

See Also:

getAvailableItemsLabel()

isDuplicateSelections

public boolean isDuplicateSelections()

Set this attribute to true if the component should allow items from the available list to be added more than one to the selected list, that is, if the selected list should allow duplicate entries.

setDuplicateSelections

public void setDuplicateSelections(boolean duplicateSelections)

Set this attribute to true if the component should allow items from the available list to be added more than one to the selected list, that is, if the selected list should allow duplicate entries.

See Also:

isDuplicateSelections()

isMoveButtons

public boolean isMoveButtons()

Show the Move Up and Move Down buttons

setMoveButtons

public void setMoveButtons(boolean moveButtons)

Show the Move Up and Move Down buttons

See Also:

isMoveButtons()

isSelectAll

public boolean isSelectAll()

Show the Add All and Remove All buttons

setSelectAll

public void setSelectAll(boolean selectAll)

Show the Add All and Remove All buttons

See Also:

isSelectAll()

getSelectedItemsLabel

public java.lang.String getSelectedItemsLabel()

The label for the selected list

setSelectedItemsLabel

public void setSelectedItemsLabel(java.lang.String selectedItemsLabel)

The label for the selected list

See Also:

getSelectedItemsLabel()

isSorted

public boolean isSorted()

If true, the items on the available options list are shown in alphabetical order. The item 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.

setSorted

public void setSorted(boolean sorted)

If true, the items on the available options list are shown in alphabetical order. The item 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.

See Also:

isSorted()

getToolTip

public java.lang.String getToolTip()

Display the text as a tooltip for this component

Specified by:

getToolTip in interface ListManager

Overrides:

getToolTip in class SelectorBase

setToolTip

public void setToolTip(java.lang.String toolTip)

Display the text as a tooltip for this component

Overrides:

setToolTip in class SelectorBase

See Also:

getToolTip()

isVertical

public boolean isVertical()

Use vertical layout instead of the default horizontal one

setVertical

public void setVertical(boolean vertical)

Use vertical layout instead of the default horizontal one

See Also:

isVertical()

restoreState

public void restoreState(javax.faces.context.FacesContext _context,
                         java.lang.Object _state)

Restore the state of this component.

Specified by:

restoreState in interface javax.faces.component.StateHolder

Overrides:

restoreState in class ListSelectorBase

saveState

public java.lang.Object saveState(javax.faces.context.FacesContext _context)

Save the state of this component.

Specified by:

saveState in interface javax.faces.component.StateHolder

Overrides:

saveState in class ListSelectorBase