ArsDigita Archives
 
 
   
 
spacer

Bboard Design Documentation

part of the ArsDigita Community System by Philip Greenspun

I. Essentials

II. Introduction

The Bboard module enables community members to communicate by posting questions and answers online. Using the Bboard module users can:
  • Post questions or other messages so that other users can read them
  • Browse and search for content posted in the past
  • Answer questions or comment on messages posted by others
  • Be alerted via email when relevant content is posted by other users
  • Post images and other files to illustrate their message
Administrators can:
  • Edit and delete stupid or irrelevant content
  • Define bozo patterns to prevent posting stupid or irrelevant content
  • Customize working of each discussion forum for particular needs
  • Identify expert users (possibly in order to offer them to become moderators)
This system is not intended to be used as:
  • A repository of structured information: every message is an unstructured chunk of text
  • A repository of files: there is no posibility for users to delete, edit or move their postings
  • A replacement for Web-based email
This system is mostly used for collaborative discussions on both corporate intranets as well as public community websites.

Some of the goals accomplished by this system could also be accomplished with traditional mailing lists and newsgroups. See the Requirements Document for the comparison.

III. Historical Considerations

Threaded or Flat structure?

Most traditional discussion systems are threaded. Joe asks a question, Nick gives an answer, Bill complains about Nick's answer, Ron complains about Bills complaint... The software shows all that as a deep hierarchy.

Although Bboard data model has the full support for threaded discussion and there is also a user interface that uses threading, the flat (Q&A) format has proven to be better in practice. Some of the advantages of the Q&A format:

  • Users are inclined to follow the original subject rather than diverge in completely disparate directions.
  • When the threaded interface is used, it is quite often that forking is quite arbitrary, i.e. that a user comments about a posting in the wrong subthread. That creates confusion.
  • Simple chronological sequences are much easier to follow and understand than hierarchies.
For these and other reasons the development of the user interface was more concentrated in the direction of the simple Q&A format.

IV. Competitive Analysis

Please see the Requirements Document for the comparison with traditional mailing lists and newsgroups.

V. Design Tradeoffs

VI. Data Model Discussion

For the complete data model please refer to the SQL file.

The bboard and helper tables

This table contains all the postings in all the forums. The topic_id column is used to determine to which forum from the table bboard_topics the posting belongs. The refers_to column is used to identify the "parent" message.

For the unique identifier msg_id we are using 6-character strings. The next ID after "00001m" is "00001n". Each character cycles through the integers, then the capital letters, then the lowercase letters. So after "00001z" the next message is "000020", 9 messages later, "000029", then "00002A", and "00002Z" will be followed by "00002a".

The msg_id_generator table is a one-row, one-column table that always contains the last used msg_id. The Tcl procedure increment_six_char_digits defined in tcl/bboard-defs.tcl is used to increment the identifier. Locking is used to make sure that generation of new msg_id is properly serialized.

The sort_key column of the bboard table is used for quick calculation of the whole thread. Here's how it is constructed and used: The sort key for a top level message is just the msg_id, say "00001n". For messages that respond to the top level, the sort keys are "00001n.00", "00001n.01", . . . , "00001n.09", "00001n.0A", . . . , "00001n.0Z", "00001n.0a", . . . , ""00001n.0z", "00001n.10", . . . There are 62 possibilities for each character and two characters per thread level. So any one message can have 3844 immediate responses. A response to a response will have a sort key with two extra characters, for example, "00001n.0900" would be the first response to the ninth response to top-level message 00001n.

This sort key enables us to get the messages out in thread-sorted order with 

   select msg_id, one_line, sort_key
     from bboard
    where topic_id = 234
 order by sort_key

and the level of a message can be calculated simply as a function of the length of the sort key.

The bboard_topics table

This table contains information about whole forums. In addition to usual fields such as integer primary key topic_id and topic (used as forum name) it contains lots of fields for generating the customized user interface (Please refer to the Requirements Document and the SQL data model file for details.) Bboard_topics also contains fields: 
read_access  varchar(16) default 'any' check (read_access in ('any','public','group')),
write_access varchar(16) default 'public' check (write_access in ('public','group')),
group_id     integer references user_groups,
which are used for permissions checking. The group_id column has significance only if at least one of the fields read_access, write_access is set to group.

The board_q_and_a_categories table

The categorization system built into the bboard module is very simple: 
create table bboard_q_and_a_categories (
        topic_id        not null references bboard_topics,
        category        varchar(200) not null
);
So for each forum (topic_id) a single flat list of categories can be defined.

The bboard_bozo_patterns table

This table contains regexp patterns (the_regexp) to prevent usage of unwanted words or phrases. Each forum has its own list of patterns. It is possible to specify whether the one line description, the body or both should be tried against the patterns to determine whether to reject the message: 
scope varchar(20) default 'both'
      check(scope in ('one_line','message','both')),
When a posting matches the forbidden pattern the user is presented with an explanation message_to_the_user why his message has been rejected. We store information on when the bozo pattern was created (creation_date), who created the pattern (creation_user not null references users(user_id)). It is also possible to enter a comment (creation_comment varchar(4000)) describing the purpose of each pattern.

Email alerts tables

Tables bboard_email_alerts and bboard_thread_email_alerts store information necessary to generate forum and thread alerts. All fields are rather self-explanatory. Bboard_email_alerts_updates is a one-row table that only stores information about last alerts (just for fun).

File upload

Users can upload one file in association with any message. This was developed to facilitate photo uploading. There is only one extra table defined for 

create sequence bboard_upload_id_sequence;

