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