MDL-57407 mod_data: Return ratings in mod_data_get_entry
[moodle.git] / mod / glossary / classes / external.php
CommitLineData
23da998f
CC
1<?php
2// This file is part of Moodle - http://moodle.org/
3//
4// Moodle is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// Moodle is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU General Public License for more details.
13//
14// You should have received a copy of the GNU General Public License
15// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
bf5bbe01 16
23da998f 17/**
bf5bbe01 18 * Glossary module external API.
23da998f
CC
19 *
20 * @package mod_glossary
21 * @category external
22 * @copyright 2015 Costantino Cito <ccito@cvaconsulting.com>
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
bf5bbe01 24 * @since Moodle 3.1
23da998f 25 */
d0d4372c
FM
26
27defined('MOODLE_INTERNAL') || die();
28
bf5bbe01 29require_once($CFG->libdir . '/externallib.php');
d0d4372c 30require_once($CFG->dirroot . '/mod/glossary/lib.php');
bf5bbe01 31
23da998f 32/**
bf5bbe01 33 * Glossary module external functions.
23da998f
CC
34 *
35 * @package mod_glossary
36 * @category external
37 * @copyright 2015 Costantino Cito <ccito@cvaconsulting.com>
38 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
bf5bbe01 39 * @since Moodle 3.1
23da998f
CC
40 */
41class mod_glossary_external extends external_api {
bf5bbe01 42
fe11f9a4
FM
43 /**
44 * Get the browse modes from the display format.
45 *
46 * This returns some of the terms that can be used when reporting a glossary being viewed.
47 *
48 * @param string $format The display format of the glossary.
49 * @return array Containing some of all of the following: letter, cat, date, author.
50 */
a4d9adcb 51 protected static function get_browse_modes_from_display_format($format) {
fe11f9a4
FM
52 global $DB;
53
a4d9adcb 54 $formats = array();
fe11f9a4 55 $dp = $DB->get_record('glossary_formats', array('name' => $format), '*', IGNORE_MISSING);
a4d9adcb
FM
56 if ($dp) {
57 $formats = glossary_get_visible_tabs($dp);
58 }
fe11f9a4
FM
59
60 // Always add 'letter'.
61 $modes = array('letter');
62
63 if (in_array('category', $formats)) {
64 $modes[] = 'cat';
65 }
66 if (in_array('date', $formats)) {
67 $modes[] = 'date';
68 }
69 if (in_array('author', $formats)) {
70 $modes[] = 'author';
71 }
72
73 return $modes;
74 }
75
76 /**
77 * Get the return value of an entry.
78 *
9cafa794 79 * @param bool $includecat Whether the definition should include category info.
fe11f9a4
FM
80 * @return external_definition
81 */
a4d9adcb 82 protected static function get_entry_return_structure($includecat = false) {
9cafa794 83 $params = array(
fe11f9a4
FM
84 'id' => new external_value(PARAM_INT, 'The entry ID'),
85 'glossaryid' => new external_value(PARAM_INT, 'The glossary ID'),
86 'userid' => new external_value(PARAM_INT, 'Author ID'),
a4d9adcb 87 'userfullname' => new external_value(PARAM_NOTAGS, 'Author full name'),
fe11f9a4
FM
88 'userpictureurl' => new external_value(PARAM_URL, 'Author picture'),
89 'concept' => new external_value(PARAM_RAW, 'The concept'),
90 'definition' => new external_value(PARAM_RAW, 'The definition'),
91 'definitionformat' => new external_format_value('definition'),
92 'definitiontrust' => new external_value(PARAM_BOOL, 'The definition trust flag'),
c8743f62 93 'definitioninlinefiles' => new external_files('entry definition inline files', VALUE_OPTIONAL),
fe11f9a4 94 'attachment' => new external_value(PARAM_BOOL, 'Whether or not the entry has attachments'),
14590070 95 'attachments' => new external_files('attachments', VALUE_OPTIONAL),
fe11f9a4
FM
96 'timecreated' => new external_value(PARAM_INT, 'Time created'),
97 'timemodified' => new external_value(PARAM_INT, 'Time modified'),
98 'teacherentry' => new external_value(PARAM_BOOL, 'The entry was created by a teacher, or equivalent.'),
99 'sourceglossaryid' => new external_value(PARAM_INT, 'The source glossary ID'),
100 'usedynalink' => new external_value(PARAM_BOOL, 'Whether the concept should be automatically linked'),
101 'casesensitive' => new external_value(PARAM_BOOL, 'When true, the matching is case sensitive'),
102 'fullmatch' => new external_value(PARAM_BOOL, 'When true, the matching is done on full words only'),
103 'approved' => new external_value(PARAM_BOOL, 'Whether the entry was approved'),
9cafa794
FM
104 );
105
106 if ($includecat) {
107 $params['categoryid'] = new external_value(PARAM_INT, 'The category ID. This may be' .
108 ' \''. GLOSSARY_SHOW_NOT_CATEGORISED . '\' when the entry is not categorised', VALUE_DEFAULT,
109 GLOSSARY_SHOW_NOT_CATEGORISED);
110 $params['categoryname'] = new external_value(PARAM_RAW, 'The category name. May be empty when the entry is' .
111 ' not categorised, or the request was limited to one category.', VALUE_DEFAULT, '');
112 }
113
114 return new external_single_structure($params);
fe11f9a4
FM
115 }
116
117 /**
118 * Fill in an entry object.
119 *
120 * This adds additional required fields for the external function to return.
121 *
122 * @param stdClass $entry The entry.
123 * @param context $context The context the entry belongs to.
124 * @return void
125 */
a4d9adcb 126 protected static function fill_entry_details($entry, $context) {
fe11f9a4
FM
127 global $PAGE;
128 $canviewfullnames = has_capability('moodle/site:viewfullnames', $context);
129
130 // Format concept and definition.
131 $entry->concept = external_format_string($entry->concept, $context->id);
132 list($entry->definition, $entry->definitionformat) = external_format_text($entry->definition, $entry->definitionformat,
133 $context->id, 'mod_glossary', 'entry', $entry->id);
134
135 // Author details.
3bb15852 136 $user = mod_glossary_entry_query_builder::get_user_from_record($entry);
fe11f9a4
FM
137 $userpicture = new user_picture($user);
138 $userpicture->size = 1;
139 $entry->userfullname = fullname($user, $canviewfullnames);
140 $entry->userpictureurl = $userpicture->get_url($PAGE)->out(false);
141
142 // Fetch attachments.
143 $entry->attachment = !empty($entry->attachment) ? 1 : 0;
144 $entry->attachments = array();
145 if ($entry->attachment) {
1a354b81 146 $entry->attachments = external_util::get_area_files($context->id, 'mod_glossary', 'attachment', $entry->id);
fe11f9a4 147 }
c8743f62
JL
148 $definitioninlinefiles = external_util::get_area_files($context->id, 'mod_glossary', 'entry', $entry->id);
149 if (!empty($definitioninlinefiles)) {
150 $entry->definitioninlinefiles = $definitioninlinefiles;
151 }
fe11f9a4
FM
152 }
153
21e30022
FM
154 /**
155 * Validate a glossary via ID.
156 *
157 * @param int $id The glossary ID.
158 * @return array Contains glossary, context, course and cm.
159 */
a4d9adcb 160 protected static function validate_glossary($id) {
21e30022
FM
161 global $DB;
162 $glossary = $DB->get_record('glossary', array('id' => $id), '*', MUST_EXIST);
163 list($course, $cm) = get_course_and_cm_from_instance($glossary, 'glossary');
164 $context = context_module::instance($cm->id);
165 self::validate_context($context);
166 return array($glossary, $context, $course, $cm);
167 }
168
23da998f
CC
169 /**
170 * Describes the parameters for get_glossaries_by_courses.
171 *
9db43c73 172 * @return external_function_parameters
bf5bbe01 173 * @since Moodle 3.1
23da998f
CC
174 */
175 public static function get_glossaries_by_courses_parameters() {
176 return new external_function_parameters (
177 array(
178 'courseids' => new external_multiple_structure(
179 new external_value(PARAM_INT, 'course id'),
bf5bbe01 180 'Array of course IDs', VALUE_DEFAULT, array()
23da998f
CC
181 ),
182 )
183 );
184 }
bf5bbe01 185
23da998f 186 /**
bf5bbe01 187 * Returns a list of glossaries in a provided list of courses.
23da998f 188 *
bf5bbe01
FM
189 * If no list is provided all glossaries that the user can view will be returned.
190 *
191 * @param array $courseids the course IDs.
192 * @return array of glossaries
193 * @since Moodle 3.1
23da998f
CC
194 */
195 public static function get_glossaries_by_courses($courseids = array()) {
23da998f 196 $params = self::validate_parameters(self::get_glossaries_by_courses_parameters(), array('courseids' => $courseids));
bf5bbe01 197
23da998f 198 $warnings = array();
bf5bbe01
FM
199 $courses = array();
200 $courseids = $params['courseids'];
201
202 if (empty($courseids)) {
23da998f
CC
203 $courses = enrol_get_my_courses();
204 $courseids = array_keys($courses);
205 }
bf5bbe01 206
23da998f 207 // Array to store the glossaries to return.
bf5bbe01 208 $glossaries = array();
fe11f9a4 209 $modes = array();
bf5bbe01 210
23da998f
CC
211 // Ensure there are courseids to loop through.
212 if (!empty($courseids)) {
bf5bbe01
FM
213 list($courses, $warnings) = external_util::validate_courses($courseids, $courses);
214
215 // Get the glossaries in these courses, this function checks users visibility permissions.
216 $glossaries = get_all_instances_in_courses('glossary', $courses);
23da998f 217 foreach ($glossaries as $glossary) {
bf5bbe01
FM
218 $context = context_module::instance($glossary->coursemodule);
219 $glossary->name = external_format_string($glossary->name, $context->id);
220 list($glossary->intro, $glossary->introformat) = external_format_text($glossary->intro, $glossary->introformat,
221 $context->id, 'mod_glossary', 'intro', null);
7ef49bd3 222 $glossary->introfiles = external_util::get_area_files($context->id, 'mod_glossary', 'intro', false, false);
fe11f9a4
FM
223
224 // Make sure we have a number of entries per page.
225 if (!$glossary->entbypage) {
226 $glossary->entbypage = $CFG->glossary_entbypage;
227 }
228
229 // Add the list of browsing modes.
230 if (!isset($modes[$glossary->displayformat])) {
231 $modes[$glossary->displayformat] = self::get_browse_modes_from_display_format($glossary->displayformat);
232 }
233 $glossary->browsemodes = $modes[$glossary->displayformat];
fad980b2 234 $glossary->canaddentry = has_capability('mod/glossary:write', $context) ? 1 : 0;
23da998f
CC
235 }
236 }
bf5bbe01 237
23da998f 238 $result = array();
bf5bbe01 239 $result['glossaries'] = $glossaries;
23da998f
CC
240 $result['warnings'] = $warnings;
241 return $result;
242 }
bf5bbe01 243
23da998f
CC
244 /**
245 * Describes the get_glossaries_by_courses return value.
246 *
247 * @return external_single_structure
bf5bbe01 248 * @since Moodle 3.1
23da998f
CC
249 */
250 public static function get_glossaries_by_courses_returns() {
bf5bbe01
FM
251 return new external_single_structure(array(
252 'glossaries' => new external_multiple_structure(
253 new external_single_structure(array(
254 'id' => new external_value(PARAM_INT, 'Glossary id'),
255 'coursemodule' => new external_value(PARAM_INT, 'Course module id'),
256 'course' => new external_value(PARAM_INT, 'Course id'),
257 'name' => new external_value(PARAM_RAW, 'Glossary name'),
258 'intro' => new external_value(PARAM_RAW, 'The Glossary intro'),
259 'introformat' => new external_format_value('intro'),
7ef49bd3 260 'introfiles' => new external_files('Files in the introduction text', VALUE_OPTIONAL),
bf5bbe01
FM
261 'allowduplicatedentries' => new external_value(PARAM_INT, 'If enabled, multiple entries can have the' .
262 ' same concept name'),
263 'displayformat' => new external_value(PARAM_TEXT, 'Display format type'),
264 'mainglossary' => new external_value(PARAM_INT, 'If enabled this glossary is a main glossary.'),
265 'showspecial' => new external_value(PARAM_INT, 'If enabled, participants can browse the glossary by' .
266 ' special characters, such as @ and #'),
267 'showalphabet' => new external_value(PARAM_INT, 'If enabled, participants can browse the glossary by' .
268 ' letters of the alphabet'),
269 'showall' => new external_value(PARAM_INT, 'If enabled, participants can browse all entries at once'),
270 'allowcomments' => new external_value(PARAM_INT, 'If enabled, all participants with permission to' .
271 ' create comments will be able to add comments to glossary entries'),
272 'allowprintview' => new external_value(PARAM_INT, 'If enabled, students are provided with a link to a' .
273 ' printer-friendly version of the glossary. The link is always available to teachers'),
274 'usedynalink' => new external_value(PARAM_INT, 'If site-wide glossary auto-linking has been enabled' .
275 ' by an administrator and this checkbox is ticked, the entry will be automatically linked' .
276 ' wherever the concept words and phrases appear throughout the rest of the course.'),
277 'defaultapproval' => new external_value(PARAM_INT, 'If set to no, entries require approving by a' .
278 ' teacher before they are viewable by everyone.'),
279 'approvaldisplayformat' => new external_value(PARAM_TEXT, 'When approving glossary items you may wish' .
280 ' to use a different display format'),
281 'globalglossary' => new external_value(PARAM_INT, ''),
282 'entbypage' => new external_value(PARAM_INT, 'Entries shown per page'),
283 'editalways' => new external_value(PARAM_INT, 'Always allow editing'),
284 'rsstype' => new external_value(PARAM_INT, 'To enable the RSS feed for this activity, select either' .
285 ' concepts with author or concepts without author to be included in the feed'),
286 'rssarticles' => new external_value(PARAM_INT, 'This setting specifies the number of glossary entry' .
287 ' concepts to include in the RSS feed. Between 5 and 20 generally acceptable'),
288 'assessed' => new external_value(PARAM_INT, 'Aggregate type'),
289 'assesstimestart' => new external_value(PARAM_INT, 'Restrict rating to items created after this'),
290 'assesstimefinish' => new external_value(PARAM_INT, 'Restrict rating to items created before this'),
291 'scale' => new external_value(PARAM_INT, 'Scale ID'),
292 'timecreated' => new external_value(PARAM_INT, 'Time created'),
293 'timemodified' => new external_value(PARAM_INT, 'Time modified'),
294 'completionentries' => new external_value(PARAM_INT, 'Number of entries to complete'),
295 'section' => new external_value(PARAM_INT, 'Section'),
296 'visible' => new external_value(PARAM_INT, 'Visible'),
297 'groupmode' => new external_value(PARAM_INT, 'Group mode'),
298 'groupingid' => new external_value(PARAM_INT, 'Grouping ID'),
fe11f9a4
FM
299 'browsemodes' => new external_multiple_structure(
300 new external_value(PARAM_ALPHA, 'Modes of browsing allowed')
fad980b2
JL
301 ),
302 'canaddentry' => new external_value(PARAM_INT, 'Whether the user can add a new entry', VALUE_OPTIONAL),
bf5bbe01
FM
303 ), 'Glossaries')
304 ),
305 'warnings' => new external_warnings())
23da998f
CC
306 );
307 }
d0d4372c
FM
308
309 /**
310 * Returns the description of the external function parameters.
311 *
312 * @return external_function_parameters
313 * @since Moodle 3.1
314 */
315 public static function view_glossary_parameters() {
316 return new external_function_parameters(array(
317 'id' => new external_value(PARAM_INT, 'Glossary instance ID'),
318 'mode' => new external_value(PARAM_ALPHA, 'The mode in which the glossary is viewed'),
319 ));
320 }
321
322 /**
323 * Notify that the course module was viewed.
324 *
325 * @param int $id The glossary instance ID.
a4d9adcb 326 * @param string $mode The view mode.
d0d4372c
FM
327 * @return array of warnings and status result
328 * @since Moodle 3.1
329 * @throws moodle_exception
330 */
331 public static function view_glossary($id, $mode) {
d0d4372c
FM
332 $params = self::validate_parameters(self::view_glossary_parameters(), array(
333 'id' => $id,
334 'mode' => $mode
335 ));
336 $id = $params['id'];
337 $mode = $params['mode'];
338 $warnings = array();
339
21e30022
FM
340 // Get and validate the glossary.
341 list($glossary, $context, $course, $cm) = self::validate_glossary($id);
d0d4372c
FM
342
343 // Trigger module viewed event.
344 glossary_view($glossary, $course, $cm, $context, $mode);
345
346 return array(
347 'status' => true,
348 'warnings' => $warnings
349 );
350 }
351
352 /**
353 * Returns the description of the external function return value.
354 *
355 * @return external_description
356 * @since Moodle 3.1
357 */
358 public static function view_glossary_returns() {
359 return new external_single_structure(array(
360 'status' => new external_value(PARAM_BOOL, 'True on success'),
361 'warnings' => new external_warnings()
362 ));
363 }
364
61fce284
FM
365 /**
366 * Returns the description of the external function parameters.
367 *
368 * @return external_function_parameters
369 * @since Moodle 3.1
370 */
371 public static function view_entry_parameters() {
372 return new external_function_parameters(array(
373 'id' => new external_value(PARAM_INT, 'Glossary entry ID'),
374 ));
375 }
376
377 /**
378 * Notify that the entry was viewed.
379 *
380 * @param int $id The entry ID.
381 * @return array of warnings and status result
382 * @since Moodle 3.1
383 * @throws moodle_exception
a4d9adcb 384 * @throws invalid_parameter_exception
61fce284
FM
385 */
386 public static function view_entry($id) {
387 global $DB, $USER;
388
389 $params = self::validate_parameters(self::view_entry_parameters(), array('id' => $id));
390 $id = $params['id'];
391 $warnings = array();
392
21e30022 393 // Get and validate the glossary.
61fce284 394 $entry = $DB->get_record('glossary_entries', array('id' => $id), '*', MUST_EXIST);
e2be9961 395 list($glossary, $context, $course, $cm) = self::validate_glossary($entry->glossaryid);
61fce284 396
e2be9961 397 if (!glossary_can_view_entry($entry, $cm)) {
61fce284
FM
398 throw new invalid_parameter_exception('invalidentry');
399 }
400
401 // Trigger view.
402 glossary_entry_view($entry, $context);
403
404 return array(
405 'status' => true,
406 'warnings' => $warnings
407 );
408 }
409
410 /**
411 * Returns the description of the external function return value.
412 *
413 * @return external_description
414 * @since Moodle 3.1
415 */
416 public static function view_entry_returns() {
417 return new external_single_structure(array(
418 'status' => new external_value(PARAM_BOOL, 'True on success'),
419 'warnings' => new external_warnings()
420 ));
421 }
422
fe11f9a4
FM
423 /**
424 * Returns the description of the external function parameters.
425 *
426 * @return external_function_parameters
427 * @since Moodle 3.1
428 */
429 public static function get_entries_by_letter_parameters() {
430 return new external_function_parameters(array(
431 'id' => new external_value(PARAM_INT, 'Glossary entry ID'),
432 'letter' => new external_value(PARAM_ALPHA, 'A letter, or either keywords: \'ALL\' or \'SPECIAL\'.'),
433 'from' => new external_value(PARAM_INT, 'Start returning records from here', VALUE_DEFAULT, 0),
434 'limit' => new external_value(PARAM_INT, 'Number of records to return', VALUE_DEFAULT, 20),
435 'options' => new external_single_structure(array(
436 'includenotapproved' => new external_value(PARAM_BOOL, 'When false, includes the non-approved entries created by' .
437 ' the user. When true, also includes the ones that the user has the permission to approve.', VALUE_DEFAULT, 0)
438 ), 'An array of options', VALUE_DEFAULT, array())
439 ));
440 }
441
442 /**
443 * Browse a glossary entries by letter.
444 *
445 * @param int $id The glossary ID.
446 * @param string $letter A letter, or a special keyword.
447 * @param int $from Start returning records from here.
448 * @param int $limit Number of records to return.
449 * @param array $options Array of options.
a4d9adcb 450 * @return array Containing count, entries and warnings.
fe11f9a4
FM
451 * @since Moodle 3.1
452 * @throws moodle_exception
a4d9adcb 453 * @throws invalid_parameter_exception
fe11f9a4 454 */
a4d9adcb 455 public static function get_entries_by_letter($id, $letter, $from, $limit, $options) {
fe11f9a4
FM
456 $params = self::validate_parameters(self::get_entries_by_letter_parameters(), array(
457 'id' => $id,
458 'letter' => $letter,
459 'from' => $from,
460 'limit' => $limit,
461 'options' => $options,
462 ));
463 $id = $params['id'];
464 $letter = $params['letter'];
465 $from = $params['from'];
466 $limit = $params['limit'];
467 $options = $params['options'];
468 $warnings = array();
469
21e30022
FM
470 // Get and validate the glossary.
471 list($glossary, $context) = self::validate_glossary($id);
fe11f9a4
FM
472
473 // Validate the mode.
474 $modes = self::get_browse_modes_from_display_format($glossary->displayformat);
475 if (!in_array('letter', $modes)) {
476 throw new invalid_parameter_exception('invalidbrowsemode');
477 }
478
8382bb4e
FM
479 $entries = array();
480 list($records, $count) = glossary_get_entries_by_letter($glossary, $context, $letter, $from, $limit, $options);
481 foreach ($records as $key => $record) {
482 self::fill_entry_details($record, $context);
483 $entries[] = $record;
fe11f9a4
FM
484 }
485
486 return array(
487 'count' => $count,
488 'entries' => $entries,
489 'warnings' => $warnings
490 );
491 }
492
493 /**
494 * Returns the description of the external function return value.
495 *
496 * @return external_description
497 * @since Moodle 3.1
498 */
499 public static function get_entries_by_letter_returns() {
500 return new external_single_structure(array(
501 'count' => new external_value(PARAM_INT, 'The total number of records matching the request.'),
502 'entries' => new external_multiple_structure(
503 self::get_entry_return_structure()
504 ),
505 'warnings' => new external_warnings()
506 ));
507 }
6a273d5a
FM
508
509 /**
510 * Returns the description of the external function parameters.
511 *
512 * @return external_function_parameters
513 * @since Moodle 3.1
514 */
515 public static function get_entries_by_date_parameters() {
516 return new external_function_parameters(array(
517 'id' => new external_value(PARAM_INT, 'Glossary entry ID'),
518 'order' => new external_value(PARAM_ALPHA, 'Order the records by: \'CREATION\' or \'UPDATE\'.',
519 VALUE_DEFAULT, 'UPDATE'),
520 'sort' => new external_value(PARAM_ALPHA, 'The direction of the order: \'ASC\' or \'DESC\'', VALUE_DEFAULT, 'DESC'),
521 'from' => new external_value(PARAM_INT, 'Start returning records from here', VALUE_DEFAULT, 0),
522 'limit' => new external_value(PARAM_INT, 'Number of records to return', VALUE_DEFAULT, 20),
523 'options' => new external_single_structure(array(
524 'includenotapproved' => new external_value(PARAM_BOOL, 'When false, includes the non-approved entries created by' .
525 ' the user. When true, also includes the ones that the user has the permission to approve.', VALUE_DEFAULT, 0)
526 ), 'An array of options', VALUE_DEFAULT, array())
527 ));
528 }
529
530 /**
531 * Browse a glossary entries by date.
532 *
533 * @param int $id The glossary ID.
534 * @param string $order The way to order the records.
535 * @param string $sort The direction of the order.
536 * @param int $from Start returning records from here.
537 * @param int $limit Number of records to return.
538 * @param array $options Array of options.
a4d9adcb 539 * @return array Containing count, entries and warnings.
6a273d5a
FM
540 * @since Moodle 3.1
541 * @throws moodle_exception
a4d9adcb 542 * @throws invalid_parameter_exception
6a273d5a 543 */
a4d9adcb 544 public static function get_entries_by_date($id, $order, $sort, $from, $limit, $options) {
6a273d5a
FM
545 $params = self::validate_parameters(self::get_entries_by_date_parameters(), array(
546 'id' => $id,
547 'order' => core_text::strtoupper($order),
548 'sort' => core_text::strtoupper($sort),
549 'from' => $from,
550 'limit' => $limit,
551 'options' => $options,
552 ));
553 $id = $params['id'];
554 $order = $params['order'];
555 $sort = $params['sort'];
556 $from = $params['from'];
557 $limit = $params['limit'];
558 $options = $params['options'];
559 $warnings = array();
560
561 if (!in_array($order, array('CREATION', 'UPDATE'))) {
562 throw new invalid_parameter_exception('invalidorder');
563 } else if (!in_array($sort, array('ASC', 'DESC'))) {
564 throw new invalid_parameter_exception('invalidsort');
565 }
566
21e30022
FM
567 // Get and validate the glossary.
568 list($glossary, $context) = self::validate_glossary($id);
6a273d5a
FM
569
570 // Validate the mode.
571 $modes = self::get_browse_modes_from_display_format($glossary->displayformat);
572 if (!in_array('date', $modes)) {
573 throw new invalid_parameter_exception('invalidbrowsemode');
574 }
575
8382bb4e
FM
576 $entries = array();
577 list($records, $count) = glossary_get_entries_by_date($glossary, $context, $order, $sort, $from, $limit, $options);
578 foreach ($records as $key => $record) {
579 self::fill_entry_details($record, $context);
580 $entries[] = $record;
6a273d5a
FM
581 }
582
583 return array(
584 'count' => $count,
585 'entries' => $entries,
586 'warnings' => $warnings
587 );
588 }
589
590 /**
591 * Returns the description of the external function return value.
592 *
593 * @return external_description
594 * @since Moodle 3.1
595 */
596 public static function get_entries_by_date_returns() {
597 return new external_single_structure(array(
598 'count' => new external_value(PARAM_INT, 'The total number of records matching the request.'),
599 'entries' => new external_multiple_structure(
600 self::get_entry_return_structure()
601 ),
602 'warnings' => new external_warnings()
603 ));
604 }
605
efb7a0a9
FM
606 /**
607 * Returns the description of the external function parameters.
608 *
609 * @return external_function_parameters
610 * @since Moodle 3.1
611 */
612 public static function get_categories_parameters() {
613 return new external_function_parameters(array(
a4d9adcb 614 'id' => new external_value(PARAM_INT, 'The glossary ID'),
efb7a0a9
FM
615 'from' => new external_value(PARAM_INT, 'Start returning records from here', VALUE_DEFAULT, 0),
616 'limit' => new external_value(PARAM_INT, 'Number of records to return', VALUE_DEFAULT, 20)
617 ));
618 }
619
620 /**
621 * Get the categories of a glossary.
622 *
623 * @param int $id The glossary ID.
624 * @param int $from Start returning records from here.
625 * @param int $limit Number of records to return.
a4d9adcb 626 * @return array Containing count, categories and warnings.
efb7a0a9
FM
627 * @since Moodle 3.1
628 * @throws moodle_exception
629 */
a4d9adcb 630 public static function get_categories($id, $from, $limit) {
efb7a0a9
FM
631 $params = self::validate_parameters(self::get_categories_parameters(), array(
632 'id' => $id,
633 'from' => $from,
634 'limit' => $limit
635 ));
636 $id = $params['id'];
637 $from = $params['from'];
638 $limit = $params['limit'];
639 $warnings = array();
640
21e30022
FM
641 // Get and validate the glossary.
642 list($glossary, $context) = self::validate_glossary($id);
efb7a0a9
FM
643
644 // Fetch the categories.
8382bb4e
FM
645 $categories = array();
646 list($records, $count) = glossary_get_categories($glossary, $from, $limit);
647 foreach ($records as $category) {
efb7a0a9 648 $category->name = external_format_string($category->name, $context->id);
8382bb4e 649 $categories[] = $category;
efb7a0a9
FM
650 }
651
652 return array(
653 'count' => $count,
654 'categories' => $categories,
655 'warnings' => array(),
656 );
657 }
658
659 /**
660 * Returns the description of the external function return value.
661 *
662 * @return external_description
663 * @since Moodle 3.1
664 */
665 public static function get_categories_returns() {
666 return new external_single_structure(array(
667 'count' => new external_value(PARAM_INT, 'The total number of records.'),
668 'categories' => new external_multiple_structure(
669 new external_single_structure(array(
670 'id' => new external_value(PARAM_INT, 'The category ID'),
671 'glossaryid' => new external_value(PARAM_INT, 'The glossary ID'),
672 'name' => new external_value(PARAM_RAW, 'The name of the category'),
673 'usedynalink' => new external_value(PARAM_BOOL, 'Whether the category is automatically linked'),
674 ))
675 ),
676 'warnings' => new external_warnings()
677 ));
678 }
679
9cafa794
FM
680 /**
681 * Returns the description of the external function parameters.
682 *
683 * @return external_function_parameters
684 * @since Moodle 3.1
685 */
686 public static function get_entries_by_category_parameters() {
687 return new external_function_parameters(array(
a4d9adcb 688 'id' => new external_value(PARAM_INT, 'The glossary ID.'),
9cafa794
FM
689 'categoryid' => new external_value(PARAM_INT, 'The category ID. Use \'' . GLOSSARY_SHOW_ALL_CATEGORIES . '\' for all' .
690 ' categories, or \'' . GLOSSARY_SHOW_NOT_CATEGORISED . '\' for uncategorised entries.'),
691 'from' => new external_value(PARAM_INT, 'Start returning records from here', VALUE_DEFAULT, 0),
692 'limit' => new external_value(PARAM_INT, 'Number of records to return', VALUE_DEFAULT, 20),
693 'options' => new external_single_structure(array(
694 'includenotapproved' => new external_value(PARAM_BOOL, 'When false, includes the non-approved entries created by' .
695 ' the user. When true, also includes the ones that the user has the permission to approve.', VALUE_DEFAULT, 0)
696 ), 'An array of options', VALUE_DEFAULT, array())
697 ));
698 }
699
700 /**
701 * Browse a glossary entries by category.
702 *
703 * @param int $id The glossary ID.
704 * @param int $categoryid The category ID.
705 * @param int $from Start returning records from here.
706 * @param int $limit Number of records to return.
707 * @param array $options Array of options.
a4d9adcb 708 * @return array Containing count, entries and warnings.
9cafa794
FM
709 * @since Moodle 3.1
710 * @throws moodle_exception
a4d9adcb 711 * @throws invalid_parameter_exception
9cafa794 712 */
a4d9adcb
FM
713 public static function get_entries_by_category($id, $categoryid, $from, $limit, $options) {
714 global $DB;
9cafa794
FM
715
716 $params = self::validate_parameters(self::get_entries_by_category_parameters(), array(
717 'id' => $id,
718 'categoryid' => $categoryid,
719 'from' => $from,
720 'limit' => $limit,
721 'options' => $options,
722 ));
723 $id = $params['id'];
724 $categoryid = $params['categoryid'];
725 $from = $params['from'];
726 $limit = $params['limit'];
727 $options = $params['options'];
728 $warnings = array();
729
21e30022
FM
730 // Get and validate the glossary.
731 list($glossary, $context) = self::validate_glossary($id);
9cafa794
FM
732
733 // Validate the mode.
734 $modes = self::get_browse_modes_from_display_format($glossary->displayformat);
735 if (!in_array('cat', $modes)) {
736 throw new invalid_parameter_exception('invalidbrowsemode');
737 }
738
739 // Validate the category.
740 if (in_array($categoryid, array(GLOSSARY_SHOW_ALL_CATEGORIES, GLOSSARY_SHOW_NOT_CATEGORISED))) {
741 // All good.
a4d9adcb 742 } else if (!$DB->record_exists('glossary_categories', array('id' => $categoryid, 'glossaryid' => $id))) {
9cafa794
FM
743 throw new invalid_parameter_exception('invalidcategory');
744 }
745
9cafa794 746 // Fetching the entries.
8382bb4e
FM
747 $entries = array();
748 list($records, $count) = glossary_get_entries_by_category($glossary, $context, $categoryid, $from, $limit, $options);
749 foreach ($records as $key => $record) {
750 self::fill_entry_details($record, $context);
751 if ($record->categoryid === null) {
752 $record->categoryid = GLOSSARY_SHOW_NOT_CATEGORISED;
9cafa794 753 }
8382bb4e
FM
754 if (isset($record->categoryname)) {
755 $record->categoryname = external_format_string($record->categoryname, $context->id);
9cafa794 756 }
8382bb4e 757 $entries[] = $record;
9cafa794
FM
758 }
759
760 return array(
761 'count' => $count,
762 'entries' => $entries,
763 'warnings' => $warnings
764 );
765 }
766
767 /**
768 * Returns the description of the external function return value.
769 *
770 * @return external_description
771 * @since Moodle 3.1
772 */
773 public static function get_entries_by_category_returns() {
774 return new external_single_structure(array(
775 'count' => new external_value(PARAM_INT, 'The total number of records matching the request.'),
776 'entries' => new external_multiple_structure(
777 self::get_entry_return_structure(true)
778 ),
779 'warnings' => new external_warnings()
780 ));
781 }
06c8bd22
FM
782
783 /**
784 * Returns the description of the external function parameters.
785 *
786 * @return external_function_parameters
787 * @since Moodle 3.1
788 */
789 public static function get_authors_parameters() {
790 return new external_function_parameters(array(
791 'id' => new external_value(PARAM_INT, 'Glossary entry ID'),
792 'from' => new external_value(PARAM_INT, 'Start returning records from here', VALUE_DEFAULT, 0),
793 'limit' => new external_value(PARAM_INT, 'Number of records to return', VALUE_DEFAULT, 20),
794 'options' => new external_single_structure(array(
795 'includenotapproved' => new external_value(PARAM_BOOL, 'When false, includes self even if all of their entries' .
796 ' require approval. When true, also includes authors only having entries pending approval.', VALUE_DEFAULT, 0)
797 ), 'An array of options', VALUE_DEFAULT, array())
798 ));
799 }
800
801 /**
802 * Get the authors of a glossary.
803 *
804 * @param int $id The glossary ID.
805 * @param int $from Start returning records from here.
806 * @param int $limit Number of records to return.
807 * @param array $options Array of options.
a4d9adcb 808 * @return array Containing count, authors and warnings.
06c8bd22
FM
809 * @since Moodle 3.1
810 * @throws moodle_exception
811 */
a4d9adcb
FM
812 public static function get_authors($id, $from, $limit, $options) {
813 global $PAGE;
06c8bd22
FM
814
815 $params = self::validate_parameters(self::get_authors_parameters(), array(
816 'id' => $id,
817 'from' => $from,
818 'limit' => $limit,
819 'options' => $options,
820 ));
821 $id = $params['id'];
822 $from = $params['from'];
823 $limit = $params['limit'];
824 $options = $params['options'];
825 $warnings = array();
826
21e30022
FM
827 // Get and validate the glossary.
828 list($glossary, $context) = self::validate_glossary($id);
06c8bd22 829
8382bb4e
FM
830 // Fetching the entries.
831 list($users, $count) = glossary_get_authors($glossary, $context, $limit, $from, $options);
06c8bd22
FM
832
833 $canviewfullnames = has_capability('moodle/site:viewfullnames', $context);
06c8bd22
FM
834 foreach ($users as $user) {
835 $userpicture = new user_picture($user);
836 $userpicture->size = 1;
837
838 $author = new stdClass();
839 $author->id = $user->id;
840 $author->fullname = fullname($user, $canviewfullnames);
841 $author->pictureurl = $userpicture->get_url($PAGE)->out(false);
842 $authors[] = $author;
843 }
844 $users->close();
845
846 return array(
847 'count' => $count,
848 'authors' => $authors,
849 'warnings' => array(),
850 );
851 }
852
853 /**
854 * Returns the description of the external function return value.
855 *
856 * @return external_description
857 * @since Moodle 3.1
858 */
859 public static function get_authors_returns() {
860 return new external_single_structure(array(
861 'count' => new external_value(PARAM_INT, 'The total number of records.'),
862 'authors' => new external_multiple_structure(
863 new external_single_structure(array(
864 'id' => new external_value(PARAM_INT, 'The user ID'),
865 'fullname' => new external_value(PARAM_NOTAGS, 'The fullname'),
866 'pictureurl' => new external_value(PARAM_URL, 'The picture URL'),
867 ))
868 ),
869 'warnings' => new external_warnings()
870 ));
871 }
f7d9cd23
FM
872
873 /**
874 * Returns the description of the external function parameters.
875 *
876 * @return external_function_parameters
877 * @since Moodle 3.1
878 */
879 public static function get_entries_by_author_parameters() {
880 return new external_function_parameters(array(
881 'id' => new external_value(PARAM_INT, 'Glossary entry ID'),
882 'letter' => new external_value(PARAM_ALPHA, 'First letter of firstname or lastname, or either keywords:'
883 . ' \'ALL\' or \'SPECIAL\'.'),
884 'field' => new external_value(PARAM_ALPHA, 'Search and order using: \'FIRSTNAME\' or \'LASTNAME\'', VALUE_DEFAULT,
885 'LASTNAME'),
886 'sort' => new external_value(PARAM_ALPHA, 'The direction of the order: \'ASC\' or \'DESC\'', VALUE_DEFAULT, 'ASC'),
887 'from' => new external_value(PARAM_INT, 'Start returning records from here', VALUE_DEFAULT, 0),
888 'limit' => new external_value(PARAM_INT, 'Number of records to return', VALUE_DEFAULT, 20),
889 'options' => new external_single_structure(array(
890 'includenotapproved' => new external_value(PARAM_BOOL, 'When false, includes the non-approved entries created by' .
891 ' the user. When true, also includes the ones that the user has the permission to approve.', VALUE_DEFAULT, 0)
892 ), 'An array of options', VALUE_DEFAULT, array())
893 ));
894 }
895
896 /**
897 * Browse a glossary entries by author.
898 *
899 * @param int $id The glossary ID.
900 * @param string $letter A letter, or a special keyword.
901 * @param string $field The field to search from.
902 * @param string $sort The direction of the order.
903 * @param int $from Start returning records from here.
904 * @param int $limit Number of records to return.
905 * @param array $options Array of options.
a4d9adcb 906 * @return array Containing count, entries and warnings.
f7d9cd23
FM
907 * @since Moodle 3.1
908 * @throws moodle_exception
a4d9adcb 909 * @throws invalid_parameter_exception
f7d9cd23 910 */
a4d9adcb 911 public static function get_entries_by_author($id, $letter, $field, $sort, $from, $limit, $options) {
f7d9cd23
FM
912 $params = self::validate_parameters(self::get_entries_by_author_parameters(), array(
913 'id' => $id,
914 'letter' => $letter,
915 'field' => core_text::strtoupper($field),
916 'sort' => core_text::strtoupper($sort),
917 'from' => $from,
918 'limit' => $limit,
919 'options' => $options,
920 ));
921 $id = $params['id'];
922 $letter = $params['letter'];
923 $field = $params['field'];
924 $sort = $params['sort'];
925 $from = $params['from'];
926 $limit = $params['limit'];
927 $options = $params['options'];
928 $warnings = array();
929
930 if (!in_array($field, array('FIRSTNAME', 'LASTNAME'))) {
931 throw new invalid_parameter_exception('invalidfield');
932 } else if (!in_array($sort, array('ASC', 'DESC'))) {
933 throw new invalid_parameter_exception('invalidsort');
934 }
935
21e30022
FM
936 // Get and validate the glossary.
937 list($glossary, $context) = self::validate_glossary($id);
f7d9cd23
FM
938
939 // Validate the mode.
940 $modes = self::get_browse_modes_from_display_format($glossary->displayformat);
941 if (!in_array('author', $modes)) {
942 throw new invalid_parameter_exception('invalidbrowsemode');
943 }
944
f7d9cd23 945 // Fetching the entries.
8382bb4e
FM
946 $entries = array();
947 list($records, $count) = glossary_get_entries_by_author($glossary, $context, $letter, $field, $sort, $from, $limit,
948 $options);
949 foreach ($records as $key => $record) {
950 self::fill_entry_details($record, $context);
951 $entries[] = $record;
f7d9cd23
FM
952 }
953
954 return array(
955 'count' => $count,
956 'entries' => $entries,
957 'warnings' => $warnings
958 );
959 }
960
961 /**
962 * Returns the description of the external function return value.
963 *
964 * @return external_description
965 * @since Moodle 3.1
966 */
967 public static function get_entries_by_author_returns() {
968 return new external_single_structure(array(
969 'count' => new external_value(PARAM_INT, 'The total number of records matching the request.'),
970 'entries' => new external_multiple_structure(
971 self::get_entry_return_structure()
972 ),
973 'warnings' => new external_warnings()
974 ));
975 }
e70f58cd
FM
976
977 /**
978 * Returns the description of the external function parameters.
979 *
980 * @return external_function_parameters
981 * @since Moodle 3.1
982 */
983 public static function get_entries_by_author_id_parameters() {
984 return new external_function_parameters(array(
985 'id' => new external_value(PARAM_INT, 'Glossary entry ID'),
986 'authorid' => new external_value(PARAM_INT, 'The author ID'),
987 'order' => new external_value(PARAM_ALPHA, 'Order by: \'CONCEPT\', \'CREATION\' or \'UPDATE\'', VALUE_DEFAULT,
988 'CONCEPT'),
989 'sort' => new external_value(PARAM_ALPHA, 'The direction of the order: \'ASC\' or \'DESC\'', VALUE_DEFAULT, 'ASC'),
990 'from' => new external_value(PARAM_INT, 'Start returning records from here', VALUE_DEFAULT, 0),
991 'limit' => new external_value(PARAM_INT, 'Number of records to return', VALUE_DEFAULT, 20),
992 'options' => new external_single_structure(array(
993 'includenotapproved' => new external_value(PARAM_BOOL, 'When false, includes the non-approved entries created by' .
994 ' the user. When true, also includes the ones that the user has the permission to approve.', VALUE_DEFAULT, 0)
995 ), 'An array of options', VALUE_DEFAULT, array())
996 ));
997 }
998
999 /**
1000 * Browse a glossary entries by author.
1001 *
1002 * @param int $id The glossary ID.
1003 * @param int $authorid The author ID.
1004 * @param string $order The way to order the results.
1005 * @param string $sort The direction of the order.
1006 * @param int $from Start returning records from here.
1007 * @param int $limit Number of records to return.
1008 * @param array $options Array of options.
a4d9adcb 1009 * @return array Containing count, entries and warnings.
e70f58cd
FM
1010 * @since Moodle 3.1
1011 * @throws moodle_exception
a4d9adcb 1012 * @throws invalid_parameter_exception
e70f58cd 1013 */
a4d9adcb 1014 public static function get_entries_by_author_id($id, $authorid, $order, $sort, $from, $limit, $options) {
e70f58cd
FM
1015 $params = self::validate_parameters(self::get_entries_by_author_id_parameters(), array(
1016 'id' => $id,
1017 'authorid' => $authorid,
1018 'order' => core_text::strtoupper($order),
1019 'sort' => core_text::strtoupper($sort),
1020 'from' => $from,
1021 'limit' => $limit,
1022 'options' => $options,
1023 ));
1024 $id = $params['id'];
1025 $authorid = $params['authorid'];
1026 $order = $params['order'];
1027 $sort = $params['sort'];
1028 $from = $params['from'];
1029 $limit = $params['limit'];
1030 $options = $params['options'];
1031 $warnings = array();
1032
1033 if (!in_array($order, array('CONCEPT', 'CREATION', 'UPDATE'))) {
1034 throw new invalid_parameter_exception('invalidorder');
1035 } else if (!in_array($sort, array('ASC', 'DESC'))) {
1036 throw new invalid_parameter_exception('invalidsort');
1037 }
1038
21e30022
FM
1039 // Get and validate the glossary.
1040 list($glossary, $context) = self::validate_glossary($id);
e70f58cd
FM
1041
1042 // Validate the mode.
1043 $modes = self::get_browse_modes_from_display_format($glossary->displayformat);
1044 if (!in_array('author', $modes)) {
1045 throw new invalid_parameter_exception('invalidbrowsemode');
1046 }
1047
e70f58cd 1048 // Fetching the entries.
8382bb4e
FM
1049 $entries = array();
1050 list($records, $count) = glossary_get_entries_by_author_id($glossary, $context, $authorid, $order, $sort, $from,
1051 $limit, $options);
1052 foreach ($records as $key => $record) {
1053 self::fill_entry_details($record, $context);
1054 $entries[] = $record;
e70f58cd
FM
1055 }
1056
1057 return array(
1058 'count' => $count,
1059 'entries' => $entries,
1060 'warnings' => $warnings
1061 );
1062 }
1063
1064 /**
1065 * Returns the description of the external function return value.
1066 *
1067 * @return external_description
1068 * @since Moodle 3.1
1069 */
1070 public static function get_entries_by_author_id_returns() {
1071 return new external_single_structure(array(
1072 'count' => new external_value(PARAM_INT, 'The total number of records matching the request.'),
1073 'entries' => new external_multiple_structure(
1074 self::get_entry_return_structure()
1075 ),
1076 'warnings' => new external_warnings()
1077 ));
1078 }
24777f7a
FM
1079
1080 /**
1081 * Returns the description of the external function parameters.
1082 *
1083 * @return external_function_parameters
1084 * @since Moodle 3.1
1085 */
1086 public static function get_entries_by_search_parameters() {
1087 return new external_function_parameters(array(
1088 'id' => new external_value(PARAM_INT, 'Glossary entry ID'),
1089 'query' => new external_value(PARAM_NOTAGS, 'The query string'),
1090 'fullsearch' => new external_value(PARAM_BOOL, 'The query', VALUE_DEFAULT, 1),
1091 'order' => new external_value(PARAM_ALPHA, 'Order by: \'CONCEPT\', \'CREATION\' or \'UPDATE\'', VALUE_DEFAULT,
1092 'CONCEPT'),
1093 'sort' => new external_value(PARAM_ALPHA, 'The direction of the order: \'ASC\' or \'DESC\'', VALUE_DEFAULT, 'ASC'),
1094 'from' => new external_value(PARAM_INT, 'Start returning records from here', VALUE_DEFAULT, 0),
1095 'limit' => new external_value(PARAM_INT, 'Number of records to return', VALUE_DEFAULT, 20),
1096 'options' => new external_single_structure(array(
1097 'includenotapproved' => new external_value(PARAM_BOOL, 'When false, includes the non-approved entries created by' .
1098 ' the user. When true, also includes the ones that the user has the permission to approve.', VALUE_DEFAULT, 0)
1099 ), 'An array of options', VALUE_DEFAULT, array())
1100 ));
1101 }
1102
1103 /**
1104 * Browse a glossary entries using the search.
1105 *
1106 * @param int $id The glossary ID.
1107 * @param string $query The search query.
1108 * @param bool $fullsearch Whether or not full search is required.
1109 * @param string $order The way to order the results.
1110 * @param string $sort The direction of the order.
1111 * @param int $from Start returning records from here.
1112 * @param int $limit Number of records to return.
1113 * @param array $options Array of options.
a4d9adcb 1114 * @return array Containing count, entries and warnings.
24777f7a
FM
1115 * @since Moodle 3.1
1116 * @throws moodle_exception
a4d9adcb 1117 * @throws invalid_parameter_exception
24777f7a 1118 */
a4d9adcb 1119 public static function get_entries_by_search($id, $query, $fullsearch, $order, $sort, $from, $limit, $options) {
24777f7a
FM
1120 $params = self::validate_parameters(self::get_entries_by_search_parameters(), array(
1121 'id' => $id,
1122 'query' => $query,
1123 'fullsearch' => $fullsearch,
1124 'order' => core_text::strtoupper($order),
1125 'sort' => core_text::strtoupper($sort),
1126 'from' => $from,
1127 'limit' => $limit,
1128 'options' => $options,
1129 ));
1130 $id = $params['id'];
1131 $query = $params['query'];
1132 $fullsearch = $params['fullsearch'];
1133 $order = $params['order'];
1134 $sort = $params['sort'];
1135 $from = $params['from'];
1136 $limit = $params['limit'];
1137 $options = $params['options'];
1138 $warnings = array();
1139
1140 if (!in_array($order, array('CONCEPT', 'CREATION', 'UPDATE'))) {
1141 throw new invalid_parameter_exception('invalidorder');
1142 } else if (!in_array($sort, array('ASC', 'DESC'))) {
1143 throw new invalid_parameter_exception('invalidsort');
1144 }
1145
1146 // Get and validate the glossary.
1147 list($glossary, $context) = self::validate_glossary($id);
1148
1149 // Fetching the entries.
1150 $entries = array();
1151 list($records, $count) = glossary_get_entries_by_search($glossary, $context, $query, $fullsearch, $order, $sort, $from,
1152 $limit, $options);
1153 foreach ($records as $key => $record) {
1154 self::fill_entry_details($record, $context);
1155 $entries[] = $record;
1156 }
24777f7a
FM
1157
1158 return array(
1159 'count' => $count,
1160 'entries' => $entries,
1161 'warnings' => $warnings
1162 );
1163 }
1164
1165 /**
1166 * Returns the description of the external function return value.
1167 *
1168 * @return external_description
1169 * @since Moodle 3.1
1170 */
1171 public static function get_entries_by_search_returns() {
1172 return new external_single_structure(array(
1173 'count' => new external_value(PARAM_INT, 'The total number of records matching the request.'),
93e122e0
FM
1174 'entries' => new external_multiple_structure(
1175 self::get_entry_return_structure()
1176 ),
1177 'warnings' => new external_warnings()
1178 ));
1179 }
1180
1181 /**
1182 * Returns the description of the external function parameters.
1183 *
1184 * @return external_function_parameters
1185 * @since Moodle 3.1
1186 */
1187 public static function get_entries_by_term_parameters() {
1188 return new external_function_parameters(array(
1189 'id' => new external_value(PARAM_INT, 'Glossary entry ID'),
1190 'term' => new external_value(PARAM_NOTAGS, 'The entry concept, or alias'),
1191 'from' => new external_value(PARAM_INT, 'Start returning records from here', VALUE_DEFAULT, 0),
1192 'limit' => new external_value(PARAM_INT, 'Number of records to return', VALUE_DEFAULT, 20),
1193 'options' => new external_single_structure(array(
1194 'includenotapproved' => new external_value(PARAM_BOOL, 'When false, includes the non-approved entries created by' .
1195 ' the user. When true, also includes the ones that the user has the permission to approve.', VALUE_DEFAULT, 0)
1196 ), 'An array of options', VALUE_DEFAULT, array())
1197 ));
1198 }
1199
1200 /**
1201 * Browse a glossary entries using a term matching the concept or alias.
1202 *
1203 * @param int $id The glossary ID.
1204 * @param string $term The term.
1205 * @param int $from Start returning records from here.
1206 * @param int $limit Number of records to return.
1207 * @param array $options Array of options.
a4d9adcb 1208 * @return array Containing count, entries and warnings.
93e122e0
FM
1209 * @since Moodle 3.1
1210 * @throws moodle_exception
1211 */
a4d9adcb 1212 public static function get_entries_by_term($id, $term, $from, $limit, $options) {
93e122e0
FM
1213 $params = self::validate_parameters(self::get_entries_by_term_parameters(), array(
1214 'id' => $id,
1215 'term' => $term,
1216 'from' => $from,
1217 'limit' => $limit,
1218 'options' => $options,
1219 ));
1220 $id = $params['id'];
1221 $term = $params['term'];
1222 $from = $params['from'];
1223 $limit = $params['limit'];
1224 $options = $params['options'];
1225 $warnings = array();
1226
1227 // Get and validate the glossary.
1228 list($glossary, $context) = self::validate_glossary($id);
1229
1230 // Fetching the entries.
1231 $entries = array();
1232 list($records, $count) = glossary_get_entries_by_term($glossary, $context, $term, $from, $limit, $options);
1233 foreach ($records as $key => $record) {
1234 self::fill_entry_details($record, $context);
1235 $entries[] = $record;
1236 }
93e122e0
FM
1237
1238 return array(
1239 'count' => $count,
1240 'entries' => $entries,
1241 'warnings' => $warnings
1242 );
1243 }
1244
1245 /**
1246 * Returns the description of the external function return value.
1247 *
1248 * @return external_description
1249 * @since Moodle 3.1
1250 */
1251 public static function get_entries_by_term_returns() {
1252 return new external_single_structure(array(
1253 'count' => new external_value(PARAM_INT, 'The total number of records matching the request.'),
c242e3f4
FM
1254 'entries' => new external_multiple_structure(
1255 self::get_entry_return_structure()
1256 ),
1257 'warnings' => new external_warnings()
1258 ));
1259 }
1260
1261 /**
1262 * Returns the description of the external function parameters.
1263 *
1264 * @return external_function_parameters
1265 * @since Moodle 3.1
1266 */
1267 public static function get_entries_to_approve_parameters() {
1268 return new external_function_parameters(array(
1269 'id' => new external_value(PARAM_INT, 'Glossary entry ID'),
1270 'letter' => new external_value(PARAM_ALPHA, 'A letter, or either keywords: \'ALL\' or \'SPECIAL\'.'),
1271 'order' => new external_value(PARAM_ALPHA, 'Order by: \'CONCEPT\', \'CREATION\' or \'UPDATE\'', VALUE_DEFAULT,
1272 'CONCEPT'),
1273 'sort' => new external_value(PARAM_ALPHA, 'The direction of the order: \'ASC\' or \'DESC\'', VALUE_DEFAULT, 'ASC'),
1274 'from' => new external_value(PARAM_INT, 'Start returning records from here', VALUE_DEFAULT, 0),
1275 'limit' => new external_value(PARAM_INT, 'Number of records to return', VALUE_DEFAULT, 20),
1276 'options' => new external_single_structure(array(), 'An array of options', VALUE_DEFAULT, array())
1277 ));
1278 }
1279
1280 /**
1281 * Browse a glossary entries using a term matching the concept or alias.
1282 *
1283 * @param int $id The glossary ID.
1284 * @param string $letter A letter, or a special keyword.
1285 * @param string $order The way to order the records.
1286 * @param string $sort The direction of the order.
1287 * @param int $from Start returning records from here.
1288 * @param int $limit Number of records to return.
a4d9adcb 1289 * @return array Containing count, entries and warnings.
c242e3f4
FM
1290 * @since Moodle 3.1
1291 * @throws moodle_exception
1292 */
a4d9adcb 1293 public static function get_entries_to_approve($id, $letter, $order, $sort, $from, $limit) {
c242e3f4
FM
1294 $params = self::validate_parameters(self::get_entries_to_approve_parameters(), array(
1295 'id' => $id,
1296 'letter' => $letter,
1297 'order' => $order,
1298 'sort' => $sort,
1299 'from' => $from,
1300 'limit' => $limit
1301 ));
1302 $id = $params['id'];
1303 $letter = $params['letter'];
1304 $order = $params['order'];
1305 $sort = $params['sort'];
1306 $from = $params['from'];
1307 $limit = $params['limit'];
1308 $warnings = array();
1309
1310 // Get and validate the glossary.
1311 list($glossary, $context) = self::validate_glossary($id);
1312
1313 // Check the permissions.
1314 require_capability('mod/glossary:approve', $context);
1315
1316 // Fetching the entries.
1317 $entries = array();
1318 list($records, $count) = glossary_get_entries_to_approve($glossary, $context, $letter, $order, $sort, $from, $limit);
1319 foreach ($records as $key => $record) {
1320 self::fill_entry_details($record, $context);
1321 $entries[] = $record;
1322 }
c242e3f4
FM
1323
1324 return array(
1325 'count' => $count,
1326 'entries' => $entries,
1327 'warnings' => $warnings
1328 );
1329 }
1330
1331 /**
1332 * Returns the description of the external function return value.
1333 *
1334 * @return external_description
1335 * @since Moodle 3.1
1336 */
1337 public static function get_entries_to_approve_returns() {
1338 return new external_single_structure(array(
1339 'count' => new external_value(PARAM_INT, 'The total number of records matching the request.'),
24777f7a
FM
1340 'entries' => new external_multiple_structure(
1341 self::get_entry_return_structure()
1342 ),
1343 'warnings' => new external_warnings()
1344 ));
1345 }
08d7954f
FM
1346
1347 /**
1348 * Returns the description of the external function parameters.
1349 *
1350 * @return external_function_parameters
1351 * @since Moodle 3.1
1352 */
1353 public static function get_entry_by_id_parameters() {
1354 return new external_function_parameters(array(
1355 'id' => new external_value(PARAM_INT, 'Glossary entry ID'),
1356 ));
1357 }
1358
1359 /**
1360 * Get an entry.
1361 *
1362 * @param int $id The entry ID.
a4d9adcb 1363 * @return array Containing entry and warnings.
08d7954f
FM
1364 * @since Moodle 3.1
1365 * @throws moodle_exception
a4d9adcb 1366 * @throws invalid_parameter_exception
08d7954f
FM
1367 */
1368 public static function get_entry_by_id($id) {
1369 global $DB, $USER;
1370
1371 $params = self::validate_parameters(self::get_entry_by_id_parameters(), array('id' => $id));
1372 $id = $params['id'];
1373 $warnings = array();
1374
1375 // Get and validate the glossary.
1376 $entry = $DB->get_record('glossary_entries', array('id' => $id), '*', MUST_EXIST);
1377 list($glossary, $context) = self::validate_glossary($entry->glossaryid);
1378
1379 if (empty($entry->approved) && $entry->userid != $USER->id && !has_capability('mod/glossary:approve', $context)) {
1380 throw new invalid_parameter_exception('invalidentry');
1381 }
1382
1383 $entry = glossary_get_entry_by_id($id);
1384 self::fill_entry_details($entry, $context);
1385
1386 return array(
1387 'entry' => $entry,
1388 'warnings' => $warnings
1389 );
1390 }
1391
1392 /**
1393 * Returns the description of the external function return value.
1394 *
1395 * @return external_description
1396 * @since Moodle 3.1
1397 */
1398 public static function get_entry_by_id_returns() {
1399 return new external_single_structure(array(
1400 'entry' => self::get_entry_return_structure(),
1401 'warnings' => new external_warnings()
1402 ));
1403 }
1404
f0e1808f
JL
1405 /**
1406 * Returns the description of the external function parameters.
1407 *
1408 * @return external_function_parameters
1409 * @since Moodle 3.2
1410 */
1411 public static function add_entry_parameters() {
1412 return new external_function_parameters(array(
1413 'glossaryid' => new external_value(PARAM_INT, 'Glossary id'),
1414 'concept' => new external_value(PARAM_TEXT, 'Glossary concept'),
ef75a648 1415 'definition' => new external_value(PARAM_RAW, 'Glossary concept definition'),
f0e1808f
JL
1416 'definitionformat' => new external_format_value('definition'),
1417 'options' => new external_multiple_structure (
1418 new external_single_structure(
1419 array(
1420 'name' => new external_value(PARAM_ALPHANUM,
1421 'The allowed keys (value format) are:
1422 inlineattachmentsid (int); the draft file area id for inline attachments
1423 attachmentsid (int); the draft file area id for attachments
1424 categories (comma separated int); comma separated category ids
1425 aliases (comma separated str); comma separated aliases
1426 usedynalink (bool); whether the entry should be automatically linked.
1427 casesensitive (bool); whether the entry is case sensitive.
1428 fullmatch (bool); whether to match whole words only.'),
1429 'value' => new external_value(PARAM_RAW, 'the value of the option (validated inside the function)')
1430 )
1431 ), 'Optional settings', VALUE_DEFAULT, array()
1432 )
1433 ));
1434 }
1435
1436
1437 /**
1438 * Add a new entry to a given glossary.
1439 *
1440 * @param int $glossaryid the glosary id
1441 * @param string $concept the glossary concept
1442 * @param string $definition the concept definition
1443 * @param int $definitionformat the concept definition format
1444 * @param array $options additional settings
1445 * @return array Containing entry and warnings.
1446 * @since Moodle 3.2
1447 * @throws moodle_exception
1448 * @throws invalid_parameter_exception
1449 */
1450 public static function add_entry($glossaryid, $concept, $definition, $definitionformat, $options = array()) {
1451 global $CFG;
1452
1453 $params = self::validate_parameters(self::add_entry_parameters(), array(
1454 'glossaryid' => $glossaryid,
1455 'concept' => $concept,
1456 'definition' => $definition,
1457 'definitionformat' => $definitionformat,
1458 'options' => $options,
1459 ));
1460 $warnings = array();
1461
1462 // Get and validate the glossary.
1463 list($glossary, $context, $course, $cm) = self::validate_glossary($params['glossaryid']);
1464 require_capability('mod/glossary:write', $context);
1465
1466 if (!$glossary->allowduplicatedentries) {
1467 if (glossary_concept_exists($glossary, $params['concept'])) {
1468 throw new moodle_exception('errconceptalreadyexists', 'glossary');
1469 }
1470 }
1471
1472 // Prepare the entry object.
1473 $entry = new stdClass;
1474 $entry->id = null;
1475 $entry->aliases = '';
1476 $entry->usedynalink = $CFG->glossary_linkentries;
1477 $entry->casesensitive = $CFG->glossary_casesensitive;
1478 $entry->fullmatch = $CFG->glossary_fullmatch;
1479 $entry->concept = $params['concept'];
1480 $entry->definition_editor = array(
1481 'text' => $params['definition'],
1482 'format' => $params['definitionformat'],
1483 );
1484 // Options.
1485 foreach ($params['options'] as $option) {
1486 $name = trim($option['name']);
1487 switch ($name) {
1488 case 'inlineattachmentsid':
1489 $entry->definition_editor['itemid'] = clean_param($option['value'], PARAM_INT);
1490 break;
1491 case 'attachmentsid':
1492 $entry->attachment_filemanager = clean_param($option['value'], PARAM_INT);
1493 break;
1494 case 'categories':
1495 $entry->categories = clean_param($option['value'], PARAM_SEQUENCE);
1496 $entry->categories = explode(',', $entry->categories);
1497 break;
1498 case 'aliases':
1499 $entry->aliases = clean_param($option['value'], PARAM_NOTAGS);
1500 // Convert to the expected format.
1501 $entry->aliases = str_replace(",", "\n", $entry->aliases);
1502 break;
1503 case 'usedynalink':
1504 case 'casesensitive':
1505 case 'fullmatch':
1506 // Only allow if linking is enabled.
1507 if ($glossary->usedynalink) {
1508 $entry->{$name} = clean_param($option['value'], PARAM_BOOL);
1509 }
1510 break;
1511 default:
1512 throw new moodle_exception('errorinvalidparam', 'webservice', '', $name);
1513 }
1514 }
1515
1516 $entry = glossary_edit_entry($entry, $course, $cm, $glossary, $context);
1517
1518 return array(
1519 'entryid' => $entry->id,
1520 'warnings' => $warnings
1521 );
1522 }
1523
1524 /**
1525 * Returns the description of the external function return value.
1526 *
1527 * @return external_description
1528 * @since Moodle 3.2
1529 */
1530 public static function add_entry_returns() {
1531 return new external_single_structure(array(
1532 'entryid' => new external_value(PARAM_INT, 'New glossary entry ID'),
1533 'warnings' => new external_warnings()
1534 ));
1535 }
1536
23da998f 1537}