SQLFORM.grid and SQLFORM.smartgrid

Introduction

In this article, we will discuss SQLFORM.grid and SQLFORM.smartgrid. But before going further, let's discuss what SQLFORM.grid is, and what are its uses?

SQLFORM.gird is based on SQLFORM that allows us to browse, search, sort, create, update and delete records from a single object.

Grid and smargrid are the two high-level objects used to create complex CRUD controls that provide pagination and the ability to browse, search, sort, create, update and delete records from a single object.

SQLFORM.grid and SQLFORM.smartgrid

grid and smartgrid were experimental before web2py version 2.0 and vulnerable to information leakage. Therefore, the grid and smartgrid no longer have practical uses, but the only reason we are still not promising backward compatibility of the grid's presentation layer is its APIs.

Because web2py's HTML objects are built on the underlying, simpler objects, the grids create SQLFORMs for viewing, editing, and creating rows. Most of the arguments are passed through SQLFORM to the grids. This means that the documentation for SQLFORM (and FORM) is relevant. Let's take an example where the grid takes an onvalidation callback, and ultimately, the processing logic of the grid passes this through to the underlying process() method of FORM.

A new request is generated as the grid passes through different states, such as editing a row, and the request.args has information about the grid's state.

SQLFORM.grid

It is simple to implement the SQLFORM.grid. So, let's see an example of its usage.

@auth.requires_login()
def manage_users():
    grid = SQLFORM.grid(db.auth_user)
    return locals()

You can also try this code with Online Python Compiler

Run Code

The first argument of SQLFORM.grid should be a table or a query. Also, the grid object will provide access to records matching the query.

Before diving into the grid object's long list of arguments, we must understand how it works. The object looks at request.args to decide what to do (browse, search, create, update, delete, etc.). Each button created by the object links the same function (manage_users in the above case) but passes a different request.args.

login required by default for data updates

We cannot perform some actions like create, update, and delete without logging in, as all the URLs generated by the grid are digitally signed and verified by default.  

These restrictions can be relaxed by the following:

def manage_users():
    grid = SQLFORM.grid(db.auth_user, user_signature=False)
    return locals()

You can also try this code with Online Python Compiler

Run Code

But we do not recommend doing it.

Multiple grids per controller function

Because of how a grid works, 

One can have only one grid per controller function unless they are embedded as components via LOAD. 

Also, use a different formname to make the default search grid work in more than one LOADed grid.

Using requests.args safely

The controller function that contains the grid may manipulate the URL arguments (known in web2py as a response.args and response.vars). Also, the grid needs to know which args should be handled and which not.

Below is an example of code that allows managing any table.

@auth.requires_login()
def manage():
    table = request.args(0)
    if not table in DB.tables(): redirect(URL('error'))
    grid = SQLFORM.grid(db[table], args=request.args[:1])
    return locals()

You can also try this code with Online Python Compiler

Run Code

The grid's argument specifies which request.args should be passed along and ignored by the grid. In this case, request.args[:1] indicates the name of the table that we want to manage, which is handled by the manage function itself but not by the grid. So, args=request.args[:1] tells the grid to preserve the first URL argument in any links it generates, appending any grid-specific arguments after that first argument.

In the above article, we have discussed SQLFORM.grid. You can also check out SQLFORM.smargrid, SQLFORM.grid Signature from the Coding Ninjas to explore yourself.

Now, let's discuss some FAQs related to them.