'''The SQLForm.grid - SQLForm.grid is the best thing that has happened to Web2py recently. Though it is still in its infancy, it is very powerful and commands its own slice. I’ve tried to get some details for preparing the slides from Google Group threads and help from code and web2py group people. Should work with web2py1.99.2 and above. '''

The SQLForm.grid Syntax- derived from code.

SQLForm.grid(query, fields=None, field_id=None, left=None,    headers={},      orderby=None,    
    searchable=True,  sortable=True,  paginate=20,   deletable=True, editable=True, details=True, 
    selectable=None, create=True, csv=True, links=None, links_in_grid=True, upload = 
    <default>'  args=[], user_signature = True, maxtextlengths={}, maxtextlength=20, 
        onvalidation=None, oncreate=None, onupdate=None, ondelete=None, 
    sorter_icons=('[^]','[v]'),  ui = 'web2py',  showbuttontext=True,  
    _class="web2py_grid",  formname='web2py_grid',
        search_widget='default',   ignore_rw = False,  formstyle = 'table3cols', ):

Real World Example of Usage:

Consider a db table as below- in your model - (db.py)

db.define_table(‘contact’, 
                           Field('first_name', length=128),
             Field('last_name', length=128),
             Field('date_of_birth', ‘date’)
)

#To create a grid for this table, add the following code in your controller –  (default.py)
#Assuming you are exposing the grid in contact.html view – 

def contact():
        db.contact.id.readable=False # Since we do not want to expose the id field on the grid

    #Define the query object. Here we are pulling all contacts having date of birth less than 18 Nov 1990
    query=((db.contact.date_of_birth < “1990-11-18”))

    #Define the fields to show on grid. Note: (you need to specify id field in fields section in 1.99.2
    # this is not required in later versions)
        fields = (db.contact.id, db.contact.first_name, db.contact.last_name, db.contact.date_of_birth)

    #Define headers as tuples/dictionaries
    headers = {'contact.id':   'ID',
           'contact.first_name': 'First Name',
           'contact.last_name': 'Last Name',
           'contact.date_of_birth': 'Birth Date' }

    #Let's specify a default sort order on date_of_birth column in grid
    default_sort_order=[db.contact.date_of_birth]

    #Creating the grid object
    form = SQLForm.grid(query=query, fields=fields, headers=headers, orderby=default_sort_order,
                create=False, deletable=False, editable=False, maxtextlength=64, paginate=25)

    return dict(form=form)

Note:

create= False -  will not show the Add button to the grid,
    deletable=False - will not show the delete button on grid
    editable=False - will not show the edit button on grid
    maxtextlength =64  - will restrict column text lenght to 64 characters and
    paginate=25  - will provide pagination to grid. here 25 records in the grid.

More parameters from the syntax can be added as per your requirement. Links could be added to the grid by adding this line. Here default is your controller name and view is your function name.

links = [lambda row: A('View Post',_href=URL("default","view",args=[row.id]))]

These could be called by adding 
links=links to the SQLForm.grid() function as a parameter.

Finally the view (contact.html)

In the view simply write the following code. You can add more to this file depending on your requirements

{{extend 'layout.html'}}
{{=form}} <! This will call the contact function -->

That's it start your web2py application and point your browser to contact.html

it should work!

Some things to consider for proper working of SQLForm.grid - -------- 1. As of this writing, css files in a plugin_layout / layout should be manipulated manually to show the SQLForm.grid else sometimes it messes the UI of the grid. In this case you have to make sure that you include below files in layout.html of your application

{{response.files.append(URL('static','jquery-ui/js/jquery-ui-1.8.16.custom.min.js'))}}
{{response.files.append(URL('static','jquery-ui/css/sunny/jquery-ui-1.8.16.custom.css'))}}