Expertiza_Wiki - User contributions [en]

E1735. UI changes for review and score reports

2017-05-09T04:17:27Z

Mamoran:

==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. 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===
# There should be a tabbed view to switch between the various review views.
#* Tab 1: Reviews
#* Tab 2: Author Feedback
#* Tab 3: Statistics
#* Tab 4: Heat grid
# There should be a way to gray out/hide the criteria (i.e. questions) so that the responses stand out more clearly.
# There should be a way to search all reviews of particular view which contain a given text string.
# Whitespace should be reduced on the review headings by including the review number, review round, and last reviewed time on a single line (left, center, and right justified respectively).
# The "Give feedback for Review #" link should not be visible unless the reivew has been expanded
# The "Give feedback for Review #" link should be at the top and bottom of the review after the review has been expanded.
# There should be a separate "Show all reviews" link for each round instead of having a single "Show all reviews" link.
# There should not be so much space between Round 2 and the Reputation.
# The unnecessary whitespace between the checkbox questions should be removed.
# The project should focus on the reduction of redundant code within views, controllers, and models where applicable

===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====
The following diagram shows what classes and their methods will be modified 
[[File:E1735._UI_changes_for_review_and_score_reports_-_Page_1.jpeg]]

====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
|-
| _reviews.html.erb
| Updates for displaying the new header styles, feedback text. Remove spacing fixes.
|}

==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" |  

==Future Changes and Improvements==
The goal of this project was to standardize the student and instructor scores report views into a single view and have it display the information appropriately. Due to time constraints we were unable to complete the merge of the student scores report into our newly created tabbed interface. Currently, only the instructors scores report view (grades/view) has the tabbed interface. Below are some suggestion on how to complete the functionality and to further improve it.

===Consolidate Student and Instructor Views===
The student scores report (grades/view_my_scores) contains much the same information as the instructors scores report (grades/view). Further, the information is displayed nearly identically and there is a lot of overlap in the code which renders the various pieces of information such as the code to build the reviews list, the author feedback list, and the heat grids. Our suggestion is to complete analysis of the view_my_scores and view methods within the grades_controller.rb file as well as on the view_my_scores.html.erb and view.html.erb files to determine how to standardize the structuring of the information so that a single view can render the page for both students and instructors.

Students will see information pertaining to their team and to themselves (as a participant) whereas instructors see similar information pertaining to all teams and all participants. We suspect that the student report is simply a subset of the instructor's view which lists only a single team and only a single participant on that team. The user role can be used within the controller to determine whether to pull all information or only a subset of the information into the data structures which are used by the view and partials. In the case of a student, the overall class statistics can be excluded from rendering on the page. The student's team can remain in a collapsible table row with the team name, average, and range on it, the only difference would be that there is only one team on the page. Within the tabs, the reviews tab need not change since they refer to the team as a whole. On the Author Feedback, Metareviews, and Heat Grid tabs, the information should be specific only for the student (i.e. the student should be the only participant listed). The Teammate Reviews tab will display nothing as student's should not be able to see their feedback and scores.

===Distribute Heat Grids to Related Tabs===
The heat grids are simply a way of quickly visualizing the scores for the various questions on a rubric. There are heat grids for submission reviews, author feedback, metareviews, and teammate reviews. All of these heat grids are displayed on view together (grades/view_team) for each participant. Some things which are important to note are that the submission reviews heatgrid is identical for all participants on a team together since the submission review scores apply to all of them as a team. Also, if there are no teammate reviews, metareviews, or author feedbacks available for the participant then those heat grids are not displayed.

Currently, in the instructors view, the heat grids are linked for each participant on the team on the Heat Grid tab. Our intention was to render the submission reviews heat grid within this tab as its own partial and then render the participant specific heat grids in collapsible table rows for each participant on the team. We suggest that a better option would be to get rid of the heat grid view (grades/view_team) and the Heat Grid tab and instead render the heat grids in the remaining tabs with their related information. For example, the submission reviews heat grid can be rendered at the top of the Reviews tab and the Author Feedback heat grids can be rendered for each participant within the collapsible table row for that participant. This would cut down on the code necessary to display this information and also it would group information by its supporting data rather than by the method in which it is rendered.

===Build Heat Grids Using Already Available Data===
This suggestion relates directly with the previous suggestion of taking the heat grids from their own view and instead rendering them within the tabbed interface. One of the problems with the instructor's scores report view is that it takes a long time to pull back all of the data for every team and participant for an assignment. We would like to cut back on that if possible, but the minimum we should do is avoid adding to it. We had originally planned on rendering the heat grids in the tabbed interface. To avoid additional overhead on the backend we were attempting to call the view_team method of the grades_controller.rb file using AJAX to pull back the custom VmQuestionResponse object for the teams and participants.

VmQuestionResponse is a custom object created by the team which created the heat grid view. It is useful in that all of the data necessary to build all of the heat grids for a participant is available in a single object. Unfortunately, there are several inefficiencies that come into play once we begin rendering the heat grids directly in the score report. First, the submission reviews heat grid is the same for all participants, but the method call would have to be done for every participant on the team so each of them would pull back their own copy of the submission reviews data. Also, the information used to build the heat grids such as rounds, questions, scores, and participants is already present within the scores report view. That same information is used to render the rounds, questions, scores, and participants across all of the various tabs. Pulling back a VmQuestionResponse might be easy, but it is unneeded overhead when the data to render all of the heat grids is already present in the page.

We suggest that the heat grids be modified to use the data which is already present in the view and remove the view_team view, method, and the VmQuestionResponse object and related code.

