The Uize.Widget.Calendar module provides the following key features...

The Uize.Widget.Calendar implements the following JavaScript interfaces...

The Uize.Widget.Calendar module supports the ability to limit the date range within which the user can select dates.

It does this by providing the minValue and maxValue set-get properties, where the minValue property specifies the start date of the valid date range, and the maxValue property specifies the end date of the range.

1.3.1. Upper and Lower Bounds

page.addChild (
  'calendar',
  Uize.Widget.Calendar,
  {minValue:'2000-01-01',maxValue:'2099-12-31'}
);

page.addChild ('calendar',Uize.Widget.Calendar,Uize.Date.getRangeAround ('','week'));

1.3.2. Boundless Date Ranges

page.addChild ('calendar',Uize.Widget.Calendar,{minValue:'2000-01-01'});

page.addChild ('calendar',Uize.Widget.Calendar,{minValue:new Date});

page.addChild ('calendar',Uize.Widget.Calendar,{maxValue:'1999-12-31'});

page.addChild ('calendar',Uize.Widget.Calendar,{maxValue:new Date});

1.3.3. Invalidation of value

The Uize.Widget.Calendar module uses the Uize.Date.resolve static method of the Uize.Date module to conform date values to instances of JavaScript's Date object.

This provides flexibility in how dates can be specified when setting values for the value, minValue, and maxValue set-get properties. Supported value types include: strings in ISO 8601 format, instances of JavaScript's Date object, date strings that can be parsed by the Date object, and basically any value type that is supported by the Uize.Date module's Uize.Date.resolve method.

The Uize.Widget.Calendar module implements support for month and year navigation in the form of navigation buttons.

The navigation button child widgets, which are all instances of the Uize.Widget.Button class, allow the user to navigate the calendar to a different month or year in order to select a date. Month navigation is offered via the nextMonth and previousMonth buttons, which are wired to control the value of the month set-get property. Year navigation is offered via the nextYear and previousYear buttons, which are wired to control the value of the year set-get property.

The markup for the navigation button child widgets is optional, and a given implementation of a calendar widget's HTML does not need to offer the navigation buttons in its UI. If the navigation button markup is omitted, the application may elect to provide month and year navigation through some alternate UI. In other cases, a calendar widget's HTML may exclude just the markup for the year navigation buttons, especially in cases where the user is not likely to need to navigate to earlier or later years, or if date selection will be constrained to dates from a particular year.

1.5.1. Navigation Button State Management

The Uize.Widget.Calendar module implements a snap-into-view behavior, so that programmatically changing the value of the value, minValue, or maxValue set-get properties will update the month and year set-get properties - as needed - in order to ensure that the date is in view and that the view is not outside of the Valid Date Range.

The Snap View behavior, as it pertains to the value set-get property, is switchable with the boolean snapViewOnValueChange set-get property. If the snapViewOnValueChange set-get property is set to true at the time that the value property is modified, then the values of the year and month set-get properties will be updated, if necessary, in order to ensure that the viewed year and month is not outside of the Valid Date Range and that the selected date is in view. If no date is selected, then the year and month will be updated so that today's date is in view, unless today's date is outside of the Valid Date Range, in which case the year and month will be updated so that the start or end date of the Valid Date Range is in view, with priority given to the start date, but with the end date being used if there is no lower bound to the Valid Date Range.

The Uize.Widget.Calendar module implements a date grid, with links for every day of the month, which lets the user select a date.

The HTML for the date grid is dynamically generated to have links for the month of the year currently in view by the instance. The currently selected date is indicated in the grid with a highlight. Days of the month currently in view that are outside of the Valid Date Range are grayed out.

An instance of Uize.Widget.Button, that is wired up as part of the Navigation Buttons, and that increments the value of the month set-get property.

When a non-null value is specified for the maxValue set-get property and incrementing the value of the month set-get property would take the view outside of the Valid Date Range, then the nextMonth button will be disabled (for more info, see the section Navigation Button State Management).

When the month set-get property is set to the value 11 (the last month of the year), then incrementing its value will increment the value of the year set-get property and set the month property to 0. Thus, the nextMonth button can be used to navigate across years (see Month Wrapping Behavior).

NOTES

An instance of Uize.Widget.Button, that is wired up as part of the Navigation Buttons, and that increments the value of the year set-get property.

When a non-null value is specified for the maxValue set-get property and incrementing the value of the year set-get property would take the view outside of the Valid Date Range, then the nextYear button will be disabled (for more info, see the section Navigation Button State Management).

NOTES

An instance of Uize.Widget.Button, that is wired up as part of the Navigation Buttons, and that decrements the value of the month set-get property.

When a non-null value is specified for the minValue set-get property and decrementing the value of the month set-get property would take the view outside of the Valid Date Range, then the previousMonth button will be disabled (for more info, see the section Navigation Button State Management).

When the month set-get property is set to the value 0 (the first month of the year), then decrementing its value will decrement the value of the year set-get property and set the month property to 11. Thus, the previousMonth button can be used to navigate across years (see Month Wrapping Behavior).

