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 | */ | |
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 | ||
23da998f | 665 | } |