Expertiza_Wiki - User contributions [en]

E1735. UI changes for review and score reports

2017-04-13T04:13:36Z

Ahasket: /* Low Level Design */

==Introduction==
This wiki provides details on the tasks that were undertaken as part of the continuous improvement to the Expertiza project.
===Background===
[[Expertiza_documentation|Expertiza]] is a web application where students can submit and peer-review learning objects (articles, code, web sites, etc). The application provides a complete system through which students and instructors collaborate on the learning objects as well as submit, review and grade assignments for the courses. It is used in select courses at NC State and by professors at several other colleges and universities. The Expertiza project is supported by the National Science Foundation.

===Overview of Review Functionality===

The Expertiza review system encompasses many types of reviews. Assignments can have multiple submission rounds defined with their own due dates and criteria. Each round can have an associated questionnaire whereby peers are encouraged, or required, to review each others' submissions and rate those submissions using the scores 1 through 5 for each question. The scores for each question are averaged to find the rating for the submission for each questionnaire response. The average of all questionnaire responses determine the score for the submission.After the reviews are submitted, the recipient of those reviews can rate the reviewers using a similar questionnaire. On this questionnaire, the author of the submission will rate the reviews based on the reviewers understanding, helpfulness, and respectfulness. This is a review of the reviews, thus it is termed a "metareview."

Both students and instructors using Expertiza have the ability to view the reviews and the scores associated with the reviews for each assignment. These screens will display review summary and detail information in various formats such as lists, graphs, and heatgrids. The instructor will be able to see all review and score information for all teams on the assignment whereas a student will only be able to see the review and score information pertaining to them.

The reviews and associated scores are available on the scores report. To access the score reports in Expertiza follow these instructions:

'''As a student'''

# Log into Expertiza.
# Click on the 'Assignments' link on the top navigation bar.
# Find the assignment in the list and click the title of the assignment.
# Click on the 'Your scores' link to see the standard view or click on the 'Alternate View' link to see the heatgrid view.

'''As an instructor'''

# Log into Expertiza.
# Hover over the 'Manage' item on the top navigation bar, then select click the 'Assignments' link.
# Find the assignment in the list and click the 'View scores' icon (a star with a magnifying glass) in the 'Actions' column.
# This will bring up the standard view. To see the heatgrid view, click the 'Alternate View' link on the team headings or click the 'view heatgrid' beneath the 'Final Score' when the team is expanded.

===Motivation===
By participating in the overall refactoring effort as part of the continuous improvement of Expertiza, students get an opportunity to work on a open source software project. This helps them gain exposure on the technologies used in the project as well as much needed experience in collaborating with peers as part of the software development process. This effort was undertaken as a final project for the CSC 517 - Object Oriented Design and Development course at North Carolina State University in the spring of 2017.

==Project Purpose==

===Requirements Statement===
Expertiza displays reviews (i) to the team who was reviewed, and (ii) to the reviewer. A student user can see all the reviews of his/her team’s project. The instructor can see all the reviews of everyone’s project. The instructor also has access to a review report, which shows, for each reviewer, all the reviews that (s)he wrote. Currently, the score report and review report use completely different code. This makes the UI non-orthogonal and also causes DRY problems. So, we would like to have a single way of displaying reviews that would be visible to students (reviews that they did, and reviews that their team received), and instructors (reviews that each time received, sorted by team; and reviews that each student did, sorted by student).

===Required Tasks===
The tasks involved as part of this requirements change are as follows:
# Compact the review display
#* Eliminate the blank lines between items within a single review. Instead vary the background color from line to line to improve readability
#* With a single click, there should be a way to hide all the reviews, reveal just the headings (as at present), or expand all the reviews
# At the top of each review, it should say
#* Who submitted the review. The instructor should see the user’s name and user-ID.
#* A student should see
#** “Reviewer #k”, where k is an integer between 1 and n, the number of reviews that have been submitted for this project
#** The version number of the review
#** The time the review was submitted
# There should be a tabbed view to switch between various review views
#* One tab has overall statistics (averages, min, max, as the present “normal” view)
#* One tab has the heat map (current “alternate” view)
#* One tab has a grid view, with no scores, but text comments in the grid squares, and then a “More” link to display the whole comment (which will require expanding the row of the grid)
#* Switching between reviews from Reviewer k and Reviewer j might also be done by clicking on different tabs. Or, it might be more convenient to keep the current score view, which lists the n reviews across the page. Then the student should be able to click on the reviewer number (the instructor would instead click on the reviewer name) and see the review done by that reviewer
# To make it easy to focus on the reviewer’s feedback, there should be a way to hide and/or gray the criteria (“questions”), so the responses stand out more clearly
# There needs to be a way to search all reviews (of a particular project, or by a particular individual) for a given text string. The user should be able to go from one instance of the text string to another by clicking down and up buttons

