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.
@@ -135,13 +135,13 @@
-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.
