| 1 |
efrain |
1 |
<?php
|
|
|
2 |
// This file is part of Moodle - http://moodle.org/
|
|
|
3 |
//
|
|
|
4 |
// Moodle is free software: you can redistribute it and/or modify
|
|
|
5 |
// it under the terms of the GNU General Public License as published by
|
|
|
6 |
// the Free Software Foundation, either version 3 of the License, or
|
|
|
7 |
// (at your option) any later version.
|
|
|
8 |
//
|
|
|
9 |
// Moodle is distributed in the hope that it will be useful,
|
|
|
10 |
// but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
11 |
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
|
12 |
// GNU General Public License for more details.
|
|
|
13 |
//
|
|
|
14 |
// You should have received a copy of the GNU General Public License
|
|
|
15 |
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
|
|
|
16 |
|
|
|
17 |
/**
|
|
|
18 |
* Core grades external functions
|
|
|
19 |
*
|
|
|
20 |
* @package core_grades
|
|
|
21 |
* @copyright 2012 Andrew Davis
|
|
|
22 |
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
|
|
|
23 |
* @since Moodle 2.7
|
|
|
24 |
*/
|
|
|
25 |
|
|
|
26 |
use core_external\external_api;
|
|
|
27 |
use core_external\external_function_parameters;
|
|
|
28 |
use core_external\external_multiple_structure;
|
|
|
29 |
use core_external\external_single_structure;
|
|
|
30 |
use core_external\external_value;
|
|
|
31 |
use core_external\external_warnings;
|
|
|
32 |
|
|
|
33 |
defined('MOODLE_INTERNAL') || die;
|
|
|
34 |
|
|
|
35 |
require_once("$CFG->libdir/gradelib.php");
|
|
|
36 |
require_once("$CFG->dirroot/grade/edit/tree/lib.php");
|
|
|
37 |
require_once("$CFG->dirroot/grade/querylib.php");
|
|
|
38 |
|
|
|
39 |
/**
|
|
|
40 |
* core grades functions
|
|
|
41 |
*/
|
|
|
42 |
class core_grades_external extends external_api {
|
|
|
43 |
/**
|
|
|
44 |
* Returns description of method parameters
|
|
|
45 |
*
|
|
|
46 |
* @return external_function_parameters
|
|
|
47 |
* @since Moodle 2.7
|
|
|
48 |
*/
|
|
|
49 |
public static function update_grades_parameters() {
|
|
|
50 |
return new external_function_parameters(
|
|
|
51 |
array(
|
|
|
52 |
'source' => new external_value(PARAM_TEXT, 'The source of the grade update'),
|
|
|
53 |
'courseid' => new external_value(PARAM_INT, 'id of course'),
|
|
|
54 |
'component' => new external_value(PARAM_COMPONENT, 'A component, for example mod_forum or mod_quiz'),
|
|
|
55 |
'activityid' => new external_value(PARAM_INT, 'The activity ID'),
|
|
|
56 |
'itemnumber' => new external_value(
|
|
|
57 |
PARAM_INT, 'grade item ID number for modules that have multiple grades. Typically this is 0.'),
|
|
|
58 |
'grades' => new external_multiple_structure(
|
|
|
59 |
new external_single_structure(
|
|
|
60 |
array(
|
|
|
61 |
'studentid' => new external_value(PARAM_INT, 'Student ID'),
|
|
|
62 |
'grade' => new external_value(PARAM_FLOAT, 'Student grade'),
|
|
|
63 |
'str_feedback' => new external_value(
|
|
|
64 |
PARAM_TEXT, 'A string representation of the feedback from the grader', VALUE_OPTIONAL),
|
|
|
65 |
)
|
|
|
66 |
), 'Any student grades to alter', VALUE_DEFAULT, array()),
|
|
|
67 |
'itemdetails' => new external_single_structure(
|
|
|
68 |
array(
|
|
|
69 |
'itemname' => new external_value(
|
|
|
70 |
PARAM_ALPHANUMEXT, 'The grade item name', VALUE_OPTIONAL),
|
|
|
71 |
'idnumber' => new external_value(
|
|
|
72 |
PARAM_INT, 'Arbitrary ID provided by the module responsible for the grade item', VALUE_OPTIONAL),
|
|
|
73 |
'gradetype' => new external_value(
|
|
|
74 |
PARAM_INT, 'The type of grade (0 = none, 1 = value, 2 = scale, 3 = text)', VALUE_OPTIONAL),
|
|
|
75 |
'grademax' => new external_value(
|
|
|
76 |
PARAM_FLOAT, 'Maximum grade allowed', VALUE_OPTIONAL),
|
|
|
77 |
'grademin' => new external_value(
|
|
|
78 |
PARAM_FLOAT, 'Minimum grade allowed', VALUE_OPTIONAL),
|
|
|
79 |
'scaleid' => new external_value(
|
|
|
80 |
PARAM_INT, 'The ID of the custom scale being is used', VALUE_OPTIONAL),
|
|
|
81 |
'multfactor' => new external_value(
|
|
|
82 |
PARAM_FLOAT, 'Multiply all grades by this number', VALUE_OPTIONAL),
|
|
|
83 |
'plusfactor' => new external_value(
|
|
|
84 |
PARAM_FLOAT, 'Add this to all grades', VALUE_OPTIONAL),
|
|
|
85 |
'deleted' => new external_value(
|
|
|
86 |
PARAM_BOOL, 'True if the grade item should be deleted', VALUE_OPTIONAL),
|
|
|
87 |
'hidden' => new external_value(
|
|
|
88 |
PARAM_BOOL, 'True if the grade item is hidden', VALUE_OPTIONAL),
|
|
|
89 |
), 'Any grade item settings to alter', VALUE_DEFAULT, array()
|
|
|
90 |
)
|
|
|
91 |
)
|
|
|
92 |
);
|
|
|
93 |
}
|
|
|
94 |
|
|
|
95 |
/**
|
|
|
96 |
* Update a grade item and, optionally, student grades
|
|
|
97 |
*
|
|
|
98 |
* @param string $source The source of the grade update
|
|
|
99 |
* @param int $courseid The course id
|
|
|
100 |
* @param string $component Component name
|
|
|
101 |
* @param int $activityid The activity id
|
|
|
102 |
* @param int $itemnumber The item number
|
|
|
103 |
* @param array $grades Array of grades
|
|
|
104 |
* @param array $itemdetails Array of item details
|
|
|
105 |
* @return int A status flag
|
|
|
106 |
* @since Moodle 2.7
|
|
|
107 |
*/
|
|
|
108 |
public static function update_grades($source, $courseid, $component, $activityid,
|
|
|
109 |
$itemnumber, $grades = array(), $itemdetails = array()) {
|
|
|
110 |
global $CFG;
|
|
|
111 |
|
|
|
112 |
$params = self::validate_parameters(
|
|
|
113 |
self::update_grades_parameters(),
|
|
|
114 |
array(
|
|
|
115 |
'source' => $source,
|
|
|
116 |
'courseid' => $courseid,
|
|
|
117 |
'component' => $component,
|
|
|
118 |
'activityid' => $activityid,
|
|
|
119 |
'itemnumber' => $itemnumber,
|
|
|
120 |
'grades' => $grades,
|
|
|
121 |
'itemdetails' => $itemdetails
|
|
|
122 |
)
|
|
|
123 |
);
|
|
|
124 |
|
|
|
125 |
list($itemtype, $itemmodule) = normalize_component($params['component']);
|
|
|
126 |
|
|
|
127 |
if (! $cm = get_coursemodule_from_id($itemmodule, $activityid)) {
|
|
|
128 |
throw new moodle_exception('invalidcoursemodule');
|
|
|
129 |
}
|
|
|
130 |
$iteminstance = $cm->instance;
|
|
|
131 |
|
|
|
132 |
$coursecontext = context_course::instance($params['courseid']);
|
|
|
133 |
|
|
|
134 |
try {
|
|
|
135 |
self::validate_context($coursecontext);
|
|
|
136 |
} catch (Exception $e) {
|
|
|
137 |
$exceptionparam = new stdClass();
|
|
|
138 |
$exceptionparam->message = $e->getMessage();
|
|
|
139 |
$exceptionparam->courseid = $params['courseid'];
|
|
|
140 |
throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
|
|
|
141 |
}
|
|
|
142 |
|
|
|
143 |
$hidinggrades = false;
|
|
|
144 |
$editinggradeitem = false;
|
|
|
145 |
$editinggrades = false;
|
|
|
146 |
|
|
|
147 |
$gradestructure = array();
|
|
|
148 |
foreach ($grades as $grade) {
|
|
|
149 |
$editinggrades = true;
|
|
|
150 |
$gradestructure[ $grade['studentid'] ] = array('userid' => $grade['studentid'], 'rawgrade' => $grade['grade']);
|
|
|
151 |
}
|
|
|
152 |
if (!empty($params['itemdetails'])) {
|
|
|
153 |
if (isset($params['itemdetails']['hidden'])) {
|
|
|
154 |
$hidinggrades = true;
|
|
|
155 |
} else {
|
|
|
156 |
$editinggradeitem = true;
|
|
|
157 |
}
|
|
|
158 |
}
|
|
|
159 |
|
|
|
160 |
if ($editinggradeitem && !has_capability('moodle/grade:manage', $coursecontext)) {
|
|
|
161 |
throw new moodle_exception('nopermissiontoviewgrades', 'error', '', null,
|
|
|
162 |
'moodle/grade:manage required to edit grade information');
|
|
|
163 |
}
|
|
|
164 |
if ($hidinggrades && !has_capability('moodle/grade:hide', $coursecontext) &&
|
|
|
165 |
!has_capability('moodle/grade:hide', $coursecontext)) {
|
|
|
166 |
throw new moodle_exception('nopermissiontoviewgrades', 'error', '', null,
|
|
|
167 |
'moodle/grade:hide required to hide grade items');
|
|
|
168 |
}
|
|
|
169 |
if ($editinggrades && !has_capability('moodle/grade:edit', $coursecontext)) {
|
|
|
170 |
throw new moodle_exception('nopermissiontoviewgrades', 'error', '', null,
|
|
|
171 |
'moodle/grade:edit required to edit grades');
|
|
|
172 |
}
|
|
|
173 |
|
|
|
174 |
return grade_update($params['source'], $params['courseid'], $itemtype,
|
|
|
175 |
$itemmodule, $iteminstance, $itemnumber, $gradestructure, $params['itemdetails'], true);
|
|
|
176 |
}
|
|
|
177 |
|
|
|
178 |
/**
|
|
|
179 |
* Returns description of method result value
|
|
|
180 |
*
|
|
|
181 |
* @return \core_external\external_description
|
|
|
182 |
* @since Moodle 2.7
|
|
|
183 |
*/
|
|
|
184 |
public static function update_grades_returns() {
|
|
|
185 |
return new external_value(
|
|
|
186 |
PARAM_INT,
|
|
|
187 |
'A value like ' . GRADE_UPDATE_OK . ' => OK, ' . GRADE_UPDATE_FAILED . ' => FAILED
|
|
|
188 |
as defined in lib/grade/constants.php'
|
|
|
189 |
);
|
|
|
190 |
}
|
|
|
191 |
}
|