org.apache.click.extras.control
Class DateField

java.lang.Object
  extended by org.apache.click.control.AbstractControl
      extended by org.apache.click.control.Field
          extended by org.apache.click.control.TextField
              extended by org.apache.click.extras.control.DateField
All Implemented Interfaces:
Serializable, Control, Stateful

public class DateField
extends TextField

Provides a Date Field control: <input type='text'><img>.

Date Field
The DateField control provides a Date entry field and a popup Calendar <div>. Users can either key in a Date value or select a Date using the Calendar.

Example:

 public MyPage extends Page {

     public void onInit() {
         Form form = new Form("form");

         // Create new DateField with default date format: 'dd MMM yyyy'
         DateField dateField = new DateField("date");

         // You can change the format to: 'yyyy-MM-dd'
         dateField.setFormatPattern("yyyy-MM-dd");

         // Finally add dateField to form
         form.add(dateField);

         addControl(form);
     }
 } 

CSS and JavaScript resources

The Calendar popup is provided by the Prototype based CalendarDateSelect library.

Please note: if you don't want to have a dependency on the Prototype library you can use the Click Calendar CalendarField which is based on the Dynarch.com library. Consider this option when using an alternative JavaScript library than Prototype, such as JQuery.

Alternatively you can switch off the Calendar popup by setting the setShowCalendar(boolean) to false. No JavaScript and CSS will be included when this option is false.

The DateField control makes use of the following resources (which Click automatically deploys to the application directories, /click/calendar and /click/prototype):

The Calendar popup is created as a <div> element using JavaScript. To enable the Calendar popup, reference $headElements and $jsElements in the page template. For example:
 <html>
 <head>
 $headElements
 </head>
 <body>

 $form

 $jsElements
 </body>
 </html> 

Calendar Styles

The default Calendar style is 'default' which has a gray theme. The Calendar styles include:

Default date format pattern

The default date format pattern is set to the message "date-format-pattern" defined in the resource bundle /org/apache/click/extras/control/DateField.properties.

You can easily customize the default date format pattern by overriding the "date-format-pattern" in your click-page.properties files.

An example src/click-page.properties file is shown below:

 date-format-pattern=dd-MM-yyyy 

Localization

The following localization messages are available in the resource bundle: /org/apache/click/extras/control/DateField.properties. The buttons are only shown when DateField popup also contains time: field.setShowTime(true);

See also W3C HTML reference INPUT

See Also:
Serialized Form

Field Summary
protected  String calendarPattern
          The JavaScript Calendar pattern.
protected  Date date
          The DateField's date value.
protected  SimpleDateFormat dateFormat
          The date format.
protected  String formatPattern
          The date format pattern value.
protected  int maximumYear
          The maximum year of the calendar, default value is 2050.
protected  int minimumYear
          The minimum year of the calendar, default value is 1930.
protected  boolean showCalendar
          Flag indicating if the Calendar popup is displayed or not, default value is true.
protected  boolean showTime
          The Calendar popup show time display bar flag.
protected  String style
          The Calendar CSS style, default value: default.
 
Fields inherited from class org.apache.click.control.TextField
maxLength, minLength, size, VALIDATE_TEXTFIELD_FUNCTION
 
Fields inherited from class org.apache.click.control.Field
disabled, error, focus, form, help, label, labelStyle, labelStyleClass, parentStyleClassHint, parentStyleHint, readonly, required, tabindex, title, trim, validate, value
 
Fields inherited from class org.apache.click.control.AbstractControl
actionListener, attributes, behaviors, headElements, listener, listenerMethod, messages, name, parent, styles
 
Fields inherited from interface org.apache.click.Control
CONTROL_MESSAGES
 
Constructor Summary
DateField()
          Create a Date Field with no name defined.
DateField(String name)
          Construct the Date Field with the given name.
DateField(String name, boolean required)
          Construct the Date Field with the given name and required status.
DateField(String name, String label)
          Construct the Date Field with the given name and label.
DateField(String name, String label, boolean required)
          Construct the Date Field with the given name, label and required status.
DateField(String name, String label, int size)
          Construct the Date Field with the given name, label and size.
DateField(String name, String label, int size, boolean required)
          Construct the Date Field with the given name, label, size and required status.
 
Method Summary
protected  void addCalendarOptions(List<Element> headElements)
          Add the calendar options as a script to the list of head elements.
