wiki:DataGridWidget
Warning: Can't synchronize with repository "(default)" (Unsupported version control system "svn": No module named svn). Look in the Trac log for more information.

Version 4 (modified by anonymous, 13 years ago) (diff)

--

Overview

DataGrid helps you to present your data on a page in a tabular form. The data expected to be a list of objects and each row renders a single object. DataGrid can integrate nicely with fastdata controllers by providing inline links to edit or delete an object or create new object of the same type. DataGrid can also be configured to render data without editing links giving you simply a nice, tabular layout with minimal efforts.

Basic usage

In a typical use case, you use DataGrid to render your model objects (SQLObject instances). The following snippet shows how DataGrid would be used to build simple user management form.

users_admin_form = DataGrid(fields=[
        ('ID', 'userId'),
        ('Name', 'displayName'),
        ('E-mail', 'emailAddress'),
        ('Created on', 'created'),
])

The fields parameter define the header of the column and object's attribute to be put in that column; each tuple represents separate table column.

When DataGrid is rendered it is given the data to be shown. DataGrid then iterates through this data and draws each element as an individual table row. To fill the row it queries the object with a corresponding name, like 'displayName' or 'userId'.

Customize cell's rendering

Sometimes simply displaying an attribute like 'displayName' is not enough. In case of TG_User object, for instance you may want to format nicely permissions a user posseses. To do this, you provide a callable object instead of the attribute name. The callable is then called with a row object and returned value is inserted in a table cell.

Example:

def format_user_permissions(u):
        # ok, nothing fancy here but you get the idea
        return ', '.join(u.permissions) 

users_admin_form = DataGrid(fields=[
        ('ID', 'userId'),
        ('Name', 'displayName'),
        ('Permissions', format_user_permissions),
])

Hint: you can use Kid's XML function to return a string with HTML markup.

Fastdata integration

Just for completeness, here is how you can use the above form with a FastData? controller:

from turbogears.fastdata import DataController
from turbogears.fastdata.datawidgets import DataGrid
from model import TG_User

class Root(controllers.RootController):
    users = DataController(sql_class=TG_User, list_widget=users_admin_form)

        # ...

Now if you access /users/ page you should see a table with a list of users, along with edit/delete icons and "Add a record" link at the bottom.

Customizing DataGrid representation

You can tweak DataGrid's representation to a certain extend by passing configuration options in a grid.insert() call. The following options are supported: show_actions, show_add_link, add_link_title. I hope their meaning is self-explaining. Most up-to-date list of these options can be found at the top of datagrid.kid file at turbogears.fastdata.templates sub-package.

When DataGrid used with FastData? you'd need to override default FastData? list template to be able to provide your own that would insert a grid with the options you want:

class Root(controllers.RootController):
    users = DataController(sql_class=TG_User,
                list_widget=users_admin_form,
        list_template='.templates.admin_users')

And something this goes to your admin_users template:

${list_widget.insert(data, show_actions=False, add_link_title='Add User')}

Changing DataGrid representation

If shallow customization described above is not enough you can change it completely by using template parameter, just like with any other Widget.

Non-fastdata environment

You can use DataGrid outside of fastdata environment without any extra efforts.

The only thing you have to remember is that DataGrid expects an iterable that gives a list of objects. DataGrid doesn't care whether particular object is SQLObject instance or not as long as it can access specified object's attribute (even that is optional if you use a callable).

Error handling

DataGrid does not intercept any exception that may raise during iteration or accessing particular object's attribute.