Yahoo! UI Library

Calendar  2.6.0

Yahoo! UI Library > calendar > YAHOO.widget.CalendarNavigator

Class YAHOO.widget.CalendarNavigator

The CalendarNavigator is used along with a Calendar/CalendarGroup to provide a Month/Year popup navigation control, allowing the user to navigate to a specific month/year in the Calendar/CalendarGroup without having to scroll through months sequentially

Constructor

YAHOO.widget.CalendarNavigator ( cal )
Parameters:
cal <Calendar|CalendarGroup> The instance of the Calendar or CalendarGroup to which this CalendarNavigator should be attached.

Properties

__isIEQuirks - private object

Private flag, to identify IE6/IE7 Quirks

__isMac - private object

Private flag, to identify MacOS

__rendered - private Boolean

Private internal state property which indicates whether or not the Navigator has been rendered.

_DEFAULT_CFG - protected static Object

Object literal containing the default configuration values for the CalendarNavigator The configuration object is expected to follow the format below, with the properties being case sensitive.
strings
Object : An object with the properties shown below, defining the string labels to use in the Navigator's UI
month
String : The string to use for the month label. Defaults to "Month".
year
String : The string to use for the year label. Defaults to "Year".
submit
String : The string to use for the submit button label. Defaults to "Okay".
cancel
String : The string to use for the cancel button label. Defaults to "Cancel".
invalidYear
String : The string to use for invalid year values. Defaults to "Year needs to be a number".
monthFormat
String : The month format to use. Either YAHOO.widget.Calendar.LONG, or YAHOO.widget.Calendar.SHORT. Defaults to YAHOO.widget.Calendar.LONG
initialFocus
String : Either "year" or "month" specifying which input control should get initial focus. Defaults to "year"

_doc - protected HTMLDocument

The document containing the Calendar/Calendar group instance

_month - protected Number

Internal state property for the current month index displayed in the navigator

_year - protected Number

Internal state property for the current year displayed in the navigator

cal - {Calendar|CalendarGroup}

The Calendar/CalendarGroup instance to which the navigator belongs

cancelEl - HTMLElement

Reference to the HTMLElement used to hide the navigator without updating the Calendar/Calendar group

errorEl - HTMLElement

Reference to the HTMLElement used to display validation errors

firstCtrl - HTMLElement

Reference to the first focusable control in the navigator (by default monthEl)

id - String

The unique ID for this CalendarNavigator instance

lastCtrl - HTMLElement

Reference to the last focusable control in the navigator (by default cancelEl)

maskEl - HTMLElement

Reference to the HTMLElement used to render the navigator's mask

monthEl - HTMLElement

Reference to the HTMLElement used to input the month

navEl - HTMLElement

Reference to the HTMLElement used to render the navigator's bounding box

submitEl - HTMLElement

Reference to the HTMLElement used to update the Calendar/Calendar group with the month/year values

YAHOO.widget.CalendarNavigator.CANCEL_SUFFIX - static final String

The suffix added to the Navigator's ID, to generate a unique ID for the "Cancel" button.

YAHOO.widget.CalendarNavigator.CLASSES - static Object

YAHOO.widget.CalendarNavigator.CLASSES contains constants for the class values applied to the CalendarNaviatgator's DOM elements

YAHOO.widget.CalendarNavigator.CLASSES.BUTTON - static String

Class applied to buttons wrapping element

YAHOO.widget.CalendarNavigator.CLASSES.BUTTONS - static String

Class applied to the submit/cancel button's bounding box

YAHOO.widget.CalendarNavigator.CLASSES.DEFAULT - static String

Class applied to default controls

YAHOO.widget.CalendarNavigator.CLASSES.ERROR - static String

Class applied to the validation error area's bounding box

YAHOO.widget.CalendarNavigator.CLASSES.INVALID - static String

Class applied to controls with invalid data (e.g. a year input field with invalid an year)

YAHOO.widget.CalendarNavigator.CLASSES.MASK - static String

Class applied to the Navigator mask's bounding box

YAHOO.widget.CalendarNavigator.CLASSES.MONTH - static String

Class applied to the month label/control bounding box

YAHOO.widget.CalendarNavigator.CLASSES.MONTH_CTRL - static String

Class applied to the month input control

YAHOO.widget.CalendarNavigator.CLASSES.NAV - static String

Class applied to the Calendar Navigator's bounding box

YAHOO.widget.CalendarNavigator.CLASSES.NAV_VISIBLE - static String

Class applied to the Calendar/CalendarGroup's bounding box to indicate the Navigator is currently visible

YAHOO.widget.CalendarNavigator.CLASSES.YEAR - static String

Class applied to the year label/control bounding box

YAHOO.widget.CalendarNavigator.CLASSES.YEAR_CTRL - static String

Class applied to the year input control

