General Comments

part of the ArsDigita Community System by Tracy Adams

User-accessible directory: /general-comments/
Site administrator directory: /admin/general-comments/
data model: subsection within /doc/sql/general-comments.sql
TCL: /tcl/general-comments

The Big Idea

We can solicit comments (or reports) on any piece of information in the database.

Under the Hood

General comments are stored in one table. Comments refer to items with an id on_what_id in the table on_which_table.

create table general_comments (
	comment_id		integer primary key,
	on_what_id		integer not null,
	on_which_table		varchar(50),
	one_line_item_desc	varchar(200) not null,
	user_id			not null references users,
	comment_date		date not null,
	ip_address		varchar(50) not null,
	modified_date		date not null,
	content			clob,
	-- is the content in HTML or plain text (the default)
	html_p			char(1) default 'f' check(html_p in ('t','f')),
	approved_p		char(1) default 't' check(approved_p in ('t','f'))
	-- columns useful for attachments, column names
	-- lifted from file-storage.sql and bboard.sql
	-- this is where the actual content is stored
	attachment		blob,
	-- file name including extension but not path
	client_file_name	varchar(500),
	file_type		varchar(100),	-- this is a MIME type (e.g., image/jpeg)
	file_extension		varchar(50), 	-- e.g., "jpg"
	-- fields that only make sense if this is an image
	caption			varchar(4000),
	original_width		integer,
	original_height		integer
);

The module contains one core procedure, ad_general_comments_list, that will show comments on an item and make appropriate links to files in /general-comments for recording and editing user comments.

The arguments to ad_general_comments_list are:

db handle
table_name containing item
id of the item
A pretty noun describing the item for the user interface.
The module name
The submodule name
A return_url (optional, the default will be the current URL)

Administration

To support central administration of comments, we rely on a helper table defined in community-core.sql:


create table table_acs_properties (
             table_name      varchar(30) primary key,
             section_name    varchar(100) not null,
             user_url_stub   varchar(200) not null,
             admin_url_stub  varchar(200) not null
);

As with site-wide search and the user profiling system, this helper table enables us to make a single query and yet link comments over to the appropriate admin or user pages. Another part of this system is the one-line item description column in the general_comments table.

The Steps

Consider applying this package to a legacy ACS module such as the classified ad system (/gc/) to allow comments on each classified ad. Here are the steps:

If necessary, decide on the site-wide comment approval policy:

The DefaultCommentApprovalPolicy parameter in your /parameters/service_name.ini file is the default approval policy for the site.

[ns/server/yourservicename/acs]
...
; open means stuff goes live immediately
; wait means stuff waits for administrator to approve
; closed means only administrator can post
DefaultCommentApprovalPolicy=wait
...

Decide on module specific parameters:

If you would like the publisher to control the use of comments in your module, add SolicitCommentsP to your module parameters.

If you would like to use a comment approval policy other than the site's default, add CommentApprovalPolicy to your module parameters.

[ns/server/yourservicename/acs/gc]
; If SolicitCommentsP is missing for the module, the default is 1
SolicitCommentsP=1
; If CommentApprovalPolicy is missing for the module, the
; default is the DefaulCommentApprovalPolicy in [ns/server/yourservicename/acs]
; open means stuff goes live immediately
; wait means stuff waits for administrator to approve
; closed means only administrator can post
CommentApprovalPolicy=open

Identify the file and location to display and solicit comments and insert a call to ad_general_comments_list.
```
ad_general_comments_list $classified_ad_id classified_ads $one_line gc
```
Note that ad_general_comments_list checks in the module's parameters to see if comments are being solicited or not.
If necessary, insert a row into table_acs_properties so that the admin pages will be up to date
Remember to delete any attached comments from the general_comments table when you delete any rows from your subsystem's table or write database triggers to do the deletions automatically.

Attachments

Users can attach arbitrary files to a comment, if the publisher has configured the general comments system to accept attachments:


[ns/server/photonet-dev/acs/general-comments]
; Whether or not we accept file uploads for general comments.
AcceptAttachmentsP=1
; Maximum attachment size in bytes. Leave empty for no limitation.
MaxAttachmentSize=5000000
AdminEditingOptionsInlineP=0
; Images with widths less than this parameter will be displayed inline.
InlineImageMaxWidth=512

Smaller photos are displayed in-line. Larger photos are displayed as links. Files that aren't identified as photos by the system are simply made available for one-click download (with a MIME type based on the extension of the file originally uploaded).

teadams@mit.edu