Using Timebox Component
Dennis Chen, Engineer, Potix Corporation
July 12, 2007
Applicable to ZK 2.4.1 and later.
Introduction
Although various types of input components are provided by ZK framework, such as textbox, intbox, datebox etc, the timebox component is missed.
Before this small talk, ZK developers have to write bunch of codes to accomplish this. In order to save developers from this nightmare, We added a timebox component in ZKForge.
Prerequisite Software
Timebox is based on the ZK Ajax Framework, so you must download and install the ZK Ajax Framework.
Installation
Installation of timebox is an easy task. Just follow these simple steps:
- Step 1. Download the timebox zip file which can be downloaded from Download.
- Step 2. Copy timebox.jar(at zipfile/lib/) into your webapp/WEB-INF/lib
Sample Codes
All the sample code below are able to be downloaded from Download.
- Sample 1 : Basic Timebox
In this sample (tb1.zul in .war), We demonstrate a basic usage of timebox. The code looks like this:
<zk>
<window title="Simple" width="300px" border="normal">
<timebox id="tb0"/>
</window>
</zk>
In the browser, you will see a datebox-like component(the left side is textbox but the right side are up & down buttons) as below:
Then you can click the up or down button to adjust the hour or minute of timebox, depending on the text cursor location in the textbox. By default, if the value of timebox is NULL, then the change will be affected on hour.
Furthermore, key storkes are supported by timebox. You can click the left text box, and use right or left key to move the position of the text cursor and use up or down key to adjust the hour or minute which is dependent on the text cursor location.
Also, keying in digit number(0~9) directly in the left textbox is supported as long as the value is a legal time format (ex: you can't type 25:01 or 12:99).
Last, to clear timebox, just press DEL key.
- Sample 2 : The Timebox and java.util.Date
In this sample (tb2.zul in .war), We demonstrate that the value of timebox is assigned by a java.util.Date . You might ask why we use java.util.Date to represent time. Reasons are :
- 1. There is no time object in JAVA language.
- 2. We want to enhance timebox to be a date-timebox and customized format be accepted in futrue.
<zk >
<zscript>
import java.text.SimpleDateFormat;
import java.util.Date;
SimpleDateFormat format = new SimpleDateFormat("HH:mm");
Date date = format.parse("23:59");
</zscript>
<window title="Time Value(Date)" width="300px" border="normal">
<timebox id="tb0" value="${date}" />
<separator/>
<button label="show time">
<attribute name="onClick">
alert(""+tb0.getValue());
</attribute>
</button>
</window>
</zk>
Click the button, You will get an alert message as the value of timebox.
- Sample 3 : Hide the Control Buttons
In this sample (tb3.zul in .war), We demonstrate how to hide the buttons by setting the buttonVisibile to false. The code looks like this:
<zk >
<window title="Btn Visibility" width="300px" border="normal">
<timebox id="tb1" buttonVisible="false"/>
<separator/>
<button label="show or hide">
<attribute name="onClick">
tb1.buttonVisible= !tb1.buttonVisible;
</attribute>
</button>
</window>
</zk>
Timebox's buttons aren't visible.
Timebox's buttons’ visibility can be shifted by clicking the button
Supported Events
The following events are supported by timebox. To know more about ZK events please refer to ZK-Devguide
Event Name | Description |
---|---|
onChange | Denotes the content of an input component has been modified by the user. |
onChanging | Denotes that user is changing the content of an input component.
Notice that the component's content (at the server) won't be changed until onChange is received. |
onFocus | Denotes when a component gets the focus. |
onBlur | Denotes when a component loses the focus. |
Supported Key Strokes
Following key strokes are supported by timebox.
Key | Description |
---|---|
DEL | Clear the value in the timebox, a null value will be apply to server side. |
0~9 | Replace the digit in timebox depends on the text cursor location. |
Arrow key - left & right | Move text cursor to left or right. |
Arrow key - up & down | Increase or decrease the time depends on the text cursor location. |
Supported Constraints
“no empty” is the only constraint property that is supplied by timebox. But, any customized constraint can be assigned to examine user input.
Download
- Download timebox zip file.
- Download sample war file.
Summary
We provide a timebox component to simplify time input for user. Customized format is not supported in this version. But it will be enhanced to support customized format and then support date-time input ( date and time, yyyy/MM/dd HH:mm). Since timebox is in ZK Forge, this component will be integrated into ZK as a base component in the future.
Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License. |