## ACS DateTime Requirements

by Ron Henderson

### I. Introduction

This document describes the requirements for the ACS DateTime service package.

### II. Vision Statement

ACS DateTime has the following primary functions:

- Allows applications to use a common set of procedures for collecting date and time information from users.
- Provides utilities to convert and format date and time information.
- Provides customizable form fragment widgets of varying degrees of temporal granularity through which applications can collect date and time information.
- Provides customizable calendar display widgets that allow applications to hook calendar information into a flexible display mechanism.

Note that most of this functionality has existed within the ACS for a long time, but it has been spread over a combination of ACS and module libraries. The ACS DateTime service packages brings these procedures into a common framework and provides for a more consistent use of formatting conventions.

Note that these procedures do not make any specific reference to timezone information and do not provide for conversion between timezones. This is left up to the application programmer. For information on timezone conversions see the ACS Reference service package and specifically the timezone reference pack therein.

### III. System/Application Overview

This service packages consists of a set of Tcl widget libraries and other procedures for processing date and time information. These libraries are roughly separated into date-time and calendar procedures.

### IV. Use-cases and User-Scenarios

This package is only used as a procedural library for applications.

### V. Related Links

None.

### VI. Requirements

#### Date and Time functions

1. Generate current system time (local or GMT)
2. Generate current system date
3. Format a calendar time (system-dependent representation of time) using the formatting codes supported by the standard Unix time functions
4. Generate a list of standard month names
5. Generate a list of standard month abbreviations
6. Convert Julian time to ANSI time (yyyy-mm-dd)
7. Convert ANSI time to "pretty ANSI time" (yyyy-mm-dd to Month day, year)
8. Generate a Tcl list of date-time elements (year, month, day, hour, minute, second)
9. Check 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

1. Generate HTML select widgets for collecting date and time information from users with varying granularity. Granularity should be optional and specified in units of seconds, minutes, fives (five minute intervals), quarters (fifteen minute intervals), halves (thirty minute intervals), hours, days, or months
2. Generate an HTML select widget for months of the year
3. Generate an HTML select widget for general numeric ranges

#### Calendar widgets

All of the following allow the programmer to supply calendar details in an `ns_set` keyed on Julian date, and return an HTML table.

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

### VII. Revision History

    $Log: requirements.html,v $
    Revision 1.2  2002/09/18 21:04:01  jeffd
    cleanup from sloan

    Revision 1.1.1.1  2002/06/25 17:42:13  aegrumet
    OpenACS and dotLRN heads, 2002-06-13

    Revision 1.1.1.1  2001/04/20 20:51:09  donb

    Forgot to define binary files before importing, so .gifs were messed up.

    Revision 1.7  2001/01/07 13:19:16  jfinkler
    fixed a few typos and reworded a bit

    Revision 1.6  2001/01/07 13:18:09  jfinkler
    fixed a few types and reworded doc a bit

    Revision 1.5  2001/01/06 01:53:03  ron
    First complete pass at all of the documentation.  Added complete
    examples of all of the public API calls.

    Changed some of the API procedures for consistency.  All of the
    HTML-generating procedures now start with "dt_widget", for example.

    Revision 1.4  2000/12/10 01:54:47  ron
    minor cleanup to docs; still needs lots of work

ron@arsdigita.com