Calendar Package Design Documentation

I. Essentials

II. Introduction

At a personal level, 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.

The calendar is not intended as a replacement for a PDA but should eventually work in conjunction with one's PDA. The calendar is not a meeting scheduler, but could work in conjunction with a scheduler or free time finder. The calendar is also not designed for conference agendas and management, though it could be used to list conference scheduling at a high level. It's also not a project management or workflow tool, but again, it could be used in conjunction with such tools.

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 community organizations. For example, the calendar package is a key component of the education solution that has been implemented for the Sloan School of Management, ArsDigita University, and MIT's 6.916 course calendar. There are a number of features which any application must bring to the table to be reasonably considered a complete calendaring application. The ArsDigita calendar package currently supports all but one of these features:

The one key missing feature is the ability to set up reminders or alarms. While this is an important feature, it wasn't a critical client feature for the first release. However, this feature will be in the next version.

There are several features that add value to the ArsDigita calendar over and above the "table stakes". These include:

There are a number of other systems which, at least superficially, might appear to address the same requirements. I will go into more detail below in the competitive analysis section, but briefly here are the key differences between these systems and the ArsDigita calendar package.

III. Historical Considerations

Recurring items

The choice of design of the data model and implementation for recurring items was critical because it impacted the design of the key tables and the implementation of the most important queries and data manipulation statements.

Briefly, one choice is to insert only a single row for each recurring item, regardless of the number of times it will recur. Then to get the items for any particular day, it is necessary to compute for each item whether it would recur on that particular day. The alternative is to insert a row for each recurrence (possibly on an as needed basis.) Then to get the items for a particular day, one can query directly for items whose date is the same as the day in question.

Fundamentally this presents a time vs. space trade-off. Given that computation is relatively expensive, and that in most cases, only a small additional amount of information needs to be stored for recurrences, this seemed a reasonable trade-off, at least for the first version of the package. Additionally this approach made it much easier to handle individual exceptions and to individualize instances by adding attachments and changing titles. However it does make it more difficult to handle items that recur indefinitely; in fact this is not yet supported in the calendar package.

Templates vs. Tcl

It would be ideal if the calendar package were simple to customize for clients. Initially the calendar package was implemented using the version of the templating system and form manager available. However, as time went on, less and less of the package used the templating system. First, the form manager was dropped. Then, various views became so complex that they couldn't be done using templates. Finally, the performance liabilities proved to be too great and all use of the templating system was dropped.

It is possible that the new Dynamic Publishing System (DPS) may solve the various problems with the old templating system. This will be investigated for a future version of the calendar package.

Old Calendar

Finally, a nod must be given to the old calendar module. This module had a very simple data model. The key missing element were times (and not just dates) for items. However, pieces of the existing calendar widgets were the basis of some of the existing display code, and the need to emulate the monthly calendar view of employee absences drove some design decisions. Finally, much of the calendar categories code was re-used in the implementation of the current calendar item types feature, with the addition of multiple types per item.

IV. Competitive Analysis

These are the key features missing from competing software: There are a number of features lacking in the calendar package which are present in competing software. Unfortunately, given the limited resources available for the calendar package, not all possible features could be implemented. However, some of these features are clearly very important and I will note those I expect to be implemented within the next version or two.

V. Design Tradeoffs

Recurring items

Two choices were considered for supporting recurring items. One choice is to insert only a single row for each recurring item, regardless of the number of times it will recur. This row contains all the information necessary to compute whether or not that item would recur on a particular day. So to get all the items for any particular day, it would be necessary to compute for each item whether it would recur on that particular day.

The alternative is to insert a row for each recurrence. To get the items for a particular day, one can query directly for items whose date is the same as the day in question, and selecting for items across a range can be done with a single query

In choosing the second approach, there were really two tradeoffs being made. The obvious tradeoff is time vs. space. Computation, particularly if it might need to be done in Tcl and not solely in the database, is relatively expensive compared to storing additional information in the database. In most cases, the only information that needs to be stored for recurrences is the date and time of the recurrence.

