From 886e3bfbd543ac504c7c9f93705f582be8952e65 Mon Sep 17 00:00:00 2001
From: jerome mouneyrac <jerome@moodle.com>
Date: Mon, 14 Dec 2009 06:01:13 +0000
Subject: [PATCH] webservice MDL-20803 added REST POST parameters documentation

---
 lang/en_utf8/webservice.php  |  4 +--
 webservice/wsdocrenderer.php | 47 ++++++++++++++++++++++++++++++++++++
 2 files changed, 49 insertions(+), 2 deletions(-)

diff --git a/lang/en_utf8/webservice.php b/lang/en_utf8/webservice.php
index d2c5d31b1e..317ffcebc2 100644
--- a/lang/en_utf8/webservice.php
+++ b/lang/en_utf8/webservice.php
@@ -43,6 +43,7 @@ $string['required'] = 'Required';
 $string['requiredcapability'] = 'Required capability';
 $string['response'] = 'Response';
 $string['restcode'] = 'REST';
+$string['restparam'] = 'REST (POST parameters)';
 $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';
@@ -56,8 +57,7 @@ $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>
-    <br/><br/>For REST parameters convert the XML-RPC structures into POST.';
+$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['wsdocumentationlogin'] = 'Enter your web service username and password.';
 $string['wspassword'] = 'Web service password';
 $string['wsusername'] = 'Web service username';
diff --git a/webservice/wsdocrenderer.php b/webservice/wsdocrenderer.php
index 399e005dad..1f56a68089 100644
--- a/webservice/wsdocrenderer.php
+++ b/webservice/wsdocrenderer.php
@@ -189,6 +189,47 @@ EOF;
         return $restresponsehtml;
     }
 
+
+     /**
+     * Create indented REST param description
+     * @param object $paramdescription
+     * @param string $indentation composed by space only
+     * @return string the html to diplay
+     */
+    public function rest_param_description_html($paramdescription, $paramstring) {
+        $brakeline = <<<EOF
+
+
+EOF;
+        if ($paramdescription instanceof external_multiple_structure) {
+            $paramstring = $paramstring.'[0]';
+            $return = $this->rest_param_description_html($paramdescription->content, $paramstring);
+            return $return;
+        } else if ($paramdescription instanceof external_single_structure) {
+            $singlestructuredesc = "";
+            foreach ($paramdescription->keys as $attributname => $attribut) {
+                $paramstring = $paramstring.'['.$attributname.']';
+                $singlestructuredesc .= $this->rest_param_description_html($paramdescription->keys[$attributname], $paramstring);
+            }
+            return $singlestructuredesc;
+        } else {
+            $paramstring = $paramstring.'=';
+            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 $paramstring." ".$type.$brakeline;
+        }
+    }
+
+
     /**
      * This display all the documentation
      * @param array $functions contains all decription objects
@@ -241,6 +282,12 @@ EOF;
                 $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><br/>";
+                $documentationhtml .= "</pre>";
+                 $documentationhtml .= "<pre>";
+                $documentationhtml .= "<div style=\"border:solid 1px #DEDEDE;background:#FEEBE5;color:#222222;padding:4px;\">";
+                $documentationhtml .= '<b>'.get_string('restparam', 'webservice').'</b><br/>';
+                $documentationhtml .= $brakeline.htmlentities($this->rest_param_description_html($paramdesc,$paramname)). $brakeline. $brakeline;
                 $documentationhtml .= "</div>";
                 $documentationhtml .= "</pre>";
                 $documentationhtml .= "</span>";
-- 
2.39.5