protected  void addCalenderTranslations(List<Element> headElements)
          Return the names of months and weekdays as a script.
 String getCalendarPattern()
          Return the JavaScript Calendar pattern.
 Date getDate()
          Return the field Date value, or null if value was empty or a parsing error occurred.
 SimpleDateFormat getDateFormat()
          Return the SimpleDateFormat for the formatPattern property.
protected  int getFirstDayOfWeek()
          Return the first day of the week.
 String getFormatPattern()
          Return the date format pattern.
 List<Element> getHeadElements()
          Return the DateField HTML head imports statements for the following resources: click/calendar/{style}.css - where {style} is a specific Calendar style e.g.
 String getHelp()
          Return the field help text.
protected  Locale getLocale()
          Returns the Locale that should be used in this control.
 int getMaximumYear()
          Return the maximum year of the Calendar, default value is 2050.
 int getMinimumYear()
          Return the minimum year of the Calendar, default value is 1930.
 String getStyle()
          Return the Calendar CSS style.
 Timestamp getTimestamp()
          Return the Timestamp value, or null if value was empty or a parsing error occurred.
 Object getValueObject()
          Return the field Date value, or null if value was empty or a parsing error occurred.
 boolean isShowCalendar()
          Return true if the Calendar popup will be displayed, false otherwise.
 boolean isShowTime()
          Return true if the Calendar popup will show the time display bar.
protected  void loadFormatPattern()
          Load the default date format pattern.
protected  String parseDateFormatPattern(String pattern)
          Return the JavaScript Calendar pattern for the given Java DateFormat pattern.
 void render(HtmlStringBuffer buffer)
          Render the HTML representation of the DateField.
protected  void renderCalendarButton(HtmlStringBuffer buffer)
          Render the calendar button HTML representation to the buffer.
 void setDate(Date date)
          Set the field Date value.
 void setFormatPattern(String pattern)
          Set the SimpleDateFormat pattern.
 void setMaximumYear(int maximumYear)
          Set the maximum year of the Calendar.
 void setMinimumYear(int minimumYear)
          Set the minimum year of the Calendar.
 void setName(String name)
           
 void setShowCalendar(boolean showCalendar)
          Set whether the Calendar popup is displayed or not.
 void setShowTime(boolean showTime)
          Set the Calendar popup show the time display bar flag.
 void setStyle(String style)
          Set the Calendar CSS style.
 void setValue(String value)
          Set the DateField value.
 void setValueObject(Object object)
          Set the date value of the field using the given object.
 void validate()
          Validate the DateField request submission.
 
Methods inherited from class org.apache.click.control.TextField
getControlSizeEst, getMaxLength, getMinLength, getSize, getTag, getType, getValidationJavaScript, setMaxLength, setMinLength, setSize
 
Methods inherited from class org.apache.click.control.Field
bindRequestValue, getError, getErrorLabel, getFocus, getFocusJavaScript, getForm, getId, getLabel, getLabelStyle, getLabelStyleClass, getParentStyleClassHint, getParentStyleHint, getRequestValue, getState, getTabIndex, getTextAlign, getTitle, getValidate, getValue, getWidth, isDisabled, isHidden, isReadonly, isRequired, isTrim, isValid, onProcess, removeState, renderTagBegin, restoreState, saveState, setDisabled, setError, setErrorMessage, setErrorMessage, setFocus, setForm, setHelp, setLabel, setLabelStyle, setLabelStyleClass, setListener, setParent, setParentStyleClassHint, setParentStyleHint, setReadonly, setRequired, setState, setTabIndex, setTextAlign, setTitle, setTrim, setValidate, setWidth
 
Methods inherited from class org.apache.click.control.AbstractControl
addBehavior, addStyleClass, appendAttributes, dispatchActionEvent, getActionListener, getAttribute, getAttributes, getBehaviors, getContext, getHtmlImports, getMessage, getMessage, getMessages, getName, getPage, getParent, getStyle, getStyles, hasAttribute, hasAttributes, hasBehaviors, hasStyles, isAjaxTarget, onDeploy, onDestroy, onInit, onRender, removeBehavior, removeStyleClass, renderTagEnd, setActionListener, setAttribute, setId, setStyle, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

date

protected Date date
The DateField's date value.


dateFormat

protected SimpleDateFormat dateFormat
The date format.


formatPattern

protected String formatPattern
The date format pattern value.


calendarPattern

protected String calendarPattern
The JavaScript Calendar pattern.


showTime