NOTES

An instance of Uize.Widget.Button, that is wired up as part of the Navigation Buttons, and that decrements the value of the year set-get property.

When a non-null value is specified for the minValue set-get property and decrementing the value of the year set-get property would take the view outside of the Valid Date Range, then the previousYear button will be disabled (for more info, see the section Navigation Button State Management).

NOTES

One of a number of nodes in the Date Grid that are used to indicate the days of the month of the year currently in view by the instance and that may be wired up to let the user select the corresponding date.

The HTML for these implied nodes are generated dynamically when the contents of the grid implied node is replaced with the updated date grid HTML. The specific day[dayNo] implied node that corresponds to the currently selected date will be highlighted. All day[dayNo] implied nodes that represent dates that are outside of the Valid Date Range will be grayed out.

NOTES

A node, whose contents will be replaced with the dynamically generated grid HTML for the month of the year currently in view by the instance.

This implied node can be of any type that can accept HTML contents containing a table. The contents of this node will be replaced when the grid needs to be updated - as a result of the values of the month or year properties changing, as a result of the Valid Date Range changing, or as a result of any other state change in the instance that would affect what is displayed in the grid. For more info, see the section Date Grid.

NOTES

A node that is used to display the name of the current month in view (ie. the value of the month set-get property, displayed as a month name).

This implied node can be of many types: div, span, p, b, td, input, etc. The month name is displayed in this implied node using the setNodeValue instance method of the Uize.Widget base class. Therefore, any features supported by the setNodeValue method are also supported for this implied node.

NOTES

A node that is used to display the current year in view (ie. the value of the year set-get property).

This implied node can be of many types: div, span, p, b, td, input, etc. The year is displayed in this implied node using the setNodeValue instance method of the Uize.Widget base class. Therefore, any features supported by the setNodeValue method are also supported for this implied node.

NOTES

An instance of JavaScript's Date object, representing the latest date that can be selected by the user (ie. the maximum value for the value set-get property).

The maxValue property specifies the end date of the valid date range represented by the minValue and maxValue properties combined (for more info, see the section Valid Date Range).

4.1.1. Flexibility in Specifying Value

4.1.2. Nullable

4.1.3. Snapping into View

4.1.4. Value Invalidation

4.1.5. Updating Navigation Button State

NOTES

An instance of JavaScript's Date object, representing the earliest date that can be selected by the user (ie. the minimum value for the value set-get property).

The minValue property specifies the start date of the valid date range represented by the minValue and maxValue properties combined (for more info, see the section Valid Date Range).

4.2.1. Flexibility in Specifying Value

4.2.2. Nullable

4.2.3. Snapping into View

4.2.4. Value Invalidation

4.2.5. Updating Navigation Button State

NOTES

An integer in the range of 0 to 11, repesenting the month of the year that should be in view in the calendar's UI.

The value of this set-get property is independent of the selected date that is represented by the value set-get property.

4.3.1. Month Wrapping Behavior

myCalendar.set ({year:2009,month:11});

// increment month into next year
myCalendar.set ({month:myCalendar.get ('month') + 1});

alert (myCalendar.get ('year'));   // displays 2010
alert (myCalendar.get ('month'));  // displays 0

// decrement month back into previous year
myCalendar.set ({month:myCalendar.get ('month') - 1});

alert (myCalendar.get ('year'));   // displays 2009
alert (myCalendar.get ('month'));  // displays 11

NOTES

A boolean, specifying whether or not the values of the month and year set-get properties should automatically be set when the value of the value set-get property changes.

When this property is set to true, the month and year properties will be automatically set when the value of the value property changes, to ensure that the newly selected date is in view. In this mode, the values of the month and year properties can still be changed so that the currently selected date is not in view, but whenever the value property is next modified, the month and year properties will be "snapped back" to the month and year of the selected date.

NOTES

This set-get property has been deprecated in favor of the minValue and maxValue set-get properties.

INSTEAD OF...

myInstance.set ({validDateRange:{start:'2009-09-18',end:'2009-12-25'}});

USE...

myInstance.set ({minValue:'2009-09-18',maxValue:'2009-12-25'});

For backwards compatibility, the validDateRange set-get property is still supported. Setting a value for this deprecated property will result in the values of the minValue and maxValue properties being set, using the start and end properties of the validDateRange object, respectively. Conversely, setting values for either - or both - of the minValue and maxValue properties will result in the value of the deprecated validDateRange property being updated. This backwards compatibility provision will not remain in forever, so if you have code using the validDateRange property, you should update it to use the new properties.

An instance of JavaScript's Date object, representing the currently selected date value for the instance.

When the user selects a date using the instance's user interface, the value property is updated. When the value property is modified programmatically, the user interface will be updated to reflect the new value.

4.6.1. Flexibility in Specifying Value

4.6.2. Nullable

4.6.3. Snapping Into View

NOTES

An integer, repesenting the year that should be in view in the calendar's UI.

The value of this set-get property is independent of the selected date that is represented by the value set-get property.

NOTES