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