Date picker

Changes<input type="text"> into a field with a button next to it that can be used to open a date picking calendar. The user can either type a date into the input area or click the picker button and choose a date from a calendar.

The composite component has the same size and shape as the <input> tag and the input field preserves any other settings that was set on it, for example input assist.

The component uses the same calendars as the DateTimeConverter.

The JSFDatePicker component adds a helper button to an input field that can be used to open a calendar that in turn can be used to select a date.

The helper button is added to the right of the input field. The input field retains all of its original characteristics adding the helper button within the constraints of the original characteristics. For example, if the input field is defined to be 120px wide, when the helper button is added the combined component is now 120px wide. The button assumes style properties that match the input field, for example the button borders match the borders of the input field. Applicable attributes applied to the input field, such as disabled, are also reflected to the button.

The popup containing the calendar behaves like a Windows popup. If you click on a date in the popup, the popup disappears. If you click anywhere in the page outside of the popup, the popup disappears. The popup typically displays below the input field, left edges aligned. If the popup does not fit below the input field (for example the input field is near the bottom of the window), it displays above the input field. It can be styled via the CSS classes.

The JSFDatePicker requires a DateTimeConverter. The converter is used to convert the value of the input field (a string) to and from a JavaScript date object. It is also used to format the month, year, and day of week displayed in the calendar. The converter should be constructed before the date picker is constructed and the ID of the converter passed to the date picker. The input field may also be associated with a DateTimeValidator and/or DateTimeAssist component. If a validator is associated with the input field, it must be passed to the JSFDatePicker (as an attribute of the constructor). If an Assist is associated with the input field, it does not need to be associated with the JSFDatePicker.

JSF tags that emit the component

<hx:inputText>

Base HTML

<input type="text">

The value of the date picker is passed as the value of the input field. The value should be formatted in the style described by the converter associated with the component. If no value is initially passed to the page, the picker has no initial value.

All attributes associated with an input of type text are supported.

All event handlers associated with an input of type text are supported.

JavaScript constructor

hX_5.addComponent("id", new hX_5.JSFDatePicker(attributes)); where

id	The ID of the HTML tag to which the component is attached.
attributes	Comma separated list of attributes where each attribute is a quoted string consisting of the attribute name and value separated by a colon, for example "label:MyLabel".

Attributes

Table 1. Date picker attributes
Attribute name	Description
button-border	Controls how the popup button is drawn relative to the input field.
button-color	Specifies the background-color of the button. By default the background color matches the border color of the input field.
css-prefix	The base class of a set of CSS classes that describe the visual appearance.
converter	The ID of a converter that has already been constructed. The converter describes the format of the value in the input field.
first-day-of-week	Day of the week that is treated as the first day of the week. Zero means Sunday.
multi-line	If true, the header over the calendar is displayed as two lines (year and month) with independent buttons that control the month and year. If false, the year and month are displayed on one line with buttons that control only the month.
validator	The ID of a validator that has already been constructed. If the validator is supplied, the constraints described in the validator are used limit the values a user can pick.

CSS classes

The CSS for the picker is complex. The class(es) applied to the input tag style the input field and by extension, the popup button next to it. A second, independent, set of classes style the popup. This set of classes applies to all popups in the page unless the css-prefix attribute is used to override the display of an individual popup. The set of classes used to style the popup follow the usual hxclient naming convention where there is a single base class name and all other classes used to style the popup use that base name with a suffix.

By default, the calendar is styled using the base class inputText_DatePicker. The css-prefix attribute can be used to specify a different base class.

The class specified on the input field styles the input field and associated button. All of the date picker popups in the page are styled by the class inputText_DatePicker (and associated sub classes) unless a css-prefix attribute is specified on an individual component.

Table 2. Date picker CSS classes
CSS class name	Description
base_DatePicker	Styles the div that contains the calendar. Note that setting the size (width/height) of the div does not change the size of the calendar within it. To change the size of the calendar, use <base>-Size.
<base>-DatePicker-Size	Styles the table that displays the calendar. The table is embedded inside the containing popup div. Changing the width and height of the table changes the size of the calendar (the containing div will size to fit this table).
<base>_DatePicker-Header	Styles the table inside the calendar table that contains the three header rows (the year row, the month row and the days of the week row).
<base>_DatePicker-HeaderLine1	Within the header table, styles the cells in the first row (the year row) of the table that do not contain the year.
<base>_DatePicker-HeaderLine2	Within the header table, styles the cells in the second row (the month row) of the table that do not contain the month.
<base>_DatePicker-HeaderWeekday	Within the header table, styles the cells in the third row (the weekday row) of the table.
<base>_DatePicker-HeaderYear	Within the header table, styles middle table cell in the first row that contains the year.
_DatePicker<base>-HeaderMonth	Within the header table, styles middle table cell in the second row that contains the month.
<base>_DatePicker-Button	Within the header table, in the first and second rows, styles the four buttons used to scroll the calendar.
<base>_DatePicker-Body	Styles the table inside the calendar table that contains the days.
<base>_DatePicker-CurrentMonth	Within the body table, styles a table cell that contains a day in the current month.
<base>_DatePicker-OtherMonth	Within the body table, styles a table cell that contains a day not in the current month (for example the last days of the previous month or the first days of the next month that need to be displayed before/after the days in the currently selected month).
<base_>DatePicker-InvalidDay	Within the body table, styles a table cell that contains a day that may not be selected because such a day is not allowed by the validator attached to the date.
<base>_DatePicker-CurrentDay	Within the body table, styles the table cell that contains the currently selected day.
<base>_DatePicker-Today	Within the body table, styles the table cell that represents the current date.
<base>_DatePicker-CurrentToday	Within the body table, if currently selected day is the same as the currectdate, then styles the table cell that represents both today's date and the current selection.
<base>_DatePicker-Hover	Defines the style that is added to the style of a day when the day has mouse or keyboard focus.

