MDL-26198 make user_has_role_assignment() check parent contexts too
[moodle.git] / webservice / renderer.php
1 <?php
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 ///////////////////////////////////////////////////////////////////////////
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 {
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'));
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;
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'));
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';
78         $cells = array($authoriseduserscell, $buttonscell, $otheruserscell);
79         $row = new html_table_row($cells);
80         $table->data[] = $row;
81         $formcontent .= html_writer::table($table);
83         $formcontent = html_writer::tag('div', $formcontent);
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     }
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     }
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     }
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     }
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     }
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';
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             }
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             }
228             $html = html_writer::table($table);
229         } else {
230             $html = get_string('nofunctions', 'webservice') . html_writer::empty_tag('br');
231         }
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         }
240         return $html;
241     }
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     }
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;
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');
282         $return = $this->output->heading(get_string('securitykeys', 'webservice'), 3, 'main', true);
283         $return .= $this->output->box_start('generalbox webservicestokenui');
285         $return .= get_string('keyshelp', 'webservice');
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();
293         if ($documentation) {
294             $table->head[] = get_string('doc', 'webservice');
295             $table->align[] = 'center';
296         }
298         if (!empty($tokens)) {
299             foreach ($tokens as $token) {
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                 }
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');
318                 $validuntil = '';
319                 if (!empty($token->validuntil)) {
320                     $validuntil = date("F j, Y"); //TODO: language support (look for moodle function)
321                 }
323                 $row = array($token->token, $token->name, $validuntil, $creatoratag, $reset);
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                 }
332                 $table->data[] = $row;
333             }
334             $return .= html_writer::table($table);
335         } else {
336             $return .= get_string('notoken', 'webservice');
337         }
339         $return .= $this->output->box_end();
340         return $return;
341     }
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 .= "//";
383             $paramdesc .= $params->desc;
385             $paramdesc .= html_writer::end_tag('i');
387             $paramdesc .= html_writer::end_tag('span');
388             $paramdesc .= html_writer::empty_tag('br', array());
389         }
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     }
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
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     }
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
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     }
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     }
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
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     }
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) {
605         $documentationhtml = $this->output->heading(get_string('documentation', 'webservice'));
607         $br = html_writer::empty_tag('br', array());
608         $brakeline = <<<EOF
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;
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;
633         /// each functions will be displayed into a collapsible region
634         //(opened if printableformat = true)
635         foreach ($functions as $functionname => $description) {
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             }
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;
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%'));
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                 }
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;
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;
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');
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         }
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');
791         return $documentationhtml;
792     }