Datebox"

From Documentation
Line 39: Line 39:
  
 
=Properties and Features=
 
=Properties and Features=
 +
== Constraint ==
 +
You could specify what value to accept for input controls by use of the <tt>constraint </tt>property.
 +
It could be a combination of <tt>no empty</tt>, <tt>no future</tt>, <tt>no past</tt>, <tt>no today</tt>.
 +
 +
To specify two or more constraints, use comma to separate them as follows.
 +
 +
<source lang="xml" >
 +
<datebox constraint="no past,no empty"/>
 +
</source>
 +
 +
If you prefer to display different message to the default one, you can append the error message to the constraint with a colon.
 +
 +
<source lang="xml" >
 +
<datebox constraint="no empty, no future: now or never"/>
 +
</source>
 +
 +
Notes:
 +
* The error message, if specified, must be the last element and start with colon.
 +
* To support multiple languages, you could use the 「l」 function as depicted in the '''Internationalization''' chapter.
 +
 +
<source lang="xml" >
 +
<datebox constraint="no empty, no future: ${c:l('err.date.nowornever')}"/>
 +
</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,
 +
 +
<source lang="xml" >
 +
<datebox constraint="between 20071225 and 20071203"/>
 +
<datebox constraint="before 20071225"/>
 +
<datebox constraint="after 20071225"/>
 +
</source>
 +
 +
Notices
 +
 +
# The format of the date in the constraint is <tt>yyyMMdd</tt>. It is independent of the locale.
 +
# 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.
 +
# 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>
 +
 
==Displayed Time Zones==
 
==Displayed Time Zones==
  
Line 48: Line 90:
 
<datebox id="datebox1" format="M/d/yy KK:mm:ss a" width="150px" displayedTimeZones="GMT+12,GMT+8" timeZone="GMT+8" timeZonesReadonly="false"/>
 
<datebox id="datebox1" format="M/d/yy KK:mm:ss a" width="150px" displayedTimeZones="GMT+12,GMT+8" timeZone="GMT+8" timeZonesReadonly="false"/>
 
</source>
 
</source>
 
== The First Day of the Week ==
 
 
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>).
 
 
Since 5.0.3, you can control the first day of the week by 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.
 
  
 
== Format ==
 
== Format ==
Line 82: Line 118:
 
<source lang="xml">
 
<source lang="xml">
 
<datebox format="medium+full"/>
 
<datebox format="medium+full"/>
</source>
 
 
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:
 
 
<source lang="xml">
 
<datebox format="medium+full" locale="de_DE"/>
 
 
</source>
 
</source>
  
Line 95: Line 125:
 
</blockquote>
 
</blockquote>
  
== Constraint ==
+
== Locale ==
You could specify what value to accept for input controls by use of the <tt>constraint </tt>property.
 
It could be a combination of <tt>no empty</tt>, <tt>no future</tt>, <tt>no past</tt>, <tt>no today</tt>.
 
  
To specify two or more constraints, use comma to separate them as follows.
+
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:
  
<source lang="xml" >
+
<source lang="xml">
<datebox constraint="no past,no empty"/>
+
<datebox format="medium+full" locale="de_DE"/>
 +
<datebox format="long" locale="fr"/>
 
</source>
 
</source>
  
 +
== The First Day of the Week ==
  
 +
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>).
  
If you prefer to display different message to the default one, you can append the error message to the constraint with a colon.
+
Since 5.0.3, you can control the first day of the week by 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.
 
 
<source lang="xml" >
 
<datebox constraint="no empty, no future: now or never"/>
 
</source>
 
 
 
Notes:
 
* The error message, if specified, must be the last element and start with colon.
 
* To support multiple languages, you could use the 「l」 function as depicted in the '''Internationalization''' chapter.
 
 
 
<source lang="xml" >
 
<datebox constraint="no empty, no future: ${c:l('err.date.nowornever')}"/>
 
</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,
 
 
 
<source lang="xml" >
 
<datebox constraint="between 20071225 and 20071203"/>
 
<datebox constraint="before 20071225"/>
 
<datebox constraint="after 20071225"/>
 
</source>
 
 
 
Notices
 
 
 
# The format of the date in the constraint is <tt>yyyMMdd</tt>. It is independent of the locale.
 
# 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.
 
# 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>
 
  
 
=Inherited Functions=
 
=Inherited Functions=

Revision as of 07:37, 25 April 2011

Datebox

Employment/Purpose

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

Mouseless Entry 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, the rendering of the calendar can be customized at the client by providing JavaScript code that overrides Renderer.

Example

ZKComRef Datebox Example.PNG

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


Properties and Features

Constraint

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

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

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

If you prefer to display different message to 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 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')}"/>

In addition to the constraints described in the above section (such as no future and regular expressions), the datebox supports a wide range 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 is 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();

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 change the format dynamically, as depicted below.

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

In additions to specifying the format explicitly, you could specify the styling[1]. 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.

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

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

In additions, you could specify the format with both date and time by using the syntax: styling_for_date+styling_for_time. For example,

<datebox format="medium+full"/>

  1. The styling is available since 5.0.7

Locale

By default, the real format depends on the current locale (i.e., Locales.getCurrent()). However, you could specify the locale for an individual instance such as:

<datebox format="medium+full" locale="de_DE"/>
<datebox format="long" locale="fr"/>

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 java.util.Calendar).

Since 5.0.3, you 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.

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 : 2011/04/25


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.



Last Update : 2011/04/25

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