==============
zif.jsonserver
==============


JSON is javascript object notation. JSON-RPC performs the same service
as XML-RPC, except the transport is javascript objects instead of XML.

jsonserver Project:

This project provides the additional functionality of listening and responding
properly to requests of type "application/json-rpc".


Dependencies
------------

This package will work with Zope 3 version 3.3 or greater.  The svn version of 
jsonserver tries hard to keep up with Zope 3's development version available at 
svn://svn.zope.org/repos/main/Zope3/trunk.

jsolait from http://jsolait.net is the recommended client-side javascript
library.  Installation of jsolait is covered in the README.txt file in this
package's jsolait folder.


Installation
------------

Install this package in a location accessible to your zope3 instance. The
lib/python folder of the instance is a good choice.

The files in the etc folder should go into etc/package-includes.

A README.txt file in the jsolait folder has instructions for installing
a client javascript library.


Usage
-----

Similar to xmlrpc usage.

jsonserver looks for content-type "application/json-rpc", and handles those 
requests as JSON-RPC.  Other http requests are not affected and will 
presumably work as expected.  Now that there is an official mime-type for JSON,
jsonserver also supports "application/json".  "application/json-rpc" 
may be considered deprecated.

jsonrpc provides another namespace,
'http://namespaces.zope.org/jsonrpc' for zcml configuration.
Statements like

::

  <jsonrpc:view for="" permission="" methods="" class="" />

are used in zcml to make jsonrpc methods viewable.

You may create views that appear only if a jsonrpc listener is installed:

::

  <configure zcml:condition="have jsonrpc">
    <jsonrpc:view
        for="someInterface"
        permission="zope.View"
        methods="blah blecht"
        class=".views.JsonViewClass"
        />
  </configure>

To make a view class, subclass
zif.jsonserver.jsonrpc.MethodPublisher like this:

::

    from zif.jsonserver import MethodPublisher
    class MyClass(MethodPublisher):
        def myOutput(self):
            blah = 'something cool'
            return blah
        def myOutput1(self,param1):
            blecht = self.context.something(param1)
            return blecht

where the return value can be a python simple object
(int, long, float, string, etc.) or list or dictionary composed of
simple objects, lists, and/or dictionaries.  Composite built-ins
like complex numbers, dates, or classes are not currently
supported.  Decompose those, and send a list or dictionary instead.
Multiple returned values will be marshalled into a list.

For web pages, you will need to include a javascript library for the client side
in your page template:

::

    <script type="text/javascript" src="/++resource++jsolait/jsolait.js"></script>

will bring in the recommended jsolait library, if it is installed here.  The following javascript examples
are for jsolait, but any similar javascript library may be used, or you can write your own.  The 
xmlHTTPRequest POST must set a content-type of "application/json-rpc" for this package to invoke
json-rpc requests on the server.

From your client javascript code, import the jsonrpc module:

::

    var jsonrpc = imprt('jsonrpc');

Then, make a jsolait connection proxy ("." often works fine for addr):

::

    addr="address to server object providing jsonrpc view class";
    //for better error handling, see http://jsolait.net/wiki/documentation
    try{var aServer = new jsonrpc.ServiceProxy(addr, ["myOutput"]);
        }catch(e){alert(e);}

then, for async communication, provide a callback function:

::

    function doThis(resp,err){
    if (!err) {do something with resp} else {do something with err}
    }

and call the method:

::

    aServer.myOutput(aparam,doThis);

If you want sync communication, call the method without
the name of a function as the last parameter.

For communication other than in a web browser (javascript), minjson.py
or other json implementations have functions for reading and writing
JSON objects.

The text of a JSON-RPC request (v1.0) looks like:

::

    {"id":jsonid,"method":remotemethod,"params":methodparams}

where

- jsonid is a string or number that may identify this specific request

- remotemethod is the method to call on the server

- methodparams is a list (javascript Array) of parameters to the method