===Rendering Team Charts and Graphs in Statistics Tab===
When you view the instructor's scores report you see the overall class statistics render in charts and graphs at the top of the page. When you view the student's scores report you see the team's statistics rendered as charts and graphs in the same place. In an effort to standardize the rendering of this page for both instructors and students we propose that the team's charts and graphs which would normally be rendered when hitting the student score report view (grades/view_my_scores) should be rendered on the Statistics tab for each team. That will ensure that when migrating students to this same view that their information is still available.

One of the problems with the current charts and graphs, particularly the bar graphs, is that they are rendered so small that peak and average numbers displayed on them often overlap. Having them create so small also means that it is harder to accurately visualize differences between bars. Making them larger posed a problem in the previous UI because the page was already so tall and so cluttered with information that it didn't need anything else adding to that. With the statistics now rendering on their own tab, we can easily make a call to the method to generate these graphs slightly larger to make them more readable by passing in larger dimensions.

E1735. UI changes for review and score reports

2017-04-13T04:41:31Z

Mamoran: /* Requirements Statement */

==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. 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===
# There should be a tabbed view to switch between the various review views.
#* Tab 1: Reviews
#* Tab 2: Author Feedback
#* Tab 3: Statistics
#* Tab 4: Heat grid
# There should be a way to gray out/hide the criteria (i.e. questions) so that the responses stand out more clearly.
# There should be a way to search all reviews of particular view which contain a given text string.
# Whitespace should be reduced on the review headings by including the review number, review round, and last reviewed time on a single line (left, center, and right justified respectively).
# The "Give feedback for Review #" link should not be visible unless the reivew has been expanded
# The "Give feedback for Review #" link should be at the top and bottom of the review after the review has been expanded.
# There should be a separate "Show all reviews" link for each round instead of having a single "Show all reviews" link.
# There should not be so much space between Round 2 and the Reputation.
# The unnecessary whitespace between the checkbox questions should be removed.
# The project should focus on the reduction of redundant code within views, controllers, and models where applicable

===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:40:51Z

Mamoran: /* Requirements */

==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===
# There should be a tabbed view to switch between the various review views.
#* Tab 1: Reviews
#* Tab 2: Author Feedback
#* Tab 3: Statistics
#* Tab 4: Heat grid
# There should be a way to gray out/hide the criteria (i.e. questions) so that the responses stand out more clearly.
# There should be a way to search all reviews of particular view which contain a given text string.
# Whitespace should be reduced on the review headings by including the review number, review round, and last reviewed time on a single line (left, center, and right justified respectively).
# The "Give feedback for Review #" link should not be visible unless the reivew has been expanded
# The "Give feedback for Review #" link should be at the top and bottom of the review after the review has been expanded.
# There should be a separate "Show all reviews" link for each round instead of having a single "Show all reviews" link.
# There should not be so much space between Round 2 and the Reputation.
# The unnecessary whitespace between the checkbox questions should be removed.
# The project should focus on the reduction of redundant code within views, controllers, and models where applicable

===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:39:17Z

Mamoran: /* Project Purpose */

==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).

===Requirements===
# There should be a tabbed view to switch between the various review views.
#* Tab 1: Reviews
#* Tab 2: Author Feedback
#* Tab 3: Statistics
#* Tab 4: Heat grid
# There should be a way to gray out/hide the criteria (i.e. questions) so that the responses stand out more clearly.
# There should be a way to search all reviews of particular view which contain a given text string.
# Whitespace should be reduced on the review headings by including the review number, review round, and last reviewed time on a single line (left, center, and right justified respectively).
# The "Give feedback for Review #" link should not be visible unless the reivew has been expanded
# The "Give feedback for Review #" link should be at the top and bottom of the review after the review has been expanded.
# There should be a separate "Show all reviews" link for each round instead of having a single "Show all reviews" link.
# There should not be so much space between Round 2 and the Reputation.
# The unnecessary whitespace between the checkbox questions should be removed.
# The project should focus on the reduction of redundant code within views, controllers, and models where applicable

===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:38:47Z

Mamoran: /* Requirements */

==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).

===Requirements===
# There should be a tabbed view to switch between the various review views.
#* Tab 1: Reviews
#* Tab 2: Author Feedback
#* Tab 3: Statistics
#* Tab 4: Heat grid
# There should be a way to gray out/hide the criteria (i.e. questions) so that the responses stand out more clearly.
# There should be a way to search all reviews of particular view which contain a given text string.
# Whitespace should be reduced on the review headings by including the review number, review round, and last reviewed time on a single line (left, center, and right justified respectively).
# The "Give feedback for Review #" link should not be visible unless the reivew has been expanded
# The "Give feedback for Review #" link should be at the top and bottom of the review after the review has been expanded.
# There should be a separate "Show all reviews" link for each round instead of having a single "Show all reviews" link.
# There should not be so much space between Round 2 and the Reputation.
# The unnecessary whitespace between the checkbox questions should be removed.
# The project should focus on the reduction of redundant code within views, controllers, and models where applicable

===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:37:49Z

Mamoran: /* Required Tasks */

==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).

===Requirements===
# There should be a tabbed view to switch between the various review views.
#* Tab 1: Reviews
#* Tab 2: Author Feedback
#* Tab 3: Statistics
#* Tab 4: Heat grid
# There should be a way to gray out/hide the criteria (i.e. questions) so that the responses stand out more clearly.
# There should be a way to search all reviews of particular view which contain a given text string.
# Whitespace should be reduced on the review headings by including the review number, review round, and last reviewed time on a single line (left, center, and right justified respectively).
# The "Give feedback for Review #" link should not be visible unless the reivew has been expanded
# The "Give feedback for Review #" link should be at the top and bottom of the review after the review has been expanded.
# There should be a separate "Show all reviews" link for each round instead of having a single "Show all reviews" link.
# There should not be so much space between Round 2 and the Reputation.
# The unnecessary whitespace between the checkbox questions should be removed.

