webservices

Documentation TOC  »  Features  »  Wiki  »  Wiki Plugin  »  PluginWebservice

Plugin Web Service

1. Introduction

Parameters

1.1. WikiSyntax

1.2. Administrator Setup

1. Create a plugin alias to the webservices plugin

1. Name any fields

1. Code to format the webservice data goes into the Default Content field

1.3. Fuller explanation movie

2. Why

• Including bug tracking information from an external source (such as Bugzilla) in documentation pages.
• Showing the results of images searches in xxx where the results are automatically refreshed.
• More examples ...

3. How

• The remote site must export the data in either JSON or YAML, or XML using SOAP.
• The data must be publicly available as no authentication methods are currently supported.

1. Self-contained, all inline in a page
2. Defined (by an administrator) as a webservice
3. Defined (by an administrator) using a plugin alias.

3.1. Output types

• Smarty to generate wiki syntax
• Smarty to generate HTML
• Javascript to generate HTML

3.2. Hello, World: Yahoo's Madonna Example

{"ResultSet":{
  "totalResultsAvailable":"229307",
  "totalResultsReturned":"2",
  "firstResultPosition":"1",
  "Result":[
    {
      "Title":"madonna 116",
      "Summary":"Picture 116 of 184",
      "Url":"http:\/\/www.celebritypicturesarchive.com\/pictures\/m\/madonna\/madonna-116.jpg",
      "ClickUrl":"http:\/\/www.celebritypicturesarchive.com\/pictures\/m\/madonna\/madonna-116.jpg",
      "RefererUrl":"http:\/\/www.celebritypicturesarchive.com\/pgs\/m\/Madonna\/Madonna%20picture_116.htm",
      "FileSize":"36990",
      "FileFormat":"jpeg",
      "Height":"530",
      "Width":"425",
      "Thumbnail":{
        "Url":"http:\/\/scd.mm-b1.yimg.com\/image\/481989943",
        "Height":"125",
        "Width":"100"
       }
    },
    {
      "Title":"madonna 118",
      "Summary":"Picture 118 of 184",
...
      }
    }
  ]
}
}

{WEBSERVICE(url="http://search.yahooapis.com/ImageSearchService/V1/imageSearch?appid=YahooDemo&query=Madonna&output=json")}
||
Total Results Available|{{$response.ResultSet.totalResultsAvailable}}
Total Results Returned|{{$response.ResultSet.totalResultsReturned}}
||
{{foreach from=$response.ResultSet.Result item=result}}
* Title {{$result.Title}}
{{/foreach}}
{WEBSERVICE}

• In Tiki 3.0 there was a fault in the template code meaning the above example would fail. Versions after r19669 have this fixed.

3.3. Fuller Example

{WEBSERVICE(url=http://bugzilla.example.com/bugexport.pl?id=00002345)}
!! {{$response.title}}
||ID|[http://bugzilla.example.com/bug/{{$response.id|escape|'url'}}|{{$response.id}}]
Status|{{$response.status}}
Assignee|{{$response.assignee.full_name}}
Open Date|{{$response.open_date}}
Last Modification|{{$response.last_modif}}
||

{{foreach from=$response.comments item=comment}}
* [http://bugzilla.example.com/bug/{{$response.id|escape|'url'}}#{{$comment.id}}|{{$comment.title}}] by ''{{$comment.author.full_name}}'' on {{$comment.date}}
{{/foreach}}
{WEBSERVICE}

3.4. Registering a Webservice

• A name
• A URL with parameters
• A type (REST / SOAP)
• A list of available templates

• A name
• The output format (use value tikiwiki or html)
• The engine used to execute the template ( smarty or javascript )
• The content of the template (this is not a content or smarty template, this template is defined where you register the webservice.)

{WEBSERVICE(service=bugzilla,template=complete,id=00002345)/}

3.5. Bundling the webservice in a Plugin Alias

• Redirect to the WEBSERVICE plugin
• Always use bugzilla as the service
• Accept a required id parameter which would be passed directly to WEBSERVICE
• Accept an optional template parameter, which would provide the required documentation to indicate the supported templates (ex: status|link|short|complete). If not provided, it would use complete as the default value.
• Ignore any user input in the body
• Require no validation because all parameters are safe.

{BUGZILLA(id=00002345)/}

{BUGZILLA(id=00002345,template=short)/}

3.6. Implementation notes

• Other scripting languages or templating engines could be added. However, because Tiki is already bundled with Smarty, it was a natural choice.

4. Security

5. Presentation Suggestion