===Problem Statement===
In the current state, the score report for instructors and students are built differently though they display the same information using similar UI elements. The application has multiple views into the same information but the way in which those views are accessed, the code which populates them, and the layout of the screens differs unnecessarily between instructors and students and across the views themselves. This leads to redundant code in both the backend and frontend of the application. Furthermore, since the UI is not uniform between instructors and students, instructors may have difficulty assisting students in accessing their score information due to the differences which are present in the UI that leads to confusion.

Following are some of the issues with the current state UI which we seek to rectify.

====Scores Report====
[[File:Problem_Statement_Diagram_1A_-_Instructor_View_-_65.png]]

The scores report for students and instructors have very similar layouts despite being created by different controller methods and views. They both display graphs, reviews on team submissions, author feedback, and score metrics. The primary different between them is that the instructor view (shown above) displays information for all teams in a collapsible accordion widget format while the student view (shown below) display the information only for a single team. There are some further discontinuities between the two UIs. For example, the student cannot access the heatgrid view from within the scores report page. This view is only accessible from the assignment page for students. For instructors there are two ways to access the heatgrid view from a single page. The 'Alternate View' link is adjacent to the team name on the heading bar and there is also a link inexplicably placed beneath the 'Final Score' field.

[[File:Problem_Statement_Diagram_1B_-_Student_View_-_65.png]]

====Author Feedback====
Author feedback takes two different forms when being shown to instructors but only one form for students. Both students and instructors have access to the author feedback format shown on the left in the student view. This format is identical to the format of the review scores and is displayed on the scores report for both instructor and student. The format on the right is shown on the heatgrid view yet it is only available to instructors. The information conveyed by these two formats is nearly identical and not uniformly available to all consumers of this information.

[[File:Problem_Statement_Diagram_2_-_Author_Feedback_-_65.png]]

====Graphs and Charts====
The scores report view has a bar of graphs and charts at the top of the page for both students and instructors. Both views shown below use a donut chart and bar graphs though their method of display is not uniform. The instructor view has titles beneath each item but the student view does not. The 'Submitted work' and 'Author Feedback' titles shown, despite being beneath the bar graphs, are actually headings for the metrics which are displayed beneath the graphs. Also, the graphs contain two labels on the y-axis: the maximum score and the average score. The graphs are so compact that the values on the axis overlap and make them illegible.

[[File:Problem_Statement_Diagram_3_-_Squashed_Graphs_-_65.png]]

==Project Design==

===High Level Design===

====Design Overview====
The project requirements state that we need to create a standard UI for accessing and consuming review and score information. The emphasis will be on smart and purposeful code reuse as well as ease of navigation to access information. To achieve these results we will redesign the scores report to work for both instructors and students alike. There will be a single route, a single controller method, and a single view that is common t users of both role types. In some instances, such as with the graphs and charts, the data will be different enough to warrant separate methods to retrieve the values needed. In most instances, the data is identical and will be accessed identically.

We will create a standard hierarchy which works for both students (who only need to see a single team's scores) and instructors (who need to see all teams' scores). This hierarchy will be rendered within a page in the form of a set of tabbed panes which contain the contents. We will separate the information among four tabs.

# Reviews
# Author Feedback
# Statistics
# Heat Grid

Putting these components on different tabs will allow us to de-clutter the UI. The instructor scores report UI has multiple ways to expand and collapse sections of information, links are placed in some unusual places, and the page can get so cluttered that it is difficult to distinguish one thing from another. This will be cleaned up by removing some links, removing the author feedback and the charts, and placing the reviews and scores into more discernible sections. The graphs and charts will be on their own tab so they can be larger and easier to read. Since they are not confined to a single bar of a fixed height new graphs and charts can be added. The heat grid will no longer be coupled with the author feedback and there will be a standard author feedback view which encompasses all information needs. Each of these tabs will be rendered using their own partial.

To prevent the application from pulling data for tabs which the user will not view, AJAX calls will be used to access the data on demand without reloading the page. These calls can also be expanded to request data for individual sections. Routes will be created to controller methods specifically to pull the data for each tab so that calls can be made to them to generate the necessary data structures. These will be accessed when a user expands a group or switches tabs.

====Technologies Used====

{| class="wikitable"
|-
! Technology
! Technology Type
! Use(s)
|-
| Ruby
| Language
| Core development of the application's backend system
|-
| Rails
| Framework
| Implements MVC; CRUD support; Web application support
|-
| RSpec (rspec)
| Gem
| Enables TDD; supports testing DSL
|-
| JQuery (jquery.ui.tabs)
| Library
| Enables creation of tabbed Web interfaces
|-
| JQuery (jquery.ui.accordion)
| Library
| Enables creation of accordion widgets for Web interfaces
|-
| Sass (sass-rails)
| Gem
| Sass style sheet pre-processor engine
|-
| Cascading Style Sheets (CSS)
| Language
| Web page presentation description language
|-
| Sassy CSS (SCSS)
| Language
| Superset of CSS style sheet language
|-
| rails-ajax
| Gem
| Enable AJAX to refresh containers within views without reloading the page
|}

