Components

Modules

Project Documentation

JSON - JavaScript Object Notation

JSON is a very popular data transmission format used in many XHR applications - the ever popular gmail application makes extensive use of it. The official web site has much more information on all the details at http://json.org.

While the majority of default XHR (ajax) behaviour provided by Tapestry uses XML as the exchange format - because of how easy it is to wrap existing html blocks - it does also provide a great deal of support/API functionality for you to utilize JSON data transmission formats in your own applications.

This document will go over some of the basics of using this part of the API on the client / server side as well as show examples of how it is used by Tapestry itself in components such as the Autocompleter.

JSON Basics

The basic idea behind the JSON format is that you can output something using it from the server and your browser can evaluate it and access the structures you define directly - like any other javascript object. For example, we could define a response listing the general attributes of a user in some theoretical system we are building:

You get the idea.. One of the more useful things provided by http://json.org is a sample java API for working with the format - http://www.json.org/java/index.html. Tapestry has incorporated this java code in to the API proper (with some minor improvements) so creating our first example JSON object output can be as simple as:

The basic idea is the same as the typical IComponent.renderComponent(IMarkupWriter, IRequestCycle) call - except that in this case you are dealing with a IJSONWriter instance instead of the more familiar IMarkupWriter. This interface is really just a wrapper around the JSON api provided by Tapestry.

Once you have implemented this IJSONRender interface in one of your components that is pretty much all there is to do. The JSON method you implement will only be called if a JSON request is processed by Tapestry AND the request has specified your component as one of the components to update and capture the response of. Otherwise the normal html markup based methods will be called on your component.

Client Side Processing

Processing json response data on the client side isn't really something Tapestry can do for you, so you'll have to have your own consumer of this data set up to handle it beforehand. If you use the standard Tapestry API's then the global tapestry.loadJson javascript function will be invoked. Currently this function does nothing other than decrement the global tapestry.requestsInFlight javascript variable value. You can replace or do an event connection on this function to provide your own implementation. An example of doing an event connection would be:

This component actually makes use of some new base classes - like AbstractFormWidget - don't let this distract you from the IJSONRender interface portion. They are both mutually exclusive and totally unrelated.

That is pretty much it. This component hands off the majority of client side functionality to a Dojo widget and only provides the widget with a URL string produced by a pre-generated JSON request. You can find the full source and all of the gory details of the rest of that here.