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

java.lang.Object
  extended by javax.faces.component.UIComponent
      extended by javax.faces.component.UIComponentBase
          extended by javax.faces.component.UIOutput
              extended by javax.faces.component.UIInput
                  extended by com.sun.rave.web.ui.component.EditableListBase
                      extended by com.sun.rave.web.ui.component.EditableList
All Implemented Interfaces:
ComplexComponent, ListManager, SelectorManager, javax.faces.component.EditableValueHolder, javax.faces.component.StateHolder, javax.faces.component.ValueHolder

public class EditableList
extends EditableListBase
implements ListManager

About this tag.

This tag renders an EditableList component. Use this component when web application users need to create and modify a list of strings. The application user can add new strings by typing them into the textfield and clicking the "Add" button, and remove them by selecting one or more items from the list and clicking the "Remove" button.

Configuring the listbox tag

Use the list attribute to bind the component to a model. The value 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 textfield, use the fieldLabel attribute. To set the label of the textfield, use the listLabel attribute. To validate new items, use the fieldValidator attribute; to validate the contents of the list once the user has finished adding and removing items, specify a labelValidator.

Facets

Client-side JavaScript functions


Field Summary
static java.lang.String ADD_BUTTON_FACET
           
static java.lang.String ADD_BUTTON_ID
          The component id for the ADD button
static java.lang.String ADD_FUNCTION
          Name of the JavaScript function which is responsible for adding elements from the availble list to the selected list
static java.lang.String ENABLE_ADD_FUNCTION
          Name of the JavaScript function which is responsible for enabling/disabling the add button
static java.lang.String ENABLE_REMOVE_FUNCTION
          Name of the JavaScript function which is responsible for enabling/disabling the remove button
static java.lang.String FIELD_FACET
           
static java.lang.String FIELD_ID
          The component ID for the textfield
static java.lang.String FIELD_LABEL_FACET
           
static java.lang.String FIELD_LABEL_ID
          The component ID for the textfield
static java.lang.String FOOTER_FACET
          Facet name for the footer facet
static java.lang.String HEADER_FACET
          Facet name for the header facet
static java.lang.String JSOBJECT
          The name of the component attribute that stores the name of the JavaScript object that organizes the JavsSCript functions for the component
static java.lang.String LIST_LABEL_FACET
           
static java.lang.String LIST_LABEL_ID
          The component ID for the textfield
static java.lang.String READ_ONLY_FACET
           
static java.lang.String READ_ONLY_ID
          The component ID for the textfield
static java.lang.String REMOVE_BUTTON_FACET
           
static java.lang.String REMOVE_BUTTON_ID
          The component ID for the remove button
static java.lang.String SEARCH_FACET
          Facet name for the search facet
static java.lang.String SET_ADD_DISABLED_FUNCTION
          Name of the JavaScript function which is responsible for enabling/disabling the add button
static java.lang.String SPACER_STRING
           
static java.lang.String UPDATE_BUTTONS_FUNCTION
          Name of the JavaScript function that updates the buttons
 
Fields inherited from class javax.faces.component.UIInput
COMPONENT_FAMILY, COMPONENT_TYPE, CONVERSION_MESSAGE_ID, REQUIRED_MESSAGE_ID, UPDATE_MESSAGE_ID
 
Fields inherited from class javax.faces.component.UIComponent
bindings
 
Constructor Summary
EditableList()
           
 
Method Summary
protected  boolean compareValues(java.lang.Object previous, java.lang.Object value)
          Return true if the new value is different from the previous value.
 javax.faces.component.UIComponent getAddButtonComponent()
          Get or create the ADD button.
 java.lang.Object getConvertedValue(javax.faces.context.FacesContext context, java.lang.Object submittedValue)
          Retrieve the value of this component (the "selected" property) as an object.
 javax.faces.component.UIComponent getFieldComponent()
          Gets or creates a component for the textfield.
 javax.faces.component.UIComponent getFieldLabelComponent()
          Gets or creates a component for the textfield label.
 java.lang.String getJavaScriptObjectName()
           
 java.util.Iterator getListItems(javax.faces.context.FacesContext context, boolean rulerAtEnd)
          Retrieve an Iterator of ListSelector.ListItem, to be used by the renderer.
 javax.faces.component.UIComponent getListLabelComponent()
          Gets or creates a component for the list label.
 int getMaxlLength()
          Get the maximum length of the strings on the list
 java.lang.String getOnChange()
          Get the JS onchange event handler
 java.lang.String getPrimaryElementID(javax.faces.context.FacesContext context)
          Implement this method so that it returns the DOM ID of the HTML element which should receive focus when the component receives focus, and to which a component label should apply.
 javax.faces.component.UIComponent getReadOnlyValueComponent()
          Creates a component for the EditableList in case the component is read-only.
 javax.faces.component.UIComponent getRemoveButtonComponent()
          Get or create the REMOVE button.