The second tradeoff is in software complexity. In looking at the two choices, the first approach, to insert only a single row, seemed to require a significantly more complex design. Thus the design, implementation and eventual maintenance time would be greater. Particularly given that there were hard deadlines in the use of the calendar package in the education solution, it made sense to go with the simpler approach.

There were additional reasons that made the multiple rows approach more compelling. First, this approach made it much easier to handle exceptions to recurrences. Second, it was a requirement of the education solution to handle individualizing instances by adding attachments and changing titles. This proved relatively simple to add.

However, there are significant drawbacks to this approach that still need to be addressed. First, it is more difficult to handle items that recur indefinitely, and in fact this is not yet supported in the calendar package. Second (but related) is that additional safeguards need to be put in place to prevent pathological (accidental or intentional) cases from swamping the database.

User preferences

The data model was designed to support a wide range of user preferences. However, adding support for every one of these preferences would have taken time away from implementing other higher priority features. So there is currently no single user preferences form. Only a few of the most important user preferences (hiding/showing group items, compressing day view, and remembering last view) were implemented by adding links specifically to set those preferences.

Templates vs. Tcl

The calendar package is likely to be used by a number of clients. Many of these clients will need to customize it for their look and feel. While the public API functions for generating various pieces of the UI provides some support for this customization, it would have been even better if the calendar package used some form of templating.

Initially the package was implemented with the version of the templating system and form manager available at the time. However, first the form manager was dropped because it interfered with the fancy date/time widgets needed and because it couldn't handle the complex inserts and updates that were sometimes needed. Then, various views became so complex that they couldn't be done using templates. Often this was because we needed to display an ordered list of dates and times but efficient queries would produce results with gaps, and thus the multiple tag couldn't handle the complexity of the layout needed. Finally, the performance liabilities proved to be too great and all use of the templating system was dropped.

It appears that the new Dynamic Publishing System (DPS) may solve some of the problems with the old templating system. This will be investigated for future versions of the calendar package. Rather than attempting to redo the package completely using templating, it will probably be best to get a feel for the portions of the package that clients will most want to customize and then to use appropriate tools to make those portions more customizable.

Security and general permissions

The security model in the current package is fairly simple. It's clear that the package should move to using general permissions. However, when the initial implementation was being done, general permissions was relatively new and seemed like overkill for what was needed. There were also rumors of performance problems. I believe these issues have been addressed in ACS 4.0.

VI. Data Model Discussion

Items

The cal_items table is the heart of the calendar package. This table has columns for all the basic item information as well as columns for recurring items. The parent_id column is used to connect instances of recurring items to the parent item which contains default information. Initially, in a child item, only the start_date and possibly end_date columns are filled in. When the item appears on the calendar, all the other information is pulled from the parent item.

Mappings

There are a number of mappings made between calendar items and other tables in both the calendar data model and in the rest of the ACS. These mappings are:

Types

Types are equivalent to what were called categories in the old calendar data model. In essence, types are pre-defined labels which can be associated with arbitrary calendar items via the cal_item_types and cal_item_type_map tables.

Preferences

User preferences are stored primarily in the cal_user_prefs table. The columns that are used in the current version of the package are: default_view, compress_day_view_p, and update_type Several other columns are defined for future use. The cal_user_update_prefs table is used to store how items from a calendar for a group that a particular user is a member of, are to be displayed on the user's personal calendar.

Unusual columns

There are a few tables/columns whose use is not immediately obvious:

Extensions

There are a few extensions that allow the data model to tie into other systems.

Conversion of old data

There is a significant amount of data stored in the old calendar model and in the user_vacations table which needs to be displayed in the new calendar package. Thus, as part of the package there is a script, calendar-cvt-intranet.sql which converts this data into corresponding data in the new calendar data model.

VII. Legal Transactions

Integrity Constraints

Triggers