protected boolean showTime
The Calendar popup show time display bar flag.


showCalendar

protected boolean showCalendar
Flag indicating if the Calendar popup is displayed or not, default value is true.


minimumYear

protected int minimumYear
The minimum year of the calendar, default value is 1930.


maximumYear

protected int maximumYear
The maximum year of the calendar, default value is 2050.


style

protected String style
The Calendar CSS style, default value: default. Available styles include: [blue, default, plain, red, silver]

Constructor Detail

DateField

public DateField(String name)
Construct the Date Field with the given name.

Parameters:
name - the name of the field

DateField

public DateField(String name,
                 String label)
Construct the Date Field with the given name and label.

Parameters:
name - the name of the field
label - the label of the field

DateField

public DateField(String name,
                 boolean required)
Construct the Date Field with the given name and required status.

Parameters:
name - the name of the field
required - the field required status

DateField

public DateField(String name,
                 String label,
                 boolean required)
Construct the Date Field with the given name, label and required status.

Parameters:
name - the name of the field
label - the label of the field
required - the field required status

DateField

public DateField(String name,
                 String label,
                 int size)
Construct the Date Field with the given name, label and size.

Parameters:
name - the name of the field
label - the label of the field
size - the size of the field

DateField

public DateField(String name,
                 String label,
                 int size,
                 boolean required)
Construct the Date Field with the given name, label, size and required status.

Parameters:
name - the name of the field
label - the label of the field
size - the size of the field
required - the field required status

DateField

public DateField()
Create a Date Field with no name defined.

Please note the control's name must be defined before it is valid.

Method Detail

getDate

public Date getDate()
Return the field Date value, or null if value was empty or a parsing error occurred.

Returns:
the field Date value

setDate

public void setDate(Date date)
Set the field Date value.

Parameters:
date - the Date value to set

getDateFormat

public SimpleDateFormat getDateFormat()
Return the SimpleDateFormat for the formatPattern property.

Returns:
the SimpleDateFormat for the formatPattern

getFormatPattern

public String getFormatPattern()
Return the date format pattern. If the date format pattern is not defined it will be loaded through the method, loadFormatPattern().

Returns:
the date format pattern

setFormatPattern

public void setFormatPattern(String pattern)
Set the SimpleDateFormat pattern.

SimpleDateFormat Pattern Characters

Letter Date or Time Component Presentation Examples
G Era designator Text AD
y Year Year 1996; 96
M Month in year Month July; Jul; 07
w Week in year Number 27
W Week in month Number 2
D Day in year Number 189
d Day in month Number 10
F Day of week in month Number 2
E Day in week Text Tuesday; Tue
a Am/pm marker Text PM
H Hour in day (0-23) Number 0
k Hour in day (1-24) Number 24
K Hour in am/pm (0-11) Number 0
h Hour in am/pm (1-12) Number 12
m Minute in hour Number 30
s Second in minute Number 55
S Millisecond Number 978
z Time zone General time zone Pacific Standard Time; PST; GMT-08:00
Z Time zone RFC 822 time zone -0800

Parameters:
pattern - the SimpleDateFormat pattern

setName

public void setName(String name)
Specified by:
setName in interface Control
Overrides:
setName in class AbstractControl
Parameters:
name - of the control
Throws:
IllegalArgumentException - if the name is null
See Also:
AbstractControl.setName(String)

getTimestamp

public Timestamp getTimestamp()
Return the Timestamp value, or null if value was empty or a parsing error occurred.

Returns:
the Timestamp value

setValue

public void setValue(String value)
Set the DateField value.

Overrides:
setValue in class Field
Parameters:
value - the DateField value

getValueObject

public Object getValueObject()
Return the field Date value, or null if value was empty or a parsing error occurred.

Overrides:
getValueObject in class Field
Returns:
the Date object representation of the Field value

setValueObject

public void setValueObject(Object object)
Set the date value of the field using the given object.

Overrides:
setValueObject in class Field
Parameters:
object - the object value to set

getCalendarPattern

public String getCalendarPattern()
Return the JavaScript Calendar pattern. The Calendar pattern is defined when you set the format pattern.

If the date format pattern is not defined it will be loaded through the method loadFormatPattern().

Returns:
the JavaScript Calendar pattern

getHeadElements

public List<Element> getHeadElements()
Return the DateField HTML head imports statements for the following resources: This method delegates to addCalendarOptions(java.util.List) to include the Calendar Options script.

