webservice/renderer.php

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