Package org.zkoss.stateless.sul

Interface IDatebox

All Superinterfaces:
IAnyGroup<IDatebox>, IChildrenOfInputgroup<IDatebox>, IComponent<IDatebox>, IDateTimeFormatInputElement<IDatebox>, IFormatInputElement<IDatebox,Date>, IHtmlBasedComponent<IDatebox>, IInputElement<IDatebox,Date>, IReadonly<IDatebox>, IXulElement<IDatebox>
public interface IDatebox extends IDateTimeFormatInputElement<IDatebox>, IAnyGroup<IDatebox>
Immutable Datebox component

An edit box for holding a date.

The default format (IFormatInputElement.getFormat()) depends on DateFormats.getDateFormat(int, Locale, String) and the current user's locale (unless IDateTimeFormatInputElement.withLocale(Locale) is assigned. Please refer to withFormat(String) for more details.

Support @Action

Name Action Type
onTimeZoneChange Denotes the time zone of the component is changed by user.

Mouseless Entry

  • Alt+DOWN to pop up the calendar.
  • LEFT, RIGHT, UP and DOWN to change the selected day from the calendar.
  • ENTER to activate the selection by copying the selected day to the datebox control.
  • Alt+UP or ESC to give up the selection and close the calendar.

Constraint

You could specify what value to accept for input controls by use of the constraint attribute. It could be a combination of no empty, no future, no past, and no today.

It also supports an interval of dates. For example,

 
 IDatebox.ofConstraint("between 20071225 and 20071203");
 IDatebox.ofConstraint("before 20071225");
 IDatebox.ofConstraint("after 20071225");

Notices: The format of the date in the constraint must be yyyMMdd. It is independent of the locale. The date specified in the above constraints (before/after/between) is included. For example, "before 20071225" includes December 25, 2007 and any day before it, and "after 20110305" includes March 5, 2011 and any day after it.

Displayed Time Zones

The image below shows the new Datebox functionality which allows the user to change the time zone to other predefined time zones.

 
 IDatebox.ofFormat("M/d/yy KK:mm:ss a").withWidth("150px")
     .withDisplayedTimeZones("GMT+12", "GMT+8").withTimeZone("GMT+8")
     .withTimeZonesReadonly(false)

Format

You are able to format the field by providing specifying the attribute with a formatting string. The default value is null. When the formatting of the datebox is null, it means the date will be outputted using the format yyyy/MM/dd.

IDatebox.ofFormat("MM/dd/yyyy");

Length Option

In addition to specifying the format explicitly, you could specify the length option. It supports four different length options mentioned at DateFormat, such as short, medium, long, and full.

In addition, you could specify the format for both date and time by using the syntax:

withFormat("option_for_date+option_for_time") For example, 
IDatebox.ofFormat("medium+full")

Multiple-Eras Calendar

Datebox can display some multiple-eras calendar systems including:

  • ROC (Taiwan): withLocale("zh-TW-u-ca-roc");
  • Japan: withLocale("ja-JP-u-ca-japanese");
  • Buddhist: withLocale("th-TH-u-ca-buddhist");

Position

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

The First Day of the Week

The first day of the week is decided by the locale (actually the return value of the getFirstDayOfWeek method in the Calendar). You can also control the first day of the week by the use of the session attribute and the library property. Please refer to The First Day of the Week for details.

2DigitYearStart

You can control the 2DigitYearStart by the use of the library property, for example,

 <library-property>
     <name>org.zkoss.web.preferred.2DigitYearStart</name>
     <value>1950</value>
 </library-property>