Specified by:
getHeadElements in interface Control
Overrides:
getHeadElements in class AbstractControl
Returns:
the HTML head import statements for the control
See Also:
Control.getHeadElements()

isShowTime

public boolean isShowTime()
Return true if the Calendar popup will show the time display bar.

Returns:
true if the Calendar popup will show the time display bar

setShowTime

public void setShowTime(boolean showTime)
Set the Calendar popup show the time display bar flag.

Parameters:
showTime - the flag to show the Calendar time display bar

isShowCalendar

public boolean isShowCalendar()
Return true if the Calendar popup will be displayed, false otherwise. Default value is true.

Returns:
true if the Calendar popup will be displayed, false otherwise

setShowCalendar

public void setShowCalendar(boolean showCalendar)
Set whether the Calendar popup is displayed or not. If set to false the DateField will not include any JavaScript or CSS.

Parameters:
showCalendar - flag indicating whether the Calendar popup is displayed or not

getMinimumYear

public int getMinimumYear()
Return the minimum year of the Calendar, default value is 1930.

Returns:
the minimum year of the Calendar

setMinimumYear

public void setMinimumYear(int minimumYear)
Set the minimum year of the Calendar.

Parameters:
minimumYear - the minimum year of the Calendar

getMaximumYear

public int getMaximumYear()
Return the maximum year of the Calendar, default value is 2050.

Returns:
the minimum year of the Calendar

setMaximumYear

public void setMaximumYear(int maximumYear)
Set the maximum year of the Calendar.

Parameters:
maximumYear - the maximum year of the Calendar

getStyle

public String getStyle()
Return the Calendar CSS style.

Returns:
the Calendar CSS style

setStyle

public void setStyle(String style)
Set the Calendar CSS style.

Available styles are: [blue, default, plain, red, silver].

Parameters:
style - the Calendar CSS style

getHelp

public String getHelp()
Return the field help text.

Overrides:
getHelp in class Field
Returns:
the help text of the Field
See Also:
Field.getHelp()

validate

public void validate()
Validate the DateField request submission.

A field error message is displayed if a validation error occurs. These messages are defined in the resource bundle:

  • /click-control.properties
    • field-required-error
  • /org/apache/click/extras/control/DateField.properties
    • date-format-error

Overrides:
validate in class TextField

render

public void render(HtmlStringBuffer buffer)
Render the HTML representation of the DateField. Note the button label is rendered as the HTML "value" attribute.

Specified by:
render in interface Control
Overrides:
render in class TextField
Parameters:
buffer - the specified buffer to render the control's output to
See Also:
AbstractControl.toString()

renderCalendarButton

protected void renderCalendarButton(HtmlStringBuffer buffer)
Render the calendar button HTML representation to the buffer.

Parameters:
buffer - the buffer to render the calendar button HTML representation to

addCalendarOptions

protected void addCalendarOptions(List<Element> headElements)
Add the calendar options as a script to the list of head elements.

The default option script will render as (depending on the values):

 Click.addLoadEvent(function() {
   Event.observe('my-calendar-button', 'click', function(){
     calendar = new CalendarDateSelect($('my-calendar'), {
       minute_interval: 1,
       popup_by: 'my-calendar-button',
       embedded: false,
       time: 'mixed',
       formatValue: 'dd MMM yyyy',
       year_range: [1930,2050]});
     });
 }); 
You can override this method to set your own options using a JsScript.

Parameters:
headElements - the list of head elements to include for this control

addCalenderTranslations

protected void addCalenderTranslations(List<Element> headElements)
Return the names of months and weekdays as a script.


getFirstDayOfWeek

protected int getFirstDayOfWeek()
Return the first day of the week. For example e.g., Sunday in US, Monday in France and Australia.

Returns:
the first day of the week

getLocale

protected Locale getLocale()
Returns the Locale that should be used in this control.

Returns:
the locale that should be used in this control

loadFormatPattern

protected void loadFormatPattern()
Load the default date format pattern. The format pattern is set to the message "date-format-pattern" defined in the resource bundle /org/apache/click/extras/control/DateField.properties.

The default date format pattern for English is: "dd MMM yyyy".


parseDateFormatPattern

protected String parseDateFormatPattern(String pattern)
Return the JavaScript Calendar pattern for the given Java DateFormat pattern.

Parameters:
pattern - the Java DateFormat pattern
Returns:
JavaScript Calendar pattern