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

Class TextItem

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

Text Item

The component implements a text input field. This allows the user to input any text into the input field, that can be later used by the application. If the maximum text length is 255, then the field will be single line, if it is more than 255, it will be a larger input field (TextArea).

The component supports the use of masks. With the use of a mask, the user can be forced to use a certain text format, and ensure that the text is displayed in the correct format. For more information about masks, see the setMask method description.

The TextItem component is a form item, that can be placed on a Form component, and the form handles it as well. The component can be used on its own, but in that case, the handling of its events and values must be provided by the program code.

Supported events:

AnimationStart AnimationEnd, Focus FocusOut FocusIn LosesFocus copy cut EnterPressed input paste Click, DoubleClick, MouseDown, MouseDown, MouseLeave, MouseMove, MouseOver, MouseOut, MouseUp, Wheel, KeyPress, KeyUp, KeyDown, Scrollable TouchCancel, TouchEnd, TouchMove, TouchStart, Drop, DragStart, DragEnd HotKey

Since:
4.0
Author:
JBStrap
See Also:

  • Constructor Details

    • TextItem

      public TextItem(String name, String label)
      Creates a text input field with the specified name and label.
      Parameters:
      name - The name of the text input field
      label - The label of the field. If null, the item won't have a label.
      Throws:
      NullPointerException - If the specified name is null

    • TextItem

      public TextItem(String name, String label, String language)
      Creates a text input field with the specified name, label and language.
      Parameters:
      name - The name of the text input field
      label - The label of the field. If null, the item won't have a label.
      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 name is null

    • TextItem

      public TextItem(DataDescriptorColumn column)

      Creates a text input field form item, based on the specified DataDescriptor column.

      The method creates and sets the text form item, based on the DataDescriptor column, specified in the parameters. The following parameters from the DataDescriptor column are used:

      • DataDescriptorColumn.getLength() - The maximum length of the column will be the maximum length of the text that can be inputted.
      • 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.MASK - The mask specified here will be used by the text input field
      • MetaParamName.FORCE_TEXT_AREA - If this is true, the text input will be forced to be a text area (multiple lines), regardless of the text length. Otherwise, the length will determine this. If the length is less or equal to 255 characters, the input field will be a single line box.
      • 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 text 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 column was specified as null

    • TextItem

      public TextItem(DataDescriptorColumn column, String language)

      Creates a form item, based on the specified DataDescriptor column and using the specified language code.

      The method creates and sets the form item, based on the DataDescriptor column, specified in the parameters. The following parameters from the DataDescriptor column are used:

      • DataDescriptorColumn.getLength() - The maximum length of the column will be the maximum length of the text that can be inputted.
      • DataDesriptorColumn.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.
      • MetaParamName.MASK - The mask specified here will be used by the text input field
      • MetaParamName.FORCE_TEXT_AREA - If this is true, the text input will be forced to be a text area (multiple lines), regardless of the text length. Otherwise, the length will determine this. If the length is less or equal to 255 characters, the input field will be a single line box.
      • 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 text 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.
      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 column was specified as null

  • Method Details

    • setMask

      public final TextItem setMask(String mask)

      Sets the specified input mask on the text input field.

      By default, there is no mask applied. If a mask is specified, the user is forced to input text in the specified format. It also allows the text to be displayed in this specified format (mask).

      Usable values:

      • a - Letter characters (A-Z,a-z)
      • 9 - Numeric characters (0-9)
      • * - Alphanumeric characters (A-Z,a-z,0-9)

      Examples

      • Credit card number: "9999 9999 9999 9999"
      • Telephone number: "(999) 999-9999"
      • Date: "99/99/9999"

      Parameters:
      mask - The mask to be applied. If null, no mask will be applied.
      Returns:
      Text item component

    • getMask

      public final String getMask()
      Gets the mask of the text item
      Returns:
      The applied mask, or null if it has no mask

    • getMaxLength

      public final int getMaxLength()
      Gets the maximum allowed length of the text item
      Returns:
      The maximum length

    • setMaxLength

      public final TextItem setMaxLength(int maxLength)
      Sets the maximum allowed length of the text item. By default, the maximum text length is 255 characters.
      Parameters:
      maxLength - The maximum amount of characters
      Returns:
      The Text item component

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

    • setDefaultValue

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

    • forceTextArea

      public final TextItem forceTextArea(boolean forceTextArea)
      Sets if the text area is forced, regardless of the character length.
      Parameters:
      forceTextArea - If true, a larger text are will be used, even if the text is less than 255 characters long. Otherwise, if the maximum length is 255 or less, the input filed will use a single line only.
      Returns:
      The Text item component