org.kuali.rice.krad.uif.widget

Class Suggest

java.lang.Object

org.kuali.rice.krad.datadictionary.DictionaryBeanBase

org.kuali.rice.krad.datadictionary.uif.UifDictionaryBeanBase

org.kuali.rice.krad.uif.component.ComponentBase

org.kuali.rice.krad.uif.widget.WidgetBase

org.kuali.rice.krad.uif.widget.Suggest

All Implemented Interfaces:

Serializable, Cloneable, Copyable, DictionaryBean, UifDictionaryBean, Component, ScriptEventSupport, LifecycleElement, Widget, org.springframework.core.Ordered

Direct Known Subclasses:

LocationSuggest

public class Suggest
extends WidgetBase

Widget that provides dynamic select options to the user as they are entering the value (also known as auto-complete).

Widget is backed by an AttributeQuery that provides the configuration for executing a query server side that will retrieve the valid option values.

Author:

Kuali Rice Team (rice.collab@kuali.org)

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Suggest.SuggestPostData Holds post data for the suggest component.

Field Summary

Fields inherited from class org.kuali.rice.krad.uif.component.ComponentBase

templateOptions

Fields inherited from class org.kuali.rice.krad.datadictionary.DictionaryBeanBase

componentCode, namespaceCode

Fields inherited from interface org.kuali.rice.krad.uif.component.Ordered

INITIAL_ORDER_VALUE

Fields inherited from interface org.springframework.core.Ordered

HIGHEST_PRECEDENCE, LOWEST_PRECEDENCE

Constructor Summary

Constructors

Constructor and Description
Suggest()

Method Summary

Modifier and Type	Method and Description
List<String>	getAdditionalPropertiesToReturn() List of additional properties to return in the result objects to the plugin's success callback.
String	getLabelPropertyName() Name of the property on the query result object that provides the label for the suggestion.
Suggest.SuggestPostData	getPostData() Returns object containing post data to store for the suggest request.
List<Object>	getSuggestOptions() When isRetrieveAllSuggestions() is true, this list provides the full list of suggestions
String	getSuggestOptionsJsString() Returns the suggest options as a JS String (set by the framework from method invocation)
AttributeQuery	getSuggestQuery() Attribute query instance the will be executed to provide the suggest options
String	getValuePropertyName() Name of the property on the query result object that provides the options for the suggest, values from this field will be collected and sent back on the result to provide as suggest options.
boolean	isRetrieveAllSuggestions() Indicates whether all suggest options should be retrieved up front and provide to the suggest widget as options locally
boolean	isReturnFullQueryObject() When set to true the results of a query method will be sent back as-is (in translated form) with all properties intact.
boolean	isSuggestConfigured() Indicates whether the suggest widget has the necessary configuration to render
void	performApplyModel(Object model, LifecycleElement parent) The following updates are done here: Invoke expression evaluation on the suggestQuery The following updates are done here: Evaluate the progressive render condition (if set) and combine with the current render status to set the render status Called after the initialize phase to perform conditional logic based on the model data
void	performFinalize(Object model, LifecycleElement parent) The following actions are performed: Adjusts the query field mappings on the query based on the binding configuration of the field TODO: determine query if render is true and query is not set The following finalization is done here: progressiveRender and conditionalRefresh variables are processed if set If any of the style properties were given, sets the style string on the style property Set the skipInTabOrder flag for nested components The last phase before the view is rendered
protected void	retrieveSuggestOptions(View view) Invokes the configured query method and sets the returned method value as the suggest options or suggest options JS string
void	setAdditionalPropertiesToReturn(List<String> additionalPropertiesToReturn) Set the list of additional properties to return to the plugin success callback results
void	setLabelPropertyName(String labelPropertyName) Set the labelPropertyName
void	setRetrieveAllSuggestions(boolean retrieveAllSuggestions) Setter for the retrieve all suggestions indicator
void	setReturnFullQueryObject(boolean returnFullQueryObject) Setter for the for returning the full object of the query
void	setSuggestOptions(List<Object> suggestOptions) Setter for the list of suggest options
void	setSuggestOptionsJsString(String suggestOptionsJsString) Sets suggest options javascript string
void	setSuggestQuery(AttributeQuery suggestQuery) Setter for the suggest attribute query
void	setValuePropertyName(String valuePropertyName) Setter for the value property name

