Initial version of a couple of big icons from Tango Desktop project
[moodle.git] / grade / grading / lib.php
CommitLineData
4333580e
DM
1<?php
2
3// This file is part of Moodle - http://moodle.org/
4//
5// Moodle is free software: you can redistribute it and/or modify
6// it under the terms of the GNU General Public License as published by
7// the Free Software Foundation, either version 3 of the License, or
8// (at your option) any later version.
9//
10// Moodle is distributed in the hope that it will be useful,
11// but WITHOUT ANY WARRANTY; without even the implied warranty of
12// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13// GNU General Public License for more details.
14//
15// You should have received a copy of the GNU General Public License
16// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
17
18/**
19 * Advanced grading methods support
20 *
21 * @package core
22 * @subpackage grading
23 * @copyright 2011 David Mudrak <david@moodle.com>
24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25 */
26
27defined('MOODLE_INTERNAL') || die();
28
29/**
30 * Factory method returning an instance of the grading manager
31 *
fb13a148 32 * @param stdClass|int $context or $areaid
4333580e 33 * @param string $component the frankenstyle name of the component
8a4acb3a 34 * @param string $area the name of the gradable area
4333580e
DM
35 * @return grading_manager
36 */
fb13a148
DM
37function get_grading_manager($context_or_areaid = null, $component = null, $area = null) {
38 global $DB;
4333580e
DM
39
40 $manager = new grading_manager();
41
fb13a148
DM
42 if (is_object($context_or_areaid)) {
43 $context = $context_or_areaid;
44 } else {
45 $context = null;
46
47 if (is_numeric($context_or_areaid)) {
48 $manager->load($context_or_areaid);
49 return $manager;
50 }
51 }
52
4333580e
DM
53 if (!is_null($context)) {
54 $manager->set_context($context);
55 }
56
57 if (!is_null($component)) {
58 $manager->set_component($component);
59 }
60
8a4acb3a
DM
61 if (!is_null($area)) {
62 $manager->set_area($area);
4333580e
DM
63 }
64
65 return $manager;
66}
67
68/**
69 * General class providing access to common grading features
70 *
9b8550f8
DM
71 * Grading manager provides access to the particular grading method controller
72 * in that area.
73 *
4333580e
DM
74 * Fully initialized instance of the grading manager operates over a single
75 * gradable area. It is possible to work with a partially initialized manager
8a4acb3a
DM
76 * that knows just context and component without known area, for example.
77 * It is also possible to change context, component and area of an existing
4333580e
DM
78 * manager. Such pattern is used when copying form definitions, for example.
79 */
80class grading_manager {
81
82 /** @var stdClass the context */
83 protected $context;
84
85 /** @var string the frankenstyle name of the component */
86 protected $component;
87
88 /** @var string the name of the gradable area */
8a4acb3a 89 protected $area;
4333580e 90
9b8550f8
DM
91 /** @var stdClass|false|null the raw record from {grading_areas}, false if does not exist, null if invalidated cache */
92 private $areacache = null;
93
21d37aa6
DM
94 /**
95 * @return stdClass grading manager context
96 */
97 public function get_context() {
98 return $this->context;
99 }
100
4333580e
DM
101 /**
102 * Sets the context the manager operates on
103 *
104 * @param stdClass $context
105 */
106 public function set_context(stdClass $context) {
9b8550f8 107 $this->areacache = null;
4333580e
DM
108 $this->context = $context;
109 }
110
21d37aa6
DM
111 /**
112 * @return string grading manager component
113 */
114 public function get_component() {
115 return $this->component;
116 }
117
4333580e
DM
118 /**
119 * Sets the component the manager operates on
120 *
121 * @param string $component the frankenstyle name of the component
122 */
123 public function set_component($component) {
9b8550f8
DM
124 $this->areacache = null;
125 list($type, $name) = normalize_component($component);
126 $this->component = $type.'_'.$name;
4333580e
DM
127 }
128
21d37aa6
DM
129 /**
130 * @return string grading manager area name
131 */
132 public function get_area() {
133 return $this->area;
134 }
135
4333580e 136 /**
8a4acb3a 137 * Sets the area the manager operates on
4333580e 138 *
8a4acb3a 139 * @param string $area the name of the gradable area
4333580e 140 */
8a4acb3a 141 public function set_area($area) {
9b8550f8 142 $this->areacache = null;
8a4acb3a 143 $this->area = $area;
4333580e
DM
144 }
145
fb13a148
DM
146 /**
147 * Loads the gradable area info from the database
148 *
149 * @param int $areaid
150 */
151 public function load($areaid) {
152 global $DB;
153
154 $this->areacache = $DB->get_record('grading_areas', array('id' => $areaid), '*', MUST_EXIST);
155 $this->context = get_context_instance_by_id($this->areacache->contextid, MUST_EXIST);
156 $this->component = $this->areacache->component;
157 $this->area = $this->areacache->areaname;
158 }
159
4333580e
DM
160 /**
161 * Returns the list of available grading methods in the given context
162 *
163 * Basically this returns the list of installed grading plugins with an empty value
164 * for simple direct grading. In the future, the list of available methods may be
165 * controlled per-context.
166 *
167 * Requires the context property to be set in advance.
6c9e506c
DM
168 *
169 * @param bool $includenone should the 'Simple direct grading' be included
4333580e
DM
170 * @return array of the (string)name => (string)localized title of the method
171 */
6c9e506c 172 public function get_available_methods($includenone = true) {
4333580e
DM
173
174 $this->ensure_isset(array('context'));
175
6c9e506c
DM
176 if ($includenone) {
177 $list = array('' => get_string('gradingmethodnone', 'core_grading'));
178 } else {
179 $list = array();
180 }
181
182 foreach (get_plugin_list('gradingform') as $name => $location) {
183 $list[$name] = get_string('pluginname', 'gradingform_'.$name);
184 }
185
186 return $list;
4333580e
DM
187 }
188
189 /**
190 * Returns the list of gradable areas in the given context and component
191 *
192 * This performs a callback to the library of the relevant plugin to obtain
193 * the list of supported areas.
194 * @return array of (string)areacode => (string)localized title of the area
195 */
196 public function get_available_areas() {
197 global $CFG;
198
199 $this->ensure_isset(array('context', 'component'));
200
201 // example: if the given context+component lead to mod_assignment, this method
202 // will do something like
203 // require_once($CFG->dirroot.'/mod/assignment/lib.php');
204 // return assignment_gradable_area_list();
205
206 // todo - hardcoded list for now
9b8550f8 207 return array('submission' => 'Submissions');
4333580e
DM
208 }
209
210 /**
8a4acb3a 211 * Returns the currently active grading method in the gradable area
4333580e 212 *
64402867 213 * @return string|null the name of the grading plugin of null if it has not been set
4333580e 214 */
8a4acb3a 215 public function get_active_method() {
64402867
DM
216 global $DB;
217
218 $this->ensure_isset(array('context', 'component', 'area'));
219
220 // get the current grading area record if it exists
9b8550f8
DM
221 if (is_null($this->areacache)) {
222 $this->areacache = $DB->get_record('grading_areas', array(
223 'contextid' => $this->context->id,
224 'component' => $this->component,
225 'areaname' => $this->area),
226 '*', IGNORE_MISSING);
227 }
64402867 228
9b8550f8 229 if ($this->areacache === false) {
64402867
DM
230 // no area record yet
231 return null;
232 }
233
9b8550f8 234 return $this->areacache->activemethod;
64402867
DM
235 }
236
237 /**
238 * Sets the currently active grading method in the gradable area
239 *
240 * @param string $method the method name, eg 'rubric' (must be available)
3bd217aa 241 * @return bool true if the method changed or was just set, false otherwise
64402867
DM
242 */
243 public function set_active_method($method) {
244 global $DB;
245
8a4acb3a 246 $this->ensure_isset(array('context', 'component', 'area'));
64402867 247
8cd65f16
DM
248 // make sure the passed method is empty or a valid plugin name
249 if (empty($method)) {
250 $method = null;
251 } else {
252 if ('gradingform_'.$method !== clean_param('gradingform_'.$method, PARAM_COMPONENT)) {
253 throw new moodle_exception('invalid_method_name', 'core_grading');
254 }
255 $available = $this->get_available_methods(false);
256 if (!array_key_exists($method, $available)) {
257 throw new moodle_exception('invalid_method_name', 'core_grading');
258 }
64402867
DM
259 }
260
261 // get the current grading area record if it exists
9b8550f8
DM
262 if (is_null($this->areacache)) {
263 $this->areacache = $DB->get_record('grading_areas', array(
264 'contextid' => $this->context->id,
265 'component' => $this->component,
266 'areaname' => $this->area),
267 '*', IGNORE_MISSING);
268 }
64402867 269
3bd217aa
DM
270 $methodchanged = false;
271
9b8550f8 272 if ($this->areacache === false) {
64402867
DM
273 // no area record yet, create one with the active method set
274 $area = array(
275 'contextid' => $this->context->id,
276 'component' => $this->component,
277 'areaname' => $this->area,
278 'activemethod' => $method);
279 $DB->insert_record('grading_areas', $area);
3bd217aa 280 $methodchanged = true;
64402867
DM
281
282 } else {
283 // update the existing record if needed
8cd65f16 284 if ($this->areacache->activemethod !== $method) {
9b8550f8 285 $DB->set_field('grading_areas', 'activemethod', $method, array('id' => $this->areacache->id));
3bd217aa 286 $methodchanged = true;
64402867
DM
287 }
288 }
9b8550f8
DM
289
290 $this->areacache = null;
3bd217aa
DM
291
292 return $methodchanged;
9b8550f8
DM
293 }
294
295 /**
296 * Extends the settings navigation with the grading settings
297 *
298 * This function is called when the context for the page is an activity module with the
299 * FEATURE_ADVANCED_GRADING and the user has the permission moodle/grade:managegradingforms.
300 *
301 * @param settings_navigation $settingsnav {@link settings_navigation}
302 * @param navigation_node $modulenode {@link navigation_node}
303 */
304 public function extend_settings_navigation(settings_navigation $settingsnav, navigation_node $modulenode=null) {
305 global $PAGE, $CFG;
306
307 $this->ensure_isset(array('context', 'component'));
308
309 $areas = $this->get_available_areas();
310
311 if (empty($areas)) {
312 // no money, no funny
313 return;
314 }
315
8168299d
DM
316 if ($PAGE->url->compare(new moodle_url('/grade/grading/management.php'), URL_MATCH_BASE)) {
317 // we are already at the management page, do not produce link to ourselves
318 // (because of the returnurl)
319 $managementurl = null;
320 } else {
321 $managementurl = $this->get_management_url($PAGE->url);
322 }
323 $managementnode = $modulenode->add(get_string('gradingmanagement', 'core_grading'), $managementurl, settings_navigation::TYPE_CUSTOM);
324
9b8550f8
DM
325 foreach ($areas as $areaname => $areatitle) {
326 $this->set_area($areaname);
327 $method = $this->get_active_method();
328
329 if (empty($method)) {
330 // no grading method selected for the given area - nothing to display
331 continue;
332 }
333
334 if (count($areas) > 1) {
335 // if the module supports multiple gradable areas, make a node for each of them
8168299d 336 $node = $managementnode->add(get_string('gradinginarea', 'core_grading', $areatitle), null, settings_navigation::NODETYPE_BRANCH);
9b8550f8
DM
337 } else {
338 // otherwise put the items directly into the module's node
8168299d 339 $node = $managementnode;
9b8550f8
DM
340 }
341
342 $controller = $this->get_controller($method);
343 $controller->extend_settings_navigation($settingsnav, $node);
344 }
345 }
346
347 /**
348 * Returns the given method's controller in the gradable area
349 *
350 * @param string $method the method name, eg 'rubric' (must be available)
351 * @return grading_controller
352 */
353 public function get_controller($method) {
354 global $CFG;
355
356 $this->ensure_isset(array('context', 'component', 'area'));
357
358 // make sure the passed method is a valid plugin name
359 if ('gradingform_'.$method !== clean_param('gradingform_'.$method, PARAM_COMPONENT)) {
360 throw new moodle_exception('invalid_method_name', 'core_grading');
361 }
362 $available = $this->get_available_methods(false);
363 if (!array_key_exists($method, $available)) {
364 throw new moodle_exception('invalid_method_name', 'core_grading');
365 }
366
367 // get the current grading area record if it exists
368 if (is_null($this->areacache)) {
369 $this->areacache = $DB->get_record('grading_areas', array(
370 'contextid' => $this->context->id,
371 'component' => $this->component,
372 'areaname' => $this->area),
373 '*', IGNORE_MISSING);
374 }
375
376 if ($this->areacache === false) {
377 // no area record yet, create one
378 $area = array(
379 'contextid' => $this->context->id,
380 'component' => $this->component,
381 'areaname' => $this->area);
382 $areaid = $DB->insert_record('grading_areas', $area);
383 // reload the cache
384 $this->areacache = $DB->get_record('grading_areas', array('id' => $areaid), '*', MUST_EXIST);
385 }
386
387 require_once($CFG->dirroot.'/grade/grading/form/'.$method.'/lib.php');
3e43eff5 388 $classname = 'gradingform_'.$method.'_controller';
9b8550f8
DM
389
390 return new $classname($this->context, $this->component, $this->area, $this->areacache->id);
4333580e
DM
391 }
392
18e6298c
MG
393 /**
394 * Returns the controller for the active method if it is available
03d448e5
DM
395 *
396 * @return null|grading_controller
18e6298c
MG
397 */
398 public function get_active_controller() {
399 if ($gradingmethod = $this->get_active_method()) {
400 $controller = $this->get_controller($gradingmethod);
401 if ($controller->is_form_available()) {
402 return $controller;
403 }
404 }
405 return null;
406 }
407
03d448e5
DM
408 /**
409 * Returns the URL of the grading area management page
410 *
411 * @param moodle_url $returnurl optional URL of the page where the user should be sent back to
412 * @return moodle_url
413 */
414 public function get_management_url(moodle_url $returnurl = null) {
415
416 $this->ensure_isset(array('context', 'component'));
417
418 if ($this->areacache) {
419 $params = array('areaid' => $this->areacache->id);
420 } else {
421 $params = array('contextid' => $this->context->id, 'component' => $this->component);
422 }
423
424 if (!is_null($returnurl)) {
425 $params['returnurl'] = $returnurl->out(false);
426 }
427
428 return new moodle_url('/grade/grading/management.php', $params);
429 }
430
9b8550f8 431 ////////////////////////////////////////////////////////////////////////////
64402867 432
4333580e
DM
433 /**
434 * Make sure that the given properties were set to some not-null value
435 *
436 * @param array $properties the list of properties
437 * @throws coding_exception
438 */
439 private function ensure_isset(array $properties) {
440 foreach ($properties as $property) {
441 if (!isset($this->$property)) {
9b8550f8 442 throw new coding_exception('The property "'.$property.'" is not set.');
4333580e
DM
443 }
444 }
445 }
446}