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 administrator 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 administrator 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 administrative 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.2 2017/08/07 23:48:12 gustafn Exp $
