Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Comments UI Update

From MoodleDocs

Scenarios

Teacher Posts a Text Comment on Assignment Submission

The teacher creates a text comment about the user’s assignment submission. The comment is posted and then a message is sent informing the student that a new comment for the assignment has been created by the teacher.

Student Attaches File to a Comment on a Blog

A Carl Monk wants to show Xao Xin Mei a mathematical article article with a proof that confirms the theory she proposed in her latest blog post on music and math. After creating the text of the post Carl would like to drag the article file to the comment and have it attached for Xao to download later.

Student Posts Video Comment on an Assignment Submission

Kristen Sanchez doesn’t agree with the grade that Alex Souza gave her on her english paper. She wants to make sure the Alex sees her frustration with the lack of comments on her face and wishes to post a video comment to the assignment. After setting up her web cam Kristen clicks on the web cam button and begins to record her video message to her Alex. After she stops the recording and saves the comment the video is displayed in the commenting area.

Teacher Posts and Audio Comment to a Student’s Assignment

Phill O’Neil prefers not to have to type out his comments to students, instead he like to save a running commentary as he reviews their assignment. Phill opens up the assignment and then starts and audio comment in the comments area of the assignment. As Phill reads he states areas of the document that need to change. After he has finished reviewing the assignment submission he saves the audio comment and the student can review it.

Student Receives an Email That a new Comment has Been Posted

Phill O’Niel has posted a comment on a math proof that Carl Monk submitted to his course. Carl has configured his message output to send an email to him whenever a new comment is created for an assignment. Carl receives an email stating that Phill has created a comment on his math submission and that he can view the comment by clicking on a link.

Feature Information

Commenting Configuration

Description

Not all sites will want to allow file attachments in their comments. Site administrators will be able to enable or disable the robust commenting features.

Requirements
  1. A new link will be added to the Settings block under the Site administration group called Comments. See Mockup: Comments Settings
  2. The comments link will display the comments settings page when clicked. See Mockup: Comments Settings
  3. A new checkbox setting for comments will be added called Allow file attachments. See Mockup: Comments Settings
  4. The allow file attachments checkbox will be checked by default. See Mockup: Comments Settings
  5. The allow file attachments checkbox will have the descriptive text of Allow user’s to upload files to comments. below the checkbox. See Mockup: Comments Settings
  6. A new drop down setting for comments will be added called maximum file upload. See Mockup: Comments Settings
  7. The maximum file upload drop down will have a default value of 2MB. See Mockup: Comments Settings
  8. The maximum file upload drop down will have the descriptive text of Define the largest size of file that can be uploaded to a comment, limited by the site-wide setting.. below the drop down. See Mockup: Comments Settings
  9. The maximum file upload drop down will use the Moodle default upload size values with a maximum of the site upload limit setting.
  10. The the allow file attachments setting is unchecked then the maximum upload size setting will be disabled.
Mockups
Settings Comments Link

settingsCommentsLink.png

Comments Settings

commentSettings.png

Use Cases
Site Administrator Disables File Attachments to Comments

Description

The site administrator determines that files should not be attached to comments and disables the feature at the site level

Preconditions

  1. The user is logged in
  2. The user is configured to be a site administrator
  3. The user is at the site level

Steps

  1. The site administrator expands the Site administration group in the settings block
  2. The site administrator clicks on the comments link
  3. The site administrator unchecked the Allow file uploads checkbox
  4. The site administrator clicks the Save changes button

Postconditions

  1. The file attachments area of comments doesn’t display
  2. users can’t upload files to a comment
Site Administrator Lowers the Maximum Upload Size in Comments

Description

The site administrator determines that the maximum size of a file uploaded to a comment should be lower than the site maximum upload size.

Preconditions

  1. The user is logged in
  2. The user is configured to be a site administrator
  3. The user is at the site level

Steps

  1. The site administrator expands the Site administration group in the settings block
  2. The site administrator clicks on the comments link
  3. The site administrator selects 100 KB for the Maximum upload size drop down
  4. The site administrator clicks the Save changes button

Postconditions

  1. When a user drags a file larger than 100 KB to the file area of a comment and error appears stating the file is too large.