Methods inherited from class org.kuali.rice.krad.uif.widget.WidgetBase

getComponentTypeName

Methods inherited from class org.kuali.rice.krad.uif.component.ComponentBase

addAriaAttribute, addDataAttribute, addScriptDataAttribute, addStyleClass, addWrapperCssClass, afterEvaluateExpression, appendToStyle, checkMutable, clone, completeValidation, getAdditionalComponentsToRefresh, getAdditionalComponentsToRefreshJs, getAdditionalCssClasses, getAdditionalTemplates, getAlign, getAriaAttributes, getAriaAttributesAsString, getCanCopyOnReadOnly, getCellWidth, getColSpan, getComponentModifiers, getComponentSecurity, getConditionalRefresh, getConditionalRefreshConditionJs, getConditionalRefreshControlNames, getContainerIdSuffix, getContext, getCssClasses, getCssGridSizes, getDataAttributes, getEventHandlerScript, getExcludeIf, getExcludeUnless, getFieldsToSendOnRefresh, getFinalizeMethodAdditionalArguments, getFinalizeMethodInvoker, getFinalizeMethodToCall, getId, getLibraryCssClasses, getMethodToCallOnRefresh, getOnBlurScript, getOnChangeScript, getOnClickScript, getOnCloseScript, getOnDblClickScript, getOnDocumentReadyScript, getOnFocusScript, getOnInputScript, getOnKeyDownScript, getOnKeyPressScript, getOnKeyUpScript, getOnLoadScript, getOnMouseDownScript, getOnMouseMoveScript, getOnMouseOutScript, getOnMouseOverScript, getOnMouseUpScript, getOnSubmitScript, getOnUnloadScript, getOrder, getPhasePathMapping, getPostRenderContent, getPreRenderContent, getProgressiveDisclosureConditionJs, getProgressiveDisclosureControlNames, getProgressiveRender, getPropertyReplacerComponents, getPropertyReplacers, getReadOnly, getRefreshTimer, getRefreshWhenChangedPropertyNames, getRenderedHtmlOutput, getRequired, getRole, getRowSpan, getScriptDataAttributes, getScriptDataAttributesJs, getSimpleDataAttributes, getStyle, getStyleClassesAsString, getTemplate, getTemplateName, getTemplateOptions, getTemplateOptionsJSString, getTitle, getToolTip, getValign, getViewPath, getViewStatus, getWidth, getWrapperCssClasses, getWrapperCssClassesAsString, getWrapperStyle, initializeComponentSecurity, isDisableSessionPersistence, isDisclosedByAction, isEditAuthz, isFinal, isForceSessionPersistence, isHidden, isInitialized, isModelApplied, isMutable, isOmitFromFormPost, isProgressiveRenderAndRefresh, isProgressiveRenderViaAJAX, isRefreshedByAction, isRender, isRendered, isResetDataOnRefresh, isRetrieveViaAjax, isSelfRendered, isSkipInTabOrder, isViewAuthz, notifyCompleted, performInitialization, pushAllToContext, pushObjectToContext, pushToPropertyReplacerContext, setAdditionalComponentsToRefresh, setAdditionalCssClasses, setAlign, setAriaAttributes, setCanCopyOnReadOnly, setCellWidth, setColSpan, setComponentModifiers, setComponentSecurity, setConditionalRefresh, setContainerIdSuffix, setContext, setCssClasses, setCssGridSizes, setDataAttributes, setDisableSessionPersistence, setDisclosedByAction, setEditAuthz, setExcludeIf, setExcludeUnless, setFieldsToSendOnRefresh, setFinalizeMethodAdditionalArguments, setFinalizeMethodInvoker, setFinalizeMethodToCall, setForceSessionPersistence, setHidden, setId, setLibraryCssClasses, setMethodToCallOnRefresh, setOmitFromFormPost, setOnBlurScript, setOnChangeScript, setOnClickScript, setOnCloseScript, setOnDblClickScript, setOnDocumentReadyScript, setOnFocusScript, setOnInputScript, setOnKeyDownScript, setOnKeyPressScript, setOnKeyUpScript, setOnLoadScript, setOnMouseDownScript, setOnMouseMoveScript, setOnMouseOutScript, setOnMouseOverScript, setOnMouseUpScript, setOnSubmitScript, setOnUnloadScript, setOrder, setPhasePathMapping, setPostRenderContent, setPreRenderContent, setProgressiveRender, setProgressiveRenderAndRefresh, setProgressiveRenderViaAJAX, setPropertyReplacers, setReadOnly, setRefreshedByAction, setRefreshTimer, setRefreshWhenChangedPropertyNames, setRender, setRenderedHtmlOutput, setRequired, setResetDataOnRefresh, setRetrieveViaAjax, setRole, setRowSpan, setScriptDataAttributes, setSelfRendered, setSkipInTabOrder, setStyle, setTemplate, setTemplateName, setTemplateOptions, setTemplateOptionsJSString, setTitle, setToolTip, setValign, setViewAuthz, setViewPath, setViewStatus, setWidth, setWrapperCssClasses, setWrapperStyle, skipLifecycle

