representation format in web2py database

Question

db.define_table('person', Field('name'), format='%(name)s')

What does this format do here?

Answer 1

The format argument is used to determine how fields in other tables that reference the 'person' table will be displayed. For example, if you define:

db.define_table('dog',
    Field('name'),
    Field('owner', db.person)

The 'owner' field is a reference field that references the 'person' table (i.e., it stores record id's of records from the 'person' table). In most cases, when you display data from the 'dog' table, you don't want to display the raw db.person record id that is stored in the 'owner' field because that doesn't have any meaning -- instead, it makes more sense to display the 'name' of the person. In web2py, the format attribute of the table enables this automatic substitution in both forms and tables.

When you create a SQLFORM based on the 'dog' table, it will automatically generate a drop-down list for the 'owner' field, and because of the format='%(name)s' argument to the 'person' table definition, the drop-down list will display db.person names instead of record id's (even though upon form submission, the 'owner' field will store the associated record id rather than the name).

Also, if you display records from the 'dog' table in a SQLTABLE or SQLFORM.grid, the 'owner' field will show the owner's name rather than the owner's record id.

See http://web2py.com/books/default/chapter/29/6#Record-representation.