Metadata-Version: 1.0
Name: zif.jsonserver
Version: 0.1
Summary: A json server for zope 3.
Home-page: http://zif.svn.sourceforge.net/viewvc/zif/zif.jsonserver
Author: Jim Washington
Author-email: jwashin@users.sourceforge.net
License: ZPL2.1
Description: ****************
        zif.jsonserver
        ****************
        
        See 'src/zif/jsonserver/README.txt' for more information.
        
        
        Releases
        ********
        
        ================
        0.1 (2007/04/13)
        ================
        
        Initial release.
        
        
        Detailed Documentation
        **********************
        
        ==============
        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.
        
        Download
        **********************
        
Keywords: jsonserver json zope3
Platform: UNKNOWN
