Calendar Package Requirements
by W. Scott Meeks
This document describes the requirements for the ACS Calendar package.
The calendar primarily allows people to add, view, and edit items on
personal and group calendars. It also provides an API which be used
by other applications to provide additional calendar functionality.
II. Vision Statement
The ArsDigita calendar allows one to enter and
keep track of anything that could reasonably be written on a paper
calendar. In addition, the calendar can be accessed from any web
browser. Various types of additional information related to an item
can be added. This information is integrated with other components of
the ACS. The calendar also provides different ways of viewing the
calendar information. Eventually the calendar will
integrate with other systems such as PDAs and email.
At a group level, the calendar can be tied to particular ACS groups
where all group members can see items entered for that group. Items
from the various groups one is a member of can be shown on
one's personal calendar.
This package could be used with any application where tracking items
in time is important. This would include most business settings for
meetings and appointments, educational settings, clubs, and other
III. System/Application Overview
The Calendar Package is made up of five major functional areas:
- Item Manipulation
- Group Calendars
- Type Management
includes every aspect of adding, editing,
viewing, and deleting calendar items. This also includes adding attachments
and setting up recurring items.
Views covers the display of calendar items in the context of a
particular span of time.
Navigation comprises the links used to change the currently viewed
Group Calendars involve switching between group calendars and the
personal calendar, adding group items, controlling the display of group
items on personal calendar, and adding and deleting group calendars.
Type Management is for adding, editing, and deleting item types for
users and groups.
IV. Use-cases and User-scenarios
There are four main classes of users for the Calendar:
- Community Members
- Group Administrators
- Site-wide Administrators
The individual is primarily interested in having a personal
web-based calendar. The calendar needs to support manipulating basic
calendar items that include times, titles, and possibly descriptions.
Here are some examples of how Al uses his calendar. At home Monday
morning, after checking his email, he goes to the week view in the
calendar for this week. He sees that he has a dental appointment at
9:30 this morning (which he almost forgot about) and a meeting on
After his dental appointment, he has to schedule a followup
appointment. When he gets into work, he brings up his calendar there,
looks at the month view for next month, makes sure the time for the
appointment is free, then clicks the link to add an item on that day.
In the form that comes up, he enters "dental appointment" as the
title, the time of the appointments, and submits the form.
Tuesday morning, reminder email comes out about massages at work. He
uses the Intranet massage reservation page to schedule his massage.
After lunch, he checks his calendar to see what he has in the
afternoon and notes the reminder for his massage.
Later that evening, he realizes he forgot his Mother's birthday last
week. After getting off the phone with her, he immediately goes to
his calendar and adds a new item. He enters the date as his Mother's
birthday, specifies no associated time, enters "Mother's Birthday" as
the title, and marks the item to recur. On the form for how the item
should recur, he specifies every year.
In addition to the features available in the personal calendar,
community members will be interested in the group calendar
Here is how Beth uses her calendar. She's a member of the
Group Leaders (GL) group and of the Political Discussion (PD)
group among others. Links to the calendars for these groups appear on her
calendar. In addition, because GL is very important she has her
calendar set up to show items for that group on her personal
calendar. However, because PD is something she's only interested in
when she has free time, items for that group don't appear on her
personal calendar and she has to explicitly go to that calendar to see
the group's schedule.
Because she's not always aware of the items being added to the group
calendars, she finds the list view very useful. She can quickly see
what has been added recently and what is coming up in the near future.
She also finds attachments to items useful. In particular, by
clicking on the attachment for a GL meeting, she is taken to the
WimpyPoint presentation of the agenda for the meeting.
Group administrators by default are the only users that can
add, edit, or delete items on group calendars. They can also create
and delete calendars for the groups they administrate.
Carl, for example, is one of the administrators for the
Marketing group. He needs to set up a twice weekly meeting. He goes
to the Marketing calendar and selects the link to add an item. He
sets the date to next Tuesday, the time to 10am, and sets it to recur
every week on Tuesday and Thursday.
Now, once the agenda is prepared for each meeting, he can view the
item for a particular meeting, select "add attachment" and add a link
to the WimpyPoint presentation for the agenda for that meeting.
Oops, it turns out that the first meeting of next month will have
to be delayed until 11. No problem. Carl edits the item for that
particular instance of the recurring meeting. He changes the time to
11am and indicates that this change should only effect the current
There is no qualitative difference in what site-wide
administrators can do versus group administrators. The difference
is that site-wide administrators can work on all groups and have an
interface which allows them to effect more than one group at a time.
V. Related Links
VI.A Requirements: Personal Calendar
10 Personal Calendar
10.0 Overall User Interface
10.0.10 The root URL for the package should be /calendar/.
10.0.20 The calendar page should clearly identify which user or
group the calendar is for.
10.0.30 The calendar should support navigation to view different
dates in a simple manner.
10.0.40 Links to functions should be clear and obvious.
10.0.50 There should be a detailed calendar presentation showing
an appropriate level of detail of the user's calendar items.
10.10.0 Different views should be easily selectable.
10.10.10 List View
10.10.10.10 The calendar should support a view showing selected
items in a tabular list format.
10.10.10.20 Columns should include date, time, and other relevant
10.10.10.30 The columns should be sortable.
10.10.10.40 There should be at least two lists of items. One list
should consist of items whose dates occur within a user-specified
number of days of the currently viewed date.
10.10.10.50 One list should consist of items that have been added
within a user-specified number of days of the current date.
10.10.20 Day View
10.10.20.10 The calendar should support a view showing all the
items for a particular day.
10.10.20.20 This view should show the items arranged
chronologically with a time guide along one side.
10.10.20.30 The range of the time guide should be
10.10.20.40 The user should have the option of compressing the
time guide so that only times with items are shown.
10.10.20.50 Items that overlap in time should be shown in a clear
10.10.20.60 There should be a simple mechanism for adding an item
starting at a particular hour.
10.10.20.70 The day view should support items that don't have a
specified start and end time and the time guide should include a slot
for these items.
10.10.30 Week View
10.10.30.10 The calendar should support a view showing all the
items for a particular week.
10.10.30.20 The items for a particular day should be grouped
10.10.30.30 There should be a simple mechanism for adding an item
for a particular day.
10.10.30.40 The currently viewed date should be indicated in some manner.
10.10.40 Month View
10.10.40.10 The calendar should support a view showing all the
items for a particular month.
10.10.40.20 The items for a particular day should be grouped
10.10.40.30 There should be a simple mechanism for adding an item
for a particular day.
10.10.40.40 The currently viewed date should be indicated in some manner.
10.10.50 Year View
10.10.50.10 Purely as a navigation mechanism, the calendar should
support a view that shows all months and days in a particular year but
not necessarily with any information on items on the days
10.10.50.20 For each month, there should be a link to the month
view of that month.
10.10.50.20 For each day, there should be a link to the day
view of that day.
10.20.10 Navigation Widget
10.20.10.10 The calendar should provide a widget for collecting
together related navigation links. This should be similar to the
widget provided by Yahoo
Calendar and Excite Planner.
10.20.10.20 Navigation to a different date should maintain the
10.20.10.30 In the list, day, and week views, the widget should
display a mini calendar of the days of the current month. Each day
should be a link except for the currently viewed day which should not
be a link and should be highlighted in some manner.
10.20.10.40 In the month view, the widget should contain a list of
the months of the year. Each month should be a link except for the month
containing the currently viewed day which should not be a link and should be
highlighted in some manner.
10.20.10.50 In the year view, the widget should contain a short
list of years before and after the current year. Each year should be
a link except for the year containing the currently viewed day which
should not be a link and should be highlighted in some manner.
10.20.10.60 The widget should contain some mechanism for entering
an arbitrary date.
10.20.10.70 The widget should clearly display today's date along
with some mechanism for navigating to that date.
10.20.10.80 In the list, day, and week views there should be a
mechanism for jumping forwards or backwards by a whole month at a
10.20.10.90 In the month and year views, there should be a
mechanism for jumping forwards or backwards by a whole year at a
10.20.20 View Specific Navigation
10.20.20.10 Each view except for list should have some easy
mechanism for jumping forward or backward by the interval being
10.20.20.20 Selecting the day in week, month, or year view should
take you to the day view for the appropriate day.
10.20.20.30 Selecting the month in year view should take you to
the month view for the appropriate month.
10.30 Adding Items
10.30.10 Adding an item should involve entering information for
the item in a form and then submitting that form. Title and date are
required fields. Also required is either a start time or an explicit
indication that this item does not have a start time. Date and time
should have default values already entered. Non-required fields
should include end time or duration, type information, a
description, and an indicator as to whether or not this item recurs.
10.30.20 There should be a simple, clearly labeled link for
adding an item. The date should default to the currently viewed date
and the time to 12-1pm.
10.30.30 The time guide in the day view should have links from
each hour and from the slot for items with no start time.
10.30.40 Selecting the no start time link should bring up the
form with the date defaulting to the currently viewed date and the
no start time indicator set.
10.30.50 Selecting a link from a specific hour should bring up
the form with the date defaulting to the currently viewed date, the
start time to the hour selected, and the end time to one hour
10.30.60 The week view should have a link for each day for adding
an item. The date should default to the date associated with the link
and the time should be 12-1pm.
10.30.70 The month view should have a link for each day for adding
an item. The date should default to the date associated with the link
and the time should be 12-1pm.
10.40 Viewing Items
10.40.10 Selecting an item's title from any view should display
details for that view, including links to edit, add attachment, and
10.50 Editing Items
10.50.10 While viewing an item, select "Edit". You should get a form
allowing you to edit the title, date, times, types, and description
for the item. Non-recurring items should have a "Repeat?" field
but not an "Update?" field.
10.60 Adding Recurring Items
10.60.10 If the recurring item indicator is selected in the form
for adding an item, then after submitting that form, a second form
should be displayed summarizing the date and time of the item
and providing fields to set how the item recurs.
10.60.20 The form should include fields to enter the type of
interval, the number of intervals between recurrences, and any
specific information for the selected type of interval.
10.60.30 Recurring on a daily basis should be supported.
10.60.40 Recurring on a weekly basis should be supported. For
weekly recurrences, it should be possible to specify exactly which
days of the week.
10.60.50 Recurrences every month on a particular date should be
10.60.60 Recurring every month on a particular day of a
particular week should be supported.
10.60.70 If a date in the 4th or 5th week of a month has been
selected, then an option should be presented allowing an item to recur
on a particular day of the last week of a month.
10.60.80 Recurring yearly on a particular date should be supported.
10.70 Editing Recurring Items
10.70.10 Selecting Edit when viewing a repeating item should add
a field at the bottom of the form to specify whether any changes
should be applied to only the current instance being edited or to all
instances of this recurring item.
10.80 Adding Attachments to Items
10.80.10 When viewing an item, there should be a link to add an
attachment to that item. Selecting that link should bring up a form
to add attachments of various types.
10.80.20 The form should include a field for the title of the
10.80.30 One type of attachment supported should be an uploaded
file. This type should be handled in the standard ACS manner.
10.80.40 One type of attachment should be a URL.
10.80.50 One type of attachment should be a block of text. The
form should provide a text box for entering the text and a way to
indicate if the text is plaintext or HTML.
10.80.60 After adding an attachment of any sort, the calendar
should return to the view of the item which should have a list of
attachments including the attachment just added.
10.80.70 For each attachment listed, there should be displayed
the title of the attachment, a link to the content of the attachment,
a link to manage the attachment, and a link to edit it.
10.80.80 For a file attachment, the content link should return
the content of the file.
10.80.90 For a URL attachment, the content link should navigate
to the URL.
10.80.100 For a text attachment, the content link should display
the entered text.
10.80.110 The manage link links to the management page of the
corresponding file in the file-storage system.
10.80.120 The edit link allows directly editing the content of
10.90 Item Types
10.90.10 Adding Types to Items
10.90.10.10 If the user or group has types defined for the calendar
being viewed, then the add item form should have an input for specifying one
or more types for the item.
10.90.10.20 If the user or group has types defined for the calendar
being viewed, then the edit item form should have an input for changing
the types for the item.
10.90.10.30 If the item has types specified, then the types should
be listed when viewing the item.
10.90.10.40 The types information should also be shown in the list views.
10.90.20 Adding New Types
10.90.20.10 There should be a link from the calendar page to the
type management pages which should clearly indicate whether the types
being managed are for the users calendar or for a particular group
10.90.20.20 There should be a list of defined types.
10.90.20.30 There should be a form to enter a new type.
10.90.20.40 There should be a form to edit the name of an existing
10.90.20.50 There should be a form to delete a type.
10.100 Deleting Items
10.100.10 When viewing an item, there should be a link to delete
10.100.20 Selecting the delete link should bring up a
10.100.30 If the item is not recurring, then the choice buttons will be
OK and Cancel.
10.100.40 If the item is recurring, then in addition to the
choice buttons, there should be a selection to indicate either the
current instance only or all occurrences.
10.100.50 Selecting Cancel should return to the item view in all
10.100.60 Selecting OK should delete the item in question.
10.100.70 If the item was recurring and all occurrences was
selected, then all other occurrences of the item should be deleted as
10.100.80 Selecting OK should return to the view where the item
was originally selected.
VI.B Requirements: Group Calendars
20 Group Calendars
20.10 The calendar should display a list of calendars that the
user can access. At a minimum, this will include the user's personal
calendar. If the user belongs to groups that have group calendars,
there should be additional links to those group calendars.
20.20 Selecting a link to a group calendar should present a
calendar showing only items for that group.
20.30 The group calendar should have a link back to the user's
personal calendar as well as to any other group calendars.
20.40 On the personal calendar, in addition to the links to
the group calendars, there should also be a toggle for each
group that controls whether or not items from that group appear on the
20.50 On the personal calendar, group items should indicate what
group they are for.
20.60 The link for adding an item should clearly indicate
whether a group item or a personal item will be created.
VI.C Requirements: Managing Group Calendars
30 Managing Group Calendars
30.10 If the user is an administrator for any groups, the
calendar should display a link to a page for managing group
30.20 The page for managing group calendars should have a list
of existing group calendars for the groups the user administers and
controls to manipulate the calendars.
30.30 There should be a link to the admin page for the group.
30.40 There should be a link to the pages for managing types for
30.50 There should be a way to delete the calendar which should
include a confirmation dialog.
30.60 The page for managing group calendars should also have a
form containing a list of groups the user administers which do not
already have calendars. The user should be able to select some of
these groups and create calendars for the selected groups by
submitting the form.
VI.D Requirements: Calendar Administration
40 Calendar Administration
40.10 Site-wide administrators, should be able to access
/admin/calendar/. This page should have a sections for groups
with calendars and a section for group types with calendars.
40.20 The groups with calendars section you should have a
function to create a group calendar and a list of groups with
40.30 The create a group calendar function should provide the
administrator the ability to select from existing groups without
calendars and then create calendars for those groups. After creating
groups calendars, the administrator should be returned to the
/admin/calendar/ page where the new group calendars should be
40.40 The list of group calendars should include a link for each
group to it's admin page.
40.50 The list of group calendars should include a delete
function for each calendar. This function should have a
confirmation dialog which returns to the admin page.
40.60 The group types with calendars should have a list of the
top level group types defined. This list should indicate which group
types automatically have group calendars and which don't.
40.70 When a group type is set to automatically have calendars,
then all existing groups of that type will have calendars created if
needed, and any new groups of this type that are added will
automatically have calendars.
40.80 When a group type is set to not automatically have
calendars, then any existing groups of that type that have calendars
will keep their calendars, but any new groups of that type will not
automatically have calendars.
VI.E Requirements: API
50.10 Calendar Item Manipulation
50.10.10 Provide a function to add a new item to a calendar. This
function should support specifying all the values that can be
specified in the add item form, it should allow creating either a user
or a group item, and it should support specifying a mapping between
the new item and an arbitrary table and id in the database.
50.10.20 Provide a function to return a list of all groups with
50.10.30 Provide a function do delete items mapped to a particular
table and id in the database.
50.10.40 Provide a function to delete a particular item.
50.10.50 Provide a function to insert a recurring item.
50.20 Calendar Views
50.20.10 Provide a function to generate the HTML for the table of
50.20.20 Provide a function to generate the HTML for the table of
50.20.30 Provide a function to generate the HTML for the list view.
50.20.40 Provide a function to generate the HTML for the day view.
50.20.50 Provide a function to generate the HTML for the week view.
50.20.60 Provide a function to generate the HTML for the month view.
50.20.70 Provide a function to generate the HTML for the year view.
50.20.80 Provide a function to generate the HTML for the navigation
50.20.90 Provide a function to generate the HTML for the complete
VI.E Requirements: Integration with Existing Modules
60 Integration with Existing Modules
60.10 Intranet Module
60.10.10 The pre-existing link to the old calendar showing
absences and events on /intranet/ad-index.tcl (/calendar/monthly)
should be changed to link to a new group calendar page which shows
absences and old calendar items.
60.10.20 Adding an absence from /intranet/absences/ should add an
equivalent item on the monthly calendar.
60.10.30 Editing the absence should cause an equivalent change
in the corresponding calendar item.
60.10.40 Deleting the absence should also delete the
corresponding calendar item.
60.20 Reservations Module
60.20.10 The /reservations/cr/ (conference room) page should
provide an option for marking calendars.
60.20.20 If the mark calendar option is selected, then after the
reservation information is submitted, an additional form should be
presented for determining which calendars should be marked.
60.20.30 One option on the form should be to select from a list
of existing group calendars. A calendar item corresponding to the
reservation will be added to the group calendar.
60.20.40 One option should be to select a list of users. A
calendar item corresponding to the reservation will be added to the
personal calendar of each user.
60.20.50 Canceling a reservation should remove the corresponding
item(s) from the calendar(s).
60.20.60 Making a massage reservation from /reservations/massage/
should add a corresponding item to the users personal calendar.
60.20.70 Canceling a reservation should delete the corresponding
VII. Revision History
|Document Revision #
||Action Taken, Notes
||W. Scott Meeks
Last modified: $Date: 2001/01/22 04:24:12 $