Writing your own Renderer allows you to fine tune every aspect of Structures_DataGrid output.
You may need to output the datagrid in a completely unsupported format. Then writing your own Renderer is the only option
But you may also need a unsupported variant of an existing renderer, say, for example, a very specific HTML output. In this case, you generally have two options : either writing a Rendering driver from scratch, or customizing (subclassing) an existing one.
This document will present you the Rendering driver interface, and how to implement it. You will certainly see how flexible Structures_DataGrid can become with custom Renderers, but also how easy we have to tried to make this process.
A Rendering driver is a descendent of the Structures_DataGrid_Renderer class, which implements the Renderer interface.
Renderer is a synomym for Rendering driver.
The Renderer interface consists in a set of methods that drivers must or may overload and protected properties that drivers can use, as well as recommended practices.
A Rendering container is either an object that contain a sort of rendering engine, or a variable of any type (string, array, object, etc...) that can contain the output of a Renderer.
A Renderer with Container Support driver is specific to, and knows how to handle, a given type of Rendering container.
A driver is said to provide Container Support when it is able to handle a given type of Rendering container. Drivers with Container Support must implement the setContainer() and getContainer() public methods. They must be able to use a Rendering container provided by the user with setContainer(). They must also be able to create and intialize a Rendering container if the user does not provide any.
A driver is said to provide Output Buffering when it buffers the output that it generates, implements the flatten() method and is able to return the generated output from flatten().
A Direct Rendering driver is the simplest form of Renderer. It directs all of its output to standard output. By definition, a such driver neither provide Container support nor Output Buffering
All of the following properties are read-only : drivers can access their content but must not change it directly.
array $_options -Common and driver-specific options
array $_columns - Columns fields names and labels
int $_columnsNum - Number of columns
array $_records - Records content
int $_recordsNum - Number of records in the current page
int $_totalRecordsNum - Total number of records as reported by the datasource
int $_firstRecord - First record number (starting from 1), in the current page
int $_lastRecord - Last record number (starting from 1), in the current page
int $_page - Current page number (starting from 1)
int $_pageLimit - Number of records per page
int $_pagesNum - Number of pages
string $_requestPrefix - GET/POST/Cookie parameters prefix
array $_currentSort - Fields/directions the data is currently sorted by
array $_sortableFields - Which fields the datagrid may be sorted by
All of the following methods are optional.
The constructor must set default options via _addDefaultOptions(), if any, and call the parent constructor.
setContainer() is responsible for attaching a rendering container provided by the user. It must return a PEAR_Error object in case of failure.
getContainer() must return a reference to the container used by the driver. It must return a PEAR_Error object in case of failure.
init() must initialize the rendering process. This method is also responsible for creating the container if it has not already been provided with setContainer().
buildHeader() must build the header. $columns is a convenient reference to the $_columns property.
_addDefaultOptions() is used to declare the driver-specific options, if any, as well as their default values. It must be called from the constructor.
setOptions() is a public method used to set options. If they ever need to change options, drivers should use this method.