DateChooser |
||||||||||||||||||||||||||||||||||||||||
Developer’s Guide Home
Installation and Configuration Common Concepts Components Index Border Layout Panel Calendar Chart Command Button Command Link Composite Filter Confirmation Data Table Date Chooser Day Table Drop Down Field Dynamic Image Folding Panel For Each Graphic Text Hint Label Input Text Input Textarea Layered Pane Level Indicator Popup Layer Popup Menu Select Boolean Checkbox Select Many Checkbox Select One Radio Spinner Suggestion Field Tabbed Pane Tab Set Tree Table Two List Selection Window Focus Load Bundle Scroll Position Ajax Framework Validation Framework Tag Reference API Reference |
Key Features
Creating the DateChooserTo add the DateChooser component to the page, use the <o:dateChooser> tag. This tag has the value attribute that controls a currently selected date. The attribute must be a value-binding expression that references a java.util.Date instance. Like the JSF UIInput component, the DateChooser supports the validator, required, immediate and disabled attributes. However, it does not support converter attribute. For more details about these attributes, see JavaServer Faces specification (section "EditableValueHolder"). It's possible to implement a scenario, when a date can be selected only from drop-down calendar using typingAllowed attribute. By default it has a value of "true". To disable the possibility of manual date entering directly into DateChooser's input field just set typingAllowed attribute to "false". DateChooser component supports the timeZone attribute that can be used to specify the time zone in which to interpret the time information in the date. <o:dateChooser value="#{DateManager.toDate}" timeZone="#{DateManager.timeZone}"/> You can also specify the timeZone attribute as a String that is a timezone ID as described in the javadocs for java.util.TimeZone.getTimeZone(). <o:dateChooser value="#{DateManager.toDate}" timeZone="GMT"/> Please note that when the DateChooser's value is saved on the server, the selected date is used and time is set to 00:00:00 in the time zone specified with the timeZone attribute(the server time zone is used by default). Specifying the Date FormatThe DateChooser component uses a specific date format to display dates. It is also assumed that the same date format is used by the user when typing a date. The date format can either be specified by the pattern attribute or be derived from the locale and dateFormat attributes. The pattern string attribute specifies the date format with the pattern similar to that in the java.text.SimpleDateFormat class. Note that the DateChooser component supports only "d", "M", "y" and "E" pattern letters, which represent the components of the date. Please also note that in order for the DateChooser component to work correctly you should specify day, month and year parameters in the pattern attribute. The following example shows a pattern according to which a date, for example, 11 June 2005 will be formatted to "6/11/05, Sat" (if the default locale is U.S.): <o:dateChooser value="#{DateManager.toDate}" pattern="M/d/yy, EEE"/> If no pattern is specified, the date format is derived from the locale used by the DateChooser based on the dateFormat attribute. By default, the DateChooser uses the client's locale, but it can also be explicitly specified by the locale attribute. You must specify it as a value-binding expression that references a java.util.Locale instance or as a String in "ll_CC_vv" format, where:
The dateFormat attribute defines which of the predefined date formats for a given locale should be used. It can take the following values: "short", "medium", "long", "full". The default value is "medium". In this example, the date format for the DateChooser is set to "full", which means that if the locale is U.S., the date format is "dddd, MMMM dd, yyyy". <o:dateChooser value="#{DateManager.toDate}" dateFormat="full"/> If the user enters an invalid value, the DateChooser component shows a validation error message. Conversion is triggered on the onchange event and failed conversion does not block page submission. The error message is shown with the FloatingIconMessage component by default. You can add your own component, for example a OpenFaces-supplied Message component. For more information about validation messages, see Validation Framework documentation). At the moment, convertion errors are shown only if the client-side validation is turned on. You can use the javax.faces.convert.DateTimeConverter.CONVERSION property from Messages.properties to localize a conversion error message. For more details about message bundles, see Validation Framework documentation. Customizing the AppearanceYou can customize the appearance of any part of the DateChooser component. For example, to change the image of the button that opens the drop-down calendar, use the buttonImageUrl attribute. If you want to change the appearance of the calendar, use the attributes that are passed to the inner Calendar component. The firstDayOfWeek attribute lets you define the first day of the week within the calendar. Also, you can change the default Today and None labels by using the todayText and noneText attributes. In addition, you can specify whether to show the Calendar's footer by using a boolean showFooter attribute. For more details about the Calendar component, see Calendar documentation. In this example, the first day of the week is Sunday. French is used as a local language and France is used as a local country for the calendar. <o:dateChooser value="#{DateManager.toDate}" buttonImageUrl="/customButton.gif" firstDayOfWeek="1" locale="fr_FR" todayText="Aujourd'hui" noneText="Aucun"/> Like the HTML <input> tag, <o:dateChooser> supports the title, tabindex and accesskey attributes. These attributes are rendered for a nested input field of the DateChooser component. Using StylesYou can define styles for the entire DateChooser component and its individual parts. To apply a style for the DateChooser, use the style, styleClass, focusedStyle, focusedClass, rolloverStyle, and rolloverClass attributes. To customize a style for the drop-down button in the normal, rollover, and pressed states, use the buttonStyle, buttonClass, rolloverButtonStyle, rolloverButtonClass, pressedButtonStyle, and pressedButtonClass attributes, respectively. To customize a style for the text field in the normal and rollover states, use the fieldStyle, fieldClass, rolloverFieldStyle, and rolloverFieldClass attributes, respectively. To change the icon of the button, use the buttonImageUrl attribute. Styles for the calendar within the DateChooser component are defined the same way as for the Calendar component. The table below lists all the style attributes for customizing the appearance of the calendar, selected and current dates, weekends, etc.
Because of the variety of styles for calendar of the DateChooser component, some style definitions may overlap. To avoid any style conflict, please keep in mind that selectedDayStyle has the highest priority, followed by todayStyle, inactiveMonthDayStyle, weekendDayStyle, and dayStyle having the lowest priority. Keyboard SupportWhen using the DateChooser component with keyboard, besides just typing in the desired date, you can open the drop-down calendar by pressing the Down key and selecting the date with the Left/Right/Up/Down keys to move the selection within a month and PgUp/PgDown keys to move the selection between months. When the selection is done, you can press the Enter key to apply the selection into the DateChooser's field, or the Esc key to close the calendar popup without applyng the selected date. The look of DateChooser in the focused state can be customized with the focusedStyle/focusedClass attributes. Client-Side EventsThe DateChoser component supports the following standard client-side events: onkeypress, ondblclick, onmousedown, onmouseover, onmousemove, onmouseout, onmouseup, onfocus, onblur, onkeydown, onkeyup and onchange event which occurs when the user changes a date. Server-Side Event ListenersThe DateChooser component has the valueChangeListener attribute. This attribute is a method-binding expression that must reference a method that accepts the javax.faces.event.ValueChangeEvent parameter. ValueChangeListener for the DateChooser works the same way as for the standard UIInput components. You can also add a value change listener to the component by using the <f:valueChangeListener> tag. Client-Side APIAll client-side API methods for the DateChooser component are listed in the following table:
|
|||||||||||||||||||||||||||||||||||||||
© 2010 TeamDev Ltd. | ![]() |