Package com.jbstrap.ui.components.form.items.selectoritem

Class SelectorItem

java.lang.Object
com.jbstrap.core.messagebus.MessageBus
com.jbstrap.ui.Component<E>
com.jbstrap.ui.components.form.FormItem<Object,SelectorItem>
com.jbstrap.ui.components.form.items.selectoritem.SelectorItem
All Implemented Interfaces:
Animatable<SelectorItem>, CanDrop<SelectorItem>, Clickable<SelectorItem>, SupportHelpIcon<SelectorItem>, SupportPlaceholder<SelectorItem>, Draggable<SelectorItem>, Focusable<SelectorItem>, HandleHotKey<SelectorItem>, HandleMouseEvents<SelectorItem>, DifferentDataDisplayValue, Touchable<SelectorItem>
public class SelectorItem extends FormItem<Object,SelectorItem> implements Animatable<SelectorItem>, Focusable<SelectorItem>, Clickable<SelectorItem>, HandleMouseEvents<SelectorItem>, Touchable<SelectorItem>, HandleHotKey<SelectorItem>, CanDrop<SelectorItem>, Draggable<SelectorItem>, DifferentDataDisplayValue, SupportPlaceholder<SelectorItem>, SupportHelpIcon<SelectorItem>

Selector item

With the use of this component, a value from a set of values can be selected. The component is similar to a ComboBoxItem, but its appearance and operation differ from it. The component is for handling large sets of values, since the selectable values do not get placed with the component on the client.

If a selector item component is displayed, a non-writable input field and a button with a magnifying glass icon will be displayed. If the user click on either of those, a window will appear. The window can be customized and implemented by the developer, or it can be the default selector window, in which a filterable list will be displayed. If the default one is used, the user can select a value from this filterable list. The list uses a lazy fetch implementation, so not every value will be used simultaneously, only a small fraction will be used. If the user goes to the bottom of the list, a new chunk of data will be queried automatically.

If the user double-clicks on a value, or selects one and presses the OK button, the value will be placed in the input field, and the component will register that value.

The JBStrap framework also allows the implementation of a custom window. The display and operation of the window must be implemented, by creating a class that extends from the SelectorWindow class. The SelectorWindow class requires the implementation of the methods that are responsible for the display and the operation of the selector window. Any other method can also be implemented and any component can be used (like for displaying the set of values) during the implementation. For more information, see the SelectorWindow class description.

Information about the default SelectorWindow can be found in the DefaultValueSelector class description.

Supported Events:

AnimationStart AnimationEnd, Focus FocusOut FocusIn LosesFocus Click, DoubleClick, MouseDown, MouseDown, MouseLeave, MouseMove, MouseOver, MouseOut, MouseUp, Wheel, TouchCancel, TouchEnd, TouchMove, TouchStart, Drop, DragStart, DragEnd HotKey

