# Yahoo! UI Library

### Calendar 2.5.1

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

Show Private Show Protected

## 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 void __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.

Returns: `void`
  The value of the configuration property

#### _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`

#### _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 © 2007 Yahoo! Inc. All rights reserved.