How to Use the ICEfaces selectInputDate Component

Applications frequently require users to insert a date such as Date-of-Birth or the Start Date of employment. The ice:selectInputDate component offers a user safe and convenient way of entering a date without worrying about format, locale and other features.

Creating a Simple Calendar

Below we see the rendering of a simple calendar. The text fields above and below the calendar are not part of the calendar control.

Calendar component usage in the page:

<ice:selectInputDate id="date1" value="#{dateSelect.date1}"/>

The selected date is stored in the backing bean 'date1' property (type java.util.Date).

Creating a Popup Calendar

Sometimes developers do not have enough real estate on the screen to render out a full calendar. The ice:selectInputDate component can be modified to show a popup version of the calendar:

In order to use a popup calendar, set the 'renderAsPopup' attribute to 'true':

<ice:selectInputDate id="date2" value="#{dateSelect.date2}" renderAsPopup="true"/>

Using Converters and Validators

If you are not familiar with the basics of using a converter or validator, please visit the validators tutorial.

A converter can be used to format how the Date is rendered out to the browser:

<ice:selectInputDate id="date1" value="#{dateSelect.date1}">
    <f:convertDateTime pattern="MM/dd/yyyy" timeZone="#{dateSelect.timeZone}"/>
</ice:selectInputDate>

In this example, we specify a common North American date presentation of MM/dd/yyyy. We also chose a time zone using the standard java TimeZone class.

By default, a java.util.Date is in the GMT/UTC time zone. It is a best practice to keep them in this time zone in your back end. However, when the date is output to the GUI, you may want to apply time zones for different users in different regions of the world. At this point you can format the date appropriately using the 'timeZone' attribute.

Often programmers need to place restrictions which dates can be selected. If it's a birthday it must be in the past, if this is a flight it must be in the future, and so on. Validators are used to restrict user input:

<ice:selectInputDate id="date1" value="#{dateSelect.date1}">
    <f:convertDateTime pattern="MM/dd/yyyy" timeZone="#{dateSelect.timeZone}"/>
    <f:validator validatorId="dateRangeValidator" />
</ice:selectInputDate>

The following code is the 'validate' method called from the dateRangeValidator. The 'value' parameter of validate() is a Date object. This method constructs a JSF FacesMessage to be displayed when validation fails:

public void validate(FacesContext context, UIComponent component, Object value)
		throws ValidatorException {
    Date myDate = (Date)value;
    Date today = new Date();
    if (myDate.before(today)) {
        FacesMessage message = new FacesMessage();
        message.setDetail("Date is in the past");
        message.setSummary("Date is in the past");
        message.setSeverity(FacesMessage.SEVERITY_ERROR);
        throw new ValidatorException(message);
    }
}

Customizing Calendar Style

ice:selectInputDate styling is easily customised. The component automatically makes use of ICEFaces themes to define its appearance. There are also component attributes available to configure the component's appearance:

• renderMonthAsDropdown, renderYearAsDropdown are set to false by default. If you change them to true, control over month and year selection will be through dropdowns and not left-right arrows
• highlightUnit, highlightValue, highlightClass regulate appearance of the highlighted items
  • highlightUnit defines which parts of the calendar are highlighted. For example, highlightUnit="DAY_OF_WEEK: MONTH" shows that days of the week and months are to be highlighted
  • highlightValue sets the values of the elements, listed in the highlight class. For Example: highlightValue="1,7: 8" will highlight Saturday and Sunday of each week in the calendar and month of August(8) will also be highlighted
  • highlightClass defines css classes for the highlighted components. example highlightClass="weekend: august:" shows that 2 classes are defined in css file called weekend and august. Highlights will appear based on the classes.
    
    

    ---

Tutorial Source Code Downloads