Package org.zkoss.stateless.sul

Interface IDaterangebox

All Superinterfaces:
IAnyGroup<IDaterangebox>, IComponent<IDaterangebox>, IDisable<IDaterangebox>, IHtmlBasedComponent<IDaterangebox>, IReadonly<IDaterangebox>, IXulElement<IDaterangebox>
public interface IDaterangebox extends IXulElement<IDaterangebox>, IDisable<IDaterangebox>, IReadonly<IDaterangebox>, IAnyGroup<IDaterangebox>
Immutable Daterangebox component (ZK EE only).

A date range picker. Allows users to select a contiguous range of dates (optionally including time) via a popup with one or more side-by-side calendar panels and an optional minimum / maximum length constraint.

The range is carried by a single value of type DateRange; beginValue and endValue are derived views of its two endpoints. Either end may be null when allowEmpty permits.

Support @Action

Name Action Type
onChange ActionData: DateRangeData
Denotes the committed range has been changed by the user.
onChanging ActionData: DateRangeData
Denotes the user is typing into one of the two inputs; the range is not committed yet.
onOpen ActionData: OpenData
Denotes the calendar popup has been opened or closed.
onError ActionData: ErrorData
Denotes the user entered a value that cannot be parsed.

Constraint

The constraint is a SimpleDateConstraint expression applied to both endpoints, for example 

 
 IDaterangebox.ofConstraint("between 20240101 and 20241231");
 IDaterangebox.ofConstraint("no past");

Only the string form is supported, the same way IInputElement.withConstraint(String) and ICalendar.withConstraint(String) are — a server-side Constraint instance has no place in an immutable component.

Length Option

withMinNights(int) and withMaxNights(int) bound the number of nights between the two endpoints; 0 disables the bound.

Position

By default, the popup position is set to after_start, for other possible popup positions please refer to IPopupBase.Position.

