design

Event Calendar是一个在线事件日程

INTRODUCTION
============
This event calendar system was designed with several objectives in mind.
We wanted people to be able to:

1. Browse events (obviously).
2. Search for specific events.
3. Submit their own events.
4. Change or possibly delete events.

Unfortunately, we don't trust the maturity of every single one of our
students, so we wanted events to be subject to some sort of approval, and
we wanted to know who was submitting offensive material (if any was
submitted).  We weren't up to creating an entirely new authentication
system, nor did we want to have yet another set of accounts to administer,
so we decided to check logins against user accounts on our web server.  We
still needed a separate way of storing various access levels and session
information, which we ended up doing in a postgres database, but it gave
us the ability to let certain people approve/modify/delete certain events
based on their location.  I suppose that's about as much detail as I can
put into an introduction, so I guess I'll get on with the following
sections:

	Backend - postgres
	Backend - sessions
	Backend - authentication
	Backend - permissions
	Backend - events
	Main Page Structure
	Boxes
	Box - Calendar
	Box - Search
	Box - Login
	Box - Submit
	Box - Approve
	Box - Modify
	Box - Delete
	Box - Help


BACKEND - POSTGRES
==================
Obviously we needed a place to store the events.  In spite of my prior
experience with LDAP (which might have made things like the SELECT
statements easier to manage), there's too much writing to the database to
make it a reasonable choice.  SQL was the next logical thing, and we
already had postgresql installed, so that's what we went with.

We created two databases in postgres, one of which was for the actual
calendar: events, locations, categories, audiences, etc; the other of
which was for authentication purposes.  While the actual accounts are
/etc/shadow based, we needed to keep track of who was logged in, when
they've last logged in, what permissions they have, etc.

One of the big disadvantages of not having accounts managed by postgres
was that we couldn't just connect to the database with whatever account
information the end-user provided.  We also didn't want guest accounts to
be able to write to the database.  To handle this, we created a couple
functions that would be kept in a separate file, readable only by the web
server, that would connect to the databases with the appropriate
information and return a connection index.  There are read-write and
read-only functions for both the calendar and authentication databases.
All connections to the database are done through these functions, so
changes in access to the database should be easy to accomodate.


BACKEND - SESSIONS
==================
We didn't want to be tossing accounts and passwords back and forth across
the internet, even over SSL, so we came up with a session class that keeps
track of a whole bunch of stuff and uses a simple session key that's set
as a cookie.  The session keeps track of the following stuff: user ID,
username, gecos (from /etc/passwd), expiration timestamp, remote address,
and permissions.  All of these are stuck together in one big string and
encrypted using MD5, with a salt formed by Unix crypting the same string.
This encrypted string is the session key.  The remote address is used to
protect from a replay-type attack.  There's a small chance of
inconsistency with this if people use a proxy though.  The expiration is
to help prevent problems with people logging in and leaving the terminal.
Browsers should delete the cookie when it expires, and whenever someone
logs in, the database is sent a delete statement to remove expired
sessions.  The session key uses MD5 because Unix crypt only looks at the
first 8 or so characters.  MD5 crypts the whole thing.  I just used Unix
crypt to get a nice random salt for MD5.  The permissions and random user
info probably isn't necessary, but is convenient to stick in the session.
Permissions are updated in the session when it is renewed.  Now back to
text with a followable string of thought.


BACKEND - AUTHENTICATION
========================
We decided to use the existing user accounts that we had in /etc/shadow
for this system, rather than setting up more accounts and having everybody
remember yet another password.  In order for PHP to get at the account
information, there are a few executables that it uses.  One is a
setuid-root thingy called getshcrypt which prints the crypted password
from /etc/shadow when given a user ID.  (It prints it so PHP can grab it.)
Two others, getpwinfo and getuidinfo, echo the line from /etc/passwd for
the given username or user ID respectively.  The verifyPassword function (in
auth-shadow.php3) uses these executables to verify the supplied username
and password, returning an error if the login failed.  This function keeps
track of things like multiple failed login attempts (using the LastLogin
class), and will fail a login unconditionally if there have been too many
recent failures.

Other authentication mechanisms have been supplied to me (a PAM module by
Bruce Tenison and an NIS module by Scott Moser).  These are relatively
easy to implement by creating some new file (auth-something.php3) which
defines a function verifyPassword and takes a username and password for
parameters.  This file can then be included by editting
calendar/includes/config.inc and changing $config_auth_module and the
related variables for the executables called by the module.

The actual session creation is done by the login box, which will be
explained later.  The login box calls verifyPassword and creates a new
session if the attempt is successful.

Aside from the table keeping track of sessions, there is another that
keeps track of last logins.  If there is a certain number of failures
within a given amount of time, then the account is temporarily locked.
The last login table keeps track of the last failed attempt, the last
successful attempt, the number of failures since last login, and the
number of recent failures.

BACKEND - PERMISSIONS
=====================
The permissions table has an easy to decipher layout.  The user_id column
contains the user's ID from /etc/passwd.  The location_id column contains
the ID for the location for which you are setting permissions.  The
permissions column contains a number which is formed by binary or-ing the
desired permissions, defined in permissions.php3.  The primary key for
this table is compound, based on location and user ID, so a user can have
different permissions for different locations.


BACKEND - EVENTS
================
In order to allow easy changes in the form of an event, there is a
separate event class.  The event itself is stored in the database across
several tables.  (It's a standard relational db thing).  The items that
are selected as a list are stored in the event table as an ID or list
of IDs that point to those items.  The event class contains variables for
every field of the event.  The fields that are IDs also have a matching
variable for the string representation of the value.

The base event class contains a constructor function that takes each of
the values as a parameter.  Most of the parameters are optional.  There
are also subclasses for different forms of initialization:  a subclass
that can be initialized from an array of values, one that can be created
when given the event ID from the database, one that will also fetch the
string representations from the database, one that will create an empty
event, and one that will get all of its values from global variables (such
as from a submitted form).

The event also handles any output, so if the event structure changes, the
other pages do not need to be updated.  There are a few different forms of
output:  detail view, which spits out a bunch of HTML; text-only view,
which overrides the rest of the pages so that only the event text is
output (not the rest of the calendar page); and an editable view, which
outputs form elements for all the fields.  Some event output is also done
in the rejectEvent function to include the event in an e-mail to the
submitter.

Several functions deal with the database operations on the event.  The
submitEvent function will build an SQL statement and insert all of the
necessary variables into the calendar database.  rejectEvent will delete
the event from the database and e-mail the submitter to let them know
their event was rejected.  deleteEvent, of course, deletes the event from
the database.  approveEvent approves the event by adding an approver ID.
updateEvent will save all variable to the database with an SQL UPDATE
statement.  For many of these operations, several SQL queries must be
constructed and sent to the server.  The event class makes use of SQL
transactions which may be rolled back if an error occurs to avoid
inconsistencies.

While modifying an event in any way, the event class is responsible for
updating the index table as well.  The event takes into consideration its
start and end times and the list of weekdays on which it occurs to produce
an array of timestamps for the days on which the event takes place.  This
array is then added to the index for easier browsing later on.

Before an event is submitted or updated, the validateEvent function should
be called to make sure all the required fields are included.  The
verifyAction function should also be called to make sure the current
session has the correct access to do whatever it is trying to do to the
event.


MAIN PAGE STRUCTURE
===================
The HTML structure of the calendar is actually pretty simple.  It consists
of a header and footer, included from the includes directory, which
contain whatever banners you want at the top and bottom of the page (at