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