webuijsf
Tag calendar


Use the webuijsf:calendar when the user needs to select a date. The calendar component displays a text field that expects a date as input, together with an icon that displays a small calendar when clicked. The user can either type directly into the textfield or select a date from the calendar display.

HTML Elements and Layout

The calendar component renders several elements: an optional <label>, an <input type="text"> and an <img> element for the icon. They are laid out inside a HTML <table>.

The pop-up calendar is a complex component also formatted using a HTML <table>. It has child components corresponding to <webuijsf:dropDown>, <webuijsf:iconHyperlink> (See these for details) and anchors <a> to represent the dates and the "close" button.

Configuring the webuijsf:calendar tag

Use the selectedDate attribute to associate the component with a model object that represents the current value, by setting the attribute's value to an EL expression that corresponds to a property of a backing bean.

By default, the component accepts dates between the current date and hundred years out. The years shown in the popup calendar reflect this range. If a date outside of the range is entered into the textfield, the component indicates a validation error. To specify a different range of date, use the minDate and maxDate attributes.

To optionally specify a label for the component, use the label attribute, or specify a label facet.

Facets

Client-side JavaScript functions

When the component is rendered, a DOM object corresponding to the component is created. To manipulate the component on the client side, you can call functions on the DOM object.To disable the component, invoke document.getElementById(id).setProps({disabled: false}) where id is the DOM id of the calendar widget.

getProps() Use this function to get widget properties. See setProps() function for a list of supported properties.
refresh(execute) Use this function to asynchronously refresh the component.
  • [optional] execute: Comma separated string containing a list of client ids against which the execute portion of the request processing lifecycle must be run.
setProps(props) Use this function to change any of the following supported properties:
  • accesskey
  • align
  • calendar
  • className
  • dir
  • disabled
  • id
  • label
  • lang
  • notify
  • onClick
  • onDblClick
  • onFocus
  • onKeyDown
  • onKeyPress
  • onKeyUp
  • onMouseDown
  • onMouseOut
  • onMouseOver
  • onMouseUp
  • onMouseMove
  • patternHelp
  • readOnly
  • required
  • style
  • tabIndex
  • title
  • valid
  • value
  • visible
subscribe(topic, obj, func) Use this function to subscribe to an event topic.
  • topic: The event topic to subscribe to.
  • obj: The object in which a function will be invoked, or null for default scope.
  • func The name of a function in context, or a function reference to invoke when topic is published.

Client Side JavaScript Events

When the calendar component is manipulated client side, some functions may publish event topics for custom Ajax implementations to listen for. For example, custom Ajax implementations can listen for the refresh event topic using:

<webuijsf:script>
    var processEvents = {                       
        update: function(props) {
            // Do something...
        }
    }

    // Subscribe to refresh event.
    var domNode = document.getElementById("form1:test1");
    domNode.subscribe(domNode.event.refresh.endTopic, processEvents, "update");


</webuijsf:script>

The following events are supported.

<Node>.event.refresh.beginTopic Event topic published before asynchronously refreshing the component. Supported properties include:
  • [optional] execute - List of the components to be executed along with this component
  • id - The client id to process the event for
<Node>.event.refresh.endTopic Event topic published after asynchronously refreshing the component. Supported properties include: See setProps() function.
  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage

Code Examples

Example 1: Basic Pop-up Calendar

The component gets the options from a managed bean called CalendarBean. The value of the component selectedDate is bound to a property of the managed bean. A label for the component as a whole (label) is shown next to the component.

This example shows how to create a simple calendar.

<webuijsf:calendar id="startDate" 
               selectedDate="#{CalendarBean.startDate}"
               label="Start Date: " />

Code for the managed bean:

CalendarBean.java

import java.io.Serializable;
import java.util.Date;
import java.util.Calendar;
import javax.faces.event.ValueChangeEvent;


public class CalendarBean {
   
    public CalendarBean() {
    }
   
    private Date startDate = null;

    public Date getStartDate() {

        return this.startDate;
    }


