This document describes the design of the ACS DateTime service package.
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 specfications. 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.
This package was written largely to consolidate and improve the date, time, and calendar functionality existing in ACS 3.
None.
The ACS DateTime package does not have a data model.
None.
See examples.
dt_systime generates current system time (local or GMT)
dt_sysdate generates current system date
dt_format formats a time using the formatting codes
supported by the standard Unix time functions
dt_month_names generates a list of standard month names
dt_month_abbrev generates a list of standard month abbreviations
dt_julian_to_ansi converts Julian time to ANSI time (yyyy-mm-dd)
dt_ansi_to_pretty converts ANSI time to "pretty ANSI time" (yyyy-mm-dd to Month day,
year)
dt_ansi_to_list generates a Tcl list of date-time elements (year, month, day, hour,
minute, second)
dt_valid_time_p checks the validity of a time specification
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
See examples.
dt_widget_datetime generate HTML select widgets of varying granularity for
collecting date and time information from users.
dt_widget_month generates an HTML select widget for
months of the year
dt_widget_numeric_range generates an HTML select
widget for general numeric ranges
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.
dt_widget_month generates a basic monthly calendar
dt_widget_month_small generates a small monthly calendar
dt_widget_centered generates small monthly calendars
centered in a given month (previous, current, next)
dt_widget_year generates a yearly calendar (composed of small montly calendars)
given the starting month as a date
dt_widget_calendar_year generates a yearly calendar
based on calendar year (Jan to Dec), given any date within that
calendar year
dt_widget_calendar_navigation generates a calendar
navigation widget with viewing options for day, week, month and year
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.
Implemented by Ron Henderson (ron@arsdigita.com), based on the previous work of gregh@arsdigita.com and smeeks@arsdigita.com.