Scales Improvements Specifications

Overview

Scales Improvements
Project state	Specification
Tracker issue	https://tracker.moodle.org/browse/MDL-17258
Discussion	-
Assignee	HQ

Note: This page is a work-in-progress. Feedback and suggested improvements are welcome. Please join the discussion on moodle.org or use the page comments.

One of the gradebook improvements is to allow teachers to enter a grade letter and have that converted to a number (e.g. b+ => 75). The feature already exists to do the reverse (enter a number and have the student see a letter). There is significant overlap with scales - and this is really just a scale with a custom mapping of items to points.

So - this specification is a break down of the changes that would be required to improve scales so that they can support a custom mapping of items -> points.

Create a scales API

The way scales are implemented currently (Moodle 2.7) is that the activity modules each re-implement the logic of retrieving a list of scale items for a given scale and creating a menu from it. The chosen item is then pushed to the gradebook via the "grade_update" method where the grade_item in the gradebook identifies the scale in use. It would be much better if there was a single function responsible for creating a form element that represents a scale. There are other bits of scales logic hard coded in modules such as getting the min and max for a scale, converting a scale item to a points value, getting a list of scale items, getting a normalized grade from a scale item and getting the closest scale item to a value specified in points.

We should create an api for these functions under \core\grade to encapsulate all this logic.

This API needs unit tests.

Allow custom mappings of scale items -> points

An extra column will need to the added to the scales table to (optionally) store a mapping of scale items to points.

This column will need to be used when converting a raw scale item to a normalised, bounded value for the gradebook finalgrade. (see grade_item::bounded_grade).

These custom mappings need unit tests.

Changes required to modules

Modules need to replace their manual scales logic with some calls to the new scales API.

Changes required to workshop

Workshop has custom scales logic for calculating the average of several scales. This should be replaces with an API call. This logic converts scale items to a 0 based index before calculating the average - the reason for this this needs to be understood before we decide how it is to be handled.