zif.jsonserver 0.6

0.6 (2007/05/25)

Updated release notes.

0.5 (2007/05/25)

Corrections to setup.

0.4 (2007/05/25)

Incorporated jsolait into release.

0.3 (2007/05/24)

Repackaging to ensure zcml files are included for zope 3.

0.2 (2007/04/18)

Corrected setup configuration file to include zif namespace.

0.1 (2007/04/13)

Initial release.

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.