Commenting Updates

Description

Moodlerooms will update the commenting API to add file upload support and anonymous display of comments.

Requirements
  1. The Moodle comment API will support a minified file uploader if Allow file uploads is checked in the comments site settings. (See Mockup: Viewing and Adding Comments)
  2. The mini file uploader will display the following information: (See Mockup: Viewing and Adding Comments)
    1. Add file with icon
    2. Drag and drop area if supported by the browser
    3. A list of files with their file type icon under the add file and drag and drop area.
  3. A new file manager form type will be created to support the mini file uploader.
  4. Comments will not require text in the text area to be saved if a file is uploaded.
  5. The user will click the save comment button to record the comment in the comment display area. (See Mockup: Viewing and Adding Comments)
  6. The comment display will be updated to display the following information about the comment:
    1. The user’s profile picture
    2. The user’s fist and last name
    3. The date and time the comment was posted.
  7. The comment display area will display comments based on the plugins display preferences. (See Mockup: Viewing and Adding Comments) for an example.
  8. The comment API will allow a developer to determine the order comments are displayed in. The options will be:
    1. Newest first
    2. Oldest first
  9. The comment API will allow the developer to load all comments or a range of comments.
  10. A comment with a file attached to it will display the file below the comment text. (See Mockup: File Attachment to Comment)
  11. If the comment site settings allow file attachments setting is unchecked then any previously attached files will not display in the comments.
  12. When the user clicks the save comment button the comment and any attachments will immediately display in the comment display area.
  13. When a user deletes or saves a comment the comments api will return any new comments to be displayed to the user.
  14. The comments API will support a plugin requesting to renderer comments with anonymised user data
  15. When a comment is set to render with anonymised user data then the work Participant with a number will display instead of the user's name. See [Mockup: Anonymous Comment!#AnonymousComment].
  16. When a comment is set to render with anonymised the number displayed with the participant text will be the user's id, context id for the comment and the item id all added together. See [Mockup: Anonymous Comment!#AnonymousComment].
  17. When a comment is set to render with anonymised the user's identification will change based on the context and plugin that the user's is commenting on. See [Mockup: Anonymous Comment!#AnonymousComment].
  18. The picture displayed with an anonymised comment will be the default user avatar for the Moodle theme. See [Mockup: Anonymous Comment!#AnonymousComment].
  19. The comment API will display comments for users with the permission to grade the activity when the comment is associated with an activity. See [Mockup: Anonymous Comment Stream|#AnonymousCommentStream]
  20. The comment API will allow user's to post content from repositories when set to be anonymous, even if the repository could give away the user's identity (for example video).
  21. The user that is viewing the comments will see all of their comments with their user information and not anonymised. See [Mockup: Anonymous Comment Stream|#AnonymousCommentStream]
Mockups
Viewing and Adding Comments

viewcomments.png

Video Comment

videocomment.png

File Attachment to Comment

fileattachmentcomment.png

Anonymous Comment

anonymousComment.png

Anonymous Comment Stream

anonymousCommentStream.png

Use Cases
Teacher Uploads a File as a Comment to an Assignment Submission via Add Button

Description

The teacher has commented on a student’s submission offline and wants to upload the file as a submission comment and isn’t using a browser that supports drag and drop. They will upload the file via the add button and the upload repository.

Preconditions

  1. The user is logged in
  2. The user is enrolled as a teacher in a course
  3. An assignment has been created that allows submission comments
  4. A student has posted a submission
  5. The teacher has a file to upload on their desktop
  6. The user has navigated to the course
  7. Comment settings has the Allow file uploads checked

Steps

  1. The teacher clicks on the assignment name
  2. The teacher clicks the add button below the textarea
  3. The teacher clicks the Upload repository link
  4. The teacher clicks the Choose file button
  5. The teacher selects the file from their computer
  6. The teacher clicks the Upload file button
  7. The teacher clicks the Save comment button

Postconditions

  1. The teachers comment is displayed in the comment display area with the file attached
  2. If more than 2 comments have been created the scroll bar appears.
Teacher Uploads a File as a Comment to an Assignment Submission via Drag and Drop

Description

The teacher has commented on a student’s submission offline and wants to drag the file to the comment area to upload it.

Preconditions

  1. The user is logged in
  2. The user is enrolled as a teacher in a course
  3. An assignment has been created that allows submission comments
  4. A student has posted a submission
  5. The teacher has a file to upload on their desktop
  6. A browser that supports drag and drop is used
  7. The user has navigated to the course
  8. Comment settings has the Allow file uploads checked

Steps

  1. The teacher clicks on the assignment name
  2. The teacher drags the file from their pc to the drag and drop file area
  3. The teacher clicks the Save comment button

Postconditions

  1. The teachers comment is displayed in the comment display area with the file attached
  2. If more than 2 comments have been created the scroll bar appears.
Teacher Records a Video Comment for an Assignment Submission

Description

The teacher wants to record a visual comment about the student’s assignment submission instead of typing or commenting on a file.

Preconditions

  1. The user is logged in
  2. The user is enrolled as a teacher in a course
  3. An assignment has been created that allows submission comments
  4. A student has posted a submission
  5. The teacher has a web camera installed
  6. The site has the kaltura web cam TinyMCE button enabled
  7. The user has navigated to the course

Steps

  1. The teacher clicks on the assignment name
  2. The teacher clicks the web cam button in the file upload area
  3. The teacher records their web cam video
  4. The teacher clicks the Save comment button

Postconditions

  1. The teachers comment is displayed in the comment display area with a video player to play the video
  2. If more than 2 comments have been created the scroll bar appears.
Student Views More than 2 Assignment Submission Comments

Description

The student is viewing the submission comments for their assignment submissions. A conversation has been going on and the student is scrolling into the history to view some of the past comments by the teacher.

Preconditions

  1. The user is logged in
  2. The user is enrolled as a student in a course
  3. An assignment has been created that allows submission comments
  4. The student has posted a submission
  5. The teacher has posted more than 1 submission comment
  6. The student has posted more than 1 submission comment
  7. The user has navigated to the course

Steps

  1. The student clicks on the assignment name
  2. The student clicks up on the scrollbar

Postconditions

  1. As the scroll bar goes up previously created comments are displayed
Teacher Deletes a Comment With Attached Files

Description

The teacher wants to remove a comment they have made with files that we incorrectly attached.

Preconditions

  1. The user is logged in
  2. The user is enrolled as a teacher in a course
  3. An assignment has been created that allows submission comments
  4. A student has posted a submission
  5. The teacher has attached a file to a comment and saved it
  6. Comment settings has the Enable file uploads checked
  7. THe teacher has navigated to the course

Steps

  1. The teacher clicks on the assignment name
  2. The teacher clicks the delete button to the right of the comment

Postconditions

  1. The comment and all file attachments are deleted
  2. The comment is removed from the screen.
Student Views Assignment Submission Comments With a Screen Reader

Description

The student is visually impaired and reviewing the comments for their assignment submission using a screen reader.

Preconditions

  1. The user is logged in
  2. The user is enrolled as a student in a course
  3. An assignment has been created that allows submission comments
  4. A student has posted a submission
  5. The student has navigated to the course

Steps

  1. The student skips to the main content
  2. The student tabs to the activity name
  3. The student hits the enter key
  4. The student tabs to the comment area

Postconditions

  1. The student clearly understand the order of the comments
  2. ====== Student Views a Blind Marking Assignment Submission With Comments ======

Description

The student is viewing the submission comments for their assignment submissions. A conversation has been going on and the student is scrolling into the history to view some of the past comments by the teacher.

Preconditions

  1. The user is logged in
  2. The user is enrolled as a student in a course
  3. An assignment has been created that allows submission comments and is set to blind marking
  4. The student has posted a submission
  5. The teacher has posted more than 1 submission comment
  6. The student has posted more than 1 submission comment
  7. The user has navigated to the course

Steps

  1. The student clicks on the assignment name

Postconditions

  1. As the scroll bar goes up previously created comments are displayed
Teacher Views a Blind Marking Assignment Submission With Comments

Description

The teacher is views a student’s submission comments for an assignment that has been set to blind marking

Preconditions

  1. The user is logged in
  2. The user is enrolled as a teacher in a course
  3. An assignment has been created that allows submission comments and is set to blind marking
  4. The student has posted a submission
  5. The teacher has posted more than 1 submission comment
  6. The student has posted more than 1 submission comment
  7. The user has navigated to the course

Steps

  1. The teacher clicks on the assignment name
  2. The teacher clicks the View/grade all submissions link
  3. The teacher clicks on the grade icon for one of the students in the grade table

Postconditions

  1. All comments made by the student are set to Participant and a number
  2. The teacher’s comment displays their name above it.

Comments Backup and Restore

Description

Moodlerooms will update the commenting API to support files in the backup and restore process.

Requirements
  1. If a file is attached to a comment it will be backed up with the comment following the current backup process.
  2. Anonymous comments will not be anonymous in the course backup and will be associated with the user who created the comment.
Use Cases
Site Administrator Backs up a Course with Comments

Description

The site administrator wants to backup the current course with the user’s data.

Preconditions

  1. The user is logged in
  2. The user is set as a site administrator
  3. An assignment has been created that allows submission comments
  4. A student has posted a submission
  5. A teacher has commented on the assignment submission
  6. A student has commented on the assignment submission
  7. The site administrator has navigated to a course

Steps

  1. The site administrator clicks the Backup link in the Settings block under the Course Administrator group
  2. The site administrator leaves the default settings
  3. The site administrator click the Next button
  4. The site administrator leaves the default settings
  5. The site administrator clicks the Next button
  6. The site administrator clicks the Perform backup button
  7. The site administrator clicks the Continue button

Postconditions

  1. The files attached to user comments in the backup are in the backup file
  2. If the course is restored the comments will show with the files attached to the correct comments.
Site Administrator Restores a Course with Comments

Description

The site administrator wants to restore a course that has user’s data and comments on assignments.

Preconditions

  1. The user is logged in
  2. The user is set as a site administrator
  3. The site administrator has a course backup that contains the following:
    1. An assignment has been created that allows submission comments
    2. A student has posted a submission
    3. A teacher has commented on the assignment submission
    4. A student has commented on the assignment submission
  4. The site administrator is at the site level
  5. The backup file is less than 50 MB in size.

Steps

  1. The site administrator clicks the Restore link in the Settings block under Front page administration
  2. The site administrator drags the backup file to the drag and drop file area.
  3. The site administrator clicks the Restore button
  4. The include comments is checked under backup settings
  5. The site administrator clicks the Continue button
  6. The site administrator selects a category radio button under Restore as a new course
  7. The site administrator clicks the Continue button under Restore as a new course
  8. The site administrator keeps the default settings
  9. The site administrator clicks the Next button
  10. The site administrator clicks the Next button
  11. The site administrator clicks the Perform restore button
  12. The site administrator clicks the Continue button

Postconditions

  1. The site administrator can view the comments within the assignment.
  2. The comments have files correctly attached to each comment.

Comment Message Output

Description

When a new comments is created it is not communicated to the student or teacher. This makes comments less useful for many plugins that user comments as an important communication to both users. Comments will be updated to have a message output event that message outputs can display and a student or teacher can set to send to each message output type they want.

Requirements
  1. A new message output event will be created for comments.
  2. All comments when created will trigger a comment event that the message outputs can listen for.
  3. The comment message event sender will be set to the user that made the comment
  4. The comment message event recipient will be all users with the role to view the comment who are not the comment creator.
  5. The comment message event subject will be “New comment for <context>” where context is the location that the comment was created:
    1. Comment block - the course or activity the block is associated with
    2. Assignment submission - the assignment the comment is associated with
    3. Blog comment - the blog the comment is associated with.
  6. The comments message event full message will contain the following:
    1. The full comment in plaintext
    2. Text stating “View original message” that is linked to url to the comment in the location in Moodle where the user can view the comment (Comment block in course or assignment submission)
  7. The comment message event full message format will be plaintext.
  8. The comments message event short message will contain the following:
    1. Up to 80 character of the original comment in plain text
    2. The text “View original message at <url>” where the <url> is the url to the location in Moodle where the user can view the comment
  9. By default the message output settings for the comments event will be enabled for: (see Mockup: User Message Output Settings)
    1. Email
      1. When logged in
      2. When not logged in
    2. Alert
      1. When logged in
      2. When not logged in
    3. Streams
      1. When logged in
      2. When not logged in
Mockups
User Message Output Settings

commentmessageoutput.png

Use cases
Student Accesses an Alert After a Teacher Posts a Comment to an Advanced Forum in Joule Grader

Description

A teacher posts a comment for a student’s submission to an activity in the Joule grader and the student receives an alert when they login.

Preconditions

  1. User is logged in
  2. User is enrolled in a course as a student
  3. User has posted a submission to an advanced forum
  4. A teacher has posted an activity comment in the Joule grader for the student and activity

Steps

  1. The student views the front page
  2. The student sees a number of alerts in the upper right of the page
  3. The student clicks on the icon
  4. The student sees a Joule grader comment for an activity
  5. The student clicks on the link to the full comment in the Joule grader

Postconditions

  1. The student is show the activity in the Joule grader and the comment shows in the Activity comments area
Student Accesses an Alert After a Teacher Posts a Comment to an Assignment in Joule Grader

Description

A teacher posts a comment for a student’s submission to an activity in the Joule grader and the student receives an alert when they login.

Preconditions

  1. User is logged in
  2. User is enrolled in a course as a student
  3. User has posted a submission to an Assignment
  4. A teacher has posted an activity comment in the Joule grader for the student and activity

Steps

  1. The student views the front page
  2. The student sees a number of alerts in the upper right of the page
  3. The student clicks on the icon
  4. The student sees a Joule grader comment for an activity
  5. The student clicks on the link to the full comment in the Joule grader

Postconditions

  1. The student is show the activity in the Joule grader and the comment shows in the Activity comments area
Student Changes Their Comments Alert Message Output

Description

A student changes their message outputs to not display alerts when they are online for comments.

Preconditions

  1. User is logged in
  2. User is enrolled in a course as a student

Steps

  1. The student clicks on the My profile link
  2. The student selects message outputs in the settings block
  3. The student clicks on the alert when online for the comments setting.
  4. The student clicks the Save changes button

Postconditions

  1. The next comment in the Joule grader the student receives and email.
Student Changes Their Offline Comments Email Message Output Setting

Description

A student changes their message outputs to receive emails when they are offline for comments.

Preconditions

  1. The user is logged in
  2. The user is enrolled in a course as a student

Steps

  1. The student clicks on the My profile link
  2. The student selects Message outputs in the settings block
  3. The student clicks on the email when offline for the Comments setting.
  4. The student clicks the Save changes button

Postconditions

  1. The next comment on the student’s assignment submission will be emailed to the student if they are not logged into Moodle.
Student Clicks the URL to the Comment in the Message Output Email

Description

The student has received a comment message output in their email. The student clicks on the link to view the comment in Moodle.

Preconditions

  1. The user is not logged in
  2. The user received an email notifying them that a new comment exists

Steps

  1. The student clicks on the link in the email
  2. The student enters their username
  3. The student enters their password
  4. The student clicks the Login button

Postconditions

  1. The student is taken to the Moodle page where the comment can be read

Document Information

Revision Summary

Revision History

  • Jason Hardin 20130131: Split out Joule features from Moodle features. Added new mockups for Moodle specific interfaces. Updated the Comments update use cases to include deletion and screen readers.
  • Jason Hardin 20130205: Added message output event information. Added a new use case for navigating to the comment in Moodle from email, and updated screen shots to remove old information and add some more descriptive information.
  • Jason Hardin 20130212: Removed the HTML editor setting and migrated video and audio comments to using the file picker.
  • Jason Hardin 20130221: Added Alerts and streams back to the specification as these will be released to the Moodle Community.
  • Jason Hardin 20130221: Added anonymous comment support to allow for Blind marking in assignment submission comments. See tracker ticket [https://tracker.moodle.org/browse/MDL-37497 MDL-37497]
  • Jason Hardin 20130222: Moved Joule Comments changes back into this specification because Moodlerooms will be releasing all Joule features that caused the specification separation.

See also

Comments Forum Discussion