Bboard Design Documentation
part of the ArsDigita Community System
by Philip Greenspun
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
- 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
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
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
for the comparison with traditional mailing lists and
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
column is used to determine to which forum from the
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
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
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
select msg_id, one_line, sort_key
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
(used as forum name) it contains lots of fields for generating the
customized user interface (Please refer to the
SQL data model file
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
is set to
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
We store information on when the bozo pattern was
), 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
store information necessary to
generate forum and thread alerts. All fields are rather self-explanatory.
is a one-row table that only stores
information about last alerts (just for fun).
Users can upload one file in association with any message. This was
developed to facilitate photo uploading. There is only one extra table
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
-- 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
-- will be null if the photo was small to begin with
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):
-- lock 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:
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 (...);
set all the common variables needed by
most scripts such as maintainer_email
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.
- 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
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
of the Requirements
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.
Here's a complete list of configuration parameters:
; SystemName=Yourdomain Network Discussion Forums (default)
; SystemOwner= something different (if desired) from SystemOwner above
; HostAdministrator=something different from system-wide
; IndexPageDecoration=<a href="/photo/pcd0796/downtown-munich-41.tcl"><img
HEIGHT=134 WIDTH=196 src="/photo/pcd0796/downtown-munich-41.1.jpg"
; 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
; do we use Oracle's Context option (only works if
; do we use standalone PLS search system
; do we use AltaVista (only works if ProvideLocalSearchP=0
; and if the site's content is exposed to AltaVista)
; anything below this threshold is considered uninteresting
; how many messages should a topic have to be considered active
; can a user start a new bboard
; link bboard permissions to AOLserver user; this is legacy
; code for ASME and probably doesn't work
; this path does *not* contain a trailing "/"
; Urgent messages
; Enables per-thread email alerts.
; Enables display of "stop per-thread alert" right on the
; fetch-one-message page.
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
- 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.