    public void setStartDate(Date startDate) {

        this.startDate = startDate;
    }
}

The selectAll attribute indicates that the Add All and Remove All buttons should be shown. A label for the component as a whole (label) is shown next to the component (labelOnTop is false). Labels have been specified for the list of available items and for the list of selected items. The sorted attribute indicates that the options on the list will be shown in alphabetical order.

Example 2: DateFormat Pattern and Date Ranges Configured

The calendar component gets its options from a managed bean called TravelBean. The value of the attribute selectedDate is bound to a property called travelDate, that belongs to the managed bean. A label for the component as a whole (label) is shown next to the component; the label is retrieved from a message bundle.

The calendar component has been configured to use a pattern for date representation consisting of four digits for the year, two for the month, and two for the day, separated by dashes. This pattern, set using the dateFormatPattern attribute will be used regardless of locale. With this date format pattern, the default help string will be "YYYY-MM-DD", which is suitable for English, but not for other locales where other words are used. So a different message will be retrieved for each locale (dateFormatPattern).

The calendar component is also configured to restrict the range of dates that are valid, so that the first valid date is the day after the day the component is viewed, and the last valid date is six months from that date.

     <webuijsf:calendar id="travelDate" 
         selectedDate="#{TravelBean.travelDate}"
         label="#{msgs.travelDate}"
         dateFormatPattern="yyyy-MM-dd"
         dateFormatPatternHelp="#{msgs.dateFormatPattern}"
         minDate="#{TravelBean.tomorrowsDate}"
         maxDate="#{TravelBean.sixMonthsFromNow}" />
 

Example 3: Update Calendar Client Side using the getProps and setProps Functions

This example shows how to toggle the disabled state of a calendar client side using the getProps and setProps functions.

<webuijsf:calendar id="calendar1" label="Start Date:"/>
<webuijsf:button id="button1" text="Toggle Calendar Disabled" onClick="toggleDisabled(); return false"/>

<webuijsf:script>
function toggleDisabled() {
var domNode = document.getElementById("form1:calendar1");
domNode.setProps({ disabled: !domNode.getProps().disabled });
}
</webuijsf:script>

Example 4: Asynchronously Update Calendar Using refresh Function

This example shows how to asynchronously update a calendar using the refresh function. The execute property of the refresh function is used to define the client id which is to be submitted and updated server-side. As the user types in the text field, the input value is updated server-side and the calendar label is updated client-side -- all without a page refresh.
<webuijsf:calendar id="calendar1" label="#{MyBean.label}"/>
<webuijsf:textField id="field1" text="#{MyBean.label}" label="Change Calendar Label"
onKeyPress="setTimeout('refreshCalendar();', 0);"/> // Field used to asynchronously update label.
<webuijsf:script>
    function
