Package com.smartgwt.client.widgets.form.fields

Class RelativeDateItem

java.lang.Object
com.smartgwt.client.core.JsObject
com.smartgwt.client.core.DataClass
com.smartgwt.client.core.RefDataClass
com.smartgwt.client.data.Field
com.smartgwt.client.widgets.form.fields.FormItem
com.smartgwt.client.widgets.form.fields.CanvasItem
com.smartgwt.client.widgets.form.fields.RelativeDateItem
All Implemented Interfaces:
HasHandlers, HasBlurHandlers, HasCanEditChangedHandlers, HasChangedHandlers, HasChangeHandlers, HasClickHandlers, HasDoubleClickHandlers, HasEditorEnterHandlers, HasEditorExitHandlers, HasFocusHandlers, HasIconClickHandlers, HasIconKeyPressHandlers, HasItemHoverHandlers, HasKeyDownHandlers, HasKeyPressHandlers, HasKeyUpHandlers, HasPendingStatusChangedHandlers, HasPickerIconClickHandlers, HasReadOnlyDisplayChangedHandlers, HasShowContextMenuHandlers, HasShowValueHandlers, HasTitleClickHandlers, HasTitleDoubleClickHandlers, HasTitleHoverHandlers, HasValueHoverHandlers, HasValueIconClickHandlers
public class RelativeDateItem extends CanvasItem
A FormItem for entering a date relative to today or relative to some other date, or a specific absolute date. Typically used for filtering data by date.

The RelativeDateItem consists of a ComboBoxItem where the user may directly choose one of several preset options, choose to enter a quantity and time unit (eg "4 months ago" or "3 years from now") or directly type in an absolute date value (7/18/2009).

