Grid Documentation

Grid is one of the fundamental views in Agile Toolkit. The goal of it's implementation is to be lightweight, extensible and fast. Select topic in the left sidebar, or you can also visit one of the resources below:

How to use Grid?

Grid is designed to show structured data organised into rows and columns. Grid introduces ability to format each column depending on it's type as well as to perform a custom formatting. If you wish to specify a custom template for rows, then look at Lister instead.

To get grid working, you would need some data to show in it. It can be either a static data or dynamic based on SQL query or a Model. Best practice is to use Grid with Models or dynamic data source, which also allows to use features such as column sorting and pagination. Grid never loads all the data into memory, so it's well suited for displaying data from large SQL tables.

Result

Name Surname
John Smith9
Peter Tester24
 

Code

$data=(array(
  array(
'name'=>'John','surname'=>'Smith'.rand(1,20)),
  array(
'name'=>'Peter','surname'=>'Tester'.rand(20,40))
));

$g=$p->add('Grid');
$g->addColumn('name');
$g->addColumn('surname');
$g->setStaticSource($data);

Database example

Grid integrates directly with the database layer and dynamic queries and can fetch data once you specify which table to look into.

Result

Name Surname
No Records Found
 

Code

$g=$p->add('Grid');
$g->addColumn('name');
$g->addColumn('surname');
$g->setSource('user');
$g->dq->where('name!=','')->limit(5);

Grid does not operate with the queries directly, instead it uses the dsql to build the query. The same code as above uses the following query for data fetching:

select SQL_CALC_FOUND_ROWS *, user.id id from user where (name!= '') limit 0, 5

You can add joins, conditions, sorting calculated fileds and many more things by accessing $g->dq directly.

MVC Grid

The best use of Grid is when you are using it together with Model. This is suggested way of implemetning your application. Please note that MVCGrid is used instead of regular grid. MVCGrid inherits all the properties, but also properly implements column population from the model.

Result

Id Name
5374 234 asdf
5375 a34
5376 asdf
 

Code

$g=$p->add('MVCGrid');
$g->setModel('Person');
$g->dq->limit(5);

Buttons, Quicksearch and Paginator

Area around the grid historically has a number of template tags which are commonly used by things like Buttons, Quicksearch form and Paginator. All those features are implemented outside of Grid, but they are added its template and may have impact on Grid's query.

Result

Gender Name
No Records Found
 

Code

$g=$p->add('Grid');
$g->addColumn('text','gender');
$g->addColumn('text','name');
$g->setSource('user');

$g->addPaginator(5);
$g->addQuickSearch(array('name'));
$g->addButton('Hello');

Interacting with Grid

Since Grid is designed to be rendered efficiently, it does not create objects on per-row basis. If you need to do some complex row calculation based on sub-selects then trust this work to SQL. Grid, however, allows few column types which are designed to control things. Button-columns.

Result

Gender Name Button Link Expander
No Records Found
 

Code

$g=$p->add('Grid');
$g->addColumn('text','gender');
$g->addColumn('text','name');
$g->setSource('user');
$g->dq->where('name!=','')->limit(5);

$g->addColumn('button','button');
$g->addColumn('link','./link','Link');
$g->addColumn('expander','expander');

All of those requests carry over the ID of the row. Button performs an AJAX request to the page and can be used for virtually any action. There are more types, but those 3 are the most common.