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

### 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 montly 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