Datebox"

From Documentation
 
(34 intermediate revisions by 5 users not shown)
Line 9: Line 9:
  
 
= Employment/Purpose =
 
= Employment/Purpose =
An edit box for holding a date. After click on the calender, a <tt>calender</tt> will pop-up for inputting date.
+
An edit box for holding a date. After click on the calender, a <code>calender</code> will pop-up for inputting date.
  
= Mouseless Entry <tt>datebox</tt> =
+
= Keyboard Navigation <code>datebox</code> =
  
* Alt+DOWN to pop up the <tt>calendar.</tt>
+
* Alt+DOWN to pop up the <code>calendar.</code>
  
* LEFT, RIGHT, UP and DOWN to change the selected day from the <tt>calendar.</tt>
+
* LEFT, RIGHT, UP and DOWN to change the selected day from the <code>calendar.</code>
  
* ENTER to activate the selection by copying the selected day to the <tt>datebox</tt> control.
+
* ENTER to activate the selection by copying the selected day to the <code>datebox</code> control.
  
* Alt+UP or ESC to give up the selection and close the <tt>calendar</tt>.
+
* Alt+UP or ESC to give up the selection and close the <code>calendar</code>.
  
  
 
= Customization =
 
= Customization =
  
Since 5.0.3, the rendering of the calendar can be customized at the client by providing JavaScript code that overrides <javadoc directory="jsdoc">zul.db.Renderer</javadoc>.
+
{{versionSince| 5.0.3}} You can customize the rendering of the calendar at the client by JavaScript code that overrides <javadoc directory="jsdoc">zul.db.Renderer</javadoc>.
  
 
= Example =
 
= Example =
Line 33: Line 33:
 
<source lang="xml" >
 
<source lang="xml" >
 
  <datebox lenient="true" buttonVisible="false" />
 
  <datebox lenient="true" buttonVisible="false" />
  <datebox lenient="false" compact="false" buttonVisible="true" />
+
  <datebox lenient="false" buttonVisible="true" />
 
</source>
 
</source>
  
 
+
{{IntegrateMomentjs}}
  
 
=Properties and Features=
 
=Properties and Features=
 
== Constraint ==
 
== Constraint ==
You could specify what value to accept for input controls by the use of the <tt>constraint </tt>property.
+
You can specify the date range to accept by the <code>constraint </code> property with one or multiple following values:
It could be a combination of <tt>no empty</tt>, <tt>no future</tt>, <tt>no past</tt>, <tt>no today</tt>.
+
* <code>no empty</code>
 +
* <code>no future</code>
 +
* <code>no past</code>
 +
* <code>no today</code>.
 +
 
  
To specify two or more constraints, use comma to separate them as follows.
+
It also supports an interval of dates. For example,
  
 
<source lang="xml" >
 
<source lang="xml" >
<datebox constraint="no past,no empty"/>
+
<datebox constraint="between 20071225 and 20071203"/>
 +
<datebox constraint="before 20071225"/>
 +
<datebox constraint="after 20071225"/>
 
</source>
 
</source>
  
If you prefer to display different message to the default one, you can append the error message to the constraint with a colon.
+
'''Notices'''
 +
 
 +
# The format of the date in the constraint must be <code>yyyMMdd</code>. It is independent of the locale.
 +
# The date specified in the above constraints (before/after/between) is ''included''. For example, <code>"before 20071225"</code> includes December 25, 2007 and any day before it, and <code>"after 20110305"</code> includes March 5, 2011 and any day after it.
 +
# The constraint is actually represented with an instance of the <code>org.zkoss.zul.SimpleDateConstraint</code> class. You can retrieve the parsed beginning and ending date with the <code>getBeginDate</code> and <code>getEndDate</code> methods.
  
<source lang="xml" >
+
<source lang="java" >
<datebox constraint="no empty, no future: now or never"/>
+
((SimpleDateConstraint)datebox.getConstraint()).getBeginDate();
 
</source>
 
</source>
  