Methods inherited from class org.kuali.rice.krad.datadictionary.uif.UifDictionaryBeanBase

getExpressionGraph, getPropertyExpression, getPropertyExpressions, setExpressionGraph, setPropertyExpressions

Methods inherited from class org.kuali.rice.krad.datadictionary.DictionaryBeanBase

copy, dataDictionaryPostProcessing, getComponentCode, getNamespaceCode, setComponentCode, setNamespaceCode

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.kuali.rice.krad.uif.component.Component

addAriaAttribute, addDataAttribute, addScriptDataAttribute, addStyleClass, addWrapperCssClass, afterEvaluateExpression, appendToStyle, completeValidation, getAdditionalComponentsToRefresh, getAdditionalComponentsToRefreshJs, getAdditionalCssClasses, getAdditionalTemplates, getAlign, getAriaAttributes, getAriaAttributesAsString, getCanCopyOnReadOnly, getCellWidth, getColSpan, getComponentModifiers, getComponentSecurity, getConditionalRefresh, getConditionalRefreshConditionJs, getConditionalRefreshControlNames, getContext, getCssClasses, getCssGridSizes, getDataAttributes, getEventHandlerScript, getExcludeIf, getExcludeUnless, getFieldsToSendOnRefresh, getFinalizeMethodAdditionalArguments, getFinalizeMethodInvoker, getFinalizeMethodToCall, getLibraryCssClasses, getMethodToCallOnRefresh, getOrder, getPostRenderContent, getPreRenderContent, getProgressiveDisclosureConditionJs, getProgressiveDisclosureControlNames, getProgressiveRender, getPropertyReplacerComponents, getPropertyReplacers, getReadOnly, getRefreshTimer, getRefreshWhenChangedPropertyNames, getRenderedHtmlOutput, getRequired, getRole, getRowSpan, getScriptDataAttributes, getScriptDataAttributesJs, getSimpleDataAttributes, getStyle, getStyleClassesAsString, getTemplate, getTemplateName, getTemplateOptions, getTemplateOptionsJSString, getTitle, getToolTip, getValign, getWidth, getWrapperCssClasses, getWrapperStyle, isDisableSessionPersistence, isDisclosedByAction, isForceSessionPersistence, isHidden, isOmitFromFormPost, isProgressiveRenderAndRefresh, isProgressiveRenderViaAJAX, isRefreshedByAction, isRendered, isResetDataOnRefresh, isRetrieveViaAjax, isSelfRendered, setAdditionalComponentsToRefresh, setAdditionalCssClasses, setAlign, setAriaAttributes, setCanCopyOnReadOnly, setCellWidth, setColSpan, setComponentModifiers, setComponentSecurity, setConditionalRefresh, setContext, setCssClasses, setCssGridSizes, setDataAttributes, setDisableSessionPersistence, setDisclosedByAction, setFieldsToSendOnRefresh, setForceSessionPersistence, setHidden, setLibraryCssClasses, setOmitFromFormPost, setOrder, setPostRenderContent, setPreRenderContent, setProgressiveRender, setProgressiveRenderAndRefresh, setProgressiveRenderViaAJAX, setPropertyReplacers, setReadOnly, setRefreshedByAction, setRefreshTimer, setRefreshWhenChangedPropertyNames, setRenderedHtmlOutput, setRequired, setResetDataOnRefresh, setRetrieveViaAjax, setRole, setRowSpan, setScriptDataAttributes, setSelfRendered, setStyle, setTemplate, setTemplateName, setTemplateOptions, setTemplateOptionsJSString, setTitle, setToolTip, setValign, setViewStatus, setWidth, setWrapperCssClasses, setWrapperStyle

