MDL-17827 workshop: initial check in of the files
[moodle.git] / mod / workshop / lib.php
CommitLineData
4eab2e7f
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/**
20 * Library of interface functions and constants for module workshop
21 *
22 * All the core Moodle functions, neeeded to allow the module to work
23 * integrated in Moodle should be placed here.
24 * All the workshop specific functions, needed to implement all the module
25 * logic, should go to locallib.php. This will help to save some memory when
26 * Moodle is performing actions across all modules.
27 *
28 * @package mod-workshop
29 * @copyright 2009 David Mudrak <david.mudrak@gmail.com>
30 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
31 */
32
33
34/**
35 * The internal codes of the anonymity levels
36 */
37define('WORKSHOP_ANONYMITY_NONE', 0); /* not anonymous */
38define('WORKSHOP_ANONYMITY_AUTHORS', 1); /* authors hidden from reviewers */
39define('WORKSHOP_ANONYMITY_REVIEWERS', 2); /* reviewers hidden from authors */
40define('WORKSHOP_ANONYMITY_BOTH', 3); /* fully anonymous */
41
42
43/**
44 * The internal codes of the example assessment modes
45 */
46define('WORKSHOP_EXAMPLES_VOLUNTARY', 0);
47define('WORKSHOP_EXAMPLES_BEFORE_SUBMISSION', 1);
48define('WORKSHOP_EXAMPLES_BEFORE_ASSESSMENT', 2);
49
50
51/**
52 * The internal codes of the required level of assessment similarity
53 */
54define('WORKSHOP_COMPARISON_VERYLOW', 0); /* f = 1.00 */
55define('WORKSHOP_COMPARISON_LOW', 1); /* f = 1.67 */
56define('WORKSHOP_COMPARISON_NORMAL', 2); /* f = 2.50 */
57define('WORKSHOP_COMPARISON_HIGH', 3); /* f = 3.00 */
58define('WORKSHOP_COMPARISON_VERYHIGH', 4); /* f = 5.00 */
59
60
61/**
62 * Given an object containing all the necessary data,
63 * (defined by the form in mod_form.php) this function
64 * will create a new instance and return the id number
65 * of the new instance.
66 *
67 * @param object $workshop An object from the form in mod_form.php
68 * @return int The id of the newly inserted workshop record
69 */
70function workshop_add_instance($workshop) {
71 global $DB;
72
73 $workshop->timecreated = time();
74 $workshop->timemodified = $workshop->timecreated;
75
76 return $DB->insert_record('workshop', $workshop);
77}
78
79
80/**
81 * Given an object containing all the necessary data,
82 * (defined by the form in mod_form.php) this function
83 * will update an existing instance with new data.
84 *
85 * @param object $workshop An object from the form in mod_form.php
86 * @return boolean Success/Fail
87 */
88function workshop_update_instance($workshop) {
89 global $DB;
90
91 $workshop->timemodified = time();
92 $workshop->id = $workshop->instance;
93
94 return $DB->update_record('workshop', $workshop);
95}
96
97
98/**
99 * Given an ID of an instance of this module,
100 * this function will permanently delete the instance
101 * and any data that depends on it.
102 *
103 * @param int $id Id of the module instance
104 * @return boolean Success/Failure
105 */
106function workshop_delete_instance($id) {
107 global $DB;
108
109 if (! $workshop = $DB->get_record('workshop', array('id' => $id))) {
110 return false;
111 }
112
113 $result = true;
114
115 # Delete any dependent records here #
116
117 if (! $DB->delete_records('workshop', array('id' => $workshop->id))) {
118 $result = false;
119 }
120
121 return $result;
122}
123
124
125/**
126 * Return a small object with summary information about what a
127 * user has done with a given particular instance of this module
128 * Used for user activity reports.
129 * $return->time = the time they did it
130 * $return->info = a short text description
131 *
132 * @return null
133 * @todo Finish documenting this function
134 */
135function workshop_user_outline($course, $user, $mod, $workshop) {
136 $return = new stdClass;
137 $return->time = 0;
138 $return->info = '';
139 return $return;
140}
141
142
143/**
144 * Print a detailed representation of what a user has done with
145 * a given particular instance of this module, for user activity reports.
146 *
147 * @return boolean
148 * @todo Finish documenting this function
149 */
150function workshop_user_complete($course, $user, $mod, $workshop) {
151 return true;
152}
153
154
155/**
156 * Given a course and a time, this module should find recent activity
157 * that has occurred in workshop activities and print it out.
158 * Return true if there was output, or false is there was none.
159 *
160 * @return boolean
161 * @todo Finish documenting this function
162 */
163function workshop_print_recent_activity($course, $isteacher, $timestart) {
164 return false; // True if anything was printed, otherwise false
165}
166
167
168/**
169 * Function to be run periodically according to the moodle cron
170 * This function searches for things that need to be done, such
171 * as sending out mail, toggling flags etc ...
172 *
173 * @return boolean
174 * @todo Finish documenting this function
175 **/
176function workshop_cron () {
177 return true;
178}
179
180
181/**
182 * Must return an array of user records (all data) who are participants
183 * for a given instance of workshop. Must include every user involved
184 * in the instance, independient of his role (student, teacher, admin...)
185 * See other modules as example.
186 *
187 * @param int $workshopid ID of an instance of this module
188 * @return mixed boolean/array of students
189 */
190function workshop_get_participants($workshopid) {
191 return false;
192}
193
194
195/**
196 * This function returns if a scale is being used by one workshop
197 * if it has support for grading and scales. Commented code should be
198 * modified if necessary. See forum, glossary or journal modules
199 * as reference.
200 *
201 * @param int $workshopid ID of an instance of this module
202 * @return mixed
203 * @todo Finish documenting this function
204 */
205function workshop_scale_used($workshopid, $scaleid) {
206 $return = false;
207
208 //$rec = get_record("workshop","id","$workshopid","scale","-$scaleid");
209 //
210 //if (!empty($rec) && !empty($scaleid)) {
211 // $return = true;
212 //}
213
214 return $return;
215}
216
217
218/**
219 * Checks if scale is being used by any instance of workshop.
220 * This function was added in 1.9
221 *
222 * This is used to find out if scale used anywhere
223 * @param $scaleid int
224 * @return boolean True if the scale is used by any workshop
225 */
226function workshop_scale_used_anywhere($scaleid) {
227 if ($scaleid and record_exists('workshop', 'grade', -$scaleid)) {
228 return true;
229 } else {
230 return false;
231 }
232}
233
234
235/**
236 * Execute post-install custom actions for the module
237 * This function was added in 1.9
238 *
239 * @return boolean true if success, false on error
240 */
241function workshop_install() {
242 return true;
243}
244
245
246/**
247 * Execute post-uninstall custom actions for the module
248 * This function was added in 1.9
249 *
250 * @return boolean true if success, false on error
251 */
252function workshop_uninstall() {
253 return true;
254}
255
256////////////////////////////////////////////////////////////////////////////////
257// Other functions needed by Moodle core follows. They can't be put into //
258// locallib.php because they are used by some core scripts (like modedit.php) //
259// where locallib.php is not included. //
260////////////////////////////////////////////////////////////////////////////////
261
262/**
263 * Return an array of numeric values that can be used as maximum grades
264 *
265 * Used at several places where maximum grade for submission and grade for
266 * assessment are defined via a HTML select form element. By default it returns
267 * an array 0, 1, 2, ..., 98, 99, 100.
268 *
269 * @access public
270 * @return array Array of integers
271 */
272function workshop_get_maxgrades() {
273
274 $grades = array();
275 for ($i=100; $i>=0; $i--) {
276 $grades[$i] = $i;
277 }
278 return $grades;
279}
280
281
282/**
283 * Return an array of possible numbers of assessments to be done
284 *
285 * Should always contain numbers 1, 2, 3, ... 10 and possibly others up to a reasonable value
286 *
287 * @return array Array of integers
288 */
289function workshop_get_numbers_of_assessments() {
290
291 $options = array();
292 $options[30] = 30;
293 $options[20] = 20;
294 $options[15] = 15;
295 for ($i=10; $i>0; $i--) {
296 $options[$i] = $i;
297 }
298 return $options;
299}
300
301
302/**
303 * Return an array of possible values for weight of teacher assessment
304 *
305 * @return array Array of integers 0, 1, 2, ..., 10
306 */
307function workshop_get_teacher_weights() {
308
309 $weights = array();
310 for ($i=10; $i>=0; $i--) {
311 $weights[$i] = $i;
312 }
313 return $weights;
314}
315
316
317/**
318 * Return an array of possible values of assessment dimension weight
319 *
320 * @return array Array of integers 0, 1, 2, ..., 16
321 */
322function workshop_get_dimension_weights() {
323
324 $weights = array();
325 for ($i=16; $i>=0; $i--) {
326 $weights[$i] = $i;
327 }
328 return $weights;
329}
330
331
332/**
333 * Return an array of the localized grading strategy names
334 *
335 * @access public
336 * $return array Array ['string' => 'string']
337 */
338function workshop_get_strategies() {
339
340 $installed = get_list_of_plugins('mod/workshop/grading');
341 $forms = array();
342 foreach ($installed as $strategy) {
343 $forms[$strategy] = get_string('strategy' . $strategy, 'workshop');
344 }
345
346 return $forms;
347}
348
349
350/**
351 * Return an array of available anonymity modes
352 *
353 * @return array Array 'anonymity DB code'=>'anonymity mode name'
354 */
355function workshop_get_anonymity_modes() {
356
357 $modes = array();
358 $modes[WORKSHOP_ANONYMITY_NONE] = get_string('anonymitynone', 'workshop');
359 $modes[WORKSHOP_ANONYMITY_AUTHORS] = get_string('anonymityauthors', 'workshop');
360 $modes[WORKSHOP_ANONYMITY_REVIEWERS] = get_string('anonymityreviewers', 'workshop');
361 $modes[WORKSHOP_ANONYMITY_BOTH] = get_string('anonymityboth', 'workshop');
362
363 return $modes;
364}
365
366
367/**
368 * Return an array of available example assessment modes
369 *
370 * @return array Array 'mode DB code'=>'mode name'
371 */
372function workshop_get_example_modes() {
373
374 $modes = array();
375 $modes[WORKSHOP_EXAMPLES_VOLUNTARY] = get_string('examplesvoluntary', 'workshop');
376 $modes[WORKSHOP_EXAMPLES_BEFORE_SUBMISSION] = get_string('examplesbeforesubmission', 'workshop');
377 $modes[WORKSHOP_EXAMPLES_BEFORE_ASSESSMENT] = get_string('examplesbeforeassessment', 'workshop');
378
379 return $modes;
380}
381
382
383/**
384 * Return array of assessment comparison levels
385 *
386 * The assessment comparison level influence how the grade for assessment is calculated.
387 * Each object in the returned array provides information about the name of the level
388 * and the value of the factor to be used in the calculation.
389 * The structure of the returned array is
390 * array[code int] of object (
391 * ->name string,
392 * ->value number,
393 * )
394 * where code if the integer code that is actually stored in the database.
395 *
396 * @return array Array of objects
397 */
398function workshop_get_comparison_levels() {
399
400 $levels = array();
401
402 $levels[WORKSHOP_COMPARISON_VERYHIGH] = new stdClass;
403 $levels[WORKSHOP_COMPARISON_VERYHIGH]->name = get_string('comparisonveryhigh', 'workshop');
404 $levels[WORKSHOP_COMPARISON_VERYHIGH]->value = 5.00;
405
406 $levels[WORKSHOP_COMPARISON_HIGH] = new stdClass;
407 $levels[WORKSHOP_COMPARISON_HIGH]->name = get_string('comparisonhigh', 'workshop');
408 $levels[WORKSHOP_COMPARISON_HIGH]->value = 3.00;
409
410 $levels[WORKSHOP_COMPARISON_NORMAL] = new stdClass;
411 $levels[WORKSHOP_COMPARISON_NORMAL]->name = get_string('comparisonnormal', 'workshop');
412 $levels[WORKSHOP_COMPARISON_NORMAL]->value = 2.50;
413
414 $levels[WORKSHOP_COMPARISON_LOW] = new stdClass;
415 $levels[WORKSHOP_COMPARISON_LOW]->name = get_string('comparisonlow', 'workshop');
416 $levels[WORKSHOP_COMPARISON_LOW]->value = 1.67;
417
418 $levels[WORKSHOP_COMPARISON_VERYLOW] = new stdClass;
419 $levels[WORKSHOP_COMPARISON_VERYLOW]->name = get_string('comparisonverylow', 'workshop');
420 $levels[WORKSHOP_COMPARISON_VERYLOW]->value = 1.00;
421
422 return $levels;
423}