MDL-54941 glossary: Correct variable naming for entry files
[moodle.git] / mod / glossary / classes / external.php
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/>.
17 /**
18  * Glossary module external API.
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
24  * @since      Moodle 3.1
25  */
27 defined('MOODLE_INTERNAL') || die();
29 require_once($CFG->libdir . '/externallib.php');
30 require_once($CFG->dirroot . '/mod/glossary/lib.php');
32 /**
33  * Glossary module external functions.
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
39  * @since      Moodle 3.1
40  */
41 class mod_glossary_external extends external_api {
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      */
51     protected static function get_browse_modes_from_display_format($format) {
52         global $DB;
54         $formats = array();
55         $dp = $DB->get_record('glossary_formats', array('name' => $format), '*', IGNORE_MISSING);
56         if ($dp) {
57             $formats = glossary_get_visible_tabs($dp);
58         }
60         // Always add 'letter'.
61         $modes = array('letter');
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         }
73         return $modes;
74     }
76     /**
77      * Get the return value of an entry.
78      *
79      * @param bool $includecat Whether the definition should include category info.
80      * @return external_definition
81      */
82     protected static function get_entry_return_structure($includecat = false) {
83         $params = array(
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'),
87             'userfullname' => new external_value(PARAM_NOTAGS, 'Author full name'),
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'),
94             'attachments' => new external_files('attachments', VALUE_OPTIONAL),
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'),
103         );
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         }
113         return new external_single_structure($params);
114     }
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      */
125     protected static function fill_entry_details($entry, $context) {
126         global $PAGE;
127         $canviewfullnames = has_capability('moodle/site:viewfullnames', $context);
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);
134         // Author details.
135         $user = mod_glossary_entry_query_builder::get_user_from_record($entry);
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);
141         // Fetch attachments.
142         $entry->attachment = !empty($entry->attachment) ? 1 : 0;
143         $entry->attachments = array();
144         if ($entry->attachment) {
145             $entry->attachments = external_util::get_area_files($context->id, 'mod_glossary', 'attachment', $entry->id);
146         }
147     }
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      */
155     protected static function validate_glossary($id) {
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     }
164     /**
165      * Describes the parameters for get_glossaries_by_courses.
166      *
167      * @return external_external_function_parameters
168      * @since Moodle 3.1
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'),
175                     'Array of course IDs', VALUE_DEFAULT, array()
176                 ),
177             )
178         );
179     }
181     /**
182      * Returns a list of glossaries in a provided list of courses.
183      *
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
189      */
190     public static function get_glossaries_by_courses($courseids = array()) {
191         $params = self::validate_parameters(self::get_glossaries_by_courses_parameters(), array('courseids' => $courseids));
193         $warnings = array();
194         $courses = array();
195         $courseids = $params['courseids'];
197         if (empty($courseids)) {
198             $courses = enrol_get_my_courses();
199             $courseids = array_keys($courses);
200         }
202         // Array to store the glossaries to return.
203         $glossaries = array();
204         $modes = array();
206         // Ensure there are courseids to loop through.
207         if (!empty($courseids)) {
208             list($courses, $warnings) = external_util::validate_courses($courseids, $courses);
210             // Get the glossaries in these courses, this function checks users visibility permissions.
211             $glossaries = get_all_instances_in_courses('glossary', $courses);
212             foreach ($glossaries as $glossary) {
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);
217                 $glossary->introfiles = external_util::get_area_files($context->id, 'mod_glossary', 'intro', false, false);
219                 // Make sure we have a number of entries per page.
220                 if (!$glossary->entbypage) {
221                     $glossary->entbypage = $CFG->glossary_entbypage;
222                 }
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];
229             }
230         }
232         $result = array();
233         $result['glossaries'] = $glossaries;
234         $result['warnings'] = $warnings;
235         return $result;
236     }
238     /**
239      * Describes the get_glossaries_by_courses return value.
240      *
241      * @return external_single_structure
242      * @since Moodle 3.1
243      */
244     public static function get_glossaries_by_courses_returns() {
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'),
254                     'introfiles' => new external_files('Files in the introduction text', VALUE_OPTIONAL),
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'),
293                     'browsemodes' => new external_multiple_structure(
294                         new external_value(PARAM_ALPHA, 'Modes of browsing allowed')
295                     )
296                 ), 'Glossaries')
297             ),
298             'warnings' => new external_warnings())
299         );
300     }
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     }
315     /**
316      * Notify that the course module was viewed.
317      *
318      * @param int $id The glossary instance ID.
319      * @param string $mode The view mode.
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) {
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();
333         // Get and validate the glossary.
334         list($glossary, $context, $course, $cm) = self::validate_glossary($id);
336         // Trigger module viewed event.
337         glossary_view($glossary, $course, $cm, $context, $mode);
339         return array(
340             'status' => true,
341             'warnings' => $warnings
342         );
343     }
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     }
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     }
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
377      * @throws invalid_parameter_exception
378      */
379     public static function view_entry($id) {
380         global $DB, $USER;
382         $params = self::validate_parameters(self::view_entry_parameters(), array('id' => $id));
383         $id = $params['id'];
384         $warnings = array();
386         // Get and validate the glossary.
387         $entry = $DB->get_record('glossary_entries', array('id' => $id), '*', MUST_EXIST);
388         list($glossary, $context, $course, $cm) = self::validate_glossary($entry->glossaryid);
390         if (!glossary_can_view_entry($entry, $cm)) {
391             throw new invalid_parameter_exception('invalidentry');
392         }
394         // Trigger view.
395         glossary_entry_view($entry, $context);
397         return array(
398             'status' => true,
399             'warnings' => $warnings
400         );
401     }
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     }
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     }
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.
443      * @return array Containing count, entries and warnings.
444      * @since Moodle 3.1
445      * @throws moodle_exception
446      * @throws invalid_parameter_exception
447      */
448     public static function get_entries_by_letter($id, $letter, $from, $limit, $options) {
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();
463         // Get and validate the glossary.
464         list($glossary, $context) = self::validate_glossary($id);
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         }
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;
477         }
479         return array(
480             'count' => $count,
481             'entries' => $entries,
482             'warnings' => $warnings
483         );
484     }
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     }
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     }
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.
532      * @return array Containing count, entries and warnings.
533      * @since Moodle 3.1
534      * @throws moodle_exception
535      * @throws invalid_parameter_exception
536      */
537     public static function get_entries_by_date($id, $order, $sort, $from, $limit, $options) {
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();
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         }
560         // Get and validate the glossary.
561         list($glossary, $context) = self::validate_glossary($id);
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         }
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;
574         }
576         return array(
577             'count' => $count,
578             'entries' => $entries,
579             'warnings' => $warnings
580         );
581     }
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     }
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(
607             'id' => new external_value(PARAM_INT, 'The glossary ID'),
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     }
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.
619      * @return array Containing count, categories and warnings.
620      * @since Moodle 3.1
621      * @throws moodle_exception
622      */
623     public static function get_categories($id, $from, $limit) {
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();
634         // Get and validate the glossary.
635         list($glossary, $context) = self::validate_glossary($id);
637         // Fetch the categories.
638         $categories = array();
639         list($records, $count) = glossary_get_categories($glossary, $from, $limit);
640         foreach ($records as $category) {
641             $category->name = external_format_string($category->name, $context->id);
642             $categories[] = $category;
643         }
645         return array(
646             'count' => $count,
647             'categories' => $categories,
648             'warnings' => array(),
649         );
650     }
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     }
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(
681             'id' => new external_value(PARAM_INT, 'The glossary ID.'),
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     }
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.
701      * @return array Containing count, entries and warnings.
702      * @since Moodle 3.1
703      * @throws moodle_exception
704      * @throws invalid_parameter_exception
705      */
706     public static function get_entries_by_category($id, $categoryid, $from, $limit, $options) {
707         global $DB;
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();
723         // Get and validate the glossary.
724         list($glossary, $context) = self::validate_glossary($id);
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         }
732         // Validate the category.
733         if (in_array($categoryid, array(GLOSSARY_SHOW_ALL_CATEGORIES, GLOSSARY_SHOW_NOT_CATEGORISED))) {
734             // All good.
735         } else if (!$DB->record_exists('glossary_categories', array('id' => $categoryid, 'glossaryid' => $id))) {
736             throw new invalid_parameter_exception('invalidcategory');
737         }
739         // Fetching the entries.
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;
746             }
747             if (isset($record->categoryname)) {
748                 $record->categoryname = external_format_string($record->categoryname, $context->id);
749             }
750             $entries[] = $record;
751         }
753         return array(
754             'count' => $count,
755             'entries' => $entries,
756             'warnings' => $warnings
757         );
758     }
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     }
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     }
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.
801      * @return array Containing count, authors and warnings.
802      * @since Moodle 3.1
803      * @throws moodle_exception
804      */
805     public static function get_authors($id, $from, $limit, $options) {
806         global $PAGE;
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();
820         // Get and validate the glossary.
821         list($glossary, $context) = self::validate_glossary($id);
823         // Fetching the entries.
824         list($users, $count) = glossary_get_authors($glossary, $context, $limit, $from, $options);
826         $canviewfullnames = has_capability('moodle/site:viewfullnames', $context);
827         foreach ($users as $user) {
828             $userpicture = new user_picture($user);
829             $userpicture->size = 1;
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();
839         return array(
840             'count' => $count,
841             'authors' => $authors,
842             'warnings' => array(),
843         );
844     }
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     }
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     }
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.
899      * @return array Containing count, entries and warnings.
900      * @since Moodle 3.1
901      * @throws moodle_exception
902      * @throws invalid_parameter_exception
903      */
904     public static function get_entries_by_author($id, $letter, $field, $sort, $from, $limit, $options) {
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();
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         }
929         // Get and validate the glossary.
930         list($glossary, $context) = self::validate_glossary($id);
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         }
938         // Fetching the entries.
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;
945         }
947         return array(
948             'count' => $count,
949             'entries' => $entries,
950             'warnings' => $warnings
951         );
952     }
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     }
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     }
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.
1002      * @return array Containing count, entries and warnings.
1003      * @since Moodle 3.1
1004      * @throws moodle_exception
1005      * @throws invalid_parameter_exception
1006      */
1007     public static function get_entries_by_author_id($id, $authorid, $order, $sort, $from, $limit, $options) {
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();
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         }
1032         // Get and validate the glossary.
1033         list($glossary, $context) = self::validate_glossary($id);
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         }
1041         // Fetching the entries.
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;
1048         }
1050         return array(
1051             'count' => $count,
1052             'entries' => $entries,
1053             'warnings' => $warnings
1054         );
1055     }
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     }
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     }
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.
1107      * @return array Containing count, entries and warnings.
1108      * @since Moodle 3.1
1109      * @throws moodle_exception
1110      * @throws invalid_parameter_exception
1111      */
1112     public static function get_entries_by_search($id, $query, $fullsearch, $order, $sort, $from, $limit, $options) {
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();
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         }
1139         // Get and validate the glossary.
1140         list($glossary, $context) = self::validate_glossary($id);
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         }
1151         return array(
1152             'count' => $count,
1153             'entries' => $entries,
1154             'warnings' => $warnings
1155         );
1156     }
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.'),
1167             'entries' => new external_multiple_structure(
1168                 self::get_entry_return_structure()
1169             ),
1170             'warnings' => new external_warnings()
1171         ));
1172     }
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     }
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.
1201      * @return array Containing count, entries and warnings.
1202      * @since Moodle 3.1
1203      * @throws moodle_exception
1204      */
1205     public static function get_entries_by_term($id, $term, $from, $limit, $options) {
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();
1220         // Get and validate the glossary.
1221         list($glossary, $context) = self::validate_glossary($id);
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         }
1231         return array(
1232             'count' => $count,
1233             'entries' => $entries,
1234             'warnings' => $warnings
1235         );
1236     }
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.'),
1247             'entries' => new external_multiple_structure(
1248                 self::get_entry_return_structure()
1249             ),
1250             'warnings' => new external_warnings()
1251         ));
1252     }
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     }
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.
1282      * @return array Containing count, entries and warnings.
1283      * @since Moodle 3.1
1284      * @throws moodle_exception
1285      */
1286     public static function get_entries_to_approve($id, $letter, $order, $sort, $from, $limit) {
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();
1303         // Get and validate the glossary.
1304         list($glossary, $context) = self::validate_glossary($id);
1306         // Check the permissions.
1307         require_capability('mod/glossary:approve', $context);
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         }
1317         return array(
1318             'count' => $count,
1319             'entries' => $entries,
1320             'warnings' => $warnings
1321         );
1322     }
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.'),
1333             'entries' => new external_multiple_structure(
1334                 self::get_entry_return_structure()
1335             ),
1336             'warnings' => new external_warnings()
1337         ));
1338     }
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     }
1352     /**
1353      * Get an entry.
1354      *
1355      * @param int $id The entry ID.
1356      * @return array Containing entry and warnings.
1357      * @since Moodle 3.1
1358      * @throws moodle_exception
1359      * @throws invalid_parameter_exception
1360      */
1361     public static function get_entry_by_id($id) {
1362         global $DB, $USER;
1364         $params = self::validate_parameters(self::get_entry_by_id_parameters(), array('id' => $id));
1365         $id = $params['id'];
1366         $warnings = array();
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);
1372         if (empty($entry->approved) && $entry->userid != $USER->id && !has_capability('mod/glossary:approve', $context)) {
1373             throw new invalid_parameter_exception('invalidentry');
1374         }
1376         $entry = glossary_get_entry_by_id($id);
1377         self::fill_entry_details($entry, $context);
1379         return array(
1380             'entry' => $entry,
1381             'warnings' => $warnings
1382         );
1383     }
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     }