MDL-49231 mod_glossary: External function get_categories
[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 */
51 public static function get_browse_modes_from_display_format($format) {
52 global $DB;
53
54 $dp = $DB->get_record('glossary_formats', array('name' => $format), '*', IGNORE_MISSING);
55 $formats = glossary_get_visible_tabs($dp);
56
57 // Always add 'letter'.
58 $modes = array('letter');
59
60 if (in_array('category', $formats)) {
61 $modes[] = 'cat';
62 }
63 if (in_array('date', $formats)) {
64 $modes[] = 'date';
65 }
66 if (in_array('author', $formats)) {
67 $modes[] = 'author';
68 }
69
70 return $modes;
71 }
72
73 /**
74 * Get the return value of an entry.
75 *
76 * @return external_definition
77 */
78 public static function get_entry_return_structure() {
79 return new external_single_structure(array(
80 'id' => new external_value(PARAM_INT, 'The entry ID'),
81 'glossaryid' => new external_value(PARAM_INT, 'The glossary ID'),
82 'userid' => new external_value(PARAM_INT, 'Author ID'),
83 'userfullname' => new external_value(PARAM_TEXT, 'Author full name'),
84 'userpictureurl' => new external_value(PARAM_URL, 'Author picture'),
85 'concept' => new external_value(PARAM_RAW, 'The concept'),
86 'definition' => new external_value(PARAM_RAW, 'The definition'),
87 'definitionformat' => new external_format_value('definition'),
88 'definitiontrust' => new external_value(PARAM_BOOL, 'The definition trust flag'),
89 'attachment' => new external_value(PARAM_BOOL, 'Whether or not the entry has attachments'),
90 'attachments' => new external_multiple_structure(
91 new external_single_structure(array(
92 'filename' => new external_value(PARAM_FILE, 'File name'),
93 'mimetype' => new external_value(PARAM_RAW, 'Mime type'),
94 'fileurl' => new external_value(PARAM_URL, 'File download URL')
95 )), 'attachments', VALUE_OPTIONAL
96 ),
97 'timecreated' => new external_value(PARAM_INT, 'Time created'),
98 'timemodified' => new external_value(PARAM_INT, 'Time modified'),
99 'teacherentry' => new external_value(PARAM_BOOL, 'The entry was created by a teacher, or equivalent.'),
100 'sourceglossaryid' => new external_value(PARAM_INT, 'The source glossary ID'),
101 'usedynalink' => new external_value(PARAM_BOOL, 'Whether the concept should be automatically linked'),
102 'casesensitive' => new external_value(PARAM_BOOL, 'When true, the matching is case sensitive'),
103 'fullmatch' => new external_value(PARAM_BOOL, 'When true, the matching is done on full words only'),
104 'approved' => new external_value(PARAM_BOOL, 'Whether the entry was approved'),
105 ));
106 }
107
108 /**
109 * Fill in an entry object.
110 *
111 * This adds additional required fields for the external function to return.
112 *
113 * @param stdClass $entry The entry.
114 * @param context $context The context the entry belongs to.
115 * @return void
116 */
117 public static function fill_entry_details($entry, $context, $useridfield = 'userdataid', $userfieldprefix = 'userdata') {
118 global $PAGE;
119 $canviewfullnames = has_capability('moodle/site:viewfullnames', $context);
120
121 // Format concept and definition.
122 $entry->concept = external_format_string($entry->concept, $context->id);
123 list($entry->definition, $entry->definitionformat) = external_format_text($entry->definition, $entry->definitionformat,
124 $context->id, 'mod_glossary', 'entry', $entry->id);
125
126 // Author details.
127 $user = new stdclass();
128 $user = user_picture::unalias($entry, null, $useridfield, $userfieldprefix);
129 $userpicture = new user_picture($user);
130 $userpicture->size = 1;
131 $entry->userfullname = fullname($user, $canviewfullnames);
132 $entry->userpictureurl = $userpicture->get_url($PAGE)->out(false);
133
134 // Fetch attachments.
135 $entry->attachment = !empty($entry->attachment) ? 1 : 0;
136 $entry->attachments = array();
137 if ($entry->attachment) {
138 $fs = get_file_storage();
139 if ($files = $fs->get_area_files($context->id, 'mod_glossary', 'attachment', $entry->id, 'filename', false)) {
140 foreach ($files as $file) {
141 $filename = $file->get_filename();
142 $fileurl = moodle_url::make_webservice_pluginfile_url($context->id, 'mod_glossary', 'attachment',
143 $entry->id, '/', $filename);
144 $entry->attachments[] = array(
145 'filename' => $filename,
146 'mimetype' => $file->get_mimetype(),
147 'fileurl' => $fileurl->out(false)
148 );
149 }
150 }
151 }
152 }
153
23da998f
CC
154 /**
155 * Describes the parameters for get_glossaries_by_courses.
156 *
157 * @return external_external_function_parameters
bf5bbe01 158 * @since Moodle 3.1
23da998f
CC
159 */
160 public static function get_glossaries_by_courses_parameters() {
161 return new external_function_parameters (
162 array(
163 'courseids' => new external_multiple_structure(
164 new external_value(PARAM_INT, 'course id'),
bf5bbe01 165 'Array of course IDs', VALUE_DEFAULT, array()
23da998f
CC
166 ),
167 )
168 );
169 }
bf5bbe01 170
23da998f 171 /**
bf5bbe01 172 * Returns a list of glossaries in a provided list of courses.
23da998f 173 *
bf5bbe01
FM
174 * If no list is provided all glossaries that the user can view will be returned.
175 *
176 * @param array $courseids the course IDs.
177 * @return array of glossaries
178 * @since Moodle 3.1
23da998f
CC
179 */
180 public static function get_glossaries_by_courses($courseids = array()) {
23da998f 181 $params = self::validate_parameters(self::get_glossaries_by_courses_parameters(), array('courseids' => $courseids));
bf5bbe01 182
23da998f 183 $warnings = array();
bf5bbe01
FM
184 $courses = array();
185 $courseids = $params['courseids'];
186
187 if (empty($courseids)) {
23da998f
CC
188 $courses = enrol_get_my_courses();
189 $courseids = array_keys($courses);
190 }
bf5bbe01 191
23da998f 192 // Array to store the glossaries to return.
bf5bbe01 193 $glossaries = array();
fe11f9a4 194 $modes = array();
bf5bbe01 195
23da998f
CC
196 // Ensure there are courseids to loop through.
197 if (!empty($courseids)) {
bf5bbe01
FM
198 list($courses, $warnings) = external_util::validate_courses($courseids, $courses);
199
200 // Get the glossaries in these courses, this function checks users visibility permissions.
201 $glossaries = get_all_instances_in_courses('glossary', $courses);
23da998f 202 foreach ($glossaries as $glossary) {
bf5bbe01
FM
203 $context = context_module::instance($glossary->coursemodule);
204 $glossary->name = external_format_string($glossary->name, $context->id);
205 list($glossary->intro, $glossary->introformat) = external_format_text($glossary->intro, $glossary->introformat,
206 $context->id, 'mod_glossary', 'intro', null);
fe11f9a4
FM
207
208 // Make sure we have a number of entries per page.
209 if (!$glossary->entbypage) {
210 $glossary->entbypage = $CFG->glossary_entbypage;
211 }
212
213 // Add the list of browsing modes.
214 if (!isset($modes[$glossary->displayformat])) {
215 $modes[$glossary->displayformat] = self::get_browse_modes_from_display_format($glossary->displayformat);
216 }
217 $glossary->browsemodes = $modes[$glossary->displayformat];
23da998f
CC
218 }
219 }
bf5bbe01 220
23da998f 221 $result = array();
bf5bbe01 222 $result['glossaries'] = $glossaries;
23da998f
CC
223 $result['warnings'] = $warnings;
224 return $result;
225 }
bf5bbe01 226
23da998f
CC
227 /**
228 * Describes the get_glossaries_by_courses return value.
229 *
230 * @return external_single_structure
bf5bbe01 231 * @since Moodle 3.1
23da998f
CC
232 */
233 public static function get_glossaries_by_courses_returns() {
bf5bbe01
FM
234 return new external_single_structure(array(
235 'glossaries' => new external_multiple_structure(
236 new external_single_structure(array(
237 'id' => new external_value(PARAM_INT, 'Glossary id'),
238 'coursemodule' => new external_value(PARAM_INT, 'Course module id'),
239 'course' => new external_value(PARAM_INT, 'Course id'),
240 'name' => new external_value(PARAM_RAW, 'Glossary name'),
241 'intro' => new external_value(PARAM_RAW, 'The Glossary intro'),
242 'introformat' => new external_format_value('intro'),
243 'allowduplicatedentries' => new external_value(PARAM_INT, 'If enabled, multiple entries can have the' .
244 ' same concept name'),
245 'displayformat' => new external_value(PARAM_TEXT, 'Display format type'),
246 'mainglossary' => new external_value(PARAM_INT, 'If enabled this glossary is a main glossary.'),
247 'showspecial' => new external_value(PARAM_INT, 'If enabled, participants can browse the glossary by' .
248 ' special characters, such as @ and #'),
249 'showalphabet' => new external_value(PARAM_INT, 'If enabled, participants can browse the glossary by' .
250 ' letters of the alphabet'),
251 'showall' => new external_value(PARAM_INT, 'If enabled, participants can browse all entries at once'),
252 'allowcomments' => new external_value(PARAM_INT, 'If enabled, all participants with permission to' .
253 ' create comments will be able to add comments to glossary entries'),
254 'allowprintview' => new external_value(PARAM_INT, 'If enabled, students are provided with a link to a' .
255 ' printer-friendly version of the glossary. The link is always available to teachers'),
256 'usedynalink' => new external_value(PARAM_INT, 'If site-wide glossary auto-linking has been enabled' .
257 ' by an administrator and this checkbox is ticked, the entry will be automatically linked' .
258 ' wherever the concept words and phrases appear throughout the rest of the course.'),
259 'defaultapproval' => new external_value(PARAM_INT, 'If set to no, entries require approving by a' .
260 ' teacher before they are viewable by everyone.'),
261 'approvaldisplayformat' => new external_value(PARAM_TEXT, 'When approving glossary items you may wish' .
262 ' to use a different display format'),
263 'globalglossary' => new external_value(PARAM_INT, ''),
264 'entbypage' => new external_value(PARAM_INT, 'Entries shown per page'),
265 'editalways' => new external_value(PARAM_INT, 'Always allow editing'),
266 'rsstype' => new external_value(PARAM_INT, 'To enable the RSS feed for this activity, select either' .
267 ' concepts with author or concepts without author to be included in the feed'),
268 'rssarticles' => new external_value(PARAM_INT, 'This setting specifies the number of glossary entry' .
269 ' concepts to include in the RSS feed. Between 5 and 20 generally acceptable'),
270 'assessed' => new external_value(PARAM_INT, 'Aggregate type'),
271 'assesstimestart' => new external_value(PARAM_INT, 'Restrict rating to items created after this'),
272 'assesstimefinish' => new external_value(PARAM_INT, 'Restrict rating to items created before this'),
273 'scale' => new external_value(PARAM_INT, 'Scale ID'),
274 'timecreated' => new external_value(PARAM_INT, 'Time created'),
275 'timemodified' => new external_value(PARAM_INT, 'Time modified'),
276 'completionentries' => new external_value(PARAM_INT, 'Number of entries to complete'),
277 'section' => new external_value(PARAM_INT, 'Section'),
278 'visible' => new external_value(PARAM_INT, 'Visible'),
279 'groupmode' => new external_value(PARAM_INT, 'Group mode'),
280 'groupingid' => new external_value(PARAM_INT, 'Grouping ID'),
fe11f9a4
FM
281 'browsemodes' => new external_multiple_structure(
282 new external_value(PARAM_ALPHA, 'Modes of browsing allowed')
283 )
bf5bbe01
FM
284 ), 'Glossaries')
285 ),
286 'warnings' => new external_warnings())
23da998f
CC
287 );
288 }
d0d4372c
FM
289
290 /**
291 * Returns the description of the external function parameters.
292 *
293 * @return external_function_parameters
294 * @since Moodle 3.1
295 */
296 public static function view_glossary_parameters() {
297 return new external_function_parameters(array(
298 'id' => new external_value(PARAM_INT, 'Glossary instance ID'),
299 'mode' => new external_value(PARAM_ALPHA, 'The mode in which the glossary is viewed'),
300 ));
301 }
302
303 /**
304 * Notify that the course module was viewed.
305 *
306 * @param int $id The glossary instance ID.
307 * @return array of warnings and status result
308 * @since Moodle 3.1
309 * @throws moodle_exception
310 */
311 public static function view_glossary($id, $mode) {
312 global $DB;
313
314 $params = self::validate_parameters(self::view_glossary_parameters(), array(
315 'id' => $id,
316 'mode' => $mode
317 ));
318 $id = $params['id'];
319 $mode = $params['mode'];
320 $warnings = array();
321
322 // Fetch and confirm.
323 $glossary = $DB->get_record('glossary', array('id' => $id), '*', MUST_EXIST);
324 list($course, $cm) = get_course_and_cm_from_instance($glossary, 'glossary');
325 $context = context_module::instance($cm->id);
326 self::validate_context($context);
327
328 // Trigger module viewed event.
329 glossary_view($glossary, $course, $cm, $context, $mode);
330
331 return array(
332 'status' => true,
333 'warnings' => $warnings
334 );
335 }
336
337 /**
338 * Returns the description of the external function return value.
339 *
340 * @return external_description
341 * @since Moodle 3.1
342 */
343 public static function view_glossary_returns() {
344 return new external_single_structure(array(
345 'status' => new external_value(PARAM_BOOL, 'True on success'),
346 'warnings' => new external_warnings()
347 ));
348 }
349
61fce284
FM
350 /**
351 * Returns the description of the external function parameters.
352 *
353 * @return external_function_parameters
354 * @since Moodle 3.1
355 */
356 public static function view_entry_parameters() {
357 return new external_function_parameters(array(
358 'id' => new external_value(PARAM_INT, 'Glossary entry ID'),
359 ));
360 }
361
362 /**
363 * Notify that the entry was viewed.
364 *
365 * @param int $id The entry ID.
366 * @return array of warnings and status result
367 * @since Moodle 3.1
368 * @throws moodle_exception
369 */
370 public static function view_entry($id) {
371 global $DB, $USER;
372
373 $params = self::validate_parameters(self::view_entry_parameters(), array('id' => $id));
374 $id = $params['id'];
375 $warnings = array();
376
377 // Fetch and confirm.
378 $entry = $DB->get_record('glossary_entries', array('id' => $id), '*', MUST_EXIST);
379 $glossary = $DB->get_record('glossary', array('id' => $entry->glossaryid), '*', MUST_EXIST);
380 list($course, $cm) = get_course_and_cm_from_instance($glossary, 'glossary');
381 $context = context_module::instance($cm->id);
382 self::validate_context($context);
383
384 if (empty($entry->approved) && $entry->userid != $USER->id && !has_capability('mod/glossary:approve', $context)) {
385 throw new invalid_parameter_exception('invalidentry');
386 }
387
388 // Trigger view.
389 glossary_entry_view($entry, $context);
390
391 return array(
392 'status' => true,
393 'warnings' => $warnings
394 );
395 }
396
397 /**
398 * Returns the description of the external function return value.
399 *
400 * @return external_description
401 * @since Moodle 3.1
402 */
403 public static function view_entry_returns() {
404 return new external_single_structure(array(
405 'status' => new external_value(PARAM_BOOL, 'True on success'),
406 'warnings' => new external_warnings()
407 ));
408 }
409
fe11f9a4
FM
410 /**
411 * Returns the description of the external function parameters.
412 *
413 * @return external_function_parameters
414 * @since Moodle 3.1
415 */
416 public static function get_entries_by_letter_parameters() {
417 return new external_function_parameters(array(
418 'id' => new external_value(PARAM_INT, 'Glossary entry ID'),
419 'letter' => new external_value(PARAM_ALPHA, 'A letter, or either keywords: \'ALL\' or \'SPECIAL\'.'),
420 'from' => new external_value(PARAM_INT, 'Start returning records from here', VALUE_DEFAULT, 0),
421 'limit' => new external_value(PARAM_INT, 'Number of records to return', VALUE_DEFAULT, 20),
422 'options' => new external_single_structure(array(
423 'includenotapproved' => new external_value(PARAM_BOOL, 'When false, includes the non-approved entries created by' .
424 ' the user. When true, also includes the ones that the user has the permission to approve.', VALUE_DEFAULT, 0)
425 ), 'An array of options', VALUE_DEFAULT, array())
426 ));
427 }
428
429 /**
430 * Browse a glossary entries by letter.
431 *
432 * @param int $id The glossary ID.
433 * @param string $letter A letter, or a special keyword.
434 * @param int $from Start returning records from here.
435 * @param int $limit Number of records to return.
436 * @param array $options Array of options.
437 * @return array of warnings and status result
438 * @since Moodle 3.1
439 * @throws moodle_exception
440 */
441 public static function get_entries_by_letter($id, $letter, $from = 0, $limit = 20, $options = array()) {
442 global $DB, $USER;
443
444 $params = self::validate_parameters(self::get_entries_by_letter_parameters(), array(
445 'id' => $id,
446 'letter' => $letter,
447 'from' => $from,
448 'limit' => $limit,
449 'options' => $options,
450 ));
451 $id = $params['id'];
452 $letter = $params['letter'];
453 $from = $params['from'];
454 $limit = $params['limit'];
455 $options = $params['options'];
456 $warnings = array();
457
458 // Fetch and confirm.
459 $glossary = $DB->get_record('glossary', array('id' => $id), '*', MUST_EXIST);
460 list($course, $cm) = get_course_and_cm_from_instance($glossary, 'glossary');
461 $context = context_module::instance($cm->id);
462 self::validate_context($context);
463
464 // Validate the mode.
465 $modes = self::get_browse_modes_from_display_format($glossary->displayformat);
466 if (!in_array('letter', $modes)) {
467 throw new invalid_parameter_exception('invalidbrowsemode');
468 }
469
470 // Preparing the query.
471 $where = '1 = 1';
472 $params = array();
473
474 if ($letter != 'ALL' && $letter != 'SPECIAL' && ($letterstrlen = core_text::strlen($letter))) {
475 $params['hookup'] = core_text::strtoupper($letter);
476 $where = $DB->sql_substr('upper(concept)', 1, $letterstrlen) . ' = :hookup';
477 }
478 if ($letter == 'SPECIAL') {
479 $alphabet = explode(',', get_string('alphabet', 'langconfig'));
480 list($nia, $aparams) = $DB->get_in_or_equal($alphabet, SQL_PARAMS_NAMED, 'a', false);
481 $params = array_merge($params, $aparams);
482 $where = $DB->sql_substr("upper(concept)", 1, 1) . " $nia";
483 }
484
485 $approvedsql = '(ge.approved <> 0 OR ge.userid = :myid)';
486 if (!empty($options['includenotapproved']) && has_capability('mod/glossary:approve', $context)) {
487 $approvedsql = '1 = 1';
488 }
489
490 $userfields = user_picture::fields('u', null, 'userdataid', 'userdata');
491
492 $sqlselectcount = "SELECT COUNT('x')";
493 $sqlselect = "SELECT ge.*, $userfields";
494 $sql = " FROM {glossary_entries} ge
495 LEFT JOIN {user} u ON ge.userid = u.id
496 WHERE (ge.glossaryid = :gid1 OR ge.sourceglossaryid = :gid2)
497 AND $approvedsql
498 AND $where";
499 $sqlorder = " ORDER BY ge.concept";
500
501 $params['gid1'] = $glossary->id;
502 $params['gid2'] = $glossary->id;
503 $params['myid'] = $USER->id;
504
505 // Fetching the entries.
506 $count = $DB->count_records_sql($sqlselectcount . $sql, $params);
507 $entries = $DB->get_records_sql($sqlselect . $sql . $sqlorder, $params, $from, $limit);
508 foreach ($entries as $key => $entry) {
509 self::fill_entry_details($entry, $context);
510 }
511
512 return array(
513 'count' => $count,
514 'entries' => $entries,
515 'warnings' => $warnings
516 );
517 }
518
519 /**
520 * Returns the description of the external function return value.
521 *
522 * @return external_description
523 * @since Moodle 3.1
524 */
525 public static function get_entries_by_letter_returns() {
526 return new external_single_structure(array(
527 'count' => new external_value(PARAM_INT, 'The total number of records matching the request.'),
528 'entries' => new external_multiple_structure(
529 self::get_entry_return_structure()
530 ),
531 'warnings' => new external_warnings()
532 ));
533 }
6a273d5a
FM
534
535 /**
536 * Returns the description of the external function parameters.
537 *
538 * @return external_function_parameters
539 * @since Moodle 3.1
540 */
541 public static function get_entries_by_date_parameters() {
542 return new external_function_parameters(array(
543 'id' => new external_value(PARAM_INT, 'Glossary entry ID'),
544 'order' => new external_value(PARAM_ALPHA, 'Order the records by: \'CREATION\' or \'UPDATE\'.',
545 VALUE_DEFAULT, 'UPDATE'),
546 'sort' => new external_value(PARAM_ALPHA, 'The direction of the order: \'ASC\' or \'DESC\'', VALUE_DEFAULT, 'DESC'),
547 'from' => new external_value(PARAM_INT, 'Start returning records from here', VALUE_DEFAULT, 0),
548 'limit' => new external_value(PARAM_INT, 'Number of records to return', VALUE_DEFAULT, 20),
549 'options' => new external_single_structure(array(
550 'includenotapproved' => new external_value(PARAM_BOOL, 'When false, includes the non-approved entries created by' .
551 ' the user. When true, also includes the ones that the user has the permission to approve.', VALUE_DEFAULT, 0)
552 ), 'An array of options', VALUE_DEFAULT, array())
553 ));
554 }
555
556 /**
557 * Browse a glossary entries by date.
558 *
559 * @param int $id The glossary ID.
560 * @param string $order The way to order the records.
561 * @param string $sort The direction of the order.
562 * @param int $from Start returning records from here.
563 * @param int $limit Number of records to return.
564 * @param array $options Array of options.
565 * @return array of warnings and status result
566 * @since Moodle 3.1
567 * @throws moodle_exception
568 */
569 public static function get_entries_by_date($id, $order = 'UPDATE', $sort = 'DESC', $from = 0, $limit = 20,
570 $options = array()) {
571 global $DB, $USER;
572
573 $params = self::validate_parameters(self::get_entries_by_date_parameters(), array(
574 'id' => $id,
575 'order' => core_text::strtoupper($order),
576 'sort' => core_text::strtoupper($sort),
577 'from' => $from,
578 'limit' => $limit,
579 'options' => $options,
580 ));
581 $id = $params['id'];
582 $order = $params['order'];
583 $sort = $params['sort'];
584 $from = $params['from'];
585 $limit = $params['limit'];
586 $options = $params['options'];
587 $warnings = array();
588
589 if (!in_array($order, array('CREATION', 'UPDATE'))) {
590 throw new invalid_parameter_exception('invalidorder');
591 } else if (!in_array($sort, array('ASC', 'DESC'))) {
592 throw new invalid_parameter_exception('invalidsort');
593 }
594
595 // Fetch and confirm.
596 $glossary = $DB->get_record('glossary', array('id' => $id), '*', MUST_EXIST);
597 list($course, $cm) = get_course_and_cm_from_instance($glossary, 'glossary');
598 $context = context_module::instance($cm->id);
599 self::validate_context($context);
600
601 // Validate the mode.
602 $modes = self::get_browse_modes_from_display_format($glossary->displayformat);
603 if (!in_array('date', $modes)) {
604 throw new invalid_parameter_exception('invalidbrowsemode');
605 }
606
607 // Preparing the query.
608 $params = array();
609 $approvedsql = '(ge.approved <> 0 OR ge.userid = :myid)';
610 if (!empty($options['includenotapproved']) && has_capability('mod/glossary:approve', $context)) {
611 $approvedsql = '1 = 1';
612 }
613
614 $userfields = user_picture::fields('u', null, 'userdataid', 'userdata');
615
616 $sqlselectcount = "SELECT COUNT('x')";
617 $sqlselect = "SELECT ge.*, $userfields";
618 $sql = " FROM {glossary_entries} ge
619 LEFT JOIN {user} u ON ge.userid = u.id
620 WHERE (ge.glossaryid = :gid1 OR ge.sourceglossaryid = :gid2)
621 AND $approvedsql";
622
623 $sqlorder = ' ORDER BY ';
624 if ($order == 'CREATION') {
625 $sqlorder .= 'ge.timecreated';
626 } else {
627 $sqlorder .= 'ge.timemodified';
628 }
629 $sqlorder .= ' ' . $sort;
630
631 $params['gid1'] = $glossary->id;
632 $params['gid2'] = $glossary->id;
633 $params['myid'] = $USER->id;
634
635 // Fetching the entries.
636 $count = $DB->count_records_sql($sqlselectcount . $sql, $params);
637 $entries = $DB->get_records_sql($sqlselect . $sql . $sqlorder, $params, $from, $limit);
638 foreach ($entries as $key => $entry) {
639 self::fill_entry_details($entry, $context);
640 }
641
642 return array(
643 'count' => $count,
644 'entries' => $entries,
645 'warnings' => $warnings
646 );
647 }
648
649 /**
650 * Returns the description of the external function return value.
651 *
652 * @return external_description
653 * @since Moodle 3.1
654 */
655 public static function get_entries_by_date_returns() {
656 return new external_single_structure(array(
657 'count' => new external_value(PARAM_INT, 'The total number of records matching the request.'),
658 'entries' => new external_multiple_structure(
659 self::get_entry_return_structure()
660 ),
661 'warnings' => new external_warnings()
662 ));
663 }
664
efb7a0a9
FM
665 /**
666 * Returns the description of the external function parameters.
667 *
668 * @return external_function_parameters
669 * @since Moodle 3.1
670 */
671 public static function get_categories_parameters() {
672 return new external_function_parameters(array(
673 'id' => new external_value(PARAM_INT, 'Glossary entry ID'),
674 'from' => new external_value(PARAM_INT, 'Start returning records from here', VALUE_DEFAULT, 0),
675 'limit' => new external_value(PARAM_INT, 'Number of records to return', VALUE_DEFAULT, 20)
676 ));
677 }
678
679 /**
680 * Get the categories of a glossary.
681 *
682 * @param int $id The glossary ID.
683 * @param int $from Start returning records from here.
684 * @param int $limit Number of records to return.
685 * @return array of warnings and status result
686 * @since Moodle 3.1
687 * @throws moodle_exception
688 */
689 public static function get_categories($id, $from = 0, $limit = 20) {
690 global $DB;
691
692 $params = self::validate_parameters(self::get_categories_parameters(), array(
693 'id' => $id,
694 'from' => $from,
695 'limit' => $limit
696 ));
697 $id = $params['id'];
698 $from = $params['from'];
699 $limit = $params['limit'];
700 $warnings = array();
701
702 // Fetch and confirm.
703 $glossary = $DB->get_record('glossary', array('id' => $id), '*', MUST_EXIST);
704 list($course, $cm) = get_course_and_cm_from_instance($glossary, 'glossary');
705 $context = context_module::instance($cm->id);
706 self::validate_context($context);
707
708 // Fetch the categories.
709 $count = $DB->count_records('glossary_categories', array('glossaryid' => $id));
710 $categories = $DB->get_records('glossary_categories', array('glossaryid' => $id), 'name ASC', '*', $from, $limit);
711 foreach ($categories as $category) {
712 $category->name = external_format_string($category->name, $context->id);
713 }
714
715 return array(
716 'count' => $count,
717 'categories' => $categories,
718 'warnings' => array(),
719 );
720 }
721
722 /**
723 * Returns the description of the external function return value.
724 *
725 * @return external_description
726 * @since Moodle 3.1
727 */
728 public static function get_categories_returns() {
729 return new external_single_structure(array(
730 'count' => new external_value(PARAM_INT, 'The total number of records.'),
731 'categories' => new external_multiple_structure(
732 new external_single_structure(array(
733 'id' => new external_value(PARAM_INT, 'The category ID'),
734 'glossaryid' => new external_value(PARAM_INT, 'The glossary ID'),
735 'name' => new external_value(PARAM_RAW, 'The name of the category'),
736 'usedynalink' => new external_value(PARAM_BOOL, 'Whether the category is automatically linked'),
737 ))
738 ),
739 'warnings' => new external_warnings()
740 ));
741 }
742
23da998f 743}