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