Grid

A tabular data presentation tool.

Quick Start

$grid = new Grid;
$grid->link()->action('entries/add')->text('Add New Entry');
$grid->column()->field('id')->title('Entry ID');
$grid->column()->field('title')->title('Entry Title');
$grid->column('date')->title('Creation Date');
$grid->column('action')->title('Edit')->url('entries/edit')->text('edit');
$grid->data($dataset);
echo $grid;

Setting up a Grid

There are 5 steps for creating a grid.

1. Instantiate a grid object
2. Specify action links (if any)
3. Specify columns
4. Add data
5. Render the grid

Specifying Action Links

The grid library allows for links to be printed at the top and bottom of a grid table. Typical usage includes "add a new entry" and "edit the selected" links.

Links are specified by the Grid Library's link() method, which returns a link object. The argument of the link() method specifies the type of link, either text (default), button, or submit. Attributes of a link object are specified by calling a function by the name of the attribute, passing the value as an argument.

All links have the following attributes:

action : the path (or route) for the link text : the text to display for the link

Text Link

$grid->link()->action('controller/method')->text('Link Text');
// OR
$grid->link('text')->action('controller/method')->text('Link Text');

Will produce Link Text

Button Link

$grid->link('button')->action('controller/method')->text('Link Button');

Will produce Link Button

Submit Link

$grid->link('submit')->action('controller/method')->text('Link Submit');

Will produce

Specifying Columns

The grid library allows for columns to be defined. The columns specify what fields from each dataset record will be printed, and how it will be printed.

Columns are specified by the Grid Library's column() method, which returns a column object. The argument of the column() method specifies the type of column (default is text). Attributes of a column object are specified by calling a function by the name of the attribute, passing the value as an argument.

All columns have the following attributes:

field : the field of the dataset record to print title : the column heading

Text Column

$grid->column()->title('Name')->field('name');
// OR
$grid->column('text')->title('Name')->field('name');

Will produce

... Name ...

<tr>
    ...
    <td><?php echo $record->name; ?></td>
    ...
</tr>

Additional attributes include:

callback : a callback function to execute prior to printing

Date Column

$grid->column('date')->title('Created')->field('created');

Extends text columns to pass the value of $record->$field through the PHP date() function.

Additional attributes include:

format : a PHP date format string to use as the first parameter for date()

The field attribute defaults to "date".

Action Column

$grid->column('action')->title('Details')->url('controller/method')->field('id')->text('view');
// OR
$grid->column('action')->title('Details')->route('default')->params(array('controller'=>'controller', 'action'=>'method'))->param('id')->text('view');

Will produce

... Details ...

<tr>
    ...
    <td><a href="http://www.domain.com/controller/method/<?php echo $record->field; ?>">view</a></td>
    ...
</tr>

Additional attributes include: url : string url to use as the link target route : use a given route instead of a string params : parameters to use with the given route param : the route parameter to set with the specified record field text : the text to use for the link; if specified as {field}, then the value of record->{field} will be displayed

Note: The field attribute defaults to "id", and the value of the field is appended to the end of the action url.

Radio Column

$grid->column('radio')->title('Edit')->field('id')->name('to_edit');

Will produce

... Edit ...

<tr>
    ...
    <td><input type="radio" name="to_edit" value="<?php echo $record->$field; ?>" /></td>
    ...
</tr>

Additional attributes include: name : the input name for the radio column

The field attribute defaults to "id".

Specifying Data

The grid library allows for data to be added with the data() method. The argument to the data() method is expected to be an iteratable collection of data records.

For example: $users = Sprig::factory('user')->load(null, FALSE); $grid->data($users);

The data() function can be called multiple times to add more dataset records to the grid dataset.

Customizing the Grid

To create a new column type, create a new class and place it in APPPATH.'/classes/grid/column/newtype.php'

The new column class must extend Grid_Column to take advantage of the member variable set functions (via the magic __call() function). If a new variable is going to be used, specify it as a public member of the column class.

The custom column class must implement the public function render($data). This function can perform any data manipulation necessary and return a string (which will be placed between ).

For example: <?php class Grid_Column_Hash extends Grid_Column { public $salt = ''; public $hash = 'md5';

    public function render($data) {
        $data = (object) $data;
        $text = $data->{$this->field};
        return hash($this->$hash, $salt.$text);
    }
}

$grid->column('hash')->title('Hash')->field('password')->salt('somesalt');