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

Class ComboboxItem

java.lang.Object
com.jbstrap.core.messagebus.MessageBus
com.jbstrap.ui.Component<E>
com.jbstrap.ui.components.form.FormItem<Object,ComboboxItem>
com.jbstrap.ui.components.form.items.ComboboxItem
All Implemented Interfaces:
Animatable<ComboboxItem>, CanDrop<ComboboxItem>, SupportAppend<ComboboxItem>, SupportHelpIcon<ComboboxItem>, SupportPlaceholder<ComboboxItem>, Draggable<ComboboxItem>, Fetchable<ComboboxItem>, Focusable<ComboboxItem>, HandleHotKey<ComboboxItem>, BasedOnDataDescriptor<ComboboxItem>, DifferentDataDisplayValue, DifferentMultiDataDisplayValue, Filterable<ComboboxItem>, MultiValueFormItem<ComboboxItem>
public class ComboboxItem extends FormItem<Object,ComboboxItem> implements Fetchable<ComboboxItem>, Filterable<ComboboxItem>, BasedOnDataDescriptor<ComboboxItem>, MultiValueFormItem<ComboboxItem>, DifferentDataDisplayValue, DifferentMultiDataDisplayValue, Animatable<ComboboxItem>, Focusable<ComboboxItem>, HandleHotKey<ComboboxItem>, CanDrop<ComboboxItem>, Draggable<ComboboxItem>, SupportAppend<ComboboxItem>, SupportPlaceholder<ComboboxItem>, SupportHelpIcon<ComboboxItem>

Combobox item

The component implements a combobox, forcing the user to only input value(s) from a predetermined set of values. The combobox values can be filtered by the user. The component supports sorting, and the set of values can be uploaded from a database as well.

The component can be in multi-select mode or single select.

The use of the component is recommended, when the selectable set of values is small. If there are too many selectable values, the use of the combobox might slow down. If using a lot of selectable values, the SelectorItem component is recommended instead, since it handles larger amounts of selectable values better.

This component is a form item, which means it can be placed, and it will be handled by the Form component. It can be used on its own, but in this case the developer must implement event and value handlers.

Supported events:

AnimationStart AnimationEnd, Focus FocusOut FocusIn LosesFocus KeyPress, KeyUp, KeyDown, Drop, DragStart, DragEnd HotKey

