| |||||||
FRAMES NO FRAMES |
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.
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.
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.
addButton
addAllButton
removeButton
removeAllButton
moveUpButton
moveDownButton
|
webuijsf:addRemove
TagUse 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.
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 addAllButton facet 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 removeAllButton facet
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 moveUpButton facet
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. |
None.
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. |
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"/>
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"/>
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>
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 Class | com.sun.webui.jsf.component.AddRemoveTag |
TagExtraInfo Class | None |
Body Content | JSP |
Display Name | None |
Attributes | ||||
Name | Required | Request-time | Type | Description |
binding | false | false | java.lang.String | A ValueExpression that resolves to the UIComponent that corresponds to this tag. This binding allows the Java bean that contains the UIComponent to manipulate the UIComponent, its properties, and its children. |
availableItemsLabel | false | false | java.lang.String | The label for the list of available items. |
selectedItemsLabel | false | false | java.lang.String | The label for the list of selected items. |
sorted | false | false | java.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. |
duplicateSelections | false | false | java.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. |
selectAll | false | false | java.lang.String | Show the Add All and Remove All buttons. |
vertical | false | false | java.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. |
moveButtons | false | false | java.lang.String | Shows the Move Up and Move Down buttons. |
toolTip | false | false | java.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. |
rows | false | false | java.lang.String | The number of items to display. The default value is 12. |
converter | false | false | java.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:
|
required | false | false | java.lang.String | Flag indicating that an input value for this field is mandatory, and failure to provide one will trigger a validation error. |
labelOnTop | false | false | java.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. |
disabled | false | false | java.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. |
validatorExpression | false | false | java.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:
The backing bean where the method is defined must implement
The method is invoked during the Process Validations Phase. |
rendered | false | false | java.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. |
id | false | true | java.lang.String | No Description |
styleClass | false | false | java.lang.String | CSS style class or classes to be applied to the outermost HTML element when this component is rendered. |
selected | false | false | java.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. |
immediate | false | false | java.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. |
items | false | false | java.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 of |
label | false | false | java.lang.String | If set, a label is rendered adjacent to the component with the value of this attribute as the label text. |
visible | false | false | java.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. |
style | false | false | java.lang.String | CSS style or styles that are applied to the outermost HTML element when the component is rendered. |
readOnly | false | false | java.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 |
valueChangeListenerExpression | false | false | java.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 .
|
tabIndex | false | false | java.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. |
| |||||||
FRAMES NO FRAMES |