Package org.kuali.rice.krad.uif.widget

Class QuickFinder

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.QuickFinder
All Implemented Interfaces:
Serializable, Cloneable, Copyable, DictionaryBean, UifDictionaryBean, Component, Ordered, ScriptEventSupport, LifecycleEventListener, LifecycleElement, Widget, org.springframework.core.Ordered
public class QuickFinder extends WidgetBase implements LifecycleEventListener
Widget for navigating to a lookup from a field (called a quickfinder).
Author:
Kuali Rice Team (rice.collab@kuali.org)
See Also:

  • Constructor Details

    • QuickFinder

      public QuickFinder()

  • Method Details

    • performInitialization

      public void performInitialization(Object model)
      The following initialization is performed:
      • Registers an event on the quickfinder action
      The following updates are done here:
      • Invoke performInitialize on component modifiers
      Initializes the component

      Where components can set defaults and setup other necessary state. The initialize method should only be called once per component lifecycle and is invoked within the initialize phase of the view lifecylce.

      Specified by:
      performInitialization in interface LifecycleElement
      Overrides:
      performInitialization in class ComponentBase
      Parameters:
      model - - object instance containing the view data
      See Also:

    • afterEvaluateExpression

      public void afterEvaluateExpression()
      Inherits readOnly from parent if not explicitly populated. No-op implementation. Override for custom behavior in subclasses. Invoked by the view lifecycle after expressions are evaluated at the apply model phase.

      In general, this method is preferred to LifecycleElement.performApplyModel(Object, LifecycleElement) for populating model data via code, since it is called before client-side state is synchronize.

      Specified by:
      afterEvaluateExpression in interface Component
      Overrides:
      afterEvaluateExpression in class ComponentBase

    • performFinalize

      public void performFinalize(Object model, LifecycleElement parent)
      The following finalization is performed:
      • Sets up the quickfinder based on whether the parent is an input field or collection group
      • Adds action parameters to the quickfinder action based on the quickfinder configuration
      • Adds callback parameters to post data if present
      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

    • setupForInputField

      protected void setupForInputField(View view, Object model, InputField inputField)
      If quickfinder not manually configured attempts to find a relationship to build the quickfinder on, then also adjusts the path for any configured field conversions, lookup parameters, and refresh refreshes.
      Parameters:
      view - view instance the quickfinder is associated with
      model - object containing the view data
      inputField - input field instance the quickfinder should apply to

    • getRelationshipForField

      protected org.kuali.rice.krad.bo.DataObjectRelationship getRelationshipForField(View view, Object model, InputField field)
      Retrieves any DataObjectRelationship that is associated with the given field and has a configured lookup view.
      Parameters:
      view - view instance the quickfinder is associated with
      model - object containing the view data
      field - input field instance the quickfinder should apply to
      Returns:
      data object relationship for the field, or null if one could not be found

    • generateFieldConversions

      protected void generateFieldConversions(org.kuali.rice.krad.bo.DataObjectRelationship relationship)
      Generates the lookup field conversions based on the references from the given relationship.
      Parameters:
      relationship - relationship field conversions will be generated from

    • generateLookupParameters

      protected void generateLookupParameters(org.kuali.rice.krad.bo.DataObjectRelationship relationship)
      Generates the lookup parameters based on the references from the given relationship.
      Parameters:
      relationship - relationship lookup parameters will be generated from

    • updateFieldConversions

      protected void updateFieldConversions(BindingInfo bindingInfo)
      Adjusts the path on the field conversion to property to match the binding path prefix of the given BindingInfo.
      Parameters:
      bindingInfo - binding info instance to copy binding path prefix from

    • updateLookupParameters

      protected void updateLookupParameters(BindingInfo bindingInfo)
      Adjusts the path on the lookup parameter from property to match the binding path prefix of the given BindingInfo.
      Parameters:
      bindingInfo - binding info instance to copy binding path prefix from

    • updateReferencesToRefresh

      protected void updateReferencesToRefresh(BindingInfo bindingInfo)
      Adjust the path on the referencesToRefresh parameter to match the binding path prefix of the given BindingInfo.
      Parameters:
      bindingInfo - binding info instance to copy binding path prefix from

    • setupForCollectionGroup

      protected void setupForCollectionGroup(View view, Object model, CollectionGroup collectionGroup)
      Configures the quickfinder for the given collection group instance by setting the data object class, field conversions, and lookup collection name (if necessary).
      Parameters:
      view - view instance the quickfinder is associated with
      model - object containing the view data
      collectionGroup - collection group instance to build quickfinder for

    • setupQuickfinderAction

      protected void setupQuickfinderAction(View view, Object model, LifecycleElement parent)
      Adjusts the id for the quickfinder action, and then adds action parameters for passing along the quickfinder configuration to the lookup view.
      Parameters:
      view - view instance the quickfinder is associated with
      model - object containing the view data
      parent - component instance the quickfinder is associated with

    • addActionParameterIfNotNull

      protected void addActionParameterIfNotNull(String parameterName, Object parameterValue)
      Utility method to add an action parameter to the quickfinder action if the given parameter value is non blank.
      Parameters:
      parameterName - name of the parameter to add
      parameterValue - value for the parameter to add

    • processEvent

      public void processEvent(ViewLifecycle.LifecycleEvent lifecycleEvent, View view, Object model, LifecycleElement eventComponent)
      Adds post context data for the quickfinder so when the lookup return occurs the focus and jump point of the quickfinder action can be retrieved. Invoked on a component listener when an event occurs for the given event component.
      Specified by:
      processEvent in interface LifecycleEventListener
      Parameters:
      lifecycleEvent - event that occurred
      view - view instance the lifecycle is being processed for
      model - object containing the model data
      eventComponent - element instance the event occurred on/for

    • addCallbackParametersIfPresent

      protected void addCallbackParametersIfPresent()
      Adds callback method and its parameters to post data so that when a refresh occurs it knows which view is returned from and possibly which collection line the quickfinder was on.

    • getBaseLookupUrl

      public String getBaseLookupUrl()
      Returns the URL for the lookup for which parameters will be added.

      The base URL includes the domain, context, and controller mapping for the lookup invocation. Parameters are then added based on configuration to complete the URL. This is generally defaulted to the application URL and internal KRAD servlet mapping, but can be changed to invoke another application such as the Rice standalone server

      Returns:
      lookup base URL

    • setBaseLookupUrl

      public void setBaseLookupUrl(String baseLookupUrl)
      See Also:

    • getDataObjectClassName

      public String getDataObjectClassName()
      Full class name the lookup should be provided for.

      This is passed on to the lookup request for the data object the lookup should be rendered for. This is then used by the lookup framework to select the lookup view (if more than one lookup view exists for the same data object class name, the getViewName() property should be specified to select the view to render).

      Returns:
      lookup class name

    • setDataObjectClassName

      public void setDataObjectClassName(String dataObjectClassName)
      See Also:

    • getViewName

      public String getViewName()
      When multiple target lookup views exists for the same data object class, the view name can be set to determine which one to use.

      When creating multiple lookup views for the same data object class, the view name can be specified for the different versions (for example 'simple' and 'advanced'). When multiple lookup views exist the view name must be sent with the data object class for the request. Note the view id can be alternatively used to uniquely identify the lookup view

      Returns:
      String name of lookup view

    • setViewName

      public void setViewName(String viewName)
      See Also:

    • isReturnByScript

      public boolean isReturnByScript()
      Indicates whether the lookup return should occur through script, or by refresing the page (making server request).

      For quickfinders that do not need any additional server side action, return through script can be much faster and prevents a page refresh.

      Returns:
      boolean true if the return should occur through script, false if not (default)

    • setReturnByScript

      public void setReturnByScript(boolean returnByScript)
      See Also:

    • getReadOnlyLookupFields

      public String getReadOnlyLookupFields()
      Comma delimited String of property names on the lookup view that should be read only.

      When requesting a lookup view, property names for fields that are rendered as search criteria can be marked as read-only. This is usually done when a lookup parameter for that property is sent in and the user should not be allowed to change the value

      Returns:
      property names (delimited by a comma) whose criteria fields should be read-only on the lookup view

    • setReadOnlyLookupFields

      public void setReadOnlyLookupFields(String readOnlyLookupFields)
      See Also:

    • getReferencesToRefresh

      public String getReferencesToRefresh()
      List of property names on the model that should be refreshed when the lookup returns.

      Note this is only relevant when the return by script option is not enabled (meaning the server will be invoked on the lookup return call)

      When a lookup return call is made (to return a result value) the controller refresh method will be invoked. If refresh properties are configured, a call to refresh those references from the database will be made. This is useful if the lookup returns a foreign key field and the related record is needed.

      Returns:
      list of property names to refresh

    • setReferencesToRefresh

      public void setReferencesToRefresh(String referencesToRefresh)
      See Also:

    • getFieldConversions

      public Map<String,String> getFieldConversions()
      Map that determines what properties from a result lookup row (if selected) will be returned to properties on the calling view.

      The purpose of using the lookup is to search for a particular value and return that value to the form being completed. In order for the lookup framework to return the field back to us, we must specify the name of the field on the data object class whose value we need, and the name of the field on the calling view. Furthermore, we can choose to have the lookup return additional fields that populate other form fields or informational properties (see ‘Field Queries and Informational Properties’). These pairs of fields are known as ‘field conversions’.

      The fieldConversions property is a Map. Each entry represents a field that will be returned back from the lookup, with the entry key being the field name on the data object class, and the entry value being the field name on the calling view. It is helpful to think of this as a from-to mapping. Pulling from the data object field (map key) to the calling view field (map value).

      Returns:
      mapping of lookup data object property names to view property names

    • setFieldConversions

      public void setFieldConversions(Map<String,String> fieldConversions)
      See Also:

    • getLookupParameters

      public Map<String,String> getLookupParameters()
      Map that determines what properties from a calling view will be sent to properties on that are rendered for the lookup view's search fields (they can be hidden).

      When invoking a lookup view, we can pre-populate search fields on the lookup view with data from the view that called the lookup. The user can then perform the search with these values, or (if edited is allowed or the fields are not hidden) change the passed in values. When the lookup is invoked, the values for the properties configured within the lookup parameters Map will be pulled and passed along as values for the lookup view properties

      Returns:
      mapping of calling view properties to lookup view search fields

    • setLookupParameters

      public void setLookupParameters(Map<String,String> lookupParameters)
      See Also:

    • getRenderReturnLink

      public Boolean getRenderReturnLink()
      Indicates whether the return links for lookup results should be rendered.

      A lookup view can be invoked to allow the user to select a value (or set of values) to return back to the calling view. For single value lookups this is done with a return link that is rendered for each row. This return link can be disabled by setting this property to false

      Returns:
      true if the return link should not be shown, false if it should be

    • setRenderReturnLink

      public void setRenderReturnLink(Boolean renderReturnLink)
      See Also:

    • getRenderResultActions

      public Boolean getRenderResultActions()
      Indicates whether the maintenance actions (or others) are rendered on the invoked lookup view.

      By default a lookup view will add an actions column for the result table that display maintenance links (in addition to a new link at the top of the page) if a maintenance action is available. Custom links can also be added to the action column as necessary. This flag can be set to true to suppress the rendering of the actions for the lookup call.

      Returns:
      true if actions should be rendered, false if not

    • setRenderResultActions

      public void setRenderResultActions(Boolean renderResultActions)
      See Also:

    • getAutoSearch

      public Boolean getAutoSearch()
      Indicates whether the search should be executed when first rendering the lookup view.

      By default the lookup view is rendered, the user enters search values and executes the results. This flag can be set to true to indicate the search should be performed before showing the screen to the user. This is generally used when search criteria is being passed in as well

      Returns:
      true if the search should be performed initially, false if not

    • setAutoSearch

      public void setAutoSearch(Boolean autoSearch)
      See Also:

    • getRenderLookupCriteria

      public Boolean getRenderLookupCriteria()
      Indicates whether the lookup criteria (search group) should be enabled on the invoked lookup view.

      Setting the this to false will not display the lookup criteria but only the results. Therefore this is only useful when setting getAutoSearch() to true and passing in criteria

      Returns:
      true if lookup criteria should be displayed, false if not

    • setRenderLookupCriteria

      public void setRenderLookupCriteria(Boolean renderLookupCriteria)
      See Also:

    • getRenderCriteriaActions

      public Boolean getRenderCriteriaActions()
      Indicates whether the criteria actions (footer) should be rendered on the invoked lookup view.
      Returns:
      boolean true if actions should be rendered (default), false if not

    • setRenderCriteriaActions

      public void setRenderCriteriaActions(Boolean renderCriteriaActions)
      See Also:

    • getHideCriteriaOnSearch

      public Boolean getHideCriteriaOnSearch()
      Indicates whether the lookup criteria should be hidden when a search is executed.
      Returns:
      boolean true if criteria should be hidden, false if not

    • setHideCriteriaOnSearch

      public void setHideCriteriaOnSearch(Boolean hideCriteriaOnSearch)
      See Also:

    • getRenderMaintenanceLinks

      public Boolean getRenderMaintenanceLinks()
      Indicates whether the maintenance action links should be rendered for the invoked lookup view.

      If a maintenance view exists for the data object associated with the lookup view, the framework will add links to initiate a new maintenance document. This flag can be used to disable the rendering of these links

      Note this serves similar purpose to getRenderResultActions() but the intent is to only remove the maintenance links in this situation, not the complete actions column

      Returns:
      true if maintenance links should be shown on the lookup view, false if not

    • setRenderMaintenanceLinks

      public void setRenderMaintenanceLinks(Boolean renderMaintenanceLinks)
      See Also:

    • getQuickfinderAction

      @ViewLifecycleRestriction(exclude="FINALIZE") public Action getQuickfinderAction()
      Action component that is used to rendered for the field for invoking the quickfinder action (bringing up the lookup).

      Through the action configuration the image (or link, button) rendered for the quickfinder can be modified. In addition to other action component settings

      Returns:
      Action instance rendered for quickfinder

    • setQuickfinderAction

      public void setQuickfinderAction(Action quickfinderAction)
      See Also:

    • getLookupDialogId

      public String getLookupDialogId()
      The id of the DialogGroup to use when the openInDialog property is true.

      The DialogGroup should only contain an iframe for its items. When not set, a default dialog will be used.

      Returns:
      the id of the dialog to use for this quickfinder

    • setLookupDialogId

      public void setLookupDialogId(String lookupDialogId)
      See Also:

    • isOpenInDialog

      public boolean isOpenInDialog()
      True if the quickfinder's lookup should be opened in a dialog; true is the default setting for the bean.
      Returns:
      true if the lookup should be opened in a dialog, false to open in a new window

    • setOpenInDialog

      public void setOpenInDialog(boolean openInDialog)
      See Also:

    • getMultipleValuesSelect

      public Boolean getMultipleValuesSelect()
      Indicates whether the invoked lookup view should allow multiple values to be selected and returned.
      Returns:
      true if multi-value lookup should be requested, false for normal lookup

    • setMultipleValuesSelect

      public void setMultipleValuesSelect(Boolean multipleValuesSelect)
      See Also:

    • getLookupCollectionName

      public String getLookupCollectionName()
      For the case of multi-value lookup, indicates the collection that should be populated with the return results.

      Note when the quickfinder is associated with a CollectionGroup, this property is set automatically from the collection name associated with the group

      Returns:
      collection name (must be full binding path)

    • setLookupCollectionName

      public void setLookupCollectionName(String lookupCollectionName)
      See Also:

    • getLookupCollectionId

      public String getLookupCollectionId()
      For the case of multi-value lookup, indicates the collection id that should be populated with the return results.

      Note when the quickfinder is associated with a CollectionGroup, this property is set automatically from the collection id associated with the group

      Returns:
      collection id

    • setLookupCollectionId

      public void setLookupCollectionId(String lookupCollectionId)
      See Also:

    • getAdditionalLookupParameters

      public Map<String,String> getAdditionalLookupParameters()
      The additional parameters that were passed to the quickFinder.
      Returns:
      additionalLookupParameters - map of additional lookup parameters

    • setAdditionalLookupParameters

      public void setAdditionalLookupParameters(Map<String,String> additionalLookupParameters)
      See Also:

    • getCallbackMethodToCall

      public String getCallbackMethodToCall()
      The name of the callback method to invoke in the view helper service that checks request parameters to indicate what view is being returned from.
      Returns:
      callbackMethodToCall - the name of the callback method

    • setCallbackMethodToCall

      public void setCallbackMethodToCall(String callbackMethodToCall)
      See Also:

    • getCallbackMethod

      public MethodInvokerConfig getCallbackMethod()
      The specific method invoker to use to invoke the callback method to call.
      Returns:
      callbackMethod - the method invoker

    • setCallbackMethod

      public void setCallbackMethod(MethodInvokerConfig callbackMethod)
      See Also:

    • getCallbackContext

      public Map<String,String> getCallbackContext()
      The context of parameters to be provided to the callback method to call.
      Returns:
      callbackContext - map of parameters

    • setCallbackContext

      public void setCallbackContext(Map<String,String> callbackContext)
      See Also: