| [ Index ] |
PHP Cross Reference of Unnamed Project |
[Summary view] [Print] [Text view]
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/>. 16 17 /** 18 * Glossary module external API. 19 * 20 * @package mod_glossary 21 * @category external 22 * @copyright 2015 Costantino Cito <ccito@cvaconsulting.com> 23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 24 * @since Moodle 3.1 25 */ 26 27 defined('MOODLE_INTERNAL') || die(); 28 29 require_once($CFG->libdir . '/externallib.php'); 30 require_once($CFG->dirroot . '/mod/glossary/lib.php'); 31 32 /** 33 * Glossary module external functions. 34 * 35 * @package mod_glossary 36 * @category external 37 * @copyright 2015 Costantino Cito <ccito@cvaconsulting.com> 38 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 39 * @since Moodle 3.1 40 */ 41 class mod_glossary_external extends external_api { 42 43 /** 44 * Get the browse modes from the display format. 45 * 46 * This returns some of the terms that can be used when reporting a glossary being viewed. 47 * 48 * @param string $format The display format of the glossary. 49 * @return array Containing some of all of the following: letter, cat, date, author. 50 */ 51 protected static function get_browse_modes_from_display_format($format) { 52 global $DB; 53 54 $formats = array(); 55 $dp = $DB->get_record('glossary_formats', array('name' => $format), '*', IGNORE_MISSING); 56 if ($dp) { 57 $formats = glossary_get_visible_tabs($dp); 58 } 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 * 79 * @param bool $includecat Whether the definition should include category info. 80 * @return external_definition 81 */ 82 protected static function get_entry_return_structure($includecat = false) { 83 $params = array( 84 'id' => new external_value(PARAM_INT, 'The entry ID'), 85 'glossaryid' => new external_value(PARAM_INT, 'The glossary ID'), 86 'userid' => new external_value(PARAM_INT, 'Author ID'), 87 'userfullname' => new external_value(PARAM_NOTAGS, 'Author full name'), 88 'userpictureurl' => new external_value(PARAM_URL, 'Author picture'), 89 'concept' => new external_value(PARAM_RAW, 'The concept'), 90 'definition' => new external_value(PARAM_RAW, 'The definition'), 91 'definitionformat' => new external_format_value('definition'), 92 'definitiontrust' => new external_value(PARAM_BOOL, 'The definition trust flag'), 93 'attachment' => new external_value(PARAM_BOOL, 'Whether or not the entry has attachments'), 94 'attachments' => new external_files('attachments', VALUE_OPTIONAL), 95 'timecreated' => new external_value(PARAM_INT, 'Time created'), 96 'timemodified' => new external_value(PARAM_INT, 'Time modified'), 97 'teacherentry' => new external_value(PARAM_BOOL, 'The entry was created by a teacher, or equivalent.'), 98 'sourceglossaryid' => new external_value(PARAM_INT, 'The source glossary ID'), 99 'usedynalink' => new external_value(PARAM_BOOL, 'Whether the concept should be automatically linked'), 100 'casesensitive' => new external_value(PARAM_BOOL, 'When true, the matching is case sensitive'), 101 'fullmatch' => new external_value(PARAM_BOOL, 'When true, the matching is done on full words only'), 102 'approved' => new external_value(PARAM_BOOL, 'Whether the entry was approved'), 103 ); 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); 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 */ 125 protected static function fill_entry_details($entry, $context) { 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. 135 $user = mod_glossary_entry_query_builder::get_user_from_record($entry); 136 $userpicture = new user_picture($user); 137 $userpicture->size = 1; 138 $entry->userfullname = fullname($user, $canviewfullnames); 139 $entry->userpictureurl = $userpicture->get_url($PAGE)->out(false); 140 141 // Fetch attachments. 142 $entry->attachment = !empty($entry->attachment) ? 1 : 0; 143 $entry->attachments = array(); 144 if ($entry->attachment) { 145 $entry->attachments = external_util::get_area_files($context->id, 'mod_glossary', 'attachment', $entry->id); 146 } 147 } 148 149 /** 150 * Validate a glossary via ID. 151 * 152 * @param int $id The glossary ID. 153 * @return array Contains glossary, context, course and cm. 154 */ 155 protected static function validate_glossary($id) { 156 global $DB; 157 $glossary = $DB->get_record('glossary', array('id' => $id), '*', MUST_EXIST); 158 list($course, $cm) = get_course_and_cm_from_instance($glossary, 'glossary'); 159 $context = context_module::instance($cm->id); 160 self::validate_context($context); 161 return array($glossary, $context, $course, $cm); 162 } 163 164 /** 165 * Describes the parameters for get_glossaries_by_courses. 166 * 167 * @return external_external_function_parameters 168 * @since Moodle 3.1 169 */ 170 public static function get_glossaries_by_courses_parameters() { 171 return new external_function_parameters ( 172 array( 173 'courseids' => new external_multiple_structure( 174 new external_value(PARAM_INT, 'course id'), 175 'Array of course IDs', VALUE_DEFAULT, array() 176 ), 177 ) 178 ); 179 } 180 181 /** 182 * Returns a list of glossaries in a provided list of courses. 183 * 184 * If no list is provided all glossaries that the user can view will be returned. 185 * 186 * @param array $courseids the course IDs. 187 * @return array of glossaries 188 * @since Moodle 3.1 189 */ 190 public static function get_glossaries_by_courses($courseids = array()) { 191 $params = self::validate_parameters(self::get_glossaries_by_courses_parameters(), array('courseids' => $courseids)); 192 193 $warnings = array(); 194 $courses = array(); 195 $courseids = $params['courseids']; 196 197 if (empty($courseids)) { 198 $courses = enrol_get_my_courses(); 199 $courseids = array_keys($courses); 200 } 201 202 // Array to store the glossaries to return. 203 $glossaries = array(); 204 $modes = array(); 205 206 // Ensure there are courseids to loop through. 207 if (!empty($courseids)) { 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); 212 foreach ($glossaries as $glossary) { 213 $context = context_module::instance($glossary->coursemodule); 214 $glossary->name = external_format_string($glossary->name, $context->id); 215 list($glossary->intro, $glossary->introformat) = external_format_text($glossary->intro, $glossary->introformat, 216 $context->id, 'mod_glossary', 'intro', null); 217 $glossary->introfiles = external_util::get_area_files($context->id, 'mod_glossary', 'intro', false, false); 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]; 229 } 230 } 231 232 $result = array(); 233 $result['glossaries'] = $glossaries; 234 $result['warnings'] = $warnings; 235 return $result; 236 } 237 238 /** 239 * Describes the get_glossaries_by_courses return value. 240 * 241 * @return external_single_structure 242 * @since Moodle 3.1 243 */ 244 public static function get_glossaries_by_courses_returns() { 245 return new external_single_structure(array( 246 'glossaries' => new external_multiple_structure( 247 new external_single_structure(array( 248 'id' => new external_value(PARAM_INT, 'Glossary id'), 249 'coursemodule' => new external_value(PARAM_INT, 'Course module id'), 250 'course' => new external_value(PARAM_INT, 'Course id'), 251 'name' => new external_value(PARAM_RAW, 'Glossary name'), 252 'intro' => new external_value(PARAM_RAW, 'The Glossary intro'), 253 'introformat' => new external_format_value('intro'), 254 'introfiles' => new external_files('Files in the introduction text', VALUE_OPTIONAL), 255 'allowduplicatedentries' => new external_value(PARAM_INT, 'If enabled, multiple entries can have the' . 256 ' same concept name'), 257 'displayformat' => new external_value(PARAM_TEXT, 'Display format type'), 258 'mainglossary' => new external_value(PARAM_INT, 'If enabled this glossary is a main glossary.'), 259 'showspecial' => new external_value(PARAM_INT, 'If enabled, participants can browse the glossary by' . 260 ' special characters, such as @ and #'), 261 'showalphabet' => new external_value(PARAM_INT, 'If enabled, participants can browse the glossary by' . 262 ' letters of the alphabet'), 263 'showall' => new external_value(PARAM_INT, 'If enabled, participants can browse all entries at once'), 264 'allowcomments' => new external_value(PARAM_INT, 'If enabled, all participants with permission to' . 265 ' create comments will be able to add comments to glossary entries'), 266 'allowprintview' => new external_value(PARAM_INT, 'If enabled, students are provided with a link to a' . 267 ' printer-friendly version of the glossary. The link is always available to teachers'), 268 'usedynalink' => new external_value(PARAM_INT, 'If site-wide glossary auto-linking has been enabled' . 269 ' by an administrator and this checkbox is ticked, the entry will be automatically linked' . 270 ' wherever the concept words and phrases appear throughout the rest of the course.'), 271 'defaultapproval' => new external_value(PARAM_INT, 'If set to no, entries require approving by a' . 272 ' teacher before they are viewable by everyone.'), 273 'approvaldisplayformat' => new external_value(PARAM_TEXT, 'When approving glossary items you may wish' . 274 ' to use a different display format'), 275 'globalglossary' => new external_value(PARAM_INT, ''), 276 'entbypage' => new external_value(PARAM_INT, 'Entries shown per page'), 277 'editalways' => new external_value(PARAM_INT, 'Always allow editing'), 278 'rsstype' => new external_value(PARAM_INT, 'To enable the RSS feed for this activity, select either' . 279 ' concepts with author or concepts without author to be included in the feed'), 280 'rssarticles' => new external_value(PARAM_INT, 'This setting specifies the number of glossary entry' . 281 ' concepts to include in the RSS feed. Between 5 and 20 generally acceptable'), 282 'assessed' => new external_value(PARAM_INT, 'Aggregate type'), 283 'assesstimestart' => new external_value(PARAM_INT, 'Restrict rating to items created after this'), 284 'assesstimefinish' => new external_value(PARAM_INT, 'Restrict rating to items created before this'), 285 'scale' => new external_value(PARAM_INT, 'Scale ID'), 286 'timecreated' => new external_value(PARAM_INT, 'Time created'), 287 'timemodified' => new external_value(PARAM_INT, 'Time modified'), 288 'completionentries' => new external_value(PARAM_INT, 'Number of entries to complete'), 289 'section' => new external_value(PARAM_INT, 'Section'), 290 'visible' => new external_value(PARAM_INT, 'Visible'), 291 'groupmode' => new external_value(PARAM_INT, 'Group mode'), 292 'groupingid' => new external_value(PARAM_INT, 'Grouping ID'), 293 'browsemodes' => new external_multiple_structure( 294 new external_value(PARAM_ALPHA, 'Modes of browsing allowed') 295 ) 296 ), 'Glossaries') 297 ), 298 'warnings' => new external_warnings()) 299 ); 300 } 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. 319 * @param string $mode The view mode. 320 * @return array of warnings and status result 321 * @since Moodle 3.1 322 * @throws moodle_exception 323 */ 324 public static function view_glossary($id, $mode) { 325 $params = self::validate_parameters(self::view_glossary_parameters(), array( 326 'id' => $id, 327 'mode' => $mode 328 )); 329 $id = $params['id']; 330 $mode = $params['mode']; 331 $warnings = array(); 332 333 // Get and validate the glossary. 334 list($glossary, $context, $course, $cm) = self::validate_glossary($id); 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 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 377 * @throws invalid_parameter_exception 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 386 // Get and validate the glossary. 387 $entry = $DB->get_record('glossary_entries', array('id' => $id), '*', MUST_EXIST); 388 list($glossary, $context, $course, $cm) = self::validate_glossary($entry->glossaryid); 389 390 if (!glossary_can_view_entry($entry, $cm)) { 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 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. 443 * @return array Containing count, entries and warnings. 444 * @since Moodle 3.1 445 * @throws moodle_exception 446 * @throws invalid_parameter_exception 447 */ 448 public static function get_entries_by_letter($id, $letter, $from, $limit, $options) { 449 $params = self::validate_parameters(self::get_entries_by_letter_parameters(), array( 450 'id' => $id, 451 'letter' => $letter, 452 'from' => $from, 453 'limit' => $limit, 454 'options' => $options, 455 )); 456 $id = $params['id']; 457 $letter = $params['letter']; 458 $from = $params['from']; 459 $limit = $params['limit']; 460 $options = $params['options']; 461 $warnings = array(); 462 463 // Get and validate the glossary. 464 list($glossary, $context) = self::validate_glossary($id); 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 472 $entries = array(); 473 list($records, $count) = glossary_get_entries_by_letter($glossary, $context, $letter, $from, $limit, $options); 474 foreach ($records as $key => $record) { 475 self::fill_entry_details($record, $context); 476 $entries[] = $record; 477 } 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 } 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. 532 * @return array Containing count, entries and warnings. 533 * @since Moodle 3.1 534 * @throws moodle_exception 535 * @throws invalid_parameter_exception 536 */ 537 public static function get_entries_by_date($id, $order, $sort, $from, $limit, $options) { 538 $params = self::validate_parameters(self::get_entries_by_date_parameters(), array( 539 'id' => $id, 540 'order' => core_text::strtoupper($order), 541 'sort' => core_text::strtoupper($sort), 542 'from' => $from, 543 'limit' => $limit, 544 'options' => $options, 545 )); 546 $id = $params['id']; 547 $order = $params['order']; 548 $sort = $params['sort']; 549 $from = $params['from']; 550 $limit = $params['limit']; 551 $options = $params['options']; 552 $warnings = array(); 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 560 // Get and validate the glossary. 561 list($glossary, $context) = self::validate_glossary($id); 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 569 $entries = array(); 570 list($records, $count) = glossary_get_entries_by_date($glossary, $context, $order, $sort, $from, $limit, $options); 571 foreach ($records as $key => $record) { 572 self::fill_entry_details($record, $context); 573 $entries[] = $record; 574 } 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 599 /** 600 * Returns the description of the external function parameters. 601 * 602 * @return external_function_parameters 603 * @since Moodle 3.1 604 */ 605 public static function get_categories_parameters() { 606 return new external_function_parameters(array( 607 'id' => new external_value(PARAM_INT, 'The glossary ID'), 608 'from' => new external_value(PARAM_INT, 'Start returning records from here', VALUE_DEFAULT, 0), 609 'limit' => new external_value(PARAM_INT, 'Number of records to return', VALUE_DEFAULT, 20) 610 )); 611 } 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. 619 * @return array Containing count, categories and warnings. 620 * @since Moodle 3.1 621 * @throws moodle_exception 622 */ 623 public static function get_categories($id, $from, $limit) { 624 $params = self::validate_parameters(self::get_categories_parameters(), array( 625 'id' => $id, 626 'from' => $from, 627 'limit' => $limit 628 )); 629 $id = $params['id']; 630 $from = $params['from']; 631 $limit = $params['limit']; 632 $warnings = array(); 633 634 // Get and validate the glossary. 635 list($glossary, $context) = self::validate_glossary($id); 636 637 // Fetch the categories. 638 $categories = array(); 639 list($records, $count) = glossary_get_categories($glossary, $from, $limit); 640 foreach ($records as $category) { 641 $category->name = external_format_string($category->name, $context->id); 642 $categories[] = $category; 643 } 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 673 /** 674 * Returns the description of the external function parameters. 675 * 676 * @return external_function_parameters 677 * @since Moodle 3.1 678 */ 679 public static function get_entries_by_category_parameters() { 680 return new external_function_parameters(array( 681 'id' => new external_value(PARAM_INT, 'The glossary ID.'), 682 'categoryid' => new external_value(PARAM_INT, 'The category ID. Use \'' . GLOSSARY_SHOW_ALL_CATEGORIES . '\' for all' . 683 ' categories, or \'' . GLOSSARY_SHOW_NOT_CATEGORISED . '\' for uncategorised entries.'), 684 'from' => new external_value(PARAM_INT, 'Start returning records from here', VALUE_DEFAULT, 0), 685 'limit' => new external_value(PARAM_INT, 'Number of records to return', VALUE_DEFAULT, 20), 686 'options' => new external_single_structure(array( 687 'includenotapproved' => new external_value(PARAM_BOOL, 'When false, includes the non-approved entries created by' . 688 ' the user. When true, also includes the ones that the user has the permission to approve.', VALUE_DEFAULT, 0) 689 ), 'An array of options', VALUE_DEFAULT, array()) 690 )); 691 } 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. 701 * @return array Containing count, entries and warnings. 702 * @since Moodle 3.1 703 * @throws moodle_exception 704 * @throws invalid_parameter_exception 705 */ 706 public static function get_entries_by_category($id, $categoryid, $from, $limit, $options) { 707 global $DB; 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 723 // Get and validate the glossary. 724 list($glossary, $context) = self::validate_glossary($id); 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. 735 } else if (!$DB->record_exists('glossary_categories', array('id' => $categoryid, 'glossaryid' => $id))) { 736 throw new invalid_parameter_exception('invalidcategory'); 737 } 738 739 // Fetching the entries. 740 $entries = array(); 741 list($records, $count) = glossary_get_entries_by_category($glossary, $context, $categoryid, $from, $limit, $options); 742 foreach ($records as $key => $record) { 743 self::fill_entry_details($record, $context); 744 if ($record->categoryid === null) { 745 $record->categoryid = GLOSSARY_SHOW_NOT_CATEGORISED; 746 } 747 if (isset($record->categoryname)) { 748 $record->categoryname = external_format_string($record->categoryname, $context->id); 749 } 750 $entries[] = $record; 751 } 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 } 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. 801 * @return array Containing count, authors and warnings. 802 * @since Moodle 3.1 803 * @throws moodle_exception 804 */ 805 public static function get_authors($id, $from, $limit, $options) { 806 global $PAGE; 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 820 // Get and validate the glossary. 821 list($glossary, $context) = self::validate_glossary($id); 822 823 // Fetching the entries. 824 list($users, $count) = glossary_get_authors($glossary, $context, $limit, $from, $options); 825 826 $canviewfullnames = has_capability('moodle/site:viewfullnames', $context); 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 } 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. 899 * @return array Containing count, entries and warnings. 900 * @since Moodle 3.1 901 * @throws moodle_exception 902 * @throws invalid_parameter_exception 903 */ 904 public static function get_entries_by_author($id, $letter, $field, $sort, $from, $limit, $options) { 905 $params = self::validate_parameters(self::get_entries_by_author_parameters(), array( 906 'id' => $id, 907 'letter' => $letter, 908 'field' => core_text::strtoupper($field), 909 'sort' => core_text::strtoupper($sort), 910 'from' => $from, 911 'limit' => $limit, 912 'options' => $options, 913 )); 914 $id = $params['id']; 915 $letter = $params['letter']; 916 $field = $params['field']; 917 $sort = $params['sort']; 918 $from = $params['from']; 919 $limit = $params['limit']; 920 $options = $params['options']; 921 $warnings = array(); 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 929 // Get and validate the glossary. 930 list($glossary, $context) = self::validate_glossary($id); 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 938 // Fetching the entries. 939 $entries = array(); 940 list($records, $count) = glossary_get_entries_by_author($glossary, $context, $letter, $field, $sort, $from, $limit, 941 $options); 942 foreach ($records as $key => $record) { 943 self::fill_entry_details($record, $context); 944 $entries[] = $record; 945 } 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 } 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. 1002 * @return array Containing count, entries and warnings. 1003 * @since Moodle 3.1 1004 * @throws moodle_exception 1005 * @throws invalid_parameter_exception 1006 */ 1007 public static function get_entries_by_author_id($id, $authorid, $order, $sort, $from, $limit, $options) { 1008 $params = self::validate_parameters(self::get_entries_by_author_id_parameters(), array( 1009 'id' => $id, 1010 'authorid' => $authorid, 1011 'order' => core_text::strtoupper($order), 1012 'sort' => core_text::strtoupper($sort), 1013 'from' => $from, 1014 'limit' => $limit, 1015 'options' => $options, 1016 )); 1017 $id = $params['id']; 1018 $authorid = $params['authorid']; 1019 $order = $params['order']; 1020 $sort = $params['sort']; 1021 $from = $params['from']; 1022 $limit = $params['limit']; 1023 $options = $params['options']; 1024 $warnings = array(); 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 1032 // Get and validate the glossary. 1033 list($glossary, $context) = self::validate_glossary($id); 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 1041 // Fetching the entries. 1042 $entries = array(); 1043 list($records, $count) = glossary_get_entries_by_author_id($glossary, $context, $authorid, $order, $sort, $from, 1044 $limit, $options); 1045 foreach ($records as $key => $record) { 1046 self::fill_entry_details($record, $context); 1047 $entries[] = $record; 1048 } 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 } 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. 1107 * @return array Containing count, entries and warnings. 1108 * @since Moodle 3.1 1109 * @throws moodle_exception 1110 * @throws invalid_parameter_exception 1111 */ 1112 public static function get_entries_by_search($id, $query, $fullsearch, $order, $sort, $from, $limit, $options) { 1113 $params = self::validate_parameters(self::get_entries_by_search_parameters(), array( 1114 'id' => $id, 1115 'query' => $query, 1116 'fullsearch' => $fullsearch, 1117 'order' => core_text::strtoupper($order), 1118 'sort' => core_text::strtoupper($sort), 1119 'from' => $from, 1120 'limit' => $limit, 1121 'options' => $options, 1122 )); 1123 $id = $params['id']; 1124 $query = $params['query']; 1125 $fullsearch = $params['fullsearch']; 1126 $order = $params['order']; 1127 $sort = $params['sort']; 1128 $from = $params['from']; 1129 $limit = $params['limit']; 1130 $options = $params['options']; 1131 $warnings = array(); 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 } 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.'), 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. 1201 * @return array Containing count, entries and warnings. 1202 * @since Moodle 3.1 1203 * @throws moodle_exception 1204 */ 1205 public static function get_entries_by_term($id, $term, $from, $limit, $options) { 1206 $params = self::validate_parameters(self::get_entries_by_term_parameters(), array( 1207 'id' => $id, 1208 'term' => $term, 1209 'from' => $from, 1210 'limit' => $limit, 1211 'options' => $options, 1212 )); 1213 $id = $params['id']; 1214 $term = $params['term']; 1215 $from = $params['from']; 1216 $limit = $params['limit']; 1217 $options = $params['options']; 1218 $warnings = array(); 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 } 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.'), 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. 1282 * @return array Containing count, entries and warnings. 1283 * @since Moodle 3.1 1284 * @throws moodle_exception 1285 */ 1286 public static function get_entries_to_approve($id, $letter, $order, $sort, $from, $limit) { 1287 $params = self::validate_parameters(self::get_entries_to_approve_parameters(), array( 1288 'id' => $id, 1289 'letter' => $letter, 1290 'order' => $order, 1291 'sort' => $sort, 1292 'from' => $from, 1293 'limit' => $limit 1294 )); 1295 $id = $params['id']; 1296 $letter = $params['letter']; 1297 $order = $params['order']; 1298 $sort = $params['sort']; 1299 $from = $params['from']; 1300 $limit = $params['limit']; 1301 $warnings = array(); 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 } 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.'), 1333 'entries' => new external_multiple_structure( 1334 self::get_entry_return_structure() 1335 ), 1336 'warnings' => new external_warnings() 1337 )); 1338 } 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. 1356 * @return array Containing entry and warnings. 1357 * @since Moodle 3.1 1358 * @throws moodle_exception 1359 * @throws invalid_parameter_exception 1360 */ 1361 public static function get_entry_by_id($id) { 1362 global $DB, $USER; 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 1398 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Thu Aug 11 10:00:09 2016 | Cross-referenced by PHPXref 0.7.1 |