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

Class DateRangePicker

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

Date range picker form item>

This component allows the user to pick a date range. The component guarantees that only valid date ranges can be picked (correctly formatted, has valid maximum and minimum dates and the minimum date is less or equal to the maximum date).

The component displays an input field for the user, that when clicked, will open two dropdown calendars. The left side calendar will allow the user to pick a starting date, the right side calendar will allow the user to pick the ending date. The user can also type in a date, but if it is not in the correct format, the component will revert back to its default value.

The component also allows the use of predefined date ranges, which the user can chose by its name (Previous month, week etc). This makes it easier for the user to input frequently used date ranges. These predefined ranges can be added by using the addPredefinedRange(java.lang.String, java.lang.String, java.util.Date, java.util.Date) method.

Supported events:

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

Since:
4.0
Author:
JBStrap
See Also:

  • Field Details

    • minDate

      protected Date minDate

    • maxDate

      protected Date maxDate

    • dateFormat

      protected String dateFormat

    • showDropdowns

      protected boolean showDropdowns

    • useTime

      protected boolean useTime

  • Constructor Details

    • DateRangePicker

      public DateRangePicker(String name, String label)
      Creates a date range picker, with the specified name and title
      Parameters:
      name - The name of the date picker
      label - The label of the date picker. If null, no label will be used
      Throws:
      NullPointerException - If the name is null

    • DateRangePicker

      public DateRangePicker(String name, String label, String language)
      Creates a date range picker, with the specified name, title and language code
      Parameters:
      name - The name of the date picker
      label - The label of the date picker. If null, no label will be used
      language - Language code according to which the component is created. If not specified or null is set, the framework’s default language code is used. The default language of the framework is set via the JBStrap parameter JBStrapParamType.DEFAULT_LANGUAGE
      Throws:
      NullPointerException - If the name is null

    • DateRangePicker

      public DateRangePicker(String name, String label, String language, String dateFormat)
      Creates a date range picker, with the specified name, title and language code. The date format can also be specified.
      Parameters:
      name - The name of the date picker
      label - The label of the date picker. If null, no label will be used
      language - Language code according to which the component is created. If not specified or null is set, the framework’s default language code is used. The default language of the framework is set via the JBStrap parameter JBStrapParamType.DEFAULT_LANGUAGE
      dateFormat - The date format that will be used by the component. If not specified or null, the framework's default format will be used. The framework's default format can be set via the JBStrapParamType.DATE_FORMAT JBStrap parameter
      Throws:
      NullPointerException - If the name is null

    • DateRangePicker

      public DateRangePicker(DataDescriptorColumn column)
      Creates a date range picker, based on the specified DataDescriptor column.

      The method creates and sets the date range picker, based on the DataDescriptor column, specified in the parameters. 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.DATE_FORMAT - The date format to be used when displaying a date. If not specified, the default format will be used, which can be specified using the JBStrapParamType.DATE_FORMAT and JBStrapParamType.DATETIME_FORMAT JBStrap parameters.
      • 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_DROPDOWN - This parameter determines, if the user can see the dropdown menu, allowing the user to choose from the years and months. By default, this is enabled. If specified as false, the user won't be able to use this dropdown menu. The user can only use the buttons above the calendar, to change the months
      • MetaParamName.PREDEFINED_RANGES - Predefined ranges can be added to the component through this parameter. More than one can be added, by listing them here. The usable range names can be found in the PredefinedDateRange enum, including the custom range(s)
      • MetaParamName.MIN_COLUMN - The column that holds minimum range value can be specified in this parameter. If specified, the component will store the minimum value in this column. * The maximum value (if the MAX_COLUMN is not specified) will be stored in the column, on which the component was built from. If neither the MIN_COLUMN or MAX_COLUMN parameter is specified, the values will be stored in a column, that has the same name, but with a postfix. The starting date postfix is "_startDate", the ending date postfix is "_endDate"
      • MetaParamName.MAX_COLUMN - The column that holds maximum range value can be specified in this parameter. If specified, the component will store the maximum value in this column. * The minimum value (if the MIN_COLUMN is not specified) will be stored in the column, on which the component was built from. If neither the MIN_COLUMN or MAX_COLUMN parameter is specified, the values will be stored in a column, that has the same name, but with a postfix. The starting date postfix is "_startDate", the ending date postfix is "_endDate"

      Parameters:
      column - The DataDescriptor column, that will be used as a basis for the form item
      Throws:
      NullPointerException - If the column is null
      See Also:

    • DateRangePicker

      public DateRangePicker(DataDescriptorColumn column, String language)
      Creates a date range picker, based on the specified DataDescriptor column, with the specified language code.

      The method creates and sets the date range picker, based on the DataDescriptor column, specified in the parameters. 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.DATE_FORMAT - The date format to be used when displaying a date. If not specified, the default format will be used, which can be specified using the JBStrapParamType.DATE_FORMAT and JBStrapParamType.DATETIME_FORMAT JBStrap parameters.
      • 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_DROPDOWN - This parameter determines, if the user can see the dropdown menu, allowing the user to choose from the years and months. By default, this is enabled. If specified as false, the user won't be able to use this dropdown menu. The user can only use the buttons above the calendar, to change the months
      • MetaParamName.PREDEFINED_RANGES - Predefined ranges can be added to the component through this parameter. More than one can be added, by listing them here. The usable range names can be found in the PredefinedDateRange enum, including the custom range(s)
      • MetaParamName.MIN_COLUMN - The column that holds minimum range value can be specified in this parameter. If specified, the component will store the minimum value in this column. * The maximum value (if the MAX_COLUMN is not specified) will be stored in the column, on which the component was built from. If neither the MIN_COLUMN or MAX_COLUMN parameter is specified, the values will be stored in a column, that has the same name, but with a postfix. The starting date postfix is "_startDate", the ending date postfix is "_endDate"
      • MetaParamName.MAX_COLUMN - The column that holds maximum range value can be specified in this parameter. If specified, the component will store the maximum value in this column. * The minimum value (if the MIN_COLUMN is not specified) will be stored in the column, on which the component was built from. If neither the MIN_COLUMN or MAX_COLUMN parameter is specified, the values will be stored in a column, that has the same name, but with a postfix. The starting date postfix is "_startDate", the ending date postfix is "_endDate"

      Parameters:
      column - The DataDescriptor column, that will be used as a basis for the form item
      language - Language code according to which the component is created. If not specified or null is set, the framework’s default language code is used. The default language of the framework is set via the JBStrap parameter JBStrapParamType.DEFAULT_LANGUAGE
      Throws:
      NullPointerException - If the column is null
      See Also:

  • Method Details

    • init

      public void init() throws JavaScriptLoadError
      Description copied from class: Component
      The component initialization method.

      Empty method, only needs to be overwritten when making a custom component, that needs to call an initializing JavaScript on the client side. The method is called by the framework after the component is drawn, but before the afterDraw() method. The use of this method during application development is not allowed. This method is meant for inner use only.

      Overrides:
      init in class FormItem<DateRange,DateRangePicker>
      Throws:
      JavaScriptLoadError - If there was a JavaScript error during the initialization.

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

    • setDateFormat

      public DateRangePicker setDateFormat(String dateFormat)
      Sets the component's date format
      Parameters:
      dateFormat - The date format to be used. If null, the default date format will be used. The framework's default date format can be set via the JBStrapParamType.DATE_FORMAT parameter
      Returns:
      The date range picker component

    • getDateFormat

      public String getDateFormat()
      Gets the component's date format
      Returns:
      The date format to be used.

    • setMinimumDate

      public final DateRangePicker setMinimumDate(Date minDate)
      Sets the minimum date. If specified, the user cannot pick an earlier date. If the user manually inputs a date earlier than the specified minimum date, the date will be automatically modified to the minimum date.
      Parameters:
      minDate - The minimum date
      Returns:
      The date rage picker component

    • getMinimumDate

      public final Date getMinimumDate()
      Gets the minimum date
      Returns:
      The minimum date or null, if no minimum date was specified

    • setMaximumDate

      public final DateRangePicker setMaximumDate(Date maxDate)
      Sets the maximum date. If specified, the user cannot pick a later date. If the user manually inputs a date later than the specified maximum date, the date will be automatically modified to the maximum date.
      Parameters:
      maxDate - The maximum date
      Returns:
      The date range picker component

    • getMaximumDate

      public final Date getMaximumDate()
      Gets the maximum date
      Returns:
      The maximum date or null, if no maximum date was specified

    • setDropDownPosition

      public DateRangePicker setDropDownPosition(DropDownPosition position)
      Sets the position of the dropdown menu. By default, it appears on the left side of the input field
      Parameters:
      position - The position of the dropdown calendar. If null, it will use the default position
      Returns:
      The date range picker component

    • getDropDownPosition

      public DropDownPosition getDropDownPosition()
      Gets the position of the dropdown menu.
      Returns:
      The position of the dropdown calendar.

    • setShowDropdowns

      public DateRangePicker setShowDropdowns(boolean show)
      Sets if the dropdown menu is enabled or not. By default, it is enabled.
      Parameters:
      show - If true, the user can select the years and months through the dropdown menus. If false, the user can only go forwards or backwards through the months
      Returns:
      The date range picker component

    • isShowDropdowns

      public boolean isShowDropdowns()
      Determines if the dropdown menu is enabled or not.
      Returns:
      If true, the user can select the years and months through the dropdown menus. If false, the user can only go forwards or backwards through the months

    • getMinColumnName

      public String getMinColumnName()
      Gets the name of the column, that stores the range minimum value.
      Returns:
      The name of the column

    • getMaxColumnName

      public String getMaxColumnName()
      Gets the name of the column, that stores the range maximum value.
      Returns:
      The name of the column

    • addPredefinedRange

      public DateRangePicker addPredefinedRange(String name, String title, Date minValue, Date maxValue)
      Adds a predefined date range to the component
      Parameters:
      name - The name of the range, must be unique within the component
      title - The title of the range, that will appear on the interface
      minValue - The minimum value of the range
      maxValue - The maximum value of the range
      Returns:
      The date range picker component
      Throws:
      NullPointerException - If the name, minimum or maximum value is null
      IllegalArgumentException - If the name is already in use or the minimum value is greater than the maximum value (the range is invalid)

    • addPredefinedRange

      public DateRangePicker addPredefinedRange(PredefinedRange<Date> range)
      Adds a predefined range to the component
      Parameters:
      range - The POJO class, containing the predefined range's data
      Returns:
      The date range picker component
      Throws:
      IllegalArgumentException - If the name is already in use or the minimum value is greater than the maximum value (the range is invalid)

    • addPredefinedRanges

      public DateRangePicker addPredefinedRanges(List<PredefinedRange<Date>> ranges)
      Adds multiple predefined ranges to the component
      Parameters:
      ranges - A list containing the predefined ranges
      Returns:
      The date range picker component
      Throws:
      IllegalArgumentException - If the name is already in use or the minimum value is greater than the maximum value (the range is invalid)

    • addPredefinedRanges

      @SafeVarargs public final DateRangePicker addPredefinedRanges(PredefinedRange<Date>... ranges)
      Adds multiple predefined ranges to the component
      Parameters:
      ranges - The predefined ranges to be added
      Returns:
      The date range picker component
      Throws:
      IllegalArgumentException - If the name is already in use or the minimum value is greater than the maximum value (the range is invalid)

    • removePredefinedRange

      public DateRangePicker removePredefinedRange(String name)
      Removes the specified predefined range from the component
      Parameters:
      name - The name of the range to be removed. If the name is not found, the method won't do anything
      Returns:
      The date range picker component

    • removePredefinedRanges

      public DateRangePicker removePredefinedRanges(String... names)
      Removes the specified predefined ranges from the component
      Parameters:
      names - The names of the ranges to be removed. If one of them are not found, the method will ignore it
      Returns:
      The date range picker component

    • removePredefinedRange

      public DateRangePicker removePredefinedRange(PredefinedRange<Date> range)
      Removes the specified predefined range from the component
      Parameters:
      range - The POJO class that describes the range
      Returns:
      The date range picker component

    • removePredefinedRanges

      public DateRangePicker removePredefinedRanges(List<PredefinedRange<Date>> ranges)
      Removes the specified predefined ranges from the component
      Parameters:
      ranges - The POJO classes describing the predefined ranges
      Returns:
      The date range picker component

    • removePredefinedRanges

      public DateRangePicker removePredefinedRanges(PredefinedRange<Date>... ranges)
      Removes the specified predefined ranges from the component
      Parameters:
      ranges - A list containing the predefined ranges to be removed
      Returns:
      The date range picker component

    • removeAllPredefinedRanges

      public DateRangePicker removeAllPredefinedRanges()
      Removes all predefined ranges from the component
      Returns:
      The date range picker component

    • getPredefinedRanges

      public List<PredefinedRange<Date>> getPredefinedRanges()
      Gets the predefined ranges that are assigned to the component
      Returns:
      A list containing the predefined ranges that are assigned to the component. If there are none, the list will be empty

    • 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<DateRange,DateRangePicker>

    • setValue

      public DateRangePicker setValue(DateRange value)
      Sets the date range picker's form item value
      Overrides:
      setValue in class FormItem<DateRange,DateRangePicker>
      Parameters:
      value - The component value
      Returns:
      Form item component

    • setOriginalValue

      public DateRangePicker setOriginalValue(DateRange originalValue)
      Description copied from class: FormItem
      Sets the form item’s original value to the specified value.
      Overrides:
      setOriginalValue in class FormItem<DateRange,DateRangePicker>
      Parameters:
      originalValue - The form item’s original value
      Returns:
      Form item component

    • setObjectValue

      public DateRangePicker setObjectValue(Object value)
      Description copied from class: FormItem
      Sets the form item’s current value using the object in the parameter.
      Overrides:
      setObjectValue in class FormItem<DateRange,DateRangePicker>
      Parameters:
      value - The object whose value is passed to the form item
      Returns:
      Form item component

    • setOriginalObjectValue

      public DateRangePicker setOriginalObjectValue(Object value)
      Description copied from class: FormItem
      Sets the form item’s original value using the object in the parameter.
      Overrides:
      setOriginalObjectValue in class FormItem<DateRange,DateRangePicker>
      Parameters:
      value - The object whose value is passed to the form item as an original value
      Returns:
      Form item component

    • setDefaultValue

      public DateRangePicker setDefaultValue(Object defaultValue)
      Description copied from class: FormItem
      Sets the form item’s default value. By default, the form item does not have a default value.
      Specified by:
      setDefaultValue in class FormItem<DateRange,DateRangePicker>
      Parameters:
      defaultValue - Form item default value
      Returns:
      Form item component

    • onFormItemValueChanged

      public void onFormItemValueChanged(FormItemChangeEvent event)
      Overrides:
      onFormItemValueChanged in class FormItem<DateRange,DateRangePicker>
      Parameters:
      event - Form item value change event handler

    • setReadOnly

      public DateRangePicker setReadOnly(boolean readOnly)
      Sets the date range picker to read-only mode. By default, the date range picker is displayed as writable and the user can freely modify the form item value. If the component is set to read-only mode, the user is unable to modify the date range picker value.
      Overrides:
      setReadOnly in class FormItem<DateRange,DateRangePicker>
      Parameters:
      readOnly - If true is set, the date range picker is switched to read-only mode and the user is unable to modify the value. If false is set, the date range picker is switched to writable mode and the user is able to modify form item value.
      Returns:
      Date range picker component

    • setEnabled

      public DateRangePicker setEnabled(boolean enabled)
      Sets the date range picker to be enabled. Defaults to true
      Overrides:
      setEnabled in class FormItem<DateRange,DateRangePicker>
      Parameters:
      enabled - true, the component is enabled, otherwise it's disabled
      Returns:
      Date range picker component