Notes:
+
=== Multiple Constraints===
* The error message, if specified, must be the last element and start with colon.
+
To specify two or more constraints, use a comma to separate them as follows:
* To support multiple languages, you could use the 「l」 function as depicted in the '''Internationalization''' chapter.
 
  
 
<source lang="xml" >
 
<source lang="xml" >
<datebox constraint="no empty, no future: ${c:l('err.date.nowornever')}"/>
+
<datebox constraint="no past,no empty"/>
 
</source>
 
</source>
  
In addition to the constraints described in the above section (such as <tt>no future</tt> and regular expressions), the <tt>datebox</tt> supports a wide range of dates. For example,
+
=== Custom Error Message ===
 +
If you prefer to display a different message from the default one, you can append the error message to the constraint with a colon.
  
 
<source lang="xml" >
 
<source lang="xml" >
<datebox constraint="between 20071225 and 20071203"/>
+
<datebox constraint="no empty, no future: now or never"/>
<datebox constraint="before 20071225"/>
 
<datebox constraint="after 20071225"/>
 
 
</source>
 
</source>
  
Notices
+
Notes:
 +
* The error message, if specified, must be the last element and start with a colon.
 +
* To support multiple languages, you could use the 「l」 function as depicted in the '''Internationalization''' chapter.
  
# The format of the date in the constraint is <tt>yyyMMdd</tt>. It is independent of the locale.
+
<source lang="xml" >
# The date specified in the above constraints (before/after/between) is ''included''. For example, <tt>"before 20071225"</tt> includes December 25, 2007 and any day before it, and <tt>"after 20110305"</tt> includes March 5, 2011 and any day after it.
+
<datebox constraint="no empty, no future: ${c:l('err.date.nowornever')}"/>
# The constraint is actually represented with an instance of the <tt>org.zkoss.zul.SimpleDateConstraint</tt> class. You can retrieve the parsed beginning and ending date with the <tt>getBeginDate</tt> and <tt>getEndDate</tt> methods.
 
 
 
<source lang="java" >
 
((SimpleDateConstraint)datebox.getConstraint()).getBeginDate();
 
 
</source>
 
</source>
  
Line 92: Line 98:
  
 
== Format ==
 
== Format ==
You are able to format the field by providing specifying the attribute with a formatting string. The default value is <tt>null</tt>. When the formatting of the <tt>datebox</tt> is null, it means the date will be outputted using the format <tt>yyyy/MM/dd</tt>.  
+
You are able to format the field by providing specifying the attribute with a formatting string. The default value is <code>null</code>. When the formatting of the <code>datebox</code> is null, it means the date will be outputted using the format <code>yyyy/MM/dd</code>.  
  
 
<source lang="xml" >
 
<source lang="xml" >
Line 98: Line 104:
 
</source>
 
</source>
  
Like any other properties, you are able change the format dynamically, as depicted below.
+
Like any other properties, you are able to change the format dynamically, as depicted below.
  
 
<source lang="xml" >
 
<source lang="xml" >
Line 105: Line 111:
 
</source>
 
</source>
  
In addition to specifying the format explicitly, you could specify the styling<ref>The styling is available since 5.0.7</ref>. There are four different styling: short, medium, long and full (representing the styling of java.text.DateFormat). For example, you could specify the styling rather than the real format as follows.
+
=== Length Option ===
 +
{{versionSince | 5.0.7}}
 +
 
 +
