webuijsf
Tag 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:

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>
 


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

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

The object that represents the list of items. The attribute's value must be a JavaServer Faces EL expression that evaluates to an array of Objects or to a java.util.List.

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 rows to display, which determines the length of the rendered listbox. The default value is 6.

labelOnTopfalsefalsejava.lang.String

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

multiplefalsefalsejava.lang.String

Flag indicating that the application user can make select more than one option from the listbox.

disabledfalsefalsejava.lang.String

Flag indicating that activation of this component by the user is not currently permitted.

styleClassfalsefalsejava.lang.String

CSS style class(es) to be applied to the outermost HTML element when this component is rendered.

labelfalsefalsejava.lang.String

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

moveTopBottomfalsefalsejava.lang.String

If this attribute is true, the Move to Top and Move to Bottom buttons are shown. The default is false.

stylefalsefalsejava.lang.String

CSS style(s) to be applied to the outermost HTML element when this component is rendered.

visiblefalsefalsejava.lang.String

Use the visible attribute to indicate whether the component should be viewable by the user in the rendered HTML page. If set to false, the HTML code for the component is present in the page, but the component is hidden with style attributes. By default, 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.

labelLevelfalsefalsejava.lang.String

Sets the style level for the generated labels. Valid values are 1 (largest), 2 and 3 (smallest). The default value is 2.

readOnlyfalsefalsejava.lang.String

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

tabIndexfalsefalsejava.lang.String

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

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.
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.
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.
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.
idfalsetruejava.lang.StringNo Description

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.