Олег Давидович: 1 версия импортирована

2024-10-21T08:53:09Z

1 версия импортирована

← Предыдущая версия	Версия от 08:53, 21 октября 2024
(нет различий)

1>Ekirving: Minor change to sorting

2010-03-11T10:46:25Z

Minor change to sorting

Новая страница

{{Infobox Project
|name = Scales
|state = Specification
|tracker = MDL-17258, MDL-13372
|discussion = [http://moodle.org/mod/forum/discuss.php?d=140907 Improving Scales in the Gradebook]
|assignee = [[User:Evan Irving-Pease|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 [http://moodle.org/mod/forum/discuss.php?d=106031 106031], [http://moodle.org/mod/forum/discuss.php?d=120541#p532013 120541], and [http://moodle.org/mod/forum/discuss.php?d=130707 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 [http://moodle.org/mod/forum/discuss.php?d=108183 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 [http://en.wikipedia.org/wiki/First_normal_form 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.

[[Image:Gradebook-ERD-Current.png|200px|thumb|right|ERD of the Moodle 2.0 Gradebook]]

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''
|-
|'''id'''
|int(10)
|
|autoincrementing
|-
|'''courseid'''
|int(10)
|<center>0</center>
|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).

[[Image:Gradebook-ERD-Proposed.png|200px|thumb|right|ERD of the proposed changes to the Moodle 2.0 Gradebook]]

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''
|-
|'''id'''
|int(10)
|
|autoincrementing
|-
|'''courseid'''
|int(10)
|<center>0</center>
|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.

{| border="1" cellpadding="2" cellspacing="0"
|'''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 ==
* [[Development:Grades]]

Development:Scales - История изменений

Олег Давидович: 1 версия импортирована

1>Ekirving: Minor change to sorting