Custom Renderers
Introduction
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.
Definitions
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
The Renderer interface
Protected properties available to drivers
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
Methods that must or may be implemented in drivers
All of the following methods are optional.
constructor (
void
)
object setContainer (
mixed container
)
container provided by the user. It must
return a PEAR_Error object in case of failure.
object getContainer (
void
)
void init (
void
)
void buildHeader (
array columns
)
$columns is a convenient reference to the
$_columns property.
Protected methods that drivers can use
void _addDefaultOptions (
array options
)
void setOptions (
array options
)
A simple driver
Soon
Testing your driver
Soon
Using your new driver
Soon