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

Changes between Initial Version and Version 1 of DataGridWidget

01/28/06 01:47:53 (13 years ago)
Max <ischenko@…>



  • DataGridWidget

    v1 v1  
     1== Overview == 
     3DataGrid 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. 
     5== Basic usage == 
     7In 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. 
     11users_admin_form = DataGrid(fields=[ 
     12        ('ID', 'userId'), 
     13        ('Name', 'displayName'), 
     14        ('E-mail', 'emailAddress'), 
     15        ('Created on', 'created'), 
     19The `fields` parameter define the header of the column and object's attribute to be put in that column; each tuple represents separate table column. 
     21When 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'. 
     23== Customize cell's rendering == 
     25Sometimes 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. 
     31def format_user_permissions(u): 
     32        # ok, nothing fancy here but you get the idea 
     33        return ', '.join(u.permissions)  
     35users_admin_form = DataGrid(fields=[ 
     36        ('ID', 'userId'), 
     37        ('Name', 'displayName'), 
     38        ('Permissions', format_user_permissions), 
     42Hint: you can use Kid's XML function to return a string with HTML markup. 
     44== Fastdata integration == 
     46Just for completeness, here is how you can use the above form with a FastData controller: 
     49from turbogears.fastdata import DataController 
     50from turbogears.fastdata.datawidgets import DataGrid 
     53class Root(controllers.RootController): 
     54    users = DataController(sql_class=TG_User, list_widget=users_admin_form) 
     56        # ... 
     59Now 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. 
     61== Customizing !DataGrid representation == 
     63You 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. 
     65When 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: 
     69class Root(controllers.RootController): 
     70    users = DataController(sql_class=TG_User, 
     71                list_widget=users_admin_form, 
     72        list_template='.templates.admin_users') 
     75And something this goes to your `admin_users` template: 
     79${list_widget.insert(data, show_actions=False, add_link_title='Add User')} 
     82== Changing !DataGrid representation == 
     84If shallow customization described above is not enough you can change it completely by using `template` parameter, just like with any other Widget. 
     86== Non-fastdata environment == 
     88You can use DataGrid outside of fastdata environment without any extra efforts. 
     90The 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). 
     92== Error handling == 
     94DataGrid does not intercept any exception that may raise during iteration or accessing particular object's attribute.