protected  java.lang.String getValueAsReadOnly(javax.faces.context.FacesContext context)
          Return a string suitable for displaying the value in read only mode.
 java.lang.String[] getValueAsStringArray(javax.faces.context.FacesContext context)
          Get the value of the component as a String array.
 java.lang.String[] getValuesToRemove()
          Getter for property valuesToRemove.
 boolean isImmediate()
          Always returns false for EditableList
 boolean mainListSubmits()
           
 void processAddAction()
           
 void processRemoveAction()
           
 void processValidators(javax.faces.context.FacesContext context)
           
 void setConverter(javax.faces.convert.Converter converter)
           
 void setValuesToRemove(java.lang.String[] valuesToRemove)
          Setter for property valuesToRemove.
 
Methods inherited from class com.sun.rave.web.ui.component.EditableListBase
getFamily, getFieldLabel, getFieldValidator, getLabelLevel, getList, getListLabel, getListValidator, getMaxLength, getRows, getStyle, getStyleClass, getTabIndex, getToolTip, getValueBinding, isDisabled, isListOnTop, isMultiple, isReadOnly, isSorted, isVisible, restoreState, saveState, setDisabled, setFieldLabel, setFieldValidator, setLabelLevel, setList, setListLabel, setListOnTop, setListValidator, setMaxLength, setMultiple, setReadOnly, setRows, setSorted, setStyle, setStyleClass, setTabIndex, setToolTip, setValueBinding, setVisible
 
Methods inherited from class javax.faces.component.UIInput
addValidator, addValueChangeListener, decode, getConverterMessage, getRequiredMessage, getSubmittedValue, getValidator, getValidatorMessage, getValidators, getValueChangeListener, getValueChangeListeners, isLocalValueSet, isRequired, isValid, processDecodes, processUpdates, removeValidator, removeValueChangeListener, resetValue, setConverterMessage, setImmediate, setLocalValueSet, setRequired, setRequiredMessage, setSubmittedValue, setValid, setValidator, setValidatorMessage, setValue, setValueChangeListener, updateModel, validate, validateValue
 
Methods inherited from class javax.faces.component.UIOutput
getConverter, getLocalValue, getValue
 
Methods inherited from class javax.faces.component.UIComponentBase
addFacesListener, broadcast, encodeBegin, encodeChildren, encodeEnd, findComponent, getAttributes, getChildCount, getChildren, getClientId, getFacesContext, getFacesListeners, getFacet, getFacetCount, getFacets, getFacetsAndChildren, getId, getParent, getRenderer, getRendererType, getRendersChildren, invokeOnComponent, isRendered, isTransient, processRestoreState, processSaveState, queueEvent, removeFacesListener, restoreAttachedState, saveAttachedState, setId, setParent, setRendered, setRendererType, setTransient
 
Methods inherited from class javax.faces.component.UIComponent
encodeAll, getContainerClientId, getValueExpression, setValueExpression
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.sun.rave.web.ui.component.ListManager
getRows, getToolTip, isVisible
 
Methods inherited from interface javax.faces.component.EditableValueHolder
addValidator, addValueChangeListener, getSubmittedValue, getValidator, getValidators, getValueChangeListener, getValueChangeListeners, isLocalValueSet, isRequired, isValid, removeValidator, removeValueChangeListener, setImmediate, setLocalValueSet, setRequired, setSubmittedValue, setValid, setValidator, setValueChangeListener
 
Methods inherited from interface javax.faces.component.ValueHolder
getConverter, getLocalValue, getValue, setValue
 
Methods inherited from interface com.sun.rave.web.ui.component.SelectorManager
getClientId, getStyle, getStyleClass, getTabIndex, isDisabled, isMultiple, isReadOnly
 

Field Detail

ADD_BUTTON_ID

public static final java.lang.String ADD_BUTTON_ID
The component id for the ADD button

See Also:
Constant Field Values

ADD_BUTTON_FACET

public static final java.lang.String ADD_BUTTON_FACET
See Also:
Constant Field Values

REMOVE_BUTTON_ID

