From: jerome mouneyrac <jerome@moodle.com>
Date: Mon, 14 Dec 2009 05:30:12 +0000 (+0000)
Subject: webservice MDL-20803 fix xml-rpc documentation, now show the real sent PHP structure... 
X-Git-Url: http://git.mjollnir.org/gw?a=commitdiff_plain;h=360e9415b43e56696d97ee59477f2038155efb19;p=moodle.git

webservice MDL-20803 fix xml-rpc documentation, now show the real sent PHP structure + response. REST POST parameters coming soon...
---

diff --git a/lang/en_utf8/webservice.php b/lang/en_utf8/webservice.php
index ac90f51e2b..d2c5d31b1e 100644
--- a/lang/en_utf8/webservice.php
+++ b/lang/en_utf8/webservice.php
@@ -30,6 +30,9 @@ $string['manageprotocols'] = 'Manage protocols';
 $string['noerrorcode'] = 'No error code';
 $string['norequiredcapability'] = 'No required capability';
 $string['optional'] = 'Optional';
+$string['phpparam'] = 'XML-RPC (PHP structure)';
+$string['phpresponse'] = 'XML-RPC (PHP structure)';
+$string['postrestparam'] = 'PHP code for REST (POST request)';
 $string['potusers'] = 'Not authorised users';
 $string['potusersmatching'] = 'Not authorised users matching';
 $string['protocol'] = 'Protocol';
@@ -39,7 +42,7 @@ $string['requireauthentication'] = 'This method requires authentication with xxx
 $string['required'] = 'Required';
 $string['requiredcapability'] = 'Required capability';
 $string['response'] = 'Response';
-$string['restcode'] = 'REST code';
+$string['restcode'] = 'REST';
 $string['restrictedusers'] = 'Authorised users only';
 $string['selectedcapabilitydoesntexit'] = 'The currently set required capability ($a) doesn\'t exist anymore. Please change it and save the changes.';
 $string['selectedcapability'] = 'Selected';
@@ -53,8 +56,9 @@ $string['testclient'] = 'Web service test client';
 $string['validuntil'] = 'Valid until';
 $string['webservices'] = 'Web services';
 $string['wsdocumentation'] = 'Web service documentation';
-$string['wsdocumentationintro'] = 'Following a listing of web service functions available for the username <b>$a</b>.<br/>In order to create a client we advice you to read the <a href=\"http://docs.moodle.org/en/Development:Creating_a_web_service_and_a_web_service_function#Create_your_own_client\">Moodle documentation</a>';
+$string['wsdocumentationintro'] = 'Following a listing of web service functions available for the username <b>$a</b>.<br/>In order to create a client we advice you to read the <a href=\"http://docs.moodle.org/en/Development:Creating_a_web_service_and_a_web_service_function#Create_your_own_client\">Moodle documentation</a>
+    <br/><br/>For REST parameters convert the XML-RPC structures into POST.';
 $string['wsdocumentationlogin'] = 'Enter your web service username and password.';
 $string['wspassword'] = 'Web service password';
 $string['wsusername'] = 'Web service username';