This item can work with logical dates or datetimes, depending on the specified data-type. For detailed information on working with dates, times and datetimes, see the Date and Time Format and Storage overview.

  • Constructor Details

    • RelativeDateItem

      public RelativeDateItem()

    • RelativeDateItem

      public RelativeDateItem(JavaScriptObject jsObj)

    • RelativeDateItem

      public RelativeDateItem(String name)

    • RelativeDateItem

      public RelativeDateItem(String name, String title)

  • Method Details

    • getOrCreateRef

      public static RelativeDateItem getOrCreateRef(JavaScriptObject jsObj)

    • changeAutoChildDefaults

      public static void changeAutoChildDefaults(String autoChildName, Canvas defaults)
      Changes the defaults for Canvas AutoChildren named autoChildName.
      Parameters:
      autoChildName - name of an AutoChild to customize the defaults for.
      defaults - Canvas defaults to apply. These defaults override any existing properties without destroying or wiping out non-overridden properties. For usage tips on this param, see SGWTProperties.
      See Also:

    • changeAutoChildDefaults

      public static void changeAutoChildDefaults(String autoChildName, FormItem defaults)
      Changes the defaults for FormItem AutoChildren named autoChildName.
      Parameters:
      autoChildName - name of an AutoChild to customize the defaults for.
      defaults - FormItem defaults to apply. These defaults override any existing properties without destroying or wiping out non-overridden properties. For usage tips on this param, see SGWTProperties.
      See Also:

    • changePickerIconDefaults

      public static void changePickerIconDefaults(FormItemIcon defaults)

    • setAllowAbsoluteDates

      public RelativeDateItem setAllowAbsoluteDates(Boolean allowAbsoluteDates)
      When set to false, only relative dates can be entered - in this mode, the date chooser icon is hidden and the value field is switched from a ComboBoxItem, which allows text-entry, to a SelectItem which does not.
      Parameters:
      allowAbsoluteDates - New allowAbsoluteDates value. Default value is true
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getAllowAbsoluteDates

      public Boolean getAllowAbsoluteDates()
      When set to false, only relative dates can be entered - in this mode, the date chooser icon is hidden and the value field is switched from a ComboBoxItem, which allows text-entry, to a SelectItem which does not.
      Returns:
      Current allowAbsoluteDates value. Default value is true

    • setBaseDate

      public RelativeDateItem setBaseDate(Date baseDate)
      Base date for calculating the relative date entered by the user.

      The default is to use the current date.

      Parameters:
      baseDate - New baseDate value. Default value is null
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getBaseDate

      public Date getBaseDate()
      Base date for calculating the relative date entered by the user.

      The default is to use the current date.

      Returns:
      Current baseDate value. Default value is null

    • getCalculatedDateField

      public BlurbItem getCalculatedDateField()
      Field that shows the current calculated date by adding the user-entered relative date to the baseDate.

      This component is an AutoChild named "calculatedDateField". For an overview of how to use and configure AutoChildren, see Using AutoChildren.

      Returns:
      Current calculatedDateField value. Default value is null

    • setCenturyThreshold

      public RelativeDateItem setCenturyThreshold(int centuryThreshold)
      Only used if we're showing the date in a text field. When parsing a date, if the year is specified with 1 or 2 digits and is less than the centuryThreshold, then the year will be assumed to be 20xx; otherwise it will be interpreted according to default browser behavior, which will consider it to be 19xx.

      By default, the centuryThreshold is calculated as the current year + 25.

      If you need to allow 1 and 2 digit years, set this attribute to null to have the control retain your year-value as entered.

      Parameters:
      centuryThreshold - New centuryThreshold value. Default value is 25
      Returns:
      RelativeDateItem instance, for chaining setter calls
      See Also:

    • getCenturyThreshold

      public int getCenturyThreshold()
      Only used if we're showing the date in a text field. When parsing a date, if the year is specified with 1 or 2 digits and is less than the centuryThreshold, then the year will be assumed to be 20xx; otherwise it will be interpreted according to default browser behavior, which will consider it to be 19xx.

      By default, the centuryThreshold is calculated as the current year + 25.

      If you need to allow 1 and 2 digit years, set this attribute to null to have the control retain your year-value as entered.

      Returns:
      Current centuryThreshold value. Default value is 25
      See Also:

    • setDaysAgoTitle

      public RelativeDateItem setDaysAgoTitle(String daysAgoTitle)
      The title to show for historical periods when the TimeUnit is "day".
      Parameters:
      daysAgoTitle - New daysAgoTitle value. Default value is "N days ago"
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getDaysAgoTitle

      public String getDaysAgoTitle()
      The title to show for historical periods when the TimeUnit is "day".
      Returns:
      Current daysAgoTitle value. Default value is "N days ago"

    • setDaysFromNowTitle

      public RelativeDateItem setDaysFromNowTitle(String daysFromNowTitle)
      The title to show for future periods when the TimeUnit is "day".
      Parameters:
      daysFromNowTitle - New daysFromNowTitle value. Default value is "N days from now"
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getDaysFromNowTitle

      public String getDaysFromNowTitle()
      The title to show for future periods when the TimeUnit is "day".
      Returns:
      Current daysFromNowTitle value. Default value is "N days from now"

    • setDefaultQuantity

      public RelativeDateItem setDefaultQuantity(int defaultQuantity)
      Default quantity to show in the quantityField.
      Parameters:
      defaultQuantity - New defaultQuantity value. Default value is 1
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getDefaultQuantity

      public int getDefaultQuantity()
      Default quantity to show in the quantityField.
      Returns:
      Current defaultQuantity value. Default value is 1

    • setEndDate

      public RelativeDateItem setEndDate(Date endDate)
      Limits the range of the popup DateChooser.

      If unset, the item's popup DateChooser is limited by DateChooser.endYear.

      Note that changing this attribute after the item is drawn may result in item-validation.

      Parameters:
      endDate - New endDate value. Default value is null
      Returns:
      RelativeDateItem instance, for chaining setter calls
      See Also:

    • getEndDate

      public Date getEndDate()
      Limits the range of the popup DateChooser.

      If unset, the item's popup DateChooser is limited by DateChooser.endYear.

      Note that changing this attribute after the item is drawn may result in item-validation.

      Returns:
      Current endDate value. Default value is null
      See Also:

    • setGenerateValidator

      public RelativeDateItem setGenerateValidator(Boolean generateValidator)
      When this item has a startDate or endDate specified, should it automatically generate a client-side dateRange validator to enforce them?

      When true, the default, the item will generate a dateRange validator automatically if the developer hasn't installed one but has set either date-range value.

      If a dateRange validator already exists, this attribute is non-functional - no automatic validator is generated, and no checks are made that the values in the developer-provided validator match the item's current start or end dates.

      Note that the validator generated by this attribute exists only on the FormItem, so it doesn't do any server enforcement and doesn't cause validation to happen in any other circumstance (eg, an unrelated grid used for editing). For consistent and pervasive enforcement, the validator should be declared on the DataSourceField.

      Parameters:
      generateValidator - New generateValidator value. Default value is true
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getGenerateValidator

      public Boolean getGenerateValidator()
      When this item has a startDate or endDate specified, should it automatically generate a client-side dateRange validator to enforce them?

      When true, the default, the item will generate a dateRange validator automatically if the developer hasn't installed one but has set either date-range value.

      If a dateRange validator already exists, this attribute is non-functional - no automatic validator is generated, and no checks are made that the values in the developer-provided validator match the item's current start or end dates.

      Note that the validator generated by this attribute exists only on the FormItem, so it doesn't do any server enforcement and doesn't cause validation to happen in any other circumstance (eg, an unrelated grid used for editing). For consistent and pervasive enforcement, the validator should be declared on the DataSourceField.

      Returns:
      Current generateValidator value. Default value is true

    • setHoursAgoTitle

      public RelativeDateItem setHoursAgoTitle(String hoursAgoTitle)
      The title to show for historical periods when the TimeUnit is "hour".
      Parameters:
      hoursAgoTitle - New hoursAgoTitle value. Default value is "N hours ago"
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getHoursAgoTitle

      public String getHoursAgoTitle()
      The title to show for historical periods when the TimeUnit is "hour".
      Returns:
      Current hoursAgoTitle value. Default value is "N hours ago"

    • setHoursFromNowTitle

      public RelativeDateItem setHoursFromNowTitle(String hoursFromNowTitle)
      The title to show for future periods when the TimeUnit is "hour".
      Parameters:
      hoursFromNowTitle - New hoursFromNowTitle value. Default value is "N hours from now"
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getHoursFromNowTitle

      public String getHoursFromNowTitle()
      The title to show for future periods when the TimeUnit is "hour".
      Returns:
      Current hoursFromNowTitle value. Default value is "N hours from now"

    • setInputFormat

      public RelativeDateItem setInputFormat(String inputFormat)
      Format for direct user input of date values.

      If unset, the input format will be determined based on the specified dateFormatter if possible, otherwise picked up from the Date class (see DateUtil.setInputFormat()).

      Overrides:
      setInputFormat in class FormItem
      Parameters:
      inputFormat - New inputFormat value. Default value is null
      Returns:
      RelativeDateItem instance, for chaining setter calls
      See Also:

    • getInputFormat

      public String getInputFormat()
      Format for direct user input of date values.

      If unset, the input format will be determined based on the specified dateFormatter if possible, otherwise picked up from the Date class (see DateUtil.setInputFormat()).

      Overrides:
      getInputFormat in class FormItem
      Returns:
      If DateItem.useTextField is true this method returns a standard DateInputFormat, determining how values entered by the user are to be converted to Javascript Date objects.

      If an explicit DateItem.inputFormat has been specified it will be returned, otherwise, if a custom DateItem.dateFormatter or DateItem.format are specified, the input format will be automatically derived from that property.

      Otherwise, the global inputFormat is used.

      Note that the inputFormat will ignore any separator characters and padding of values. However if necessary entirely custom date formatting and parsing may be achieved via the setEditorValueFormatter() and setEditorValueParser() APIs. Default value is null

      See Also:

    • setMaxQuantity

      public RelativeDateItem setMaxQuantity(int maxQuantity)
      Maximum value to allow in the quantityField. Increasing this value may result in date miscalculations for very large numbers, due to Javascript Date limitations.
      Parameters:
      maxQuantity - New maxQuantity value. Default value is 999999
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getMaxQuantity

      public int getMaxQuantity()
      Maximum value to allow in the quantityField. Increasing this value may result in date miscalculations for very large numbers, due to Javascript Date limitations.
      Returns:
      Current maxQuantity value. Default value is 999999

    • setMillisecondsAgoTitle

      public RelativeDateItem setMillisecondsAgoTitle(String millisecondsAgoTitle)
      The title to show for historical periods when the TimeUnit is "millisecond".
      Parameters:
      millisecondsAgoTitle - New millisecondsAgoTitle value. Default value is "N milliseconds ago"
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getMillisecondsAgoTitle

      public String getMillisecondsAgoTitle()
      The title to show for historical periods when the TimeUnit is "millisecond".
      Returns:
      Current millisecondsAgoTitle value. Default value is "N milliseconds ago"

    • setMillisecondsFromNowTitle

      public RelativeDateItem setMillisecondsFromNowTitle(String millisecondsFromNowTitle)
      The title to show for future periods when the TimeUnit is "millisecond".
      Parameters:
      millisecondsFromNowTitle - New millisecondsFromNowTitle value. Default value is "N milliseconds from now"
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getMillisecondsFromNowTitle

      public String getMillisecondsFromNowTitle()
      The title to show for future periods when the TimeUnit is "millisecond".
      Returns:
      Current millisecondsFromNowTitle value. Default value is "N milliseconds from now"

    • setMinQuantity

      public RelativeDateItem setMinQuantity(int minQuantity)
      Minimum value to allow in the quantityField.
      Parameters:
      minQuantity - New minQuantity value. Default value is 0
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getMinQuantity

      public int getMinQuantity()
      Minimum value to allow in the quantityField.
      Returns:
      Current minQuantity value. Default value is 0

    • setMinutesAgoTitle

      public RelativeDateItem setMinutesAgoTitle(String minutesAgoTitle)
      The title to show for historical periods when the TimeUnit is "minute".
      Parameters:
      minutesAgoTitle - New minutesAgoTitle value. Default value is "N minutes ago"
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getMinutesAgoTitle

      public String getMinutesAgoTitle()
      The title to show for historical periods when the TimeUnit is "minute".
      Returns:
      Current minutesAgoTitle value. Default value is "N minutes ago"

    • setMinutesFromNowTitle

      public RelativeDateItem setMinutesFromNowTitle(String minutesFromNowTitle)
      The title to show for future periods when the TimeUnit is "minute".
      Parameters:
      minutesFromNowTitle - New minutesFromNowTitle value. Default value is "N minutes from now"
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getMinutesFromNowTitle

      public String getMinutesFromNowTitle()
      The title to show for future periods when the TimeUnit is "minute".
      Returns:
      Current minutesFromNowTitle value. Default value is "N minutes from now"

    • setMonthsAgoTitle

      public RelativeDateItem setMonthsAgoTitle(String monthsAgoTitle)
      The title to show for historical periods when the TimeUnit is "month".
      Parameters:
      monthsAgoTitle - New monthsAgoTitle value. Default value is "N months ago"
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getMonthsAgoTitle

      public String getMonthsAgoTitle()
      The title to show for historical periods when the TimeUnit is "month".
      Returns:
      Current monthsAgoTitle value. Default value is "N months ago"

    • setMonthsFromNowTitle

      public RelativeDateItem setMonthsFromNowTitle(String monthsFromNowTitle)
      The title to show for future periods when the TimeUnit is "month".
      Parameters:
      monthsFromNowTitle - New monthsFromNowTitle value. Default value is "N months from now"
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getMonthsFromNowTitle

      public String getMonthsFromNowTitle()
      The title to show for future periods when the TimeUnit is "month".
      Returns:
      Current monthsFromNowTitle value. Default value is "N months from now"

    • setOperator

      public RelativeDateItem setOperator(OperatorId operator)
      What operator to use when the FormItemCriterionGetter's getCriterion() method is called.
      Overrides:
      setOperator in class FormItem
      Parameters:
      operator - New operator value. Default value is "greaterThan"
      Returns:
      RelativeDateItem instance, for chaining setter calls
      See Also:

    • getOperator

      public OperatorId getOperator()
      What operator to use when the FormItemCriterionGetter's getCriterion() method is called.
      Overrides:
      getOperator in class FormItem
      Returns:
      Current operator value. Default value is "greaterThan"
      See Also:

    • setPickerConstructor

      public RelativeDateItem setPickerConstructor(String pickerConstructor)
      Smart GWT class for the dateChooser autoChild displayed to allow the user to directly select dates.
      Parameters:
      pickerConstructor - New pickerConstructor value. Default value is "DateChooser"
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getPickerConstructor

      public String getPickerConstructor()
      Smart GWT class for the dateChooser autoChild displayed to allow the user to directly select dates.
      Returns:
      Current pickerConstructor value. Default value is "DateChooser"

    • getPickerIcon

      public FormItemIcon getPickerIcon()
      Icon that launches a DateChooser for choosing an absolute date.

      This component is an AutoChild named "pickerIcon". For an overview of how to use and configure AutoChildren, see Using AutoChildren.

      Returns:
      Current pickerIcon value. Default value is null

    • setPickerIconPrompt

      public RelativeDateItem setPickerIconPrompt(String pickerIconPrompt)
      Prompt to show when the user hovers the mouse over the picker icon for this RelativeDateItem. May be overridden for localization of your application.
      Overrides:
      setPickerIconPrompt in class FormItem
      Parameters:
      pickerIconPrompt - New pickerIconPrompt value. Default value is "Show Date Chooser"
      Returns:
      RelativeDateItem instance, for chaining setter calls
      See Also:

    • getPickerIconPrompt

      public String getPickerIconPrompt()
      Prompt to show when the user hovers the mouse over the picker icon for this RelativeDateItem. May be overridden for localization of your application.
      Overrides:
      getPickerIconPrompt in class FormItem
      Returns:
      Current pickerIconPrompt value. Default value is "Show Date Chooser"
      See Also:

    • setPickerTimeItemProperties

      public RelativeDateItem setPickerTimeItemProperties(TimeItem pickerTimeItemProperties)
      A set of properties to apply to the TimeItem displayed in the picker when showPickerTimeItem is true.

      Has no effect for fields of type "date".

      Note : This is an advanced setting

      Parameters:
      pickerTimeItemProperties - New pickerTimeItemProperties value. Default value is null
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getPickerTimeItemProperties

      public TimeItem getPickerTimeItemProperties()
      A set of properties to apply to the TimeItem displayed in the picker when showPickerTimeItem is true.

      Has no effect for fields of type "date".

      Returns:
      Current pickerTimeItemProperties value. Default value is null

    • getQuantityField

      public SpinnerItem getQuantityField()
      Field allowing user to pick units of time, eg, number of days.

      This component is an AutoChild named "quantityField". For an overview of how to use and configure AutoChildren, see Using AutoChildren.

      Returns:
      Current quantityField value. Default value is null

    • setQuartersAgoTitle

      public RelativeDateItem setQuartersAgoTitle(String quartersAgoTitle)
      The title to show for historical periods when the TimeUnit is "quarter".
      Parameters:
      quartersAgoTitle - New quartersAgoTitle value. Default value is "N quarters ago"
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getQuartersAgoTitle

      public String getQuartersAgoTitle()
      The title to show for historical periods when the TimeUnit is "quarter".
      Returns:
      Current quartersAgoTitle value. Default value is "N quarters ago"

    • setQuartersFromNowTitle

      public RelativeDateItem setQuartersFromNowTitle(String quartersFromNowTitle)
      The title to show for future periods when the TimeUnit is "quarter".
      Parameters:
      quartersFromNowTitle - New quartersFromNowTitle value. Default value is "N quarters from now"
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getQuartersFromNowTitle

      public String getQuartersFromNowTitle()
      The title to show for future periods when the TimeUnit is "quarter".
      Returns:
      Current quartersFromNowTitle value. Default value is "N quarters from now"

    • setRangePosition

      public RelativeDateItem setRangePosition(RelativeDateRangePosition rangePosition)
      Does this item's relative date value refer to the start or end of the chosen date? Useful when using this item to generate filter criteria, such as the from or to value for an inclusive range.

      If unset "start" is assumed.

      Note : This is an advanced setting

      Parameters:
      rangePosition - New rangePosition value. Default value is null
      Returns:
      RelativeDateItem instance, for chaining setter calls
      See Also:

    • getRangePosition

      public RelativeDateRangePosition getRangePosition()
      Does this item's relative date value refer to the start or end of the chosen date? Useful when using this item to generate filter criteria, such as the from or to value for an inclusive range.

      If unset "start" is assumed.

      Returns:
      Current rangePosition value. Default value is null
      See Also:
      • getOperator()
      • com.smartgwt.client.widgets.form.fields.RelativeDateItem#getRangeRoundingGranularity

    • setSecondsAgoTitle

      public RelativeDateItem setSecondsAgoTitle(String secondsAgoTitle)
      The title to show for historical periods when the TimeUnit is "second".
      Parameters:
      secondsAgoTitle - New secondsAgoTitle value. Default value is "N seconds ago"
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getSecondsAgoTitle

      public String getSecondsAgoTitle()
      The title to show for historical periods when the TimeUnit is "second".
      Returns:
      Current secondsAgoTitle value. Default value is "N seconds ago"

    • setSecondsFromNowTitle

      public RelativeDateItem setSecondsFromNowTitle(String secondsFromNowTitle)
      The title to show for future periods when the TimeUnit is "second".
      Parameters:
      secondsFromNowTitle - New secondsFromNowTitle value. Default value is "N seconds from now"
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getSecondsFromNowTitle

      public String getSecondsFromNowTitle()
      The title to show for future periods when the TimeUnit is "second".
      Returns:
      Current secondsFromNowTitle value. Default value is "N seconds from now"

    • setShouldSaveValue

      public RelativeDateItem setShouldSaveValue(Boolean shouldSaveValue)
      Should this item's value be saved in the form's values and hence returned from form.getValues()?

      shouldSaveValue:false is used to mark formItems which do not correspond to the underlying data model and should not save a value into the form's values. Example includes visual separators, password re-type fields, or checkboxes used to show/hide other form items.

      A shouldSaveValue:false item should be given a value either via FormItem.defaultValue or by calling form.setValue(item, value) or formItem.setValue(value). Providing a value via form.values or form.setValues() will automatically switch the item to shouldSaveValue:true.

      Note that

      • if an item is shouldSaveValue true, but has no name, a warning is logged, and shouldSaveValue will be set to false.
      Overrides:
      setShouldSaveValue in class CanvasItem
      Parameters:
      shouldSaveValue - New shouldSaveValue value. Default value is true
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getShouldSaveValue

      public Boolean getShouldSaveValue()
      Should this item's value be saved in the form's values and hence returned from form.getValues()?

      shouldSaveValue:false is used to mark formItems which do not correspond to the underlying data model and should not save a value into the form's values. Example includes visual separators, password re-type fields, or checkboxes used to show/hide other form items.

      A shouldSaveValue:false item should be given a value either via FormItem.defaultValue or by calling form.setValue(item, value) or formItem.setValue(value). Providing a value via form.values or form.setValues() will automatically switch the item to shouldSaveValue:true.

      Note that

      • if an item is shouldSaveValue true, but has no name, a warning is logged, and shouldSaveValue will be set to false.
      Overrides:
      getShouldSaveValue in class CanvasItem
      Returns:
      Current shouldSaveValue value. Default value is true

    • setShowCalculatedDateField

      public RelativeDateItem setShowCalculatedDateField(Boolean showCalculatedDateField)
      Should the Calculated-Date be displayed to the right of the pickerIcon.
      Parameters:
      showCalculatedDateField - New showCalculatedDateField value. Default value is true
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getShowCalculatedDateField

      public Boolean getShowCalculatedDateField()
      Should the Calculated-Date be displayed to the right of the pickerIcon.
      Returns:
      Current showCalculatedDateField value. Default value is true

    • setShowChooserFiscalYearPicker

      public RelativeDateItem setShowChooserFiscalYearPicker(Boolean showChooserFiscalYearPicker)
      When set to true, show a button that allows the calendar to be navigated by fiscal year.
      Parameters:
      showChooserFiscalYearPicker - New showChooserFiscalYearPicker value. Default value is false
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getShowChooserFiscalYearPicker

      public Boolean getShowChooserFiscalYearPicker()
      When set to true, show a button that allows the calendar to be navigated by fiscal year.
      Returns:
      Current showChooserFiscalYearPicker value. Default value is false

    • setShowChooserIcon

      public RelativeDateItem setShowChooserIcon(Boolean showChooserIcon)
      Should we show the icon that displays a date-chooser?
      Parameters:
      showChooserIcon - New showChooserIcon value. Default value is true
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getShowChooserIcon

      public Boolean getShowChooserIcon()
      Should we show the icon that displays a date-chooser?
      Returns:
      Current showChooserIcon value. Default value is true

    • setShowChooserWeekPicker

      public RelativeDateItem setShowChooserWeekPicker(Boolean showChooserWeekPicker)
      When set to true, show a button that allows the calendar to be navigated by week or fiscal week, depending on the value of showChooserFiscalYearPicker.
      Parameters:
      showChooserWeekPicker - New showChooserWeekPicker value. Default value is false
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getShowChooserWeekPicker

      public Boolean getShowChooserWeekPicker()
      When set to true, show a button that allows the calendar to be navigated by week or fiscal week, depending on the value of showChooserFiscalYearPicker.
      Returns:
      Current showChooserWeekPicker value. Default value is false

    • setShowFutureOptions

      public RelativeDateItem setShowFutureOptions(Boolean showFutureOptions)
      Should we show time-unit options in the future? If set to false, for each timeUnitOption we will show only past options [for example "N weeks ago"].

      Note: this does not change the presetOptions, which show up in addition to the time-unit options ("N days from now", etc). The default preset options include both past and future presets so developers may wish to modify the presets to ensure only future options are available.

      Parameters:
      showFutureOptions - New showFutureOptions value. Default value is true
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getShowFutureOptions

      public Boolean getShowFutureOptions()
      Should we show time-unit options in the future? If set to false, for each timeUnitOption we will show only past options [for example "N weeks ago"].

      Note: this does not change the presetOptions, which show up in addition to the time-unit options ("N days from now", etc). The default preset options include both past and future presets so developers may wish to modify the presets to ensure only future options are available.

      Returns:
      Current showFutureOptions value. Default value is true

    • setShowPastOptions

      public RelativeDateItem setShowPastOptions(Boolean showPastOptions)
      Should we show time-unit options in the past? If set to false, for each timeUnitOption we will show only future options [for example "N weeks from now"].

      Note: this does not change the presetOptions, which show up in addition to the time-unit options ("N days from now", etc). The default preset options include both past and future presets so developers may wish to modify the presets to ensure only past options are available.

      Parameters:
      showPastOptions - New showPastOptions value. Default value is true
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getShowPastOptions

      public Boolean getShowPastOptions()
      Should we show time-unit options in the past? If set to false, for each timeUnitOption we will show only future options [for example "N weeks from now"].

      Note: this does not change the presetOptions, which show up in addition to the time-unit options ("N days from now", etc). The default preset options include both past and future presets so developers may wish to modify the presets to ensure only past options are available.

      Returns:
      Current showPastOptions value. Default value is true

    • setShowPickerTimeItem

      public RelativeDateItem setShowPickerTimeItem(Boolean showPickerTimeItem)
      If this item is editing a field of type "datetime", should the DateChooser display the time field, allowing the user to select a time?

      One case where developers will wish to suppress this time-field from being displayed is if a custom dateFormatter has been specified which does not display the time portion of the selected date. In this case any value selected from the DateChooser's time field will be discarded when the picker is dismissed, making it a confusing UI for the end user.

      Has no effect if the field type is "date" - in this case the picker will never show the time field.

      Note : This is an advanced setting

      Parameters:
      showPickerTimeItem - New showPickerTimeItem value. Default value is true
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getShowPickerTimeItem

      public Boolean getShowPickerTimeItem()
      If this item is editing a field of type "datetime", should the DateChooser display the time field, allowing the user to select a time?

      One case where developers will wish to suppress this time-field from being displayed is if a custom dateFormatter has been specified which does not display the time portion of the selected date. In this case any value selected from the DateChooser's time field will be discarded when the picker is dismissed, making it a confusing UI for the end user.

      Has no effect if the field type is "date" - in this case the picker will never show the time field.

      Returns:
      Current showPickerTimeItem value. Default value is true

    • setStartDate

      public RelativeDateItem setStartDate(Date startDate)
      Limits the range of the popup DateChooser.

      If unset, the item's popup DateChooser is limited by DateChooser.startYear.

      Note that changing this attribute after the item is drawn may result in item-validation.

      Parameters:
      startDate - New startDate value. Default value is null
      Returns:
      RelativeDateItem instance, for chaining setter calls
      See Also:

    • getStartDate

      public Date getStartDate()
      Limits the range of the popup DateChooser.

      If unset, the item's popup DateChooser is limited by DateChooser.startYear.

      Note that changing this attribute after the item is drawn may result in item-validation.

      Returns:
      Current startDate value. Default value is null
      See Also:

    • setTimeUnitOptions

      public RelativeDateItem setTimeUnitOptions(TimeUnit... timeUnitOptions)
      List of time units that will be offered for relative dates.

      Each available time unit option will cause two options to appear in the valueField. For example, if "day" is an available time unit option, there will be "N days ago" and "N days from now".

      Parameters:
      timeUnitOptions - New timeUnitOptions value. Default value is ["day", "week", "month"]
      Returns:
      RelativeDateItem instance, for chaining setter calls
      See Also:

    • getTimeUnitOptions

      public TimeUnit[] getTimeUnitOptions()
      List of time units that will be offered for relative dates.

      Each available time unit option will cause two options to appear in the valueField. For example, if "day" is an available time unit option, there will be "N days ago" and "N days from now".

      Returns:
      Current timeUnitOptions value. Default value is ["day", "week", "month"]
      See Also:

    • setUse24HourTime

      public RelativeDateItem setUse24HourTime(Boolean use24HourTime)
      When showing the DateChooser, should the time field be set to use 24-hour time? Has no effect for fields of type "date" rather than "datetime", or if showPickerTimeItem is false.

      Default is true.

      Parameters:
      use24HourTime - New use24HourTime value. Default value is true
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getUse24HourTime

      public Boolean getUse24HourTime()
      When showing the DateChooser, should the time field be set to use 24-hour time? Has no effect for fields of type "date" rather than "datetime", or if showPickerTimeItem is false.

      Default is true.

      Returns:
      Current use24HourTime value. Default value is true

    • setUseSharedPicker

      public RelativeDateItem setUseSharedPicker(Boolean useSharedPicker)
      When set to true (the default), use a single shared date-picker across all widgets that use one. When false, create a new picker using the autoChild system. See picker and pickerProperties for details on setting up an unshared picker.
      Parameters:
      useSharedPicker - New useSharedPicker value. Default value is true
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getUseSharedPicker

      public Boolean getUseSharedPicker()
      When set to true (the default), use a single shared date-picker across all widgets that use one. When false, create a new picker using the autoChild system. See picker and pickerProperties for details on setting up an unshared picker.
      Returns:
      Current useSharedPicker value. Default value is true

    • setValueFieldWidth

      public RelativeDateItem setValueFieldWidth(int valueFieldWidth)
      The width for the valueField in this item. Defaults to the current default value for the width attribute on the DateTimeItem class - this is assumed to be just wide enough to show a full datetime string, in the current global datetime format.

      Setting the width globally on the DateTimeItem class results in all text-based datetime entry fields assuming the same default width - this caters for custom date-time formatters that need differing amounts of space.

      Parameters:
      valueFieldWidth - New valueFieldWidth value. Default value is null
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getValueFieldWidth

      public int getValueFieldWidth()
      The width for the valueField in this item. Defaults to the current default value for the width attribute on the DateTimeItem class - this is assumed to be just wide enough to show a full datetime string, in the current global datetime format.

      Setting the width globally on the DateTimeItem class results in all text-based datetime entry fields assuming the same default width - this caters for custom date-time formatters that need differing amounts of space.

      Note : This method will return -1 if the underlying SmartClient JavaScript attribute value cannot be expressed as a(n) int. In that case, other getters, similarly-named but ending in AsString, AsCanvas, etc., may be provided.

      Returns:
      Current valueFieldWidth value. Default value is null

    • setValueFieldWidth

      public RelativeDateItem setValueFieldWidth(String valueFieldWidth)
      The width for the valueField in this item. Defaults to the current default value for the width attribute on the DateTimeItem class - this is assumed to be just wide enough to show a full datetime string, in the current global datetime format.

      Setting the width globally on the DateTimeItem class results in all text-based datetime entry fields assuming the same default width - this caters for custom date-time formatters that need differing amounts of space.

      Parameters:
      valueFieldWidth - New valueFieldWidth value. Default value is null
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getValueFieldWidthAsString

      public String getValueFieldWidthAsString()
      The width for the valueField in this item. Defaults to the current default value for the width attribute on the DateTimeItem class - this is assumed to be just wide enough to show a full datetime string, in the current global datetime format.

      Setting the width globally on the DateTimeItem class results in all text-based datetime entry fields assuming the same default width - this caters for custom date-time formatters that need differing amounts of space.

      Returns:
      Current valueFieldWidth value. Default value is null

    • setWeeksAgoTitle

      public RelativeDateItem setWeeksAgoTitle(String weeksAgoTitle)
      The title to show for historical periods when the TimeUnit is "week".
      Parameters:
      weeksAgoTitle - New weeksAgoTitle value. Default value is "N weeks ago"
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getWeeksAgoTitle

      public String getWeeksAgoTitle()
      The title to show for historical periods when the TimeUnit is "week".
      Returns:
      Current weeksAgoTitle value. Default value is "N weeks ago"

    • setWeeksFromNowTitle

      public RelativeDateItem setWeeksFromNowTitle(String weeksFromNowTitle)
      The title to show for future periods when the TimeUnit is "week".
      Parameters:
      weeksFromNowTitle - New weeksFromNowTitle value. Default value is "N weeks from now"
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getWeeksFromNowTitle

      public String getWeeksFromNowTitle()
      The title to show for future periods when the TimeUnit is "week".
      Returns:
      Current weeksFromNowTitle value. Default value is "N weeks from now"

    • setYearsAgoTitle

      public RelativeDateItem setYearsAgoTitle(String yearsAgoTitle)
      The title to show for historical periods when the TimeUnit is "year".
      Parameters:
      yearsAgoTitle - New yearsAgoTitle value. Default value is "N years ago"
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getYearsAgoTitle

      public String getYearsAgoTitle()
      The title to show for historical periods when the TimeUnit is "year".
      Returns:
      Current yearsAgoTitle value. Default value is "N years ago"

    • setYearsFromNowTitle

      public RelativeDateItem setYearsFromNowTitle(String yearsFromNowTitle)
      The title to show for future periods when the TimeUnit is "year".
      Parameters:
      yearsFromNowTitle - New yearsFromNowTitle value. Default value is "N years from now"
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • getYearsFromNowTitle

      public String getYearsFromNowTitle()
      The title to show for future periods when the TimeUnit is "year".
      Returns:
      Current yearsFromNowTitle value. Default value is "N years from now"

    • formatEditorValue

      public void formatEditorValue()
      RelativeDateItems do not make use of the standard FormItem.formatEditorValue() and FormItem.parseEditorValue() methods. Developers can customize the display values for these items in the following ways:
      • The presetOptions map allows standard preset RelativeDateString and RelativeDateShortcut values to be mapped to custom display values
      • The text displayed for each of the timeUnitOptions (e.g:"N days ago") may be customized via the per-time unit title attributes (daysFromNowTitle, daysAgoTitle, etc)
      • The dateFormatter and inputFormat may be used modify how date values are displayed (both in the text entry box and in the calculatedDateField

    • getEnteredValue

      public void getEnteredValue()
      Returns the raw text value typed into this items value text field

    • getFiscalCalendar

      public FiscalCalendar getFiscalCalendar()
      Returns the FiscalCalendar object that will be used by this item's DateChooser.
      Returns:
      the fiscal calendar for this chooser, if set, or the global one otherwise

    • parseEditorValue

      public void parseEditorValue()
      RelativeDateItems do not make use of the standard FormItem.formatEditorValue() and FormItem.parseEditorValue() methods. Developers can customize the display values for these items in the following ways:
      • The presetOptions map allows standard preset RelativeDateString and RelativeDateShortcut values to be mapped to custom display values
      • The text displayed for each of the timeUnitOptions (e.g:"N days ago") may be customized via the per-time unit title attributes (daysFromNowTitle, daysAgoTitle, etc)
      • The dateFormatter and inputFormat may be used modify how date values are displayed (both in the text entry box and in the calculatedDateField

    • setFiscalCalendar

      public void setFiscalCalendar()
      Sets the FiscalCalendar object that will be used by this item's DateChooser. If unset, the global fiscal calendar is used.

    • setFiscalCalendar

      public void setFiscalCalendar(FiscalCalendar fiscalCalendar)
      Sets the FiscalCalendar object that will be used by this item's DateChooser. If unset, the global fiscal calendar is used.
      Parameters:
      fiscalCalendar - the fiscal calendar for this chooser, if set, or the global one otherwise

    • setDefaultProperties

      public static void setDefaultProperties(RelativeDateItem relativeDateItemProperties)
      Class level method to set the default properties of this class. If set, then all existing and subsequently created instances of this class will automatically have default properties corresponding to the properties of the class instance passed to this function. This is a powerful feature that eliminates the need for users to create a separate hierarchy of subclasses that only alter the default properties of this class. Can also be used for skinning / styling purposes.

      Note: This method is intended for setting default attributes only and will affect all instances of the underlying class (including those automatically generated in JavaScript). This method should not be used to apply standard EventHandlers or override methods for a class - use a custom subclass instead. Calling this method after instances have been created can result in undefined behavior, since it bypasses any setters and a class instance may have already examined a particular property and not be expecting any changes through this route.

      Parameters:
      relativeDateItemProperties - properties that should be used as new defaults when instances of this class are created
      See Also:

    • getRelativeDate

      public RelativeDate getRelativeDate()
      Returns the RelativeDate for the current value.
      Returns:
      the RelativeDate for the current value or null if not set

    • getAbsoluteDate

      public static Date getAbsoluteDate(RelativeDate relativeDate)
      Converts a RelativeDate to a concrete Date.
      Parameters:
      relativeDate - the relative date to convert
      Returns:
      resulting absolute date value

    • getAbsoluteDate

      public static Date getAbsoluteDate(RelativeDate relativeDate, Date baseDate)
      Converts a RelativeDate to a concrete Date.
      Parameters:
      relativeDate - the relative date to convert
      baseDate - base value for conversion. Defaults to today
      Returns:
      resulting absolute date value

    • setPresetOptions

      public void setPresetOptions(LinkedHashMap valueMap)
      Set up a set of standard relative dates such as "today" or "tomorrow" that the user can choose directly from the valueField of this item.

      This is similar to a standard {@link FormItem::setValueMap(), valueMap} - the parameter passed in should be a HashMap mapping RelativeDate strings to display values. The default set of preset options (expressed in JSON) are: 

       {
  "$today" : "Today",
  "$yesterday" : "Yesterday",
  "$tomorrow" : "Tomorrow",
  "-1w" : "Current day of last week",
  "+1w" : "Current day of next week",
  "-1m" : "Current day of last month",
  "+1m" : "Current day of next month"
  }
      In addition to these presets, options are shown for each of the {@link #setTimeUnitOptions,time unit options}.

    • setRangeRoundingGranularity

      public void setRangeRoundingGranularity(Map rangeRoundingGranularity)
      A map from a granularity of time specified by a user to the granularity of time used for rounding.

      A relative date such as "n days from now" is normally shifted to the end of the day when used as a range endpoint, and the beginning of the day when used as the beginning of a range. (The rounding direction on some item can be specified via +link{relativeDateItem.rangePosition}). This causes the intuitive behavior that "from yesterday to today" is from the beginning of yesterday to the end of today, and that "from today until 5 days from now" includes the entirety of Friday if today is Monday.

      This same rule can be applied to any time granularity, such that "from now until 20 minutes from now" is up to 5:32 if it is now 5:11:34, and "from now until 2 months from now" means end of June if it is mid-April.

      User intuitions about where this rounding is expected for any given time period tend to vary based on what kind of event is being discussed and subtle phrasing differences (consider "up to one year from now", "until next year", "within the next couple of years"). The defaults behaviors are:

      • for days, weeks and months round to day end/beginning
      • for hours, round to minute end/beginning
      • for minutes and seconds, round to second end/beginning
      To customize this rounding behavior, this attribute may be set to a Map mapping each timeUnit to the granularity for that timeUnit.
      For example the following config code would produce an item where the user could select only day or week values, and the selected value would be rounded to the beginning of the day if a day was selected, or the beginning of the week if a week was selected: 
        RelativeDateItem fromDate = new RelativeDateItem("from");
  fromDate.setRangePosition(RelativeDateRangePosition.START);
  fromDate.setTimeUnitOptions(TimeUnit.DAY, TimeUnit.WEEK);
    
  Map<TimeUnit,TimeUnit> roundingMap = new HashMap<TimeUnit,TimeUnit>();
  roundingMap.put(TimeUnit.DAY, TimeUnit.DAY);
  roundingMap.put(TimeUnit.WEEK, TimeUnit.WEEK);
  fromDate.setRangeRoundingGranularity(roundingMap);
      Parameters:
      rangeRoundingGranularity -

    • setDateFormatter

      public RelativeDateItem setDateFormatter(DateDisplayFormat dateFormatter)
      Format for displaying dates in the valueField and calculatedDateField. Defaults to the system-wide default established by Date.setShortDisplayFormat, or if this item has its type specified as datetime, Date.setShortDatetimeDisplayFormat.
      Overrides:
      setDateFormatter in class FormItem
      Parameters:
      dateFormatter - dateFormatter Default value is null
      Returns:
      RelativeDateItem instance, for chaining setter calls
      See Also:

    • setDateFormatter

      public RelativeDateItem setDateFormatter(DateDisplayFormatter formatter)
      Formatter function for displaying dates in the valueField and calculatedDateField in some custom format. Typically the setDateParser(DateParser) method should also be applied to ensure dates can be both formatted and edited date strings parsed back into actual date values.
      Parameters:
      dateFormatter - dateFormatter Default value is null
      Returns:
      RelativeDateItem instance, for chaining setter calls

    • setDateParser

      public void setDateParser(DateParser parser)
      Custom date parser function for direct user input of date values. Typically used in conjunction with setDateFormatter(DateDisplayFormatter).

      Note that setDateFormatter(DateDisplayFormat) and setInputFormat(String) already provide a mechanism for customizing the display format for date values displayed in this item.

    • setEditorValueParser

      public void setEditorValueParser(FormItemValueParser parser)
      RelativeDateItems do not make use of the standard FormItem.setEditorValueFormatter() and FormItem.setEditorValueParser() methods. Developers can customize the display values for these items in the following ways:
      • The RelativeDateItem.presetOptions map allows standard preset RelativeDateString and RelativeDateShortcut values to be mapped to custom display values
      • The text displayed for each of the RelativeDateItem.timeUnitOptions (e.g:"N days ago") may be customized via the per-time unit title attributes (RelativeDateItem.daysFromNowTitle, RelativeDateItem.daysAgoTitle, etc)
      • setDateFormatter and setInputFormat / setDateParser may be used modify how date values are displayed (both in the text entry box and in the calculatedDateField)
      Overrides:
      setEditorValueParser in class FormItem
      Parameters:
      parser - the FormItemValueParser

    • setEditorValueFormatter

      public void setEditorValueFormatter(FormItemValueFormatter formatter)
      RelativeDateItems do not make use of the standard FormItem.setEditorValueFormatter() and FormItem.setEditorValueParser() methods. Developers can customize the display values for these items in the following ways:
      • The RelativeDateItem.presetOptions map allows standard preset RelativeDateString and RelativeDateShortcut values to be mapped to custom display values
      • The text displayed for each of the RelativeDateItem.timeUnitOptions (e.g:"N days ago") may be customized via the per-time unit title attributes (RelativeDateItem.daysFromNowTitle, RelativeDateItem.daysAgoTitle, etc)
      • setDateFormatter and setInputFormat / setDateParser may be used modify how date values are displayed (both in the text entry box and in the calculatedDateField)
      Overrides:
      setEditorValueFormatter in class FormItem
      Parameters:
      formatter - the FormItemValueFormatter

    • getValueFieldComboBox

      public ComboBoxItem getValueFieldComboBox()
      ComboBoxItem field where a user may choose among presets, time unit plus quantity, or direct entry of a date as text.

      For an overview of how to use and configure AutoChildren, see Using AutoChildren.

      Returns:
      ComboBoxItem