The text of a JSON-RPC response looks like:

::

    {"id":jsonid,"result":returnedresult,"error":returnederr}

where

- jsonid is the same jsonid as sent in the request

- returnedresult is a javascript representation of the result or null

- returnederr is a javascript representation of an error state

Either returnedresult or returnederr will be the javascript null value.

Actual implementation using e.g., urllib is left as an exercise for the
reader. Hint:  Use the minjson.write(object) and minjson.read(string)
methods for conversion before and after transport.


Dojo
----

JSON-RPC in Dojo should work out-of-the-box with jsonserver, since it provides a
content-type supported by jsonserver.  A preliminary package that serves a 
per-object ".smd" file is available at dojosupport.

Dojo is available at "http://dojotoolkit.org":http://dojotoolkit.org .


Simple JSON / Non-POST Views
----------------------------

JSON Views accessible to HTTP GET are also provided with zif.jsonserver.
See "JSONViews":/jsonviews_README.html .


Page Templates, Form Variables, and Named Parameters
----------------------------------------------------

jsonserver will work with page templates and similar
snippets of HTML.  Most registered views (browser:page or similar)
are also accessible to json-rpc clients.  The simplest way to use a 
page template is to call it in javascript just as you would call a 
jsonrpc:view.  jsonserver sets a request variable, JSONRPC_MODE, 
which will be True if a template is requested through json-rpc.  
This may be useful if you need json-rpc-specific behavior.

If you need form data, jsonserver has a special facility for this.  The
contents of any client object (dict) passed as a parameter to json-rpc 
that is (cleverly) named "pythonKwMaRkEr" will be available in the request 
as items in request.form.  If you call methods with named parameters, 
those items also will replace the named parameters as appropriate.

A pythonkw module is provided here for use with jsolait on the client side. 
Code like

::

  var pythonkw = imprt("pythonkw");
  var kwparams = new pythonkw.PythonKw({'parm1': 'aaa', 'parm2': text_value})
  var result = aServer.my_portlet(kwparams);

will do the marshalling so you do not have to type "pythonKwMaRkEr".

Here is an example of using a page template through a
jsonrpc:view method (ViewPageTemplateFile is in zope.app.pagetemplate)

::

    def my_portlet(self,parm1='bbb',parm2=None):
        date = datetime.now()
        rand = random.randint(0,2000)
        portlet = ViewPageTemplateFile("my_portlet.pt")
        return portlet(self,date=date,random=rand,parm1=parm1)

In the above example, parm1 is available to the template as options/parm1
and as request/form/parm1.  parm2 may be available to the template as 
request/form/parm2 if provided in the request.


Debugging
---------

To get verbose output of requests, responses, and errors,
set level DEBUG for your event log in etc/zope.conf for your
instance. e.g.,

::

    <eventlog>
     level DEBUG
      <logfile>
        path $LOGDIR/z3.log
      </logfile>
      <logfile>
        path STDOUT
      </logfile>
    </eventlog>

You can get pretty much the same results with tcpwatch, except you get the 
entire request and response with tcpwatch.

Compatibility
-------------

Most compatibility issues should  be about client implementations.  

jsonserver will accept any valid JSON-RPC request that is a POST with 
content-type "application/json-rpc" or "application/json".  Output responses will be of 
content-type "application/x-javascript" so that browser clients can know
that the response will be interpreted in javascript.

jsolait should work on any current browser with enabled javascript and
a functioning xmlHTTPRequest POST implementation.  This includes most
gecko browsers (Firefox, Mozilla, and Netscape 6.1+), khtml browsers (Safari and
konqueror), recent IEs, and Opera 8.1+.  If it will do Google maps, it probably
will do jsolait.


Unicode Support
---------------

jsonserver supports unicode properly now, I think, (maybe?).  If you have a 
project that depends on unicode, let me know if this does anything unexpected.