-$string['xmlrpcstructure'] = 'XML-RPC structure';
+$string['xmlrpcstructure'] = 'documentation';
diff --git a/webservice/wsdoc.php b/webservice/wsdoc.php
index 519afa2391..f16e3aa2b2 100644
--- a/webservice/wsdoc.php
+++ b/webservice/wsdoc.php
@@ -67,7 +67,7 @@ class webservice_documentation_generator {
         // init all properties from the request data
         $this->get_authentication_parameters();
 
-        // this sets up $USER TODO: and $SESSION for the environment.php
+        // this sets up $USER
         try {
             $this->authenticate_user();
         } catch(moodle_exception $e) {
diff --git a/webservice/wsdocrenderer.php b/webservice/wsdocrenderer.php
index 192637d15b..399e005dad 100644
--- a/webservice/wsdocrenderer.php
+++ b/webservice/wsdocrenderer.php
@@ -34,19 +34,19 @@ class moodle_core_wsdoc_renderer extends moodle_renderer_base {
      * @param object $params a part of parameter/return description
      * @return string the html to display
      */
-    public function detailed_html_description($params) {
+    public function detailed_description_html($params) {
         $paramdesc = "";
         if (!empty($params->desc)) {
             $paramdesc = "<span style=\"color:#2A33A6\"><i>//".$params->desc."</i></span><br/>";
         }
         if ($params instanceof external_multiple_structure) {
 
-            return $paramdesc."list of ( <br/>". $this->detailed_html_description($params->content).")";
+            return $paramdesc."list of ( <br/>". $this->detailed_description_html($params->content).")";
         } else if ($params instanceof external_single_structure) {
             //var_dump($params->keys);
             $singlestructuredesc = $paramdesc."object {<br/>";
             foreach ($params->keys as $attributname => $attribut) {
-                $singlestructuredesc .= "<b>".$attributname."</b> ".$this->detailed_html_description($params->keys[$attributname]);
+                $singlestructuredesc .= "<b>".$attributname."</b> ".$this->detailed_description_html($params->keys[$attributname]);
             }
             $singlestructuredesc .= "} <br/>";
             return $singlestructuredesc;
@@ -112,6 +112,53 @@ EOF;
         }
     }
 
+     /**
+     * Create indented XML-RPC  param description
+     * @param object $paramdescription
+     * @param string $indentation composed by space only
+     * @return string the html to diplay
+     */
+    public function xmlrpc_param_description_html($paramdescription, $indentation = "") {
+        $indentation = $indentation . "    ";
+        $brakeline = <<<EOF
+
+
+EOF;
+        if ($paramdescription instanceof external_multiple_structure) {
+            $return  = $brakeline.$indentation."Array ";
+            $indentation = $indentation . "    ";
+            $return .= $brakeline.$indentation."(";
+            $return .= $brakeline.$indentation."[0] =>";
+            $return .= $this->xmlrpc_param_description_html($paramdescription->content, $indentation);
+            $return .= $brakeline.$indentation.")";
+            return $return;
+        } else if ($paramdescription instanceof external_single_structure) {
+            $singlestructuredesc = $brakeline.$indentation."Array ";
+            $keyindentation = $indentation."    ";
+            $singlestructuredesc  .= $brakeline.$keyindentation."(";
+            foreach ($paramdescription->keys as $attributname => $attribut) {
+                $singlestructuredesc .= $brakeline.$keyindentation."[".$attributname."] =>".
+                        $this->xmlrpc_param_description_html($paramdescription->keys[$attributname], $keyindentation).
+                        $keyindentation;
+            }
+            $singlestructuredesc .= $brakeline.$keyindentation.")";
+            return $singlestructuredesc;
+        } else {
+            switch($paramdescription->type) {
+                case PARAM_BOOL: // 0 or 1 only for now
+                case PARAM_INT:
+                    $type = 'int';
+                    break;
+                case PARAM_FLOAT;
+                    $type = 'double';
+                    break;
+                default:
+                    $type = 'string';
+            }
+            return " ".$type;
+        }
+    }
+
     /**
      * Return the REST response (xml code display in <pre> tag)
      * @param string $functionname
@@ -119,12 +166,16 @@ EOF;
      * @return string the html to diplay
      */
     public function rest_response_html($functionname, $returndescription) {
+        $brakeline = <<<EOF
+
+
+EOF;
 
         $restresponsehtml = "";
 
         $restresponsehtml .= "<pre>";
         $restresponsehtml .= "<div style=\"border:solid 1px #DEDEDE;background:#FEEBE5;color:#222222;padding:4px;\">";
-        $restresponsehtml .= '<b>REST code</b><br/>';
+        $restresponsehtml .= '<b>'.get_string('restcode', 'webservice').'</b><br/>';
         $brakeline = <<<EOF
 
 
@@ -132,7 +183,7 @@ EOF;
         $content  = "<?xml version=\"1.0\" encoding=\"UTF-8\" ?>".$brakeline."<RESPONSE>".$brakeline;
         $content .= $this->description_in_indented_xml_format($returndescription);
         $content .="</RESPONSE>".$brakeline;
-        $restresponsehtml .= htmlentities($content);
+        $restresponsehtml .= $brakeline.htmlentities($content).$brakeline;
         $restresponsehtml .= "</div>";
         $restresponsehtml .= "</pre>";
         return $restresponsehtml;
@@ -146,6 +197,11 @@ EOF;
      */
     public function documentation_html($functions, $username) {
 
+        $brakeline = <<<EOF
+
+
+EOF;
+
         $documentationhtml = "";
 
         $documentationhtml .= "<table style=\"margin-left:auto; margin-right:auto;\"><tr><td>";
@@ -177,14 +233,14 @@ EOF;
                 $documentationhtml .= "<pre>";
                 $documentationhtml .= print_collapsible_region_start('', 'aera_'.$functionname."_".$paramname,'<b>'.get_string('xmlrpcstructure', 'webservice').'</b>',false,true,true);
                 //echo '<b>'.get_string('xmlrpcstructure', 'webservice').'</b><br/>';
-                $documentationhtml .= $this->detailed_html_description($paramdesc);
+                $documentationhtml .= $brakeline.$this->detailed_description_html($paramdesc);
                 $documentationhtml .= print_collapsible_region_end(true);
                 $documentationhtml .= "</pre>";
                 $documentationhtml .= "</div><br/>";
                 $documentationhtml .= "<pre>";
-                $documentationhtml .= "<div style=\"border:solid 1px #DEDEDE;background:#FEEBE5;color:#222222;padding:4px;\">";
-                $documentationhtml .= '<b>'.get_string('restcode', 'webservice').'</b><br/>';
-                $documentationhtml .= htmlentities($this->description_in_indented_xml_format($paramdesc));
+                $documentationhtml .= "<div style=\"border:solid 1px #DEDEDE;background:#DFEEE7;color:#222222;padding:4px;\">";
+                $documentationhtml .= '<b>'.get_string('phpparam', 'webservice').'</b><br/>';
+                $documentationhtml .= $brakeline.'['.$paramname.'] =>'.htmlentities($this->xmlrpc_param_description_html($paramdesc)). $brakeline. $brakeline;
                 $documentationhtml .= "</div>";
                 $documentationhtml .= "</pre>";
                 $documentationhtml .= "</span>";
@@ -202,11 +258,17 @@ EOF;
                 $documentationhtml .= "<pre>";
                 $documentationhtml .= print_collapsible_region_start('', 'aera_'.$functionname."_xmlrpc_return",'<b>'.get_string('xmlrpcstructure', 'webservice').'</b>',false,true,true);
                 //echo '<b>'.get_string('xmlrpcstructure', 'webservice').'</b><br/>';
-                $documentationhtml .= $this->detailed_html_description($description->returns_desc);
+                $documentationhtml .= $brakeline.$this->detailed_description_html($description->returns_desc);
                 $documentationhtml .= print_collapsible_region_end(true);
                 $documentationhtml .= "</pre>";
                 $documentationhtml .= "</div><br/>";
-                $documentationhtml .=$this->rest_response_html($functionname, $description->returns_desc);
+                $documentationhtml .= "<pre>";
+                $documentationhtml .= "<div style=\"border:solid 1px #DEDEDE;background:#DFEEE7;color:#222222;padding:4px;\">";
+                $documentationhtml .= '<b>'.get_string('phpresponse', 'webservice').'</b><br/>';
+                $documentationhtml .= htmlentities($this->xmlrpc_param_description_html($description->returns_desc)).$brakeline.$brakeline;
+                $documentationhtml .= "</div>";
+                $documentationhtml .= "</pre><br/>";
+                $documentationhtml .= $this->rest_response_html($functionname, $description->returns_desc);
             }
             $documentationhtml .= "</span>";
             $documentationhtml .= "<br/><br/>";
@@ -250,7 +312,7 @@ EOF;
 //        echo get_string('error','webservice',$errormessage);
 //        echo "<br/><br/>";
 
-        //login form - we cannot use moodle form are we don't have sessionkey
+        //login form - we cannot use moodle form as we don't have sessionkey
         $form = new html_form();
         $form->url = new moodle_url($CFG->wwwroot.'/webservice/wsdoc.php', array()); // Required
         $form->button = new html_button();