YAHOO.widget.CalendarNavigator.ERROR_SUFFIX - static final String

The suffix added to the Navigator's ID, to generate a unique ID for the error bounding box.

YAHOO.widget.CalendarNavigator.ID_SUFFIX - static final String

The suffix added to the Calendar/CalendarGroup's ID, to generate a unique ID for the Navigator and it's bounding box.

YAHOO.widget.CalendarNavigator.MONTH_SUFFIX - static final String

The suffix added to the Navigator's ID, to generate a unique ID for the month control.

YAHOO.widget.CalendarNavigator.SUBMIT_SUFFIX - static final String

The suffix added to the Navigator's ID, to generate a unique ID for the "Submit" button.

YAHOO.widget.CalendarNavigator.TRIM - static RegExp

Regular expression used to trim strings

YAHOO.widget.CalendarNavigator.UPDATE_DELAY - static Number

Artificial delay (in ms) between the time the Navigator is hidden and the Calendar/CalendarGroup state is updated. Allows the user the see the Calendar/CalendarGroup page changing. If set to 0 the Calendar/CalendarGroup page will be updated instantly

YAHOO.widget.CalendarNavigator.YEAR_SUFFIX - static final String

The suffix added to the Navigator's ID, to generate a unique ID for the year control.

YAHOO.widget.CalendarNavigator.YR_MAJOR_INC - static Number

The amount by which to increment the current year value, when the page up/down key is pressed on the year control

YAHOO.widget.CalendarNavigator.YR_MAX_DIGITS - static Number

The number of digits to which the year input control is to be limited.

YAHOO.widget.CalendarNavigator.YR_MINOR_INC - static Number

The amount by which to increment the current year value, when the arrow up/down key is pressed on the year control

YAHOO.widget.CalendarNavigator.YR_PATTERN - static RegExp

Regular expression used to validate the year input

yearEl - HTMLElement

Reference to the HTMLElement used to input the year

Methods

__getCfg

private __getCfg ( Case , true, )
Retrieve Navigator configuration values from the parent Calendar/CalendarGroup's config value.

If it has not been set in the user provided configuration, the method will return the default value of the configuration property, as set in _DEFAULT_CFG

Parameters:
Case <String> sensitive property name.
true, <Boolean> if the property is a string property, false if not.

_getMonthFromUI

protected Number _getMonthFromUI ( )
Returns the month value (index), from the month UI element
Returns: Number
The month index, or 0 if a UI element for the month is not found

_getYearFromUI

protected Number _getYearFromUI ( )
Returns the year value, from the Navitator's year UI element
Returns: Number
The year value set in the UI, if valid. null is returned if the UI does not contain a valid year value.

_handleDirectionKeys

protected void _handleDirectionKeys ( e )
Default Keyboard event handler to capture up/down/pgup/pgdown on the Navigator's year control (yearEl).
Parameters:
e <Event> The DOM event being handled
Returns: void

_handleEnterKey

protected void _handleEnterKey ( e )
Default Keyboard event handler to capture Enter on the Navigator's year control (yearEl)
Parameters:
e <Event> The DOM event being handled
Returns: void

_handleShiftTabKey

protected void _handleShiftTabKey ( e )
Default Keyboard event handler to capture Shift-Tab on the first control (firstCtrl) in the Navigator.
Parameters:
e <Event> The DOM event being handled
Returns: void

_handleTabKey

protected void _handleTabKey ( e )
Default Keyboard event handler to capture Tab on the last control (lastCtrl) in the Navigator.
Parameters:
e <Event> The DOM event being handled
Returns: void

_setFirstLastElements

protected void _setFirstLastElements ( )
Sets up references to the first and last focusable element in the Navigator's UI in terms of tab order (Naviagator's firstEl and lastEl properties). The references are used to control modality by looping around from the first to the last control and visa versa for tab/shift-tab navigation.

See applyKeyListeners

Returns: void

_show

protected void _show ( )
Protected implementation to handle how UI elements are hidden/shown.
Returns: void

_syncMask

protected void _syncMask ( )
Used to set the width/height of the mask in pixels to match the Calendar Container. Currently only used for IE6 and IE7 quirks mode. The other A-Grade browser are handled using CSS (width/height 100%).

The method is also registered as an HTMLElement resize listener on the Calendars container element.

Returns: void

_update

protected void _update ( cal )
Updates the Calendar rendered state, based on the state of the CalendarNavigator
Parameters:
cal <object> The Calendar instance to update
Returns: void

_updateMonthUI

protected void _updateMonthUI ( )
Updates the Navigator's month UI, based on the month value set on the Navigator object
Returns: void

_updateYearUI

protected void _updateYearUI ( )
Updates the Navigator's year UI, based on the year value set on the Navigator object
Returns: void

applyKeyListeners

