MDL-30998: updated docblocks for backup of advanced grading
[moodle.git] / grade / grading / lib.php
1 <?php
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/>.
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  */
27 defined('MOODLE_INTERNAL') || die();
29 /**
30  * Factory method returning an instance of the grading manager
31  *
32  * There are basically ways how to use this factory method. If the area record
33  * id is known to the caller, get the manager for that area by providing just
34  * the id. If the area record id is not know, the context, component and area name
35  * can be provided. Note that null values are allowed in the second case as the context,
36  * component and the area name can be set explicitly later.
37  *
38  * @example $manager = get_grading_manager($areaid);
39  * @example $manager = get_grading_manager(get_system_context());
40  * @example $manager = get_grading_manager($context, 'mod_assignment', 'submission');
41  * @param stdClass|int|null $context or $areaid if $areaid is passed, no other parameter is needed
42  * @param string|null $component the frankenstyle name of the component
43  * @param string|null $area the name of the gradable area
44  * @return grading_manager
45  */
46 function get_grading_manager($context_or_areaid = null, $component = null, $area = null) {
47     global $DB;
49     $manager = new grading_manager();
51     if (is_object($context_or_areaid)) {
52         $context = $context_or_areaid;
53     } else {
54         $context = null;
56         if (is_numeric($context_or_areaid)) {
57             $manager->load($context_or_areaid);
58             return $manager;
59         }
60     }
62     if (!is_null($context)) {
63         $manager->set_context($context);
64     }
66     if (!is_null($component)) {
67         $manager->set_component($component);
68     }
70     if (!is_null($area)) {
71         $manager->set_area($area);
72     }
74     return $manager;
75 }
77 /**
78  * General class providing access to common grading features
79  *
80  * Grading manager provides access to the particular grading method controller
81  * in that area.
82  *
83  * Fully initialized instance of the grading manager operates over a single
84  * gradable area. It is possible to work with a partially initialized manager
85  * that knows just context and component without known area, for example.
86  * It is also possible to change context, component and area of an existing
87  * manager. Such pattern is used when copying form definitions, for example.
88  */
89 class grading_manager {
91     /** @var stdClass the context */
92     protected $context;
94     /** @var string the frankenstyle name of the component */
95     protected $component;
97     /** @var string the name of the gradable area */
98     protected $area;
100     /** @var stdClass|false|null the raw record from {grading_areas}, false if does not exist, null if invalidated cache */
101     private $areacache = null;
103     /**
104      * @return stdClass grading manager context
105      */
106     public function get_context() {
107         return $this->context;
108     }
110     /**
111      * Sets the context the manager operates on
112      *
113      * @param stdClass $context
114      */
115     public function set_context(stdClass $context) {
116         $this->areacache = null;
117         $this->context = $context;
118     }
120     /**
121      * @return string grading manager component
122      */
123     public function get_component() {
124         return $this->component;
125     }
127     /**
128      * Sets the component the manager operates on
129      *
130      * @param string $component the frankenstyle name of the component
131      */
132     public function set_component($component) {
133         $this->areacache = null;
134         list($type, $name) = normalize_component($component);
135         $this->component = $type.'_'.$name;
136     }
138     /**
139      * @return string grading manager area name
140      */
141     public function get_area() {
142         return $this->area;
143     }
145     /**
146      * Sets the area the manager operates on
147      *
148      * @param string $area the name of the gradable area
149      */
150     public function set_area($area) {
151         $this->areacache = null;
152         $this->area = $area;
153     }
155     /**
156      * Returns a text describing the context and the component
157      *
158      * At the moment this works for gradable areas in course modules. In the future, this
159      * method should be improved so it works for other contexts (blocks, gradebook items etc)
160      * or subplugins.
161      *
162      * @return string
163      */
164     public function get_component_title() {
166         $this->ensure_isset(array('context', 'component'));
168         if ($this->get_context()->contextlevel == CONTEXT_SYSTEM) {
169             if ($this->get_component() == 'core_grading') {
170                 $title = ''; // we are in the bank UI
171             } else {
172                 throw new coding_exception('Unsupported component at the system context');
173             }
175         } else if ($this->get_context()->contextlevel >= CONTEXT_COURSE) {
176             list($context, $course, $cm) = get_context_info_array($this->get_context()->id);
178             if (!empty($cm->name)) {
179                 $title = $cm->name;
180             } else {
181                 debugging('Gradable areas are currently supported at the course module level only', DEBUG_DEVELOPER);
182                 $title = $this->get_component();
183             }
185         } else {
186             throw new coding_exception('Unsupported gradable area context level');
187         }
189         return $title;
190     }
192     /**
193      * Returns the localized title of the currently set area
194      *
195      * @return string
196      */
197     public function get_area_title() {
199         if ($this->get_context()->contextlevel == CONTEXT_SYSTEM) {
200             return '';
202         } else if ($this->get_context()->contextlevel >= CONTEXT_COURSE) {
203             $this->ensure_isset(array('context', 'component', 'area'));
204             $areas = $this->get_available_areas();
205             if (array_key_exists($this->get_area(), $areas)) {
206                 return $areas[$this->get_area()];
207             } else {
208                 debugging('Unknown area!');
209                 return '???';
210             }
212         } else {
213             throw new coding_exception('Unsupported context level');
214         }
215     }
217     /**
218      * Loads the gradable area info from the database
219      *
220      * @param int $areaid
221      */
222     public function load($areaid) {
223         global $DB;
225         $this->areacache = $DB->get_record('grading_areas', array('id' => $areaid), '*', MUST_EXIST);
226         $this->context = context::instance_by_id($this->areacache->contextid, MUST_EXIST);
227         $this->component = $this->areacache->component;
228         $this->area = $this->areacache->areaname;
229     }
231     /**
232      * Returns the list of installed grading plugins together, optionally extended
233      * with a simple direct grading.
234      *
235      * @param bool $includenone should the 'Simple direct grading' be included
236      * @return array of the (string)name => (string)localized title of the method
237      */
238     public static function available_methods($includenone = true) {
240         if ($includenone) {
241             $list = array('' => get_string('gradingmethodnone', 'core_grading'));
242         } else {
243             $list = array();
244         }
246         foreach (get_plugin_list('gradingform') as $name => $location) {
247             $list[$name] = get_string('pluginname', 'gradingform_'.$name);
248         }
250         return $list;
251     }
253     /**
254      * Returns the list of available grading methods in the given context
255      *
256      * Currently this is just a static list obtained from {@link self::available_methods()}.
257      * In the future, the list of available methods may be controlled per-context.
258      *
259      * Requires the context property to be set in advance.
260      *
261      * @param bool $includenone should the 'Simple direct grading' be included
262      * @return array of the (string)name => (string)localized title of the method
263      */
264     public function get_available_methods($includenone = true) {
265         $this->ensure_isset(array('context'));
266         return self::available_methods($includenone);
267     }
269     /**
270      * Returns the list of gradable areas provided by the given component
271      *
272      * This performs a callback to the library of the relevant plugin to obtain
273      * the list of supported areas.
274      *
275      * @param string $component normalized component name
276      * @return array of (string)areacode => (string)localized title of the area
277      */
278     public static function available_areas($component) {
279         global $CFG;
281         list($plugintype, $pluginname) = normalize_component($component);
283         if ($component === 'core_grading') {
284             return array();
286         } else if ($plugintype === 'mod') {
287             return plugin_callback('mod', $pluginname, 'grading', 'areas_list', null, array());
289         } else {
290             throw new coding_exception('Unsupported area location');
291         }
292     }
295     /**
296      * Returns the list of gradable areas in the given context and component
297      *
298      * This performs a callback to the library of the relevant plugin to obtain
299      * the list of supported areas.
300      * @return array of (string)areacode => (string)localized title of the area
301      */
302     public function get_available_areas() {
303         global $CFG;
305         $this->ensure_isset(array('context', 'component'));
307         if ($this->get_context()->contextlevel == CONTEXT_SYSTEM) {
308             if ($this->get_component() !== 'core_grading') {
309                 throw new coding_exception('Unsupported component at the system context');
310             } else {
311                 return array();
312             }
314         } else if ($this->get_context()->contextlevel == CONTEXT_MODULE) {
315             list($context, $course, $cm) = get_context_info_array($this->get_context()->id);
316             return self::available_areas('mod_'.$cm->modname);
318         } else {
319             throw new coding_exception('Unsupported gradable area context level');
320         }
321     }
323     /**
324      * Returns the currently active grading method in the gradable area
325      *
326      * @return string|null the name of the grading plugin of null if it has not been set
327      */
328     public function get_active_method() {
329         global $DB;
331         $this->ensure_isset(array('context', 'component', 'area'));
333         // get the current grading area record if it exists
334         if (is_null($this->areacache)) {
335             $this->areacache = $DB->get_record('grading_areas', array(
336                 'contextid' => $this->context->id,
337                 'component' => $this->component,
338                 'areaname'  => $this->area),
339             '*', IGNORE_MISSING);
340         }
342         if ($this->areacache === false) {
343             // no area record yet
344             return null;
345         }
347         return $this->areacache->activemethod;
348     }
350     /**
351      * Sets the currently active grading method in the gradable area
352      *
353      * @param string $method the method name, eg 'rubric' (must be available)
354      * @return bool true if the method changed or was just set, false otherwise
355      */
356     public function set_active_method($method) {
357         global $DB;
359         $this->ensure_isset(array('context', 'component', 'area'));
361         // make sure the passed method is empty or a valid plugin name
362         if (empty($method)) {
363             $method = null;
364         } else {
365             if ('gradingform_'.$method !== clean_param('gradingform_'.$method, PARAM_COMPONENT)) {
366                 throw new moodle_exception('invalid_method_name', 'core_grading');
367             }
368             $available = $this->get_available_methods(false);
369             if (!array_key_exists($method, $available)) {
370                 throw new moodle_exception('invalid_method_name', 'core_grading');
371             }
372         }
374         // get the current grading area record if it exists
375         if (is_null($this->areacache)) {
376             $this->areacache = $DB->get_record('grading_areas', array(
377                 'contextid' => $this->context->id,
378                 'component' => $this->component,
379                 'areaname'  => $this->area),
380             '*', IGNORE_MISSING);
381         }
383         $methodchanged = false;
385         if ($this->areacache === false) {
386             // no area record yet, create one with the active method set
387             $area = array(
388                 'contextid'     => $this->context->id,
389                 'component'     => $this->component,
390                 'areaname'      => $this->area,
391                 'activemethod'  => $method);
392             $DB->insert_record('grading_areas', $area);
393             $methodchanged = true;
395         } else {
396             // update the existing record if needed
397             if ($this->areacache->activemethod !== $method) {
398                 $DB->set_field('grading_areas', 'activemethod', $method, array('id' => $this->areacache->id));
399                 $methodchanged = true;
400             }
401         }
403         $this->areacache = null;
405         return $methodchanged;
406     }
408     /**
409      * Extends the settings navigation with the grading settings
410      *
411      * This function is called when the context for the page is an activity module with the
412      * FEATURE_ADVANCED_GRADING and the user has the permission moodle/grade:managegradingforms.
413      *
414      * @param settings_navigation $settingsnav {@link settings_navigation}
415      * @param navigation_node $modulenode {@link navigation_node}
416      */
417     public function extend_settings_navigation(settings_navigation $settingsnav, navigation_node $modulenode=null) {
419         $this->ensure_isset(array('context', 'component'));
421         $areas = $this->get_available_areas();
423         if (empty($areas)) {
424             // no money, no funny
425             return;
427         } else if (count($areas) == 1) {
428             // make just a single node for the management screen
429             $areatitle = reset($areas);
430             $areaname  = key($areas);
431             $this->set_area($areaname);
432             $method = $this->get_active_method();
433             $managementnode = $modulenode->add(get_string('gradingmanagement', 'core_grading'),
434                 $this->get_management_url(), settings_navigation::TYPE_CUSTOM);
435             if ($method) {
436                 $controller = $this->get_controller($method);
437                 $controller->extend_settings_navigation($settingsnav, $managementnode);
438             }
440         } else {
441             // make management screen node for each area
442             $managementnode = $modulenode->add(get_string('gradingmanagement', 'core_grading'),
443                 null, settings_navigation::TYPE_CUSTOM);
444             foreach ($areas as $areaname => $areatitle) {
445                 $this->set_area($areaname);
446                 $method = $this->get_active_method();
447                 $node = $managementnode->add($areatitle,
448                     $this->get_management_url(), settings_navigation::TYPE_CUSTOM);
449                 if ($method) {
450                     $controller = $this->get_controller($method);
451                     $controller->extend_settings_navigation($settingsnav, $node);
452                 }
453             }
454         }
455     }
457     /**
458      * Extends the module navigation with the advanced grading information
459      *
460      * This function is called when the context for the page is an activity module with the
461      * FEATURE_ADVANCED_GRADING.
462      *
463      * @param global_navigation $navigation
464      * @param navigation_node $modulenode
465      */
466     public function extend_navigation(global_navigation $navigation, navigation_node $modulenode=null) {
467         $this->ensure_isset(array('context', 'component'));
469         $areas = $this->get_available_areas();
470         foreach ($areas as $areaname => $areatitle) {
471             $this->set_area($areaname);
472             if ($controller = $this->get_active_controller()) {
473                 $controller->extend_navigation($navigation, $modulenode);
474             }
475         }
476     }
478     /**
479      * Returns the given method's controller in the gradable area
480      *
481      * @param string $method the method name, eg 'rubric' (must be available)
482      * @return grading_controller
483      */
484     public function get_controller($method) {
485         global $CFG, $DB;
487         $this->ensure_isset(array('context', 'component', 'area'));
489         // make sure the passed method is a valid plugin name
490         if ('gradingform_'.$method !== clean_param('gradingform_'.$method, PARAM_COMPONENT)) {
491             throw new moodle_exception('invalid_method_name', 'core_grading');
492         }
493         $available = $this->get_available_methods(false);
494         if (!array_key_exists($method, $available)) {
495             throw new moodle_exception('invalid_method_name', 'core_grading');
496         }
498         // get the current grading area record if it exists
499         if (is_null($this->areacache)) {
500             $this->areacache = $DB->get_record('grading_areas', array(
501                 'contextid' => $this->context->id,
502                 'component' => $this->component,
503                 'areaname'  => $this->area),
504             '*', IGNORE_MISSING);
505         }
507         if ($this->areacache === false) {
508             // no area record yet, create one
509             $area = array(
510                 'contextid' => $this->context->id,
511                 'component' => $this->component,
512                 'areaname'  => $this->area);
513             $areaid = $DB->insert_record('grading_areas', $area);
514             // reload the cache
515             $this->areacache = $DB->get_record('grading_areas', array('id' => $areaid), '*', MUST_EXIST);
516         }
518         require_once($CFG->dirroot.'/grade/grading/form/'.$method.'/lib.php');
519         $classname = 'gradingform_'.$method.'_controller';
521         return new $classname($this->context, $this->component, $this->area, $this->areacache->id);
522     }
524     /**
525      * Returns the controller for the active method if it is available
526      *
527      * @return null|grading_controller
528      */
529     public function get_active_controller() {
530         if ($gradingmethod = $this->get_active_method()) {
531             $controller = $this->get_controller($gradingmethod);
532             if ($controller->is_form_available()) {
533                 return $controller;
534             }
535         }
536         return null;
537     }
539     /**
540      * Returns the URL of the grading area management page
541      *
542      * @param moodle_url $returnurl optional URL of the page where the user should be sent back to
543      * @return moodle_url
544      */
545     public function get_management_url(moodle_url $returnurl = null) {
547         $this->ensure_isset(array('context', 'component'));
549         if ($this->areacache) {
550             $params = array('areaid' => $this->areacache->id);
551         } else {
552             $params = array('contextid' => $this->context->id, 'component' => $this->component);
553             if ($this->area) {
554                 $params['area'] = $this->area;
555             }
556         }
558         if (!is_null($returnurl)) {
559             $params['returnurl'] = $returnurl->out(false);
560         }
562         return new moodle_url('/grade/grading/manage.php', $params);
563     }
565     /**
566      * Creates a new shared area to hold a grading form template
567      *
568      * Shared area are implemented as virtual gradable areas at the system level context
569      * with the component set to core_grading and unique random area name.
570      *
571      * @param string $method the name of the plugin we create the area for
572      * @return int the new area id
573      */
574     public function create_shared_area($method) {
575         global $DB;
577         // generate some unique random name for the new area
578         $name = $method . '_' . sha1(rand().uniqid($method, true));
579         // create new area record
580         $area = array(
581             'contextid'     => context_system::instance()->id,
582             'component'     => 'core_grading',
583             'areaname'      => $name,
584             'activemethod'  => $method);
585         return $DB->insert_record('grading_areas', $area);
586     }
588     /**
589      * Removes all data associated with the given context
590      *
591      * This is called by {@link context::delete_content()}
592      *
593      * @param int $contextid context id
594      */
595     public static function delete_all_for_context($contextid) {
596         global $DB;
598         $areaids = $DB->get_fieldset_select('grading_areas', 'id', 'contextid = ?', array($contextid));
599         $methods = array_keys(self::available_methods(false));
601         foreach($areaids as $areaid) {
602             $manager = get_grading_manager($areaid);
603             foreach ($methods as $method) {
604                 $controller = $manager->get_controller($method);
605                 $controller->delete_definition();
606             }
607         }
609         $DB->delete_records_list('grading_areas', 'id', $areaids);
610     }
612     /**
613      * Helper method to tokenize the given string
614      *
615      * Splits the given string into smaller strings. This is a helper method for
616      * full text searching in grading forms. If the given string is surrounded with
617      * double quotes, the resulting array consists of a single item containing the
618      * quoted content.
619      *
620      * Otherwise, string like 'grammar, english language' would be tokenized into
621      * the three tokens 'grammar', 'english', 'language'.
622      *
623      * One-letter tokens like are dropped in non-phrase mode. Repeated tokens are
624      * returned just once.
625      *
626      * @param string $needle
627      * @return array
628      */
629     public static function tokenize($needle) {
631         // check if we are searching for the exact phrase
632         if (preg_match('/^[\s]*"[\s]*(.*?)[\s]*"[\s]*$/', $needle, $matches)) {
633             $token = $matches[1];
634             if ($token === '') {
635                 return array();
636             } else {
637                 return array($token);
638             }
639         }
641         // split the needle into smaller parts separated by non-word characters
642         $tokens = preg_split("/\W/u", $needle);
643         // keep just non-empty parts
644         $tokens = array_filter($tokens);
645         // distinct
646         $tokens = array_unique($tokens);
647         // drop one-letter tokens
648         foreach ($tokens as $ix => $token) {
649             if (strlen($token) == 1) {
650                 unset($tokens[$ix]);
651             }
652         }
654         return array_values($tokens);
655     }
657     ////////////////////////////////////////////////////////////////////////////
659     /**
660      * Make sure that the given properties were set to some not-null value
661      *
662      * @param array $properties the list of properties
663      * @throws coding_exception
664      */
665     private function ensure_isset(array $properties) {
666         foreach ($properties as $property) {
667             if (!isset($this->$property)) {
668                 throw new coding_exception('The property "'.$property.'" is not set.');
669             }
670         }
671     }