By returning a dictionary from your controller methods, you make it possible for TurboGears to dynamically decide how the data should be presented to the browser. Most often, you’ll want to return HTML.
TurboGears makes it easy to return JSON from your methods by converting the returned dictionary into the appropriate JSON. This means that your application can instantly get a usable API in addition to its browser-based interface!
You might not want someone to get JSON for all your exposed methods, so TurboGears disallows JSON by default. To enable it you can:
@expose("json")on a particular method
If a request comes in with a parameter of
will perform the JSON conversion. If the parameter is missing, your
templates will process as normal.
This is a good option for providing both a direct web interface and an optional json interface on top. Good for those who like to “progressively enhance” their web apps.
tg_format=jsonon every method. You can selectively restrict this call by adding
allow_json=Falseas an argument to
In any event, to convert the JSON to a usable object, you simply
this in the browser, you’ll have a hash table of your data, ready to use!
MochiKit provides a convenience function
loadJSONDoc that sends an
XMLHttpRequest to the server and returns the
If you use the hybrid approach with
allow_json=True, and you include
TurboGears widgets in your returned dictionary so they can be used by a
template, you may run into the problem that the widgets cannot (and need
not) be JSONified when requesting JSON output. You can add the following
json.py file to render all widgets as null values in JSON:
from turbogears.widgets.base import Widget @jsonify.when("isinstance(obj, Widget)") def jsonify_widgets(obj): return None
By the way, this workaround is only needed in TurboGears 1. In TurboGears 2,
you would pass the widgets in
tmpl_context instead, and return only the
actual data in the dictionary.