Introduction

Gecko Toolbox contains a powerful DataGrid component, capable of plotting any DataSource, independent of its source, be a XML, Array, SQL, etc.

The Grid is broken in three principal areas:

DataSource

It's the source of data for the grid, the Toolbox only contains a SQL, and DBTable Sources, but if you inplement the interface you can create your custom DataSources, and show them in a table.

Formatter

The grid uses a Formatter for displaying the grid as a HTML Table, also has some basic CellRenderers to render data in cells.

You can extend, or create custom Formatters and Renderers to allow complex tables be created.

DataGrid

It's the Gateway between the Data and the presentation, handles all of the logic for extracting the data from the DataSource and printing it on the web page, checks if pagination is needed and sorts the data source if needed.

Grid Creation

You can create a custom and quick Grid with very little effort, the needed steps are: 1. Create the DataSource 1. Create the Grid 1. Build Grid 1. Render on WebPage

Below you can see a basic example: ``` users"; $model = new Gecko_DataSource_Table_SQL($query, $db);

$grid = new Gecko_DataGrid("users", $model); $grid->buildTable(); ?> Grid Test ```

If you need to paginate and / or sorting you can enable them creating a settings array and passing it to the grid as the third argument: $settings = array( "paginate" => 3, // Number of rows to show per page "sorting" => array( "sortColumn" => "id", "sortOrder" => "ASC" ) ); $grid = new Gecko_DataGrid("users", $model, $settings);

If you need to display the column names different you can tell the formatter about it: $formatter = $grid->getFormatter(); $colNames = array( "id" => "ID", "firstname" => "First Name", "lastname" => "Last Name", "age" => "Age" ); $formatter->setColumnNames($colNames);

If you are going to use a custom Formatter, you can pass it as the fourth parameter to the grid, or call setFormatter at any time (before calling buildTable) or pasing a "formatter" element in the settings array. Remember that if your are creating a custom formatter you have to implement Gecko_DataGrid_Formatter_Interface.

If you need to create additional columns (for example a view, or edit link) at the end or the beginning of your table, you have to either: create a custom formatter or extend the Table Formatter (Gecko_DataGrid_Formatter_Table).

If you are extending the default Table Formatter, you can add your custom columns at the beginRow() or endRow() methods, inside the formatter you can access the Table object using $this->table.

If you want to customize some of the cells, you can call the addCellRenderer method of the formatter, and pass in the column name, and the cellRenderer to use.

The ToolBox contains three basic renderers: * URL Renderer: Transforms a Cell into a clickable link, if you pass the second argument to the constructor, you can have a value of the dataSource be printed in the link, ej: $urlRenderer = new Gecko_DataGrid_CellRenderer_URL("/your/url/?id=%VALUE%", "id"); $formatter->addCellRenderer("id", $urlRenderer); The URL Renderer supports a third argument that is the label of the link if you want to swap it. * Image Renderer: Transforms a cell into a image, it can optinally check if the image exists and put a default image in case the image doesn't exist. Example: $imageRenderer = new Gecko_DataGrid_CellRenderer_Image("/url/path/to/images", "/physical/path/to/images/", "/path/to/404.image" ); All arguments are optional. * Printf Renderer: Transforms the Cell value using the printf syntax you want, example: $printfRenderer = new Gecko_DataGrid_CellRenderer_Printf("%.2f");

The formatter can work with multiple renderers, just make sure you are correct in the order you submit them or you can end with malformed html and/or different data, for example, transform a image cell into a Image with a link: $formatter->addCellRenderer("image", $imageRenderer); $formatter->addCellRenderer("image", $urlRenderer);

The grid supports automatic pagination if you submit the "paginate" element in the settings array or you call the setMaxRows method of the grid. You can then call setNavMsg, to set a custom pagination message, for example: Browsing %s of %s pages. You can also submit the navMsg in the settings array.

Once you call buildTable you can't alter any settings of the table, and then the only methods available are getId, getNavLinks and getOutput (or simply echo $grid).

The toolbox also ships with a extended Formatter that if needed can add a View, Edit, and Delete Link at the end of each row, you can initiate it and pass it to the grid, the first argument is the settings array for each link, and the second argument is the column name wich contains a id to append to the url $fsettings = array( 'viewLink' => true, 'viewLabel' => "View", // This can contain any HTML needed 'viewUri' => '/viewscript?id=%VALUE%' ); $formatter = new Gecko_DataGrid_Formatter_ViewEditDeleteTable( $fsettings, "id" );

Zend Controller

If you are using Zend Controller, you must change the URL Engine for creating and reading the current requests. To change the engine just add a line before rendering or creating the table (preferably in the Bootstrap): Gecko_URL::setDefaultURLEngine(new Gecko_URL_Engine_Zend());

Static methods

The grid also supports two quick static methods for creating a grid, these are: Gecko_DataGrid::createFromSQL, and Gecko_DataGrid::createFromDBTable, you can pass the same arguments as the Source constructor, except that the first argument should be the table name, for example: $query = "SELECT * FROM something"; $grid = Gecko_DataGrid::createFromSQL("users", $query);

That will create a grid, and will look for the DB Adapter in a 'db' entry in the registry, or will attempt to create one using Gecko_DB::getInstance();