representation format in web2py database

Question

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

What does this format do here?

Impaction

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.

Rochette

Thanks. What I don't understand here is what do this symbol % and the s at the end of argument mean – Impaction

That's just standard Python string formatting notation. The format string can include the names of any fields within the table. – Rochette

By the way, how to get the username of a user who has already logged in my website on server-side? Thank you – Impaction

I've figured it out. Using session.auth.user.username, right? – Impaction

Yes, though you can also get it from auth.user.username. – Rochette

Thank you Anthony, A small clarification please, does format='%(name)s mean that the primary key is now the field 'name' instead of 'id' in the persons table? – Xanthine

No, the format argument is used purely for display purposes -- it does not affect the underlying data or primary key in any way. – Rochette