Selecting JSON Output

A URL in TurboGears can serve double duty by returning multiple formats depending on how it is called. In most cases, the URL will return html or xhtml by default. By adding the query parameter, tg_format=json you can switch from returning the default format to returning json data. You need to add an @expose(allow_json=True) decorator [3] to your controller method to tell TurboGears that this controller should return json data:

@expose(allow_json=True)
@expose(template='my.templates.amplifypage')
def amplify(self, data):

allow_json=True is a shortcut for this:

@expose("json", content_type="text/javascript",
        as_format="json", accept_format="text/javascript")

That means that the controller method will use the json template (uses TurboJson to marshall the returned data to json) to return data of type text/javascript when either of these conditions is met: a query param of tg_format=json or an Accept: text/javascript header is sent.

BaseClient in python-fedora 0.1.x and 0.2.x use the query parameter method of selecting json output. BaseClient 0.2.99.6 and 0.3.x use both the header method and the query parameter since the argument was made that the header method is friendlier to other web frameworks. 0.4 intends to use the header alone. If you use allow_json=True this change shouldn't matter. If you specify the @expose("json") decorator manually it is advisable to include both as_format and accept_format in your decorator so you can handle either method.

Why Two Formats from a Single URL?

When designing your URLs you might wonder why you'd want to return json and html from a single controller method instead of having two separate controller methods. For instance, separating the URLs into their own namespaces might seem logical: /app/json/get_user/USERNAME as opposed to /app/user/USERNAME. Doing things with two URLs as opposed to one has both benefits and drawbacks:

Marshalling

All data should be encoded in json before being returned. This is normally taken care of automatically by TurboGears and simplejson. If you are returning non-builtin objects you may have to define an __json__() method.

Unicode

simplejson (and probably other json libraries) will take care of encoding unicode strings to json so be sure that you are passing unicode strings around rather than encoded byte strings.

Error Handling

In python, error conditions are handled by raising an exception. However, an exception object will not propogate automatically through a return from the server. Instead we set several special variables in the returned data to inform BaseClient of any errors.

At present, when BaseClient receives an error it raises an exception of its own with the exception information from the server inside. Raising the same exception as the server is being investigated but may pose security risks so hasn't yet been implemented.

Redirects

Redirects do not play well with JSON [#] because TurboGears is unable to turn the function returned from the redirect into a dictionary that can be turned into JSON.

Redirects are commonly used to express errors. This is actually better expressed using tg_template because that method leaves the URL intact. That allows the end user to look for spelling mistakes in their URL. If you need to use a redirect, the same recipe as above will allow you to split your code paths.

tg_template

Setting what template is returnedto a user by setting tg_template in the return dict (for instance, to display an error page without changing the URL) is a perfectly valid way to use TurboGears. Unfortunately, since JSON is simply another template in TurboGears you have to be sure not to interfere with the generation of json data. You need to check whether json was requested using fedora.tg.util.request_format() and only return a different template if that's not the case.

Example

SABase is a base class that you can use when defining objects in your project's model. So the first step is defining the classes in your model to inherit from SABase:

from fedora.tg.json import SABase
from sqlalchemy import Table, Column, Integer, String, MetaData, ForeignKey
from turbogears.database import metadata, mapper

class Person(SABase):
    pass
PersonTable = Table('person', metadata
    Column('name', String, primary_key=True),
    )

class Address(SABase):
    pass
AddressTable = Table (
    Column('id', Integer, primary_key=True),
    Column('street', string),
    Column('person_id', Integer, ForeignKey('person.name')
    )

mapper(PersonTable, Person)
mapper(AddressTable, Address, properties = {
    person: relation(Person, backref = 'addresses'),
})

The next step is to tell SABase which properties should be copied (this allows you to omit large trees of objects when you only need the data from a few of them):

@expose('my.templates.about_me')
@expose(allow_json=True)
def my_info(self):
    person = Person.query.filter_by(name='Myself').one()
    person.jsonProps = {'Person': ['addresses']}
    return dict(myself=person}

Now, when someone requests json data from my_info, they should get back a record for person that includes a property addresses. Addresses will be a list of address records associated with the person.

How it Works

SABase adds a special __json__() method to the class. By default, this method returns a dict with all of the attributes that are backed by fields in the database.

Adding entries to jsonProps adds the values for those properties to the returned dict as well. If you need to override the __json__() method in your class you probably want to call SABase's __json__() unless you know that neither you nor any future subclasses will need it.