National Oceanic and
Atmospheric Administration
United States Department of Commerce

DateWidget

Last modified: Mon, 04/03/2017 - 17:29
Creates smart date selectors that restrict user input to valid dates.

Overview

The DateWidget object manages a collection of Year-Month-Day-Time Selectors for user selection of a single Date-Time or a pair of start and end Date-Times.

The DateWidget object is initialized with a valid range (DateLo <--> DateHi) and allows the user to select dates Date1 and Date2 within this range (DateLo <= Date1 <= Date2 <= DateHi).

It also handles the number of days in each month as well as leap years so that the user can never select an invalid date (e.g. "Sept 31").

Climatologies are handled by setting the DateWidget render format to not include the Year selector. You must still specify a year when initializing the DateWidget and this year will be returned by the getDate1() and getDate2() methods. The HTML, however, will display the text 'Climatology: ' instead of the Year selector.

The Date1 and Date2 Year-Month-Day-Time selectors each show all possible dates in the valid range. Setting Date1 to a value higher than the current Date2 causes Date2 to reset to the same value as Date1, satisfying (Date1 <= Date2).

Changes from v1.0 DateWidget.js

  • 'RESTRICT_OPTIONS' mode is no longer supported. (It is unlikely you or anyone else ever used it.)

  • Dates beginning in year '0001' are no longer automatically interpreted as climatologies. Climatologies are inferred whenever the rendering format does not include the Year selector.

  • DateWidget now adheres to the LASWidget interface described in the LAS javascript components Widget Interface.

Documentation & Source

  • API
  • $LAS_HOME/WebContent/JavaScript/components/DateWidget.js

Examples

  • $LAS/home/WebContent/examples/Pacific_Ocean_temps.html

Here is the relevant snippet from the <head> in that example:

...

<!--
 * Imported libaries:
 *
 * xmldom.js Parses the LASRequest XML. Used by LASRequest.js.
 * LASRequest.js Provides an API for accessing/modifying LASRequest elements.
 * DateWidget.js Creates and populates a date Widget (group of Selectors).
-->
 <script type="text/javascript" src="../JavaScript/components/xmldom.js"></script>
 <script type="text/javascript" src="../JavaScript/components/LASRequest.js"></script>
 <script type="text/javascript" src="../JavaScript/components/DateWidget.js"></script>

 <script type="text/javascript">

...

 // Initialize the DateWidget
 // Then render it in the identified table cell with only Month and Year Selectors showing.
 // This renders a single set of Month-Year selectors. To allow selection of a range of 
 // dates, a second render format must be given e.g.:
 // DW.render('DateWidgetCell','MY','MY)

 DW = new DateWidget('1980-01-15','2006-01-15');
 DW.render('DateWidgetCell','MY');

...

/**
 * Use any user selected parameters to update the LASRequest.
 */
function updateLASRequest() {
 Req.setRange('t',DW.getDate1_Ferret());
}

...

 </script>

Background

Web interfaces to climate data typically require the user to specify asingle date or a range of dates. These dates must be chosen froma range of valid dates and should exclude non-existent dates like 'Sep.31' or 'Feb. 29' in non-leap years. The DateWidget javascriptcomponent makes it easy to add such a smart user interface component to a web page.

Features of the DateWidget component include

  • the DateWidget is initialized with a time domain is specified within which the user is allowed to select a range:
    DW = new DateWidget('1980-01-01','2006-12-31')
  • The DateWidget is rendered with the specified Selectors in an HTML element with a specified 'id' attribute:
    DW.render(HTML_element_id, 'YMDT'[,'YMDT'])
  • Month, Day and Time selectors are dynamically updated based on user selections.
  • Dynamic updating restricts users to valid months and days for the start and end years which may begin or end mid-year.
  • Dynamic updating ensures that the Day widget always has the correct number of days for the month (includes leap year calculations).
  • Date1 is guaranteed to be <= Date2. All dates are visisble in both date widgets. If the user sets Date1 > Date2 then Date2 is automatically updated to match Date1.
  • All dates are guaranteed to be ISO standard YYYY-MM-DD[ HH:MM:SS] and always have 4-digit years and 2-digit everything else.
  • Support for Time widget intervals with deltaMinutes and offsetMinutes.
  • Higher resolution selectors may be left out to have monthly or yearly time axes by specifying the render format.
  • Date2 selectors may be left out to have user select a time point instead of a time range by omitting the render format for Date2.
  • DateWidgets may be initialized to TODAY or NOW and offset by a specified number of minutes