====Software Patterns====

'''Model-View-Controller (MVC)''' - MVC is a software architectural pattern which divides an application into three parts which separate the data representation from the interface through which users will access and operate on the data. We will use this pattern to logically segregate our interface from the business logic implementation. The main components of this pattern are the:
* Model - The underlying logical structure of the application's data along with the accesses and operators on the data in the persistent storage medium.
* View - The user facing representation of the data along with the means for the user to request, operate on, or view the data.
* Controller - The intermediary layer between the Model and the View which accepts requests from the View, translates that to the Model, receives the Model's response and formats the response to the View.

'''Active Record''' - A software architectural pattern which wraps data from persistent storage, along with the method to operate on the data, in a class or object of a class to be used within an application. It uses the object-relation mapping (ORM) technique to create virtual database objects. We will use this pattern to access the persistent storage in a standard way and to generate object representations of the records.

'''Factory Method''' - A creational software design pattern which allows a class to instantiate objects but defer the creation to subclasses of the parent class. We will use this pattern in various places to generate objects for either students or instructors based on the user's role at the time of instantiation. This will allow us to have a single class to interact with from the controller and views but remain flexible enough to accommodate the needs of the different user types.

===Low Level Design===

====Screen Mockups====

'''New Scores Report With Multiple Teams and Collapsed Reviews'''

[[File:Expanded_Teams_With_Collapsed_Tabs_-_35.png]]

'''New Scores Report With Multiple Teams and Expanded Reviews'''

[[File:Expanded_Teams_With_Expanded_Tabs_-_35.png]]

====Class Diagram====

====Files Changed====

{| class="wikitable"
|-
! File
! Changes
|-
| grades_controller.rb
| Add extra methods for filters of student names, team names, or assignment titles. Edit the index and show methods to support new tabs and expansion areas in the display.
|-
| view_my_scores.html.erb
| Edit arguments passed and linkage to the new display tabs.
|-
| _summary_reviews.html.erb
| Add more expansion areas to the display to organize the reviews.
|-
| _reviewTabs.html.erb
| Add new display tabs by building on the current test suite in this file.
|-
| _searchbox.html.erb
| Edit linkage to point to the new search method in grades_controller.rb
|}

==Test Plan==
For testing, we built off the existing test framework which implemented RSPEC. The goal of our testing is to verify that the existing functionality is still present in the new views and is accessible to both the student and the instructor. Below are the tests that have been modified or created to verify the changed functionality. Any other tests not listed below are assumed to be unmodified and are intended to still work with the new updates. Note that some requirements of this project cannot be verified with the script such as formatting changes, but any functional modifications to the layout will be verified.

