Instantiating the Calendar

In Calendar 0.12, the configuration properties formerly known as monthyear and selected have been moved to take advantage of the new config argument that can be passed to the constructor. If these properties are not being set, it is not necessary to change the Calendar code at all. Previously, the Calendar was constructed like this:

var cal1 = new YAHOO.widget.Calendar("cal1",
                                     "cal1Container",
                                     "5/2007",
                                     "5/5/2007-5/27/2007,5/30/2007");
 

var cal1 = new YAHOO.widget.Calendar("cal1",
                                     "cal1Container",
                                     "5/2007",
                                     "5/5/2007-5/27/2007,5/30/2007");
 

The new constructor, which adds the config argument (see lines 3 and 4 below), allows the currently displayed calendar page and selected dates to be specified as a part of this new configuration argument, rather than as arguments of the constructor:

var cal1 = new YAHOO.widget.Calendar("cal1",
                                     "cal1Container",
                                    { pagedate: "5/2007",
                                      selected: "5/5/2007-5/27/2007,5/30/2007" } );
 

var cal1 = new YAHOO.widget.Calendar("cal1",
                                     "cal1Container",
                                    { pagedate: "5/2007",
                                      selected: "5/5/2007-5/27/2007,5/30/2007" } );
 

The config argument can also be used to set other configuration properties, which will be covered in the next section.

Configuration Properties

Previous versions of Calendar required that configuration options be set using the Options and Locale objects prior to rendering. Calendar 0.12 provides the ability to configure the Calendar during instantiation or at runtime using the Calendar's new cfg object. Previously, setting the MULTI_SELECT property was accomplished by changing the value in the Options object:

cal1.Options.MULTI_SELECT = true;
 

cal1.Options.MULTI_SELECT = true;
 

The most common ways to configure properties in Calendar 0.12 are via the constructor or by using the cfg object's setProperty method:

// In the constructor, via an object literal:
var cal1 = new YAHOO.widget.Calendar("myCalendar", "myCalendarContainer", { MULTI_SELECT: true });
// Via "setProperty", at runtime, after the Calendar has been rendered
myCalendar.cfg.setProperty("MULTI_SELECT", true);
 

// In the constructor, via an object literal:
var cal1 = new YAHOO.widget.Calendar("myCalendar", "myCalendarContainer", { MULTI_SELECT: true });
// Via "setProperty", at runtime, after the Calendar has been rendered
myCalendar.cfg.setProperty("MULTI_SELECT", true);
 

Multi-Page Calendars using CalendarGroup

In Calendar 0.11.x, instantiating a multi-page calendar required the use of the Calendar2up class. For Calendar 0.12, the default multi-page calendar is called CalendarGroup. Previously, the pages array had to be manipulated directly in order to make changes to a multi-page calendar's individual configuration properties. In Calendar 0.12, the configuration interfaces have been synchronized to allow a CalendarGroup to be configured directly in the same way as the Calendar.

// The previous Calendar2up object's configuration was set by 
// manipulating the pages separately
var calOld = new YAHOO.widget.Calendar2up("cal", "calContainer");
calOld.pages[0].Options.MULTI_SELECT = true;
calOld.pages[1].Options.MULTI_SELECT = true;
// Now, CalendarGroup allows direct manipulation of configuration properties.
var calNew = new YAHOO.widget.CalendarGroup("cal1", "calContainer1");
calNew.cfg.setProperty("MULTI_SELECT", true);
 

// The previous Calendar2up object's configuration was set by 
// manipulating the pages separately
var calOld = new YAHOO.widget.Calendar2up("cal", "calContainer");
calOld.pages[0].Options.MULTI_SELECT = true;
calOld.pages[1].Options.MULTI_SELECT = true;
// Now, CalendarGroup allows direct manipulation of configuration properties.
var calNew = new YAHOO.widget.CalendarGroup("cal1", "calContainer1");
calNew.cfg.setProperty("MULTI_SELECT", true);
 

CalendarGroup also introduces a new argument, pages, that can be set using the configuration methods described above. This argument is set to 2 by default, meaning that a CalendarGroup will display 2 pages at a time. Setting this argument to a higher number will increase the number of pages displayed simultaneously. However, it should be noted that performance may decrease when the pages property is set to an unusually high number.

Styling and Customizing Calendar Cells

The familiar interface for addRenderer that Calendar 0.11.x used for adding renderer functions to a Calendar instance remains unchanged for Calendar 0.12. However, a new styling mechanism has been implemented that allows cells to be styled more easily using CSS rules. Meaningful class names have been applied to the Calendar's various elements, making it easy to style specific dates:

For instance, the class selector .y2006 .m8 .d22 would allow the styling of 8/22/2006 through CSS:

.y2006 .m8 .d22 { background-color:yellow }
 

.y2006 .m8 .d22 { background-color:yellow }
 

The addRenderer function can still be used to customize the contents of cells for both Calendar and CalendarGroup.

Localization

Localization now takes advantage of the same configuration mechanism used by other properties in Calendar 0.12. Instead of setting locale properties against the Locale object, the properties can be set directly using the same familiar names from 0.11.x. In the code sample below, all references to cal.Locale have been modififed to use cfg.setProperty:

