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

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.OrderableListBase
                      com.sun.rave.web.ui.component.OrderableList

All Implemented Interfaces:

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

public class OrderableList

extends OrderableListBase

implements ListManager

About this tag.

This tag renders an OrderableList 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 "moveUp" 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

• fieldLabel: use this facet to specify a custom component for the textfield label.
• listLabel: use this facet to specify a custom component for the textfield label.
• field: use this facet to specify a custom component for the textfield.
• moveUpButton: use this facet to specify a custom component for the moveUp button.
• removeButton: use this facet to specify a custom component for the remove button.
• search: use this facet to specify a custom component for the search button.
• readOnly: use this facet to specify a custom component for display a readonly version of the component.
• header: use this facet to specify a header, rendered in a table row above the component.
• footer: use this facet to specify a header, rendered in a table row below the component.

Client-side JavaScript functions

• NONE yet

Author:

avk

Field Summary

static java.lang.String	FOOTER_FACET The name for the footer facet.
static java.lang.String	JAVASCRIPT_PREFIX Represents the "javascript:" printed at the start of javascript event handler code.
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	LABEL_FACET The facet name for the label.
static java.lang.String	LABEL_ID The component ID for the label.
static java.lang.String	MOVEBOTTOM_BUTTON_FACET The facet name for the moveBottom button.
static java.lang.String	MOVEBOTTOM_BUTTON_ID The component id for the moveBottom button.
static java.lang.String	MOVEBOTTOM_FUNCTION Name of the JavaScript function which moves elements to the bottom.
static java.lang.String	MOVEDOWN_BUTTON_FACET The facet name for the moveDown button.
static java.lang.String	MOVEDOWN_BUTTON_ID The component id for the moveDown button.
static java.lang.String	MOVEDOWN_FUNCTION Name of the JavaScript function which moves elements down.
static java.lang.String	MOVETOP_BUTTON_FACET The facet name for the moveTop button.
static java.lang.String	MOVETOP_BUTTON_ID The component id for the moveTop button.
static java.lang.String	MOVETOP_FUNCTION Name of the JavaScript function which moves elements to the top.
static java.lang.String	MOVEUP_BUTTON_FACET The facet name for the moveUp button.
static java.lang.String	MOVEUP_BUTTON_ID The component id for the moveUp button.
static java.lang.String	MOVEUP_FUNCTION Name of the JavaScript function which moves elements up.
static java.lang.String	ONCHANGE_FUNCTION Name of the JavaScript function that handles changes on the available list.
static java.lang.String	READ_ONLY_FACET The facet name for the readOnly text field.
static java.lang.String	READ_ONLY_ID The component ID for the read only text field.
static java.lang.String	REMOVE_BUTTON_FACET The facet name for the remove button.
static java.lang.String	REMOVE_BUTTON_ID The component ID for the remove button.
static java.lang.String	RETURN String representing "return false" printed at the end of the javascript event handlers.
static java.lang.String	UPDATEBUTTONS_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

Constructor Summary

OrderableList()

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.
protected ListItem	createListItem(javax.faces.component.UIComponent comp, java.lang.Object value) Enforce non null values.
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	getHeaderComponent() Gets or creates a component for the list label.
java.util.Iterator	getListItems(javax.faces.context.FacesContext context, boolean ruler) Retrieve an Iterator of ListSelector.ListItem, to be used by the renderer.
javax.faces.component.UIComponent	getMoveBottomButtonComponent(javax.faces.context.FacesContext context) Get or create the MOVEBOTTOM button.
javax.faces.component.UIComponent	getMoveDownButtonComponent(javax.faces.context.FacesContext context) Get or create the MOVEDOWN button.
javax.faces.component.UIComponent	getMoveTopButtonComponent(javax.faces.context.FacesContext context) Get or create the MOVETOP button.
javax.faces.component.UIComponent	getMoveUpButtonComponent(javax.faces.context.FacesContext context) Get or create the MOVE UP button.
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 OrderableList in case the component is read-only.
int	getRows() Get the number of rows to display (the size of the HTML select element)
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.
boolean	mainListSubmits()

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

getFamily, getLabel, getLabelLevel, getList, getStyle, getStyleClass, getTabIndex, getToolTip, getValueBinding, isDisabled, isLabelOnTop, isMoveTopBottom, isMultiple, isReadOnly, isVisible, restoreState, saveState, setDisabled, setLabel, setLabelLevel, setLabelOnTop, setList, setMoveTopBottom, setMultiple, setReadOnly, setRows, setStyle, setStyleClass, setTabIndex, setToolTip, setValueBinding, setVisible

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, getRendersChildren, 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, toString, wait, wait, wait

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

getToolTip, 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, getStyle, getStyleClass, getTabIndex, isDisabled, isMultiple, isReadOnly

Field Detail

MOVEUP_BUTTON_ID

public static final java.lang.String MOVEUP_BUTTON_ID

The component id for the moveUp button.

See Also:

Constant Field Values

MOVEUP_BUTTON_FACET

public static final java.lang.String MOVEUP_BUTTON_FACET

The facet name for the moveUp button.

See Also:

Constant Field Values

MOVEDOWN_BUTTON_ID

public static final java.lang.String MOVEDOWN_BUTTON_ID

The component id for the moveDown button.

See Also:

Constant Field Values

MOVEDOWN_BUTTON_FACET

public static final java.lang.String MOVEDOWN_BUTTON_FACET

The facet name for the moveDown button.

See Also:

Constant Field Values

MOVETOP_BUTTON_ID

