ArsDigita Community System Documentation

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

• /bboard revision
• templating, navigation, forms, and other enhancements
• general cleanup

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

cd /web/yourservername/tcl/ 
grep 'ad_register_filter' *.tcl

• service of all /*.html files follows the following sequence:
  1. 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
  2. ad_serve_html_page in /tcl/ad-html.tcl delivers the page, with included comments and related links
  3. 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
  4. 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

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).