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                 $row = array($token->token, $token->name, $validuntil, $creatoratag, $reset);
 324
 325                 if ($documentation) {
 326                     $doclink = new moodle_url('/webservice/wsdoc.php',
 327                             array('id' => $token->id, 'sesskey' => sesskey()));
 328                     $row[] = html_writer::tag('a', get_string('doc', 'webservice'),
 329                             array('href' => $doclink));
 330                 }
 331
 332                 $table->data[] = $row;
 333             }
 334             $return .= html_writer::table($table);
 335         } else {
 336             $return .= get_string('notoken', 'webservice');
 337         }
 338
 339         $return .= $this->output->box_end();
 340         return $return;
 341     }
 342
 343     /**
 344      * Return documentation for a ws description object
 345      * ws description object can be 'external_multiple_structure', 'external_single_structure'
 346      * or 'external_value'
 347      * Example of documentation for moodle_group_create_groups function:
 348       list of (
 349       object {
 350       courseid int //id of course
 351       name string //multilang compatible name, course unique
 352       description string //group description text
 353       enrolmentkey string //group enrol secret phrase
 354       }
 355       )
 356      * @param object $params a part of parameter/return description
 357      * @return string the html to display
 358      */
 359     public function detailed_description_html($params) {
 360         /// retrieve the description of the description object
 361         $paramdesc = "";
 362         if (!empty($params->desc)) {
 363             $paramdesc .= html_writer::start_tag('span', array('style' => "color:#2A33A6"));
 364             if ($params->required == VALUE_REQUIRED) {
 365                 $required = '';
 366             }
 367             if ($params->required == VALUE_DEFAULT) {
 368                 if ($params->default === null) {
 369                     $params->default = "null";
 370                 }
 371                 $required = html_writer::start_tag('b', array()) .
 372                         get_string('default', 'webservice', print_r($params->default, true))
 373                         . html_writer::end_tag('b');
 374             }
 375             if ($params->required == VALUE_OPTIONAL) {
 376                 $required = html_writer::start_tag('b', array()) .
 377                         get_string('optional', 'webservice') . html_writer::end_tag('b');
 378             }
 379             $paramdesc .= " " . $required . " ";
 380             $paramdesc .= html_writer::start_tag('i', array());
 381             $paramdesc .= "//";
 382
 383             $paramdesc .= $params->desc;
 384
 385             $paramdesc .= html_writer::end_tag('i');
 386
 387             $paramdesc .= html_writer::end_tag('span');
 388             $paramdesc .= html_writer::empty_tag('br', array());
 389         }
 390
 391         /// description object is a list
 392         if ($params instanceof external_multiple_structure) {
 393             return $paramdesc . "list of ( " . html_writer::empty_tag('br', array())
 394             . $this->detailed_description_html($params->content) . ")";
 395         } else if ($params instanceof external_single_structure) {
 396             /// description object is an object
 397             $singlestructuredesc = $paramdesc . "object {" . html_writer::empty_tag('br', array());
 398             foreach ($params->keys as $attributname => $attribut) {
 399                 $singlestructuredesc .= html_writer::start_tag('b', array());
 400                 $singlestructuredesc .= $attributname;
 401                 $singlestructuredesc .= html_writer::end_tag('b');
 402                 $singlestructuredesc .= " " .
 403                         $this->detailed_description_html($params->keys[$attributname]);
 404             }
 405             $singlestructuredesc .= "} ";
 406             $singlestructuredesc .= html_writer::empty_tag('br', array());
 407             return $singlestructuredesc;
 408         } else {
 409             /// description object is a primary type (string, integer)
 410             switch ($params->type) {
 411                 case PARAM_BOOL: // 0 or 1 only for now
 412                 case PARAM_INT:
 413                     $type = 'int';
 414                     break;
 415                 case PARAM_FLOAT;
 416                     $type = 'double';
 417                     break;
 418                 default:
 419                     $type = 'string';
 420             }
 421             return $type . " " . $paramdesc;
 422         }
 423     }
 424
 425     /**
 426      * Return a description object in indented xml format (for REST response)
 427      * It is indented in order to be displayed into <pre> tag
 428      * @param object $returndescription
 429      * @param string $indentation composed by space only
 430      * @return string the html to diplay
 431      */
 432     public function description_in_indented_xml_format($returndescription, $indentation = "") {
 433         $indentation = $indentation . "    ";
 434         $brakeline = <<<EOF
 435
 436
 437 EOF;
 438         /// description object is a list
 439         if ($returndescription instanceof external_multiple_structure) {
 440             $return = $indentation . "<MULTIPLE>" . $brakeline;
 441             $return .= $this->description_in_indented_xml_format($returndescription->content,
 442                             $indentation);
 443             $return .= $indentation . "</MULTIPLE>" . $brakeline;
 444             return $return;
 445         } else if ($returndescription instanceof external_single_structure) {
 446             /// description object is an object
 447             $singlestructuredesc = $indentation . "<SINGLE>" . $brakeline;
 448             $keyindentation = $indentation . "    ";
 449             foreach ($returndescription->keys as $attributname => $attribut) {
 450                 $singlestructuredesc .= $keyindentation . "<KEY name=\"" . $attributname . "\">"
 451                         . $brakeline .
 452                         $this->description_in_indented_xml_format(
 453                                 $returndescription->keys[$attributname], $keyindentation) .
 454                         $keyindentation . "</KEY>" . $brakeline;
 455             }
 456             $singlestructuredesc .= $indentation . "</SINGLE>" . $brakeline;
 457             return $singlestructuredesc;
 458         } else {
 459             /// description object is a primary type (string, integer)
 460             switch ($returndescription->type) {
 461                 case PARAM_BOOL: // 0 or 1 only for now
 462                 case PARAM_INT:
 463                     $type = 'int';
 464                     break;
 465                 case PARAM_FLOAT;
 466                     $type = 'double';
 467                     break;
 468                 default:
 469                     $type = 'string';
 470             }
 471             return $indentation . "<VALUE>" . $type . "</VALUE>" . $brakeline;
 472         }
 473     }
 474
 475     /**
 476      * Create indented XML-RPC  param description
 477      * @param object $paramdescription
 478      * @param string $indentation composed by space only
 479      * @return string the html to diplay
 480      */
 481     public function xmlrpc_param_description_html($paramdescription, $indentation = "") {
 482         $indentation = $indentation . "    ";
 483         $brakeline = <<<EOF
 484
 485
 486 EOF;
 487         /// description object is a list
 488         if ($paramdescription instanceof external_multiple_structure) {
 489             $return = $brakeline . $indentation . "Array ";
 490             $indentation = $indentation . "    ";
 491             $return .= $brakeline . $indentation . "(";
 492             $return .= $brakeline . $indentation . "[0] =>";
 493             $return .= $this->xmlrpc_param_description_html($paramdescription->content, $indentation);
 494             $return .= $brakeline . $indentation . ")";
 495             return $return;
 496         } else if ($paramdescription instanceof external_single_structure) {
 497             /// description object is an object
 498             $singlestructuredesc = $brakeline . $indentation . "Array ";
 499             $keyindentation = $indentation . "    ";
 500             $singlestructuredesc .= $brakeline . $keyindentation . "(";
 501             foreach ($paramdescription->keys as $attributname => $attribut) {
 502                 $singlestructuredesc .= $brakeline . $keyindentation . "[" . $attributname . "] =>" .
 503                         $this->xmlrpc_param_description_html(
 504                                 $paramdescription->keys[$attributname], $keyindentation) .
 505                         $keyindentation;
 506             }
 507             $singlestructuredesc .= $brakeline . $keyindentation . ")";
 508             return $singlestructuredesc;
 509         } else {
 510             /// description object is a primary type (string, integer)
 511             switch ($paramdescription->type) {
 512                 case PARAM_BOOL: // 0 or 1 only for now
 513                 case PARAM_INT:
 514                     $type = 'int';
 515                     break;
 516                 case PARAM_FLOAT;
 517                     $type = 'double';
 518                     break;
 519                 default:
 520                     $type = 'string';
 521             }
 522             return " " . $type;
 523         }
 524     }
 525
 526     /**
 527      * Return the html of a colored box with content
 528      * @param string $title - the title of the box
 529      * @param string $content - the content to displayed
 530      * @param string $rgb - the background color of the box
 531      * @return <type>
 532      */
 533     public function colored_box_with_pre_tag($title, $content, $rgb = 'FEEBE5') {
 534         //TODO: this tag removes xhtml strict error but cause warning
 535         $coloredbox = html_writer::start_tag('div', array());
 536         $coloredbox .= html_writer::start_tag('div',
 537                         array('style' => "border:solid 1px #DEDEDE;background:#" . $rgb
 538                             . ";color:#222222;padding:4px;"));
 539         $coloredbox .= html_writer::start_tag('pre', array());
 540         $coloredbox .= html_writer::start_tag('b', array());
 541         $coloredbox .= $title;
 542         $coloredbox .= html_writer::end_tag('b', array());
 543         $coloredbox .= html_writer::empty_tag('br', array());
 544         $coloredbox .= "\n" . $content . "\n";
 545         $coloredbox .= html_writer::end_tag('pre', array());
 546         $coloredbox .= html_writer::end_tag('div', array());
 547         $coloredbox .= html_writer::end_tag('div', array());
 548         return $coloredbox;
 549     }
 550
 551     /**
 552      * Return indented REST param description
 553      * @param object $paramdescription
 554      * @param string $indentation composed by space only
 555      * @return string the html to diplay
 556      */
 557     public function rest_param_description_html($paramdescription, $paramstring) {
 558         $brakeline = <<<EOF
 559
 560
 561 EOF;
 562         /// description object is a list
 563         if ($paramdescription instanceof external_multiple_structure) {
 564             $paramstring = $paramstring . '[0]';
 565             $return = $this->rest_param_description_html($paramdescription->content, $paramstring);
 566             return $return;
 567         } else if ($paramdescription instanceof external_single_structure) {
 568             /// description object is an object
 569             $singlestructuredesc = "";
 570             $initialparamstring = $paramstring;
 571             foreach ($paramdescription->keys as $attributname => $attribut) {
 572                 $paramstring = $initialparamstring . '[' . $attributname . ']';
 573                 $singlestructuredesc .= $this->rest_param_description_html(
 574                                 $paramdescription->keys[$attributname], $paramstring);
 575             }
 576             return $singlestructuredesc;
 577         } else {
 578             /// description object is a primary type (string, integer)
 579             $paramstring = $paramstring . '=';
 580             switch ($paramdescription->type) {
 581                 case PARAM_BOOL: // 0 or 1 only for now
 582                 case PARAM_INT:
 583                     $type = 'int';
 584                     break;
 585                 case PARAM_FLOAT;
 586                     $type = 'double';
 587                     break;
 588                 default:
 589                     $type = 'string';
 590             }
 591             return $paramstring . " " . $type . $brakeline;
 592         }
 593     }
 594
 595     /**
 596      * This display all the documentation
 597      * @param array $functions contains all decription objects
 598      * @param array $authparam keys contains 'tokenid'
 599      * @param boolean $printableformat true if we want to display the documentation in a printable format
 600      * @param array $activatedprotocol
 601      * @return string the html to diplay
 602      */
 603     public function documentation_html($functions, $printableformat, $activatedprotocol, $authparams) {
 604
 605         $documentationhtml = $this->output->heading(get_string('documentation', 'webservice'));
 606
 607         $br = html_writer::empty_tag('br', array());
 608         $brakeline = <<<EOF
 609
 610
 611 EOF;
 612         /// Some general information
 613         $docinfo = new stdClass();
 614         $docurl = new moodle_url('http://docs.moodle.org/en/Development:Creating_a_web_service_client');
 615         $docinfo->doclink = html_writer::tag('a',
 616                         get_string('wsclientdoc', 'webservice'), array('href' => $docurl));
 617         $documentationhtml .= html_writer::start_tag('table',
 618                         array('style' => "margin-left:auto; margin-right:auto;"));
 619         $documentationhtml .= html_writer::start_tag('tr', array());
 620         $documentationhtml .= html_writer::start_tag('td', array());
 621         $documentationhtml .= get_string('wsdocumentationintro', 'webservice', $docinfo);
 622         $documentationhtml .= $br . $br;
 623
 624
 625         /// Print button
 626         $authparams['print'] = true;
 627         //$parameters = array ('token' => $token, 'wsusername' => $username, 'wspassword' => $password, 'print' => true);
 628         $url = new moodle_url('/webservice/wsdoc.php', $authparams); // Required
 629         $documentationhtml .= $this->output->single_button($url, get_string('print', 'webservice'));
 630         $documentationhtml .= $br;
 631
 632
 633         /// each functions will be displayed into a collapsible region
 634         //(opened if printableformat = true)
 635         foreach ($functions as $functionname => $description) {
 636
 637             if (empty($printableformat)) {
 638                 $documentationhtml .= print_collapsible_region_start('',
 639                                 'aera_' . $functionname,
 640                                 html_writer::start_tag('strong', array())
 641                                 . $functionname . html_writer::end_tag('strong'),
 642                                 false,
 643                                 !$printableformat,
 644                                 true);
 645             } else {
 646                 $documentationhtml .= html_writer::tag('strong', $functionname);
 647                 $documentationhtml .= $br;
 648             }
 649
 650             /// function global description
 651             $documentationhtml .= $br;
 652             $documentationhtml .= html_writer::start_tag('div',
 653                             array('style' => 'border:solid 1px #DEDEDE;background:#E2E0E0;
 654                         color:#222222;padding:4px;'));
 655             $documentationhtml .= $description->description;
 656             $documentationhtml .= html_writer::end_tag('div');
 657             $documentationhtml .= $br . $br;
 658
 659             /// function arguments documentation
 660             $documentationhtml .= html_writer::start_tag('span', array('style' => 'color:#EA33A6'));
 661             $documentationhtml .= get_string('arguments', 'webservice');
 662             $documentationhtml .= html_writer::end_tag('span');
 663             $documentationhtml .= $br;
 664             foreach ($description->parameters_desc->keys as $paramname => $paramdesc) {
 665                 /// a argument documentation
 666                 $documentationhtml .= html_writer::start_tag('span', array('style' => 'font-size:80%'));
 667
 668                 if ($paramdesc->required == VALUE_REQUIRED) {
 669                     $required = get_string('required', 'webservice');
 670                 }
 671                 if ($paramdesc->required == VALUE_DEFAULT) {
 672                     if ($paramdesc->default === null) {
 673                         $default = "null";
 674                     } else {
 675                         $default = print_r($paramdesc->default, true);
 676                     }
 677                     $required = get_string('default', 'webservice', $default);
 678                 }
 679                 if ($paramdesc->required == VALUE_OPTIONAL) {
 680                     $required = get_string('optional', 'webservice');
 681                 }
 682
 683                 $documentationhtml .= html_writer::start_tag('b', array());
 684                 $documentationhtml .= $paramname;
 685                 $documentationhtml .= html_writer::end_tag('b');
 686                 $documentationhtml .= " (" . $required . ")"; // argument is required or optional ?
 687                 $documentationhtml .= $br;
 688                 $documentationhtml .= "&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"
 689                         . $paramdesc->desc; // argument description
 690                 $documentationhtml .= $br . $br;
 691                 ///general structure of the argument
 692                 $documentationhtml .= $this->colored_box_with_pre_tag(
 693                                 get_string('generalstructure', 'webservice'),
 694                                 $this->detailed_description_html($paramdesc),
 695                                 'FFF1BC');
 696                 ///xml-rpc structure of the argument in PHP format
 697                 if (!empty($activatedprotocol['xmlrpc'])) {
 698                     $documentationhtml .= $this->colored_box_with_pre_tag(
 699                                     get_string('phpparam', 'webservice'),
 700                                     htmlentities('[' . $paramname . '] =>'
 701                                             . $this->xmlrpc_param_description_html($paramdesc)),
 702                                     'DFEEE7');
 703                 }
 704                 ///POST format for the REST protocol for the argument
 705                 if (!empty($activatedprotocol['rest'])) {
 706                     $documentationhtml .= $this->colored_box_with_pre_tag(
 707                                     get_string('restparam', 'webservice'),
 708                                     htmlentities($this->rest_param_description_html(
 709                                                     $paramdesc, $paramname)),
 710                                     'FEEBE5');
 711                 }
 712                 $documentationhtml .= html_writer::end_tag('span');
 713             }
 714             $documentationhtml .= $br . $br;
 715
 716
 717             /// function response documentation
 718             $documentationhtml .= html_writer::start_tag('span', array('style' => 'color:#EA33A6'));
 719             $documentationhtml .= get_string('response', 'webservice');
 720             $documentationhtml .= html_writer::end_tag('span');
 721             $documentationhtml .= $br;
 722             /// function response description
 723             $documentationhtml .= html_writer::start_tag('span', array('style' => 'font-size:80%'));
 724             if (!empty($description->returns_desc->desc)) {
 725                 $documentationhtml .= $description->returns_desc->desc;
 726                 $documentationhtml .= $br . $br;
 727             }
 728             if (!empty($description->returns_desc)) {
 729                 ///general structure of the response
 730                 $documentationhtml .= $this->colored_box_with_pre_tag(
 731                                 get_string('generalstructure', 'webservice'),
 732                                 $this->detailed_description_html($description->returns_desc),
 733                                 'FFF1BC');
 734                 ///xml-rpc structure of the response in PHP format
 735                 if (!empty($activatedprotocol['xmlrpc'])) {
 736                     $documentationhtml .= $this->colored_box_with_pre_tag(
 737                                     get_string('phpresponse', 'webservice'),
 738                                     htmlentities($this->xmlrpc_param_description_html(
 739                                                     $description->returns_desc)),
 740                                     'DFEEE7');
 741                 }
 742                 ///XML response for the REST protocol
 743                 if (!empty($activatedprotocol['rest'])) {
 744                     $restresponse = "<?xml version=\"1.0\" encoding=\"UTF-8\" ?>"
 745                             . $brakeline . "<RESPONSE>" . $brakeline;
 746                     $restresponse .= $this->description_in_indented_xml_format(
 747                                     $description->returns_desc);
 748                     $restresponse .="</RESPONSE>" . $brakeline;
 749                     $documentationhtml .= $this->colored_box_with_pre_tag(
 750                                     get_string('restcode', 'webservice'),
 751                                     htmlentities($restresponse),
 752                                     'FEEBE5');
 753                 }
 754             }
 755             $documentationhtml .= html_writer::end_tag('span');
 756             $documentationhtml .= $br . $br;
 757
 758             /// function errors documentation for REST protocol
 759             if (!empty($activatedprotocol['rest'])) {
 760                 $documentationhtml .= html_writer::start_tag('span', array('style' => 'color:#EA33A6'));
 761                 $documentationhtml .= get_string('errorcodes', 'webservice');
 762                 $documentationhtml .= html_writer::end_tag('span');
 763                 $documentationhtml .= $br . $br;
 764                 $documentationhtml .= html_writer::start_tag('span', array('style' => 'font-size:80%'));
 765                 $errormessage = get_string('invalidparameter', 'debug');
 766                 $restexceptiontext = <<<EOF
 767 <?xml version="1.0" encoding="UTF-8"?>
 768 <EXCEPTION class="invalid_parameter_exception">
 769     <MESSAGE>{$errormessage}</MESSAGE>
 770     <DEBUGINFO></DEBUGINFO>
 771 </EXCEPTION>
 772 EOF;
 773                 $documentationhtml .= $this->colored_box_with_pre_tag(
 774                                 get_string('restexception', 'webservice'),
 775                                 htmlentities($restexceptiontext),
 776                                 'FEEBE5');
 777
 778                 $documentationhtml .= html_writer::end_tag('span');
 779             }
 780             $documentationhtml .= $br . $br;
 781             if (empty($printableformat)) {
 782                 $documentationhtml .= print_collapsible_region_end(true);
 783             }
 784         }
 785
 786         /// close the table and return the documentation
 787         $documentationhtml .= html_writer::end_tag('td');
 788         $documentationhtml .= html_writer::end_tag('tr');
 789         $documentationhtml .= html_writer::end_tag('table');
 790
 791         return $documentationhtml;
 792     }
 793
 794 }