public static final java.lang.String REMOVE_BUTTON_ID
The component ID for the remove button

See Also:
Constant Field Values

REMOVE_BUTTON_FACET

public static final java.lang.String REMOVE_BUTTON_FACET
See Also:
Constant Field Values

FIELD_ID

public static final java.lang.String FIELD_ID
The component ID for the textfield

See Also:
Constant Field Values

FIELD_FACET

public static final java.lang.String FIELD_FACET
See Also:
Constant Field Values

LIST_LABEL_ID

public static final java.lang.String LIST_LABEL_ID
The component ID for the textfield

See Also:
Constant Field Values

LIST_LABEL_FACET

public static final java.lang.String LIST_LABEL_FACET
See Also:
Constant Field Values

FIELD_LABEL_ID

public static final java.lang.String FIELD_LABEL_ID
The component ID for the textfield

See Also:
Constant Field Values

FIELD_LABEL_FACET

public static final java.lang.String FIELD_LABEL_FACET
See Also:
Constant Field Values

READ_ONLY_ID

public static final java.lang.String READ_ONLY_ID
The component ID for the textfield

See Also:
Constant Field Values

READ_ONLY_FACET

public static final java.lang.String READ_ONLY_FACET
See Also:
Constant Field Values

HEADER_FACET

public static final java.lang.String HEADER_FACET
Facet name for the header facet

See Also:
Constant Field Values

FOOTER_FACET

public static final java.lang.String FOOTER_FACET
Facet name for the footer facet

See Also:
Constant Field Values

JSOBJECT

public static final java.lang.String JSOBJECT
The name of the component attribute that stores the name of the JavaScript object that organizes the JavsSCript functions for the component

See Also:
Constant Field Values

ADD_FUNCTION

public static final java.lang.String ADD_FUNCTION
Name of the JavaScript function which is responsible for adding elements from the availble list to the selected list

See Also:
Constant Field Values

ENABLE_ADD_FUNCTION

public static final java.lang.String ENABLE_ADD_FUNCTION
Name of the JavaScript function which is responsible for enabling/disabling the add button

See Also:
Constant Field Values

SET_ADD_DISABLED_FUNCTION

public static final java.lang.String SET_ADD_DISABLED_FUNCTION
Name of the JavaScript function which is responsible for enabling/disabling the add button

See Also:
Constant Field Values

ENABLE_REMOVE_FUNCTION

public static final java.lang.String ENABLE_REMOVE_FUNCTION
Name of the JavaScript function which is responsible for enabling/disabling the remove button

See Also:
Constant Field Values

UPDATE_BUTTONS_FUNCTION

public static final java.lang.String UPDATE_BUTTONS_FUNCTION
Name of the JavaScript function that updates the buttons

See Also:
Constant Field Values

SEARCH_FACET

public static final java.lang.String SEARCH_FACET
Facet name for the search facet

See Also:
Constant Field Values

SPACER_STRING

public static final java.lang.String SPACER_STRING
See Also:
Constant Field Values
Constructor Detail

EditableList

public EditableList()
Method Detail

getMaxlLength

public int getMaxlLength()
Get the maximum length of the strings on the list

Returns:
An integer value for the maximum number of characters on the list

getAddButtonComponent

public javax.faces.component.UIComponent getAddButtonComponent()
Get or create the ADD button. Retrieves the component specified by the addButton facet (if there is one) or creates a new Button component.

Returns:
A UI Component for the Add button

getRemoveButtonComponent

public javax.faces.component.UIComponent getRemoveButtonComponent()
Get or create the REMOVE button. Retrieves the component specified by the removeButton facet (if there is one) or creates a new Button component.

Returns:
A UI Component for the REMOVE button

getListLabelComponent

public javax.faces.component.UIComponent getListLabelComponent()
Gets or creates a component for the list label. Retrieves the listLabel facet if one was specified, or creates a new label component.

Returns:
A UIComponent for the list label

getFieldLabelComponent

public javax.faces.component.UIComponent getFieldLabelComponent()
Gets or creates a component for the textfield label. Retrieves the fieldLabel facet if one was specified, or creates a new label component.

Returns:
A UIComponent for the field label

getFieldComponent

public javax.faces.component.UIComponent getFieldComponent()
Gets or creates a component for the textfield. Retrieves the field facet if one was specified, or creates a new TextField component.

Returns:
A UIComponent for the textfield

getValueAsReadOnly

protected java.lang.String getValueAsReadOnly(javax.faces.context.FacesContext context)
                                       throws javax.faces.FacesException
