org.apache.wicket.extensions.yui.calendar
Class DatePicker

java.lang.Object
  org.apache.wicket.behavior.AbstractBehavior
      org.apache.wicket.extensions.yui.calendar.DatePicker

All Implemented Interfaces:

Serializable, IBehavior, IComponentConfigurationBehavior, IClusterable, IHeaderContributor

public class DatePicker
extends AbstractBehavior
implements IHeaderContributor

Pops up a YUI calendar component so that the user can select a date. On selection, the date is set in the component it is coupled to, after which the popup is closed again. This behavior can only be used with components that either implement AbstractTextComponent.ITextFormatProvider or that use DateConverter configured with an instance of SimpleDateFormat (like Wicket's default configuration has).
To use, simply add a new instance to your component, which would typically a TextField, like DateTextField.
The CalendarNavigator can be configured by overriding configure(Map) and setting the property or by returning true for enableMonthYearSelection().

Author:

eelcohillenius

See Also:

http://developer.yahoo.com/yui/calendar/, Serialized Form

Field Summary

static String	FORMAT_DATE Format to be used when configuring YUI calendar.
static String	FORMAT_PAGEDATE For specifying which page (month/year) to show in the calendar, use this format for the date.

Constructor Summary

DatePicker()
Construct.

Method Summary

protected boolean	alignWithIcon() Whether to position the date picker relative to the trigger icon.
void	bind(Component component) Bind this handler to the given component.
protected void	configure(Map<String,Object> widgetProperties) Gives overriding classes the option of adding (or even changing/ removing) configuration properties for the javascript widget.
protected void	configureWidgetProperties(Map<String,Object> widgetProperties) Deprecated. Please use configure(Map) instead.
protected boolean	enableMonthYearSelection() Indicates whether plain text is rendered or two select boxes are used to allow direct selection of month and year.
protected String[]	filterEmpty(String[] array) Filter all empty elements (workaround for DateFormatSymbols returning arrays with empty elements).
protected String	getAdditionalJavascript() Override this method to further customize the YUI Calendar with additional Javascript code.
protected String	getComponentMarkupId() Gets the id of the component that the calendar widget will get attached to.
protected String	getDatePattern() Gets the date pattern to use for putting selected values in the coupled component.
protected String	getEscapedComponentMarkupId() Gets the escaped DOM id that the calendar widget will get attached to.
protected CharSequence	getIconAltText() Gets the icon alt text for the datepicker icon
protected String	getIconId() Gets the id of the icon that triggers the popup.
protected String	getIconStyle() Gets the style of the icon that triggers the popup.
protected CharSequence	getIconTitle() Gets the title attribute of the datepicker icon
protected CharSequence	getIconUrl() Gets the url for the popup button.
protected Locale	getLocale() Gets the locale that should be used to configure this widget.
protected boolean	hideOnSelect() Indicates whether the calendar should be hidden after a date was selected.
protected boolean	includeYUILibraries() Controls whether or not datepicker will contribute YUI libraries to the page as part of its rendering lifecycle.
boolean	isEnabled(Component component) Called when a components is rendering and wants to render this behavior.
protected void	localize(Map<String,Object> widgetProperties) Configure the localized strings for the datepicker widget.
protected boolean	notifyComponentOnDateSelected() Whether to notify the associated component when a date is selected.
void	onRendered(Component component) Called when a component that has this behavior coupled was rendered.
void	renderHead(IHeaderResponse response) Render to the web response whatever the component wants to contribute to the head section.
protected boolean	renderOnLoad() Indicates whether the calendar should be rendered after it has been loaded.
DatePicker	setShowOnFieldClick(boolean show)
protected boolean	showOnFieldClick() Indicates whether the calendar should be shown when corresponding text input is clicked.
protected String[]	substring(String[] array, int len) Makes a copy of the provided array and for each element copy the substring 0..len to the new array
protected String[]	substring(String[] array, int start, int len) Makes a copy of the provided array and for each element copy the substring 0..len to the new array

Methods inherited from class org.apache.wicket.behavior.AbstractBehavior

afterRender, beforeRender, cleanup, detach, detachModel, exception, getStatelessHint, isTemporary, onComponentTag, onConfigure, onException, rendered

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FORMAT_DATE

public static String FORMAT_DATE

Format to be used when configuring YUI calendar. Can be used when using the "selected" property.

FORMAT_PAGEDATE

public static String FORMAT_PAGEDATE

For specifying which page (month/year) to show in the calendar, use this format for the date. This is to be used together with the property "pagedate"

Constructor Detail

DatePicker

public DatePicker()

Construct.

Method Detail

bind

public void bind(Component component)

Description copied from interface: IBehavior

Bind this handler to the given component. This method is called by the host component immediately after this behavior is added to it. This method is useful if you need to do initialization based on the component it is attached and you can't wait to do it at render time. Keep in mind that if you decide to keep a reference to the host component, it is not thread safe anymore, and should thus only be used in situations where you do not reuse the behavior for multiple components.

Specified by:

bind in interface IBehavior

Overrides:

bind in class AbstractBehavior

Parameters:

component - the component to bind to

See Also:

AbstractBehavior.bind(org.apache.wicket.Component)

onRendered

public void onRendered(Component component)

Description copied from class: AbstractBehavior

Called when a component that has this behavior coupled was rendered.

Overrides:

onRendered in class AbstractBehavior

Parameters:

component - the component that has this behavior coupled

See Also:

AbstractBehavior.onRendered(org.apache.wicket.Component)

includeYUILibraries

protected boolean includeYUILibraries()

Controls whether or not datepicker will contribute YUI libraries to the page as part of its rendering lifecycle. There may be cases when the user wants to use their own version of YUI contribution code, in those cases this method should be overridden to return false.

Returns:

renderHead

public void renderHead(IHeaderResponse response)

Description copied from interface: IHeaderContributor

Render to the web response whatever the component wants to contribute to the head section. TODO: Post 1.3, add component parameter, so that the behaviors dont' have to track component instances

Specified by:

renderHead in interface IHeaderContributor

Overrides:

renderHead in class AbstractBehavior

Parameters:

response - Response object

See Also:

IHeaderContributor.renderHead(org.apache.wicket.markup.html.IHeaderResponse)

alignWithIcon

protected boolean alignWithIcon()

Whether to position the date picker relative to the trigger icon.

Returns:

If true, the date picker is aligned with the left position of the icon, and with the top right under. If false, the date picker will skip positioning and will let you do the positioning yourself. Returns true by default.

configure

protected void configure(Map<String,Object> widgetProperties)

Gives overriding classes the option of adding (or even changing/ removing) configuration properties for the javascript widget. See the widget's documentation for the available options. If you want to override/ remove properties, you should call super.configure(properties) first. If you don't call that, be aware that you will have to call localize(Map) manually if you like localized strings to be added.

Parameters:

widgetProperties - the current widget properties

configureWidgetProperties

@Deprecated
protected final void configureWidgetProperties(Map<String,Object> widgetProperties)

Deprecated. Please use configure(Map) instead.

filterEmpty

protected final String[] filterEmpty(String[] array)

Filter all empty elements (workaround for DateFormatSymbols returning arrays with empty elements).

Parameters:

array - array to filter

Returns:

filtered array (without null or empty string elements)

getComponentMarkupId

protected final String getComponentMarkupId()

Gets the id of the component that the calendar widget will get attached to.

Returns:

The DOM id of the component

getDatePattern

protected String getDatePattern()

Gets the date pattern to use for putting selected values in the coupled component.

Returns:

The date pattern

getEscapedComponentMarkupId

protected final String getEscapedComponentMarkupId()

Gets the escaped DOM id that the calendar widget will get attached to. All non word characters (\W) will be removed from the string.

Returns:

The DOM id of the calendar widget - same as the component's markup id + 'Dp'}

getIconId

protected final String getIconId()

Gets the id of the icon that triggers the popup.

Returns:

The id of the icon

getIconStyle

protected String getIconStyle()

Gets the style of the icon that triggers the popup.

Returns:

The style of the icon, e.g. 'cursor: point' etc.

getIconTitle

protected CharSequence getIconTitle()

Gets the title attribute of the datepicker icon

Returns:

text

getIconAltText

protected CharSequence getIconAltText()

Gets the icon alt text for the datepicker icon

Returns:

text

getIconUrl

protected CharSequence getIconUrl()

Gets the url for the popup button. Users can override to provide their own icon URL.

Returns:

the url to use for the popup button/ icon

getLocale

protected Locale getLocale()

Gets the locale that should be used to configure this widget.

Returns:

By default the locale of the bound component.

localize

protected void localize(Map<String,Object> widgetProperties)

Configure the localized strings for the datepicker widget. This implementation uses DateFormatSymbols and some slight string manupilation to get the strings for months and week days. Also, the first week day is set according to the Locale returned by getLocale(). It should work well for most locales.

This method is called from configureWidgetProperties(Map) and can be overridden if you want to customize setting up the localized strings but are happy with the rest of configureWidgetProperties(Map)'s behavior. Note that you can call (overridable) method getLocale() to get the locale that should be used for setting up the widget.

See YUI Calendar's German and Japanese examples for more info.

Parameters:

widgetProperties - the current widget properties

notifyComponentOnDateSelected

protected boolean notifyComponentOnDateSelected()

Whether to notify the associated component when a date is selected. Notifying is done by calling the associated component's onchange Javascript event handler. You can for instance attach an AjaxEventBehavior to that component to get a call back to the server. The default is true.

Returns:

if true, notifies the associated component when a date is selected

substring

protected final String[] substring(String[] array,
                                   int len)

Makes a copy of the provided array and for each element copy the substring 0..len to the new array

Parameters:

array - array to copy from

len - size of substring for each element to copy

Returns:

copy of the array filled with substrings.

substring

protected final String[] substring(String[] array,
                                   int start,
                                   int len)

Makes a copy of the provided array and for each element copy the substring 0..len to the new array

Parameters:

array - array to copy from

start - start position of the substring

len - size of substring for each element to copy

Returns:

copy of the array filled with substrings.

enableMonthYearSelection

protected boolean enableMonthYearSelection()

Indicates whether plain text is rendered or two select boxes are used to allow direct selection of month and year.

Returns:

true if select boxes should be rendered to allow month and year selection.
false to render just plain text.

hideOnSelect

protected boolean hideOnSelect()

Indicates whether the calendar should be hidden after a date was selected.

Returns:

true (default) if the calendar should be hidden after the date selection
false if the calendar should remain visible after the date selection.

showOnFieldClick

protected boolean showOnFieldClick()

Indicates whether the calendar should be shown when corresponding text input is clicked.

Returns:

true
false (default)

setShowOnFieldClick

public DatePicker setShowOnFieldClick(boolean show)

See Also:

#showOnFieldClick()}

renderOnLoad

protected boolean renderOnLoad()

Indicates whether the calendar should be rendered after it has been loaded.

Returns:

true if the calendar should be rendered after it has been loaded.
false (default) if it's initially hidden.

getAdditionalJavascript

protected String getAdditionalJavascript()

Override this method to further customize the YUI Calendar with additional Javascript code. The code returned by this method is executed right after the Calendar has been constructed and initialized. To refer to the actual Calendar DOM object, use ${calendar} in your code.
See the widget's documentation for more information about the YUI Calendar.
Example:

 protected String getAdditionalJavascript()
 {
        return "${calendar}.addRenderer(\"10/3\", ${calendar}.renderCellStyleHighlight1);";
 }
 

Returns:

a String containing additional Javascript code

isEnabled

public boolean isEnabled(Component component)

Description copied from interface: IBehavior

Called when a components is rendering and wants to render this behavior. If false is returned this behavior will be ignored.

Specified by:

isEnabled in interface IBehavior

Overrides:

isEnabled in class AbstractBehavior

Parameters:

component - the component that has this behavior coupled

Returns:

true if this behavior must be executed/rendered

See Also:

AbstractBehavior.isEnabled(org.apache.wicket.Component)