Since:
4.0
Author:
JBStrap
See Also:

  • Field Details

  • Constructor Details

    • SelectorItem

      public SelectorItem(String name, String label)
      Creates a selector item with the specified name and label. It will use the default selector window.
      Parameters:
      name - The name of the selector item
      label - The label of the selector item. If null, no label will be used
      Throws:
      NullPointerException - If the name is null

    • SelectorItem

      public SelectorItem(String name, String label, Class<? extends SelectorWindow> selectorClass)
      Creates a selector item with the specified name and label. It will use a custom selector window that needs to be implemented.
      Parameters:
      name - The name of the selector item
      label - The label of the selector item. If null, no label will be used
      selectorClass - The class containing the custom selector window implementation. If null, the default selector window will be used.
      Throws:
      NullPointerException - If the name is null

    • SelectorItem

      public SelectorItem(String name, String label, String language, Class<? extends SelectorWindow> selectorClass)
      Creates a selector item with the specified name, label and language code. It will use a custom selector window that needs to be implemented.
      Parameters:
      name - The name of the selector item
      label - The label of the selector item. If null, no label will be used
      language - The language code, that the form item will use. If not specified, or null, the framework will use the default language. The default language can be set with the JBStrapParamType.DEFAULT_LANGUAGE JBStrap parameter.
      selectorClass - The class containing the custom selector window implementation. If null, the default selector window will be used.
      Throws:
      NullPointerException - If the name null

    • SelectorItem

      public SelectorItem(DataDescriptorColumn column)

      Creates a selector item based on the specified DataDescriptorColumn.

      The method creates and sets the selector item component based on the specified column. The following parameters from the DataDescriptor column are used:

      • DataDescriptorColumn.getTitle - The title set in the DataDescriptor column will be used by the input field as its label.
      • DataDescriptorColumn.isNullable() - If the field can a null value, the field will be marked as not mandatory. If it cannot have a null value, the field will be marked as mandatory.
      • MetaParamName.SELECTOR_CLASS - The name of the class, that contains the custom selector window implementation. This class must extend from the SelectorWindow class. If not specified, the default selector window will be used.
      • MetaParamName.DATADESCRIPTOR - The name of the DataDescriptor, that contains the set of values that will be used by the form item. If specified, the form item will be able to automatically read and use the data, and save it to the database.
      • MetaParamName.DATA_COLUMN - The name of the DataDescriptor column, that contains the set of values, used by the form item. These values are the ones, that the form item can use, and the user can pick from these values.
      • MetaParamName.DISPLAY_COLUMN - The name of the column that contains the display values. If multiple values need to be displayed, multiple names must be specified here, seperated by a "," character. This is the value that the user will see when selecting a value.
      • MetaParamName.DISPLAY_COLUMN_SEPARATOR - If multiple display column values are to be used, then the character specified here will be used as a separator character, that will seperate the display column values. If not specified, they will follow each other without a separator.
      • MetaParamName.CRITERIA - The filter criteria can be specified here, in a text format, that will be applied during the query of the values from the DataDescriptor. If not specified, every value from the DataDescriptor will be used to fill up the form item.
      • MetaParamName.SELECTOR_FILTER_TYPE - The default filter type can be specified here. This will be applied to the default selector window. The usable filter types are:
        • "none" - No filter will be displayed
        • "adaptiveFilter" - A AdaptiveFilter will be displayed within the grid.
        • "simpleFilter" - A SimpleFilter will be displayed above the grid. The user can then filter the values by a column.
        • "advancedFilter" - A AdvancedFilter will be displayed above the grid, in which the user can input multiple columns (an advanced filter)
        • "textFilter" - A TextFilter will be displayed above the grid, with which the user can input text, that will filter the text value columns.
        • "custom" - In this case no custom filter implementation is supported
      • MetaParamName.PLACEHOLDER - This text will be used as a placeholder.
      • MetaParamName.SIZE - The value specified here defines the size of the input field. (Applicable values: SMALL, MEDIUM, LARGE)
      • MetaParamName.STATE - The value specified here defines the state of the input field. (Applicable values: DEFAULT, ERROR, WARNING, SUCCESS, INFO)
      • MetaParamName.DEFAULT_VALUE - The value specified here defines the field's default value. The value must have the type of field, in this case, it must be a boolean value.
      • MetaParamName.READ_ONLY - If true, the field will be read only. Otherwise, the field can have its contents modified by the user.
      • MetaParamName.ENABLED - If false, the field will be disabled (it will be created in an unusable state.) Otherwise, the field will be enabled when created.
      • MetaParamName.HELP - If the parameter is specified, an icon will be displayed next to the field. If the user moves over the icon, the text specified here will be displayed, as a help text.
      • MetaParamName.HELP_ICON - If the icon name is specified (from the Icon enum), then this icon will replace the default "?" icon.
      • MetaParamName.DESCRIPTION - The text specified here will appear below the field, in a smaller, italic font.
      • MetaParamName.TAB_INDEX - The value specified here determines the order of the input focus (when the user presses the Tab key). The order goes in ascending order. If not specified, the component will use the order value from the DataDescriptor. If that not specified either, the order in which it was placed in the DataDescriptor will be used.

      Parameters:
      column - The DataDescriptor column, that will be used as a basis for the form item.
      Throws:
      NullPointerException - If the specified DataDescriptor column is null, or if the DATADESCRIPTOR parameter is not specified, or if the specified DataDescriptor cannot be found in the application
      IllegalArgumentException - If the class in the SELECTOR_CLASS parameter does not extend from the SelectorWindow class, or is not found within the application, or the filter specified in the SELECTOR_FILTER_TYPE parameter is invalid
      See Also:

    • SelectorItem

      public SelectorItem(DataDescriptorColumn column, String language)

      Creates a selector item based on the specified DataDescriptorColumn and using the specified language code.

      The method creates and sets the selector item component based on the specified column. The following parameters from the DataDescriptor column are used:

      • DataDescriptorColumn.getTitle - The title set in the DataDescriptor column will be used by the input field as its label.
      • DataDescriptorColumn.isNullable() - If the field can a null value, the field will be marked as not mandatory. If it cannot have a null value, the field will be marked as mandatory.
      • MetaParamName.SELECTOR_CLASS - The name of the class, that contains the custom selector window implementation. This class must extend from the SelectorWindow class. If not specified, the default selector window will be used.
      • MetaParamName.DATADESCRIPTOR - The name of the DataDescriptor, that contains the set of values that will be used by the form item. If specified, the form item will be able to automatically read and use the data, and save it to the database.
      • MetaParamName.DATA_COLUMN - The name of the DataDescriptor column, that contains the set of values, used by the form item. These values are the ones, that the form item can use, and the user can pick from these values.
      • MetaParamName.DISPLAY_COLUMN - The name of the column that contains the display values. If multiple values need to be displayed, multiple names must be specified here, seperated by a "," character. This is the value that the user will see when selecting a value.
      • MetaParamName.DISPLAY_COLUMN_SEPARATOR - If multiple display column values are to be used, then the character specified here will be used as a separator character, that will seperate the display column values. If not specified, they will follow each other without a separator.
      • MetaParamName.CRITERIA - The filter criteria can be specified here, in a text format, that will be applied during the query of the values from the DataDescriptor. If not specified, every value from the DataDescriptor will be used to fill up the form item.
      • MetaParamName.SELECTOR_FILTER_TYPE - The default filter type can be specified here. This will be applied to the default selector window. The usable filter types are:
        • "none" - No filter will be displayed
        • "adaptiveFilter" - A AdaptiveFilter will be displayed within the grid.
        • "simpleFilter" - A SimpleFilter will be displayed above the grid. The user can then filter the values by a column.
        • "advancedFilter" - A AdvancedFilter will be displayed above the grid, in which the user can input multiple columns (an advanced filter)
        • "textFilter" - A TextFilter will be displayed above the grid, with which the user can input text, that will filter the text value columns.
        • "custom" - In this case no custom filter implementation is supported
      • MetaParamName.PLACEHOLDER - This text will be used as a placeholder.
      • MetaParamName.SIZE - The value specified here defines the size of the input field. (Applicable values: SMALL, MEDIUM, LARGE)
      • MetaParamName.STATE - The value specified here defines the state of the input field. (Applicable values: DEFAULT, ERROR, WARNING, SUCCESS, INFO)
      • MetaParamName.DEFAULT_VALUE - The value specified here defines the field's default value. The value must have the type of field, in this case, it must be a boolean value.
      • MetaParamName.READ_ONLY - If true, the field will be read only. Otherwise, the field can have its contents modified by the user.
      • MetaParamName.ENABLED - If false, the field will be disabled (it will be created in an unusable state.) Otherwise, the field will be enabled when created.
      • MetaParamName.HELP - If the parameter is specified, an icon will be displayed next to the field. If the user moves over the icon, the text specified here will be displayed, as a help text.
      • MetaParamName.HELP_ICON - If the icon name is specified (from the Icon enum), then this icon will replace the default "?" icon.
      • MetaParamName.DESCRIPTION - The text specified here will appear below the field, in a smaller, italic font.
      • MetaParamName.TAB_INDEX - The value specified here determines the order of the input focus (when the user presses the Tab key). The order goes in ascending order. If not specified, the component will use the order value from the DataDescriptor. If that not specified either, the order in which it was placed in the DataDescriptor will be used.
      • MetaParamName.SHOW_BUTTONS - This parameter determines if the buttons are shown on the component. By default, the buttons are not shown. If true, the buttons will be displayed in the component's input field

      Parameters:
      column - The DataDescriptor column, that will be used as a basis for the form item.
      language - The language code, that the form item will use. If not specified, or null, the framework will use the default language. The default language can be set with the JBStrapParamType.DEFAULT_LANGUAGE JBStrap parameter.
      Throws:
      NullPointerException - If the specified DataDescriptor column is null, or if the DATADESCRIPTOR parameter is not specified, or if the specified DataDescriptor cannot be found in the application
      IllegalArgumentException - If the class in the SELECTOR_CLASS parameter does not extend from the SelectorWindow class, or is not found within the application, or the filter specified in the SELECTOR_FILTER_TYPE parameter is invalid
      See Also:

  • Method Details

    • setDataDescriptor

      public final SelectorItem setDataDescriptor(DataDescriptor dataDescriptor)
      Sets the DataDescriptor of the selector item
      Parameters:
      dataDescriptor - The instance of the DataDescriptor
      Returns:
      The selector item component
      Throws:
      NullPointerException - If the DataDescriptor was specified as null

    • getDataDescriptor

      public final DataDescriptor getDataDescriptor()
      Gets the DataDescriptor of the selector item
      Returns:
      The DataDescriptor instance, that is used by the selector item, and supplies the set of values, or null if the selector item has no DataDescriptor specified.

    • setDataColumn

      public final SelectorItem setDataColumn(String dataColumnName)
      Sets the name of the DataDescriptor column that contains the selector item values. This column must exist in the DataDescriptor, that was previously specified.
      Parameters:
      dataColumnName - The name of the DataDescriptor column that contains the selector item values
      Returns:
      The selector item component

    • getDataColumnName

      public final String getDataColumnName()
      Gets the name of the DataDescriptor column that contains the selector item values.
      Returns:
      The name of the column, or null if not specified

    • setDisplayColumn

      public final SelectorItem setDisplayColumn(String dispalyColumnName)
      Sets the name of the DataDescriptor column that contains the selector item display values. This column must exist in the DataDescriptor, that was previously specified.
      Parameters:
      dispalyColumnName - The name of the DataDescriptor column that contains the selector item display values. These are displayed in the input field when the user selects a value
      Returns:
      The selector item component

    • setDisplayColumns

      public final SelectorItem setDisplayColumns(String... displayColumns)
      Sets the name of the DataDescriptor columns that contain the selector item display values. These columns must exist in the DataDescriptor, that was previously specified.
      Parameters:
      displayColumns - The name of the DataDescriptor columns that contain the selector item display values. These are displayed in the input field when the user selects a value
      Returns:
      The selector item component

    • getDisplayColumnNames

      public List<String> getDisplayColumnNames()
      Gets the name of the DataDescriptor columns that contain the selector item display values.
      Returns:
      A list containing the name of the columns, or an empty list if there are none

    • setDisplayColumnSeparator

      public final SelectorItem setDisplayColumnSeparator(String separator)
      Sets the separator text, that separates the display values. By default, it's a regular whitespace.
      Parameters:
      separator - The separator text. If null, the values will not be separated
      Returns:
      The selector item component

    • getDisplayColumnSeparator

      public String getDisplayColumnSeparator()
      Gets the separator text, that separates the display values.
      Returns:
      The separator text or null if none were specified

    • setDefaultFilterCriteria

      public final SelectorItem setDefaultFilterCriteria(Criteria criteria)
      Sets the default filter criteria, that will be applied to the values. The user cannot remove or overwrite this criteria.
      Parameters:
      criteria - The default filter criteria, that will be applied to the values. The user cannot remove or overwrite this criteria.
      Returns:
      The selector item component

    • getDefaultFilterCriteria

      public final Criteria getDefaultFilterCriteria()
      Gets the default filter criteria, that are applied to the values.
      Returns:
      The default filter criteria or null if none was specified

    • drawEditor

      public void drawEditor(StringWriter writer)
      Description copied from class: FormItem

      Draws the editor component.

      You do not need to use this method during development, but all components extending the form item must implement it. Use the method to generate the input field’s HTML code. This code is then inserted into the corresponding DOM code when drawing the form item.

      Specified by:
      drawEditor in class FormItem<Object,SelectorItem>
      Parameters:
      writer - The HTML string writer class instance; write here the HTML code for the input field

    • setDefaultValue

      public SelectorItem setDefaultValue(Object defaultValue)
      Sets the default value of the selector item
      Specified by:
      setDefaultValue in class FormItem<Object,SelectorItem>
      Parameters:
      defaultValue - The default value of the selector item
      Returns:
      Form item component

    • setValue

      public SelectorItem setValue(Object value)
      Sets the current value of the selector item
      Overrides:
      setValue in class FormItem<Object,SelectorItem>
      Parameters:
      value - The current value of the selector item
      Returns:
      Form item component

    • setReadOnly

      public final SelectorItem setReadOnly(boolean readOnly)
      Sets the selector item to be read only. By default, this is disabled, the user can modify the selector item's value
      Overrides:
      setReadOnly in class FormItem<Object,SelectorItem>
      Parameters:
      readOnly - If true, the selector item will be read only, and the user won't be able to modify the value
      Returns:
      The selector item component

    • setEnabled

      public SelectorItem setEnabled(boolean enabled)
      Description copied from class: Component
      Sets the component to be enabled. Defaults to true
      Overrides:
      setEnabled in class FormItem<Object,SelectorItem>
      Parameters:
      enabled - true, the component is enabled, otherwise it's disabled
      Returns:
      The component

    • isReadOnly

      public boolean isReadOnly()
      Description copied from class: FormItem
      Checks if the form item is in read-only mode.
      Overrides:
      isReadOnly in class FormItem<Object,SelectorItem>
      Returns:
      If true is set, the form item is in read-only mode and the user cannot modify its content. Otherwise false.

    • afterDraw

      public void afterDraw()
      Description copied from class: Component
      The operations to be executed after the drawing of the component

      By default, this is an empty method. It has to be overwritten on a component or page if additional operations have to be executed after the drawing process. One such operation is data retrieval, which shouldn't run in constructors so that the user could see results of an operation or navigation process.

      Overrides:
      afterDraw in class FormItem<Object,SelectorItem>

    • triggerChange

      protected void triggerChange()

    • getDisplayValue

      public String getDisplayValue()
      Gets the selector item's current display value .
      Specified by:
      getDisplayValue in interface DifferentDataDisplayValue
      Returns:
      The selector item's current display value, or null, if the value is null, or if it has no display value

    • getOriginalDisplayValue

      public String getOriginalDisplayValue()
      Gets the selector item's original display value.
      Specified by:
      getOriginalDisplayValue in interface DifferentDataDisplayValue
      Returns:
      The selector item's original display value, or null, if the value is null, or if it has no original display value

    • setSearchButtonVisible

      public SelectorItem setSearchButtonVisible(boolean visible)
      Sets if the search button should appear on the right side of the input field. By default, it does not appear.
      Parameters:
      visible - If true, the search button will be displayed. Otherwise, it will not
      Returns:
      The selector item component

    • setState

      public SelectorItem setState(FormItemState formItemState)
      Description copied from class: FormItem
      Sets the form element state. By default, the form element is displayed in the FormItemState.DEFAULT state.
      Overrides:
      setState in class FormItem<Object,SelectorItem>
      Parameters:
      formItemState - Form item state Available states are listed in the enum FormItemState.
      Returns:
      Form element component

    • isSearchButtonVisible

      public boolean isSearchButtonVisible()
      Determines if the search button is displayed on the right side of the input field.
      Returns:
      If true, the search button will be displayed. Otherwise, it will not