Note:

Older versions of the date picker used the class <base>-CurrentOtherDay. This class is no longer used because of changes to the picker.
The base class that styles the popup supports three kinds of effects that apply to the popup div in some browsers. Not all browsers support these effects. If the browser does not support the effect the effect is not drawn.
To make the background of the menu transparent (only the background, not the text in the foreground), use:
```
-moz-opacity: .9;
opacity: .9;
```
Both properties must be supplied in order for the style to render in Mozilla and Internet Explorer (IE). The value of the opacity must be between 0 and 1.
To give the menu a drop-shadow, use:
```
outline-color: #E4E4E5;
outline-width: 1px;
-moz-outline-color: #E4E4E5;
-moz-outline-width: 1px;
```
Both sets of properties must be supplied for Mozilla and IE browsers to render the menu. The color specifies the color of the darkest part of the drop-shadow. The width specifies the width of the drop-shadow (minimum 1). The shadow is drawn on the right and bottom of the menu.
In IE (only), a transition effect can be applied to the menu (for example, it can slide into place). This is specified via an IE filter effect. For example:
```
filter:progid:DXImageTransform.Microsoft.Inset(duration=.4);
```
If a filter is detected, it is held (not played) until the menu is displayed, for example, the filter is applied before the style of the menu is changed to visible and is "played" afterwards.

Note that Microsoft now deprecates the use of their transition filters if the transition is applied to any kind of text. This is because of a bug in their ClearType code which causes the text to be displayed bold and black while the transition is running. (This is due to an inherent flaw in the ClearType sub-pixel rendering algorithm which cannot be fixed. ClearType is only available on machines using an LCD/Plasma display and so you may not ever see it turned on.)

API calls

Table 3. Date picker API calls
API call	Description
redraw()	Redraw the component taking into account any changes made to the attributes/properties of the base tag.
uirelease()	Releases any active UI associated with the component.
setValue(string)	Sets the value of the component and ensures that the value provided is valid.
object = getValue(boolean)	Retrieves the value of the component. If the boolean is false, this is equivalent to getting the value of the base tag. If the boolean is true, the value is returned as a JavaScript date/time object instead of as a string.
object = setAttribute(attribute)	Sets an attribute or changes its value (if it was set previously).
string = getAttribute(attribute-name)	Retrieves the current value of an attribute.

Accessibility

The date picker is fully keyboard accessible. Both the input field and the date picker button are in the tab order. In the input field, the up and down arrow keys can be used to increment/decrement the date by one day. Pressing the up/down arrow will spin the date by one day increments until the key is released. When the button has focus, pressing the spacebar or newline displays the calendar and focus is moved to the current selection in the calendar. While the calendar has focus, pressing spacebar or newline selects the currently selected day (closing the calendar and returning focus to the button). Pressing ESC closes the calendar, returning focus to the button and leaves the value unchanged. Pressing the left, right, up and down arrows changes the selected day. Pressing SHIFT left/right arrow changes the month and pressing SHIFT up/down arrow changes the selected year.

The date picker currently does not report XML roles/states (it is however XHTML compliant).

Limitations

The minimum value handled by the date picker is January 1, 100 AD. Dates before that are rounded to that value.
When the date picker is popped open, in order to show focus it must have be given a value where focus is initially supplied. If the value of the input field is not usable or the field is empty, in general, the current day will be used.
If the converter used with the field does not include at least month, day and year markers in the format for the date, the date picker is unpredictable.
If the popup "pops up" instead of down (because the control is positioned near the bottom of the window), as the calendar is scrolled month to month, if the number of visible weeks changes (for example, from five to four), there may be a gap between the bottom of the calendar the input field.

Example code

Add a date picker to a field where the format of the date is MMM d,yyyy. Restrict the valid dates to only those in every other month starting with February.

<input type="text" id="form1:text01" class="inputText" size="20" value="Feb 3, 2006" />
<script>
hX.addConverter("c", new hX.DateTimeConverter("strict:1", "format:MMM d, yyyy"));
hX.addValidator("20", new hX.DateTimeValidator("constraint-expression:@testValue.month==1 || 
                  @testValue.month==3 || @testValue.month==5 || @testValue.month==7 || 
                  @testValue.mongth==9 || @testValue.month==11"));
hX.addComponent("form1:text01", new hX.JSFDatePicker("converter:c","validator:20", 
                  "first-day-of-week:0"));
</script>

Feedback