This Project Has Moved!
As of 28 April, 2010, this project has moved to Google Code:
All documentation/code on this site is from the original source repository, and is no longer maintained.
JSONMessage
JSONMessage is a JavaScript/PHP framework for JSON-based RPC. It can be used to generically add JSON-centric RPC support to a wide variety of web applications.
Author: Stephan Beal (http://wanderinghorse.net/home/stephan/)
License: Good question! Next Question! The core code is Public Domain. Some of it optionally uses 3rd-party libraries like jQuery or Dojo, and may inherit a license from that code. e.g. if you use the jQuery bits and your jQuery is GPL, then that code inherits the GPL as well. The core bits, however, you can do whatever the hell you want to with them.
Demo: demo/
Downloading: see the download page.
Getting started: see the (Mini-)HOWTO page. The source tree also includes a fairly thorough library manual in OpenDocument format.
Primary Features
- Easy to import, use, and extend.
- Provides a uniform interface for passing arbitrary JSON-compatible data between servers and JS clients. The default/reference server-side installation requires PHP5, but it could be re-implemented using other back-ends (e.g. Ruby or, God forbid, ASP).
- The server-side components compress all responses if the client supports it.
- JS-side, it can use near-arbitrary AJAX providers. e.g. if you have a favourite JS toolkit (e.g. jQuery, Dojo, Prototype, or Mojo), you can tell JSONMessage to use it for all AJAX traffic. It provides implementations for raw XMLHttpRequests, jQuery, Dojo, and Prototype (but i've had bad luck with buggy JSON quoting in Prototype and Mojo).
- Posting and handling messages is uniform, regardless of the underlying AJAX back-end. The client code just deals with high-level objects and interfaces, with JSON-friendly response data, and is completely shielded from AJAX-level details.
- Application-wide defaults can be set for all AJAX parameters, so client code need not ever see them (not even the URL(s)).
- While the high-level interface is uniform, server-side response handlers each define their own "payload" data structure interfaces (of arbitrary complexity) for requesting and returning data. The only limitation is that the incoming/outgoing payloads be JSON-compatible. Server-side applications which already generate JSON simply need one more layer of indirection to plug them into this framework.
- Because it can use arbitrary AJAX back-ends, it can be used in non-web-browser environments (e.g. application-embeddable JS engines like SpiderMonkey or Google v8), provided they can supply the internal plumbing necessary for performing requests and responses. They need not be HTTP-based (or even network-capable at all), as long as the server and clients all speak the same protocol(s) and agree to use JSON as the transport format for client data.
- The framework is flexible enough to insert arbitrary layers between the request/response APIs. e.g. one could insert a client-side response caching layer without affecting how the API is used client-side.
Primary Mis-features
- Not all AJAX back-ends have a way to pass HTTP login information. (In theory you can always pass it along with the URL, e.g. http://me:mypassword@host/.)
- Not all AJAX back-ends (*cough*Prototype*cough*) have (publically documented) support for timeouts.
- See the Disclaimer, below.
JSONMessage in the wild...
Here's an application which uses this framework to fetch Wiki pages from Google Code: