Small Talks/2007/July/Using Timebox Component

Author
Dennis Chen, Engineer, Potix Corporation

Date
July 12, 2007

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