##############################################################################
#
# Copyright (c) 2005 Balazs Ree <ree@ree.hu>
# 		and Jim Washington jwashin@vt.edu and Contributors
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
jsonserver

Based on:

- jsonserver for zope3 by Jim Washington jwashin@vt.edu and Contributors
- ZPublisher/xmlrpc.py 

JSON is javascript object notation. JSON-RPC performs the same service
as XML-RPC, except the format is javascript script objects instead of
XML, and the content-type is 'application/json-rpc' instead of 'text/xml'.

====================
jsonserver for zope2
====================

This project overrides some base zope2 code to provide the additional
functionality of listening and responding properly to requests of type
"application/json-rpc".

This works with zope2.8 or higher, or zope2.7 with Five installed.

Dependencies:
-------------

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.

jsolait is licensed by the LGPL.

Installation:
-------------

Install this package to the Products path of the zope instance.

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.

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 it installed here.

Otherwise if you know of a better method for publishing these scripts
from the application root, please let me know.

In client side javascript, make a jsolait connection proxy::

    addr="address to server object providing jsonrpc view class"
    try{var aServer = new jsonrpc.ServiceProxy(addr, ["myOutput"]);
        }catch(e){reportException(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.

You can also pass keyword parameters to a python method, python script
or page template. In this case the last parameter should be the
desired keywords object wrapped into the PythonKw class::

	/* import the module */
	var pythonkw = importModule("pythonkw");

	/* pass the keywords */
	aServer.my_method(new pythonkw.PythonKw({'parm1': 'aaa', 'parm2': 'bbb'}));

	/* ... or */
	aServer.my_method(arg1, arg2, ..., argn, new pythonkw.PythonKw({'parm1': 'aaa', 'parm2': 'bbb'}));
	
	/* ... or in async */
	aServer.my_method(arg1, arg2, ..., argn, new pythonkw.PythonKw({'parm1': 'aaa', 'parm2': 'bbb'}), asyncCallBackFunc);
	
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 looks like::

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

where:

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

    o remotemethod is the method to call on the server

    o 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:

    o jsonid is the same jsonid as sent in the request

    o returnedresult is a javascript representation of the result or null

    o 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.

Compatibility:
--------------

jsolait should work on any current browser with enabled javascript and
a functioning xmlHTTPRequest POST implementation.  This includes most
Mozilla (gecko) browsers like Firefox, konqueror (khtml) browsers, like
Safari, and IE 6.0+.

Opera 8.0 also works now but because
their xmlHTTPRequest implementation does not support setting request
headers, we must recognize requests by magic instead of the mime type.

Five extensions
---------------

The "json" namespace (http://namespaces.zope.org/json) defines the
**page** and **pages** directives. **json:page** is identical to
**browser:page** in the usage, but the page or method declared
is allowed to be called up in a json request, but will be
invisible for normal requests.

**browser:page** and **browser:pages** declarations will be
available to both normal and json requests.

**json:page** declarations will be callable from code and
their macros will be visible from other templates.


Release notes
-------------

In Zope 2.9.2 there is Five 1.3.3 included. This contains a but that
the resources will never be looked up from the
application root.

To fix this, you need to update Five to version 1.3.5, or update Zope
to version 2.9.3 (not available of the time of writing this).