public static final java.lang.String MOVETOP_BUTTON_ID

The component id for the moveTop button.

See Also:

Constant Field Values

MOVETOP_BUTTON_FACET

public static final java.lang.String MOVETOP_BUTTON_FACET

The facet name for the moveTop button.

See Also:

Constant Field Values

MOVEBOTTOM_BUTTON_ID

public static final java.lang.String MOVEBOTTOM_BUTTON_ID

The component id for the moveBottom button.

See Also:

Constant Field Values

MOVEBOTTOM_BUTTON_FACET

public static final java.lang.String MOVEBOTTOM_BUTTON_FACET

The facet name for the moveBottom button.

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

The facet name for the remove button.

See Also:

Constant Field Values

LABEL_ID

public static final java.lang.String LABEL_ID

The component ID for the label.

See Also:

Constant Field Values

LABEL_FACET

public static final java.lang.String LABEL_FACET

The facet name for the label.

See Also:

Constant Field Values

READ_ONLY_ID

public static final java.lang.String READ_ONLY_ID

The component ID for the read only text field.

See Also:

Constant Field Values

READ_ONLY_FACET

public static final java.lang.String READ_ONLY_FACET

The facet name for the readOnly text field.

See Also:

Constant Field Values

FOOTER_FACET

public static final java.lang.String FOOTER_FACET

The 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

JAVASCRIPT_PREFIX

public static final java.lang.String JAVASCRIPT_PREFIX

Represents the "javascript:" printed at the start of javascript event handler code.

See Also:

Constant Field Values

RETURN

public static final java.lang.String RETURN

String representing "return false" printed at the end of the javascript event handlers.

See Also:

Constant Field Values

MOVEUP_FUNCTION

public static final java.lang.String MOVEUP_FUNCTION

Name of the JavaScript function which moves elements up.

See Also:

Constant Field Values

MOVEDOWN_FUNCTION

public static final java.lang.String MOVEDOWN_FUNCTION

Name of the JavaScript function which moves elements down.

See Also:

Constant Field Values

MOVETOP_FUNCTION

public static final java.lang.String MOVETOP_FUNCTION

Name of the JavaScript function which moves elements to the top.

See Also:

Constant Field Values

MOVEBOTTOM_FUNCTION

public static final java.lang.String MOVEBOTTOM_FUNCTION

Name of the JavaScript function which moves elements to the bottom.

See Also:

Constant Field Values

UPDATEBUTTONS_FUNCTION

public static final java.lang.String UPDATEBUTTONS_FUNCTION

Name of the JavaScript function that updates the buttons.

See Also:

Constant Field Values

ONCHANGE_FUNCTION

public static final java.lang.String ONCHANGE_FUNCTION

Name of the JavaScript function that handles changes on the available list.

See Also:

Constant Field Values

Constructor Detail

OrderableList

public OrderableList()

Method Detail

getMoveUpButtonComponent

public javax.faces.component.UIComponent getMoveUpButtonComponent(javax.faces.context.FacesContext context)

Get or create the MOVE UP button. Retrieves the component specified by the moveUpButton facet (if there is one) or creates a new Button component.

Returns:

A UI Component for the moveUp button

getMoveDownButtonComponent

public javax.faces.component.UIComponent getMoveDownButtonComponent(javax.faces.context.FacesContext context)

Get or create the MOVEDOWN button. Retrieves the component specified by the moveDownButton facet (if there is one) or creates a new Button component.

Returns:

A UI Component for the MOVEDOWN button

getMoveTopButtonComponent

public javax.faces.component.UIComponent getMoveTopButtonComponent(javax.faces.context.FacesContext context)

Get or create the MOVETOP button. Retrieves the component specified by the moveTopButton facet (if there is one) or creates a new Button component.

Returns:

A UI Component for the Add button

getMoveBottomButtonComponent

public javax.faces.component.UIComponent getMoveBottomButtonComponent(javax.faces.context.FacesContext context)

Get or create the MOVEBOTTOM button. Retrieves the component specified by the moveBottomButton facet (if there is one) or creates a new Button component.

Returns:

A UI Component for the Move Bottom button

getHeaderComponent

public javax.faces.component.UIComponent getHeaderComponent()

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

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

getListItems

public java.util.Iterator getListItems(javax.faces.context.FacesContext context,
                                       boolean ruler)
                                throws javax.faces.FacesException

Retrieve an Iterator of ListSelector.ListItem, to be used by the renderer.

Specified by:

getListItems in interface ListManager

Parameters:

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

createListItem

protected ListItem createListItem(javax.faces.component.UIComponent comp,
                                  java.lang.Object value)

Enforce non null values. This is ok, since Converter returns null on null input. And secondly this is equivalent to SelectItem and therefore Option which do not allow null values. However we have to be wary of values that are "". But if the null case is out of the way the this should work ok.

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

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.

Parameters:

context - The FacesContext of the request

submittedValue - The submitted value of the component

Throws:

javax.faces.convert.ConverterException

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 OrderableList in case the component is read-only.

Specified by:

getReadOnlyValueComponent in interface ListManager

Returns:

A UIComponent that displays the read-only value

getRows

public int getRows()

Description copied from interface: ListManager

Get the number of rows to display (the size of the HTML select element)

Specified by:

getRows in interface ListManager

Overrides:

getRows in class OrderableListBase

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

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.

Parameters:

previous - old value of this component (if any)

value - new value of this component (if any)

mainListSubmits

public boolean mainListSubmits()

Specified by:

mainListSubmits in interface ListManager