Scales
Scales | |
---|---|
Project state | Specification |
Tracker issue | MDL-17258, MDL-13372 |
Discussion | Improving Scales in the Gradebook |
Assignee | Evan Irving-Pease |
Executive Summary
The scales in the Gradebook should be rewritten to:
- 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).
- 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.
- 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.
- Support sort options on scale items – Currently scales must be ordered from lowest to highest, however sort options should invlude "by value" or "by name" with a direction of either ASC or DESC.
- Improve database design – At present the storage of scale items within a comma delimited text field fails first normal form.
- 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:
- Replace all direct access to the `scale` table with calls to the scales’ API, then test thoroughly to make sure nothing is broken.
- Add the `scale_items` table and drop the scale field in the `scale` table.
- 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).
- Write an upgrade script that converts old scales into the new format.
- Update the backup code to include the `scale_items` table.
- Update the scales edit/create page to include separate scale items, each with name, description, value and sortorder fields.
- Update the interface to use the `scale_items` description field, so users can see the description of each item.
- 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.
Field | Type | Default | Info |
id | int(10) | autoincrementing | |
courseid | int(10) | 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).
Field | Type | Default | Info |
id | int(10) | autoincrementing | |
courseid | int(10) | 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) | ||
sortmode | tinyint(1) | The field to use for sorting; either SORT_NAME or SORT_VALUE. | |
sortdirection | tinyint(1) | The direction of the search; either ASC or DESC | |
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. | |
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.