Since:
4.0
Author:
JBStrap
See Also:

  • Field Details

  • Constructor Details

    • ComboboxItem

      public ComboboxItem(String name)
      Creates an empty combobox input field with the specified name
      Parameters:
      name - The name of the combobox
      Throws:
      NullPointerException - If the specified name is null

    • ComboboxItem

      public ComboboxItem(String name, String label)
      Creates an empty combobox input field with the specified name and label
      Parameters:
      name - The name of the combobox
      label - The label of the combobox. If null, no label will be used
      Throws:
      NullPointerException - If the specified name is null

    • ComboboxItem

      public ComboboxItem(String name, String label, String language)
      Creates an empty combobox input field with the specified name, label and language
      Parameters:
      name - The name of the combobox
      label - The label of the combobox. If null, no label will be used
      language - The language code to be used by the form item. If not specified, or null the default language will be used. The framework's default language can be set by the JBStrapParamType.DEFAULT_LANGUAGE JBStrap parameter
      Throws:
      NullPointerException - If the specified name is null

    • ComboboxItem

      public ComboboxItem(String name, String label, Map<Object,Object> elements)
      Creates a combobox input field with the specified name and label. Fills up the combobox with the specified values.
      Parameters:
      name - The name of the combobox
      label - The label of the combobox. If null, no label will be used
      elements - The map containing the values to be added to the combobox. The map key is the combobox data value, and the value is the display value.
      Throws:
      NullPointerException - If the specified name is null
      IllegalArgumentException - If any of the specified map's key or value is null
      See Also:

    • ComboboxItem

      public ComboboxItem(String name, String label, String language, Map<Object,Object> elements)
      Creates a combobox input field with the specified name, label and language. Fills up the combobox with the specified values.
      Parameters:
      name - The name of the combobox
      label - The label of the combobox. If null, no label will be used
      language - The language code to be used by the form item. If not specified, or null the default language will be used. The framework's default language can be set by the JBStrapParamType.DEFAULT_LANGUAGE JBStrap parameter
      elements - The map containing the values to be added to the combobox. The map key is the combobox data value, and the value is the display value.
      Throws:
      NullPointerException - If the specified name is null
      IllegalArgumentException - If any of the specified map's key or value is null
      See Also:

    • ComboboxItem

      public ComboboxItem(DataDescriptorColumn column)

      Creates a combobox input field, based on the specified DataDescriptor column.

      The method creates and sets the Combobox item, based on the parameters of the specified column. The following parameters are used:

      • DataDescriptorColumn.getTitle - The field label is the one specified for the DataDescriptor column
      • DataDescriptorColumn.isNullable() - If the field gets a value of null, it is not designated as mandatory. If the field value is not set to null, it is designated as a mandatory field.
      • MetaParamName.MULTIPLE - If true, multiple values can be selected from the combobox values. Otherwise, only one can be selected.
      • MetaParamName.ALLOW_NULL - If true, the combobox will accept null values, regardless of the DataDescriptor Column's settings. Also allows the user to delete previous values from the combobox. If false, the user cannot use null values. If not specified, it will follow the DataDescriptor Column's settings.
      • MetaParamName.DATADESCRIPTOR - The name of the DataDescriptor, where the Combobox will read the values from. If specified, the component will be able to read the values automatically, and will fill itself out, after displaying.
      • MetaParamName.DATA_COLUMN - The name of the DataDescriptor column, that contains the combobox values. This is the value, that the combobox will have, when the user selects it from the set of values.
      • MetaParamName.DISPLAY_COLUMN - The name of the column that contains the combobox display values. If multiple columns are to be used, the name of the columns must be seperated by a "," character.
      • MetaParamName.DISPLAY_COLUMN_SEPARATOR - If multiple column values are to be used, their values will be separated by the character specified here. If not specified, the values will follow each other, with no character, or spacing between them.
      • MetaParamName.CRITERIA - This is where the filter criteria can be specified, in text form, which will be used during the DataDescriptor queries. If not specified, every value from the DataDescriptor will be used in the combobox.
      • MetaParamName.AUTO_FETCH - Sets if the auto fetch is enabled or not. If true, or not specified, the data fetch from the database will be automatic. If false the fetch won't happen, the program logic must implement it, by calling the fetchData() method.
      • MetaParamName.MULTI_VALUE_JOIN_TABLE - The name of the 1:N relation table in the database. Must be specified, if multi-select is enabled. Note: the name to be specified here is not a Domain class name, but the database table name, as it appears in the database.
      • MetaParamName.MULTI_VALUE_RECORD_COLUMN - This is where the saved record and record in the relation table must be connected. This is done by specifying the name of the column (as it appears in the table), where the primary key of the record is to be saved. If the record has a complex key, then the fields in the columns (that are from the table) that respond to the key, must be listed in the parameter. They must be separated by a "," character, in the order that the fields are in the complex key (that are connected to the record). They must be specified exactly as they appear in the database.
        If the table and the record is not to be connected with a primary key, the connection must be specified in the parameter, by specifying the name of the table field, then assigning a record attribute name, after a "=" character.
        (Example: column=recordAttributeName.) In this format, multiple connections can be specified, separated by a "," character.
      • MetaParamName.MULTI_VALUE_VALUE_COLUMN - This is where the column (containing the component's value) of the relation table must be specified. The component values are in the dataValue, in a list. If the component has multiple values selected, then multiple records will be in the relation table as well. If the component is modified, the records in the table will also be modified. That is, if the user deletes something from the component, the corresponding table record will be deleted as well.
      • MetaParamName.MULTI_VALUE_EXTEND_VALUES - If further data is to be stored in the relation table, it can be set using this parameter. Static values can be assigned to a relation table, by specifying the field name, then a "=" character, then the static value to be saved (Example: column=12 or column=ABC)
        If the value is not static, a saved record's attribute can be used, by specifying the field name, followed by a "=" character, followed by the name of an attribute in the record: columnName=${recordAttributeName}. Values specified like this will be saved in every relation table. Multiple values can be specified, following the above mentioned formats, by separating the values with a "," character.
      • MetaParamName.PLACEHOLDER - Placeholder text to be used in the input field. This text is displayed if no other text is entered into the input field.
      • MetaParamName.SIZE - The input field size is set from the value specified here. (Available values: SMALL, MEDIUM, LARGE)
      • MetaParamName.STATE - The input field state is set from these values. (Available values: DEFAULT, ERROR, WARNING, SUCCESS, INFO)
      • MetaParamName.DEFAULT_VALUE - The value specified here is set as the input field’s default value. The value must be specified based on the field’s data type, that is, it must be a text value.
      • MetaParamName.READ_ONLY - If true is set, the field is created as a read-only field. Otherwise the field is created as writable and the user is free to change its content.
      • MetaParamName.ENABLED - If false is set, the field is disabled. In all other cases the field is created as enabled.
      • MetaParamName.HELP - If this parameter is specified, an icon is displayed next to the input field and the text specified here appears as a help text if the user moves the mouse over it.
      • MetaParamName.HELP_ICON - If an icon name is specified in the parameter, also listed in the enum Icon, the default help text is changed to the 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 smaller the value is, the sooner the field gets focus. The greater the value is, the later the field gets focus. If the parameter is not specified, the field’s tab index receives the focus order value set for the field in the DataDescriptor. If that is also not specified, the focus order is based on which data value was entered earlier into the DataDescriptor.

      Parameters:
      column - The DataDescriptor column, that will be the basis of the component
      Throws:
      NullPointerException - If the specified column is null
      IllegalArgumentException - If the DATA_VALUE or DISPLAY_VALUE parameters are specified, but not the DATADESCRIPTOR parameter, or if the DATA_VALUE or the DISPLAY_VALUE column names do not match the column names in the specified DATADESCRIPTOR
      See Also:

    • ComboboxItem

      public ComboboxItem(DataDescriptorColumn column, String language)

      Creates a combobox input field, based on the specified DataDescriptor column and language.

      The method creates and sets the Combobox item, based on the parameters of the specified column. The following parameters are used:

      • DataDescriptorColumn.getTitle - The field label is the one specified for the DataDescriptor column
      • DataDescriptorColumn.isNullable() - If the field gets a value of null, it is not designated as mandatory. If the field value is not set to null, it is designated as a mandatory field.
      • MetaParamName.MULTIPLE - If true, multiple values can be selected from the combobox values. Otherwise, only one can be selected.
      • MetaParamName.ALLOW_NULL - If true, the combobox will accept null values, regardless of the DataDescriptor Column's settings. Also allows the user to delete previous values from the combobox. If false, the user cannot use null values. If not specified, it will follow the DataDescriptor Column's settings.
      • MetaParamName.DATADESCRIPTOR - The name of the DataDescriptor, where the Combobox will read the values from. If specified, the component will be able to read the values automatically, and will fill itself out, after displaying.
      • MetaParamName.DATA_COLUMN - The name of the DataDescriptor column, that contains the combobox values. This is the value, that the combobox will have, when the user selects it from the set of values.
      • MetaParamName.DISPLAY_COLUMN - The name of the column that contains the combobox display values. If multiple columns are to be used, the name of the columns must be seperated by a "," character.
      • MetaParamName.DISPLAY_COLUMN_SEPARATOR - If multiple column values are to be used, their values will be separated by the character specified here. If not specified, the values will follow each other, with no character, or spacing between them.
      • MetaParamName.CRITERIA - This is where the filter criteria can be specified, in text form, which will be used during the DataDescriptor queries. If not specified, every value from the DataDescriptor will be used in the combobox.
      • MetaParamName.AUTO_FETCH - Sets if the auto fetch is enabled or not. If true, or not specified, the data fetch from the database will be automatic. If false the fetch won't happen, the program logic must implement it, by calling the fetchData() method.
      • MetaParamName.MULTI_VALUE_JOIN_TABLE - The name of the 1:N relation table in the database. Must be specified, if multi-select is enabled. Note: the name to be specified here is not a Domain class name, but the database table name, as it appears in the database.
      • MetaParamName.MULTI_VALUE_RECORD_COLUMN - This is where the saved record and record in the relation table must be connected. This is done by specifying the name of the column (as it appears in the table), where the primary key of the record is to be saved. If the record has a complex key, then the fields in the columns (that are from the table) that respond to the key, must be listed in the parameter. They must be separated by a "," character, in the order that the fields are in the complex key (that are connected to the record). They must be specified exactly as they appear in the database.
        If the table and the record is not to be connected with a primary key, the connection must be specified in the parameter, by specifying the name of the table field, then assigning a record attribute name, after a "=" character.
        (Example: column=recordAttributeName.) In this format, multiple connections can be specified, separated by a "," character.
      • MetaParamName.MULTI_VALUE_VALUE_COLUMN - This is where the column (containing the component's value) of the relation table must be specified. The component values are in the dataValue, in a list. If the component has multiple values selected, then multiple records will be in the relation table as well. If the component is modified, the records in the table will also be modified. That is, if the user deletes something from the component, the corresponding table record will be deleted as well.
      • MetaParamName.MULTI_VALUE_EXTEND_VALUES - If further data is to be stored in the relation table, it can be set using this parameter. Static values can be assigned to a relation table, by specifing the field name, then a "=" character, then the static value to be saved (Example: column=12 or column=ABC)
        If the value is not static, a saved record's attribute can be used, by specifying the field name, followed by a "=" character, followed by the name of an attribute in the record: columnName=${recordAttributeName}. Values specified like this will be saved in every relation table. Multiple values can be specified, following the above mentioned formats, by separating the values with a "," character.
      • MetaParamName.PLACEHOLDER - Placeholder text to be used in the input field. This text is displayed if no other text is entered into the input field.
      • MetaParamName.SIZE - The input field size is set from the value specified here. (Available values: SMALL, MEDIUM, LARGE)
      • MetaParamName.STATE - The input field state is set from these values. (Available values: DEFAULT, ERROR, WARNING, SUCCESS, INFO)
      • MetaParamName.DEFAULT_VALUE - The value specified here is set as the input field’s default value. The value must be specified based on the field’s data type, that is, it must be a text value.
      • MetaParamName.READ_ONLY - If true is set, the field is created as a read-only field. Otherwise the field is created as writable and the user is free to change its content.
      • MetaParamName.ENABLED - If false is set, the field is disabled. In all other cases the field is created as enabled.
      • MetaParamName.HELP - If this parameter is specified, an icon is displayed next to the input field and the text specified here appears as a help text if the user moves the mouse over it.
      • MetaParamName.HELP_ICON - If an icon name is specified in the parameter, also listed in the enum Icon, the default help text is changed to the 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 smaller the value is, the sooner the field gets focus. The greater the value is, the later the field gets focus. If the parameter is not specified, the field’s tab index receives the focus order value set for the field in the DataDescriptor. If that is also not specified, the focus order is based on which data value was entered earlier into the DataDescriptor.

      Parameters:
      column - The DataDescriptor column, that will be the basis of the component
      language - The language code to be used by the form item. If not specified, or null the default language will be used. The framework's default language can be set by the JBStrapParamType.DEFAULT_LANGUAGE JBStrap parameter
      Throws:
      NullPointerException - If the specified column is null
      IllegalArgumentException - If the DATA_VALUE or DISPLAY_VALUE parameters are specified, but not the DATADESCRIPTOR parameter, or if the DATA_VALUE or the DISPLAY_VALUE column names do not match the column names in the specified DATADESCRIPTOR
      See Also:

  • Method Details

    • setJoinTableName

      public final ComboboxItem setJoinTableName(String joinTableName)
      If the user can select multiple values in the combobox, those values will be saved to a separate relation table. This table can be specified with this method. If the user can only select one value, this setting is ignored.
      Specified by:
      setJoinTableName in interface MultiValueFormItem<ComboboxItem>
      Parameters:
      joinTableName - The name of the table, that is in a 1:N relation with the database. The name must be exactly the same, as it appears in the database
      Returns:
      The combobox component

    • getJoinTableName

      public final String getJoinTableName()
      Gets the name of the relation table, that is used, when the user can select multiple values in the combobox
      Specified by:
      getJoinTableName in interface MultiValueFormItem<ComboboxItem>
      Returns:
      The name of the table with the 1:N relation, or null if not specified

    • setRecordColumnName

      public final ComboboxItem setRecordColumnName(String recordColumnName)

      This is where the connection of the saved record and the record in the table can be set.

      This is done by specifying the name of the relation table column, where the record's primary key is to be saved. If the record has a complex key, then every column field that is in the key must be listed from the relation table, separated with a "," character, in the order the fields are in the record's complex key. They must be specified exactly like they are in the database.
      If the table and the record is not to be connected with a primary key, the connection must be specified in the parameter, by specifying the name of the table field, then assigning a record attribute name, after a "=" character.
      (Example: column=recordAttributeName.) In this format, mutliple connections can be specified, separated by a "," character.