Methods inherited from interface org.kuali.rice.krad.datadictionary.uif.UifDictionaryBean

getExpressionGraph, getPropertyExpression, getPropertyExpressions, setExpressionGraph, setPropertyExpressions

Methods inherited from interface org.kuali.rice.krad.datadictionary.DictionaryBean

dataDictionaryPostProcessing, getComponentCode, getNamespaceCode

Methods inherited from interface org.kuali.rice.krad.uif.util.LifecycleElement

checkMutable, getContainerIdSuffix, getId, getPhasePathMapping, getViewPath, getViewStatus, isFinal, isInitialized, isModelApplied, isMutable, isRender, notifyCompleted, performInitialization, pushAllToContext, pushObjectToContext, setContainerIdSuffix, setId, setPhasePathMapping, setRender, setViewPath, skipLifecycle

Methods inherited from interface org.kuali.rice.krad.datadictionary.Copyable

clone

Methods inherited from interface org.kuali.rice.krad.uif.component.ScriptEventSupport

getOnBlurScript, getOnChangeScript, getOnClickScript, getOnCloseScript, getOnDblClickScript, getOnDocumentReadyScript, getOnFocusScript, getOnInputScript, getOnKeyDownScript, getOnKeyPressScript, getOnKeyUpScript, getOnLoadScript, getOnMouseDownScript, getOnMouseMoveScript, getOnMouseOutScript, getOnMouseOverScript, getOnMouseUpScript, getOnSubmitScript, getOnUnloadScript, setOnBlurScript, setOnChangeScript, setOnClickScript, setOnCloseScript, setOnDblClickScript, setOnDocumentReadyScript, setOnFocusScript, setOnInputScript, setOnKeyDownScript, setOnKeyPressScript, setOnKeyUpScript, setOnLoadScript, setOnMouseDownScript, setOnMouseMoveScript, setOnMouseOutScript, setOnMouseOverScript, setOnMouseUpScript, setOnSubmitScript, setOnUnloadScript

Constructor Detail

Suggest

public Suggest()

Method Detail

performApplyModel

public void performApplyModel(Object model,
                              LifecycleElement parent)

The following updates are done here:

• Invoke expression evaluation on the suggestQuery

The following updates are done here:

• Evaluate the progressive render condition (if set) and combine with the current render status to set the render status

Called after the initialize phase to perform conditional logic based on the model data

Where components can perform conditional logic such as dynamically generating new fields or setting field state based on the given data

Specified by:

performApplyModel in interface LifecycleElement

Overrides:

performApplyModel in class ComponentBase

Parameters:

model - - Top level object containing the data (could be the form or a top level business object, dto)

parent - parent lifecycle element

performFinalize

public void performFinalize(Object model,
                            LifecycleElement parent)

The following actions are performed:

• Adjusts the query field mappings on the query based on the binding configuration of the field
• TODO: determine query if render is true and query is not set

The following finalization is done here:

• progressiveRender and conditionalRefresh variables are processed if set
• If any of the style properties were given, sets the style string on the style property
• Set the skipInTabOrder flag for nested components

The last phase before the view is rendered

Here final preparations can be made based on the updated view state.

Specified by:

performFinalize in interface LifecycleElement

Overrides:

performFinalize in class ComponentBase

Parameters:

model - - top level object containing the data

parent - - parent component

isSuggestConfigured

public boolean isSuggestConfigured()

Indicates whether the suggest widget has the necessary configuration to render

Returns:

true if the necessary configuration is present, false if not

retrieveSuggestOptions

protected void retrieveSuggestOptions(View view)

Invokes the configured query method and sets the returned method value as the suggest options or suggest options JS string

Parameters:

view - view instance the suggest belongs to, used to get the view helper service if needed

getPostData

public Suggest.SuggestPostData getPostData()

Returns object containing post data to store for the suggest request.

Returns:

suggest post data instance

getSuggestQuery

public AttributeQuery getSuggestQuery()

Attribute query instance the will be executed to provide the suggest options

Returns:

AttributeQuery

setSuggestQuery

public void setSuggestQuery(AttributeQuery suggestQuery)

Setter for the suggest attribute query

Parameters:

suggestQuery -

getValuePropertyName

public String getValuePropertyName()

Name of the property on the query result object that provides the options for the suggest, values from this field will be collected and sent back on the result to provide as suggest options.

