index.mustache revision e459c407a404c834e5f9759744d1a134d820d41b
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci<div class="intro">
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci<img src="{{componentAssets}}/calendar.png" alt="Screenshot of the Calendar widget" style="border: 1px solid #bfbfbf; float:right; height:161px; margin: 0 0 8px 8px; width:272px;">
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucciThe Calendar widget is a visual representation of a range of dates in blocks of one or more months, which allows the user to select dates and navigate the date range.</p>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucciIn addition to the core logic for displaying a date range and allowing date selection and navigation, Calendar also provides options for custom date filtering, custom formatting of individual dates, various display options, internationalization, flexible templates, additional navigation plugins, and more.
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucciCalendar is highly modular and easy to extend so that it can be modified or used as the basis for custom implementations and widgets.
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci{{>getting-started}}
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci<h2>Using Calendar</h2>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci<h3>Quick Start</h3>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucciHere's an easy way to create an instance of a Calendar with just a few lines of code.
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucciYUI().use('calendar', function (Y) {
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci // Add the yui3-skin-sam class to the body so the default
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci // Calendar widget skin will be applied.
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci Y.one('body').addClass('yui3-skin-sam');
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci // Create a new instance of Calendar, setting its width
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci // and height, allowing the dates from the previous
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci // and next month to be visible and setting the initial
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci // date to be November, 1982.
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci var calendar = new Y.Calendar({
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci contentBox: "#mycalendar",
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci height:'200px',
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci width:'600px',
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci showPrevMonth: true,
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci showNextMonth: true,
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci date: new Date(1982,11,1)}).render();
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucciFor a more complete discussion of how to use, configure, and customize Calendar, read on.
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci<h3>Configuring Calendar</h3>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucciExcept for `contentBox`, all configuration attributes are optional. This list only contain the most interesting attributes. For a complete list of all attributes, please refer to the <a href="/yui/3/api/module_calendar.html">API docs</a>.
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci<h4>CalendarBase Config Attributes</h4>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucciThese attributes are provided by `CalendarBase`, which is the core foundation for the Calendar widget. They are available on all Calendar instances.
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci <th>Attribute</th>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci <th>Default</th>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci <th>Description</th>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci <td>`width`</td>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci <td>`300px`</td>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci The width of the calendar widget.
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci <td>`height`</td>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci <td>`200px`</td>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci The height of the calendar widget.
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci <td>`date`</td>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci <td>Today's date on the user's system</td>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci The date corresponding to the month and the year to be displayed. The date assigned to this attribute will always be normalized to the noon on the first of the month. In a multi-pane calendar, the month and the year of the first pane will correspond to this date.
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci <td>`customRenderer`</td>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci <td>`null`</td>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci An object containing a `rules` attribute and a `filterFunction` attribute. See the [[#Custom Rendering]] section for details on how these attributes work.
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci <td>`showPrevMonth`</td>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci <td>`false`</td>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci Whether the dates from the previous month should be shown in the empty cells of the month grid before the first of the month (if there are any).
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci <td>`showNextMonth`</td>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci <td>`false`</td>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci Whether the dates from the next month should be shown in the empty cells of the month grid after the last of the month (if there are any).
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci <td>`headerFormat`</td>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci <td>`"%B %Y"`</td>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci The formatting for the header of the Calendar. This attribute can be either a String with the formatting tokens used by the `strftime` specification, or a callback function that will receive a `Date` object as an argument and output a `String`.
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci<h4>Calendar Config Attributes</h4>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucciThese attributes are provided by `Calendar`, which is the complete implementation of Calendar widget that includes user interactivity (navigation and selection). They are available on all instances of `Calendar`.
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci <th>Attribute</th>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci <th>Default</th>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci <th>Description</th>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci <td>`selectionMode`</td>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci <td>`single`</td>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci The configuration for the type of date selection allowed by the calendar. The `selectionMode` can be either `"single"`, `"multiple"` or `"multiple-sticky"`.
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci <td>`startDate`</td>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci <td>`null`</td>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci Specification for the earliest month which the Calendar will display. In a multi-pane calendar, this is the earliest month that will appear in the first pane.
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci <td>`endDate`</td>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci <td>`null`</td>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci Specification for the latest month which the Calendar will display. In a multi-pane calendar, this is the latest month that will appear in the last pane.
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci <td>`enabledDatesRule`</td>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci <td>`null`</td>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci The name of the rule that should be matched by enabled dates. If specified, a `customRenderer` definition is required (see [[#Custom Rendering]] for more information). Only dates matching the rule will be enabled for interaction; all other dates will be disabled. Cannot be specified simultaneously with the `disabledDatesRule` attribute.
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci <td>`disabledDatesRule`</td>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci <td>`null`</td>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci The name of the rule that should be matched by disabled dates. If specified, a `customRenderer` definition is required (see [[#Custom Rendering]] for more information). Only dates not matching the rule will be enabled for interaction; all other dates will be disabled. Cannot be specified simultaneously with the `enabledDatesRule` attribute.
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci<h3>Custom Rendering</h3>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucciCalendar allows the developer to customize the rendering of individual cells based on a set of rules that match
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgolluccispecific dates. To create a set of custom rules and a custom renderer function that is triggered when a rule is matched, set the `customRenderer` property to an `Object` with two keys: `rules` and `filterFunction`:
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgolluccicalendar.set("customRenderer", {rules: myRules,
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci filterFunction: myFilterFunction});
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci<h4>Rendering Rules</h4>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci<p>The `rules` parameter looks as follows:</p>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgolluccivar rules = {
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci"2011,2013,2015-2019,2017": {
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci "0,1,5-7": {
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci "all": "rule_name"
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucciAt the top level, the rules object specifies years that dates should match; the next level is months (indexed
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgolluccistarting at 0), the next is days of the month (indexed starting at 1), and the last is days of the week (indexed
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgolluccifrom Sunday, starting at 0). The actual value is the name of the rule that is matched by a date. In the example
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucciabove, the rule "rule_name" is matched by the 5th, 6th and 8th days of January, February, June, July and August of
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucci2011, 2013, 2015 through 2019, and 2017.</p>
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgollucciNote that the keyword `'all'` can appear at any level of the `rule` object and will match all parameters (e.g. all years, or all months) at that level. Furthermore, the rule name value can also appear at any level, for instance:
f6ebc4d280b727f6f35e44323d7a88b02f22d3e9pgolluccivar rules = {
The rule 'summer-2011' corresponds to June through August of 2011. More than one rule can be specified in the same
<p>In order to match these rules, the customRenderer allows the developer to provide a `filterFunction` that will get called every time one or more rules is matched. The `filterFunction` has the following signature:</p>
if (rules.indexOf("rule_name") >= 0) {
<p>The first parameter, `date`, is a single date that matched one or more rules. The second parameter, `node`, is the `Node` wrapping the DOM element corresponding to the given date. Finally, the third parameter, `rules`, is an
<p>As an example, here is a custom renderer that assigns a custom CSS class to all summer weekends:</p>
if (rules.indexOf("all-summer-weekends" >= 0)) {
node.addClass("customCSSClass");
calendar.set("customRenderer", {rules: rules, filterFunction: filterFunction});
<p> In addition to custom rendering, the rules can also be used to specify sets of dates that should be enabled or disabled for selection. To do that, specify a rule set as described above, and then specify which rule should be used to match either the disabled dates, or the enabled dates (but not both: only one of the two parameters will be honored):</p>
calendar.set("disabledDatesRule", "someRuleName");
calendar.set("enabledDatesRule", "someRuleName");
Note, by the way, that the same rule name can be listed multiple times, giving the developer a lot of flexibility in defining what set of dates can be matched. For example, the following rule set matches all weekends and the 10th of every month:
<p>By default, the calendar is rendered using a set of templates, specified as static properties of the `CalendarBase` class. These templates can be completely modified to reconfigure the markup of the calendar, as long as the tokens they use as placeholders for CSS classes, ids and content are preserved.</p>
<p>Using the template logic, the developer can easily switch from a single pane calendar, to a calendar with
<p>In this template, the `{calendar_grid_template}` is a so-called iterative token -- that means it can be used
multiple times, and the calendar will automatically adjust to generate multiple sequential month grids for the
<p>For convenience, we provide a two-pane and a three-pane calendar templates. Here is the two-pane template:</p>
<p>Switching to the two-pane template is as simple as assigning the value of `CalendarBase.CONTENT_TEMPLATE`:</p>
Custom templates may also be constructed, with as many `{calendar_grid_template}` tokens as necessary.
simple navigation controls to the top of the widget. The plugin is located on the `navigator` namespace (that is, to access it and its properties, you would reference `mycalendar.navigator`). For future releases, more complex calendar navigation plugins