e27a4ec8bcb2ed7bcaabc1d359da8451122820f0
[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 = get_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      * Returns the given method's controller in the gradable area
459      *
460      * @param string $method the method name, eg 'rubric' (must be available)
461      * @return grading_controller
462      */
463     public function get_controller($method) {
464         global $CFG, $DB;
466         $this->ensure_isset(array('context', 'component', 'area'));
468         // make sure the passed method is a valid plugin name
469         if ('gradingform_'.$method !== clean_param('gradingform_'.$method, PARAM_COMPONENT)) {
470             throw new moodle_exception('invalid_method_name', 'core_grading');
471         }
472         $available = $this->get_available_methods(false);
473         if (!array_key_exists($method, $available)) {
474             throw new moodle_exception('invalid_method_name', 'core_grading');
475         }
477         // get the current grading area record if it exists
478         if (is_null($this->areacache)) {
479             $this->areacache = $DB->get_record('grading_areas', array(
480                 'contextid' => $this->context->id,
481                 'component' => $this->component,
482                 'areaname'  => $this->area),
483             '*', IGNORE_MISSING);
484         }
486         if ($this->areacache === false) {
487             // no area record yet, create one
488             $area = array(
489                 'contextid' => $this->context->id,
490                 'component' => $this->component,
491                 'areaname'  => $this->area);
492             $areaid = $DB->insert_record('grading_areas', $area);
493             // reload the cache
494             $this->areacache = $DB->get_record('grading_areas', array('id' => $areaid), '*', MUST_EXIST);
495         }
497         require_once($CFG->dirroot.'/grade/grading/form/'.$method.'/lib.php');
498         $classname = 'gradingform_'.$method.'_controller';
500         return new $classname($this->context, $this->component, $this->area, $this->areacache->id);
501     }
503     /**
504      * Returns the controller for the active method if it is available
505      *
506      * @return null|grading_controller
507      */
508     public function get_active_controller() {
509         if ($gradingmethod = $this->get_active_method()) {
510             $controller = $this->get_controller($gradingmethod);
511             if ($controller->is_form_available()) {
512                 return $controller;
513             }
514         }
515         return null;
516     }
518     /**
519      * Returns the URL of the grading area management page
520      *
521      * @param moodle_url $returnurl optional URL of the page where the user should be sent back to
522      * @return moodle_url
523      */
524     public function get_management_url(moodle_url $returnurl = null) {
526         $this->ensure_isset(array('context', 'component'));
528         if ($this->areacache) {
529             $params = array('areaid' => $this->areacache->id);
530         } else {
531             $params = array('contextid' => $this->context->id, 'component' => $this->component);
532             if ($this->area) {
533                 $params['area'] = $this->area;
534             }
535         }
537         if (!is_null($returnurl)) {
538             $params['returnurl'] = $returnurl->out(false);
539         }
541         return new moodle_url('/grade/grading/manage.php', $params);
542     }
544     /**
545      * Creates a new shared area to hold a grading form template
546      *
547      * Shared area are implemented as virtual gradable areas at the system level context
548      * with the component set to core_grading and unique random area name.
549      *
550      * @param string $method the name of the plugin we create the area for
551      * @return int the new area id
552      */
553     public function create_shared_area($method) {
554         global $DB;
556         // generate some unique random name for the new area
557         $name = $method . '_' . sha1(rand().uniqid($method, true));
558         // create new area record
559         $area = array(
560             'contextid'     => context_system::instance()->id,
561             'component'     => 'core_grading',
562             'areaname'      => $name,
563             'activemethod'  => $method);
564         return $DB->insert_record('grading_areas', $area);
565     }
567     /**
568      * Removes all data associated with the given context
569      *
570      * This is called by {@link context::delete_content()}
571      *
572      * @param int $contextid context id
573      */
574     public static function delete_all_for_context($contextid) {
575         global $DB;
577         $areaids = $DB->get_fieldset_select('grading_areas', 'id', 'contextid = ?', array($contextid));
578         $methods = array_keys(self::available_methods(false));
580         foreach($areaids as $areaid) {
581             $manager = get_grading_manager($areaid);
582             foreach ($methods as $method) {
583                 $controller = $manager->get_controller($method);
584                 $controller->delete_definition();
585             }
586         }
588         $DB->delete_records_list('grading_areas', 'id', $areaids);
589     }
591     /**
592      * Helper method to tokenize the given string
593      *
594      * Splits the given string into smaller strings. This is a helper method for
595      * full text searching in grading forms. If the given string is surrounded with
596      * double quotes, the resulting array consists of a single item containing the
597      * quoted content.
598      *
599      * Otherwise, string like 'grammar, english language' would be tokenized into
600      * the three tokens 'grammar', 'english', 'language'.
601      *
602      * One-letter tokens like are dropped in non-phrase mode. Repeated tokens are
603      * returned just once.
604      *
605      * @param string $needle
606      * @return array
607      */
608     public static function tokenize($needle) {
610         // check if we are searching for the exact phrase
611         if (preg_match('/^[\s]*"[\s]*(.*?)[\s]*"[\s]*$/', $needle, $matches)) {
612             $token = $matches[1];
613             if ($token === '') {
614                 return array();
615             } else {
616                 return array($token);
617             }
618         }
620         // split the needle into smaller parts separated by non-word characters
621         $tokens = preg_split("/\W/u", $needle);
622         // keep just non-empty parts
623         $tokens = array_filter($tokens);
624         // distinct
625         $tokens = array_unique($tokens);
626         // drop one-letter tokens
627         foreach ($tokens as $ix => $token) {
628             if (strlen($token) == 1) {
629                 unset($tokens[$ix]);
630             }
631         }
633         return array_values($tokens);
634     }
636     ////////////////////////////////////////////////////////////////////////////
638     /**
639      * Make sure that the given properties were set to some not-null value
640      *
641      * @param array $properties the list of properties
642      * @throws coding_exception
643      */
644     private function ensure_isset(array $properties) {
645         foreach ($properties as $property) {
646             if (!isset($this->$property)) {
647                 throw new coding_exception('The property "'.$property.'" is not set.');
648             }
649         }
650     }