{| class="wikitable"
! colspan="2" | Test Case 1
|-
! Test Type
| Functional
|-
! Scenario
| Test to see if modifications to the display_as_html function in response.rb order to hide the “feedback review” button is correct for a student
|-
! Pre-Conditions
|
Make sure student to test with has the following:
#Has one course assigned
#Has one assigned as part of that course
#Has more than one review for that assignment
|-
! Description
|
#Login to the site as a student
#Click on "Assignments" on the top menu
#Select an assignment from the list
#On the "Submit or Review work for Expertiza" screen, click on "Your scores”
#On the "Summary Report for assignment" screen, verify that the "Give feedback for Review 1" button is not present
|-
| colspan="2" |  
|-
! colspan="2" | Test Case 2
|-
! Test Type
| Functional
|-
! Scenario
| Test to see if modifications to the display_as_html function in response.rb order to show the “feedback review” button is correct for a student
|-
! Pre-Conditions
|
Make sure student to test with has the following:
#Has one course assigned
#Has one assigned as part of that course
#Has more than one review for that assignment
|-
! Description
|
#Login to the site as a student
#Click on "Assignments" on the top menu
#Select an assignment from the list
#On the "Submit or Review work for Expertiza" screen, click on "Your scores”
#On the “Summary Report for assignment” screen, select the “Show Review” button
#On the "Summary Report for assignment" screen, verify that the "Give feedback for Review 1" button is present
|-
| colspan="2" |  
|-
! colspan="2" | Test Case 3
|-
! Test Type
| Functional
|-
! Scenario
| Test to see if modifications to the display_as_html function in response.rb order to hide the “feedback review” button is correct for an instructor
|-
! Pre-Conditions
|
Make sure student to test with has the following:
#At least one assignment exists
#Has more than one review for that assignment
|-
! Description
|
#Login to the site as an instructor
#Click on "Manage" on the top menu
#Click on “Assignments”
#Select an assignment from the list
#Click on "View Scores”
#On the "Summary Report for assignment" screen, verify that the "Give feedback for Review 1" button is not present
|-
| colspan="2" |  
|-
! colspan="2" | Test Case 4
|-
! Test Type
| Functional
|-
! Scenario
| Test to see if modifications to the display_as_html function in response.rb order to show the “feedback review” button is correct for an instructor
|-
! Pre-Conditions
|
Make sure student to test with has the following:
#At least one assignment exists
#Has more than one review for that assignment
|-
! Description
|
#Login to the site as an instructor
#Click on "Manage" on the top menu
#Click on “Assignments”
#Select an assignment from the list
#Click on "View Scores”
#On the “Summary Report for assignment” screen, select the “Show Review” button
#On the "Summary Report for assignment" screen, verify that the "Give feedback for Review 1" button is present
|-
| colspan="2" |  

E1735. UI changes for review and score reports

2017-04-13T04:12:49Z

Ahasket: /* Low Level Design */

==Introduction==
This wiki provides details on the tasks that were undertaken as part of the continuous improvement to the Expertiza project.
===Background===
[[Expertiza_documentation|Expertiza]] is a web application where students can submit and peer-review learning objects (articles, code, web sites, etc). The application provides a complete system through which students and instructors collaborate on the learning objects as well as submit, review and grade assignments for the courses. It is used in select courses at NC State and by professors at several other colleges and universities. The Expertiza project is supported by the National Science Foundation.

===Overview of Review Functionality===

The Expertiza review system encompasses many types of reviews. Assignments can have multiple submission rounds defined with their own due dates and criteria. Each round can have an associated questionnaire whereby peers are encouraged, or required, to review each others' submissions and rate those submissions using the scores 1 through 5 for each question. The scores for each question are averaged to find the rating for the submission for each questionnaire response. The average of all questionnaire responses determine the score for the submission.After the reviews are submitted, the recipient of those reviews can rate the reviewers using a similar questionnaire. On this questionnaire, the author of the submission will rate the reviews based on the reviewers understanding, helpfulness, and respectfulness. This is a review of the reviews, thus it is termed a "metareview."

Both students and instructors using Expertiza have the ability to view the reviews and the scores associated with the reviews for each assignment. These screens will display review summary and detail information in various formats such as lists, graphs, and heatgrids. The instructor will be able to see all review and score information for all teams on the assignment whereas a student will only be able to see the review and score information pertaining to them.

The reviews and associated scores are available on the scores report. To access the score reports in Expertiza follow these instructions:

'''As a student'''

# Log into Expertiza.
# Click on the 'Assignments' link on the top navigation bar.
# Find the assignment in the list and click the title of the assignment.
# Click on the 'Your scores' link to see the standard view or click on the 'Alternate View' link to see the heatgrid view.

'''As an instructor'''

# Log into Expertiza.
# Hover over the 'Manage' item on the top navigation bar, then select click the 'Assignments' link.
# Find the assignment in the list and click the 'View scores' icon (a star with a magnifying glass) in the 'Actions' column.
# This will bring up the standard view. To see the heatgrid view, click the 'Alternate View' link on the team headings or click the 'view heatgrid' beneath the 'Final Score' when the team is expanded.

===Motivation===
By participating in the overall refactoring effort as part of the continuous improvement of Expertiza, students get an opportunity to work on a open source software project. This helps them gain exposure on the technologies used in the project as well as much needed experience in collaborating with peers as part of the software development process. This effort was undertaken as a final project for the CSC 517 - Object Oriented Design and Development course at North Carolina State University in the spring of 2017.

==Project Purpose==

===Requirements Statement===
Expertiza displays reviews (i) to the team who was reviewed, and (ii) to the reviewer. A student user can see all the reviews of his/her team’s project. The instructor can see all the reviews of everyone’s project. The instructor also has access to a review report, which shows, for each reviewer, all the reviews that (s)he wrote. Currently, the score report and review report use completely different code. This makes the UI non-orthogonal and also causes DRY problems. So, we would like to have a single way of displaying reviews that would be visible to students (reviews that they did, and reviews that their team received), and instructors (reviews that each time received, sorted by team; and reviews that each student did, sorted by student).

===Required Tasks===
The tasks involved as part of this requirements change are as follows:
# Compact the review display
#* Eliminate the blank lines between items within a single review. Instead vary the background color from line to line to improve readability
#* With a single click, there should be a way to hide all the reviews, reveal just the headings (as at present), or expand all the reviews
# At the top of each review, it should say
#* Who submitted the review. The instructor should see the user’s name and user-ID.
#* A student should see
#** “Reviewer #k”, where k is an integer between 1 and n, the number of reviews that have been submitted for this project
#** The version number of the review
#** The time the review was submitted
# There should be a tabbed view to switch between various review views
#* One tab has overall statistics (averages, min, max, as the present “normal” view)
#* One tab has the heat map (current “alternate” view)
#* One tab has a grid view, with no scores, but text comments in the grid squares, and then a “More” link to display the whole comment (which will require expanding the row of the grid)
#* Switching between reviews from Reviewer k and Reviewer j might also be done by clicking on different tabs. Or, it might be more convenient to keep the current score view, which lists the n reviews across the page. Then the student should be able to click on the reviewer number (the instructor would instead click on the reviewer name) and see the review done by that reviewer
# To make it easy to focus on the reviewer’s feedback, there should be a way to hide and/or gray the criteria (“questions”), so the responses stand out more clearly
# There needs to be a way to search all reviews (of a particular project, or by a particular individual) for a given text string. The user should be able to go from one instance of the text string to another by clicking down and up buttons

===Problem Statement===
In the current state, the score report for instructors and students are built differently though they display the same information using similar UI elements. The application has multiple views into the same information but the way in which those views are accessed, the code which populates them, and the layout of the screens differs unnecessarily between instructors and students and across the views themselves. This leads to redundant code in both the backend and frontend of the application. Furthermore, since the UI is not uniform between instructors and students, instructors may have difficulty assisting students in accessing their score information due to the differences which are present in the UI that leads to confusion.

Following are some of the issues with the current state UI which we seek to rectify.

====Scores Report====
[[File:Problem_Statement_Diagram_1A_-_Instructor_View_-_65.png]]

The scores report for students and instructors have very similar layouts despite being created by different controller methods and views. They both display graphs, reviews on team submissions, author feedback, and score metrics. The primary different between them is that the instructor view (shown above) displays information for all teams in a collapsible accordion widget format while the student view (shown below) display the information only for a single team. There are some further discontinuities between the two UIs. For example, the student cannot access the heatgrid view from within the scores report page. This view is only accessible from the assignment page for students. For instructors there are two ways to access the heatgrid view from a single page. The 'Alternate View' link is adjacent to the team name on the heading bar and there is also a link inexplicably placed beneath the 'Final Score' field.

[[File:Problem_Statement_Diagram_1B_-_Student_View_-_65.png]]

====Author Feedback====
Author feedback takes two different forms when being shown to instructors but only one form for students. Both students and instructors have access to the author feedback format shown on the left in the student view. This format is identical to the format of the review scores and is displayed on the scores report for both instructor and student. The format on the right is shown on the heatgrid view yet it is only available to instructors. The information conveyed by these two formats is nearly identical and not uniformly available to all consumers of this information.

[[File:Problem_Statement_Diagram_2_-_Author_Feedback_-_65.png]]

====Graphs and Charts====
The scores report view has a bar of graphs and charts at the top of the page for both students and instructors. Both views shown below use a donut chart and bar graphs though their method of display is not uniform. The instructor view has titles beneath each item but the student view does not. The 'Submitted work' and 'Author Feedback' titles shown, despite being beneath the bar graphs, are actually headings for the metrics which are displayed beneath the graphs. Also, the graphs contain two labels on the y-axis: the maximum score and the average score. The graphs are so compact that the values on the axis overlap and make them illegible.

[[File:Problem_Statement_Diagram_3_-_Squashed_Graphs_-_65.png]]

==Project Design==

===High Level Design===

====Design Overview====
The project requirements state that we need to create a standard UI for accessing and consuming review and score information. The emphasis will be on smart and purposeful code reuse as well as ease of navigation to access information. To achieve these results we will redesign the scores report to work for both instructors and students alike. There will be a single route, a single controller method, and a single view that is common t users of both role types. In some instances, such as with the graphs and charts, the data will be different enough to warrant separate methods to retrieve the values needed. In most instances, the data is identical and will be accessed identically.

We will create a standard hierarchy which works for both students (who only need to see a single team's scores) and instructors (who need to see all teams' scores). This hierarchy will be rendered within a page in the form of a set of tabbed panes which contain the contents. We will separate the information among four tabs.

# Reviews
# Author Feedback
# Statistics
# Heat Grid

Putting these components on different tabs will allow us to de-clutter the UI. The instructor scores report UI has multiple ways to expand and collapse sections of information, links are placed in some unusual places, and the page can get so cluttered that it is difficult to distinguish one thing from another. This will be cleaned up by removing some links, removing the author feedback and the charts, and placing the reviews and scores into more discernible sections. The graphs and charts will be on their own tab so they can be larger and easier to read. Since they are not confined to a single bar of a fixed height new graphs and charts can be added. The heat grid will no longer be coupled with the author feedback and there will be a standard author feedback view which encompasses all information needs. Each of these tabs will be rendered using their own partial.

To prevent the application from pulling data for tabs which the user will not view, AJAX calls will be used to access the data on demand without reloading the page. These calls can also be expanded to request data for individual sections. Routes will be created to controller methods specifically to pull the data for each tab so that calls can be made to them to generate the necessary data structures. These will be accessed when a user expands a group or switches tabs.

====Technologies Used====

{| class="wikitable"
|-
! Technology
! Technology Type
! Use(s)
|-
| Ruby
| Language
| Core development of the application's backend system
|-
| Rails
| Framework
| Implements MVC; CRUD support; Web application support
|-
| RSpec (rspec)
| Gem
| Enables TDD; supports testing DSL
|-
| JQuery (jquery.ui.tabs)
| Library
| Enables creation of tabbed Web interfaces
|-
| JQuery (jquery.ui.accordion)
| Library
| Enables creation of accordion widgets for Web interfaces
|-
| Sass (sass-rails)
| Gem
| Sass style sheet pre-processor engine
|-
| Cascading Style Sheets (CSS)
| Language
| Web page presentation description language
|-
| Sassy CSS (SCSS)
| Language
| Superset of CSS style sheet language
|-
| rails-ajax
| Gem
| Enable AJAX to refresh containers within views without reloading the page
|}

====Software Patterns====

'''Model-View-Controller (MVC)''' - MVC is a software architectural pattern which divides an application into three parts which separate the data representation from the interface through which users will access and operate on the data. We will use this pattern to logically segregate our interface from the business logic implementation. The main components of this pattern are the:
* Model - The underlying logical structure of the application's data along with the accesses and operators on the data in the persistent storage medium.
* View - The user facing representation of the data along with the means for the user to request, operate on, or view the data.
* Controller - The intermediary layer between the Model and the View which accepts requests from the View, translates that to the Model, receives the Model's response and formats the response to the View.

'''Active Record''' - A software architectural pattern which wraps data from persistent storage, along with the method to operate on the data, in a class or object of a class to be used within an application. It uses the object-relation mapping (ORM) technique to create virtual database objects. We will use this pattern to access the persistent storage in a standard way and to generate object representations of the records.

'''Factory Method''' - A creational software design pattern which allows a class to instantiate objects but defer the creation to subclasses of the parent class. We will use this pattern in various places to generate objects for either students or instructors based on the user's role at the time of instantiation. This will allow us to have a single class to interact with from the controller and views but remain flexible enough to accommodate the needs of the different user types.

===Low Level Design===

====Screen Mockups====

'''New Scores Report With Multiple Teams and Collapsed Reviews'''

[[File:Expanded_Teams_With_Collapsed_Tabs_-_35.png]]

'''New Scores Report With Multiple Teams and Expanded Reviews'''

[[File:Expanded_Teams_With_Expanded_Tabs_-_35.png]]

====Code Change Specifics====

====Class Diagram====

====Files Changed====

{| class="wikitable"
|-
! File
! Changes
|-
| grades_controller.rb
| Add extra methods for filters of student names, team names, or assignment titles. Edit the index and show methods to support new tabs and expansion areas in the display.
|-
| view_my_scores.html.erb
| Edit arguments passed and linkage to the new display tabs.
|-
| _summary_reviews.html.erb
| Add more expansion areas to the display to organize the reviews.
|-
| _reviewTabs.html.erb
| Add new display tabs by building on the current test suite in this file.
|-
| _searchbox.html.erb
| Edit linkage to point to the new search method in grades_controller.rb
|}

==Test Plan==
For testing, we built off the existing test framework which implemented RSPEC. The goal of our testing is to verify that the existing functionality is still present in the new views and is accessible to both the student and the instructor. Below are the tests that have been modified or created to verify the changed functionality. Any other tests not listed below are assumed to be unmodified and are intended to still work with the new updates. Note that some requirements of this project cannot be verified with the script such as formatting changes, but any functional modifications to the layout will be verified.

{| class="wikitable"
! colspan="2" | Test Case 1
|-
! Test Type
| Functional
|-
! Scenario
| Test to see if modifications to the display_as_html function in response.rb order to hide the “feedback review” button is correct for a student
|-
! Pre-Conditions
|
Make sure student to test with has the following:
#Has one course assigned
#Has one assigned as part of that course
#Has more than one review for that assignment
|-
! Description
|
#Login to the site as a student
#Click on "Assignments" on the top menu
#Select an assignment from the list
#On the "Submit or Review work for Expertiza" screen, click on "Your scores”
#On the "Summary Report for assignment" screen, verify that the "Give feedback for Review 1" button is not present
|-
| colspan="2" |  
|-
! colspan="2" | Test Case 2
|-
! Test Type
| Functional
|-
! Scenario
| Test to see if modifications to the display_as_html function in response.rb order to show the “feedback review” button is correct for a student
|-
! Pre-Conditions
|
Make sure student to test with has the following:
#Has one course assigned
#Has one assigned as part of that course
#Has more than one review for that assignment
|-
! Description
|
#Login to the site as a student
#Click on "Assignments" on the top menu
#Select an assignment from the list
#On the "Submit or Review work for Expertiza" screen, click on "Your scores”
#On the “Summary Report for assignment” screen, select the “Show Review” button
#On the "Summary Report for assignment" screen, verify that the "Give feedback for Review 1" button is present
|-
| colspan="2" |  
|-
! colspan="2" | Test Case 3
|-
! Test Type
| Functional
|-
! Scenario
| Test to see if modifications to the display_as_html function in response.rb order to hide the “feedback review” button is correct for an instructor
|-
! Pre-Conditions
|
Make sure student to test with has the following:
#At least one assignment exists
#Has more than one review for that assignment
|-
! Description
|
#Login to the site as an instructor
#Click on "Manage" on the top menu
#Click on “Assignments”
#Select an assignment from the list
#Click on "View Scores”
#On the "Summary Report for assignment" screen, verify that the "Give feedback for Review 1" button is not present
|-
| colspan="2" |  
|-
! colspan="2" | Test Case 4
|-
! Test Type
| Functional
|-
! Scenario
| Test to see if modifications to the display_as_html function in response.rb order to show the “feedback review” button is correct for an instructor
|-
! Pre-Conditions
|
Make sure student to test with has the following:
#At least one assignment exists
#Has more than one review for that assignment
|-
! Description
|
#Login to the site as an instructor
#Click on "Manage" on the top menu
#Click on “Assignments”
#Select an assignment from the list
#Click on "View Scores”
#On the “Summary Report for assignment” screen, select the “Show Review” button
#On the "Summary Report for assignment" screen, verify that the "Give feedback for Review 1" button is present
|-
| colspan="2" |  

CSC/ECE 517 Spring 2017 E1711

2017-03-25T07:50:31Z

Ahasket:

E1711. Refactor delayed_mailer.rb and scheduled_task.rb

__TOC__

=Overview=

==Introduction to Expertiza==

[http://expertiza.ncsu.edu/ Expertiza] is a web based tool that allows instructors to create collaborative assignments where students can provide peer feedback on each others work. It provides instructors a system to manage assignments and different courses.

==Scope of project E1711==

The goal of E1711 was to refactor code found in the files delayed_mailer.rb and scheduled_task.rb.

The following issues were identified as the scope of this project:

:::* scheduled_task.rb duplicated most of its code from delayed_mailer.rb. Our objective is to reduce/remove the duplication in keeping with the DRY principle.
:::* The <code>perform</code> method uses a giant case statement, instead we were to incorporate the use of polymorphism
:::* The <code>mail_signed_up_users</code> is long and should be broken into smaller and better named methods
:::* Add/modify test cases as we added/removed/modified areas of the code

Information about the assignment can be found on [https://docs.google.com/document/d/17f8WVW7i-S5i0HEc__33lDQYRu9RxD7HQndSumQ_-JA/edit#heading=h.kq28lsw1uwf4 this document]

==Test Plan==

As this was a purely refactoring effort, our testing consisted of confirming existing tests did not break, modifying existing tests to match our changes, or adding tests as needed. The below sections will cover each objective in detail and will include information on how testing was done for each of those changes. See each of the Our Testing sections.

=Remove duplicated code between ''delayed_mailer.rb'' and ''scheduled_task.rb''=

===Background of Objective===

The main objective of this task was to reduce duplicated code as recommended by DRY principle.

After a deep investigation into understanding why the same code would appear in two separate files, we concluded that the authors of scheduled_task.rb found that delayed_mailer.rb already integrated with a Ruby gem called [https://rubygems.org/gems/delayed_job/versions/4.1.2 delayed_job]. delayed_job is used to run tasks asynchronously in the background. It was used in delayed_mailer to add an outgoing email to a queue to send out in the future. Instead of recreating similar infrastructure, the authors copied over the file to a different location, added on the new desired functionality, and renamed it. The authors also pointed all existing code to use scheduled_task.rb instead of delayed_mailer.rb

===Our Changes===

We found that the vast majority of the code in both the files applied to sending emails so we decided to merge the scheduled_task.rb into delayed_mailer.rb by porting the enhancements made for the scheduled tasks into delayed_mailer.rb. Doing so allowed us to meet the objective of DRYing out the code. However, we still have a situation where scheduled tasks feature has code in a section devoted to mailer code. We recommend that a future project take up the needed changes to pull out the scheduled task code out of the mailer file and make it a standalone feature as it should have been originally. See details in the Future Refactoring Opportunities below.

===Existing Tests===

We did not find any existing automated testing targeting this area of the code. All existing tests in the <code>spec</code> file associated with this feature were copies of the tests in the delayed mailer feature and did not exercise any of the new code that was introduced with adding the new types of scheduled tasks.

===Our Testing===

We went back to the demonstration of this feature and manually tested all the same scenarios. We verified that no functionality presented in the scheduled tasks demonstration was broken. Tests were added for the delayed mailer feature (covered in more details in the following sections). We recommend tests focused towards scheduled tasks are added once the scheduled tasks code is removed from the delayed mailer file back into an independent file.

=Refactor the <code>perform</code> mehtod=

===Background of Objective===

The objective of this task was to clean up this method. It was identified as being badly named, long, and not taking advantage of good design. It is essentially a giant case statement where one of the variables passed into the <code>DelayedMailer</code> constructor determines the people who receives the email.. Some suggested ways to refactor this function was first rename the <code>perform</code> to better describe what it does and to use polymorphism in place of the case statement. The original thought was that polymorphism could be used to determine what was sent out in each email based on the type of the email.

===Our Changes===

The first item we looked at was to rename the method. A generic name such as <code>perform</code> usually means that the method is doing too much or does not have a clear objective. Unfortunately, we found we could not rename the method because the delayed_job gem requires a method named <code>perform</code> in order to work on a custom job. See documentation [http://www.rubydoc.info/gems/delayed_job/4.1.2 here]

The second part of the planned refactoring was to use polymorphism to determine the content of the email. After simplifying much of the code in the file, we discovered that the content of the email was independent of the variables used to initialize the object. At that point, we weighed the complexity of new code to use polymorphism versus a significantly more simplified case statement, and because of the lack of existing tests, decided that the simplified case statement was not only short, it is also very simple to follow the flow through the code. We instead focused on DRYing out this code as a better return on immediate investment as opposed to adding polymorphism.

===Existing Tests===

There were six existing Rspec tests for delayed_mailer.rb, but the existing tests only verify that a new delayed job was added to the queue based on the type of deadline specified when creating a new <code>DelayedMalier</code>. We deemed the existing testing as adequate for this section of the file as the <code>perform</code> method calls other methods to find the email addresses and send the email.

===Our Testing===

We did not change existing testing for the <code>perform</code> method as the existing testing verified that a job to send out emails was added to the queue. We did, however, verify that our code changes did not break this portion of the code by continuously running the existing test cases.

=Refactor <code>mail_signed_up_users</code> method=

===Background of Objective===

The primary objective of this task was that the method is long and could be broken into smaller appropriately named methods.

===Our Changes===

We replaced the existing single method <code>mail_signed_up_users</code> with a shorter version and a new method <code>find_team_members_email_for_all_topics</code>. We also heavily modified (including renaming) the existing method <code>getTeamMembersMail</code>, and it is now called <code>find_team_members_email</code>. As the naming of the methods suggest, there are still opportunities for DRYing the two functions to get team member emails, but exiting code makes it extremely difficult to combine the two functions exactly though they are extremely similar at first glance. Merging the two would require refactoring areas outside the scope of this assignment and a whole new set of test cases to verify a lot of basic functionality is not broken in the process. We recommend this is taken up as a part of a future assignment. See Future Refactoring Opportunities below.

===Existing Tests===

We did not find any existing automated testing targeting this area of the code. None of the six existing tests verified if the emails are being retrieved from the database so changes in the database schema would break the feature.

=== Our Testing===

We added test cases for each of the methods we changed. There are now 10 test cases that are covering this file. The four new test cases focus on verifying that the functions can access the database to protect against schema changes and making sure the right methods are called. Tests were not added for code that was not within the scope of this assignment but we recommend the remainder of the functions also get similar test cases. See details in Future Refactoring Opportunities below.

=Future Refactoring Opportunities=

Once we started to refactor the code, we found many additional opportunities to refactor the files that was beyond the planned scope. We note down some of the opportunities here and leave it to future projects to address.

1. Scheduled Task feature does not belong in the mailers. It needs to be a standalone file with new tests added.

2. There are still methods that look like they should be collapsed into one function and opportunities for DRYing out code once other tightly coupled methods are also refactored.

3. There were practically no tests for this area of the code. We added tests for what we modified but much code still remains that is not being tested.

4. There are many calls to the database for the same information in different methods. These repeated calls could probably be reduced to one call and save the result from the database.

=Extra Credit=

During our testing, we found that the "create new late policy" function was broken. It was throwing a ActiveModel::ForbiddenAttributesError on LatePoliciesController#create, as seen below:

[[File:Late_Policy_Ruby_Error.jpg|frame|center]]

To find this, we had to add the following code to the private section of late_policies_controller.rb:

def late_policy
params.require(:late_policy).permit(:policy_name, :penalty_per_unit, :penalty_unit, :max_penalty)
end

and change the argument in the LatePolicy.new() to just

@late_policy = LatePolicy.new(late_policy)

After these two small changes, we were able to create new late policies from the UI.

File:Late Policy Ruby Error.jpg

2017-03-25T07:42:35Z

Ahasket: uploaded a new version of "File:Late Policy Ruby Error.jpg"

File:Late Policy Ruby Error.jpg

2017-03-25T07:33:41Z

Ahasket: