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


Tag Information
Tag Classcom.sun.webui.jsf.component.EditableListTag
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. The list attribute must be an EL expression that evaluates to an object of typejava.lang.String[].

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.

maxLengthfalsefalsejava.lang.String

The maximum number of characters allowed for each string in the list.

rowsfalsefalsejava.lang.String

The number of items to display, which determines the length of the rendered listbox. The default value is 6.

multiplefalsefalsejava.lang.String

Flag indicating that the application user can select more than one option at a time in the listbox.

listValidatorExpressionfalsefalsejava.lang.String

A validator which will be applied to the contents of the list (e.g. to verify that the list has a minimum number of entries). Specify this to be the validate() method of a javax.faces.validator.Validator, or to another method with the same argument structure and exceptions.

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.

sortedfalsefalsejava.lang.String

Set sorted to true if the list items should be sorted in locale-specific alphabetical order. The sorting is performed using a Collator configured with the locale from the FacesContext.

fieldValidatorExpressionfalsefalsejava.lang.String

A validator that will be applied to entries made into the textfield. Specify this to be the validate() method of a javax.faces.validator.Validator, or to another method with the same argument structure and exceptions.

styleClassfalsefalsejava.lang.String

CSS style class(es) no parents, see Accordion example to be applied to the outermost HTML element when this component is rendered.

fieldLabelfalsefalsejava.lang.String

Text to be used as the label next to the input text field.

listLabelfalsefalsejava.lang.String

Text to be used as the label next to the list box.

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

listOnTopfalsefalsejava.lang.String

Specifies the display order of the parts of this component. When set to true, the listOnTop attribute causes the list box to be displayed above the text input field. By default, the list box is displayed below the input field.

stylefalsefalsejava.lang.String

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

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

requiredfalsefalsejava.lang.String Flag indicating that an input value for this field is mandatory, and failure to provide one will trigger a validation error.
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.