In addition to specifying the format explicitly, you could specify the length option. It supports four different length options mentioned at [http://docs.oracle.com/javase/7/docs/api/java/text/DateFormat.html java.text.DateFormat]:  
 +
* short
 +
* medium
 +
* long
 +
* full
 +
For example, you could specify the styling rather than the real format as follows.
  
 
<source lang="xml">
 
<source lang="xml">
Line 112: Line 126:
 
</source>
 
</source>
  
Then the real format of the datebox will be decided at run time depending on the configuration. For more information, please refer to [[ZK Developer's Reference/Internationalization/Date and Time Formatting|ZK Developer's Reference: Date and Time Formatting]].
+
Then the real format of the datebox will be decided at run-time depending on the configuration. For more information, please refer to [[ZK Developer's Reference/Internationalization/Date and Time Formatting|ZK Developer's Reference: Date and Time Formatting]].
  
In addition, you could specify the format with both date and time by using the syntax: <tt>''styling_for_date''+''styling_for_time''</tt>. For example,
+
In addition, you could specify the format for both date and time by using the syntax:  
 +
<source lang="XML">
 +
format="option_for_date+option_for_time"
 +
</source>
 +
For example,
  
 
<source lang="xml">
 
<source lang="xml">
Line 120: Line 138:
 
</source>
 
</source>
  
<blockquote>
+
==== Warning ====
----
+
Because [http://openjdk.java.net/jeps/252 Java default locale provider changes since JDK 9], the built-in formats (e.g. <code> long</code>) for some locales might change since JDK 9. We recommend you to use a fixed format pattern.
<references/>
+
 
</blockquote>
+
=== Validation ===
 +
If a user's input doesn't match the specified format, a Datebox will show an error message. It's a client-side validation.
  
 
== Locale ==
 
== Locale ==
 +
Default: depends on the current locale (i.e., <javadoc method="getCurrent()" >org.zkoss.util.Locales</javadoc>) at run-time
  
By default, the real format depends on the current locale (i.e., <javadoc method="getCurrent()">org.zkoss.util.Locales</javadoc>). However, you could specify the locale for an individual instance such as:
+
You can enforce the locale for an individual component such as:
  
 
<source lang="xml">
 
<source lang="xml">
<datebox format="medium+full" locale="de_DE"/>
+
<datebox locale="de-DE" format="full"/>
<datebox format="long" locale="fr"/>
+
<datebox locale="fr" format="full"/>
 
</source>
 
</source>
 +
 +
=== Multiple-Eras Calendar ===
 +
{{versionSince| 9.6.0}}
 +
Datebox can display some multiple-eras calendar systems including:
 +
* ROC(Taiwan): <code>locale="zh-TW-u-ca-roc"</code>
 +
* Japan: <code>locale="ja-JP-u-ca-japanese"</code>
 +
* Buddhist: <code>locale="th-TH-u-ca-buddhist"</code>
 +
 +
[[File:Roc-calendar.jpg]]
 +
[[File:jp-calendar.jpg]]
 +
[[File:buddhist-calendar.jpg]]
 +
 +
See [https://www.oracle.com/java/technologies/javase/jdk8-jre8-suported-locales.html complete locale list].
 +
 +
Reference: [https://docs.oracle.com/javase/8/docs/api/java/time/chrono/Era.html Era]
 +
 +
== Position ==
 +
{{versionSince| 8.0.3}}
 +
 +
By default, the popup position is  set to <code>after_start</code>, for other possible popup positions please refer to [[ZK_Component_Reference/Essential_Components/Popup#Position|Popup#Position]].
  
 
== The First Day of the Week ==
 
== The First Day of the Week ==
 +
The first day of the week is decided by the locale by default. (actually the return value of the <code>getFirstDayOfWeek</code> method in the <code>java.util.Calendar</code>).
 +
 +
{{versionSince| 5.0.3}}
 +
You can control the first day of the week by the use of the session attribute and the library property. Please refer to [[ZK_Developer%27s_Reference/Internationalization/The_First_Day_of_the_Week|The First Day of the Week]] for details.
  
The first day of the week is decided by the locale (actually the return value of the <tt>getFirstDayOfWeek</tt> method in the <tt>java.util.Calendar</tt>).
+
== 2DigitYearStart ==
 +
{{versionSince| 8.6.2}}
  
Since 5.0.3, you can control the first day of the week by the use of the session attribute and the library property. Please refer to [[ZK_Developer%27s_Reference/Internationalization/The_First_Day_of_the_Week|The First Day of the Week]] for details.
+
You can control the 2DigitYearStart by the use of the library property[[ZK_Configuration_Reference/zk.xml/The_Library_Properties/org.zkoss.web.preferred.2DigitYearStart |org.zkoss.web.preferred.2DigitYearStart]].
  
 
== Show Week Number ==
 
== Show Week Number ==
 +
{{ZK EE}}
 +
{{versionSince | 6.5.0}}
 +
 
Datebox supports to show a week number of the year in a calendar.
 
Datebox supports to show a week number of the year in a calendar.
[ZK EE]
+
 
[Since 6.5.0]
 
  
 
[[Image:ZKComRef_Datebox_Week_Of_Year.PNG]]
 
[[Image:ZKComRef_Datebox_Week_Of_Year.PNG]]
Line 154: Line 201:
 
Datebox supports a link to jump back to the date of today quickly
 
Datebox supports a link to jump back to the date of today quickly
  
[Since 8.0.0]
+
{{versionSince| 8.0.0}}
  
 
[[Image:ZKComRef_Datebox_Link_Of_Today.PNG]]
 
[[Image:ZKComRef_Datebox_Link_Of_Today.PNG]]
Line 162: Line 209:
 
</source>
 
</source>
 
The format is the same with that specified on format attribute
 
The format is the same with that specified on format attribute
 +
 +
 +
== Show Timebox ==
 +
 +
By default, there is no Timebox in the popup Calendar. If the specified <code>format</code> attribute contains a time format (like below), it will show a Timebox at the bottom of the popup Calendar.
 +
 +
<source lang='xml'>
 +
<datebox format="yyyy-MM-dd HH:mm"/>
 +
</source>
 +
 +
== Monthly / yearly option ==
 +
{{versionSince|9.5.1}}
 +
Default: <code>day</code>
 +
 +
You can specify the <code>selectLevel</code> attribute to restrict the date granularity users can select. For example, you can limit users to just select a month, it doesn't show the day view to users to choose a day.
 +
 +
Available values are:
 +
* <code>year</code>
 +
* <code>month</code>
 +
* <code>day</code>.
 +
 +
<source lang='xml'>
 +
<datebox format="yyyy" selectLevel="year"/>
 +
</source>
 +
 +
== Close Popup OnTimezoneChange ==
 +
{{versionSince|9.6.0}}
 +
 +
Datebox supports switching whether to auto close the datebox popup after changing the timezone.
 +
 +
example:
 +
<source lang="xml">
 +
<datebox closePopupOnTimezoneChange="false" displayedTimeZones="GMT+12,GMT+8" timeZone="GMT+8" timeZonesReadonly="false"/>
 +
</source>
  
 
=Inherited Functions=
 
=Inherited Functions=
Line 169: Line 250:
 
=Supported Events=
 
=Supported Events=
  
{| border="1" | width="100%"
+
{| class='wikitable' | width="100%"
 
! <center>Name</center>
 
! <center>Name</center>
 
! <center>Event Type</center>
 
! <center>Event Type</center>
 
|-
 
|-
| <center><tt>onTimeZoneChange</tt></center>
+
| <center><code>onTimeZoneChange</code></center>
 
| '''Event:''' <javadoc>org.zkoss.zk.ui.event.Event</javadoc>
 
| '''Event:''' <javadoc>org.zkoss.zk.ui.event.Event</javadoc>
 
Denotes the time zone of the component is changed by user.
 
Denotes the time zone of the component is changed by user.
Line 181: Line 262:
 
=Supported Molds=
 
=Supported Molds=
 
Available molds of a component are defined in lang.xml embedded in zul.jar.
 
Available molds of a component are defined in lang.xml embedded in zul.jar.
{| border="1" | width="100%"
+
{| class='wikitable' | width="100%"
 
! <center>Name</center>
 
! <center>Name</center>
 
! <center>Snapshot</center>
 
! <center>Snapshot</center>
Line 190: Line 271:
 
| <center>rounded</center>
 
| <center>rounded</center>
 
|[[Image:datebox_mold_rounded.png ]]
 
|[[Image:datebox_mold_rounded.png ]]
[Since 5.0.0]
+
{{versionSince| 5.0.0}}
 
|}
 
|}
  
 
=Supported Children=
 
=Supported Children=
  
{| border="1" | width="100%"
+
{| class='wikitable' | width="100%"
 
! <center>Name</center>
 
! <center>Name</center>
 
! <center>Event Type</center>
 
! <center>Event Type</center>
Line 205: Line 286:
 
=Use Cases=
 
=Use Cases=
  
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Description !! Example Location
 
! Version !! Description !! Example Location
 
|-
 
|-
Line 215: Line 296:
 
=Version History=
 
=Version History=
 
{{LastUpdated}}
 
{{LastUpdated}}
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Date !! Content
 
! Version !! Date !! Content
 
|-
 
|-
Line 236: Line 317:
 
| 6.5.0
 
| 6.5.0
 
| June, 2012
 
| June, 2012
| [http://tracker.zkoss.org/browse/ZK-1175 ZK-1175]: Calendar support show week number
+
| [https://tracker.zkoss.org/browse/ZK-1175 ZK-1175]: Calendar support show week number
 +
|-
 +
| 9.5.1
 +
| October 2020
 +
| [https://tracker.zkoss.org/browse/ZK-3289 ZK-3289]: Monthly / yearly options for datebox.
 
|}
 
|}
  
 
{{ZKComponentReferencePageFooter}}
 
{{ZKComponentReferencePageFooter}}

Latest revision as of 09:22, 18 September 2023

Datebox

Employment/Purpose

An edit box for holding a date. After click on the calender, a calender will pop-up for inputting date.

Keyboard Navigation datebox

  • 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.


Customization

Since 5.0.3 You can customize the rendering of the calendar at the client by JavaScript code that overrides Renderer.

Example

ZKComRef Datebox Example.PNG

 <datebox lenient="true" buttonVisible="false" />
 <datebox lenient="false" buttonVisible="true" />

Integrate Moment.js

Since 8.5.1 The JavaScript widgets including Datebox,Timebox,Timepicker rely on moment.js and moment-timezone.js to handle time zone information more accurately.

To check the included moment.js version, enter zk.mm.version in the browser developer console tab.


Properties and Features

Constraint

You can specify the date range to accept by the constraint property with one or multiple following values:

  • no empty
  • no future
  • no past
  • no today.


It also supports an interval of dates. For example,

<datebox constraint="between 20071225 and 20071203"/>
<datebox constraint="before 20071225"/>
<datebox constraint="after 20071225"/>

Notices

  1. The format of the date in the constraint must be yyyMMdd. It is independent of the locale.
  2. 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.
  3. The constraint is actually represented with an instance of the org.zkoss.zul.SimpleDateConstraint class. You can retrieve the parsed beginning and ending date with the getBeginDate and getEndDate methods.
((SimpleDateConstraint)datebox.getConstraint()).getBeginDate();

Multiple Constraints

To specify two or more constraints, use a comma to separate them as follows:

<datebox constraint="no past,no empty"/>

Custom Error Message

If you prefer to display a different message from the default one, you can append the error message to the constraint with a colon.

<datebox constraint="no empty, no future: now or never"/>

Notes:

  • The error message, if specified, must be the last element and start with a colon.
  • To support multiple languages, you could use the 「l」 function as depicted in the Internationalization chapter.
<datebox constraint="no empty, no future: ${c:l('err.date.nowornever')}"/>

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. Viewing the zul markup provided below the image we can see that the displayedTimeZones is set to "GMT+12,GMT+8". These options are specified by the developer and restrict the user to the available time zones.

ZKComRef Datebox Timezone.png

<datebox id="datebox1" format="M/d/yy KK:mm:ss a" width="150px" displayedTimeZones="GMT+12,GMT+8" timeZone="GMT+8" timeZonesReadonly="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.

<datebox format="MM/dd/yyyy"/>

Like any other properties, you are able to change the format dynamically, as depicted below.

<datebox id="db"/>
<button label="set MM-dd-yyyy" onClick='db.setFormat("MM-dd-yyyy")'/>

Length Option

Since 5.0.7

In addition to specifying the format explicitly, you could specify the length option. It supports four different length options mentioned at java.text.DateFormat:

  • short
  • medium
  • long
  • full

For example, you could specify the styling rather than the real format as follows.

<datebox format="short"/>
<datebox format="long"/>

Then the real format of the datebox will be decided at run-time depending on the configuration. For more information, please refer to ZK Developer's Reference: Date and Time Formatting.

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

format="option_for_date+option_for_time"

For example,

<datebox format="medium+full"/>

Warning

Because Java default locale provider changes since JDK 9, the built-in formats (e.g. long) for some locales might change since JDK 9. We recommend you to use a fixed format pattern.

Validation

If a user's input doesn't match the specified format, a Datebox will show an error message. It's a client-side validation.

Locale

Default: depends on the current locale (i.e., Locales.getCurrent()) at run-time

You can enforce the locale for an individual component such as:

<datebox locale="de-DE" format="full"/>
<datebox locale="fr" format="full"/>

Multiple-Eras Calendar

Since 9.6.0 Datebox can display some multiple-eras calendar systems including:

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

Roc-calendar.jpg Jp-calendar.jpg Buddhist-calendar.jpg

See complete locale list.

Reference: Era

Position

Since 8.0.3

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

The First Day of the Week

The first day of the week is decided by the locale by default. (actually the return value of the getFirstDayOfWeek method in the java.util.Calendar).

Since 5.0.3 You can 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

Since 8.6.2

You can control the 2DigitYearStart by the use of the library property, org.zkoss.web.preferred.2DigitYearStart.

Show Week Number

  • Available for ZK:
  • http://www.zkoss.org/product/zkhttp://www.zkoss.org/whyzk/zkeeVersion ee.png

Since 6.5.0

Datebox supports to show a week number of the year in a calendar.


ZKComRef Datebox Week Of Year.PNG

<datebox weekOfYear="true" />

Show Link of Today

Datebox supports a link to jump back to the date of today quickly

Since 8.0.0

ZKComRef Datebox Link Of Today.PNG

<datebox id="db" showTodayLink="true" ></datebox>

The format is the same with that specified on format attribute


Show Timebox

By default, there is no Timebox in the popup Calendar. If the specified format attribute contains a time format (like below), it will show a Timebox at the bottom of the popup Calendar.

<datebox format="yyyy-MM-dd HH:mm"/>

Monthly / yearly option

Since 9.5.1

Default: day

You can specify the selectLevel attribute to restrict the date granularity users can select. For example, you can limit users to just select a month, it doesn't show the day view to users to choose a day.

Available values are:

  • year
  • month
  • day.
<datebox format="yyyy" selectLevel="year"/>

Close Popup OnTimezoneChange

Since 9.6.0

Datebox supports switching whether to auto close the datebox popup after changing the timezone.

example:

<datebox closePopupOnTimezoneChange="false" displayedTimeZones="GMT+12,GMT+8" timeZone="GMT+8" timeZonesReadonly="false"/>

Inherited Functions

Please refer to FormatInputElement for inherited functions.

Supported Events

Name
Event Type
onTimeZoneChange
Event: Event

Denotes the time zone of the component is changed by user.

Supported Molds

Available molds of a component are defined in lang.xml embedded in zul.jar.

Name
Snapshot
default
Datebox mold default.png
rounded
Datebox mold rounded.png

Since 5.0.0

Supported Children

Name
Event Type
None None

Use Cases

Version Description Example Location
     

Version History

Last Update : 2023/09/18


Version Date Content
5.0.3 July, 2010 An application can control the first day of the week by use of the session attribute and the library property. Please refer to The First Day of the Week for details.
5.0.4 August, 2010 Calendar supports moving to next/prev mon by mouse scrolling.
5.0.7 April, 2011 Datebox.setFormat(String) supported the styling.
5.0.7 April, 2011 Datebox.setLocale(Locale) was introduced.
6.5.0 June, 2012 ZK-1175: Calendar support show week number
9.5.1 October 2020 ZK-3289: Monthly / yearly options for datebox.



Last Update : 2023/09/18

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.