Scales

Moodle 2.0

There is an ongoing discussion about this spec here

Executive Summary

The scales in the Gradebook should be rewritten to:

1. Support arbitrary numeric values for scale items – The current system of converting scale items into numeric values is both confusing and unconfigurable. This is requested in MDL-17258, and discussed in numerous forum threads (see 106031, 120541, and 130707 for but a few examples).
2. Allow descriptive text to be associated with scale items – Currently you can describe the scale but not the individual items within the scale. This has been requested in MDL-13372 for usability reasons.
3. Allow commas in scale item names – Because scale items are currently delimited by commas it is not possible to have a comma in the scale item name. This has been requested for internationalisation reasons.
4. Support sortorder on scales – Currently scales must be ordered from lowest to highest, however the sort order of the scale should be up to the user.
5. Improve database design – At present the storage of scale items within a comma delimited text field fails first normal form.
6. Use a standard API – For consistency with other areas of the gradebook, accessing scales should be through a standard API. At present code directly accesses the table.

Updating Moodle code

Steps:

1. Replace all direct access to the `scale` table with calls to the scales’ API, then test thoroughly to make sure nothing is broken.
2. Add the `scale_items` table and drop the scale field in the `scale` table.
3. Update the code behind the scales’ API to use the new table (for backwards compatibility, if the value field is not defined in the `scale_items` table then the value for a scale item will calculated in the same manner as it currently is).
4. Write an upgrade script that converts old scales into the new format.
5. Update the backup code to include the `scale_items` table.
6. Update the scales edit/create page to include separate scale items, each with name, description, value and sortorder fields.
7. Update the interface to use the `scale_items` description field, so users can see the description of each item.
8. Add a new page, linked to from the scale administration page, which shows all current uses of a scale.

Current Database Structure

scale

This table currently stores both the name and description of the scale as well as all the items that comprise the scale.

ERD of the Moodle 2.0 Gradebook

Field	Type	Default	Info
id	int(10)		autoincrementing
courseid	int(10)	0	The course this scale is specific to. If not set then this scale is available site-wide.
userid	int(10)		The user who created this scale.
scale	text		The comma delimited list of scale items.
description	text		The description of the scale.
descriptionformat	tinyint(2)
timemodified	int(10)		The last time this scale was modified.

Proposed Database Structure

scale

This table stores the name and description of the scale, along with its creator and course (if set).

ERD of the proposed changes to the Moodle 2.0 Gradebook

Field	Type	Default	Info
id	int(10)		autoincrementing
courseid	int(10)	0	The course this scale is specific to. If not set then this scale is available site-wide.
userid	int(10)		The user who created this scale.
description	text		The description of the scale.
descriptionformat	tinyint(2)
timemodified	int(10)		The last time this scale was modified.

scale_items

This table stores the name and description of the scale item, along with its corresponding numeric value and sortorder.

Field	Type	Default	Info
id	int(10)		autoincrementing
scaleid	int(10)		The scale this scale item belongs to.
name	varchar(255)		The name of the scale item.
description	text		The description of the scale item.
value	float(10,5)		The value assigned to the scale item, used in aggregation methods.
sortorder	int(10)		The sortorder used for displaying the list of scale items.
timemodified	int(10)		The last time this scale item was modified.

Public API

Modules may use only functions which are marked as public.

scale_get_items()

scale_get_items($scaleid)

Returns a nested array containing the scale, along with all the scale items.

Private API

Private API is used by gradebook plugins and core Moodle code.

scale_update()

scale_update($object)

Updates, or creates if necessary, a scale; returns the scaleid.

scale_delete()

scale_delete($scaleid)

Deletes a scale and all its scale items, if not in use.

scale_in_use()

scale_in_use($scaleid)

Returns true if the scale is in use.

scale_get_usage()

scale_get_usage($scaleid)

Gets the list of all the places where a given scale is used (e.g. courses, outcomes, activities, etc).

scale_item_update()

scale_item_ update($object)

Updates, or creates if necessary, a scale item; returns the scaleitemid.

scale_item_delete()

scale_item_delete($scaleitemid)

Deletes a scale item.

scale_item_get_value()

scale_item_get_value($scaleitemid, $method)

Gets the value of a scale item, for aggregation calculations in the Gradebook.

See also

• Grades