ArsDigita Community System Documentation
by Philip Greenspun
Caveat emptor: This is documentation distributed from around 2001; links and information contained within may be stale.
Documentation
- /doc/index.html -- this document
- /doc/arsdigita-faq.html -- ArsDigita Community System FAQ
- /doc/installation.html
- /doc/upgrading.html -- moving from one
ACS version to the next
- /doc/developers.html -- including procedure-by-procedure documentation (for programmers)
- /doc/style.html -- templates and
multi-lingual support
- /doc/monitoring.html
- /doc/mainframe-integration.html
- working with XML
- /doc/help.html -- building documentation for
the end-user
- /doc/security-sessions.html --
information on the security subsystem, and associating state with user
sessions and browsers
- /doc/abstract-url.html --
information on the system allowing use of abstract (extensionless) URLs
- /doc/webmasters.html -- for the person
who makes publishing decisions
- /doc/patches.html -- documentation of
patches/fixes to the ArsDigita Community System (ACS) on this site;
useful when you are upgrading and when we are building a new version
of the system
- /doc/custom.html -- documentation of
custom features that you've added to this site that will/can never
be rolled into the ACS.
- Development Standards
- Version History
- AOLserver documentation, a
notably useful part of which is the Tcl Developer's Guide
Individual Modules
Each module is owned by at least one programmer. The current list
is in module-owners.html; each
programmer
is responsible for maintaining the module and
the relevant portion of acceptance-test.html
- /doc/address-book.html
- /doc/bannerideas.html
- /doc/bboard.html -- the discussion forum
system
- /doc/bookmarks.html
- /doc/calendar.html
- /doc/chat.html - Chat was removed from this installation
- /doc/classifieds.html
- /doc/clickthrough.html
- /doc/contact-manager.html -- good
for sites with an extranet-y flavor
- /doc/content-sections.html -- lets
administrators add/manage different content sections of the site
- /doc/custom-sections.html -- allows
group administrators add/manage custom sections of the site
- /doc/curriculum.html
- /doc/directory.html -- letting users
find each other
- /doc/download.html -- offering versions
of software or other stuff to people
- /doc/dw.html -- a toolkit for data
warehouse-style queries
- /doc/events.html -- facilitates online
registration for events
- /doc/faq.html
- /doc/file-storage.html -- users who
don't know HTML can collaboratively maintain a set of files on the server
- /doc/glassroom.html -- the ArsDigita
Glass Room system, for coordinating people involved in keeping a Web
service up and running
- /doc/glossary.html -- the ArsDigita
Glossary, for creating an on-site dictionary of specialized terminology.
- /doc/neighbor.html -- Neighbor to
Neighbor (hard to explain; see example at http://photo.net/neighbor/)
- /doc/news.html
- /doc/partner.html -- site-wide cobranding
- /doc/poll.html -- opinion polls
- /doc/pull-down-menus.html -- create Macintosh style menu bars
- /doc/spam.html -- send email to a group of users
- /doc/static.html -- support for collecting
comments, links, and download statistics for static .html files
- /doc/survey-simple.html -- ask the
users a series of questions
- /doc/ticket.html -- a project
and bug tracking system
- /doc/wp.html -- WimpyPoint, a replacement for desktop
bloatware like PowerPoint, allowing you to create and view presentations
in your Web browsers
- User session tracking --
getting a meaningful handle on usage
- User registration and access control
- User administration -- how the
publisher can select a class of users and what can then be done with
that class
- Customer relationship management -- tracking a customer relationship through its various states.
- User groups -- a general mechanism
for lumping users together in groups, e.g., all students in a particular
course
- Member value -- a way of
accumulating charges for users and then billing them out at the end of
each month (commercial sites) or excluding them from the community if
the charges get too high (non-commercial)
- Redirects -- ensuring that legacy URLs
pointed to by bookmarks and search engines still work
- Robot detection -- making sure
that your entire site gets indexed
Two Related Modules
- User profiling and content categorization -- matching users
to content
- Site-wide-search -- a
system for indexing all of a site's content from one big table
Module Tools
- Audit -- adding a change history to a table
- Calendar widget -- displaying
calendars
- Content tagging -- useful for
finding/screening naughty words but with wider potential as well
- Email handler -- queues incoming
email into an Oracle table; let's you do things like unified customer
support or email replies to tickets
- Graphing -- generating bar charts
- New stuff -- showing folks what is new site-wide
- Permissions -- a standardized way of
answering: "Is user x allowed to do y?"
- General permissions -- a
way to answer the question "can a particular user, group, or role do
this on a particular row?", where this can be an arbitrary action
(e.g., read, comment, write, administer, etc.)
- General comments -- allows you to collect user comments on any item
- General links -- allows you to collect user links on any item
- Prototype builder -- quickly build standard ACS pages via a user interface
- Tools -- collections of scripts providing services to perform common tasks such as spell checking.
- Server Clusters -- a facility for keeping
state synchronized between a group of load-balance servers.
The Glorious Future
Here we link to plans that are in the works; it is a collaboration area
for toolkit programmers to look at.
Directories
Not Under the Page Root
- /web/yourdomain/parameters/ -- stores definitions such as the
service name
- /web/yourdomain/tcl/ -- Tcl procedures used system-wide
Under the Page Root
- /doc/ -- this directory
- /doc/sql/ -- data model files
- /install/ -- files needed for installation only
- /global/ -- files served up by AOLserver when it gets unhappy (e.g.
file not found or too many threads), also for privacy statements, etc.
- /graphics/ -- for site-wide logos and other images that aren't
specific to content sections
- /pvt/ -- material private to a particular member
- /shared/ -- material available to members but not private to a particular member
- /incoming/ -- material that authorized users need to FTP up to
you
- /acs-examples/ -- scripts that show programmers how to use
various ACS features
Subsystems
Each module generally defines a top-level subdirectory with the same
name as itself; there are some exceptions with weird names below.
- /comments/ -- comments on static pages
- /gc/ -- generic classified ad system
- /links/ -- Tcl scripts that show related links on the bottom of a page
- /ug/ -- viewing and creating user groups
Magic Files
- /global/copyright.adp explains the site's copyright policy
- /global/server-busy.html is served by AOLserver when the threads are
stacked up (presumably because the RDBMS is overwhelmed)
- /global/file-not-found.html is served by AOLserver when the user
hits a non-existent URL; presumably this will contain some search tips
- /global/unauthorized.html is served by AOLserver when the user hasn't
typed in a valid HTTP username/password (this shouldn't really ever be
part of the user experience since the ArsDigita Community System doesn't
use HTTP usernames/passwords)
- /global/forbidden.html is served by AOLserver when the nsperm system
isn't happy and refuses to say why (not sure why this should ever happen)
- /global/error.html is served by AOLserver when it chokes on a Tcl
API program or CGI script
- /global/privacy.adp is the site's privacy statement.
- /global/legal.adp is the site's legal statement.
Filters and Other Tricks
To be sure that you're getting them all on a particular server, do:
cd /web/yourservername/tcl/
grep 'ad_register_filter' *.tcl
- service of all /*.html files follows the following sequence:
- the ad_verify_identity filter from /tcl/ad-security.tcl may run to
abort service of the page, depending on which directories are specified
for protection in /tcl/ad-security.tcl
- ad_serve_html_page in /tcl/ad-html.tcl delivers the page, with
included comments and related links
- ad_maintain_user_content_map from /tcl/ad-user-content-map.tcl runs
after the page has been served, to insert rows into the
user_content_map
table
- ad_pics_filter from /tcl/ad-pics.tcl will add a PICS header saying
"I'm a naughty page" (or whatever else you've put in the ad.ini file) to
the directories and files specified in ad.ini
- /tcl/ad-admin.tcl defines filters to restrict /admin pages to SSL
(when available) and to registered users in the site-wide administration
group
- /tcl/ad-last-visit.tcl defines a filter to maintain the last visit
cookie and database rows
- /tcl/ad-referer.tcl defines a filter to update referral counters in
the database
- /tcl/ad-robot-defs.tcl may define a filter to look for robots
visiting particular directories
- /tcl/ad-user-content-map.tcl defines a trace filter to enter rows
into the
user_content_map
- /tcl/curriculum.tcl defines a filter to maintain the curriculum
cookie
Database Pools
The community system depends on the existence of three database
pools: main, subquery, and log. They must be named as such. The
default pool will be "main".
Substrate
If you want to have a reliable service, you should read and apply
this installation guide for the
ArsDigita Server
Architecture (don't confuse this with the ACS intallation guide
in /doc/installation.html).
Copyright and Legal Status of this Software
This software is mostly Copyright 1995-99 Philip Greenspun and
licensed under the GNU General Public License,
version 2 (June 1991).
philg@mit.edu