Since:
11.0.0
Author:
peaker
See Also:
  • Daterangebox

  • Field Details

    • DEFAULT

      static final IDaterangebox DEFAULT
      Constant for default attributes of this immutable component.

  • Method Details

    • getWidgetClass

      default String getWidgetClass()
      Returns the client widget class.

      Default: "zkmax.db.Daterangebox"

      Specified by:
      getWidgetClass in interface IComponent<IDaterangebox>

    • getValue

      @Nullable org.zkoss.zul.DateRange getValue()
      Returns the current range, or null if unset. Either end of a non-null range may itself be null (an open-ended range).

      This is the one stored endpoint attribute; getBeginValue() and getEndValue() are derived from it. DateRange copies both ends on the way in and on the way out, so a caller that keeps a reference to the Date it passed cannot mutate this component afterwards.

      Default: null

    • withValue

      IDaterangebox withValue(@Nullable org.zkoss.zul.DateRange value)
      Returns a copy of this immutable component with the specified value.

      Sets both endpoints at once.

      Note: UiAgent.smartUpdate(Locator, SmartUpdater) is not supported for this property — IDaterangebox.Updater ships the raw attribute while the initial render ships the epoch millis the client widget parses. Push a whole component with UiAgent.replaceWith(Locator, IComponent) instead.

      Parameters:
      value - The range; null clears both ends.
      Returns:
      A modified copy of the this object

    • getBeginValue

      @Nullable @Derived default Date getBeginValue()
      Returns the begin endpoint, or null if unset.

      A derived snapshot of getValue(); mutating the returned Date is not supported, call getValue() for a fresh copy.

      Default: null

    • withBeginValue

      default IDaterangebox withBeginValue(@Nullable Date beginValue)
      Returns a copy of this immutable component with the specified beginValue, keeping the current end endpoint.

      Sets the begin endpoint. See withValue(DateRange) for the smartUpdate restriction.

      Parameters:
      beginValue - The begin date; null clears the begin endpoint.

      Default: null.

      Returns:
      A modified copy of the this object

    • getEndValue

      @Nullable @Derived default Date getEndValue()
      Returns the end endpoint, or null if unset.

      A derived snapshot of getValue(); mutating the returned Date is not supported, call getValue() for a fresh copy.

      Default: null

    • withEndValue

      default IDaterangebox withEndValue(@Nullable Date endValue)
      Returns a copy of this immutable component with the specified endValue, keeping the current begin endpoint.

      Sets the end endpoint. See withValue(DateRange) for the smartUpdate restriction.

      Parameters:
      endValue - The end date; null clears the end endpoint.

      Default: null.

      Returns:
      A modified copy of the this object

    • withBeginValueInLocalDate

      default IDaterangebox withBeginValueInLocalDate(@Nullable LocalDate beginValue)
      Returns a copy of this immutable component with the specified beginValue taken at start of day in getTimeZone().
      Parameters:
      beginValue - The begin date; null clears the begin endpoint.
      Returns:
      A modified copy of the this object

    • withEndValueInLocalDate

      default IDaterangebox withEndValueInLocalDate(@Nullable LocalDate endValue)
      Returns a copy of this immutable component with the specified endValue taken at start of day in getTimeZone().
      Parameters:
      endValue - The end date; null clears the end endpoint.
      Returns:
      A modified copy of the this object

    • withValueInLocalDate

      default IDaterangebox withValueInLocalDate(@Nullable org.zkoss.zul.LocalDateRange value)
      Returns a copy of this immutable component with the specified value, each end taken at start of day in getTimeZone().
      Parameters:
      value - The range; null clears both ends.
      Returns:
      A modified copy of the this object

    • withBeginValueInLocalDateTime

      default IDaterangebox withBeginValueInLocalDateTime(@Nullable LocalDateTime beginValue)
      Returns a copy of this immutable component with the specified beginValue, interpreted in getTimeZone().
      Parameters:
      beginValue - The begin date-time; null clears the begin endpoint.
      Returns:
      A modified copy of the this object

    • withEndValueInLocalDateTime

      default IDaterangebox withEndValueInLocalDateTime(@Nullable LocalDateTime endValue)
      Returns a copy of this immutable component with the specified endValue, interpreted in getTimeZone().
      Parameters:
      endValue - The end date-time; null clears the end endpoint.
      Returns:
      A modified copy of the this object

    • withValueInLocalDateTime

      default IDaterangebox withValueInLocalDateTime(@Nullable org.zkoss.zul.LocalDateTimeRange value)
      Returns a copy of this immutable component with the specified value, each end interpreted in getTimeZone().
      Parameters:
      value - The range; null clears both ends.
      Returns:
      A modified copy of the this object

    • withBeginValueInZonedDateTime

      default IDaterangebox withBeginValueInZonedDateTime(@Nullable ZonedDateTime beginValue)
      Returns a copy of this immutable component with the specified beginValue (its instant is used).
      Parameters:
      beginValue - The begin date-time; null clears the begin endpoint.
      Returns:
      A modified copy of the this object

    • withEndValueInZonedDateTime

      default IDaterangebox withEndValueInZonedDateTime(@Nullable ZonedDateTime endValue)
      Returns a copy of this immutable component with the specified endValue (its instant is used).
      Parameters:
      endValue - The end date-time; null clears the end endpoint.
      Returns:
      A modified copy of the this object

    • withValueInZonedDateTime

      default IDaterangebox withValueInZonedDateTime(@Nullable org.zkoss.zul.ZonedDateTimeRange value)
      Returns a copy of this immutable component with the specified value (each end's instant is used).
      Parameters:
      value - The range; null clears both ends.
      Returns:
      A modified copy of the this object

    • getFormat

      @Nullable String getFormat()
      Returns the raw date format pattern, or null if none was set (in which case getRealFormat() supplies the locale-derived fallback).

      Default: null

    • withFormat

      IDaterangebox withFormat(@Nullable String format)
      Returns a copy of this immutable component with the specified format.

      Sets the date format pattern applied to both input fields, using java.text.SimpleDateFormat letters (e.g. yyyy/MM/dd). null or "" resets to the locale-aware MEDIUM fallback.

      Note: UiAgent.smartUpdate(Locator, SmartUpdater) is not supported for this property — IDaterangebox.Updater ships the raw attribute while the initial render ships getRealFormat(). Push a whole component with UiAgent.replaceWith(Locator, IComponent) instead.

      Parameters:
      format - The format pattern, or null/"" for the default.

      Default: null.

      Returns:
      A modified copy of the this object

    • getLocale

      @Nullable Locale getLocale()
      Returns the locale used for month/weekday labels and the first-day-of-week, or null (the page/current locale) if unset.

      Default: null

    • withLocale

      IDaterangebox withLocale(@Nullable Locale locale)
      Returns a copy of this immutable component with the specified locale.

      Sets the locale used for month/weekday labels and the first-day-of-week.

      Note: UiAgent.smartUpdate(Locator, SmartUpdater) is not supported for this property — IDaterangebox.Updater ships the raw attribute while the initial render ships locale.toString() plus the localized symbols. Push a whole component with UiAgent.replaceWith(Locator, IComponent) instead.

      Parameters:
      locale - The preferred locale, or null to use the current locale.

      Default: null.

      Returns:
      A modified copy of the this object

    • withLocale

      default IDaterangebox withLocale(@Nullable String locale)
      Returns a copy of this immutable component with the specified locale.

      Sets the locale from its string code (e.g. "zh_TW").

      Parameters:
      locale - The locale code, or null/"" to clear.

      Default: null.

      Returns:
      A modified copy of the this object

    • getTimeZone

      @Nullable TimeZone getTimeZone()
      Returns the time zone used for calendar-day boundary decisions and constraint-bound parsing, or null (the current time zone) if unset.

      Default: null

    • withTimeZone

      IDaterangebox withTimeZone(@Nullable TimeZone timeZone)
      Returns a copy of this immutable component with the specified timeZone.

      Sets the time zone used for calendar-day boundary decisions and for SimpleDateConstraint bound parsing.

      Note: UiAgent.smartUpdate(Locator, SmartUpdater) is not supported for this property — IDaterangebox.Updater ships the raw attribute while the initial render ships DateTimeFormatInputElement.getFormattedTimeZone(timeZone). Push a whole component with UiAgent.replaceWith(Locator, IComponent) instead.

      Parameters:
      timeZone - The preferred time zone, or null to use the current one.

      Default: null.

      Returns:
      A modified copy of the this object

    • withTimeZone

      default IDaterangebox withTimeZone(@Nullable String timeZone)
      Returns a copy of this immutable component with the specified timeZone.

      Sets the time zone from its ID (e.g. "Asia/Tokyo").

      Parameters:
      timeZone - The time zone ID, or null/"" to clear.

      Default: null.

      Returns:
      A modified copy of the this object
      Throws:
      org.zkoss.zk.ui.WrongValueException - if timeZone is not a recognized time zone ID.

    • getConstraint

      @Nullable String getConstraint()
      Returns the SimpleDateConstraint expression applied to both endpoints, or null if none.

      Default: null

    • withConstraint

      IDaterangebox withConstraint(@Nullable String constraint)
      Returns a copy of this immutable component with the specified constraint.

      Sets the constraint from a SimpleDateConstraint expression (e.g. "between 20240101 and 20241231", "no past"), which is applied to both the begin and end values.

      Parameters:
      constraint - The constraint expression, or null to clear.

      Default: null.

      Returns:
      A modified copy of the this object

    • getNumberOfMonths

      default int getNumberOfMonths()
      Returns the number of side-by-side calendar panels shown in the popup.

      Default: the library property org.zkoss.zul.daterangebox.numberOfMonths (2 if unset).

    • withNumberOfMonths

      IDaterangebox withNumberOfMonths(int numberOfMonths)
      Returns a copy of this immutable component with the specified numberOfMonths.

      Sets the number of side-by-side calendar panels shown in the popup.

      Parameters:
      numberOfMonths - The panel count; must be between 1 and the configured maximum (library property org.zkoss.zul.daterangebox.numberOfMonths.max, default 12).
      Returns:
      A modified copy of the this object
      Throws:
      org.zkoss.zk.ui.WrongValueException - if it is outside that range.

    • getAllowEmpty

      @Nullable default String getAllowEmpty()
      Returns which endpoints may be left empty: one of "none", "begin", "end" or "both".

      Default: "both"

    • withAllowEmpty

      IDaterangebox withAllowEmpty(@Nullable String allowEmpty)
      Returns a copy of this immutable component with the specified allowEmpty.

      Sets which endpoints may be left empty.

      Parameters:
      allowEmpty - one of none, begin, end or both.

      Default: "both".

      Returns:
      A modified copy of the this object
      Throws:
      org.zkoss.zk.ui.WrongValueException - if it is not one of the accepted tokens.

    • isShowTime

      @Nullable default Boolean isShowTime()
      Returns whether the popup shows a time picker and the inputs display the time component, or null when it was never set.

      Default: null (unset)

      Tri-state, mirroring Daterangebox's Boolean _showTime: null leaves the decision to the client, which auto-detects a time token in the format; an explicit false suppresses that auto-detection. Only a non-null value reaches the wire, so the three states stay distinguishable.

    • withShowTime

      IDaterangebox withShowTime(@Nullable Boolean showTime)
      Returns a copy of this immutable component with the specified showTime.

      Sets whether the popup shows a time picker. When turned on without an explicit format, " HH:mm" is appended to the effective format (see getRealFormat()).

      Parameters:
      showTime - true to show the time picker, false to suppress it even for a time-bearing format, or null to let the client decide from the format.

      Default: null.

      Returns:
      A modified copy of the this object

    • getMinNights

      default int getMinNights()
      Returns the minimum number of nights required between begin and end. 0 means no minimum.

      Default: 0

    • withMinNights

      IDaterangebox withMinNights(int minNights)
      Returns a copy of this immutable component with the specified minNights.

      Sets the minimum number of nights required between begin and end.

      Parameters:
      minNights - The minimum nights; must be >= 0 and not exceed a non-zero getMaxNights().

      Default: 0.

      Returns:
      A modified copy of the this object
      Throws:
      org.zkoss.zk.ui.WrongValueException - if it is negative, or greater than a configured non-zero maxNights.

    • getMaxNights

      default int getMaxNights()
      Returns the maximum number of nights allowed between begin and end. 0 means unbounded.

      Default: 0

    • withMaxNights

      IDaterangebox withMaxNights(int maxNights)
      Returns a copy of this immutable component with the specified maxNights.

      Sets the maximum number of nights allowed between begin and end.

      Parameters:
      maxNights - The maximum nights; must be >= 0 and not less than a non-zero getMinNights().

      Default: 0.

      Returns:
      A modified copy of the this object
      Throws:
      org.zkoss.zk.ui.WrongValueException - if it is negative, or less than a configured non-zero minNights.

    • getPosition

      @Nullable default String getPosition()
      Returns the popup anchor position token.

      Default: "after_start"

    • withPosition

      IDaterangebox withPosition(@Nullable String position)
      Returns a copy of this immutable component with the specified position.

      Position the calendar popup to the specified location.

      Parameters:
      position - Where to position. Default: after_start. It accepts the same tokens as IPopupBase.Position.
      Returns:
      A modified copy of the this object

    • withPosition

      default IDaterangebox withPosition(IPopupBase.Position position)
      Returns a copy of this immutable component with the specified position.

      Position the calendar popup to the specified location.

      Parameters:
      position - Where to position. Default: IPopupBase.Position.AFTER_START
      Returns:
      A modified copy of the this object

    • isButtonVisible

      default boolean isButtonVisible()
      Returns whether the calendar drop-down button is shown to the right of the inputs.

      Default: true

    • withButtonVisible

      IDaterangebox withButtonVisible(boolean buttonVisible)
      Returns a copy of this immutable component with the specified buttonVisible.

      Sets whether the calendar drop-down button is shown.

      Parameters:
      buttonVisible - false to hide the button.

      Default: true.

      Returns:
      A modified copy of the this object

    • isWeekOfYear

      default boolean isWeekOfYear()
      Returns whether the week-of-year column is shown in the calendar panels.

      Default: false

    • withWeekOfYear

      IDaterangebox withWeekOfYear(boolean weekOfYear)
      Returns a copy of this immutable component with the specified weekOfYear.

      Sets whether the week-of-year column is shown in the calendar panels.

      Parameters:
      weekOfYear - true to show the week-of-year column.

      Default: false.

      Returns:
      A modified copy of the this object

    • isShowTodayLink

      default boolean isShowTodayLink()
      Returns whether the "Today" shortcut link is shown in the day view.

      Default: false

    • withShowTodayLink

      IDaterangebox withShowTodayLink(boolean showTodayLink)
      Returns a copy of this immutable component with the specified showTodayLink.

      Sets whether the "Today" shortcut link is shown in the day view.

      Parameters:
      showTodayLink - true to show the "Today" link.

      Default: false.

      Returns:
      A modified copy of the this object

    • getTodayLinkLabel

      @Nullable default String getTodayLinkLabel()
      Returns the label of the "Today" shortcut shown in the popup footer.

      Default: the localized MZul.CALENDAR_TODAY ("Today" in English)

    • withTodayLinkLabel

      IDaterangebox withTodayLinkLabel(@Nullable String todayLinkLabel)
      Returns a copy of this immutable component with the specified todayLinkLabel.

      Sets the label of the "Today" shortcut shown in the popup footer.

      Parameters:
      todayLinkLabel - The label of the link to jump to today, or null — Daterangebox.setTodayLinkLabel(String) accepts a null and the C2I conversion has to be able to carry it back.

      Default: "Today".

      Returns:
      A modified copy of the this object

    • getInputAttributes

      @Nullable Map<String,String> getInputAttributes()
      Returns the additional attributes which is set by withInputAttributes(Map)

      Default: null.

    • withInputAttributes

      IDaterangebox withInputAttributes(@Nullable Map<String,? extends String> inputAttributes)
      Returns a copy of this immutable component with the specified inputAttributes.

      Sets some additional attributes to both range inputs at client. It is also how to specify the HTML autocomplete attribute required by WCAG 1.3.5 (Identify Input Purpose) when this component collects information about the user, for example autocomplete=bday.

      Parameters:
      inputAttributes - A Map with attribute names as the keys.

      Default: null.

      Returns:
      A modified copy of the this object

    • isLenient

      default boolean isLenient()
      Returns whether date parsing is lenient. With lenient parsing, inputs that do not exactly match the format may be interpreted heuristically.

      Default: true

    • withLenient

      IDaterangebox withLenient(boolean lenient)
      Returns a copy of this immutable component with the specified lenient.

      Sets whether date parsing is lenient.

      Parameters:
      lenient - false to require inputs to match the format exactly.

      Default: true.

      Returns:
      A modified copy of the this object

    • isStrictDate

      default boolean isStrictDate()
      Returns whether strict date validation is enabled, rejecting impossible dates such as "Nov 31".

      Default: false

    • withStrictDate

      IDaterangebox withStrictDate(boolean strictDate)
      Returns a copy of this immutable component with the specified strictDate.

      Sets whether strict date validation is enabled.

      Parameters:
      strictDate - true to refuse dates like "Jan 0".

      Default: false.

      Returns:
      A modified copy of the this object

    • getSeparator

      default String getSeparator()
      Returns the separator rendered between the two date inputs.

      Default: the library property org.zkoss.zul.daterangebox.separator ("~" if unset)

    • withSeparator

      IDaterangebox withSeparator(String separator)
      Returns a copy of this immutable component with the specified separator.

      Sets the separator string rendered between the two date inputs.

      Note: unlike Daterangebox.setSeparator(String), null is not accepted here. To fall back to getSeparator()'s default chain, build a fresh instance without setting a separator.

      Parameters:
      separator - The separator string.

      Default: "~".

      Returns:
      A modified copy of the this object

    • getPlaceholder

      @Nullable String getPlaceholder()
      Returns the placeholder applied to both inputs when no per-input placeholder is set, or null if none.

      Default: null

    • withPlaceholder

      IDaterangebox withPlaceholder(@Nullable String placeholder)
      Returns a copy of this immutable component with the specified placeholder.

      Sets the placeholder shown in both inputs when empty.

      Parameters:
      placeholder - The placeholder text, or null to clear.

      Default: null.

      Returns:
      A modified copy of the this object

    • getBeginPlaceholder

      @Nullable String getBeginPlaceholder()
      Returns the placeholder for the begin input, or null if none.

      Default: null

    • withBeginPlaceholder

      IDaterangebox withBeginPlaceholder(@Nullable String beginPlaceholder)
      Returns a copy of this immutable component with the specified beginPlaceholder.

      Sets the placeholder shown in the begin input when empty.

      Parameters:
      beginPlaceholder - The placeholder text, or null to clear.

      Default: null.

      Returns:
      A modified copy of the this object

    • getEndPlaceholder

      @Nullable String getEndPlaceholder()
      Returns the placeholder for the end input, or null if none.

      Default: null

    • withEndPlaceholder

      IDaterangebox withEndPlaceholder(@Nullable String endPlaceholder)
      Returns a copy of this immutable component with the specified endPlaceholder.

      Sets the placeholder shown in the end input when empty.

      Parameters:
      endPlaceholder - The placeholder text, or null to clear.

      Default: null.

      Returns:
      A modified copy of the this object

    • isHoverPreview

      default boolean isHoverPreview()
      Returns whether hovering a candidate end date previews the range in the calendar.

      Default: the library property org.zkoss.zul.daterangebox.hoverPreview (true if unset)

    • withHoverPreview

      IDaterangebox withHoverPreview(boolean hoverPreview)
      Returns a copy of this immutable component with the specified hoverPreview.

      Sets whether hovering a candidate end date previews the range.

      Parameters:
      hoverPreview - false to disable the hover preview.

      Default: true.

      Returns:
      A modified copy of the this object

    • of

      static IDaterangebox of(org.zkoss.zul.DateRange value)
      Returns the instance with the given range.
      Parameters:
      value - The initial range

    • of

      static IDaterangebox of(@Nullable Date beginValue, @Nullable Date endValue)
      Returns the instance with the given endpoints.
      Parameters:
      beginValue - The begin date, or null
      endValue - The end date, or null

    • ofFormat

      static IDaterangebox ofFormat(String format)
      Returns the instance with the given format.
      Parameters:
      format - The daterangebox format

    • ofConstraint

      static IDaterangebox ofConstraint(String constraint)
      Returns the instance with the given constraint.
      Parameters:
      constraint - The daterangebox constraint

    • ofId

      static IDaterangebox ofId(String id)
      Returns the instance with the given id.
      Parameters:
      id - The id to identify this component