Scales

Jump to: navigation, search
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:

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

See also