void applyKeyListeners ( )
Attaches DOM listeners for keyboard support. Tab/Shift-Tab looping, Enter Key Submit on Year element, Up/Down/PgUp/PgDown year increment on Year element

NOTE: MacOSX Safari 2.x doesn't let you tab to buttons and MacOSX Gecko does not let you tab to buttons or select controls, so for these browsers, Tab/Shift-Tab looping is limited to the elements which can be reached using the tab key.

Returns: void

applyListeners

void applyListeners ( )
Attaches DOM event listeners to the rendered elements

The method will call applyKeyListeners, to setup keyboard specific listeners

Returns: void

cancel

void cancel ( )
Hides the navigator and mask, without updating the Calendar/CalendarGroup's state
Returns: void

clearError

void clearError ( )
Clears the navigator's error message and hides the error panel
Returns: void

clearErrors

void clearErrors ( )
Clears all validation and error messages in the UI
Returns: void

clearYearError

void clearYearError ( )
Removes the validation error UI for the year control
Returns: void

createMask

void createMask ( )
Creates the Mask HTMLElement and appends it to the Calendar/CalendarGroups container.
Returns: void

createNav

void createNav ( )
Creates the navigator's containing HTMLElement, it's contents, and appends the containg element to the Calendar/CalendarGroup's container.
Returns: void

destroy

void destroy ( )
Destroys the Navigator object and any HTML references
Returns: void

erase

void erase ( )
Removes all renderered HTML elements for the Navigator from the DOM, purges event listeners and clears (nulls) any property references to HTML references
Returns: void

getMonth

Number getMonth ( )
Returns the current month set on the navigator Note: This may not be the month set in the UI, if the UI contains an invalid value.
Returns: Number
The Navigator's current month index

getYear

Number getYear ( )
Returns the current year set on the navigator Note: This may not be the year set in the UI, if the UI contains an invalid value.
Returns: Number
The Navigator's current year value

hide

void hide ( )
Hides the navigator and mask The show method will fire the Calendar/CalendarGroup's beforeHideNav event and hideNav events
Returns: void

hideMask

void hideMask ( )
Hides the navigator's mask element
Returns: void

init

void init ( cal )
Init lifecycle method called as part of construction
Parameters:
cal <Calendar> The instance of the Calendar or CalendarGroup to which this CalendarNavigator should be attached
Returns: void

purgeKeyListeners

void purgeKeyListeners ( )
Removes/purges DOM listeners for keyboard support
Returns: void

purgeListeners

void purgeListeners ( )
Removes/purges DOM event listeners from the rendered elements
Returns: void

render

void render ( )
Renders the HTML for the navigator, adding it to the document and attaches event listeners if it has not already been rendered.
Returns: void

renderButton

String renderButton ( )
Renders the submit/cancel buttons for the navigator
Returns: String
The HTML created for the Button UI

renderNavContents

Array renderNavContents ( html )
Renders the contents of the navigator
Parameters:
html <Array> The HTML buffer to append the HTML to.
Returns: Array
A reference to the buffer passed in.

renderYear

Array renderYear ( html )
Renders the year label and control for the navigator
Parameters:
html <Array> The HTML buffer to append the HTML to.
Returns: Array
A reference to the buffer passed in.

setError

void setError ( msg )
Displays an error message in the Navigator's error panel
Parameters:
msg <String> The error message to display
Returns: void

setInitialFocus

void setInitialFocus ( )
Sets the initial focus, based on the configured value
Returns: void

setMonth

void setMonth ( nMonth )
Sets the current month on the Navigator, and updates the UI
Parameters:
nMonth <Number> The month index, from 0 (Jan) through 11 (Dec).
Returns: void

setYear

void setYear ( nYear )
Sets the current year on the Navigator, and updates the UI. If the provided year is invalid, it will not be set.
Parameters:
nYear <Number> The full year value to set the Navigator to.
Returns: void

setYearError

void setYearError ( )
Displays the validation error UI for the year control
Returns: void

show

void show ( )
Displays the navigator and mask, updating the input controls to reflect the currently set month and year. The show method will invoke the render method if the navigator has not been renderered already, allowing for lazy rendering of the control. The show method will fire the Calendar/CalendarGroup's beforeShowNav and showNav events
Returns: void

showMask

void showMask ( )
Displays the navigator's mask element
Returns: void

submit

void submit ( )
Updates the Calendar/CalendarGroup's pagedate with the currently set month and year if valid.

If the currently set month/year is invalid, a validation error will be displayed and the Calendar/CalendarGroup's pagedate will not be updated.

Returns: void

validate

Boolean validate ( )
Validates the current state of the UI controls
Returns: Boolean
true, if the current UI state contains valid values, false if not


Copyright © 2008 Yahoo! Inc. All rights reserved.