API transactions

User transactions

These transactions occur because of user actions on the calendar UI.

calendar/admin transactions

admin/calendar transactions

VIII. API

Public

These are the functions that are available for other packages and modules to use to manipulate calendar items.

Displays and Portals

These are the functions for displaying the various calendar views. They are used internally by the calendar package and also by the portals package.

Internal

These are the key functions used internally by the calendar package.

IX. User Interface

The user's UI

Views
The calendar package provides the same views that other calendar applications such as Yahoo and Excite do plus some additional features. Considerable effort has been put into optimizing the performance of the views because of the potentially large number of items that are being dealt with.

The day view handles overlapping items. In addition, it supports "compressing" the view so that only hours with items are shown. This is particularly useful when the view is inside a portal.

The list view provides a way of viewing items that the other calendar applications don't have. The upcoming and new items views are both useful for embedding in portals. The sortable columns for these views provide considerable flexibility.

Navigation
The mini calendar makes it easy to get to any particular view of any date quickly. Because the configuration changes based on the view, it's very flexible.
Items
Items appear slightly differently depending on the view. This allows a trade-off between the space available and the amount of information presented.

The form for setting the parameters of recurring events has gone through several revisions to improve usability. I believe the current form is significantly better than what either Yahoo or Excite provide. Color is used to distinguish the different types of intervals that can be set.

Group calendars
On the personal calendar, under the heading Your Calendars: there are links to the group calendars for the groups that the user is a member of. Next to these links are toggles to show or hide the group items for that group. Below the group calendars, Personal is listed.

Group calendars are distinguished from personal calendars in three minor ways but are otherwise identical:

  1. The page heading reads "ArsDigita Calendar for <group_name>" rather than "...for <user_name>".
  2. The link under Your Calendars: for the group calendar is turned off while Personal becomes a link to the personal calendar.
  3. The column for hiding/showing items is removed.
Types for Your Calendar
There is a separate subsystem for adding new types for your calendar. It provides a series of forms allowing the user to add new types, edit the names of existing types, and delete types.

The sub-site administrator's UI

Sub-admins have access to controls for administering calendars for the groups for which they are members.
Manage group calendars
Under this link are two subsections: "Your Groups' Calendars" and "Create Group Calendar". The first lists user groups you manage that have calendars. Links are provided to the admin page for the groups, to delete the group calendar, and to add types for the group.

The second lists those groups you manage which don't yet have calendars, with checkboxes to select those groups you want to create calendars for.

Types for <group_name>
This link goes to the same subsystem as described above, but sets types for this particular group.

The site-wide administrator's UI

Administrators have access to site-wide controls for manipulating group calendars.
Group Types With Calendars
This is a multiple select box. Selecting one or more types and clicking update will cause group calendars to be added for all groups of the selected types. This dialog needs to be made clearer on the exact behavior implemented. For example, deselecting a group type does not remove the calendars for all groups of this type but this is not obvious from the interface.
Groups With Calendars
This section lists all groups that have calendars, with a link to delete the corresponding calendar. It also provides a link to a page where multiple group calendars can be added at once. However, this secondary page is very cumbersome to use when there are many groups and should probably be redesigned.

X. Configuration/Parameters

FileAttachmentsFolder
Specifies the default name of the folder used to store calendar item attachments. If this parameter is not set, it defaults to "CalendarAttachments".

XI. Acceptance Tests

Acceptance Tests: acceptance.txt

The tests are split into two main sections. The first section tests the functioning of the standalone calendar. The second section tests those modules and other packages which have been integrated with the calendar.

XII. Future Improvements/Areas of Likely Change

There are a number of enhancements that should be made to the calendar package. Most of these have already been detailed in the competitive analysis section and I will just list those here. More detail will be given for those enhancements not already covered.

XIII. Authors

System owner: W. Scott Meeks

System creators:

Documentation author: W. Scott Meeks

smeeks@arsdigita.com
Advertisements