If a labelPropertyName is also set, the property specified by it will be used as the label the user selects (the suggestion), but the value will be the value retrieved by this property. If only one of labelPropertyName or valuePropertyName is set, the property's value on the object will be used for both the value inserted on selection and the suggestion text (most default cases only a valuePropertyName would be set).

Returns:

source property name

setValuePropertyName

public void setValuePropertyName(String valuePropertyName)

Setter for the value property name

Parameters:

valuePropertyName -

getLabelPropertyName

public String getLabelPropertyName()

Name of the property on the query result object that provides the label for the suggestion.

This should be set when the label that the user selects is different from the value that is inserted when a user selects a suggestion. If only one of labelPropertyName or valuePropertyName is set, the property's value on the object will be used for both the value inserted on selection and the suggestion text (most default cases only a valuePropertyName would be set).

Returns:

labelPropertyName representing the property to use for the suggestion label of the item

setLabelPropertyName

public void setLabelPropertyName(String labelPropertyName)

Set the labelPropertyName

Parameters:

labelPropertyName -

getAdditionalPropertiesToReturn

public List<String> getAdditionalPropertiesToReturn()

List of additional properties to return in the result objects to the plugin's success callback.

In most cases, this should not be set. The main use case of setting this list is to use additional properties in the select function on the plugin's options, so it is only recommended that this property be set when doing heavy customization to the select function. This list is not used if the full result object is already being returned.

Returns:

the list of additional properties to send back

setAdditionalPropertiesToReturn

public void setAdditionalPropertiesToReturn(List<String> additionalPropertiesToReturn)

Set the list of additional properties to return to the plugin success callback results

Parameters:

additionalPropertiesToReturn -

isReturnFullQueryObject

public boolean isReturnFullQueryObject()

When set to true the results of a query method will be sent back as-is (in translated form) with all properties intact.

Note this is not supported for highly complex objects (ie, most auto-query objects - will throw exception). Intended usage of this flag is with custom query methods which return simple data objects. The query method can return a list of Strings which will be used for the suggestions, a list of objects with 'label' and 'value' properties, or a custom object. In the case of using a customObject labelPropertyName or valuePropertyName MUST be specified (or both) OR the custom object must contain a property named "label" or "value" (or both) for the suggestions to appear. In cases where this is not used, the data sent back represents a slim subset of the properties on the object.

Returns:

true if the query method results should be used as the suggestions, false to assume objects are returned and suggestions are formed using the source property name

setReturnFullQueryObject

public void setReturnFullQueryObject(boolean returnFullQueryObject)

Setter for the for returning the full object of the query

Parameters:

returnFullQueryObject -

isRetrieveAllSuggestions

public boolean isRetrieveAllSuggestions()

Indicates whether all suggest options should be retrieved up front and provide to the suggest widget as options locally

Use this for a small list of options to improve performance. The query will be performed on the client to filter the provider options based on the users input instead of doing a query each time

When a query method is configured and this option set to true the method will be invoked to set the options. The query method should not take any arguments and should return the suggestion options List or the JS String as a result. If a query method is not configured the suggest options can be set through configuration or a view helper method (for example a component finalize method)

Returns:

true to provide the suggest options initially, false to use ajax retrieval based on the user's input

setRetrieveAllSuggestions

public void setRetrieveAllSuggestions(boolean retrieveAllSuggestions)

Setter for the retrieve all suggestions indicator

Parameters:

retrieveAllSuggestions -

getSuggestOptions

public List<Object> getSuggestOptions()

When isRetrieveAllSuggestions() is true, this list provides the full list of suggestions

If a query method is configured that method will be invoked to populate this list, otherwise the list should be populated through configuration or the view helper

The suggest options can either be a list of Strings, in which case the strings will be the suggested values. Or a list of objects. If the object does not have 'label' and 'value' properties, a custom render and select method must be provided

Returns:

list of suggest options

setSuggestOptions

public void setSuggestOptions(List<Object> suggestOptions)

Setter for the list of suggest options

Parameters:

suggestOptions -

getSuggestOptionsJsString

public String getSuggestOptionsJsString()

Returns the suggest options as a JS String (set by the framework from method invocation)

Returns:

suggest options JS string

setSuggestOptionsJsString

public void setSuggestOptionsJsString(String suggestOptionsJsString)

Sets suggest options javascript string

Parameters:

suggestOptionsJsString -