ACS DateTime

by Ron Henderson

I. Essentials

This document describes the design of the ACS DateTime service package.

II. Introduction

The ACS DateTime service is a collection of HTML widget generation procedures and date/time processing functions. The latter are built largely on top of the Tcl clock routines, although there are a small number of procedures that connect to the database for services like Julian date conversions.

Most the procedures defined within the ACS DateTime service take date/time information as input and return date/time strings to the caller. Rather than standardize on a low-level representation of time (like seconds since 00:00:00 UTC, January 1 1970) all of these procedures accept general date specifications. For example, the default date for dt_widget_datetime can be specified as "2001-01-05", "2000-01-05 09:57 pm", "2000-01-05 21:57", etc. Internally these are parsed by the standard Tcl procedure clock scan for processing and then converted back to a formatted string for output. This makes it easy to pass dates between the Tcl layer and the database.

III. Historical Considerations

This package was written largely to consolidate and improve the date, time, and calendar functionality existing in ACS 3.

IV. Competitive Analysis

None.

VI. Data Model Discussion

The ACS DateTime package does not have a data model.

VII. Legal Transactions

None.

VIII. API

Date and Time functions

See examples.

  1. dt_systime generates current system time (local or GMT)
  2. dt_sysdate generates current system date
  3. dt_format formats a time using the formatting codes supported by the standard Unix time functions
  4. dt_month_names generates a list of standard month names
  5. dt_month_abbrev generates a list of standard month abbreviations
  6. dt_julian_to_ansi converts Julian time to ANSI time (yyyy-mm-dd)
  7. dt_ansi_to_pretty converts ANSI time to "pretty ANSI time" (yyyy-mm-dd to Month day, year)
  8. dt_ansi_to_list generates a Tcl list of date-time elements (year, month, day, hour, minute, second)
  9. dt_valid_time_p checks the validity of a time specification
  10. dt_interval_check checks the validity of a time interval by comparing start and end times and determining if they represent a positive, empty, or negative time range

Date and Time widgets

See examples.

  1. dt_widget_datetime generate HTML select widgets of varying granularity for collecting date and time information from users.
  2. dt_widget_month generates an HTML select widget for months of the year
  3. dt_widget_numeric_range generates an HTML select widget for general numeric ranges

Calendar widgets

See examples.

Each of the following allow the programmer to supply calendar details in an ns_set keyed on Julian date and returns an HTML table.

  1. dt_widget_month generates a basic monthly calendar
  2. dt_widget_month_small generates a small monthly calendar
  3. dt_widget_centered generates small monthly calendars centered in a given month (previous, current, next)
  4. dt_widget_year generates a yearly calendar (composed of small monthly calendars) given the starting month as a date
  5. dt_widget_calendar_year generates a yearly calendar based on calendar year (Jan to Dec), given any date within that calendar year
  6. dt_widget_calendar_navigation generates a calendar navigation widget with viewing options for day, week, month and year

XII. Future Improvements/Areas of Likely Change

Many of the calendar widgets generate extensive HTML from within Tcl procedures. This will eventually be converted to a template-based system so that the display properties are more easily customized.

XIII. Authors

Implemented by Ron Henderson (ron@arsdigita.com), based on the previous work of gregh@arsdigita.com and smeeks@arsdigita.com.

ron@arsdigita.com