source: trunk/tools/ws.htm @ 20741

Last change on this file since 20741 was 20192, checked in by mistic100, 12 years ago

update triggers_list, use DataTables and same design as Webservices explorer
  • Property svn:eol-style set to LF
File size: 19.1 KB
Line 
1<!DOCTYPE html>
2<html xmlns="http://www.w3.org/1999/xhtml" lang="en" dir="ltr">
3<head>
4  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
5  <title>Piwigo web API (web-services) explorer</title>
6 
7  <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
8 
9  <style type="text/css">
10  /* BEGIN CSS RESET
11    http://meyerweb.com/eric/tools/css/reset
12    v2.0 | 20110126 | License: none (public domain) */
13  html, body, div, span, applet, object, iframe, h1, h2, h3, h4, h5, h6, p, blockquote, pre, a, abbr, acronym, address, big, cite, code,
14  del, dfn, em, img, ins, kbd, q, s, samp, small, strike, strong, sub, sup, tt, var, b, u, i, center, dl, dt, dd, ol, ul, li,
15  fieldset, form, label, legend, table, caption, tbody, tfoot, thead, tr, th, td, article, aside, canvas, details, embed, 
16  figure, figcaption, footer, header, hgroup, menu, nav, output, ruby, section, summary, time, mark, audio, video
17  {margin:0;padding:0;border:0;font-size:100%;vertical-align:baseline;}
18
19  article, aside, details, figcaption, figure, footer, header, hgroup, menu, nav, section {display:block;}
20  body {line-height:1.1;}
21  blockquote, q {quotes:none;}
22  blockquote:before, blockquote:after, q:before, q:after {content:'';content:none;}
23  table {border-collapse:collapse;border-spacing:0;}
24  /* END CSS RESET */
25
26  html {font-family:"Corbel","Lucida Grande","Verdana",sans-serif;color:#222;font-size:13px;}
27
28  a {color:#247EBF;text-decoration:none;}
29  a:hover {color:#EB9C39;border-bottom-width:1px;border-style:dotted;
30    text-shadow:1px 1px 0 #ddd;-moz-text-shadow:1px 1px 0 #ddd;-webkit-text-shadow:1px 1px 0 #ddd;
31  }
32  blockquote {border:1px solid #cdcdcd;background:#F9F9F9;padding:8px;}
33  hr {margin:10px 30px;color:#fff;}
34  ul {margin-left:25px;}
35  p {margin:8px 0;}
36
37  h1 {color:#fff;font-size:26px;padding:10px 15px;
38    text-shadow:1px 1px 0 #999;-moz-text-shadow:1px 1px 0 #999;-webkit-text-shadow:1px 1px 0 #999;
39    background:#45484d;background:-moz-linear-gradient(top, #45484d 0%, #333333 100%);background:-webkit-gradient(linear, left top, left bottom, color-stop(0%,#45484d), color-stop(100%,#333333));background:-webkit-linear-gradient(top, #45484d 0%,#333333 100%);background:-o-linear-gradient(top, #45484d 0%,#333333 100%);background:-ms-linear-gradient(top, #45484d 0%,#333333 100%);background:linear-gradient(to bottom, #45484d 0%,#333333 100%);filter:progid:DXImageTransform.Microsoft.gradient( startColorstr='#45484d', endColorstr='#333333',GradientType=0 );
40  }
41  h2 {color:#fff;font-size:20px;padding:5px 10px;
42    text-shadow:1px 1px 0 #555;-moz-text-shadow:1px 1px 0 #555;-webkit-text-shadow:1px 1px 0 #555;
43    background:#f2a841;background:-moz-linear-gradient(top, #f2a841 0%, #ef6b13 100%);background:-webkit-gradient(linear, left top, left bottom, color-stop(0%,#f2a841), color-stop(100%,#ef6b13));background:-webkit-linear-gradient(top, #f2a841 0%,#ef6b13 100%);background:-o-linear-gradient(top, #f2a841 0%,#ef6b13 100%);background:-ms-linear-gradient(top, #f2a841 0%,#ef6b13 100%);background:linear-gradient(to bottom, #f2a841 0%,#ef6b13 100%);filter:progid:DXImageTransform.Microsoft.gradient( startColorstr='#f2a841', endColorstr='#ef6b13',GradientType=0 );
44  }
45  h2#errorWrapper {color:#F42C00;font-weight:normal;
46    background:#eaeaea;background:-moz-linear-gradient(top, #eaeaea 0%, #afafaf 100%);background:-webkit-gradient(linear, lefttop, leftbottom, color-stop(0%,#eaeaea), color-stop(100%,#afafaf));background:-webkit-linear-gradient(top, #eaeaea 0%, #afafaf 100%);background:-o-linear-gradient(top, #eaeaea 0%, #afafaf 100%);background:-ms-linear-gradient(top, #eaeaea 0%, #afafaf 100%);background:linear-gradient(tobottom, #eaeaea 0%, #afafaf 100%);filter:progid:DXImageTransform.Microsoft.gradient(startColorstr='#eaeaea', endColorstr='#afafaf', GradientType=0);
47  }
48  h3 {display:inline-block;padding:5px 10px;color:#555;font-weight:bold;text-align:center;
49    border-radius:8px 8px 0 0;-moz-border-radius:8px 8px 0 0;-webkit-border-radius:8px 8px 0 0;
50    text-shadow:1px 1px 0 #bbb;-moz-text-shadow:1px 1px 0 #bbb;-webkit-text-shadow:1px 1px 0 #bbb;
51    background:#f2f2f2;background:-moz-linear-gradient(top, #f2f2f2 0%, #cecece 100%);background:-webkit-gradient(linear, left top, left bottom, color-stop(0%,#f2f2f2), color-stop(100%,#cecece));background:-webkit-linear-gradient(top, #f2f2f2 0%,#cecece 100%);background:-o-linear-gradient(top, #f2f2f2 0%,#cecece 100%);background:-ms-linear-gradient(top, #f2f2f2 0%,#cecece 100%);background:linear-gradient(to bottom, #f2f2f2 0%,#cecece 100%);filter:progid:DXImageTransform.Microsoft.gradient( startColorstr='#f2f2f2', endColorstr='#cecece',GradientType=0 );
52  }
53
54  #the_header {border-bottom:1px solid #cdcdcd;margin-bottom:1px;}
55  #the_footer {background:#EAEAEA;border-top:1px solid #cdcdcd;padding:10px;clear:both;}
56
57  #the_methods {width:250px;float:left;border-style:solid;border-color:#cdcdcd;border-width:1px 1px 0 0;
58    background-image:url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAMAAAADCAIAAADZSiLoAAAAH0lEQVQImSXHMQEAMAwCMOrfK0jIjuVL2gLBzyHJtgd7wBdU3Vt/7AAAAABJRU5ErkJggg==);
59  }
60  #the_methods ul {font-size:1.1em;margin:5px 0 10px 10px;list-style:none;}
61  #the_methods li:before {content:"\203A\00A0";font-weight:bold;color:#EB9C39;font-size:1.1em;}
62  #the_methods li:hover:before {content:"\00A0\203A";}
63
64  #the_page {margin-left:252px;border-style:solid;border-color:#cdcdcd;border-width:1px 0 0 1px;}
65  #the_content {padding:10px;}
66
67  #methodParams {display:inline-block;}
68  #methodParams thead td {background:#DEE3E9;font-weight:bold;padding:2px 5px;}
69  #methodParams td {padding:2px;border:1px solid #cdcdcd;vertical-align:middle;}
70  #methodParams tbody tr:nth-child(even) {background:#f7f7f7;}
71  #methodParams tbody tr td:first-child {font-family:monospace;font-size:0.95em;}
72  #methodParams td.mini {width:0px;text-align:center;}
73  #methodParams tfoot {font-size:0.95em;}
74  #methodParams td.input {text-align:center;}
75  #methodParams td.input input[type="text"] {width:97%;font-size:0.9em;background:#f7f7f7;border:1px solid #ccc;
76    border-radius:2px;-moz-border-radius:2px;-webkit-border-radius:2px;
77  }
78  #methodParams td.input input[type="text"]:hover, #methodParams td.input input[type="text"]:focus {border-color:#C7E2F1;border-top-color:#96BCD7;background:#fff;}
79
80  #testForm {display:inline-block;margin-left:15px;}
81  #testForm td {padding:2px 0;}
82  #testForm tr:last-child td {padding:8px 0 5px 0;}
83  #testForm blockquote {width:200px;}
84 
85  #introMessage {font-size:1.1em;}
86  #urlForm {margin-bottom:10px;}
87
88  a.button {color:#fff;padding:3px 8px;border:1px solid #91bb5c;font-size:0.9em;margin-right:3px;display:inline-block;
89    border-radius:5px;-moz-border-radius:5px;-webkit-border-radius:5px;
90    text-shadow:1px 1px 0 #666;-moz-text-shadow:1px 1px 0 #666;-webkit-text-shadow:1px 1px 0 #666;
91    background:#84bb3c;background:-moz-linear-gradient(top, #84bb3c 0%, #3f5a1d 100%);background:-webkit-gradient(linear, lefttop, leftbottom, color-stop(0%,#84bb3c), color-stop(100%,#3f5a1d));background:-webkit-linear-gradient(top, #84bb3c 0%, #3f5a1d 100%);background:-o-linear-gradient(top, #84bb3c 0%, #3f5a1d 100%);background:-ms-linear-gradient(top, #84bb3c 0%, #3f5a1d 100%);background:linear-gradient(tobottom, #84bb3c 0%, #3f5a1d 100%);filter:progid:DXImageTransform.Microsoft.gradient(startColorstr='#84bb3c', endColorstr='#3f5a1d', GradientType=0);
92  }
93  a.button:hover {color:#E5FF00;}
94 
95  #iframeWrapper {width:100%;height:300px;padding:3px 3px 20px 3px;background:#F9F9F9;border:1px solid #cdcdcd;overflow:hidden;position:relative;}
96  iframe {width:100%;height:100%;background:#fff;}
97  </style>
98 
99</head>
100
101<body>
102
103<div id="the_header">
104  <h1>Piwigo web API (web-services) explorer</h1>
105</div> <!-- the_header -->
106
107<div id="the_methods">
108  <h2>Available methods</h2>
109 
110  <ul id="methodsList">
111  </ul>
112</div> <!-- the_methods -->
113
114<div id="the_page">
115  <h2 id="methodName" style="display:none;"></h2>
116  <h2 id="errorWrapper" style="display:none;"></h2>
117 
118  <div id="the_content">
119    <form id="urlForm" style="display:none;">
120      <input type="text" name="ws_url" size="60">
121      <input type="submit" value="Go!">
122    </form>
123   
124    <blockquote id="introMessage">
125      <p>
126        <b>API = Application Programming Interface.</b><br>
127        This is the way other applications can communicate with Piwigo. This feature is also know as Web Services.
128      </p>
129
130      <p>Examples:</p>
131      <ul>
132        <li>Wordpress (web blog software) can display random photos from a Piwigo gallery in its sidebar</li>
133        <li>Lightroom (photo management software for desktop) can create albums and upload photos to Piwigo</li>
134      </ul>
135
136      <p>
137        This page lists all API methods available on your Piwigo installation, part of the Piwigo core or added by third-party plugins.
138        For each method you can consult required and optional parameters, and even test them in direct live!
139      </p>
140
141      <p>
142        For more information you can consult our Wiki <a href="http://piwigo.org/doc/doku.php?id=dev:webapi:start" target="_blank">Piwigo Web API</a> and <a href="http://piwigo.org/forum" target="_blank">our forums</a>.
143      </p>
144    </blockquote> <!-- introMessage -->
145
146
147    <form id="methodWrapper" style="display:none;">
148      <div id="methodDescription" style="display:none;">
149        <h3>Description</h3>
150        <blockquote>
151        </blockquote>
152        <br>
153      </div> <!-- methodDescription -->
154     
155      <div id="methodParams">
156        <h3>Method parameters</h3>
157        <table>
158          <thead>
159            <tr>
160              <td style="width:150px;">Name</td>
161              <td class="mini">Extra</td>
162              <td style="width:300px;">Value</td>
163              <td class="mini">Send</td>
164            </tr>
165          </thead>
166         
167          <tbody>
168          </tbody>
169         
170          <tfoot>
171            <tr>
172              <td colspan="4"><b>*</b>: required parameter, <b>?</b>: optional parameter, <b>[]</b>: parameter can be an array (use a pipe | to split values)</td>
173            </tr>
174          </tfoot>
175        </table>
176      </div> <!-- methodParams -->
177     
178      <div id="testForm">
179        <h3>Test</h3>
180        <blockquote>
181          <table>
182            <tr>
183              <td>Request format :</td>
184              <td>
185                <select id="requestFormat">
186                  <option value="get" selected="selected">GET</option>
187                  <option value="post">POST</option>
188                </select>
189              </td>
190            </tr>
191            <tr>
192              <td>Response format :</td>
193              <td>
194                <select id="responseFormat">
195                  <option value="rest" selected="selected">REST (xml)</option>
196                  <option value="json">JSON</option>
197                  <option value="php">PHP serial</option>
198                  <option value="xmlrpc">XML RPC</option>
199                </select>
200              </td>
201            </tr>
202            <tr>
203              <td colspan="2">
204                <a href="#" class="button" id="invokeMethod">INVOKE</a>
205                <a href="#" class="button" id="invokeMethodBlank">INVOKE (new window)</a>
206              </td>
207            </tr>
208          </table>
209        </blockquote>
210      </div> <!-- testForm -->
211     
212      <br><br>
213     
214      <h3>Result</h3>
215      <div id="iframeWrapper">
216        <iframe src="" id="invokeFrame" name="invokeFrame"></iframe>
217        <a href="#bottom" id="increaseIframe"><b>&darr;</b> increase height</a> &#8226; <a href="#bottom" id="decreaseIframe"><b>&uarr;</b> decrease height</a>
218        <a name="bottom"></a>
219      </div>
220    </form> <!-- iframeWrapper -->
221   
222    <!-- hidden form for POST submition -->
223    <form method="post" action="" target="" id="invokeForm" style="display:none;"></form>
224   
225  </div> <!-- the_content -->
226
227</div> <!-- the_page -->
228
229<div id="the_footer">
230  Copyright &copy; 2002-2013 <a href="http://piwigo.org">Piwigo Team</a>
231</div> <!-- the_footer -->
232
233
234<script type="text/javascript"> 
235// global vars
236var cachedMethods = new Array;
237var ws_url = "http://";
238
239// automatic detection of ws_url
240match = document.location.toString().match(/^(https?.*\/)tools\/ws\.html?/);
241if (match==null) {
242  askForUrl();
243}
244else {
245  ws_url = match[1]+'ws.php';
246  getMethodList();
247}
248
249// manual set of ws_url
250$("#urlForm").submit(function() {
251  ws_url = $(this).children("input[name='ws_url']").val();
252  getMethodList();
253  return false;
254});
255
256// invoke buttons
257$("#invokeMethod").click(function() {
258  invokeMethod($("#methodName").html(), false);
259  return false;
260});
261$("#invokeMethodBlank").click(function() {
262  invokeMethod($("#methodName").html(), true);
263  return false;
264});
265
266// resizable iframe
267$("#increaseIframe").click(function() {
268  $("#iframeWrapper").css('height', $("#iframeWrapper").height()+100);
269  adaptHeight();
270});
271$("#decreaseIframe").click(function() {
272  if ($("#iframeWrapper").height() > 200) {
273    $("#iframeWrapper").css('height', $("#iframeWrapper").height()-100);
274    adaptHeight();
275  }
276});
277
278// mask all wrappers
279function resetDisplay() {
280  $("#errorWrapper").hide();
281  $("#methodWrapper").hide();
282  $("#methodName").hide();
283  $("#urlForm").hide();
284  $("#methodDescription").hide();
285  $("#invokeFrame").attr('src','');
286}
287
288// give the same size to methods list and main page
289function adaptHeight()
290{
291  $("#the_page").css('height', 'auto');
292  $("#the_methods").css('height', 'auto');
293 
294  min_h = $(window).height()-$("#the_header").outerHeight()-$("#the_footer").outerHeight()-3;
295  h = Math.max(min_h, Math.max($("#the_methods").height(), $("#the_page").height()));
296 
297  $("#the_page").css('height', h);
298  $("#the_methods").css('height', h);
299}
300
301// display error wrapper
302function displayError(error) {
303  resetDisplay();
304  $("#errorWrapper").html("<b>Error:</b> "+ error).show();
305  adaptHeight();
306}
307
308// display ws_url form
309function askForUrl() {
310  if ($("#urlForm input[name='ws_url']").val() == "") {
311    $("#urlForm input[name='ws_url']").val(ws_url);
312  }
313  $("#urlForm").show();
314  displayError("can't contact web-services, please give absolute url to 'ws.php'");
315}
316
317// parse Piwigo JSON
318function parsePwgJSON(json) {
319  try {
320    resp = jQuery.parseJSON(json);
321    if (resp==null | resp.result==null | resp.stat==null | resp.stat!='ok') {
322      throw new Error();
323    }
324  }
325  catch(e) {
326    displayError("unable to parse JSON string");
327    resp = {"stat": "ko", "result": "null"};
328  }
329 
330  return resp.result;
331}
332
333// fetch methods list
334function getMethodList() {
335  resetDisplay();
336 
337  $.ajax({
338    type: "GET",
339    url: ws_url,
340    data: { format: "json", method: "reflection.getMethodList" }
341  }).done(function(result) {
342    result = parsePwgJSON(result);
343   
344    if (result!=null) {
345      methods = result.methods;
346     
347      var ml = '';
348      for (var i=0; i<methods.length; i++)
349      {
350        ml += '<li><a href="#">'+ methods[i]+'</a></li>';
351      }
352      $("#methodsList").html(ml).show();
353     
354      adaptHeight();
355     
356      // trigger method selection
357      $("#methodsList li a").click(function() {
358        selectMethod($(this).html());
359        return false;
360      });
361    }
362  }).error(function(jqXHR, textStatus, errorThrown) {
363    askForUrl();
364  });
365}
366
367// select method
368function selectMethod(methodName) {
369  $("#introMessage").hide();
370 
371  if (cachedMethods[ methodName ]) {
372    fillNewMethod(methodName);
373  }
374  else {
375    $.ajax({
376      type: "GET",
377      url: ws_url,
378      data: { format: "json", method: "reflection.getMethodDetails", methodName: methodName }
379    }).done(function(result) { 
380      result = parsePwgJSON(result);
381   
382      if (result!=null) {
383        cachedMethods[ methodName ] = result;
384        fillNewMethod(methodName);
385      }
386    }).error(function(jqXHR, textStatus, errorThrown) {
387      displayError("unknown error");
388    });
389  }
390}
391
392// display method details
393function fillNewMethod(methodName) {
394  resetDisplay();
395 
396  method = cachedMethods[ methodName ];
397 
398  $("#methodName").html(method.name).show();
399 
400  if (method.description != "") {
401    $("#methodDescription blockquote").html(method.description);
402    $("#methodDescription").show();
403  }
404 
405  var methodParams = '';
406  if (method.params && method.params.length>0) {
407    for (var i=0; i<method.params.length; i++) {
408      var isOptional = method.params[i].optional;
409      var acceptArray = method.params[i].acceptArray;
410      var defaultValue = method.params[i].defaultValue == null ? '' : method.params[i].defaultValue;
411     
412      // if an array is direclty printed, the delimiter is a comma where we use a pipe
413      if (typeof defaultValue == 'object') {
414        defaultValue = defaultValue.join('|');
415      }
416
417      methodParams+= '<tr>'+
418        '<td>'+ method.params[i].name +'</td>'+
419        '<td class="mini">'+ (isOptional ? '?':'*') + (acceptArray ? ' []':'') +'</td>'+
420        '<td class="input"><input type="text" class="methodParameterValue" data-id="'+ i +'" value="'+ defaultValue +'"></td>'+
421        '<td class="mini"><input type="checkbox" class="methodParameterSend" data-id="'+ i +'" '+ (isOptional ? '':'checked="checked"') +'></td>'+
422      '</tr>';
423    }
424        }
425  else {
426    methodParams = '<tr><td colspan="4">This method takes no parameters</td></tr>';
427  }
428 
429  $("#methodParams tbody").html(methodParams);
430  $("#methodWrapper").show(); 
431 
432  adaptHeight();
433 
434  // trigger field modification
435  $("input.methodParameterValue").change(function() {
436    $("input.methodParameterSend[data-id='"+ $(this).data('id') +"']").attr('checked', 'checked');
437  });
438}
439
440// invoke method
441function invokeMethod(methodName, newWindow) {
442        var method = cachedMethods[ methodName ];
443
444  var reqUrl = ws_url +"?format="+ $("#responseFormat").val();
445 
446  // GET
447  if ($("#requestFormat").val() == 'get') {
448    reqUrl+= "&method="+ methodName;
449   
450    for (var i=0; i<method.params.length; i++) {
451      if (! $("input.methodParameterSend[data-id='"+ i +"']").is(":checked")) {
452        continue;
453      }
454
455      var paramValue = $("input.methodParameterValue[data-id='"+ i +"']").val();
456     
457      var paramSplitted = paramValue.split('|');
458      if (method.params[i].acceptArray &&  paramSplitted.length > 1) {
459        $.each(paramSplitted, function(v) {
460          reqUrl+= '&'+ method.params[i].name +'[]='+ paramSplitted[v];
461        });
462      }
463      else {
464        reqUrl+= '&'+ method.params[i].name +'='+ paramValue;
465      }
466    }
467   
468    if (newWindow) {
469      window.open(reqUrl);
470    }
471    else {
472      $("#invokeFrame").attr('src', reqUrl);
473    }
474  }
475  // POST
476  else {
477    var form = $("#invokeForm");
478    form.attr('action', reqUrl);
479   
480    var t = '<input type="hidden" name="method" value="'+ methodName +'">';
481   
482    for (var i=0; i<method.params.length; i++) {
483      if (! $("input.methodParameterSend[data-id='"+ i +"']").is(":checked")) {
484        continue;
485      }
486
487      var paramValue = $("input.methodParameterValue[data-id='"+ i +"']").val();
488
489      var paramSplitted = paramValue.split('|');
490      if (method.params[i].acceptArray &&  paramSplitted.length > 1) {
491        $.each(paramSplitted, function(v) {
492          t+= '<input type="hidden" name="'+ method.params[i].name +'[]" value="'+ paramSplitted[v] +'">';
493        });
494      }
495      else {
496        t+= '<input type="hidden" name="'+ method.params[i].name +'" value="'+ paramValue +'">';
497      }
498    }
499   
500    form.html(t);
501    form.attr('target', newWindow ? "_blank" : "invokeFrame");
502    form.submit();
503  }
504 
505  return false;
506}
507</script>
508
509</body>
510</html>
Note: See TracBrowser for help on using the repository browser.