Zapatec.Calendar

Overview | File | Class | Tree | Index | Help

Zapatec Calendar

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## Class Zapatec.Calendar

    Object
       |
       +--Zapatec.Calendar

class Zapatec.Calendar

Field Summary
`Object` | `setDateStatusHandler` These functions allow one to install a handler that gets called for each date when a month is displayed in the calendar.

Method Summary
`void` | `_displayWeekdays()` This function displays the week day names in the calendar header, according to the current "firstDayOfWeek".
`void` | `_dragStart(ev)` \internal Starts dragging the element.
`void` | `_hideCombos()` \internal Hides all combo boxes that might be displayed.
`void` | `_init(firstDayOfWeek, date, last)` (RE)Initializes the calendar to the given date and firstDayOfWeek.
`void` | `_initMultipleDates()` If "multiple dates" is selected (the calendar.multiple property) this function will highlight cells that display dates that are selected.
`void` | `_toggleMultipleDate(date)` Given a Date object, this function will "toggle" it in the calendar; that is, it will select it if not already selected, or unselect it if was already selected.
`void` | `callCloseHandler()` Calls the calendar's onClose handler, if present.
`void` | `callHandler()` Call the calendar's "onSelected" handler, if defined.
`void` | `create(_par)` This function creates the calendar HTML elements inside the given parent.
`void` | `destroy()` Removes the calendar object from the DOM tree and destroys it.
`void` | `hide()` Hides the calendar.
`void` | `hideShowCovered()` This function hides or shows "windowed controls" accordingly so that the calendar isn't obtured by any such control.
`Object` | `parseDate(str, fmt)` Tries to identify the date represented in a string.
`void` | `refresh()` "refresh()" isn't a good name for it: this function _destroys_ the calendar object and creates another one with the same parameters.
`void` | `reinit()` Refreshes the calendar.
`void` | `reparent(new_parent)` Moves the calendar element to a different section in the DOM tree (changes its parent).
`void` | `setDate(date, justInit)` Moves the calendar to the specified date.
`void` | `setDateFormat(str)` Customizes the date format that will be reported to the onSelect handler.
`void` | `setDateToolTipHandler(unaryFunction)` Call this in order to install a function handler that returns a tooltip for the given date.
`Object` | `setDisabledHandler(unaryFunction)`
`void` | `setFirstDayOfWeek(firstDayOfWeek)` Configures the "firstDayOfWeek" parameter of the calendar.
`void` | `setMultipleDates(multiple)` This function sets up the cal.multiple property initially when the flat or popup calendar is created.
`void` | `setRange(A, Z)` Configures a range of allowed dates for the calendar.
`void` | `setTtDateFormat(str)` Customizes the tooltip date format.
`void` | `show()` Displays a hidden calendar.
`void` | `showAt(x, y)` Shows the calendar at a given absolute position (beware that, depending on the calendar element style -- position property -- this might be relative to the parent's containing rectangle).
`Object` | `showAtElement(el, opts)` This function displays the calendar near a given "anchor" element, according to some rules passed in \em opts.
`void` | `showHint(text)` Displays a hint in the status bar
`void` | `submitFlatDates()` Call the calendar's callback function, if defined.
`void` | `updateHistory()` This function updates the calendar history and saves the cookie.
`void` | `updateWCH(other_el)` Updates the calendar "WCH" (windowed controls hider).
`<static> Object` | `_checkCalendar(ev)` This gets called when the user presses a mouse button anywhere in the document, if the calendar is shown.
`<static> Object` | `_keyEvent(ev)` This function handles keypress events that occur while a popup calendar is displayed.
`<static> Object` | `setup(params)` This function "patches" an input field (or other element) to use a calendar widget for date selection.

Field Detail

### setDateStatusHandler

    Object setDateStatusHandler

These functions allow one to install a handler that gets called for each date when a month is displayed in the calendar. Based on this handler's return value, that date can be disabled or highlighted using a class name returned by the handler. The handler has the following prototype: \code function dateStatus(date, year, month, day); \endcode While all 4 parameters are passed, the handler can for instance use only the first one. The year, month and day can all be determined from the first parameter which is a Date object, but because many people will explicitely need the year, month or day, we pass them too to speed things up (since we already know them at the time the handler is called). Here is an example of a not-so-complex handler: \code function my_DateStatus(date, year, month, day) {} calendar.setDateStatusHandler(my_DateStatus); \endcode The above handler will disable all dates in 2000 (returns true) and highlight "1979/08/03" using the class "birthday". From this example we can notice that the handler can return a boolean value or a string value. The "boolean" return type is supported for backwards compatibility (function setDisabledHandler, which is deprecated by setDateStatusHandler). Here's what the return value means: - \b true: the date will be disabled. - \b false: no action taken (date stays enabled). - "disabled": the date will be disabled. - "other_string": the "other_string" will be added to the cell's class name. - "disabled other_string": the date will be disabled and "disabled other_string" will be added to cell's class name; this helps one make a date disabled while still highlighting it in a special way. Note that user defined class names should have an associated CSS part somewhere in the document that specifies how the days will look like; otherwise, no difference will be visible. For instance, for highlighting "birthday" dates, one should also add: \code .birthday { color: #f00; } \endcode somewhere in the CSS of the calling document. (the above will make them red). Disabled dates are not clickable; however, if one overrides the "disable" CSS class, or if the cell also gets an "other_string" class that contains settings that override the "disabled" class, those cells might not look "disabled" but still behave so. \b WARNING: this function gets called 28 to 31 times each time a month is displayed. This means that if you are doing crazy computations in order to determine the status of a day, things \em will slow down dramatically. You have been warned.

Method Detail

### _displayWeekdays

    void _displayWeekdays()

This function displays the week day names in the calendar header, according to the current "firstDayOfWeek".

### _dragStart

    void _dragStart(ev)

\internal Starts dragging the element.

### _hideCombos

    void _hideCombos()

\internal Hides all combo boxes that might be displayed.

### _init

    void _init(firstDayOfWeek, date, last)

(RE)Initializes the calendar to the given date and firstDayOfWeek. This function perform the action of actually displaying the day names and dates in the calendar. But first, it checks if the passed date fits in the allowed range, configured by the "minYear", "maxYear", "minMonth" and "maxMonth" properties of the Calendar object. It takes care to highlight special days (calling the calendar.getDateStatus() function which can be overridden by external scripts) or to highlight any dates that might be selected (for instance when multiple dates is on, this function will call _initMultipleDates() to highlight selected dates accordingly). This function is highly optimized for speed, therefore the code in it is not trivial and what it does might not seem obvious. :-) So, WARNING, this is voodoo. If you want to properly understand the code you should analyze it line by line and try to execute it step by step; use the Venkman JS debugger.

Parameters:

`firstDayOfWeek` - [int] the first day of week, 0 for Sunday, 1 for Monday, etc.

`date` - [Date] the date to initialize the calendar to

### _initMultipleDates

    void _initMultipleDates()

If "multiple dates" is selected (the calendar.multiple property) this function will highlight cells that display dates that are selected. It is only called from the _init() function.

### _toggleMultipleDate

    void _toggleMultipleDate(date)

Given a Date object, this function will "toggle" it in the calendar; that is, it will select it if not already selected, or unselect it if was already selected. The array of dates is updated accordingly and the cell object will be added or removed the appropriate class name ("selected"). Of course, this only takes place if "multiple dates" is selected.

Parameters:

`date` - [Date] the date to (un)select.

### callCloseHandler

    void callCloseHandler()

Calls the calendar's onClose handler, if present. Either way, this function calls updateHistory() in order to update the history cookie.

### callHandler

    void callHandler()

Call the calendar's "onSelected" handler, if defined. The passed arguments are the date object and a string with the date formatted by the specifier in calendar.dateFormat.

### create

    void create(_par)

This function creates the calendar HTML elements inside the given parent. If _par is null than it creates a popup calendar inside the BODY element. If _par is an element, be it BODY, then it creates a non-popup calendar (still hidden). The function looks rather complicated, but what it does is quite simple. The basic calendar elements will be created, that is, a containing DIV, a TABLE that contains a headers (titles, navigation bar and day names bars), a body containing up to 12 months, each has 6 rows with 7 or 8 cells (this depends on whether week numbers are on or off) and a footer containing the status bar. Appropriate event handlers are assigned to all buttons or to the titles and status bar (for drag'n'drop). This function also builds the time selector if the calendar is configured so, and it also creates the elements required for combo boxes (years, months, history). This function does not display day names or dates. This is done in Zapatec.Calendar.prototype._init(). Therefore, by separating these 2 actions we can make date switching happen much faster because the _init function will already have the elements in place (so we don't need to create them again and again). This was a major improvement which got in the calendar v0.9.1.

Parameters:

`_par` -

### destroy

    void destroy()

Removes the calendar object from the DOM tree and destroys it.

### hide

    void hide()

Hides the calendar. Also removes any "hilite" from the class of any TD element. Unregisters the document event handlers for key presses and mousedown.

### hideShowCovered

    void hideShowCovered()

This function hides or shows "windowed controls" accordingly so that the calendar isn't obtured by any such control. Historically, this function was used for any browser. It simply walks through all SELECT, IFRAME and APPLET elements present in the DOM, checks if they intersect the calendar and hides them if so or makes them visible otherwise. This approacy has a number of problems, the most important being that if the end-user's code contains a SELECT which is already hidden and it must stay hidden, it will still be made visible when the calendar closes. The other obvious problem is that there's an ugly effect generated by elements that suddenly (dis)appear when you drag the calendar around the screen. Currently this function is only used on IE5.0/Windows, browser that leaves no room for a better workaround to this problem. For IE5.5+/Windows an workaround is possible, albeit amazingly ugly (WCH). For other browsers such crazy techniques are not anymore useful because the bugs related to windowed controls were fixed.

### parseDate

    Object parseDate(str, fmt)

Tries to identify the date represented in a string. If successful it also calls this.setDate which moves the calendar to the given date.

Parameters:

`str` - [string] a date

`fmt` - [string] the format to try to parse \em str in

### refresh

    void refresh()

"refresh()" isn't a good name for it: this function _destroys_ the calendar object and creates another one with the same parameters. This comes in handy for the calendar wizard where we need to reconstruct the calendar for virtually any property change.

### reinit

    void reinit()

Refreshes the calendar. Useful if the "disabledHandler" function is dynamic, meaning that the list of disabled date can change at runtime. Just call this function if you think that the list of disabled dates should change. This function simply calls _init() using the current firstDayOfWeek and the current calendar date.

### reparent

    void reparent(new_parent)

Moves the calendar element to a different section in the DOM tree (changes its parent). This might be useful for flat calendars.

Parameters:

`new_parent` - [HTMLElement] the new parent for the calendar.

### setDate

    void setDate(date, justInit)

Moves the calendar to the specified date. If \em date is not passed, then the "today" date is assumed. This function does range checking and displays an error in the status bar if the new date is not allowed by the configured calendar range. Otherwise, it simply calls _init() with the new date.

Parameters:

`date` - [Date, optional] the date object.

### setDateFormat

    void setDateFormat(str)

Customizes the date format that will be reported to the onSelect handler. The format string is described in Date.prototype.print().

Parameters:

`str` - [string] the date format.

### setDateToolTipHandler

    void setDateToolTipHandler(unaryFunction)

Call this in order to install a function handler that returns a tooltip for the given date. For example: \code function myHandler(date) { var str = date.print("%Y/%m/%d"); if (str == "1979/08/03") { return "Happy birthday Mishoo! :D"; } return str; } calendar.setDateToolTipHandler(myHandler); \endcode The tooltip handler is a "unary" function (receives one argument). The argument passed is a date object and the function should return the tooltip for that date.

Parameters:

`unaryFunction` - [function] your tooltip handler, as described above

### setDisabledHandler

    Object setDisabledHandler(unaryFunction)

### setFirstDayOfWeek

    void setFirstDayOfWeek(firstDayOfWeek)

Configures the "firstDayOfWeek" parameter of the calendar.

Parameters:

`firstDayOfWeek` - [int] the new first day of week, 0 for Sunday, 1 for Monday, etc.

### setMultipleDates

    void setMultipleDates(multiple)

This function sets up the cal.multiple property initially when the flat or popup calendar is created. If there are dates to be displayed or added to the first time, this property will be filled with those dates at the beginning. multiple -- [Array] - stores the current dates for future use and appending of additional dates

### setRange

    void setRange(A, Z)

Configures a range of allowed dates for the calendar. Currently, this function supports setting a range on a "month granularity". This means, using it you can't disable part of a month. Both parameters are numeric and can be float. The range is "inclusive". This function might seem somehow complicated, but it's designed in a way that keeps backwards compatibility with the calendar v0.9.6. -# when the end points are integers, the full years will be included. That is, if you call calendar.setRange(1999, 2005) then only dates between and including 1999/01/01 and 2005/12/31 will be allowed. -# when the end points are floats, the decimal part specifies the month. Therefore, calendar.setRange(1999.03, 2005.05) will allow dates between and including 1999/03/01 (March 1) and 2005/05/31 (May 31). The above statements mean that the following two lines are equivalent: \code calendar.setDate(1999, 2005); // or calendar.setDate(1999.01, 2005.12); \endcode

Parameters:

`A` - [number] the range start point

`Z` - [number] the range end point

### setTtDateFormat

    void setTtDateFormat(str)

Customizes the tooltip date format. See Zapatec.Calendar.prototype.setDateFormat() for a description of the \em str format.

Parameters:

`str` - [string] the "tooltip" date format

### show

    void show()

Displays a hidden calendar. It walks quickly through the HTML elements and makes sure that they don't have "hover" or "active" class names that might be there from a previous time the same calendar was displayed. This function also calls updateWCH() and hideShowCovered() to workaround miserable IE bugs. If the calendar is a popup calendar and doesn't have the "noGrab" property set, this function also adds document event handlers to intercept key events or to close the calendar when one clicks outside it.

### showAt

    void showAt(x, y)

Shows the calendar at a given absolute position (beware that, depending on the calendar element style -- position property -- this might be relative to the parent's containing rectangle).

Parameters:

`x` - [int] the X position

`y` - [int] the Y position

### showAtElement

    Object showAtElement(el, opts)

This function displays the calendar near a given "anchor" element, according to some rules passed in \em opts. The \em opts argument is a string containing one or 2 letters. The first letter decides the vertical alignment, and the second letter decides the horizontal alignment relative to the anchor element. Following we will describe these options; in parens we will use simple descriptions like "top to bottom" which means that the top margin of the calendar is aligned with the bottom margin of the object. \b Vertical align: - T -- the calendar is completely above the element (bottom to top) - t -- the calendar is above the element but might overlap it (bottom to bottom) - C -- the calendar is vertically centered to the element - b -- the calendar is below the element but might overlap it (top to top) - B -- the calendar is completely below the element (top to bottom) \b Horizontal align (defaults to 'l' if no letter passed): - L -- the calendar is completely to the left of the element (right to left) - l -- the calendar is to the left of the element but might overlap it (right to right) - C -- the calendar is horizontally centered to the element - r -- the calendar is to the right of the element but might overlap it (left to left) - R -- the calendar is completely to the right of the element (left to right)

Parameters:

`el` - [HTMLElement] the anchor element

`opts` - [string, optional] the align options, as described above. Defaults to "Bl" if nothing passed.

### showHint

    void showHint(text)

Displays a hint in the status bar

Parameters:

`text` - [string] what to display

### submitFlatDates

    void submitFlatDates()

Call the calendar's callback function, if defined. The passed argument is the date object. This is a public function meant to be invoked by the user so that s/he can have more controls on what to do with the dates selected.

### updateHistory

    void updateHistory()

This function updates the calendar history and saves the cookie. The history is a string containing date and time formatted as "%Y/%m/%d/%H/%M" (that is, all time parts separated by slashes, in a "most significant to least significant order"). Further, such formats are separated by commas, and the current calendar date is added the first, then the cookie saved.

### updateWCH

    void updateWCH(other_el)

Updates the calendar "WCH" (windowed controls hider). A WCH is an "invention" (read: "miserable hack") that works around one of the most common and old bug in Internet Explorer: the SELECT boxes or IFRAMES show on top of any other HTML element. This function makes sure that the WCH covers correctly the calendar element and another element if passed.

Parameters:

`other_el` - [HTMLElement, optional] a second element that the WCH should cover.

### _checkCalendar

    <static> Object _checkCalendar(ev)

This gets called when the user presses a mouse button anywhere in the document, if the calendar is shown. If the click was outside the open calendar this function closes it and stops the event from propagating.

Parameters:

`ev` - [Event] the event object.

Returns:

false if the event is stopped.

### _keyEvent

    <static> Object _keyEvent(ev)

This function handles keypress events that occur while a popup calendar is displayed. The implementation is quite complicated; this function calls cellClick in order to set the new date as if it was clicked.

Parameters:

`ev` - [Event] the event object

Returns:

false

### setup

    <static> Object setup(params)

This function "patches" an input field (or other element) to use a calendar widget for date selection. Note that you can use the Zapatec DHTML Calendar Wizard and generate the code and modify the results. The "params" is a single object that can have the following properties: \code prop. name | description ------------------------------------------------------------------------------------------------- inputField | the ID of an input field to store the date displayArea | the ID of a DIV or other element to show the date button | ID of a button or other element that will trigger the calendar eventName | event that will trigger the calendar, without the "on" prefix (default: "click") closeEventName| event that will close the calendar (i.e. one can use "focus" for eventName and "blur" for closeEventName) ifFormat | date format that will be stored in the input field daFormat | the date format that will be used to display the date in displayArea singleClick | (true/false) wether the calendar is in single click mode or not (default: true) firstDay | numeric: 0 to 6. "0" means display Sunday first, "1" means display Monday first, etc. align | alignment (default: "Br"); if you don't know what's this see the calendar documentation range | array with 2 elements. Default: [1900.0, 2999.12] -- the range of years available weekNumbers | (true/false) if it's true (default) the calendar will display week numbers flat | null or element ID; if not null the calendar will be a flat calendar having the parent with the given ID flatCallback | function that receives a JS Date object and returns an URL to point the browser to (for flat calendar) disableFunc | function that receives a JS Date object and should return true if that date has to be disabled in the calendar onSelect | function that gets called when a date is selected. You don't _have_ to supply this (the default is generally okay) onClose | function that gets called when the calendar is closed. [default] onUpdate | function that gets called after the date is updated in the input field. Receives a reference to the calendar. date | the date that the calendar will be initially displayed to showsTime | default: false; if true the calendar will include a time selector timeFormat | the time format; can be "12" or "24", default is "12" electric | if true (default) then given fields/date areas are updated for each move; otherwise they're updated only on close sortOrder | ("asc"(ending)/"desc"(ending)/"none"). If "asc" (default), order of the multiple dates (when multiple dates is on) will be sorted in ascending order. Otherwise, it will be sorted in descending order. "none" means no sorting is needed. step | configures the step of the years in drop-down boxes; default: 2 position | configures the calendar absolute position; default: null cache | if "true" (but default: "false") it will reuse the same calendar object, where possible showOthers | if "true" (but default: "false") it will show days from other months too saveDate | if set (default unset) will save a cookie for this duration. numberMonths | Have the calendar display multiple months controlMonth | When displaying multiple months, this will be the control month. Default 1. vertical | When displaying multiple months, months can progress in a vertical or horizontal way. Horizontal is the default. monthsInRow | When displaying multiple months how many months in a horizontal row. Works both in vertical and horizontal mode. Default numberMonths fdowClick | Allow click on Days of Week 1st day titleHtml | Html you can put in title of calendar noHelp | Disables "?" button in your calendar noCloseButton | Disables "X" button in your calendar disableYearNav| Disables year navigation buttons \endcode None of them is required, they all have default values. However, if you pass none of "inputField", "displayArea" or "button" you'll get a warning saying "nothing to setup".

Overview | File | Class | Tree | Index | Help

Zapatec Calendar

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Documentation generated by JSDoc on Thu Aug 16 12:18:51 2007