Search moodle.org's
Developer Documentation
Developer Documentation
- Bug fixes for general core bugs in 4.2.x will end 22 April 2024 (12 months).
- Bug fixes for security issues in 4.2.x will end 7 October 2024 (18 months).
- PHP version: minimum PHP 8.0.0 Note: minimum PHP version has increased since Moodle 4.1. PHP 8.1.x is supported too.
/webservice/ -> renderer.php (source)
Differences Between: [Versions 310 and 402] [Versions 311 and 402] [Versions 39 and 402] [Versions 400 and 402] [Versions 401 and 402] [Versions 402 and 403]
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 use core_external\external_api; 18 use core_external\external_multiple_structure; 19 use core_external\external_single_structure; 20 21 /** 22 * Web service documentation renderer. 23 * 24 * @package core_webservice 25 * @category output 26 * @copyright 2009 Jerome Mouneyrac <jerome@moodle.com> 27 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 28 */ 29 class core_webservice_renderer extends plugin_renderer_base { 30 31 /** 32 * Display the authorised user selector 33 * 34 * @param stdClass $options It contains alloweduserselector, potentialuserselector and serviceid 35 * @return string html 36 */ 37 public function admin_authorised_user_selector(&$options) { 38 global $CFG; 39 $formcontent = html_writer::empty_tag('input', 40 array('name' => 'sesskey', 'value' => sesskey(), 'type' => 'hidden')); 41 42 $table = new html_table(); 43 $table->size = array('45%', '10%', '45%'); 44 $table->attributes['class'] = 'roleassigntable generaltable generalbox boxaligncenter'; 45 $table->summary = ''; 46 $table->cellspacing = 0; 47 $table->cellpadding = 0; 48 49 // LTR/RTL support, for drawing button arrows in the right direction 50 if (right_to_left()) { 51 $addarrow = '▶'; 52 $removearrow = '◀'; 53 } else { 54 $addarrow = '◀'; 55 $removearrow = '▶'; 56 } 57 58 //create the add and remove button 59 $addinput = html_writer::empty_tag('input', 60 array('name' => 'add', 'id' => 'add', 'type' => 'submit', 61 'value' => $addarrow . ' ' . get_string('add'), 62 'title' => get_string('add'))); 63 $addbutton = html_writer::tag('div', $addinput, array('id' => 'addcontrols')); 64 $removeinput = html_writer::empty_tag('input', 65 array('name' => 'remove', 'id' => 'remove', 'type' => 'submit', 66 'value' => $removearrow . ' ' . get_string('remove'), 67 'title' => get_string('remove'))); 68 $removebutton = html_writer::tag('div', $removeinput, array('id' => 'removecontrols')); 69 70 71 //create the three cells 72 $label = html_writer::tag('label', get_string('serviceusers', 'webservice'), 73 array('for' => 'removeselect')); 74 $label = html_writer::tag('p', $label); 75 $authoriseduserscell = new html_table_cell($label . 76 $options->alloweduserselector->display(true)); 77 $authoriseduserscell->id = 'existingcell'; 78 $buttonscell = new html_table_cell($addbutton . html_writer::empty_tag('br') . $removebutton); 79 $buttonscell->id = 'buttonscell'; 80 $label = html_writer::tag('label', get_string('potusers', 'webservice'), 81 array('for' => 'addselect')); 82 $label = html_writer::tag('p', $label); 83 $otheruserscell = new html_table_cell($label . 84 $options->potentialuserselector->display(true)); 85 $otheruserscell->id = 'potentialcell'; 86 87 $cells = array($authoriseduserscell, $buttonscell, $otheruserscell); 88 $row = new html_table_row($cells); 89 $table->data[] = $row; 90 $formcontent .= html_writer::table($table); 91 92 $formcontent = html_writer::tag('div', $formcontent); 93 94 $actionurl = new moodle_url('/' . $CFG->admin . '/webservice/service_users.php', 95 array('id' => $options->serviceid)); 96 $html = html_writer::tag('form', $formcontent, 97 array('id' => 'assignform', 'action' => $actionurl, 'method' => 'post')); 98 return $html; 99 } 100 101 /** 102 * Display list of authorised users for the given external service. 103 * 104 * @param array $users authorised users 105 * @param int $serviceid service id 106 * @return string $html 107 */ 108 public function admin_authorised_user_list($users, $serviceid) { 109 global $CFG; 110 111 $listitems = []; 112 $extrafields = \core_user\fields::get_identity_fields(context_system::instance()); 113 114 foreach ($users as $user) { 115 $settingsurl = new moodle_url('/admin/webservice/service_user_settings.php', 116 ['userid' => $user->id, 'serviceid' => $serviceid]); 117 118 $identity = []; 119 foreach ($extrafields as $extrafield) { 120 if (isset($user->{$extrafield})) { 121 $identity[] = s($user->{$extrafield}); 122 } 123 } 124 $identity = $identity ? html_writer::div(implode(', ', $identity), 'small') : ''; 125 126 $link = html_writer::link($settingsurl, fullname($user)); 127 128 if (!empty($user->missingcapabilities)) { 129 $count = html_writer::span(count($user->missingcapabilities), 'badge badge-danger'); 130 $links = array_map(function($capname) { 131 return get_capability_docs_link((object)['name' => $capname]) . html_writer::div($capname, 'text-muted'); 132 }, $user->missingcapabilities); 133 $list = html_writer::alist($links); 134 $help = $this->output->help_icon('missingcaps', 'webservice'); 135 $missingcaps = print_collapsible_region(html_writer::div($list . $help, 'missingcaps'), 'small', 136 html_writer::random_id('usermissingcaps'), get_string('usermissingcaps', 'webservice', $count), '', true, true); 137 138 } else { 139 $missingcaps = ''; 140 } 141 142 $listitems[] = $link . $identity . $missingcaps; 143 } 144 145 $html = html_writer::div(html_writer::alist($listitems), 'alloweduserlist'); 146 147 return $html; 148 } 149 150 /** 151 * Display a confirmation page to remove a function from a service 152 * 153 * @param stdClass $function It needs function id + function name properties. 154 * @param stdClass $service It needs service id + service name properties. 155 * @return string html 156 */ 157 public function admin_remove_service_function_confirmation($function, $service) { 158 $optionsyes = array('id' => $service->id, 'action' => 'delete', 159 'confirm' => 1, 'sesskey' => sesskey(), 'fid' => $function->id); 160 $optionsno = array('id' => $service->id); 161 $formcontinue = new single_button(new moodle_url('service_functions.php', 162 $optionsyes), get_string('remove')); 163 $formcancel = new single_button(new moodle_url('service_functions.php', 164 $optionsno), get_string('cancel'), 'get'); 165 return $this->output->confirm(get_string('removefunctionconfirm', 'webservice', 166 (object) array('service' => $service->name, 'function' => $function->name)), 167 $formcontinue, $formcancel); 168 } 169 170 /** 171 * Display a confirmation page to remove a service 172 * 173 * @param stdClass $service It needs service id + service name properties. 174 * @return string html 175 */ 176 public function admin_remove_service_confirmation($service) { 177 global $CFG; 178 $optionsyes = array('id' => $service->id, 'action' => 'delete', 179 'confirm' => 1, 'sesskey' => sesskey()); 180 $optionsno = array('section' => 'externalservices'); 181 $formcontinue = new single_button(new moodle_url('service.php', $optionsyes), 182 get_string('delete'), 'post'); 183 $formcancel = new single_button( 184 new moodle_url($CFG->wwwroot . "/" . $CFG->admin . "/settings.php", $optionsno), 185 get_string('cancel'), 'get'); 186 return $this->output->confirm(get_string('deleteserviceconfirm', 'webservice', $service->name), 187 $formcontinue, $formcancel); 188 } 189 190 /** 191 * Display a list of functions for a given service 192 * If the service is built-in, do not display remove/add operation (read-only) 193 * 194 * @param array $functions list of functions 195 * @param stdClass $service the given service 196 * @return string the table html + add operation html 197 */ 198 public function admin_service_function_list($functions, $service) { 199 global $CFG; 200 if (!empty($functions)) { 201 $table = new html_table(); 202 $table->head = array(get_string('function', 'webservice'), 203 get_string('description'), get_string('requiredcaps', 'webservice')); 204 $table->align = array('left', 'left', 'left'); 205 $table->size = array('15%', '40%', '40%'); 206 $table->width = '100%'; 207 $table->align[] = 'left'; 208 209 //display remove function operation (except for build-in service) 210 if (empty($service->component)) { 211 $table->head[] = get_string('edit'); 212 $table->align[] = 'center'; 213 } 214 215 $anydeprecated = false; 216 foreach ($functions as $function) { 217 $function = external_api::external_function_info($function); 218 219 if (!empty($function->deprecated)) { 220 $anydeprecated = true; 221 } 222 $requiredcaps = html_writer::tag('div', 223 empty($function->capabilities) ? '' : $function->capabilities, 224 array('class' => 'functiondesc')); 225 ; 226 $description = html_writer::tag('div', $function->description, 227 array('class' => 'functiondesc')); 228 //display remove function operation (except for build-in service) 229 if (empty($service->component)) { 230 $removeurl = new moodle_url('/' . $CFG->admin . '/webservice/service_functions.php', 231 array('sesskey' => sesskey(), 'fid' => $function->id, 232 'id' => $service->id, 233 'action' => 'delete')); 234 $removelink = html_writer::tag('a', 235 get_string('removefunction', 'webservice'), 236 array('href' => $removeurl)); 237 $table->data[] = array($function->name, $description, $requiredcaps, $removelink); 238 } else { 239 $table->data[] = array($function->name, $description, $requiredcaps); 240 } 241 } 242 243 $html = html_writer::table($table); 244 } else { 245 $html = get_string('nofunctions', 'webservice') . html_writer::empty_tag('br'); 246 } 247 248 //display add function operation (except for build-in service) 249 if (empty($service->component)) { 250 251 if (!empty($anydeprecated)) { 252 debugging('This service uses deprecated functions, replace them by the proposed ones and update your client/s.', DEBUG_DEVELOPER); 253 } 254 $addurl = new moodle_url('/' . $CFG->admin . '/webservice/service_functions.php', 255 array('sesskey' => sesskey(), 'id' => $service->id, 'action' => 'add')); 256 $html .= html_writer::tag('a', get_string('addfunctions', 'webservice'), array('href' => $addurl)); 257 } 258 259 return $html; 260 } 261 262 /** 263 * Display Reset token confirmation box 264 * 265 * @param stdClass $token token to reset 266 * @return string html 267 */ 268 public function user_reset_token_confirmation($token) { 269 $managetokenurl = '/user/managetoken.php'; 270 $optionsyes = ['tokenid' => $token->id, 'action' => 'resetwstoken', 'confirm' => 1]; 271 $formcontinue = new single_button(new moodle_url($managetokenurl, $optionsyes), get_string('reset')); 272 $formcancel = new single_button(new moodle_url($managetokenurl), get_string('cancel'), 'get'); 273 $html = $this->output->confirm(get_string('resettokenconfirm', 'webservice', 274 (object) array('user' => $token->firstname . " " . 275 $token->lastname, 'service' => $token->name)), 276 $formcontinue, $formcancel); 277 return $html; 278 } 279 280 /** 281 * Display user tokens with buttons to reset them 282 * 283 * @param stdClass $tokens user tokens 284 * @param int $userid user id 285 * @param bool $documentation if true display a link to the API documentation 286 * @return string html code 287 */ 288 public function user_webservice_tokens_box($tokens, $userid, $documentation = false) { 289 global $CFG, $DB; 290 291 // display strings 292 $stroperation = get_string('operation', 'webservice'); 293 $strtoken = get_string('key', 'webservice'); 294 $strservice = get_string('service', 'webservice'); 295 $strcreator = get_string('tokencreator', 'webservice'); 296 $strcontext = get_string('context', 'webservice'); 297 $strvaliduntil = get_string('validuntil', 'webservice'); 298 299 $return = $this->output->heading(get_string('securitykeys', 'webservice'), 3, 'main', true); 300 $return .= $this->output->box_start('generalbox webservicestokenui'); 301 302 $return .= get_string('keyshelp', 'webservice'); 303 304 $table = new html_table(); 305 $table->head = array($strtoken, $strservice, $strvaliduntil, $strcreator, $stroperation); 306 $table->align = array('left', 'left', 'left', 'center', 'left', 'center'); 307 $table->width = '100%'; 308 $table->data = array(); 309 310 if ($documentation) { 311 $table->head[] = get_string('doc', 'webservice'); 312 $table->align[] = 'center'; 313 } 314 315 if (!empty($tokens)) { 316 foreach ($tokens as $token) { 317 318 if ($token->creatorid == $userid) { 319 $reset = html_writer::link(new moodle_url('/user/managetoken.php', [ 320 'action' => 'resetwstoken', 321 'tokenid' => $token->id, 322 ]), get_string('reset')); 323 $creator = $token->firstname . " " . $token->lastname; 324 } else { 325 //retrieve administrator name 326 $admincreator = $DB->get_record('user', array('id'=>$token->creatorid)); 327 $creator = $admincreator->firstname . " " . $admincreator->lastname; 328 $reset = ''; 329 } 330 331 $userprofilurl = new moodle_url('/user/view.php?id=' . $token->creatorid); 332 $creatoratag = html_writer::start_tag('a', array('href' => $userprofilurl)); 333 $creatoratag .= $creator; 334 $creatoratag .= html_writer::end_tag('a'); 335 336 $validuntil = ''; 337 if (!empty($token->validuntil)) { 338 $validuntil = userdate($token->validuntil, get_string('strftimedatetime', 'langconfig')); 339 } 340 341 $tokenname = $token->name; 342 if (!$token->enabled) { //that is the (1 token-1ws) related ws is not enabled. 343 $tokenname = '<span class="dimmed_text">'.$token->name.'</span>'; 344 } 345 $row = array($token->token, $tokenname, $validuntil, $creatoratag, $reset); 346 347 if ($documentation) { 348 $doclink = new moodle_url('/webservice/wsdoc.php', 349 array('id' => $token->id)); 350 $row[] = html_writer::tag('a', get_string('doc', 'webservice'), 351 array('href' => $doclink)); 352 } 353 354 $table->data[] = $row; 355 } 356 $return .= html_writer::table($table); 357 } else { 358 $return .= get_string('notoken', 'webservice'); 359 } 360 361 $return .= $this->output->box_end(); 362 return $return; 363 } 364 365 /** 366 * Return documentation for a ws description object 367 * ws description object can be 'external_multiple_structure', 'external_single_structure' 368 * or 'external_value' 369 * 370 * Example of documentation for core_group_create_groups function: 371 * list of ( 372 * object { 373 * courseid int //id of course 374 * name string //multilang compatible name, course unique 375 * description string //group description text 376 * enrolmentkey string //group enrol secret phrase 377 * } 378 * ) 379 * 380 * @param stdClass $params a part of parameter/return description 381 * @return string the html to display 382 */ 383 public function detailed_description_html($params) { 384 // retrieve the description of the description object 385 $paramdesc = ""; 386 if (!empty($params->desc)) { 387 $paramdesc .= html_writer::start_tag('span', array('style' => "color:#2A33A6")); 388 if ($params->required == VALUE_REQUIRED) { 389 $required = ''; 390 } 391 if ($params->required == VALUE_DEFAULT) { 392 if ($params->default === null) { 393 $params->default = "null"; 394 } 395 $required = html_writer::start_tag('b', array()) . 396 get_string('default', 'webservice', print_r($params->default, true)) 397 . html_writer::end_tag('b'); 398 } 399 if ($params->required == VALUE_OPTIONAL) { 400 $required = html_writer::start_tag('b', array()) . 401 get_string('optional', 'webservice') . html_writer::end_tag('b'); 402 } 403 $paramdesc .= " " . $required . " "; 404 $paramdesc .= html_writer::start_tag('i', array()); 405 $paramdesc .= "//"; 406 407 $paramdesc .= s($params->desc); 408 409 $paramdesc .= html_writer::end_tag('i'); 410 411 $paramdesc .= html_writer::end_tag('span'); 412 $paramdesc .= html_writer::empty_tag('br', array()); 413 } 414 415 // description object is a list 416 if ($params instanceof external_multiple_structure) { 417 return $paramdesc . "list of ( " . html_writer::empty_tag('br', array()) 418 . $this->detailed_description_html($params->content) . ")"; 419 } else if ($params instanceof external_single_structure) { 420 // description object is an object 421 $singlestructuredesc = $paramdesc . "object {" . html_writer::empty_tag('br', array()); 422 foreach ($params->keys as $attributname => $attribut) { 423 $singlestructuredesc .= html_writer::start_tag('b', array()); 424 $singlestructuredesc .= $attributname; 425 $singlestructuredesc .= html_writer::end_tag('b'); 426 $singlestructuredesc .= " " . 427 $this->detailed_description_html($params->keys[$attributname]); 428 } 429 $singlestructuredesc .= "} "; 430 $singlestructuredesc .= html_writer::empty_tag('br', array()); 431 return $singlestructuredesc; 432 } else { 433 // description object is a primary type (string, integer) 434 switch ($params->type) { 435 case PARAM_BOOL: // 0 or 1 only for now 436 case PARAM_INT: 437 $type = 'int'; 438 break; 439 case PARAM_FLOAT; 440 $type = 'double'; 441 break; 442 default: 443 $type = 'string'; 444 } 445 return $type . " " . $paramdesc; 446 } 447 } 448 449 /** 450 * Return a description object in indented xml format (for REST response) 451 * It is indented to be output within <pre> tags 452 * 453 * @param external_description $returndescription the description structure of the web service function returned value 454 * @param string $indentation Indentation in the generated HTML code; should contain only spaces. 455 * @return string the html to diplay 456 */ 457 public function description_in_indented_xml_format($returndescription, $indentation = "") { 458 $indentation = $indentation . " "; 459 $brakeline = <<<EOF 460 461 462 EOF; 463 // description object is a list 464 if ($returndescription instanceof external_multiple_structure) { 465 $return = $indentation . "<MULTIPLE>" . $brakeline; 466 $return .= $this->description_in_indented_xml_format($returndescription->content, 467 $indentation); 468 $return .= $indentation . "</MULTIPLE>" . $brakeline; 469 return $return; 470 } else if ($returndescription instanceof external_single_structure) { 471 // description object is an object 472 $singlestructuredesc = $indentation . "<SINGLE>" . $brakeline; 473 $keyindentation = $indentation . " "; 474 foreach ($returndescription->keys as $attributname => $attribut) { 475 $singlestructuredesc .= $keyindentation . "<KEY name=\"" . $attributname . "\">" 476 . $brakeline . 477 $this->description_in_indented_xml_format( 478 $returndescription->keys[$attributname], $keyindentation) . 479 $keyindentation . "</KEY>" . $brakeline; 480 } 481 $singlestructuredesc .= $indentation . "</SINGLE>" . $brakeline; 482 return $singlestructuredesc; 483 } else { 484 // description object is a primary type (string, integer) 485 switch ($returndescription->type) { 486 case PARAM_BOOL: // 0 or 1 only for now 487 case PARAM_INT: 488 $type = 'int'; 489 break; 490 case PARAM_FLOAT; 491 $type = 'double'; 492 break; 493 default: 494 $type = 'string'; 495 } 496 return $indentation . "<VALUE>" . $type . "</VALUE>" . $brakeline; 497 } 498 } 499 500 /** 501 * Create indented XML-RPC param description 502 * 503 * @todo MDL-76078 - Incorrect inter-communication, core cannot have plugin dependencies like this. 504 * 505 * @param external_description $paramdescription the description structure of the web service function parameters 506 * @param string $indentation Indentation in the generated HTML code; should contain only spaces. 507 * @return string the html to diplay 508 */ 509 public function xmlrpc_param_description_html($paramdescription, $indentation = "") { 510 $indentation = $indentation . " "; 511 $brakeline = <<<EOF 512 513 514 EOF; 515 // description object is a list 516 if ($paramdescription instanceof external_multiple_structure) { 517 $return = $brakeline . $indentation . "Array "; 518 $indentation = $indentation . " "; 519 $return .= $brakeline . $indentation . "("; 520 $return .= $brakeline . $indentation . "[0] =>"; 521 $return .= $this->xmlrpc_param_description_html($paramdescription->content, $indentation); 522 $return .= $brakeline . $indentation . ")"; 523 return $return; 524 } else if ($paramdescription instanceof external_single_structure) { 525 // description object is an object 526 $singlestructuredesc = $brakeline . $indentation . "Array "; 527 $keyindentation = $indentation . " "; 528 $singlestructuredesc .= $brakeline . $keyindentation . "("; 529 foreach ($paramdescription->keys as $attributname => $attribut) { 530 $singlestructuredesc .= $brakeline . $keyindentation . "[" . $attributname . "] =>" . 531 $this->xmlrpc_param_description_html( 532 $paramdescription->keys[$attributname], $keyindentation) . 533 $keyindentation; 534 } 535 $singlestructuredesc .= $brakeline . $keyindentation . ")"; 536 return $singlestructuredesc; 537 } else { 538 // description object is a primary type (string, integer) 539 switch ($paramdescription->type) { 540 case PARAM_BOOL: // 0 or 1 only for now 541 case PARAM_INT: 542 $type = 'int'; 543 break; 544 case PARAM_FLOAT; 545 $type = 'double'; 546 break; 547 default: 548 $type = 'string'; 549 } 550 return " " . $type; 551 } 552 } 553 554 /** 555 * Return the html of a coloured box with content 556 * 557 * @param string $title - the title of the box 558 * @param string $content - the content to displayed 559 * @param string $rgb - the background color of the box 560 * @return string HTML code 561 */ 562 public function colored_box_with_pre_tag($title, $content, $rgb = 'FEEBE5') { 563 //TODO MDL-31192 this tag removes xhtml strict error but cause warning 564 $coloredbox = html_writer::start_tag('div', array()); 565 $coloredbox .= html_writer::start_tag('div', 566 array('style' => "border:solid 1px #DEDEDE;background:#" . $rgb 567 . ";color:#222222;padding:4px;")); 568 $coloredbox .= html_writer::start_tag('pre', array()); 569 $coloredbox .= html_writer::start_tag('b', array()); 570 $coloredbox .= $title; 571 $coloredbox .= html_writer::end_tag('b', array()); 572 $coloredbox .= html_writer::empty_tag('br', array()); 573 $coloredbox .= "\n" . $content . "\n"; 574 $coloredbox .= html_writer::end_tag('pre', array()); 575 $coloredbox .= html_writer::end_tag('div', array()); 576 $coloredbox .= html_writer::end_tag('div', array()); 577 return $coloredbox; 578 } 579 580 /** 581 * Return indented REST param description 582 * 583 * @todo MDL-76078 - Incorrect inter-communication, core cannot have plugin dependencies like this. 584 * 585 * @param external_description $paramdescription the description structure of the web service function parameters 586 * @param string $paramstring parameter 587 * @return string the html to diplay 588 */ 589 public function rest_param_description_html($paramdescription, $paramstring) { 590 $brakeline = <<<EOF 591 592 593 EOF; 594 // description object is a list 595 if ($paramdescription instanceof external_multiple_structure) { 596 $paramstring = $paramstring . '[0]'; 597 $return = $this->rest_param_description_html($paramdescription->content, $paramstring); 598 return $return; 599 } else if ($paramdescription instanceof external_single_structure) { 600 // description object is an object 601 $singlestructuredesc = ""; 602 $initialparamstring = $paramstring; 603 foreach ($paramdescription->keys as $attributname => $attribut) { 604 $paramstring = $initialparamstring . '[' . $attributname . ']'; 605 $singlestructuredesc .= $this->rest_param_description_html( 606 $paramdescription->keys[$attributname], $paramstring); 607 } 608 return $singlestructuredesc; 609 } else { 610 // description object is a primary type (string, integer) 611 $paramstring = $paramstring . '='; 612 switch ($paramdescription->type) { 613 case PARAM_BOOL: // 0 or 1 only for now 614 case PARAM_INT: 615 $type = 'int'; 616 break; 617 case PARAM_FLOAT; 618 $type = 'double'; 619 break; 620 default: 621 $type = 'string'; 622 } 623 return $paramstring . " " . $type . $brakeline; 624 } 625 } 626 627 /** 628 * Displays all the documentation 629 * 630 * @todo MDL-76078 - Incorrect inter-communication, core cannot have plugin dependencies like this. 631 * 632 * @param array $functions external_description of all the web service functions 633 * @param boolean $printableformat true if we want to display the documentation in a printable format 634 * @param array $activatedprotocol the currently enabled protocol 635 * @param array $authparams url parameters (it contains 'tokenid' and sometimes 'print') 636 * @param string $parenturl url of the calling page - needed for the print button url: 637 * '/admin/documentation.php' or '/webservice/wsdoc.php' (default) 638 * @return string the html to diplay 639 */ 640 public function documentation_html($functions, $printableformat, $activatedprotocol, 641 $authparams, $parenturl = '/webservice/wsdoc.php') { 642 643 $documentationhtml = $this->output->heading(get_string('wsdocapi', 'webservice')); 644 645 $br = html_writer::empty_tag('br', array()); 646 $brakeline = <<<EOF 647 648 649 EOF; 650 // Some general information 651 $docinfo = new stdClass(); 652 $docurl = new moodle_url('http://docs.moodle.org/dev/Creating_a_web_service_client'); 653 $docinfo->doclink = html_writer::tag('a', 654 get_string('wsclientdoc', 'webservice'), array('href' => $docurl)); 655 $documentationhtml .= get_string('wsdocumentationintro', 'webservice', $docinfo); 656 $documentationhtml .= $br . $br; 657 658 659 // Print button 660 $authparams['print'] = true; 661 $url = new moodle_url($parenturl, $authparams); // Required 662 $documentationhtml .= $this->output->single_button($url, get_string('print', 'webservice')); 663 $documentationhtml .= $br; 664 665 666 // each functions will be displayed into a collapsible region 667 //(opened if printableformat = true) 668 foreach ($functions as $functionname => $description) { 669 670 $tags = ''; 671 if (!empty($description->deprecated)) { 672 $tags .= ' ' . html_writer::span(get_string('deprecated', 'core_webservice'), 'badge badge-warning'); 673 } 674 675 if (empty($printableformat)) { 676 $documentationhtml .= print_collapsible_region_start('', 677 'aera_' . $functionname, 678 html_writer::start_tag('strong', array()) 679 . $functionname . html_writer::end_tag('strong') . $tags, 680 false, 681 !$printableformat, 682 true); 683 } else { 684 $documentationhtml .= html_writer::tag('strong', $functionname) . $tags; 685 $documentationhtml .= $br; 686 } 687 688 // function global description 689 $documentationhtml .= $br; 690 $documentationhtml .= html_writer::start_tag('div', 691 array('style' => 'border:solid 1px #DEDEDE;background:#E2E0E0; 692 color:#222222;padding:4px;')); 693 $documentationhtml .= s($description->description); 694 $documentationhtml .= html_writer::end_tag('div'); 695 $documentationhtml .= $br . $br; 696 697 // function arguments documentation 698 $documentationhtml .= html_writer::start_tag('span', array('style' => 'color:#EA33A6')); 699 $documentationhtml .= get_string('arguments', 'webservice'); 700 $documentationhtml .= html_writer::end_tag('span'); 701 $documentationhtml .= $br; 702 foreach ($description->parameters_desc->keys as $paramname => $paramdesc) { 703 // a argument documentation 704 $documentationhtml .= html_writer::start_tag('span', array('style' => 'font-size:80%')); 705 706 if ($paramdesc->required == VALUE_REQUIRED) { 707 $required = get_string('required', 'webservice'); 708 } 709 if ($paramdesc->required == VALUE_DEFAULT) { 710 if ($paramdesc->default === null) { 711 $default = "null"; 712 } else { 713 $default = print_r($paramdesc->default, true); 714 } 715 $required = get_string('default', 'webservice', $default); 716 } 717 if ($paramdesc->required == VALUE_OPTIONAL) { 718 $required = get_string('optional', 'webservice'); 719 } 720 721 $documentationhtml .= html_writer::start_tag('b', array()); 722 $documentationhtml .= $paramname; 723 $documentationhtml .= html_writer::end_tag('b'); 724 $documentationhtml .= " (" . $required . ")"; // argument is required or optional ? 725 $documentationhtml .= $br; 726 $documentationhtml .= " " 727 . s($paramdesc->desc); // Argument description. 728 $documentationhtml .= $br . $br; 729 // general structure of the argument 730 $documentationhtml .= $this->colored_box_with_pre_tag( 731 get_string('generalstructure', 'webservice'), 732 $this->detailed_description_html($paramdesc), 733 'FFF1BC'); 734 // xml-rpc structure of the argument in PHP format 735 if (!empty($activatedprotocol['xmlrpc'])) { 736 $documentationhtml .= $this->colored_box_with_pre_tag( 737 get_string('phpparam', 'webservice'), 738 htmlentities('[' . $paramname . '] =>' 739 . $this->xmlrpc_param_description_html($paramdesc), ENT_COMPAT), 740 'DFEEE7'); 741 } 742 // POST format for the REST protocol for the argument 743 if (!empty($activatedprotocol['rest'])) { 744 $documentationhtml .= $this->colored_box_with_pre_tag( 745 get_string('restparam', 'webservice'), 746 htmlentities($this->rest_param_description_html( 747 $paramdesc, $paramname), ENT_COMPAT), 748 'FEEBE5'); 749 } 750 $documentationhtml .= html_writer::end_tag('span'); 751 } 752 $documentationhtml .= $br . $br; 753 754 755 // function response documentation 756 $documentationhtml .= html_writer::start_tag('span', array('style' => 'color:#EA33A6')); 757 $documentationhtml .= get_string('response', 'webservice'); 758 $documentationhtml .= html_writer::end_tag('span'); 759 $documentationhtml .= $br; 760 // function response description 761 $documentationhtml .= html_writer::start_tag('span', array('style' => 'font-size:80%')); 762 if (!empty($description->returns_desc->desc)) { 763 $documentationhtml .= $description->returns_desc->desc; 764 $documentationhtml .= $br . $br; 765 } 766 if (!empty($description->returns_desc)) { 767 // general structure of the response 768 $documentationhtml .= $this->colored_box_with_pre_tag( 769 get_string('generalstructure', 'webservice'), 770 $this->detailed_description_html($description->returns_desc), 771 'FFF1BC'); 772 // xml-rpc structure of the response in PHP format 773 if (!empty($activatedprotocol['xmlrpc'])) { 774 $documentationhtml .= $this->colored_box_with_pre_tag( 775 get_string('phpresponse', 'webservice'), 776 htmlentities($this->xmlrpc_param_description_html( 777 $description->returns_desc), ENT_COMPAT), 778 'DFEEE7'); 779 } 780 // XML response for the REST protocol 781 if (!empty($activatedprotocol['rest'])) { 782 $restresponse = "<?xml version=\"1.0\" encoding=\"UTF-8\" ?>" 783 . $brakeline . "<RESPONSE>" . $brakeline; 784 $restresponse .= $this->description_in_indented_xml_format( 785 $description->returns_desc); 786 $restresponse .="</RESPONSE>" . $brakeline; 787 $documentationhtml .= $this->colored_box_with_pre_tag( 788 get_string('restcode', 'webservice'), 789 htmlentities($restresponse, ENT_COMPAT), 790 'FEEBE5'); 791 } 792 } 793 $documentationhtml .= html_writer::end_tag('span'); 794 $documentationhtml .= $br . $br; 795 796 // function errors documentation for REST protocol 797 if (!empty($activatedprotocol['rest'])) { 798 $documentationhtml .= html_writer::start_tag('span', array('style' => 'color:#EA33A6')); 799 $documentationhtml .= get_string('errorcodes', 'webservice'); 800 $documentationhtml .= html_writer::end_tag('span'); 801 $documentationhtml .= $br . $br; 802 $documentationhtml .= html_writer::start_tag('span', array('style' => 'font-size:80%')); 803 $errormessage = get_string('invalidparameter', 'debug'); 804 $restexceptiontext = <<<EOF 805 <?xml version="1.0" encoding="UTF-8"?> 806 <EXCEPTION class="invalid_parameter_exception"> 807 <MESSAGE>{$errormessage}</MESSAGE> 808 <DEBUGINFO></DEBUGINFO> 809 </EXCEPTION> 810 EOF; 811 $documentationhtml .= $this->colored_box_with_pre_tag( 812 get_string('restexception', 'webservice'), 813 htmlentities($restexceptiontext, ENT_COMPAT), 814 'FEEBE5'); 815 816 $documentationhtml .= html_writer::end_tag('span'); 817 } 818 $documentationhtml .= $br . $br; 819 820 // Login required info. 821 $documentationhtml .= html_writer::start_tag('span', array('style' => 'color:#EA33A6')); 822 $documentationhtml .= get_string('loginrequired', 'webservice') . $br; 823 $documentationhtml .= html_writer::end_tag('span'); 824 $documentationhtml .= $description->loginrequired ? get_string('yes') : get_string('no'); 825 $documentationhtml .= $br . $br; 826 827 // Ajax info. 828 $documentationhtml .= html_writer::start_tag('span', array('style' => 'color:#EA33A6')); 829 $documentationhtml .= get_string('callablefromajax', 'webservice') . $br; 830 $documentationhtml .= html_writer::end_tag('span'); 831 $documentationhtml .= $description->allowed_from_ajax ? get_string('yes') : get_string('no'); 832 $documentationhtml .= $br . $br; 833 834 if (empty($printableformat)) { 835 $documentationhtml .= print_collapsible_region_end(true); 836 } 837 } 838 839 return $documentationhtml; 840 } 841 842 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