Return a string suitable for displaying the value in read only mode. The default is to separate the list values with a comma.

Parameters:
context - The FacesContext
Throws:
javax.faces.FacesException - If the list items cannot be processed

getReadOnlyValueComponent

public javax.faces.component.UIComponent getReadOnlyValueComponent()
Creates a component for the EditableList in case the component is read-only.

Specified by:
getReadOnlyValueComponent in interface ListManager
Returns:
A UIComponent that displays the read-only value

setConverter

public void setConverter(javax.faces.convert.Converter converter)
Specified by:
setConverter in interface javax.faces.component.ValueHolder
Overrides:
setConverter in class javax.faces.component.UIOutput
Parameters:
converter -

getJavaScriptObjectName

public java.lang.String getJavaScriptObjectName()

getOnChange

public java.lang.String getOnChange()
Description copied from interface: SelectorManager
Get the JS onchange event handler

Specified by:
getOnChange in interface SelectorManager
Returns:
A string representing the JS event handler

getPrimaryElementID

public java.lang.String getPrimaryElementID(javax.faces.context.FacesContext context)
Description copied from interface: ComplexComponent
Implement this method so that it returns the DOM ID of the HTML element which should receive focus when the component receives focus, and to which a component label should apply. Usually, this is the first element that accepts input.

Specified by:
getPrimaryElementID in interface ComplexComponent
Parameters:
context - The FacesContext for the request
Returns:
The client id, also the JavaScript element id

getValuesToRemove

public java.lang.String[] getValuesToRemove()
Getter for property valuesToRemove.

Returns:
Value of property valuesToRemove.

setValuesToRemove

public void setValuesToRemove(java.lang.String[] valuesToRemove)
Setter for property valuesToRemove.

Parameters:
valuesToRemove - New value of property valuesToRemove.

getListItems

public java.util.Iterator getListItems(javax.faces.context.FacesContext context,
                                       boolean rulerAtEnd)
                                throws javax.faces.FacesException
Retrieve an Iterator of ListSelector.ListItem, to be used by the renderer.

Specified by:
getListItems in interface ListManager
rulerAtEnd - If this attribute is set to true, the iterator will contain, as the last item, a disabled list option with a blank label whose sole function is to guarantee that the list stays the same size
Returns:
an Iterator over ListItem.
Throws:
javax.faces.FacesException

getConvertedValue

public java.lang.Object getConvertedValue(javax.faces.context.FacesContext context,
                                          java.lang.Object submittedValue)
                                   throws javax.faces.convert.ConverterException
Retrieve the value of this component (the "selected" property) as an object. This method is invoked by the JSF engine during the validation phase. The JSF default behaviour is for components to defer the conversion and validation to the renderer, but for the Selector based components, the renderers do not share as much functionality as the components do, so it is more efficient to do it here.

Overrides:
getConvertedValue in class javax.faces.component.UIInput
Parameters:
context - The FacesContext of the request
submittedValue - The submitted value of the component
Throws:
javax.faces.convert.ConverterException

processValidators

public void processValidators(javax.faces.context.FacesContext context)
Overrides:
processValidators in class javax.faces.component.UIInput
Throws:
java.lang.NullPointerException

processAddAction

public void processAddAction()

processRemoveAction

public void processRemoveAction()

isImmediate

public boolean isImmediate()
Always returns false for EditableList

Specified by:
isImmediate in interface javax.faces.component.EditableValueHolder
Overrides:
isImmediate in class javax.faces.component.UIInput

compareValues

protected boolean compareValues(java.lang.Object previous,
                                java.lang.Object value)

Return true if the new value is different from the previous value.

This only implements a compareValues for value if it is an Array. If value is not an Array, defer to super.compareValues. The assumption is that the ordering of the elements between the previous value and the new value is determined in the same manner. Another assumption is that the two object arguments are of the same type, both arrays of both not arrays.

Overrides:
compareValues in class javax.faces.component.UIInput
Parameters:
previous - old value of this component (if any)
value - new value of this component (if any)

getValueAsStringArray

public java.lang.String[] getValueAsStringArray(javax.faces.context.FacesContext context)
Description copied from interface: ListManager
Get the value of the component as a String array. The array consists of the converted value of each list item is shown.

Specified by:
getValueAsStringArray in interface ListManager
Parameters:
context - The FacesContext of the request
Returns:
A string representation of the value

mainListSubmits

public boolean mainListSubmits()
Specified by:
mainListSubmits in interface ListManager