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

Class RadioButtonItem

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

Radio button item

With the use of this component, a radio button can be placed on the form. The radio button is used to select only one value from a set of values. Each value has its own radio button. By default, these are displayed under each other, but they can be set to appear next to each other.

The use of the component is only recommended, if the set of values is small, so the radio buttons don't expand the page too much.

The component reads the values automatically from the database, if the related parameters are set, or the values can be loaded with the use of a custom code. The component is a form item, so it can be placed on, and will be handled by the Form component. The component can be used on its own, but then the developer must implement event and value handlers.

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:

  • Constructor Details

    • RadioButtonItem

      public RadioButtonItem(String name, String label)
      Creates a radio button with the specified name and label.
      Parameters:
      name - Radio button name
      label - Radio button label If null is set, the field has no label.
      Throws:
      NullPointerException - Thrown if the specified name for the field is null

    • RadioButtonItem

      public RadioButtonItem(String name, String label, String language)
      Creates a radio button with the specified name, label and language code.
      Parameters:
      name - Radio button name
      label - Radio button label If null is set, the field has no label.
      language - The language code used to create the field If not specified or set to null, the field is created using the default language of the framework. The default language of the framework is set via the JBStrap parameter JBStrapParamType.DEFAULT_LANGUAGE.
      Throws:
      NullPointerException - Thrown if the specified name for the field is null

    • RadioButtonItem

      public RadioButtonItem(String name, String label, Map<Object,Object> elements)
      Creates a radio button with the specified name and label and populates a combobox with the specified value set.
      Parameters:
      name - Radio button name
      label - Radio button label If null is set, the field has no label.
      elements - The map containing the value set for the combobox The map key is equal to the combobox data value and the map value is the displayed value.
      Throws:
      NullPointerException - Thrown if the specified name for the field is null
      IllegalArgumentException - Thrown if any of the keys or values of the specified value set is null
      See Also:

    • RadioButtonItem

      public RadioButtonItem(String name, String label, String language, Map<Object,Object> elements)
      Creates a radio button with the specified name, label and language code and populates a combobox with the specified value set.
      Parameters:
      name - Radio button name
      label - Radio button label If null is set, the field has no label.
      language - The language code used to create the field If not specified or set to null, the field is created using the default language of the framework. The default language of the framework is set via the JBStrap parameter JBStrapParamType.DEFAULT_LANGUAGE.
      elements - The map containing the value set for the combobox The map key is equal to the combobox data value and the map value is the displayed value.
      Throws:
      NullPointerException - Thrown if the specified name for the field is null
      IllegalArgumentException - Thrown if any of the keys or values of the specified value set is null
      See Also:

    • RadioButtonItem

      public RadioButtonItem(DataDescriptorColumn column)

      Creates a radio button from the specified DataDescriptor column.

      The method creates and sets the radio button from the parameter-specified DataDescriptor column. The following parameters of the DataDescriptor column 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.DATADESCRIPTOR - The name of the DataDescriptor from where the combobox retrieves its value set If the parameter is specified, the value set of the combobox is automatically retrieved from the database and populated with data upon being displayed
      • MetaParamName.DATA_COLUMN - The name of the DataDescriptor column from where the combobox retrieves its value set The data value of the combobox is the value to be taken by the combobox if the user selects the specified item from the value set.
      • MetaParamName.DISPLAY_COLUMN - The name of the column from where the combobox retrieves its displayed values If multiple columns are displayed in the combobox, all column names must be specified here, separated by a ',’ character. A displayed value is a value shown on the interface if an item is selected.
      • MetaParamName.DISPLAY_COLUMN_SEPARATOR - If multiple column values are shown in the combobox component, this parameter specifies the column separator If no column separator is specified, values are shown in a consecutive order.
      • MetaParamName.CRITERIA - This parameter specifies the filter criterion text that we would like to use to filter the DataDescriptor values in the query. If no filter criterion is specified, all data values in the DataDescriptor are added to the combobox as a value set.
      • MetaParamName.AUTO_FETCH - Sets if the combobox should automatically get value set items from the database If not specified, or provided as true, the query is performed automatically. If false is set, the query is not performed, data retrieval must be implemented from code by calling the method ComboboxItem.fetchData().
      • MetaParamName.PLACEHOLDER - Placeholder text to be used in the radio button component. 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, in this case 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 contents.
      • MetaParamName.ENABLED - If false is specified, the field is created as disabled. Otherwise, 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 icon 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 value of the field’s position in a sequence as specified 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 - DataDescriptor column used to create the field
      Throws:
      NullPointerException - Thrown if the parameter’s specified column is set to null
      IllegalArgumentException - Thrown if the parameters DATA_VALUE or DISPLAY_VALUE are specified, but DATADESCRIPTOR is not specified or there are no columns in the DataDescriptor identified as DATADESCRIPTOR by the names specified in the parameters DATA_VALUE or DISPLAY_VALUE.
      See Also:

    • RadioButtonItem

      public RadioButtonItem(DataDescriptorColumn column, String language)

      Creates a radio button using the specified DataDescriptor column and language code.

      The method creates and sets the radio button from the parameter-specified DataDescriptor column. The following parameters of the DataDescriptor column 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.DATADESCRIPTOR - The name of the DataDescriptor from where the combobox retrieves its value set If the parameter is specified, the value set of the combobox is automatically retrieved from the database and populated with data upon being displayed
      • MetaParamName.DATA_COLUMN - The name of the DataDescriptor column from where the combobox retrieves its value set The data value of the combobox is the value to be taken by the combobox if the user selects the specified item from the value set.
      • MetaParamName.DISPLAY_COLUMN - The name of the column from where the combobox retrieves its displayed values If multiple columns are displayed in the combobox, all column names must be specified here, separated by a ',’ character. A displayed value is a value shown on the interface if an item is selected.
      • MetaParamName.DISPLAY_COLUMN_SEPARATOR - If multiple column values are shown in the combobox component, this parameter specifies the column separator If no column separator is specified, values are shown in a consecutive order.
      • MetaParamName.CRITERIA - This parameter specifies the filter criterion text that we would like to use to filter the DataDescriptor values in the query. If no filter criterion is specified, all data values in the DataDescriptor are added to the combobox as a value set.
      • MetaParamName.AUTO_FETCH - Sets if the combobox should automatically get value set items from the database If not specified, or provided as true, the query is performed automatically. If false is set, the query is not performed, data retrieval must be implemented from code by calling the method ComboboxItem.fetchData().
      • MetaParamName.PLACEHOLDER - Placeholder text to be used in the radio button component. 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, in this case 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 contents.
      • MetaParamName.ENABLED - If false is specified, the field is created as disabled. Otherwise, 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 icon 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 value of the field’s position in a sequence as specified in the data source. If that is also not specified, the focus order is based on which data value was entered earlier into the DataDescriptor.

      Parameters:
      column - DataDescriptor column used to create the field
      language - The language code used to create the field. If not specified or set to null, the field is created using the default language of the framework. The default language of the framework is set via the JBStrap parameter JBStrapParamType.DEFAULT_LANGUAGE.
      Throws:
      NullPointerException - Thrown if the parameter’s specified column is set to null
      IllegalArgumentException - Thrown if the parameters DATA_VALUE or DISPLAY_VALUE are specified, but DATADESCRIPTOR is not specified or there are no columns in the DataDescriptor identified as DATADESCRIPTOR by the names specified in the parameters DATA_VALUE or DISPLAY_VALUE.
      See Also:

  • Method Details

    • fetchData

      public final RadioButtonItem fetchData(Criteria criteria)
      Gets value set data from the database, fulfilling the specified filter criterion.
      Parameters:
      criteria - The filter criterion used to query data from the database
      Returns:
      Radio button component

    • addElement

      public final RadioButtonItem addElement(Object dataValue, Object displayValue)
      Adds an item to the value set.
      Parameters:
      dataValue - The component takes this value if the user selects the item
      displayValue - The value denoting an item on the interface
      Returns:
      Radio button component
      Throws:
      IllegalArgumentException - Thrown if the specified data value or displayed value is null

    • addElements

      public final RadioButtonItem addElements(Map<Object,Object> data)
      Adds multiple items to the value set.
      Parameters:
      data - A map of values to be added to the value set The map key is a data value and the map value is the displayed value. A data value is the component’s value if the user selects an item. The displayed value is a value shown on the interface.
      Returns:
      Radio button component
      Throws:
      IllegalArgumentException - Thrown if the data value or displayed value of any specified item is null

    • removeElement

      public final RadioButtonItem removeElement(Object dataValue)
      Removes an item from the value set if the data value is specified.
      Parameters:
      dataValue - The data value we want to remove from the value set If you specify a value that is not included in the value set, the method does nothing.
      Returns:
      Radio button component

    • clear

      public final RadioButtonItem clear()
      Clears the component’s value set and removes all value set items.
      Returns:
      Radio button component

    • setDataDescriptor

      public final RadioButtonItem setDataDescriptor(DataDescriptor dataDescriptor)
      Sets the DataDescriptor for the value set.
      Specified by:
      setDataDescriptor in interface BasedOnDataDescriptor<RadioButtonItem>
      Parameters:
      dataDescriptor - The DataDescriptor instance from where the component retrieves its value set
      Returns:
      Radio button component
      See Also:

    • getDataDescriptor

      public DataDescriptor getDataDescriptor()
      Gets the DataDescriptor for the component value set.
      Specified by:
      getDataDescriptor in interface BasedOnDataDescriptor<RadioButtonItem>
      Returns:
      The DataDescriptor instance from where the component gets its value set. null if no DataDescriptor is set.

    • setDataColumn

      public final RadioButtonItem setDataColumn(String columnName)
      Sets the name of the DataDescriptor that contains the value set’s data values. A data value is a value taken by the component if the item is selected.
      Parameters:
      columnName - The name of the DataDescriptor that contains the value set’s values
      Returns:
      Radio button component
      Throws:
      IllegalArgumentException - Thrown if there is no DataDescriptor set for the component or the specified column is not included in the data source

    • getDataColumnName

      public String getDataColumnName()
      Gets the name of the DataDescriptor column that contains the data values of the value set.
      Returns:
      The name of the DataDescriptor column containing the value set’s data values or null if not set

    • setDisplayColumn

      public final RadioButtonItem setDisplayColumn(String columnName)
      Sets the name of the DataDescriptor column containing the displayed values of the value set. The displayed value is the value to be displayed on the interface.
      Parameters:
      columnName - The name of the DataDescriptor column containing the display values
      Returns:
      Radio button component
      Throws:
      IllegalArgumentException - Thrown if there is not DataDescriptor set for the component or the specified DataDescriptor column is not included in the DataDescriptor

    • setDisplayColumns

      public final RadioButtonItem setDisplayColumns(String... columnNames)
      Sets the DataDescriptors containing the value set’s displayed values. The displayed value is the value to be displayed on the interface.
      Parameters:
      columnNames - An enumeration of DataDescriptor columns containing the display values
      Returns:
      Radio button component
      Throws:
      IllegalArgumentException - Thrown if there is no DataDescriptor set for the component or one of the specified DataDescriptor columns is not included in the DataDescriptor

    • getDisplayColumnName

      public String getDisplayColumnName()
      Gets the DataDescriptor column name containing the displayed value. If multiple values are set, the method returns the name of the first column.
      Returns:
      The name of the DataDescriptor containing displayed values or null if not set

    • getDisplayColumnNames

      public List<String> getDisplayColumnNames()
      Gets the names of all DataDescriptor columns that contain the specified value.
      Returns:
      A list of all DataDescriptor columns containing the specified display name If no column is specified that contains the column with the displayed value, the return value is an empty list.

    • setDisplayColumnSeparator

      public final RadioButtonItem setDisplayColumnSeparator(String separator)
      Sets a text separating the displayed columns. By default, this text is not set and the columns are displayed in a consecutive order.
      Parameters:
      separator - The separator text specified in case of multiple values for the same item
      Returns:
      Radio button component

    • getDisplayColumnSeparator

      public String getDisplayColumnSeparator()
      Gets the separator text for the displayed values.
      Returns:
      The text separating display values or null if it is not specified

    • setValue

      public RadioButtonItem setValue(Object value)
      Sets the current value of the component.
      Overrides:
      setValue in class FormItem<Object,RadioButtonItem>
      Parameters:
      value - The current value of the component
      Returns:
      Radio button component

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

    • onShow

      public void onShow()
      Description copied from class: Component
      The operations to be executed after the component is displayed on the client

      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 component is displayed. This method is nearly identical to the afterDraw() method, they differ in when they are executed. This method runs after the component is displayed on the client. Meaning that it is executed even if the component isn't redrawn, but only set to be visible after being hidden.

      Overrides:
      onShow in class FormItem<Object,RadioButtonItem>

    • getValue

      public Object getValue()
      Gets the current value of the component.
      Overrides:
      getValue in class FormItem<Object,RadioButtonItem>
      Returns:
      The current value of the component

    • getDisplayValue

      public String getDisplayValue()
      Gets the displayed value for the component’s current value.
      Specified by:
      getDisplayValue in interface DifferentDataDisplayValue
      Returns:
      The displayed value for the component’s current value or null if the component’s current value is null

    • getOriginalDisplayValue

      public String getOriginalDisplayValue()
      Gets the displayed value for the component’s original value.
      Specified by:
      getOriginalDisplayValue in interface DifferentDataDisplayValue
      Returns:
      The displayed value for the component’s original value or null if the component’s original value is null

    • 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,RadioButtonItem>
      Parameters:
      writer - The HTML string writer class instance; write here the HTML code for the input field

    • setSort

      public RadioButtonItem setSort(boolean sort)
      Sets if the value set is displayed to the user in a sorted fashion. By default, the value set is not displayed sorted, but based on which item was added earlier.
      Parameters:
      sort - If true is set, the value set is displayed in a sorted fashion Otherwise, items are displayed in the order of being added to the component.
      Returns:
      Radio button component

    • setSort

      public RadioButtonItem setSort(boolean sort, Collator collator)
      Sets if the value set is displayed to the user in a sorted fashion. By default, the value set is not displayed sorted, but based on which item was added earlier.
      Parameters:
      sort - If true is set, the value set is displayed in a sorted fashion Otherwise, items are displayed in the order of being added to the component.
      collator - Collator instance describing sorting
      Returns:
      Radio button component

    • setCollator

      public final RadioButtonItem setCollator(Collator collator)
      Sets the collator instance sorting the value set.
      Parameters:
      collator - Collator instance for sorting
      Returns:
      Combobox component
      See Also:

    • setDefaultValue

      public RadioButtonItem setDefaultValue(Object defaultValue)
      Sets the component’s default value.
      Specified by:
      setDefaultValue in class FormItem<Object,RadioButtonItem>
      Parameters:
      defaultValue - The default value for the component
      Returns:
      Radio button component

    • getCriteria

      public final Criteria getCriteria()
      Gets the filter criterion used to query the component’s value set data from the database.
      Specified by:
      getCriteria in interface Filterable<RadioButtonItem>
      Returns:
      Filter criterion used by the component to query the value set data from the database or null if no filter criterion is set

    • fetchData

      public final RadioButtonItem fetchData()
      Gets the value set data from the database.
      Specified by:
      fetchData in interface Fetchable<RadioButtonItem>
      Specified by:
      fetchData in interface Filterable<RadioButtonItem>
      Returns:
      Radio button component
      Throws:
      UnsupportedOperationException - Thrown if there is no DataDescriptor defined for the component, but the method has been called

    • setFilterCriteria

      public final RadioButtonItem setFilterCriteria(Criteria criteria)
      Sets the filter criterion used to query the value set.
      Specified by:
      setFilterCriteria in interface Filterable<RadioButtonItem>
      Parameters:
      criteria - The filter criterion used for the query If null is set,the query is performed without setting a filter and all items of the DataDescriptor are retrieved to the value set
      Returns:
      Radio button component

    • setInline

      public final RadioButtonItem setInline(boolean inline)
      Sets the value set to be displayed in a single line. By default, the value set items are displayed below each other.
      Parameters:
      inline - If true is set, value set items are displayed within a single line Otherwise, value set items are displayed below each other.
      Returns:
      Radio button component

    • isInline

      public boolean isInline()
      Sets if the value set items are displayed in a single line.
      Returns:
      If true the value set items are displayed in a single line. Otherwise false.

    • setAutoFetchData

      public RadioButtonItem setAutoFetchData(boolean autoFetch)
      Sets if the component should automatically query the data for the value set from the database. By default, the component queries the value set data automatically from the database.
      Specified by:
      setAutoFetchData in interface Fetchable<RadioButtonItem>
      Specified by:
      setAutoFetchData in interface Filterable<RadioButtonItem>
      Parameters:
      autoFetch - If set to true, the query is performed automatically. Otherwise, the value set query must be implemented by calling the method fetchData().
      Returns:
      Radio button component

    • isAutoFetchData

      public boolean isAutoFetchData()
      Sets if value set data is automatically queried.
      Specified by:
      isAutoFetchData in interface Fetchable<RadioButtonItem>
      Specified by:
      isAutoFetchData in interface Filterable<RadioButtonItem>
      Returns:
      If true is set, the data for the value set is automatically queried, otherwise not.

    • setReadOnly

      public final RadioButtonItem setReadOnly(boolean readOnly)
      Sets the component to read-only. If the component is set to read-only, the user is not allowed to modify the component value. By default, the component can be freely modified.
      Overrides:
      setReadOnly in class FormItem<Object,RadioButtonItem>
      Parameters:
      readOnly - If true is set, the component is in read-only mode. Otherwise it can be modified.
      Returns:
      Radio button component

    • setCustomFetch

      public RadioButtonItem setCustomFetch(FetchEvent fetchEvent)
      Sets a custom query. When calling the fetchData method, the specified FetchEvent implementation is called, then callback methods are run on records returned by the onFetch method.
      Parameters:
      fetchEvent - Custom query implementation

    • fetch

      public List<Record> fetch(int startRow, int endRow, Criteria criteria, List<Order> orders, Client client) throws FindException, DataAccessException
      Description copied from interface: Fetchable
      This method implements actual data retrieval. The Fetchable.fetchData() function runs callback methods on the returned records.
      Specified by:
      fetch in interface Fetchable<RadioButtonItem>
      Parameters:
      startRow - The first row of the query that appears in the returned list
      endRow - The last row of the query that appears in the returned list
      criteria - The criteria used during the query If null, no criteria will be used, every record is queried.
      orders - The orderings that will be applied to the query results. If null, the data will not be ordered.
      client - The client that started the query. If null, the query will happen without checking for access rights.
      Returns:
      The list of records that meet the specified filter criteria.
      Throws:
      FindException - Occurs if an error was encountered during the query
      DataAccessException - Occurs if the user in the specified client has no access to read the data