var cal1 = new YAHOO.widget.Calendar("cal1","cal1Container");
// Correct formats for Germany: dd.mm.yyyy, dd.mm, mm.yyyy
cal1.cfg.setProperty("DATE_FIELD_DELIMITER", ".");
cal1.cfg.setProperty("MDY_DAY_POSITION", 1);
cal1.cfg.setProperty("MDY_MONTH_POSITION", 2);
cal1.cfg.setProperty("MDY_YEAR_POSITION", 3);
cal1.cfg.setProperty("MD_DAY_POSITION", 1);
cal1.cfg.setProperty("MD_MONTH_POSITION", 2);
// Date labels for German locale
cal1.cfg.setProperty("MONTHS_SHORT",   ["Jan", "Feb", "M\u00E4r", "Apr", "Mai", "Jun", "Jul", "Aug", "Sep", "Okt", "Nov", "Dez"]);
cal1.cfg.setProperty("MONTHS_LONG",    ["Januar", "Februar", "M\u00E4rz", "April", "Mai", "Juni", "Juli", "August", "September", "Oktober", "November", "Dezember"]);
cal1.cfg.setProperty("WEEKDAYS_1CHAR", ["S", "M", "D", "M", "D", "F", "S"]);
cal1.cfg.setProperty("WEEKDAYS_SHORT", ["So", "Mo", "Di", "Mi", "Do", "Fr", "Sa"]);
cal1.cfg.setProperty("WEEKDAYS_MEDIUM",["Son", "Mon", "Die", "Mit", "Don", "Fre", "Sam"]);
cal1.cfg.setProperty("WEEKDAYS_LONG",  ["Sonntag", "Montag", "Dienstag", "Mittwoch", "Donnerstag", "Freitag", "Samstag"]);
cal1.render();
 

var cal1 = new YAHOO.widget.Calendar("cal1","cal1Container");
// Correct formats for Germany: dd.mm.yyyy, dd.mm, mm.yyyy
cal1.cfg.setProperty("DATE_FIELD_DELIMITER", ".");
cal1.cfg.setProperty("MDY_DAY_POSITION", 1);
cal1.cfg.setProperty("MDY_MONTH_POSITION", 2);
cal1.cfg.setProperty("MDY_YEAR_POSITION", 3);
cal1.cfg.setProperty("MD_DAY_POSITION", 1);
cal1.cfg.setProperty("MD_MONTH_POSITION", 2);
// Date labels for German locale
cal1.cfg.setProperty("MONTHS_SHORT",   ["Jan", "Feb", "M\u00E4r", "Apr", "Mai", "Jun", "Jul", "Aug", "Sep", "Okt", "Nov", "Dez"]);
cal1.cfg.setProperty("MONTHS_LONG",    ["Januar", "Februar", "M\u00E4rz", "April", "Mai", "Juni", "Juli", "August", "September", "Oktober", "November", "Dezember"]);
cal1.cfg.setProperty("WEEKDAYS_1CHAR", ["S", "M", "D", "M", "D", "F", "S"]);
cal1.cfg.setProperty("WEEKDAYS_SHORT", ["So", "Mo", "Di", "Mi", "Do", "Fr", "Sa"]);
cal1.cfg.setProperty("WEEKDAYS_MEDIUM",["Son", "Mon", "Die", "Mit", "Don", "Fre", "Sam"]);
cal1.cfg.setProperty("WEEKDAYS_LONG",  ["Sonntag", "Montag", "Dienstag", "Mittwoch", "Donnerstag", "Freitag", "Samstag"]);
cal1.render();
 

In addition, specifying which set of labels to use has become easier, thanks to the LOCALE_MONTHS and LOCALE_WEEKDAYS properties:

These properties can be set using the same configuration syntax used by other properties:

cal1.cfg.setProperty("LOCALE_MONTHS", "short");
cal1.cfg.setProperty("LOCALE_WEEKDAYS", "medium");
 

cal1.cfg.setProperty("LOCALE_MONTHS", "short");
cal1.cfg.setProperty("LOCALE_WEEKDAYS", "medium");
 

Handling Events

Prior to Calendar 0.12, events were defined as functions, such as onSelect and onDeselect. To achieve custom behaviors, these prototypal functions could be overridden on your Calendar instance:

//0.11.x syntax:
cal1.onSelect = myFunction;
 

//0.11.x syntax:
cal1.onSelect = myFunction;
 

In Calendar 0.12, all event functions have been replaced with Custom Event objects (see the Event Utility for more details), allowing event handlers to subscribe to these events dynamically. This provides added flexibility to allow more than one event handler to be subscribed to any given event. But this added flexibility comes at the cost of a a syntax change:

//new 0.12 syntax for custom event subscription:
cal1.selectEvent.subscribe(myFunction, cal1, true);
 

//new 0.12 syntax for custom event subscription:
cal1.selectEvent.subscribe(myFunction, cal1, true);
 

The second argument in the above code snippet is the scope in which to execute the function, and the third argument indicates that the scope should be corrected so that this refers to cal1 (in this case, the Calendar instance).

Support & Community

The YUI Library and related topics are discussed on the on the YUILibrary.com forums.

Also be sure to check out YUIBlog for updates and articles about the YUI Library written by the library's developers.

Filing Bugs & Feature Requests

The YUI Library's public bug tracking and feature request repositories are located on the YUILibrary.com site. Before filing new feature requests or bug reports, please review our reporting guidelines.