Package com.github.bordertech.wcomponents

Class WSuggestions

  • All Implemented Interfaces:
    AjaxInternalTrigger, AjaxTarget, WComponent, WebComponent, Serializable
    public class WSuggestions
extends AbstractWComponent
implements AjaxInternalTrigger, AjaxTarget
    WSuggestions represents a device for providing suggested input for a text-like input field. The suggestions may be a static list, derived from a data url or acquired on the fly (via AJAX) based on user input into an associated input.

    WSuggestions has no effect unless it is associated with a text-like input control such as WTextField. If it is associated with a constrained input (such as WEmailField) then it is expected (but not enforced) that the suggestions would be in line with the associated field's constraints.

    It allows for client caching of frequently used lists via a data key or lists that can be produced via AJAX depending on the text entered in the related TextField.

    Suggestions provided via a lookup table are cached on the client and filtered on the client.

    To have a suggestion list dynamically updated via AJAX, do not use a lookup table, but manually set the options and set a refresh action via setRefreshAction(Action). The text entered by the user that triggered the refresh is provided by getAjaxFilter().

    Since:
    1.0.0
    Author:
    Jonathan Austin
    See Also:
    Serialized Form

    • Field Detail

      • AJAX_REFRESH_ACTION_COMMAND

        public static final String AJAX_REFRESH_ACTION_COMMAND
        AJAX refresh command.
        See Also:
        Constant Field Values

    • Constructor Detail

      • WSuggestions

        public WSuggestions()
        Create a WSuggestions.

      • WSuggestions

        public WSuggestions​(List<String> suggestions)
        Creates a WSuggestions with predefined suggestions.
        Parameters:
        suggestions - the list of suggestions.

      • WSuggestions

        public WSuggestions​(Object lookupTable)
        Creates a WSuggestions using a lookup table for the suggestions.
        Parameters:
        lookupTable - the lookup table identifier to obtain the list of suggestions.

    • Method Detail

      • handleRequest

        public void handleRequest​(Request request)
        Subclasses should override this method in order to provide specific request handling logic. For example, a text field may set its value to the value of a request parameter.
        Specified by:
        handleRequest in interface WComponent
        Overrides:
        handleRequest in class AbstractWComponent
        Parameters:
        request - the request being responded to.

      • doHandleAjaxRefresh

        protected void doHandleAjaxRefresh()
        Handle the AJAX refresh request.

      • getSuggestions

        public List<String> getSuggestions()
        Returns the complete list of suggestions available for selection for this user's session.
        Returns:
        the list of suggestions available for the given user's session.

      • getListCacheKey

        public String getListCacheKey()
        Retrieves the data list cache key for this component.
        Returns:
        the cache key if client-side caching is enabled, null otherwise.

      • setSuggestions

        public void setSuggestions​(List<String> suggestions)
        Set the complete list of suggestions available for selection for this user's session.
        Parameters:
        suggestions - the list of suggestions available to the user.

      • setLookupTable

        public void setLookupTable​(Object lookupTable)
        Set the lookupTable for this user's session.
        Parameters:
        lookupTable - the lookup table identifier to obtain the suggestions for the list.

      • getLookupTable

        public Object getLookupTable()
        Get the lookupTable for this user's session.
        Returns:
        the lookupTable for the suggestions

      • setRefreshAction

        public void setRefreshAction​(Action action)
        Parameters:
        action - the refresh action. Ignored if using a lookup table.

      • getRefreshAction

        public Action getRefreshAction()
        Returns:
        the refresh action. Ignored if using a lookup table.

      • setAjaxFilter

        protected void setAjaxFilter​(String filter)
        Parameters:
        filter - the refresh filter value passed on the AJAX request.

      • getAjaxFilter

        public String getAjaxFilter()
        Returns:
        the refresh filter value passed on the AJAX request. Ignored if using a lookup table.

      • setAutocomplete

        public void setAutocomplete​(WSuggestions.Autocomplete autocomplete)
        Parameters:
        autocomplete - The Autocomplete to set for this instance.

      • setMinRefresh

        public void setMinRefresh​(int min)
        The minimum number of characters entered before refreshing suggestions. A value of zero indicates to use the theme default, which is usually 3.
        Parameters:
        min - the minimum number of characters entered before refreshing suggestions.

      • getMinRefresh

        public int getMinRefresh()
        The minimum characters entered before triggering the refresh action.

        A value of zero indicates the theme default will be used (usually 3).

        Returns:
        the minimum characters entered before triggering the refresh action.

      • getComponentModel

        protected WSuggestions.SuggestionsModel getComponentModel()
        Returns the effective component model for this component. Subclass may override this method to narrow the return type to their specific model type.
        Overrides:
        getComponentModel in class AbstractWComponent
        Returns:
        the effective component model

      • getOrCreateComponentModel

        protected WSuggestions.SuggestionsModel getOrCreateComponentModel()
        Retrieves the model for this component so that it can be modified. If this method is called during request processing, and a session specific model does not yet exist, then a new model is created. Subclasses may override this method to narrow the return type to their specific model type.
        Overrides:
        getOrCreateComponentModel in class AbstractWComponent
        Returns:
        the model for this component