refreshCalendar() {
        var domNode = document.getElementById("form1:calendar1"); // Get calendar
        return domNode.refresh("form1:field1"); // Asynchronously refresh while submitting field value
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,...")



Tag Information
Tag Classcom.sun.webui.jsf.component.CalendarTag
TagExtraInfo ClassNone
Body ContentJSP
Display NameNone

Attributes
NameRequiredRequest-timeTypeDescription
bindingfalsefalsejava.lang.String A ValueExpression that resolves to the UIComponent that corresponds to this tag. This attribute allows the Java bean that contains the UIComponent to manipulate the UIComponent, its properties, and its children.
dateFormatPatternfalsefalsejava.lang.String

The date format pattern to use (i.e. yyyy-MM-dd). The calendar component uses an instance of java.text.SimpleDateFormat and you can specify a pattern to be used by this component with the following restriction: the format pattern must include yyyy (not yy), MM, and dd; and no other time elements(such as seconds or minutes) may be displayed. If a pattern is not specified, a locale-specific default is used.

If you change the date format pattern, you might also need to change the dateFormatPatternHelp attribute. See the documentation for that attribute.

timeZonefalsefalsejava.lang.String

The java.util.TimeZone that is used with the calendar component. Unless set, the default TimeZone for the locale in javax.faces.component.UIViewRoot is used.

maxDatefalsefalsejava.lang.String

A java.util.Date object representing the last selectable day. The default value is 200 years after the minDate (which is evaluated first).

The value of this attribute is reflected in the years that are available for selection in the month display. In future releases of this component, web application users will also not be able to view months after this date, or select days that follow this date. At present such dates can be selected, but will not be validated when the form is submitted.

requiredfalsefalsejava.lang.String Flag indicating that an input value for this field is mandatory, and failure to provide one will trigger a validation error.
selectedDatefalsefalsejava.lang.String

A java.util.Date object representing the currently selected calendar date.

dateFormatPatternHelpfalsefalsejava.lang.String

A message located below the textfield for the date.Indicates which string format to use when entering a date as text into the textfield.

The calendar component internally relies on an instance of java.text.SimpleDateFormat to produce this help. The default hint is constructed by invoking the toLocalizedPattern() method on the SimpleDateFormat instance and converting this String to lower case.

Due to a bug in SimpleDateFormat, toLocalizedPattern() does not actually produce locale-appropriate strings for most locales (it works for German, but not for other locales). If the default value for the dateFormtPattern is used, the calendar component performs the localization itself, but if the default is overridden, you may need to override the hint on a per-locale basis too.

minDatefalsefalsejava.lang.String

A java.util.Date object representing the first selectable day. The default value is 100 years prior to today's date.

The value of this attribute is reflected in the years that are available for selection in the month display. In future releases of this component, web application users will not be able to view months before this date, or select days that precede this date. At present such dates can be selected, but are not validated when the form is submitted.

submitFormfalsefalsejava.lang.String

Flag indicating whether pressing enter in this text field would allow browser to submit the enclosing form ( for all input fields with the exception of TextArea which uses enter key to open a new line)
If set to false, the browser will be prevented from submitting the form on enter in all circumstances. If set to true, the form will be submitted on enter in all circumstances. The default value for this attribute is "false", i.e. default browser auto submit feature will be disabled.

onDblClickfalsefalsejava.lang.String

Scripting code executed when a mouse double click occurs over this component.

onKeyPressfalsefalsejava.lang.String

Scripting code executed when the user presses and releases a key while the component has focus.

onSelectfalsefalsejava.lang.String

Scripting code executed when some text in this component value is selected.

onFocusfalsefalsejava.lang.String

Scripting code executed when this component receives focus. An element receives focus when the user selects the element by pressing the tab key or clicking the mouse.

renderedfalsefalsejava.lang.String Indicates whether the HTML code for the component should be included in the rendered HTML page. If set to false, the rendered HTML page does not include the HTML for the component. If the component is not rendered, it is also not processed on any subsequent form submission.
columnsfalsefalsejava.lang.String

Number of character columns used to render this field. The default is 20.

idfalsetruejava.lang.StringNo Description
onKeyUpfalsefalsejava.lang.String

Scripting code executed when the user releases a key while the component has focus.

onMouseUpfalsefalsejava.lang.String

Scripting code executed when the user releases a mouse button while the mouse pointer is on the component.

styleClassfalsefalsejava.lang.String

CSS style class(es) to be applied to the outermost HTML element when this component is rendered.

stylefalsefalsejava.lang.String

CSS style(s) to be applied to the outermost HTML element when this component is rendered.

onClickfalsefalsejava.lang.String

Scripting code executed when a mouse click occurs over this component.

onBlurfalsefalsejava.lang.String

Scripting code executed when this element loses focus.

onMouseDownfalsefalsejava.lang.String

Scripting code executed when the user presses a mouse button while the mouse pointer is on the component.

toolTipfalsefalsejava.lang.String

Sets the value of the title attribute for the HTML element. The specified text will display as a tooltip if the mouse cursor hovers over the HTML element.

converterfalsefalsejava.lang.String Specifies a method to translate native property values to String and back for this component. The converter attribute value must be one of the following:
  • A JavaServer Faces EL expression that resolves to a backing bean or bean property that implements the javax.faces.converter.Converter interface; or
  • the ID of a registered converter (a String).
disabledfalsefalsejava.lang.String

Flag indicating that the user is not permitted to activate this component, and that the component's value will not be submitted with the form.

validatorExpressionfalsefalsejava.lang.String Used to specify a method in a backing bean to validate input to the component. The value must be a JavaServer Faces EL expression that resolves to a public method with return type void. The method must take three parameters:
  • a javax.faces.context.FacesContext
  • a javax.faces.component.UIComponent (the component whose data is to be validated)
  • a java.lang.Object containing the data to be validated.

The backing bean where the method is defined must implement java.io.Serializable or javax.faces.component.StateHolder.

The method is invoked during the Process Validations Phase.

onMouseOutfalsefalsejava.lang.String

Scripting code executed when a mouse out movement occurs over this component.

autoValidatefalsefalsejava.lang.String Attribute indicating to turn on/off the autovalidate functionality of the TextField. Autovalidate would trigger the AJAX request to the validator on the component. Setting autoValidate neccessitates that component is ajaxified, and so it will be accomplished automatically when autoValidate is set to true.
Autovalidate will submit the content of the text field for server side processing that will be processed using JSFX partial lifecycle cycle. Validation of the data remains responsibility of the developer. For example, validatorExpression still needs to be set
By default autovalidate is off.
onMouseOverfalsefalsejava.lang.String

Scripting code executed when the user moves the mouse pointer into the boundary of this component.

htmlTemplatefalsefalsejava.lang.String Alternative HTML template to be used by this component.
onMouseMovefalsefalsejava.lang.String

Scripting code executed when the user moves the mouse pointer while over the component.

immediatefalsefalsejava.lang.String Flag indicating that event handling for this component should be handled immediately (in Apply Request Values phase) rather than waiting until Invoke Application phase.
labelfalsefalsejava.lang.String

If set, a label is rendered adjacent to the component with the value of this attribute as the label text.

onChangefalsefalsejava.lang.String

Scripting code executed when the element value of this component is changed.

visiblefalsefalsejava.lang.String

Use the visible attribute to indicate whether the component should be viewable by the user in the rendered HTML page.

onKeyDownfalsefalsejava.lang.String

Scripting code executed when the user presses down on a key while the component has focus.

readOnlyfalsefalsejava.lang.String

Flag indicating that modification of this component by the user is not currently permitted, but that it will be included when the form is submitted.

labelLevelfalsefalsejava.lang.String

Sets the style level for the generated label, provided the label attribute has been set. Valid values are 1 (largest), 2 and 3 (smallest). The default value is 2.

valueChangeListenerExpressionfalsefalsejava.lang.String Specifies a method to handle a value-change event that is triggered when the user enters data in the input component. The attribute value must be a JavaServer Faces EL expression that resolves to a backing bean method. The method must take a single parameter of type javax.faces.event.ValueChangeEvent, and its return type must be void. The backing bean where the method is defined must implement java.io.Serializable or javax.faces.component.StateHolder.
tabIndexfalsefalsejava.lang.String

Position of this element in the tabbing order of the current document. Tabbing order determines the sequence in which elements receive focus when the tab key is pressed. The value must be an integer between 0 and 32767.

notifyfalsefalsejava.lang.String The comma separated list of absolute client IDs to notify during text field events.

Currently, this feature is only supported by label and alert components. For example, when the label attribute of the textField tag is not used. Or, when an alert is used in the page to display validation messages.

During auto-validation, the text field will notify the label and alert associated with the given client IDs. If the user's input is found to be invalid, the label will change text color and display an error indicator. Likewise, if there are any messages associated with the event, the alert will display the assocaited summary, detail, and error indicator.


Variables
No Variables Defined.


Output Generated by Tag Library Documentation Generator. Java, JSP, and JavaServer Pages are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries. Copyright 2002-4 Sun Microsystems, Inc. 4150 Network Circle Santa Clara, CA 95054, U.S.A. All Rights Reserved.