Custom Renderers

Custom Renderers – How to write your own Rendering driver.

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 )

The constructor must set default options via _addDefaultOptions(), if any, and call the parent constructor.

object setContainer ( mixed container )

setContainer() is responsible for attaching a rendering container provided by the user. It must return a PEAR_Error object in case of failure.

object getContainer ( void )

getContainer() must return a reference to the container used by the driver. It must return a PEAR_Error object in case of failure.

void init ( void )

init() must initialize the rendering process. This method is also responsible for creating the container if it has not already been provided with setContainer().

void buildHeader ( array columns )

buildHeader() must build the header. $columns is a convenient reference to the $_columns property.

Protected methods that drivers can use

void _addDefaultOptions ( array options )

_addDefaultOptions() is used to declare the driver-specific options, if any, as well as their default values. It must be called from the constructor.

void setOptions ( array options )

setOptions() is a public method used to set options. If they ever need to change options, drivers should use this method.

A simple driver

Soon

Testing your driver

Soon

Using your new driver

Soon