$title
\n" + if { $mime_type == "text/plain" } { + append html "[util_convert_plaintext_to_html $content]\n" + } else { + append html "$content\n" + } + if { $print_attachments_p == 1 } { + set attachments_html "" + db_foreach get_attachments " + select r.title, r.mime_type, i.name, i.item_id + from cr_items i, cr_revisions r + where i.parent_id = :comment_id + and r.revision_id = i.live_revision" { + + append attachments_html "[_ general-comments.Attachments]
\n- \n$attachments_html
" + } + } + append html "
-- $author [_ general-comments.on] $pretty_date2 ([_ general-comments.view_details])
\n" + } else { + append html "\n" + } + + return $html +} + + +ad_proc -public general_comments_create_link { + -object_name + { -link_text {Add a comment} } + -context_id + { -category {} } + object_id + {return_url {}} +} { + Generates an html link to add a comment to an object. + + @param object_id The object to comment on. + @param return_url A url for the user to return to after viewing a comment. + @param object_name The name of the object. + @param link_text The text to display for the link. + @param context_id The context_id for the comment. + @param category A category to associate comment to. +} { + # get the package url + set package_url [general_comments_package_url] + if { [empty_string_p $package_url] } { + return "" + } + + # initialize variables + if { ![info exists object_name] } { set object_name [acs_object_name $object_id] } + if { ![info exists context_id] } { set context_id $object_id } + + set html "$link_text" + + return $html +} + +ad_proc -private general_comments_package_url {} { + Returns a url pointing to the mounted general-comments package. + Uses util_memoize for caching. +} { + return [util_memoize [list general_comments_package_url_not_cached]] +} + +ad_proc -private general_comments_package_url_not_cached {} { + Returns a url pointing to the mounted general-comments package. + Goes to the database on every invocation. +} { + + if { [db_0or1row get_package_url "" ] } { + return $package_url + } else { + # log an error message + ns_log "Notice" "The General Comments package is not mounted." + return "" + } +} + +# these are being replaced with the above procs +namespace eval general_comments { + +ad_proc -deprecated get_comments {object_id return_url} { + Generates a line item list of comments for the object_id. + + @param object_id The object_id to retrieve the comments for. + @param return_url A url for the user to return to after viewing a comment. + + @see general_comments_get_comments +} { + + # get the package url + set package_url [db_string get_package_url_deprecated " + select site_node.url(s.node_id) + from site_nodes s, apm_packages a + where s.object_id = a.package_id and + a.package_key = 'general-comments'"] + + set html "" + db_foreach get_comments_deprecated " + select g.comment_id, + r.title, + r.content, + r.mime_type, + o.creation_user, + to_char(o.creation_date, 'MM-DD-YYYY') as creation_date, + p.first_names || ' ' || p.last_name as author + from general_comments g, + cr_items i, + cr_revisions r, + acs_objects o, + persons p + where g.object_id = :object_id and + i.item_id = g.comment_id and + r.revision_id = i.live_revision and + o.object_id = g.comment_id and + p.person_id = o.creation_user + order by creation_date" { + append html "
\n" + } + return "$html" +} + +ad_proc -deprecated create_link {object_id object_name return_url link_text {context_id ""} {category ""}} { + Generates an html link to add a comment to an object. + @param object_id The object to comment on. + @param object_name The name of the object. + @param return_url A url for the user to return to after viewing a comment. + @param link_text The text to display for the link. + @param category A category to associate comment to. + + @see general_comments_create_link +} { + # get the package url + set package_url [db_string get_package_url_deprecated " + select site_node.url(s.node_id) + from site_nodes s, apm_packages a + where s.object_id = a.package_id and + a.package_key = 'general-comments'"] + + set html "$link_text" + return $html +} + +} Index: openacs-4/contrib/packages/general-comments/tcl/general-comments-procs.xql =================================================================== RCS file: /usr/local/cvsroot/openacs-4/contrib/packages/general-comments/tcl/Attic/general-comments-procs.xql,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/contrib/packages/general-comments/tcl/general-comments-procs.xql 2 May 2003 15:49:59 -0000 1.1 @@ -0,0 +1,33 @@ + +
++ +@title@
+@html_content@ +
++
+
+
| + + | + ++ + | +
+@dimensional_bar@ +
+@comments_table@ + + + + + Index: openacs-4/contrib/packages/general-comments/www/index.tcl =================================================================== RCS file: /usr/local/cvsroot/openacs-4/contrib/packages/general-comments/www/Attic/index.tcl,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/contrib/packages/general-comments/www/index.tcl 2 May 2003 15:50:44 -0000 1.1 @@ -0,0 +1,91 @@ +# /packages/general-comments/www/index.tcl + +ad_page_contract { + General comments main page + + @author Phong Nguyen (phong@arsdigita.com) + @author Pascal Scheffers (pascal@scheffers.net) + @creation-date 2000-10-12 + @cvs-id $Id: index.tcl,v 1.1 2003/05/02 15:50:44 daveb Exp $ +} { + {orderby {pretty_date*} } +} -properties { + page_title:onevalue + context:onevalue + dimensional_bar:onevalue + comments_table:onevalue +} + +# authenticate the user +set user_id [ad_maybe_redirect_for_registration] + +# check for admin privileges +set package_id [ad_conn package_id] +set admin_p [ad_permission_p $package_id admin] + +# return_url to be passed to various helper pages so that we return to +# this page with the proper parameters +set return_url [ns_urlencode index?[export_ns_set_vars url]] + + +set dimensional [list \ + [list approval "[_ general-comments.Status]" any [list \ + [list approved "[_ general-comments.approved]" {where "[db_map status_approved]"}] \ + [list unapproved "[_ general-comments.unapproved]" {where "[db_map status_unapproved]"}] \ + [list any "[_ general-comments.all]" {} ] \ + ]] \ + [list modified "[_ general-comments.Last_Modified]" 1m [list \ + [list 1d "[_ general-comments.last_24_hours]" {where "[db_map modified_last_24hours]"}] \ + [list 1w "[_ general-comments.last_week]" {where "[db_map modified_last_week]"}] \ + [list 1m "[_ general-comments.last_month]" {where "[db_map modified_last_month]"}] \ + [list any "[_ general-comments.all]" {} ] \ +]] +] +set dimensional_bar [ad_dimensional $dimensional] + +# ad_table definition +set table_def [list \ + [list num "[_ general-comments.Num]" {} {
+
| #general-comments.lt_Current_values_for_Ge# | |
| package_id | +
+ |
| package_url | +
+ |
| AutoApproveCommentsP | +
+ |
| AllowFileAttachmentsP | +
+ |
| AllowLinkAttachmentsP | +
+ |
| MaxFileSize | +
+ |
+
#general-comments.Comments#
+-
+
- #general-comments.none# +
+
#general-comments.Full_Comments#
++++ +#general-comments.none# + + @full_comments@ + +
+ @link@ +
#general-comments.If# general-comments #general-comments.lt_is_not_mounted_and___# general_comments_get_comments
+ #general-comments.or# general_comments_create_link#general-comments.lt__then_an_error___will# general-comments
+ #general-comments.package_instance#
+
+
++ + + +@title@
+ +@html_content@ + +
++ -- #general-comments.you# + + #general-comments.edit_your_comment# +
++ -- @author@ + + +
#general-comments.Attachments#
+-
+ <% set counter 0 %>
+
-
+
+ ( #general-comments.edit# | +#general-comments.delete# ) + ++ @attachments.title@ + (@attachments.name@) + ++ @attachments.title@ + (@attachments.name@) + + -
+
+ ( #general-comments.edit# | +#general-comments.delete# ) + + @links.label@ + - #general-comments.no_attachments# +
#general-comments.Actions#
+ +#general-comments.Revisions#
+-
+
- @revisions.revision_date@ +
- @revisions.revision_date@ +
+
+
+ @title@ (#general-comments.details#)+
++ <%= [util_convert_plaintext_to_html $content] %> + ++ @content@ + +
-- @author@ + (@pretty_date@) +
| + + | + ++ + | +
+@dimensional_bar@ +
+@comments_table@ + + + + Index: openacs-4/contrib/packages/general-comments/www/admin/index.tcl =================================================================== RCS file: /usr/local/cvsroot/openacs-4/contrib/packages/general-comments/www/admin/Attic/index.tcl,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/contrib/packages/general-comments/www/admin/index.tcl 2 May 2003 15:50:59 -0000 1.1 @@ -0,0 +1,91 @@ +# /packages/general-comments/www/admin/index.tcl + +ad_page_contract { + General comments administration main page + + @author Phong Nguyen (phong@arsdigita.com) + @author Pascal Scheffers (pascal@scheffers.net) + @creation-date 2000-10-12 + @cvs-id $Id: index.tcl,v 1.1 2003/05/02 15:50:59 daveb Exp $ +} { + {orderby {} } +} -properties { + page_title:onevalue + context:onevalue + dimensional_bar:onevalue + comments_table:onevalue +} + +# return_url to be passed to various helper pages so that we return to +# this page with the proper parameters +set return_url [ad_urlencode index?[export_ns_set_vars url]] + +# dimensional slider definition +set dimensional [list \ + [list approval "[_ general-comments.Status]" unapproved [list \ + [list approved "[_ general-comments.approved]" {where "[db_map status_approved]"} ] \ + [list unapproved "[_ general-comments.unapproved]" {where "[db_map status_unapproved]"} ] \ + [list any "[_ general-comments.all]" {} ] \ + ]] \ + [list modified "[_ general-comments.Last_Modified]" any [list \ + [list 1d "[_ general-comments.last_24_hours]" {where "[db_map modified_last_24hours]"}] \ + [list 1w "[_ general-comments.last_week]" {where "[db_map modified_last_week]"}] \ + [list 1m "[_ general-comments.last_month]" {where "[db_map modified_last_month]"}] \ + [list any "[_ general-comments.all]" {} ] \ + ]] +] +set dimensional_bar [ad_dimensional $dimensional] + +# ad_table definition +set table_def [list \ + [list num "[_ general-comments.Num]" {} {
1.2. Design Document
1.2.1. Essentials
User directory: /general-comments/
ACS administrator directory: /general-comments/admin/
TCL API: + +
+PL/SQL API: + +
none
Data model: + +
+
1.2.2. Introduction
General Comments enables all users in the community to add a + comment to any object in the system. Any comment can have files or + hyperlinks attached.
This package is intended to utilize the users' engagement in the + community by letting them voice their opinion on any topic (object) + on the site. Commenting an article, a press release or any other + object is never more than a click away.
Administrators can choose to put comments on hold until they've + been approved or moderated.
User feedback is an invaluable resource for improvements. For + example, the usage of General Comments on documentation not only + allows feedback, it can shape, extend and refine draft ideas before + they are taken to the next level.
1.2.3. Historical Considerations
General Comments in ACS 4.0 differs from previous versions by + utilizing the ACS Object system, introduced in 4.0. The data-model + has been changed to accomodate this adoption.
In ACS 3.x, general comments did not have revisioning. Let's + assume that in an ACS 3.x installation, the policy for comments was + set to "closed", meaning comments must be approved by an + administrator before it goes live. The following unwanted scenario + could occur:
A user posted a comment which was approved by the + administrator.
The user notices that there was a spelling error, and makes a + change to the posted comment.
From the time of the user's correction to the time the + adminstrator re-approves the comment, other users will not be able + to read the comment, since the new data replaced the old one.
General Comments implements the revisioning feature provided by + the Content Repository. Users are able to view all of their + revisions for a comment, along with an indication of which revision + is live. This allows the contents of an older revision to be seen + by the public while a newer revision is awaiting adminstrative + approval.
1.2.4. Competitive Analysis
not available
1.2.5. Design Tradeoffs
not available
1.2.6. API
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 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 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 [acs_object_name].
link_text: The text of the link returned. Defaults to + "Add a comment".
context_id: The context_id to set for the comment. + Defaults to the object_id of the object being commented on.
category: This feature is not 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 links. In this case, both procedures will return + nothing and log a notice.
Note: In the alpha release of + 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 ones are marked as + deprecated. The final version will completely remove all traces of + the namespace procedures.
PL/SQL API
None. Uses PL/SQL functions provided by ACS Messaging.
1.2.7. Data Model Discussion
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 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 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 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 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, which would set up the + multirow datasource in the current environment.
From the .adp page, loop through the multirow + datasource.
1.2.8. User Interface
General Comments provides two similar sets of UIs for + adminstrators and normal users. The adminstrator UI allows + approval/unapproval of comments as well as deletion of comments. + The normal user UI presents to users all of their created comments, + with links to editing and creating attachments.
1.2.9. Configuration/Parameters
AutoApproveCommentsP: Sets whether comments go + live immediately.
AllowFileAttachmentsP: Sets whether files can be + attached to comments.
AllowLinkAttachmentsP: Sets whether links can be + attached to comments.
MaxFileSize: Maximum file size that can be + uploaded in bytes.
1.2.10. Future Improvements/Areas of Likely Change
Subsite administration
Cascading parameters to depending packages.
Revisioning of attachments
1.2.12. Revision History
| Document Revision # | Action Taken, Notes | When? | By Whom? |
| 0.2 | Revision | 12/11/2000 | Phong Nguyen |
| 0.1 | Creation | 10/26/2000 | Phong Nguyen |
Last modified: $Id: design.html,v 1.1 2003/05/02 15:51:13 daveb Exp $ +
Chapter 1. Developer's guide
1.1. Requirements Document
1.1.1. Introduction
This is the requirements document for the General Comments + package for ACS 4.0. General Comments is an application that takes + advantage of the ACS Messaging service package.
1.1.2. Vision Statement
User feedback and engagement is the very heart of a + collaborative community. General Comments allows users to comment + on any object in the community, such as articles, white papers, + press releases or pictures.
Comments are not limited to text, but can include attachments + such as links, pictures or other documents.
Users can edit their own comments and an administrator can + choose to moderate all or particular comments before they go live + on the site.
1.1.3. Application Overview
General Comments is an application package that relies on the + ACS Messaging package. Comments can be associated with any object + in ACS 4.0, which gives you the benefits of the Permission System. + Comments are stored as ACS Messages.
When a user creates a comment, General Comments stores the + comment as an ACS Message and associates the comment to the object + commented on. The value set by the adminstrator on whether comments + go live immediately or needs approval first is stored along with + the comment during this phase. After this, the user is presented + with a page that displays contents of the comment along with + revision history, attachments, and links to perform actions on the + comment such as adding attachments or editing the comment.
1.1.4. Use-cases and User-scenarios
This package supports empowering all users with the option of + adding comments to objects in the system, and editing their own + comments later on.
A user adding a comment:
Nurse Nancy is browsing through an ACS 4.0 site that has a page for + medical emergencies. Upon reaching the bottom of the page, Nancy + sees a posting that reads, "Please help, my child has just + swallowed some cleaning solution!!!". Nancy sees that this + posting was made only 30 seconds ago and quickly posts a remedy for + this situation. After she makes her posting, she immediately + revisits the page and happily sees that her posting is already + available.
A user editing an old comment:
George Genius is reviewing all of the comments he has posted over + the last 24 hours. In one of his postings, George notices that his + mathematical formula for earthquake prediction was incorrect. He + then clicks on the edit link, makes changes to his formula and + submits his changes. Since comments are moderated, others will only + see his older incorrect version until his changes are approved. + George eagerly awaits for his changes to be approved so that he + won't be ridiculed by his colleagues for his mistakes.
An adminstrator moderating:
Adam Admin is looking over all recently unnapproved changes to + comments. Adam sees that George Genius has made a correction to the + earthquake prediction formula in which he helped write. He believes + that the their original formaula is correct, so Adam does not + approve of the changes. Several days later, George barges into + Adam's office wondering why his changes were not approved. After a + few hours George convinces Adam that the new modifications were + correct, and so Adam approves George's comment. +
1.1.6. Requirements: Data Model
10.0 Comments can be attached to any object in the system.
10.10 Maintain revisioning of comments.
10.20 Store comment as an acs-message.
10.30 Allow separation of comments on an object.
10.40 Allow file and url attachments to comments.
10.50 Allow limitations on size of file attachments.
10.60 Use permissioning system to control creation of comments.
1.1.7. Requirements: API
20.0 A summary type function that retrieves all + comments for a particular object.
20.10 A link function that generates an + appropriate link to add a comment.
1.1.8. Requirements: Interface
The Community Member's Interface
The user interface for community members is a set of HTML pages + that allow creation and editing of comments.
30.0 Customized presentation.
30.0.10 Show all comments that the user created.
30.0.20 Have sliders to show approved/uapproved comments.
30.0.30 Have sliders to show comments by age.
30.10 Comments can be viewed in detail.
30.20 Provide ways for a user to add attachments to a comment.
30.30 Allow editing of comments.
30.40 Provide a way to display attached images.
30.50 Allow download of attached files.
The Administrator's Interface
The user interface for adminstrative members is a set of HTML pages + that allows deletion and approval of comments.
40.0 Customized presentation.
40.0.10 Show all created comments.
40.0.20 Have sliders to show approved/unapproved comments.
40.0.30 Have sliders to show comments by age.
40.10 Allow deletion of comments.
1.1.9. Revision History
| Document Revision # | Action Taken, Notes | When? | By Whom? |
| 0.2 | Revision | 12/11/2000 | Phong Nguyen |
| 0.1 | Creation | 10/26/2000 | Phong Nguyen |
Last modified: $Id: dev-guide.html,v 1.1 2003/05/02 15:51:14 daveb Exp $ +
- Table of Contents
- 1. Developer's guide
- 1.1. Requirements Document
- 1.1.1. Introduction
- 1.1.2. Vision Statement
- 1.1.3. Application Overview
- 1.1.4. Use-cases and User-scenarios
- 1.1.5. Related Links
- 1.1.6. Requirements: Data Model
- 1.1.7. Requirements: API
- 1.1.8. Requirements: Interface
- 1.1.9. Revision History
- 1.2. Design Document
- 1.2.1. Essentials
- 1.2.2. Introduction
- 1.2.3. Historical Considerations
- 1.2.4. Competitive Analysis
- 1.2.5. Design Tradeoffs
- 1.2.6. API
- 1.2.7. Data Model Discussion
- 1.2.8. User Interface
- 1.2.9. Configuration/Parameters
- 1.2.10. Future Improvements/Areas of Likely Change
- 1.2.11. Authors
- 1.2.12. Revision History
- 2. User's guide
| Next | ||
| Developer's guide |
| General Comments | ||
|---|---|---|
| Prev |