Author:
katherine
See Also:
  • Datebox

  • Field Details

    • DEFAULT

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

  • Method Details

    • getWidgetClass

      default String getWidgetClass()
      Returns the client widget class.

      Default: "zul.db.Datebox"

      Specified by:
      getWidgetClass in interface IComponent<IDatebox>

    • getDisplayedTimeZones

      @Nullable default List<TimeZone> getDisplayedTimeZones()
      Returns a list of the time zones that will be displayed at the client and allow user to select.

      Default: null

    • withDisplayedTimeZones

      IDatebox withDisplayedTimeZones(@Nullable Iterable<? extends TimeZone> displayedTimeZones)
      Returns a copy of this immutable component with the specified displayedTimeZones.

      Sets a list of the time zones that will be displayed at the client and allow user to select.

      If the IDateTimeFormatInputElement.getTimeZone() is null, the first time zone in the list is assumed.

      Parameters:
      displayedTimeZones - A list of the time zones to display.

      Default: null.

      Returns:
      A modified copy of the this object

    • withDisplayedTimeZones

      default IDatebox withDisplayedTimeZones(TimeZone... displayedTimeZones)
      Returns a copy of this immutable component with the specified displayedTimeZones.

      Sets a list of the time zones that will be displayed at the client and allow user to select.

      If the IDateTimeFormatInputElement.getTimeZone() is null, the first time zone in the list is assumed.

      Parameters:
      displayedTimeZones - A list of the time zones to display.

      Default: null.

      Returns:
      A modified copy of the this object

    • withDisplayedTimeZones

      default IDatebox withDisplayedTimeZones(String displayedTimeZones)
      Returns a copy of this immutable component with the specified displayedTimeZones.

      Sets a list of the time zones that will be displayed at the client and allow user to select.

      If the IDateTimeFormatInputElement.getTimeZone() is null, the first time zone in the list is assumed.

      Parameters:
      displayedTimeZones - A list of the time zones to display.

      Default: null.

      Returns:
      A modified copy of the this object

    • withDisplayedTimeZones

      default IDatebox withDisplayedTimeZones(String... displayedTimeZones)
      Returns a copy of this immutable component with the specified displayedTimeZones.

      Sets a list of the time zones that will be displayed at the client and allow user to select.

      If the IDateTimeFormatInputElement.getTimeZone() is null, the first time zone in the list is assumed.

      Parameters:
      displayedTimeZones - A list of the time zones to display.

      Default: null.

      Returns:
      A modified copy of the this object

    • getDefaultDateTime

      @Nullable LocalDateTime getDefaultDateTime()
      Returns the default datetime if the value is empty.

      Default: null (means current datetime)

    • withDefaultDateTime

      IDatebox withDefaultDateTime(@Nullable LocalDateTime defaultDateTime)
      Returns a copy of this immutable component with the specified defaultDateTime.

      Sets the default datetime if the value is empty.

      Parameters:
      defaultDateTime - Default datetime. null means current datetime.

      Default: null.

      Returns:
      A modified copy of the this object

    • isButtonVisible

      default boolean isButtonVisible()
      Returns whether the button (on the right of the timebox) is visible.

      Default: true.

    • withButtonVisible

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

      Sets whether the button (on the right of the timebox) is visible.

      Parameters:
      buttonVisible - false to disable the button visibility.

      Default: true.

      Returns:
      A modified copy of the this object

    • isLenient

      default boolean isLenient()
      Returns whether date/time parsing is to be lenient or not.

      With lenient parsing, the parser may use heuristics to interpret inputs that do not precisely match this object's format. With strict parsing, inputs must match this object's format.

      Default: true

    • withLenient

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

      Sets whether date/time parsing is to be lenient or not.

      Parameters:
      lenient - false to disable date/time parsing is to be lenient.

      Default: true.

      Returns:
      A modified copy of the this object

    • isTimeZonesReadonly

      default boolean isTimeZonesReadonly()
      Returns whether the list of the time zones to display is readonly. If readonly, the user cannot change the time zone at the client.

      Default: false

    • withTimeZonesReadonly

      IDatebox withTimeZonesReadonly(boolean timeZonesReadonly)
      Returns a copy of this immutable component with the specified timeZonesReadonly.

      Sets whether the list of the time zones to display is readonly. If readonly, the user cannot change the time zone at the client.

      Parameters:
      timeZonesReadonly - true to make time zones options display as readonly.

      Default: false.

      Returns:
      A modified copy of the this object

    • isWeekOfYear

      default boolean isWeekOfYear()
      Returns whether enable to show the week number in the current calendar or not.

      Default: false

    • withWeekOfYear

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

      Sets whether enable to show the week number in the current calendar or not. (ZK EE only)

      Parameters:
      weekOfYear - true to show the week number in the current calendar.

      Default: false.

      Returns:
      A modified copy of the this object

    • getPosition

      default String getPosition()
      Returns:
      the datebox popup position

    • withPosition

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

      Position the popup datebox to the specified location.

      Parameters:
      position - Where to position. Default: after_start Allowed values:
      • before_start
        the component appears above the anchor, aligned to the left.
      • before_center
        the component appears above the anchor, aligned to the center.
      • before_end
        the component appears above the anchor, aligned to the right.
      • after_start
        the component appears below the anchor, aligned to the left.
      • after_center
        the component appears below the anchor, aligned to the center.
      • after_end
        the component appears below the anchor, aligned to the right.
      • start_before
        the component appears to the left of the anchor, aligned to the top.
      • start_center
        the component appears to the left of the anchor, aligned to the middle.
      • start_after
        the component appears to the left of the anchor, aligned to the bottom.
      • end_before
        the component appears to the right of the anchor, aligned to the top.
      • end_center
        the component appears to the right of the anchor, aligned to the middle.
      • end_after
        the component appears to the right of the anchor, aligned to the bottom.
      • overlap/top_left
        the component overlaps the anchor, with anchor and element aligned at top-left.
      • top_center
        the component overlaps the anchor, with anchor and element aligned at top-center.
      • overlap_end/top_right
        the component overlaps the anchor, with anchor and element aligned at top-right.
      • middle_left
        the component overlaps the anchor, with anchor and element aligned at middle-left.
      • middle_center
        the component overlaps the anchor, with anchor and element aligned at middle-center.
      • middle_right
        the component overlaps the anchor, with anchor and element aligned at middle-right.
      • overlap_before/bottom_left
        the component overlaps the anchor, with anchor and element aligned at bottom-left.
      • bottom_center
        the component overlaps the anchor, with anchor and element aligned at bottom-center.
      • overlap_after/bottom_right
        the component overlaps the anchor, with anchor and element aligned at bottom-right.
      • at_pointer
        the component appears with the upper-left aligned with the mouse cursor.
      • after_pointer
        the component appears with the top aligned with the bottom of the mouse cursor, with the left side of the component at the horizontal position of the mouse cursor.
      Returns:
      A modified copy of the this object

    • withPosition

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

      Position the popup datebox to the specified location.

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

    • isStrictDate

      default boolean isStrictDate()
      Returns whether date/time should be strict or not.

      Default: false.

    • withStrictDate

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

      Sets whether date/time should be strict or not.

      If true, any invalid input like "Jan 0" or "Nov 31" would be refused.

      If false, it won't be checked and let lenient parsing decide.

      Parameters:
      strictDate - true to make date/time be strict.

      Default: false.

      Returns:
      A modified copy of the this object

    • getShowTodayLink

      default boolean getShowTodayLink()
      Returns whether enable to show the link that jump to today in day view

      Default: false

    • withShowTodayLink

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

      Sets whether enable to show the link that jump to today in day view

      Parameters:
      showTodayLink - true to show a link to jump to today.

      Default: false.

      Returns:
      A modified copy of the this object

    • getTodayLinkLabel

      default String getTodayLinkLabel()
      Returns the label of the link that jump to today in day view

      Default: "Today"

    • withTodayLinkLabel

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

      Sets the label of the link that jump to today in day view.

      Parameters:
      todayLinkLabel - The label of the link to jump to today.

      Default: "Today".

      Returns:
      A modified copy of the this object

    • getSelectLevel

      default String getSelectLevel()
      Returns the level that a user can select.

      Default: "day"

    • withSelectLevel

      IDatebox withSelectLevel(String selectLevel)
      Returns a copy of this immutable component with the specified selectLevel.

      Sets the level that a user can select.

      Parameters:
      selectLevel - The level that a user can select.

      Default: "day".

      Returns:
      A modified copy of the this object

    • getClosePopupOnTimezoneChange

      default boolean getClosePopupOnTimezoneChange()
      Returns whether to auto close the datebox popup after changing the timezone.

      Default: true

    • withClosePopupOnTimezoneChange

      IDatebox withClosePopupOnTimezoneChange(boolean closePopupOnTimezoneChange)
      Returns a copy of this immutable component with the specified closePopupOnTimezoneChange.

      Sets whether to auto close the datebox popup after changing the timezone.

      Parameters:
      closePopupOnTimezoneChange - Whether to auto close the datebox popup after changing the timezone

      Default: true.

      Returns:
      A modified copy of the this object

    • getCols

      default int getCols()
      Returns the cols which determines the visible width, in characters.

      Default: 11 (non-positive means the same as browser's default).

      Specified by:
      getCols in interface IInputElement<IDatebox,Date>

    • withFormat

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

      Sets the date format.

      You could specify one of the following reserved words, and DateFormats.getDateFormat(int, Locale, String) or DateFormats.getDateTimeFormat(int, int, java.util.Locale, java.lang.String) will be used to retrieve the real format.

      short DateFormats.getDateFormat(int, Locale, String) with DateFormat.SHORT
      medium DateFormats.getDateFormat(int, Locale, String) with DateFormat.MEDIUM
      long DateFormats.getDateFormat(int, Locale, String) with DateFormat.LONG
      full DateFormats.getDateFormat(int, Locale, String) with DateFormat.FULL

      To specify a date/time format, you could specify two reserved words, separated by a plus. For example, "medium+short" means DateFormats.getDateTimeFormat(int, int, java.util.Locale, java.lang.String) with the medium date styling and the short time styling.

      In additions, the format could be a combination of the following pattern letters:

      Letter Date or Time Component Presentation Examples
      G Era designator Text AD
      y Year Year 1996; 96
      M Month in year Month July; Jul; 07
      w Week in year (starting at 1) Number 27
      W Week in month (starting at 1) Number 2
      D Day in year (starting at 1) Number 189
      d Day in month (starting at 1) Number 10
      F Day of week in month Number 2
      E Day in week Text Tuesday; Tue
      Specified by:
      withFormat in interface IFormatInputElement<IDatebox,Date>
      Parameters:
      format - The format of the datebox.

      Default: Datebox.DEFAULT_FORMAT.

      Returns:
      A modified copy of the this object

    • of

      static IDatebox of(Date date)
      Return the instance of the given date.
      Parameters:
      date - The date to indicate the value for datebox.

    • of

      static IDatebox of(Temporal date)
      Return the instance of the given date.
      Parameters:
      date - The date to indicate the value for datebox.

    • of

      static IDatebox of(String format, Date date)
      Return the instance of the given format and date.
      Parameters:
      format - The format of the datebox
      date - The date to indicate the value for datebox.

    • of

      static IDatebox of(String format, Temporal date)
      Return the instance of the given format and date.
      Parameters:
      format - The format of the datebox
      date - The date to indicate the value for datebox.

    • ofLocale

      static IDatebox ofLocale(String locale)
      Returns the instance with the given locale.
      Parameters:
      locale - The datebox locale

    • ofLocale

      static IDatebox ofLocale(Locale locale)
      Returns the instance with the given locale.
      Parameters:
      locale - The datebox locale

    • ofCols

      static ITimebox ofCols(int cols)
      Returns the instance with the given cols.
      Parameters:
      cols - The cols which determines the visible width

    • ofConstraint

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

    • ofFormat

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

    • ofId

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