Purpose

This extension provides a high-level component for date entering and date choosing. The ULCDateComponent can be configured with both a locale and a time zone. The locale is used to adapt the date input and output format according to the locale-specific rules. The time zone provided defines relative time zone for the date entered / chosen. In multi-language and worldwide deployed applications, it is often crucial to define a kind of a reference time zone the dates used are managed relative to. When converting dates between different time zones, it is very important to known what timezone the user assumed at the time it has defined a specific date. It may also be important to specify whether a given date should be converted to the user's time zone or not.

datecomponent-screenshot

Resources

How to use

Create an instance of ULCDateComponent

The ULCDateComponent instance has to be configured with the output format style (used to format the date in the text field), a number of input format styles (used to filter user input), locale, time zone and selected date (if any).

...

int outputFormatStyle = ULCDateComponent.DATE_MEDIUM; int[] inputFormatStyles = new int[]{ULCDateComponent.DATE_SHORT, ULCDateComponent.DATE_MEDIUM}; Locale defaultLocale = ClientContext.getLocale(); TimeZone defaultTimeZone = ClientContext.getTimeZone();

ULCDateComponent dateComponent = new ULCDateComponent(outputFormatStyle, inputFormatStyles, defaultLocale, defaultTimeZone, new Date());

...

Register an IDateSelectionListener

All registered IDateSelectionListener instances get notified whenever the user enters a date into the text field or chooses a date using the date chooser dialog.

...

dateComponent.addDateSelectionListener(new IDateSelectedListener(){ public void dateChosen(Date date) { // do something } });

...

Place the ULCDateComponent in the UI

As the ULCDateComponent currently extends from ULCBoxPane, it can be placed like any other container directly in the UI layout. The accessors to the contained text field, chooser button and date chooser dialog can be used to further configure and customize the visual representation.

...

ULCBoxPane container = new ULCBoxPane(1, 0); container.add(ULCBoxPane.BOX_CENTER_CENTER, dateComponent);

...

Changed the locale and time zone during runtime

Using the appropriate API, the locale and time zone used by the ULCDateComponent can be changed during runtime:

...

dateComponent.setLocale(Locale.EN); dateComponent.setTimeZone(TimeZone.getTimeZone("GMT");

...

How it is implemented

The ULCDateComponent is a container that holds a subtype of ULCTextField with a special data type associated and an ULCButton that triggers the ULCDateChooserDialog to appear. When selecting a specific day on the date chooser dialog, the selected date is sent to the server-side and the registered IDateSelectionListener instances are notified.

Compatibility

Project setup with Eclipse

The project contains all necessary Eclipse project files and can be directly imported from the repository. The classpath in this project contains a entry named ULC Library, which locates the needed UltraLightClient libraries. For to uses the ULC Library entry you have to install the Eclipse Java IDE Integration Plug-in that can be found at : http://update.canoo.com/eclipse.
A installation guide how to install plug-ins in Eclipse can be found at the Eclipse help pages: Workbench User Guide > Tasks > Updating and installing software.