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
Private flag, to identify IE Quirks
__isMac
- private object
Private flag, to identify MacOS
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
Deprecated: Made public. See the public DEFAULT_CONFIG property
_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
Reference to the HTMLElement used to hide the navigator without updating the
Calendar/Calendar group
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
- HTML : The markup to use for the month label. Defaults to "Month".
- year
- HTML : The markup to use for the year label. Defaults to "Year".
- submit
- HTML : The markup to use for the submit button label. Defaults to "Okay".
- cancel
- HTML : The markup to use for the cancel button label. Defaults to "Cancel".
- invalidYear
- HTML : The markup 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"
Reference to the HTMLElement used to display validation errors
Reference to the first focusable control in the navigator (by default monthEl)
id
- String
The unique ID for this CalendarNavigator instance
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
Reference to the HTMLElement used to input the month
navEl
- HTMLElement
Reference to the HTMLElement used to render the navigator's bounding box
Reference to the HTMLElement used to update the Calendar/Calendar group
with the month/year values
The suffix added to the Navigator's ID, to generate
a unique ID for the "Cancel" button.
YAHOO.widget.CalendarNavigator.CLASSES contains constants
for the class values applied to the CalendarNaviatgator's
DOM elements
Class applied to buttons wrapping element
Class applied to the submit/cancel button's bounding box
Class applied to default controls
Class applied to the validation error area's bounding box
Class applied to controls with invalid data (e.g. a year input field with invalid an year)
Class applied to the Navigator mask's bounding box
Class applied to the month label/control bounding box
Class applied to the month input control
Class applied to the Calendar Navigator's bounding box
Class applied to the Calendar/CalendarGroup's bounding box to indicate
the Navigator is currently visible
Class applied to the year label/control bounding box
Class applied to the year input control
The suffix added to the Navigator's ID, to generate
a unique ID for the error bounding box.
The suffix added to the Calendar/CalendarGroup's ID, to generate
a unique ID for the Navigator and it's bounding box.
The suffix added to the Navigator's ID, to generate
a unique ID for the month control.
The suffix added to the Navigator's ID, to generate
a unique ID for the "Submit" button.
Regular expression used to trim strings
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
The suffix added to the Navigator's ID, to generate
a unique ID for the year control.
The amount by which to increment the current year value,
when the page up/down key is pressed on the year control
The number of digits to which the year input control is to be limited.
The amount by which to increment the current year value,
when the arrow up/down key is pressed on the year control
Regular expression used to validate the year input
yearEl
- HTMLElement
Reference to the HTMLElement used to input the year
Methods
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_CONFIG
- Parameters:
-
Case
<String>
sensitive property name.
-
true,
<Boolean>
if the property is a string property, false if not.
- Returns:
- The value of the configuration property
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
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.
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
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
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
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
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
protected
void
_show
(
)
Protected implementation to handle how UI elements are
hidden/shown.
protected
void
_syncMask
(
)
Used to set the width/height of the mask in pixels to match the Calendar Container.
Currently only used for IE6 or IE in 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.
protected
void
_update
(
cal
)
Updates the Calendar rendered state, based on the state of the CalendarNavigator
- Parameters:
-
cal
<object>
The Calendar instance to update
protected
void
_updateMonthUI
(
)
Updates the Navigator's month UI, based on the month value set on the Navigator object
protected
void
_updateYearUI
(
)
Updates the Navigator's year UI, based on the year value set on the Navigator object
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.
void
applyListeners
(
)
Attaches DOM event listeners to the rendered elements
The method will call applyKeyListeners, to setup keyboard specific
listeners
void
cancel
(
)
Hides the navigator and mask, without updating the Calendar/CalendarGroup's state
void
clearError
(
)
Clears the navigator's error message and hides the error panel
void
clearErrors
(
)
Clears all validation and error messages in the UI
void
clearYearError
(
)
Removes the validation error UI for the year control
void
createMask
(
)
Creates the Mask HTMLElement and appends it to the Calendar/CalendarGroups
container.
void
createNav
(
)
Creates the navigator's containing HTMLElement, it's contents, and appends
the containg element to the Calendar/CalendarGroup's container.
void
destroy
(
)
Destroys the Navigator object and any HTML references
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
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
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
void
hide
(
)
Hides the navigator and mask
The show method will fire the Calendar/CalendarGroup's beforeHideNav event and hideNav events
void
hideMask
(
)
Hides the navigator's mask element
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
void
purgeKeyListeners
(
)
Removes/purges DOM listeners for keyboard support
void
purgeListeners
(
)
Removes/purges DOM event listeners from the rendered elements
void
render
(
)
Renders the HTML for the navigator, adding it to the
document and attaches event listeners if it has not
already been rendered.
Array
renderButtons
(
html
)
Renders the submit/cancel buttons for the navigator. NOTE: The contents of the array passed into this method are added to the DOM as HTML, and should be escaped by the implementor if coming from an external source.
- Parameters:
-
html
<Array>
The HTML buffer to append the HTML to.
- Returns:
Array
- A reference to the buffer passed in.
HTML[]
renderNavContents
(
html
)
Renders the contents of the navigator. NOTE: The contents of the array passed into this method are added to the DOM as HTML, and should be escaped by the implementor if coming from an external source.
- Parameters:
-
html
<HTML[]>
The HTML buffer to append the HTML to.
- Returns:
HTML[]
- A reference to the buffer passed in.
Array
renderYear
(
html
)
Renders the year label and control for the navigator. NOTE: The contents of the array passed into this method are added to the DOM as HTML, and should be escaped by the implementor if coming from an external source.
- Parameters:
-
html
<Array>
The HTML buffer to append the HTML to.
- Returns:
Array
- A reference to the buffer passed in.
void
setError
(
msg
)
Displays an error message in the Navigator's error panel.
- Parameters:
-
msg
<HTML>
The markup for the error message to display. NOTE: The msg passed into this method is added to the DOM as HTML, and should be escaped by the implementor if coming from an external source.
void
setInitialFocus
(
)
Sets the initial focus, based on the configured value
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).
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.
void
setYearError
(
)
Displays the validation error UI for the year control
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
void
showMask
(
)
Displays the navigator's mask element
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.
Boolean
validate
(
)
Validates the current state of the UI controls
- Returns:
Boolean
- true, if the current UI state contains valid values, false if not