Search moodle.org's
Developer Documentation
Developer Documentation
- Bug fixes for general core bugs in 3.11.x will end 14 Nov 2022 (12 months plus 6 months extension).
- Bug fixes for security issues in 3.11.x will end 13 Nov 2023 (18 months plus 12 months extension).
- PHP version: minimum PHP 7.3.0 Note: minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is supported too.
/webservice/ -> renderer.php (source)
Differences Between: [Versions 310 and 311] [Versions 311 and 401] [Versions 311 and 402] [Versions 311 and 403] [Versions 39 and 311]
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 * @param external_description $paramdescription the description structure of the web service function parameters 501 * @param string $indentation Indentation in the generated HTML code; should contain only spaces. 502 * @return string the html to diplay 503 */ 504 public function xmlrpc_param_description_html($paramdescription, $indentation = "") { 505 $indentation = $indentation . " "; 506 $brakeline = <<<EOF 507 508 509 EOF; 510 // description object is a list 511 if ($paramdescription instanceof external_multiple_structure) { 512 $return = $brakeline . $indentation . "Array "; 513 $indentation = $indentation . " "; 514 $return .= $brakeline . $indentation . "("; 515 $return .= $brakeline . $indentation . "[0] =>"; 516 $return .= $this->xmlrpc_param_description_html($paramdescription->content, $indentation); 517 $return .= $brakeline . $indentation . ")"; 518 return $return; 519 } else if ($paramdescription instanceof external_single_structure) { 520 // description object is an object 521 $singlestructuredesc = $brakeline . $indentation . "Array "; 522 $keyindentation = $indentation . " "; 523 $singlestructuredesc .= $brakeline . $keyindentation . "("; 524 foreach ($paramdescription->keys as $attributname => $attribut) { 525 $singlestructuredesc .= $brakeline . $keyindentation . "[" . $attributname . "] =>" . 526 $this->xmlrpc_param_description_html( 527 $paramdescription->keys[$attributname], $keyindentation) . 528 $keyindentation; 529 } 530 $singlestructuredesc .= $brakeline . $keyindentation . ")"; 531 return $singlestructuredesc; 532 } else { 533 // description object is a primary type (string, integer) 534 switch ($paramdescription->type) { 535 case PARAM_BOOL: // 0 or 1 only for now 536 case PARAM_INT: 537 $type = 'int'; 538 break; 539 case PARAM_FLOAT; 540 $type = 'double'; 541 break; 542 default: 543 $type = 'string'; 544 } 545 return " " . $type; 546 } 547 } 548 549 /** 550 * Return the html of a coloured box with content 551 * 552 * @param string $title - the title of the box 553 * @param string $content - the content to displayed 554 * @param string $rgb - the background color of the box 555 * @return string HTML code 556 */ 557 public function colored_box_with_pre_tag($title, $content, $rgb = 'FEEBE5') { 558 //TODO MDL-31192 this tag removes xhtml strict error but cause warning 559 $coloredbox = html_writer::start_tag('div', array()); 560 $coloredbox .= html_writer::start_tag('div', 561 array('style' => "border:solid 1px #DEDEDE;background:#" . $rgb 562 . ";color:#222222;padding:4px;")); 563 $coloredbox .= html_writer::start_tag('pre', array()); 564 $coloredbox .= html_writer::start_tag('b', array()); 565 $coloredbox .= $title; 566 $coloredbox .= html_writer::end_tag('b', array()); 567 $coloredbox .= html_writer::empty_tag('br', array()); 568 $coloredbox .= "\n" . $content . "\n"; 569 $coloredbox .= html_writer::end_tag('pre', array()); 570 $coloredbox .= html_writer::end_tag('div', array()); 571 $coloredbox .= html_writer::end_tag('div', array()); 572 return $coloredbox; 573 } 574 575 /** 576 * Return indented REST param description 577 * 578 * @param external_description $paramdescription the description structure of the web service function parameters 579 * @param string $paramstring parameter 580 * @return string the html to diplay 581 */ 582 public function rest_param_description_html($paramdescription, $paramstring) { 583 $brakeline = <<<EOF 584 585 586 EOF; 587 // description object is a list 588 if ($paramdescription instanceof external_multiple_structure) { 589 $paramstring = $paramstring . '[0]'; 590 $return = $this->rest_param_description_html($paramdescription->content, $paramstring); 591 return $return; 592 } else if ($paramdescription instanceof external_single_structure) { 593 // description object is an object 594 $singlestructuredesc = ""; 595 $initialparamstring = $paramstring; 596 foreach ($paramdescription->keys as $attributname => $attribut) { 597 $paramstring = $initialparamstring . '[' . $attributname . ']'; 598 $singlestructuredesc .= $this->rest_param_description_html( 599 $paramdescription->keys[$attributname], $paramstring); 600 } 601 return $singlestructuredesc; 602 } else { 603 // description object is a primary type (string, integer) 604 $paramstring = $paramstring . '='; 605 switch ($paramdescription->type) { 606 case PARAM_BOOL: // 0 or 1 only for now 607 case PARAM_INT: 608 $type = 'int'; 609 break; 610 case PARAM_FLOAT; 611 $type = 'double'; 612 break; 613 default: 614 $type = 'string'; 615 } 616 return $paramstring . " " . $type . $brakeline; 617 } 618 } 619 620 /** 621 * Displays all the documentation 622 * 623 * @param array $functions external_description of all the web service functions 624 * @param boolean $printableformat true if we want to display the documentation in a printable format 625 * @param array $activatedprotocol the currently enabled protocol 626 * @param array $authparams url parameters (it contains 'tokenid' and sometimes 'print') 627 * @param string $parenturl url of the calling page - needed for the print button url: 628 * '/admin/documentation.php' or '/webservice/wsdoc.php' (default) 629 * @return string the html to diplay 630 */ 631 public function documentation_html($functions, $printableformat, $activatedprotocol, 632 $authparams, $parenturl = '/webservice/wsdoc.php') { 633 634 $documentationhtml = $this->output->heading(get_string('wsdocapi', 'webservice')); 635 636 $br = html_writer::empty_tag('br', array()); 637 $brakeline = <<<EOF 638 639 640 EOF; 641 // Some general information 642 $docinfo = new stdClass(); 643 $docurl = new moodle_url('http://docs.moodle.org/dev/Creating_a_web_service_client'); 644 $docinfo->doclink = html_writer::tag('a', 645 get_string('wsclientdoc', 'webservice'), array('href' => $docurl)); 646 $documentationhtml .= get_string('wsdocumentationintro', 'webservice', $docinfo); 647 $documentationhtml .= $br . $br; 648 649 650 // Print button 651 $authparams['print'] = true; 652 $url = new moodle_url($parenturl, $authparams); // Required 653 $documentationhtml .= $this->output->single_button($url, get_string('print', 'webservice')); 654 $documentationhtml .= $br; 655 656 657 // each functions will be displayed into a collapsible region 658 //(opened if printableformat = true) 659 foreach ($functions as $functionname => $description) { 660 661 if (empty($printableformat)) { 662 $documentationhtml .= print_collapsible_region_start('', 663 'aera_' . $functionname, 664 html_writer::start_tag('strong', array()) 665 . $functionname . html_writer::end_tag('strong'), 666 false, 667 !$printableformat, 668 true); 669 } else { 670 $documentationhtml .= html_writer::tag('strong', $functionname); 671 $documentationhtml .= $br; 672 } 673 674 // function global description 675 $documentationhtml .= $br; 676 $documentationhtml .= html_writer::start_tag('div', 677 array('style' => 'border:solid 1px #DEDEDE;background:#E2E0E0; 678 color:#222222;padding:4px;')); 679 $documentationhtml .= s($description->description); 680 $documentationhtml .= html_writer::end_tag('div'); 681 $documentationhtml .= $br . $br; 682 683 // function arguments documentation 684 $documentationhtml .= html_writer::start_tag('span', array('style' => 'color:#EA33A6')); 685 $documentationhtml .= get_string('arguments', 'webservice'); 686 $documentationhtml .= html_writer::end_tag('span'); 687 $documentationhtml .= $br; 688 foreach ($description->parameters_desc->keys as $paramname => $paramdesc) { 689 // a argument documentation 690 $documentationhtml .= html_writer::start_tag('span', array('style' => 'font-size:80%')); 691 692 if ($paramdesc->required == VALUE_REQUIRED) { 693 $required = get_string('required', 'webservice'); 694 } 695 if ($paramdesc->required == VALUE_DEFAULT) { 696 if ($paramdesc->default === null) { 697 $default = "null"; 698 } else { 699 $default = print_r($paramdesc->default, true); 700 } 701 $required = get_string('default', 'webservice', $default); 702 } 703 if ($paramdesc->required == VALUE_OPTIONAL) { 704 $required = get_string('optional', 'webservice'); 705 } 706 707 $documentationhtml .= html_writer::start_tag('b', array()); 708 $documentationhtml .= $paramname; 709 $documentationhtml .= html_writer::end_tag('b'); 710 $documentationhtml .= " (" . $required . ")"; // argument is required or optional ? 711 $documentationhtml .= $br; 712 $documentationhtml .= " " 713 . s($paramdesc->desc); // Argument description. 714 $documentationhtml .= $br . $br; 715 // general structure of the argument 716 $documentationhtml .= $this->colored_box_with_pre_tag( 717 get_string('generalstructure', 'webservice'), 718 $this->detailed_description_html($paramdesc), 719 'FFF1BC'); 720 // xml-rpc structure of the argument in PHP format 721 if (!empty($activatedprotocol['xmlrpc'])) { 722 $documentationhtml .= $this->colored_box_with_pre_tag( 723 get_string('phpparam', 'webservice'), 724 htmlentities('[' . $paramname . '] =>' 725 . $this->xmlrpc_param_description_html($paramdesc)), 726 'DFEEE7'); 727 } 728 // POST format for the REST protocol for the argument 729 if (!empty($activatedprotocol['rest'])) { 730 $documentationhtml .= $this->colored_box_with_pre_tag( 731 get_string('restparam', 'webservice'), 732 htmlentities($this->rest_param_description_html( 733 $paramdesc, $paramname)), 734 'FEEBE5'); 735 } 736 $documentationhtml .= html_writer::end_tag('span'); 737 } 738 $documentationhtml .= $br . $br; 739 740 741 // function response documentation 742 $documentationhtml .= html_writer::start_tag('span', array('style' => 'color:#EA33A6')); 743 $documentationhtml .= get_string('response', 'webservice'); 744 $documentationhtml .= html_writer::end_tag('span'); 745 $documentationhtml .= $br; 746 // function response description 747 $documentationhtml .= html_writer::start_tag('span', array('style' => 'font-size:80%')); 748 if (!empty($description->returns_desc->desc)) { 749 $documentationhtml .= $description->returns_desc->desc; 750 $documentationhtml .= $br . $br; 751 } 752 if (!empty($description->returns_desc)) { 753 // general structure of the response 754 $documentationhtml .= $this->colored_box_with_pre_tag( 755 get_string('generalstructure', 'webservice'), 756 $this->detailed_description_html($description->returns_desc), 757 'FFF1BC'); 758 // xml-rpc structure of the response in PHP format 759 if (!empty($activatedprotocol['xmlrpc'])) { 760 $documentationhtml .= $this->colored_box_with_pre_tag( 761 get_string('phpresponse', 'webservice'), 762 htmlentities($this->xmlrpc_param_description_html( 763 $description->returns_desc)), 764 'DFEEE7'); 765 } 766 // XML response for the REST protocol 767 if (!empty($activatedprotocol['rest'])) { 768 $restresponse = "<?xml version=\"1.0\" encoding=\"UTF-8\" ?>" 769 . $brakeline . "<RESPONSE>" . $brakeline; 770 $restresponse .= $this->description_in_indented_xml_format( 771 $description->returns_desc); 772 $restresponse .="</RESPONSE>" . $brakeline; 773 $documentationhtml .= $this->colored_box_with_pre_tag( 774 get_string('restcode', 'webservice'), 775 htmlentities($restresponse), 776 'FEEBE5'); 777 } 778 } 779 $documentationhtml .= html_writer::end_tag('span'); 780 $documentationhtml .= $br . $br; 781 782 // function errors documentation for REST protocol 783 if (!empty($activatedprotocol['rest'])) { 784 $documentationhtml .= html_writer::start_tag('span', array('style' => 'color:#EA33A6')); 785 $documentationhtml .= get_string('errorcodes', 'webservice'); 786 $documentationhtml .= html_writer::end_tag('span'); 787 $documentationhtml .= $br . $br; 788 $documentationhtml .= html_writer::start_tag('span', array('style' => 'font-size:80%')); 789 $errormessage = get_string('invalidparameter', 'debug'); 790 $restexceptiontext = <<<EOF 791 <?xml version="1.0" encoding="UTF-8"?> 792 <EXCEPTION class="invalid_parameter_exception"> 793 <MESSAGE>{$errormessage}</MESSAGE> 794 <DEBUGINFO></DEBUGINFO> 795 </EXCEPTION> 796 EOF; 797 $documentationhtml .= $this->colored_box_with_pre_tag( 798 get_string('restexception', 'webservice'), 799 htmlentities($restexceptiontext), 800 'FEEBE5'); 801 802 $documentationhtml .= html_writer::end_tag('span'); 803 } 804 $documentationhtml .= $br . $br; 805 806 // Login required info. 807 $documentationhtml .= html_writer::start_tag('span', array('style' => 'color:#EA33A6')); 808 $documentationhtml .= get_string('loginrequired', 'webservice') . $br; 809 $documentationhtml .= html_writer::end_tag('span'); 810 $documentationhtml .= $description->loginrequired ? get_string('yes') : get_string('no'); 811 $documentationhtml .= $br . $br; 812 813 // Ajax info. 814 $documentationhtml .= html_writer::start_tag('span', array('style' => 'color:#EA33A6')); 815 $documentationhtml .= get_string('callablefromajax', 'webservice') . $br; 816 $documentationhtml .= html_writer::end_tag('span'); 817 $documentationhtml .= $description->allowed_from_ajax ? get_string('yes') : get_string('no'); 818 $documentationhtml .= $br . $br; 819 820 if (empty($printableformat)) { 821 $documentationhtml .= print_collapsible_region_end(true); 822 } 823 } 824 825 return $documentationhtml; 826 } 827 828 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
