Index: openacs-4/packages/general-comments/www/doc/design.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/general-comments/www/doc/design.adp,v diff -u -N -r1.1.2.5 -r1.1.2.6 --- openacs-4/packages/general-comments/www/doc/design.adp 5 Jul 2016 16:52:02 -0000 1.1.2.5 +++ openacs-4/packages/general-comments/www/doc/design.adp 18 Jul 2016 11:45:37 -0000 1.1.2.6 @@ -62,16 +62,16 @@
Tcl API
There is one core procedure, general_comments_get_comments, that will show comments on an object and make appropriate links to files from the -general-comments package for -recording and editing user comments. An optional return_url can be specified which will be -provided as a link to the user within the general-comments pages. This is useful for +general-comments package for +recording and editing user comments. An optional return_url can be specified which will be +provided as a link to the user within the general-comments pages. This is useful for the user to return to the original page after making a comment.
The other procedure, general_comments_create_link, is a wrapper procedure that returns an html fragment for a link which points to the -location of the mounted general_comments package. There are various +location of the mounted general_comments package. There are various switches that will be useful to package developers:
object_name: A name for the object -being commented on is displayed throughout the general-comments pages. Defaults to +being commented on is displayed throughout the general-comments pages. Defaults to [acs_object_name].
link_text: The text of the link returned. Defaults to "Add a comment".
@@ -82,14 +82,14 @@ complete. The purpose is to allow separation of comments on the same object into categories.
A problem that may occur is when any of the two tcl procedures -are called when the general-comments package is not mounted. Both -general_comments_get_comments and -general_comments_create_link needs -to find out the location of the mounted general-comments instance to generate correct +are called when the general-comments package is not mounted. Both +general_comments_get_comments and +general_comments_create_link needs +to find out the location of the mounted general-comments instance to generate correct links. In this case, both procedures will return nothing and log a notice.
Note: In the alpha release of -general-comments, the tcl +general-comments, the tcl procedures were defined within a namespace and encountered problems with the api browser not being able to display them properly. These procedures have now been moved out of the namespace and the old @@ -98,31 +98,31 @@
The majority of the functionality of general comments has been -merged with acs-messaging. Comments are stored as acs-messages.
The general_comments table -extends acs_messages to provide -categorization of comments on a particular object. general_comments also stores the object_id of +merged with acs-messaging. Comments are stored as acs-messages.
The general_comments table +extends acs_messages to provide +categorization of comments on a particular object. general_comments also stores the object_id of the object the comment refers to. Relationships from attachments to -acs-message is done by using the cr_items.parent_id column.
A general-comment can be -associated with any object in the system by using the general_comments.object_id column. Because +acs-message is done by using the cr_items.parent_id column.
A general-comment can be +associated with any object in the system by using the general_comments.object_id column. Because each comment is itself an object, we could implement comments on comments. However, this functionality is not needed in the -general-comments model and the UI +general-comments model and the UI does not support comments on comments.
There are three types of attachments a user can create: file, image, and url. The underlying data representation of an attachment is a content item with different content_types. File attachments are stored with a content_revision type. Image attachments are stored with a image type. Url attachments are stored with a content_extlink type.
One problem we face is how to allow designers to modify the presentation of the comments on an object without modifying tcl -code. The proc general_comments_get_comments has html code +code. The proc general_comments_get_comments has html code which should really be placed into a template. Karl Goldstein code reviewed general comments and has an interesting solution:
Add an -uplevel parameter to -db_multirow.
In the general_comments_get_comments proc, create an -upleveled datasource.
From the .tcl page, make a call -to general_comments_get_comments, +
Add an -uplevel parameter to +db_multirow.
In the general_comments_get_comments proc, create an +upleveled datasource.
From the .tcl page, make a call +to general_comments_get_comments, which would set up the multirow datasource in the current -environment.
From the .adp page, loop through +environment.
From the .adp page, loop through the multirow datasource.
-AutoApproveCommentsP: Sets +AutoApproveCommentsP: Sets whether comments go live immediately.
-AllowFileAttachmentsP: Sets +AllowFileAttachmentsP: Sets whether files can be attached to comments.
-AllowLinkAttachmentsP: Sets +AllowLinkAttachmentsP: Sets whether links can be attached to comments.
-MaxFileSize: Maximum file size +MaxFileSize: Maximum file size that can be uploaded in bytes.