Package 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, Ordered, 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:

  • Constructor Details

    • Suggest

      public Suggest()

  • Method Details

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