create table bboard_uploaded_files (
	bboard_upload_id	integer primary key,
	msg_id			not null references bboard,
	file_type		varchar(100),	-- e.g., "photo"
	file_extension		varchar(50), 	-- e.g., "jpg"
	-- can be useful when deciding whether to present all of something
	n_bytes			integer,
	-- generally the filename will be "*msg_id*-*upload_id*.extension"
	-- where the extension was the originally provided (so 
	-- that ns_guesstype will work)
	filename_stub		varchar(200) not null,
	-- fields that only make sense if this is an image
	caption			varchar(4000),
	-- will be null if the photo was small to begin with
	thumbnail_stub		varchar(200),
	original_width		integer,
	original_height		integer
);

VII. Legal Transactions

There is only one important user transaction: posting a message. Here's how the transaction looks like (with details ommited for clarity): 

begin transaction;

     -- lock msg_id_generator:
     select last_msg_id
     from msg_id_generator
     for update of last_msg_id;
     
     -- generate new_id (with the Tcl proc increment_six_char_digits)
     -- and update msg_id_generator:
     update msg_id_generator
     set last_msg_id = :new_id;
     
     -- insert the new message:
     insert into bboard (...);
     
     -- if user can define categories insert it now:
     insert into bboard_q_and_a_categories (...);
     
     -- set default thread alert:
     insert into bboard_thread_email_alerts (...);
     
     -- take care of the uploaded files:
     
     insert into bboard_uploaded_files (...);

end transaction;

VIII. API

bboard_get_topic_info

Given topic_id set all the common variables needed by most scripts such as maintainer_email and maintainer_name.

This procedure doesn't require any explicit arguments to be set but it depends on topic_id to be set in the caller's environment.

Permissions functions

  • bboard_user_is_admin_for_topic is used to find out whether the current user is an administrator for the current topic.
  • bboard_user_can_view_topic_p is used to find out whether the current user has permission to view the current topoic.

Interfaces to ad-new-stuff.tcl and ad-user-contributions-summary.tcl

Procedures bboard_new_stuff and bboard_user_contributions are called from the New Stuff and User Contributions subsystems to make bboard postings available on the What's New page as well as the User Contributions page.

Interface to the Site-wide Search System

The interface to the search system is pretty well described in the comments of /arsdigita/doc/sql/site-wide-search.sql. The important thing to notice is that whole threads, rather than single messages are being indexed.

IX. User Interface

The Site-wide Administrator Interface

Site-wide Administrators can create, activate and deactivate whole forums.

The Forum Administrator Interface

Forum Administrators can edit and delete postings and whole threads. They can also edit all the forum parameters described in the section VI.A-20 of the Requirements Document.

The Interface for Ordinary Users

Users can browse, search for and read messages. They can also post new messages and upload files to attach them to messages. Users can choose whether their posting should be considered HTML or plain text.

X. Configuration/Parameters

Here's a complete list of configuration parameters: 
[ns/server/yourservername/acs/bboard]
PartialUrlStub=/bboard/
; SystemName=Yourdomain Network Discussion Forums (default)
; SystemOwner= something different (if desired) from SystemOwner above
; HostAdministrator=something different from system-wide
SenderEmail=bboard-robot@yourdomain.com
; IndexPageDecoration=<a href="/photo/pcd0796/downtown-munich-41.tcl"><img
   HEIGHT=134 WIDTH=196 src="/photo/pcd0796/downtown-munich-41.1.jpg"
   ALT="Downtown Munich."></a>
; ActivePageDecoration=<a href="http://photo.net/photo/pcd3609/girls-17.tcl"><img
   HEIGHT=134 WIDTH=196 src="http://photo.net/photo/pcd3609/girls-17.1.jpg"></a>
; do we offer users a full-text search box
ProvideLocalSearchP=1
; do we use Oracle's Context option (only works if 
; ProvideLocalSearchP=1)
UseContext=0
; do we use standalone PLS search system
UsePLS=0
; do we use AltaVista (only works if ProvideLocalSearchP=0
; and if the site's content is exposed to AltaVista)
LinktoAltaVista=0
; anything below this threshold is considered uninteresting
InterestLevelThreshold=4
; how many messages should a topic have to be considered active
ActiveLevelThreshold=30
; can a user start a new bboard
UserCanAddTopicsP=0
; link bboard permissions to AOLserver user; this is legacy 
; code for ASME and probably doesn't work
UseNsPermAuthorizationP=0
FileUploadingEnabledP=1
; this path does *not* contain a trailing "/"
FilePath=/web/yourservername/data/bboard
; Urgent messages
UrgentMessageEnabledP=0
DaysConsideredUrgent=14
; Enables per-thread email alerts.
EnableThreadEmailAlerts=1
; Enables display of "stop per-thread alert" right on the 
; fetch-one-message page.
OfferStopNotificationLinkForThreadEmailAlertsP=0

XI. Acceptance Tests

What follows is just a sample test to early find out if something is horribly wrong with the installation. For more comprehensive test please refer to the Installation guide.
  • Visit /admin/bboard and click on Add New Topic
  • Fill in the form and click on "Enter This New Topic in the Database"
  • Once the topic (forum) is created you'll be offered a link to visit the admin page. Follow that link.
  • Click on the link to user-visible page in Q&A format offered on the top of the admin page
  • Once on the user-visible page select Post a Message and follow instructions in the series of forms that follow. Make sure that when the message is entered in the databse the forum administrator gets email (if the forum is set up like that).
  • Go to the admin interface and delete the posting

XII. Future Improvements/Areas of Likely Change

The bboard module is one of the oldest and most often hacked module in ACS. This document describes the version of Bboard that comes with ACS 3.x. For ACS 4.0 the module will be completely rewritten to make full use of ACS 4 core services, templating and new APIs.

XIII. Authors

jfinkler@arsdigita.com
audrey@arsdigita.com
spacer