===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:09:00Z

Mamoran: /* Project 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====

==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:08:33Z

Mamoran: /* High 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====

==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:03:48Z

Mamoran:

==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====

==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-13T03:51:34Z

Mamoran:

File:Expanded Teams With Expanded Tabs - 35.png

2017-04-13T03:50:32Z

Mamoran:

File:Expanded Teams With Collapsed Tabs - 35.png

2017-04-13T03:50:15Z

Mamoran:

E1735. UI changes for review and score reports

2017-04-13T03:41:57Z

Mamoran:

File:Expanded Teams With Collapsed Tabs - 45.png

2017-04-13T03:40:47Z

Mamoran:

E1735. UI changes for review and score reports

2017-04-13T03:39:05Z

Mamoran:

File:Expanded Teams With Expanded Tabs - 85.png

2017-04-13T03:35:29Z

Mamoran:

File:Expanded Teams With Collapsed Tabs - 85.png

2017-04-13T03:34:59Z

Mamoran:

E1735. UI changes for review and score reports

2017-04-13T00:18:51Z

Mamoran:

E1735. UI changes for review and score reports

2017-04-12T03:21:20Z

Mamoran:

E1735. UI changes for review and score reports

2017-04-12T03:05:12Z

Mamoran:

E1735. UI changes for review and score reports

2017-04-12T02:07:07Z

Mamoran:

E1735. UI changes for review and score reports

2017-04-12T02:04:43Z

Mamoran:

E1735. UI changes for review and score reports

2017-04-12T02:04:09Z

Mamoran:

E1735. UI changes for review and score reports

2017-04-08T02:22:56Z

Mamoran:

E1735. UI changes for review and score reports

2017-04-08T01:58:27Z

Mamoran:

E1735. UI changes for review and score reports

2017-04-08T01:20:06Z

Mamoran:

File:Problem Statement Diagram 3 - Squashed Graphs - 65.png

2017-04-08T01:16:38Z

Mamoran:

File:Problem Statement Diagram 2 - Author Feedback - 65.png

2017-04-08T01:16:26Z

Mamoran:

File:Problem Statement Diagram 1B - Student View - 65.png

2017-04-08T01:16:10Z

Mamoran:

File:Problem Statement Diagram 1A - Instructor View - 65.png

2017-04-08T01:15:54Z

Mamoran:

File:Problem Statement Diagram 3 - Squashed Graphs.png

2017-04-08T01:00:22Z

Mamoran:

File:Problem Statement Diagram 2 - Author Feedback.png

2017-04-08T01:00:12Z

Mamoran:

File:Problem Statement Diagram 1B - Student View.png

2017-04-08T00:59:52Z

Mamoran:

File:Problem Statement Diagram 1A - Instructor View.png

2017-04-08T00:58:46Z

Mamoran:

E1735. UI changes for review and score reports

2017-04-08T00:08:22Z

Mamoran:

E1735. UI changes for review and score reports

2017-04-06T23:34:21Z

Mamoran:

CSC/ECE 517 Spring 2017/oss E1713

2017-04-01T07:19:45Z

Mamoran:

E1713. Refactor penalty_helper.rb and late_policies_controller.rb 
This project is intended to improve the code quality and reduce technical debt within the Expertiza system by refactoring the penalty_helper.rb module, refactoring the late_policies_controller.rb controller, and adding test coverage for both files.

==Introduction==

===Expertiza===
Expertiza is an open source web application which allows an instructor to manage assignments. It has various features viz. creating new assignments, customizing existing assignments, automatically allocating submissions for peer review etc. It has been developed using the [https://en.wikipedia.org/wiki/Ruby_on_Rails Ruby on Rails] framework, and the code is available on [https://www.github.com/expertiza/expertiza Github].

===Project Goals===
In this project, the files [https://github.com/expertiza/expertiza/blob/master/app/controllers/late_policies_controller.rb late_policies_controller.rb] and [https://github.com/expertiza/expertiza/blob/master/app/helpers/penalty_helper.rb penalty_helper.rb] were to be refactored. The methods contained in these files were too long, and needed to be either shortened, or used polymorphically, or deleted altogether if they were not being used. They also were to be refactored semantically if the code did not follow good Ruby coding practices.

==Functionality==

===Late policies and penalties functionality===
After an instructor creates an assignment in Expertiza they will have the ability to edit the details of the assignment by clicking the Edit action icon beside the assignment. From the "Editing Assignment" screen instructors have the ability to set due dates for each round of an assignment on the "Due dates" tab. On this tab, the instructor can elect to apply a late policy to the assignment by checking the "Apply penalty policy" checkbox and selecting a late policy from the adjacent drop down menu. If no late policies exist, or if the instructor wishes to define a new late policy, then they can click the "New late policy" link to define a new late policy.

An instructor can define a late policy with the following fields:

* Late policy name - This name will show up in the drop down menu on the "Due dates" tab when editing the assignment. It is not enforced to be unique.
* Penalty Unit - With the options of 'Minute', 'Hour', and 'Day' this field will define the frequency with which penalty points are deducted if an assignment is submitted after a due date.
* Penalty Point Per Unit - This is the amount of points which will be deducted from the student's score for the assignment round every time the Penalty Unit time has elapsed between the due date and the submission date. [Range: > 50]
* Maximum Penalty - Points will continue to be deducted from the assignment round score for each Penalty Unit time that has elapsed, but the number of points deducted will not exceed the Maximum Penalty [Range: 1..50]

Once an assignment has a late policy applied to an assignment, students' submissions will be checked against deadlines to determine if the late policy should be enforced. The penalty is applied to the grades under two circumstances. When a student is viewing an assignment task and they click on the "Your scores" link, the applicable penalties will be applied before displaying. Also, when an instructor is viewing the list of assignments on the "Manage content" page, if they click the icon for "View scores" the penalties will be applied to all submissions within the list which were submitted past the due date.

==Change specifics==
The penalty_helper.rb and late_policies_controller.rb files are central to the creation and maintenance of late policies. Late policies are created by instructors and associated with assignments. The late_policies_controller.rb file is primarily used in the communication with view where late policies are displayed, created, or modified. The penalty_helper.rb file includes many useful methods related to late policies and the penalties which result from their use. For instance, if an assignment is designated as having penalties calculated then when it is graded the PenaltyHelper module will allow the penalties for each assignment to be calculated and applied to the final grade for the assignment.

This effort was initiated with the intent of refactoring some longer methods with redundant subprocedures so that the overall structure of the code is cleaner, concise, and DRYer. This was achieved by performing analysis on the files to identify methods which are not used within the Expertiza code base, methods which are too long, and redundant code which can be extracted from other methods and replaced with a call to a single method.

===Late Policies Controller===
This is controller class for late policies. It handles all the basic operations on late policies like create/edit/delete policy. The project goal was to refactor the code of create and update methods to make them smaller and more readable. Three helper methods were added in the PenaltyHelper module to make the code shorter.
There was a common input check in both create and update methods which was separated to write two new methods "check_penalty_points_validity" and "check_policy_with_same_name", which helped to reuse the code.

#checking that penalty_per_unit is not exceeding max_penalty
def self.check_penalty_points_validity(max_penalty, penalty_per_unit)
if max_penalty < penalty_per_unit
flash[:error] = "The maximum penalty cannot be less than penalty per unit."
invalid_penalty_per_unit = true
else
invalid_penalty_per_unit = false
end
end

#method to check whether the policy name given as a parameter already exists under the current instructor id
#it return true if there's another policy with the same name under current instructor else false
def self.check_policy_with_same_name(late_policy_name)
@policy = LatePolicy.where(policy_name: late_policy_name)
if !@policy.nil? && !@policy.empty?
@policy.each do |p|
next unless p.instructor_id == instructor_id
return true
end
end
return false
end

In case of update action call, there was a part of code which was updating already calculated penalty objects based on the updated late policy. This part was written as a separate method in the helper class with name "update_calculated_penalty_objects".

#this method updates all the penalty objects which uses the penalty policy which is passed as a parameter
#whenever a policy is updated, all the existing penalty objects needs to be updated according to new policy
def self.update_calculated_penalty_objects(penalty_policy)
@penaltyObjs = CalculatedPenalty.all
@penaltyObjs.each do |pen|
@participant = AssignmentParticipant.find(pen.participant_id)
@assignment = @participant.assignment
next unless @assignment.late_policy_id == penalty_policy.id
@penalties = calculate_penalty(pen.participant_id)
@total_penalty = (@penalties[:submission] + @penalties[:review] + @penalties[:meta_review])
if pen.deadline_type_id.to_i == 1
{penalty_points: @penalties[:submission]}
pen.update_attribute(:penalty_points, @penalties[:submission])
elsif pen.deadline_type_id.to_i == 2
{penalty_points: @penalties[:review]}
pen.update_attribute(:penalty_points, @penalties[:review])
elsif pen.deadline_type_id.to_i == 5
{penalty_points: @penalties[:meta_review]}
pen.update_attribute(:penalty_points, @penalties[:meta_review])
end
end
end

Some variable names were changed in order to make it easier for reader to understand the meaning of code.
There was some unused commented code which was removed.

===Penalty Helper===
This is a helper class which contains methods which calculate the different penalties, and are then brought together in one Hash object. The aim was to keep the methods below 25 lines of code if possible. Out of the numerous methods in the file, there were 3 substantial methods, namely calculate_penalty, calculate_submission_penalty, and compute_penalty_on_reviews crossed the 25 line limit.

calculate_penalty is the main method of the PenaltyHelper module. It is called from the [https://github.com/expertiza/expertiza/blob/master/app/controllers/grades_controller.rb GradesController] module. The other methods are called from within the calculate_penalty module. The method mainly contains a few assignment statements, and some method calls. There was no scope for it to be shortened further without risking non-operation of some functionalities.

A particular segment of code converted a time difference into respective unit. This code was inserted into a method with the parameter 'time_difference'. The conversion segment was called in calculate_submission_penalty, as well as compute_penalty_on_reviews. Inserting the conversion logic into a separate method allowed the simplification of both methods.

def self.calculate_penalty_units(time_difference, penalty_unit)
if penalty_unit == 'Minute'
penalty_units = time_difference / 60
elsif penalty_unit == 'Hour'
penalty_units = time_difference / 3600
elsif penalty_unit == 'Day'
penalty_units = time_difference / 86_400
end
end

The method was called in two places.

# Line 44
time_difference = last_submission_time - submission_due_date
penalty_units = calculate_penalty_units(time_difference, @penalty_unit)

# Line 109
time_difference = review_map_created_at_list.at(i) - review_due_date
penalty_units = calculate_penalty_units(time_difference, @penalty_unit)

Apart from the method which was defined, some other methods which were not being called were removed, extraneous statements which were written and then commented were also removed. Also, minor modifications in places where code did not follow Ruby grammar were made, for eg: a space was added between 'if' and the condition statement.

==Test plan==
The project formerly had no tests associated with these source files. Our refactoring added moved functionality out of the controller and into the helper module, therefore our testing focused on validating the helper methods in penalty_helper.rb.

====Unit tests====
{| class="wikitable"
! colspan="4" | Unit Test Summary
|-
! Method
! Parameters
! Purpose
! Tested Scenarios
|-
| check_policy_with_same_name
| late_policy_name; instructor_id
| Check whether a given late policy name exists for the current instructor.
| 1) Returns true when passed an existing policy name; 2) Returns false when passed a non-existant policy name
|-
| check_penalty_points_validity
| max_penalty; penalty_per_unit
| Validate that the max penalty and penalty points per unit provided by the user allow at least one unit to pass before reaching the max.
| 1) Returns true (indicating invalid values) when the penalty points per unit > max penalty; 2) Returns false (indicating valid values) when the penalty points per unit < max penalty; 3) Returns false (indicating valid values) when the penalty points per unit == max penalty
|-
| calculate_penalty_units
| time_difference; penalty_unit
| Convert a time difference, given in seconds, into the requested penalty unit (i.e. Minutes, Hours, or Days).
| 1) Returns 1 minute when passed a time difference of 1 minute; 2) Returns 1 hour when passed a time difference of 1 hour; 3) Returns 1 day when passed a time difference of 1 day;
|-
|}

==Peer review validation==

===Validating application functionality===
Instructions on how our reviewers should validate the impacted functionality to ensure that it still works.

===Validating code via RSpec tests===

====Setup Expertiza VCL environment====
First, setup your Expertiza environment. Navigate to https://vcl.ncsu.edu and click the "Make a Reservation" button. Sign in with your Unity ID. Click the "Reservations" button and then click "New Reservation". In the environment drop down box select the ' [CSC517, F15] Ruby on Rails / Expertiza' environment, set your session duration, and click the "Create Reservation" button.

One your reservation is ready you should see a Connect! button. Click it and copy the IP address. If you don't have PuTTY then download it. Open PuTTY and paste the IP address in the hostname field and click "Open." Confirm connection at the security dialog. Log into the server using your Unity ID and password. Once logged in, execute the following commands to setup the Expertiza environment.

git clone https://github.com/michaelamoran/expertiza.git
cd expertiza
cp ./config/database.yml.example ./config/database.yml
cp ./config/secrets.yml.example ./config/secrets.yml
vi ./Gemfile
# Search for 'pg' and delete the line and save
bundle install
rake db:migrate
curl https://raw.githubusercontent.com/creationix/nvm/v0.13.1/install.sh | bash
source ~/.bash_profile
nvm install v7.7.3
npm install -g bower
bower install

# The following commands will prepare the test database so the tests don't fail.
rake db:create RAILS_ENV=test
rake db:migrate RAILS_ENV=test

====Executing tests====

Now, to run the tests, make sure you are in the project's root directory (i.e. ~/expertiza/). Run the following command:

rspec spec/helpers/penalty_helper_spec.rb

Once it is complete, the output should contain the number of test cases and how man of them passed or failed.

CSC/ECE 517 Spring 2017/oss E1713

2017-04-01T06:57:50Z

Mamoran:

E1713. Refactor penalty_helper.rb and late_policies_controller.rb 
This project is intended to improve the code quality and reduce technical debt within the Expertiza system by refactoring the penalty_helper.rb module, refactoring the late_policies_controller.rb controller, and adding test coverage for both files.

==Introduction==

===Expertiza===
Expertiza is an open source web application which allows an instructor to manage assignments. It has various features viz. creating new assignments, customizing existing assignments, automatically allocating submissions for peer review etc. It has been developed using the [https://en.wikipedia.org/wiki/Ruby_on_Rails Ruby on Rails] framework, and the code is available on [https://www.github.com/expertiza/expertiza Github].

===Project Goals===
In this project, the files [https://github.com/expertiza/expertiza/blob/master/app/controllers/late_policies_controller.rb late_policies_controller.rb] and [https://github.com/expertiza/expertiza/blob/master/app/helpers/penalty_helper.rb penalty_helper.rb] were to be refactored. The methods contained in these files were too long, and needed to be either shortened, or used polymorphically, or deleted altogether if they were not being used. They also were to be refactored semantically if the code did not follow good Ruby coding practices.

==Functionality==

===Late policies and penalties functionality===
After an instructor creates an assignment in Expertiza they will have the ability to edit the details of the assignment by clicking the Edit action icon beside the assignment. From the "Editing Assignment" screen instructors have the ability to set due dates for each round of an assignment on the "Due dates" tab. On this tab, the instructor can elect to apply a late policy to the assignment by checking the "Apply penalty policy" checkbox and selecting a late policy from the adjacent drop down menu. If no late policies exist, or if the instructor wishes to define a new late policy, then they can click the "New late policy" link to define a new late policy.

An instructor can define a late policy with the following fields:

* Late policy name - This name will show up in the drop down menu on the "Due dates" tab when editing the assignment. It is not enforced to be unique.
* Penalty Unit - With the options of 'Minute', 'Hour', and 'Day' this field will define the frequency with which penalty points are deducted if an assignment is submitted after a due date.
* Penalty Point Per Unit - This is the amount of points which will be deducted from the student's score for the assignment round every time the Penalty Unit time has elapsed between the due date and the submission date. [Range: > 50]
* Maximum Penalty - Points will continue to be deducted from the assignment round score for each Penalty Unit time that has elapsed, but the number of points deducted will not exceed the Maximum Penalty [Range: 1..50]

Once an assignment has a late policy applied to an assignment, students' submissions will be checked against deadlines to determine if the late policy should be enforced. The penalty is applied to the grades under two circumstances. When a student is viewing an assignment task and they click on the "Your scores" link, the applicable penalties will be applied before displaying. Also, when an instructor is viewing the list of assignments on the "Manage content" page, if they click the icon for "View scores" the penalties will be applied to all submissions within the list which were submitted past the due date.

==Change specifics==
The penalty_helper.rb and late_policies_controller.rb files are central to the creation and maintenance of late policies. Late policies are created by instructors and associated with assignments. The late_policies_controller.rb file is primarily used in the communication with view where late policies are displayed, created, or modified. The penalty_helper.rb file includes many useful methods related to late policies and the penalties which result from their use. For instance, if an assignment is designated as having penalties calculated then when it is graded the PenaltyHelper module will allow the penalties for each assignment to be calculated and applied to the final grade for the assignment.

This effort was initiated with the intent of refactoring some longer methods with redundant subprocedures so that the overall structure of the code is cleaner, concise, and DRYer. This was achieved by performing analysis on the files to identify methods which are not used within the Expertiza code base, methods which are too long, and redundant code which can be extracted from other methods and replaced with a call to a single method.

===Late Policies Controller===
This is controller class for late policies. It handles all the basic operations on late policies like create/edit/delete policy. The project goal was to refactor the code of create and update methods to make them smaller and more readable. Three helper methods were added in the PenaltyHelper module to make the code shorter.
There was a common input check in both create and update methods which was separated to write two new methods "check_penalty_points_validity" and "check_policy_with_same_name", which helped to reuse the code.

#checking that penalty_per_unit is not exceeding max_penalty
def self.check_penalty_points_validity(max_penalty, penalty_per_unit)
if max_penalty < penalty_per_unit
flash[:error] = "The maximum penalty cannot be less than penalty per unit."
invalid_penalty_per_unit = true
else
invalid_penalty_per_unit = false
end
end

#method to check whether the policy name given as a parameter already exists under the current instructor id
#it return true if there's another policy with the same name under current instructor else false
def self.check_policy_with_same_name(late_policy_name)
@policy = LatePolicy.where(policy_name: late_policy_name)
if !@policy.nil? && !@policy.empty?
@policy.each do |p|
next unless p.instructor_id == instructor_id
return true
end
end
return false
end

In case of update action call, there was a part of code which was updating already calculated penalty objects based on the updated late policy. This part was written as a separate method in the helper class with name "update_calculated_penalty_objects".

#this method updates all the penalty objects which uses the penalty policy which is passed as a parameter
#whenever a policy is updated, all the existing penalty objects needs to be updated according to new policy
def self.update_calculated_penalty_objects(penalty_policy)
@penaltyObjs = CalculatedPenalty.all
@penaltyObjs.each do |pen|
@participant = AssignmentParticipant.find(pen.participant_id)
@assignment = @participant.assignment
next unless @assignment.late_policy_id == penalty_policy.id
@penalties = calculate_penalty(pen.participant_id)
@total_penalty = (@penalties[:submission] + @penalties[:review] + @penalties[:meta_review])
if pen.deadline_type_id.to_i == 1
{penalty_points: @penalties[:submission]}
pen.update_attribute(:penalty_points, @penalties[:submission])
elsif pen.deadline_type_id.to_i == 2
{penalty_points: @penalties[:review]}
pen.update_attribute(:penalty_points, @penalties[:review])
elsif pen.deadline_type_id.to_i == 5
{penalty_points: @penalties[:meta_review]}
pen.update_attribute(:penalty_points, @penalties[:meta_review])
end
end
end

Some variable names were changed in order to make it easier for reader to understand the meaning of code.
There was some unused commented code which was removed.

===Penalty Helper===
This is a helper class which contains methods which calculate the different penalties, and are then brought together in one Hash object. The aim was to keep the methods below 25 lines of code if possible. Out of the numerous methods in the file, there were 3 substantial methods, namely calculate_penalty, calculate_submission_penalty, and compute_penalty_on_reviews crossed the 25 line limit.

calculate_penalty is the main method of the PenaltyHelper module. It is called from the [https://github.com/expertiza/expertiza/blob/master/app/controllers/grades_controller.rb GradesController] module. The other methods are called from within the calculate_penalty module. The method mainly contains a few assignment statements, and some method calls. There was no scope for it to be shortened further without risking non-operation of some functionalities.

A particular segment of code converted a time difference into respective unit. This code was inserted into a method with the parameter 'time_difference'. The conversion segment was called in calculate_submission_penalty, as well as compute_penalty_on_reviews. Inserting the conversion logic into a separate method allowed the simplification of both methods.

def self.calculate_penalty_units(time_difference, penalty_unit)
if penalty_unit == 'Minute'
penalty_units = time_difference / 60
elsif penalty_unit == 'Hour'
penalty_units = time_difference / 3600
elsif penalty_unit == 'Day'
penalty_units = time_difference / 86_400
end
end

The method was called in two places.

# Line 44
time_difference = last_submission_time - submission_due_date
penalty_units = calculate_penalty_units(time_difference, @penalty_unit)

# Line 109
time_difference = review_map_created_at_list.at(i) - review_due_date
penalty_units = calculate_penalty_units(time_difference, @penalty_unit)

Apart from the method which was defined, some other methods which were not being called were removed, extraneous statements which were written and then commented were also removed. Also, minor modifications in places where code did not follow Ruby grammar were made, for eg: a space was added between 'if' and the condition statement.

===Functional and integration testing===
Motivation behind testing including the technologies used for testing.

====penalty_helper_spec.rb====
Specific changes identified and made here, including the motivation behind making those changes.

====late_policies_controller_spec.rb====
Specific changes identified TO BE made here, including the motivation behind making those changes.

==Peer review validation==

===Validating application functionality===
Instructions on how our reviewers should validate the impacted functionality to ensure that it still works.

===Validating code via RSpec tests===

====Setup Expertiza VCL environment====
First, setup your Expertiza environment. Navigate to https://vcl.ncsu.edu and click the "Make a Reservation" button. Sign in with your Unity ID. Click the "Reservations" button and then click "New Reservation". In the environment drop down box select the ' [CSC517, F15] Ruby on Rails / Expertiza' environment, set your session duration, and click the "Create Reservation" button.

One your reservation is ready you should see a Connect! button. Click it and copy the IP address. If you don't have PuTTY then download it. Open PuTTY and paste the IP address in the hostname field and click "Open." Confirm connection at the security dialog. Log into the server using your Unity ID and password. Once logged in, execute the following commands to setup the Expertiza environment.

git clone https://github.com/michaelamoran/expertiza.git
cd expertiza
cp ./config/database.yml.example ./config/database.yml
cp ./config/secrets.yml.example ./config/secrets.yml
vi ./Gemfile
# Search for 'pg' and delete the line and save
bundle install
rake db:migrate
curl https://raw.githubusercontent.com/creationix/nvm/v0.13.1/install.sh | bash
source ~/.bash_profile
nvm install v7.7.3
npm install -g bower
bower install

# The following commands will prepare the test database so the tests don't fail.
rake db:create RAILS_ENV=test
rake db:migrate RAILS_ENV=test

====Executing tests====

Now, to run the tests, make sure you are in the project's root directory (i.e. ~/expertiza/). Run the following command:

rspec spec/helpers/penalty_helper_spec.rb

Once it is complete, the output should contain the number of test cases and how man of them passed or failed.

CSC/ECE 517 Spring 2017/oss E1713

2017-04-01T06:20:50Z

Mamoran:

E1713. Refactor penalty_helper.rb and late_policies_controller.rb 
This project is intended to improve the code quality and reduce technical debt within the Expertiza system by refactoring the penalty_helper.rb module, refactoring the late_policies_controller.rb controller, and adding test coverage for both files.

==Introduction==

===Expertiza===
Expertiza is an open source web application which allows an instructor to manage assignments. It has various features viz. creating new assignments, customizing existing assignments, automatically allocating submissions for peer review etc. It has been developed using the [https://en.wikipedia.org/wiki/Ruby_on_Rails Ruby on Rails] framework, and the code is available on [https://www.github.com/expertiza/expertiza Github].

===Project Goals===
In this project, the files [https://github.com/expertiza/expertiza/blob/master/app/controllers/late_policies_controller.rb late_policies_controller.rb] and [https://github.com/expertiza/expertiza/blob/master/app/helpers/penalty_helper.rb penalty_helper.rb] were to be refactored. The methods contained in these files were too long, and needed to be either shortened, or used polymorphically, or deleted altogether if they were not being used. They also were to be refactored semantically if the code did not follow good Ruby coding practices.

==Functionality==

===Late policies and penalties functionality===
After an instructor creates an assignment in Expertiza they will have the ability to edit the details of the assignment by clicking the Edit action icon beside the assignment. From the "Editing Assignment" screen instructors have the ability to set due dates for each round of an assignment on the "Due dates" tab. On this tab, the instructor can elect to apply a late policy to the assignment by checking the "Apply penalty policy" checkbox and selecting a late policy from the adjacent drop down menu. If no late policies exist, or if the instructor wishes to define a new late policy, then they can click the "New late policy" link to define a new late policy.

An instructor can define a late policy with the following fields:

* Late policy name - This name will show up in the drop down menu on the "Due dates" tab when editing the assignment. It is not enforced to be unique.
* Penalty Unit - With the options of 'Minute', 'Hour', and 'Day' this field will define the frequency with which penalty points are deducted if an assignment is submitted after a due date.
* Penalty Point Per Unit - This is the amount of points which will be deducted from the student's score for the assignment round every time the Penalty Unit time has elapsed between the due date and the submission date. [Range: > 50]
* Maximum Penalty - Points will continue to be deducted from the assignment round score for each Penalty Unit time that has elapsed, but the number of points deducted will not exceed the Maximum Penalty [Range: 1..50]

Once an assignment has a late policy applied

==Change specifics==
The penalty_helper.rb and late_policies_controller.rb files are central to the creation and maintenance of late policies. Late policies are created by instructors and associated with assignments. The late_policies_controller.rb file is primarily used in the communication with view where late policies are displayed, created, or modified. The penalty_helper.rb file includes many useful methods related to late policies and the penalties which result from their use. For instance, if an assignment is designated as having penalties calculated then when it is graded the PenaltyHelper module will allow the penalties for each assignment to be calculated and applied to the final grade for the assignment.

This effort was initiated with the intent of refactoring some longer methods with redundant subprocedures so that the overall structure of the code is cleaner, concise, and DRYer. This was achieved by performing analysis on the files to identify methods which are not used within the Expertiza code base, methods which are too long, and redundant code which can be extracted from other methods and replaced with a call to a single method.

===Late Policies Controller===
This is controller class for late policies. It handles all the basic operations on late policies like create/edit/delete policy. The project goal was to refactor the code of create and update methods to make them smaller and more readable. Three helper methods were added in the PenaltyHelper module to make the code shorter.
There was a common input check in both create and update methods which was separated to write two new methods "check_penalty_points_validity" and "check_policy_with_same_name", which helped to reuse the code.

#checking that penalty_per_unit is not exceeding max_penalty
def self.check_penalty_points_validity(max_penalty, penalty_per_unit)
if max_penalty < penalty_per_unit
flash[:error] = "The maximum penalty cannot be less than penalty per unit."
invalid_penalty_per_unit = true
else
invalid_penalty_per_unit = false
end
end

#method to check whether the policy name given as a parameter already exists under the current instructor id
#it return true if there's another policy with the same name under current instructor else false
def self.check_policy_with_same_name(late_policy_name)
@policy = LatePolicy.where(policy_name: late_policy_name)
if !@policy.nil? && !@policy.empty?
@policy.each do |p|
next unless p.instructor_id == instructor_id
return true
end
end
return false
end

In case of update action call, there was a part of code which was updating already calculated penalty objects based on the updated late policy. This part was written as a separate method in the helper class with name "update_calculated_penalty_objects".

#this method updates all the penalty objects which uses the penalty policy which is passed as a parameter
#whenever a policy is updated, all the existing penalty objects needs to be updated according to new policy
def self.update_calculated_penalty_objects(penalty_policy)
@penaltyObjs = CalculatedPenalty.all
@penaltyObjs.each do |pen|
@participant = AssignmentParticipant.find(pen.participant_id)
@assignment = @participant.assignment
next unless @assignment.late_policy_id == penalty_policy.id
@penalties = calculate_penalty(pen.participant_id)
@total_penalty = (@penalties[:submission] + @penalties[:review] + @penalties[:meta_review])
if pen.deadline_type_id.to_i == 1
{penalty_points: @penalties[:submission]}
pen.update_attribute(:penalty_points, @penalties[:submission])
elsif pen.deadline_type_id.to_i == 2
{penalty_points: @penalties[:review]}
pen.update_attribute(:penalty_points, @penalties[:review])
elsif pen.deadline_type_id.to_i == 5
{penalty_points: @penalties[:meta_review]}
pen.update_attribute(:penalty_points, @penalties[:meta_review])
end
end
end

Some variable names were changed in order to make it easier for reader to understand the meaning of code.
There was some unused commented code which was removed.

===Penalty Helper===
This is a helper class which contains methods which calculate the different penalties, and are then brought together in one Hash object. The aim was to keep the methods below 25 lines of code if possible. Out of the numerous methods in the file, there were 3 substantial methods, namely calculate_penalty, calculate_submission_penalty, and compute_penalty_on_reviews crossed the 25 line limit.

calculate_penalty is the main method of the PenaltyHelper module. It is called from the [https://github.com/expertiza/expertiza/blob/master/app/controllers/grades_controller.rb GradesController] module. The other methods are called from within the calculate_penalty module. The method mainly contains a few assignment statements, and some method calls. There was no scope for it to be shortened further without risking non-operation of some functionalities.

A particular segment of code converted a time difference into respective unit. This code was inserted into a method with the parameter 'time_difference'. The conversion segment was called in calculate_submission_penalty, as well as compute_penalty_on_reviews. Inserting the conversion logic into a separate method allowed the simplification of both methods.

def self.calculate_penalty_units(time_difference, penalty_unit)
if penalty_unit == 'Minute'
penalty_units = time_difference / 60
elsif penalty_unit == 'Hour'
penalty_units = time_difference / 3600
elsif penalty_unit == 'Day'
penalty_units = time_difference / 86_400
end
end

The method was called in two places.

# Line 44
time_difference = last_submission_time - submission_due_date
penalty_units = calculate_penalty_units(time_difference, @penalty_unit)

# Line 109
time_difference = review_map_created_at_list.at(i) - review_due_date
penalty_units = calculate_penalty_units(time_difference, @penalty_unit)

Apart from the method which was defined, some other methods which were not being called were removed, extraneous statements which were written and then commented were also removed. Also, minor modifications in places where code did not follow Ruby grammar were made, for eg: a space was added between 'if' and the condition statement.

===Functional and integration testing===
Motivation behind testing including the technologies used for testing.

====penalty_helper_spec.rb====
Specific changes identified and made here, including the motivation behind making those changes.

====late_policies_controller_spec.rb====
Specific changes identified TO BE made here, including the motivation behind making those changes.

==Peer review validation==

===Validating application functionality===
Instructions on how our reviewers should validate the impacted functionality to ensure that it still works.

===Validating code via RSpec tests===

====Setup Expertiza VCL environment====
First, setup your Expertiza environment. Navigate to https://vcl.ncsu.edu and click the "Make a Reservation" button. Sign in with your Unity ID. Click the "Reservations" button and then click "New Reservation". In the environment drop down box select the ' [CSC517, F15] Ruby on Rails / Expertiza' environment, set your session duration, and click the "Create Reservation" button.

One your reservation is ready you should see a Connect! button. Click it and copy the IP address. If you don't have PuTTY then download it. Open PuTTY and paste the IP address in the hostname field and click "Open." Confirm connection at the security dialog. Log into the server using your Unity ID and password. Once logged in, execute the following commands to setup the Expertiza environment.

git clone https://github.com/michaelamoran/expertiza.git
cd expertiza
cp ./config/database.yml.example ./config/database.yml
cp ./config/secrets.yml.example ./config/secrets.yml
vi ./Gemfile
# Search for 'pg' and delete the line and save
bundle install
rake db:migrate
curl https://raw.githubusercontent.com/creationix/nvm/v0.13.1/install.sh | bash
source ~/.bash_profile
nvm install v7.7.3
npm install -g bower
bower install

# The following commands will prepare the test database so the tests don't fail.
rake db:create RAILS_ENV=test
rake db:migrate RAILS_ENV=test

====Executing tests====

Now, to run the tests, make sure you are in the project's root directory (i.e. ~/expertiza/). Run the following command:

rspec spec/helpers/penalty_helper_spec.rb

Once it is complete, the output should contain the number of test cases and how man of them passed or failed.

CSC/ECE 517 Spring 2017/oss E1713

2017-03-24T02:00:22Z

Mamoran:

CSC/ECE 517 Spring 2017/oss E1713

2017-03-24T01:54:05Z

Mamoran:

CSC/ECE 517 Spring 2017/oss E1713

2017-03-24T01:50:08Z

Mamoran:

CSC/ECE 517 Spring 2017/oss E1713

2017-03-22T17:09:09Z

Mamoran: Created page with "E1713. Refactor penalty_helper.rb and late_policies_controller.rb This project is intended to improve the code quality and reduce technical debt within ..."