Merge remote branch 'origin/master' into rubric
[moodle.git] / grade / grading / form / lib.php
CommitLineData
9b8550f8
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/**
21d37aa6
DM
19 * Common classes used by gradingform plugintypes are defined here
20 *
9b8550f8
DM
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/**
21d37aa6 30 * Grading method controller represents a plugin used in a particular area
9b8550f8 31 */
3e43eff5 32abstract class gradingform_controller {
9b8550f8 33
21d37aa6
DM
34 const DEFINITION_STATUS_WORKINPROGRESS = 0;
35 const DEFINITION_STATUS_PRIVATE = 1;
36 const DEFINITION_STATUS_PUBLIC = 2;
37
9b8550f8
DM
38 /** @var stdClass the context */
39 protected $context;
40
41 /** @var string the frankenstyle name of the component */
42 protected $component;
43
44 /** @var string the name of the gradable area */
45 protected $area;
46
47 /** @var int the id of the gradable area record */
48 protected $areaid;
49
fe817d87 50 /** @var stdClass|false the definition structure */
3e43eff5
DM
51 protected $definition;
52
9b8550f8
DM
53 /**
54 * Do not instantinate this directly, use {@link grading_manager::get_controller()}
55 *
fe817d87
DM
56 * @param stdClass $context the context of the form
57 * @param string $component the frankenstyle name of the component
58 * @param string $area the name of the gradable area
59 * @param int $areaid the id of the gradable area record
9b8550f8
DM
60 */
61 public function __construct(stdClass $context, $component, $area, $areaid) {
3e43eff5
DM
62 global $DB;
63
64 $this->context = $context;
fe817d87
DM
65 list($type, $name) = normalize_component($component);
66 $this->component = $type.'_'.$name;
3e43eff5
DM
67 $this->area = $area;
68 $this->areaid = $areaid;
69
70 $this->load_definition();
71 }
72
fe817d87
DM
73 /**
74 * @return stdClass controller context
75 */
76 public function get_context() {
77 return $this->context;
78 }
79
80 /**
81 * @return string gradable component name
82 */
83 public function get_component() {
84 return $this->component;
85 }
86
87 /**
88 * @return string gradable area name
89 */
90 public function get_area() {
91 return $this->area;
92 }
93
94 /**
95 * @return int gradable area id
96 */
97 public function get_areaid() {
98 return $this->areaid;
99 }
100
3e43eff5 101 /**
21d37aa6 102 * Is the grading form defined and released for usage by the given user?
3e43eff5 103 *
21d37aa6 104 * @param int $foruserid the id of the user who attempts to work with the form
3e43eff5
DM
105 * @return boolean
106 */
21d37aa6
DM
107 public function is_form_available($foruserid = null) {
108 global $USER;
109
110 if (is_null($foruserid)) {
111 $foruserid = $USER->id;
112 }
113
114 if (empty($this->definition)) {
115 return false;
116 }
117
118 if ($this->definition->status == self::DEFINITION_STATUS_PUBLIC) {
119 return true;
120 }
121
122 if ($this->definition->status == self::DEFINITION_STATUS_PRIVATE) {
123 if ($this->definition->usercreated == $foruserid) {
124 return true;
125 }
126 }
127
128 return false;
3e43eff5
DM
129 }
130
9b8550f8
DM
131 /**
132 * Extends the module settings navigation
133 *
134 * This function is called when the context for the page is an activity module with the
135 * FEATURE_ADVANCED_GRADING, the user has the permission moodle/grade:managegradingforms
136 * and there is an area with the active grading method set to the given plugin.
137 *
138 * @param settings_navigation $settingsnav {@link settings_navigation}
139 * @param navigation_node $node {@link navigation_node}
140 */
141 public function extend_settings_navigation(settings_navigation $settingsnav, navigation_node $node=null) {
142 // do not extend by default
143 }
3e43eff5
DM
144
145 /**
fe817d87 146 * Returns the grading form definition structure
3e43eff5 147 *
fe817d87 148 * @return stdClass|false definition data or false if the form is not defined yet
3e43eff5 149 */
fe817d87
DM
150 public function get_definition() {
151 if (is_null($this->definition)) {
152 $this->load_definition();
153 }
154 return $this->definition;
3e43eff5
DM
155 }
156
157 /**
fe817d87 158 * Saves the defintion data into the database
21d37aa6 159 *
fe817d87
DM
160 * The implementation in this base class stores the common data into the record
161 * into the {grading_definition} table. The plugins are likely to extend this
162 * and save their data into own tables, too.
21d37aa6 163 *
fe817d87
DM
164 * @param stdClass $definition data containing values for the {grading_definition} table
165 * @param int|null $usermodified optional userid of the author of the definition, defaults to the current user
21d37aa6
DM
166 */
167 public function update_definition(stdClass $definition, $usermodified = null) {
168 global $DB, $USER;
169
170 if (is_null($usermodified)) {
171 $usermodified = $USER->id;
172 }
173
fe817d87
DM
174 if (!empty($this->definition->id)) {
175 // prepare a record to be updated
176 $record = new stdClass();
177 // populate it with scalar values from the passed definition structure
178 foreach ($definition as $prop => $val) {
179 if (is_array($val) or is_object($val)) {
180 // probably plugin's data
181 continue;
182 }
183 $record->{$prop} = $val;
184 }
185 // make sure we do not override some crucial values by accident
186 if (!empty($record->id) and $record->id != $this->definition->id) {
187 throw new coding_exception('Attempting to update other definition record.');
188 }
189 $record->id = $this->definition->id;
190 unset($record->areaid);
191 unset($record->method);
192 unset($record->timecreated);
193 // set the modification flags
194 $record->timemodified = time();
195 $record->usermodified = $usermodified;
21d37aa6 196
fe817d87 197 $DB->update_record('grading_definitions', $record);
21d37aa6
DM
198
199 } else if ($this->definition === false) {
fe817d87
DM
200 // prepare a record to be inserted
201 $record = new stdClass();
202 // populate it with scalar values from the passed definition structure
203 foreach ($definition as $prop => $val) {
204 if (is_array($val) or is_object($val)) {
205 // probably plugin's data
206 continue;
207 }
208 $record->{$prop} = $val;
209 }
210 // make sure we do not override some crucial values by accident
211 if (!empty($record->id)) {
212 throw new coding_exception('Attempting to create a new record while there is already one existing.');
213 }
214 unset($record->id);
215 $record->areaid = $this->areaid;
216 $record->method = $this->get_method_name();
217 $record->timecreated = time();
218 $record->usercreated = $usermodified;
219 $record->timemodified = $definition->timecreated;
220 $record->usermodified = $definition->usercreated;
221 $record->status = self::DEFINITION_STATUS_WORKINPROGRESS;
21d37aa6
DM
222
223 $DB->insert_record('grading_definitions', $definition);
224
225 } else {
fe817d87 226 throw new coding_exception('Unknown status of the cached definition record.');
21d37aa6
DM
227 }
228 }
229
230 /**
231 * Makes sure there is a form instance for the given rater grading the given item
232 *
233 * Plugins will probably override/extend this and load additional data of how their
234 * forms are filled in one complex query.
235 *
236 * @todo this might actually become abstract method
237 * @param int $raterid
238 * @param int $itemid
239 * @return stdClass newly created or existing record from {grading_instances}
240 */
241 public function prepare_instance($raterid, $itemid) {
242 global $DB;
243
244 if (empty($this->definition)) {
245 throw new coding_exception('Attempting to prepare an instance of non-existing grading form');
246 }
247
248 $current = $DB->get_record('grading_instances', array(
249 'formid' => $this->definition->id,
250 'raterid' => $raterid,
251 'itemid' => $itemid), '*', IGNORE_MISSING);
252
253 if (empty($current)) {
254 $instance = new stdClass();
255 $instance->formid = $this->definition->id;
256 $instance->raterid = $raterid;
257 $instance->itemid = $itemid;
258 $instance->timemodified = time();
259 $instance->id = $DB->insert_record('grading_instances', $instance);
260 return $instance;
261
262 } else {
263 return $current;
264 }
265 }
266
fe817d87
DM
267 ////////////////////////////////////////////////////////////////////////////
268
269
21d37aa6
DM
270 /**
271 * Loads the form definition if it exists
3e43eff5 272 *
21d37aa6 273 * The default implementation just tries to load the record from the {grading_definitions}
3e43eff5
DM
274 * table. The plugins are likely to override this with a more complex query that loads
275 * all required data at once.
276 */
277 protected function load_definition() {
278 global $DB;
3e43eff5
DM
279 $this->definition = $DB->get_record('grading_definitions', array(
280 'areaid' => $this->areaid,
281 'method' => $this->get_method_name()), '*', IGNORE_MISSING);
282 }
21d37aa6
DM
283
284 /**
fe817d87
DM
285 * @return string the name of the grading method plugin, eg 'rubric'
286 * @see PARAM_PLUGIN
21d37aa6 287 */
fe817d87
DM
288 protected function get_method_name() {
289 if (preg_match('/^gradingform_([a-z][a-z0-9_]*[a-z0-9])_controller$/', get_class($this), $matches)) {
290 return $matches[1];
291 } else {
292 throw new coding_exception('Invalid class name');
293 }
21d37aa6
DM
294 }
295}