Class: Structures_DataGrid_Renderer

Source Location: /Structures_DataGrid-0.9.3/Structures/DataGrid/Renderer.php

Class Overview

Base class of all Renderer drivers

Author(s):

Olivier Guilyardi <olivier at samalyse.com>
Mark Wiesemann <wiesemann at php.net>
Sascha Grossenbacher <saschagros at bluewin.ch>

Version:

$Revision$

Inherited Variables

Inherited Methods

Class Details

[line 145]
Base class of all Renderer drivers

SUPPORTED OPTIONS:

buildHeader: (bool) Whether to build the header.
buildFooter: (bool) Whether to build the footer.
fillWithEmptyRows: (bool) Ensures that all pages have the same number of rows.
numberAlign: (bool) Whether to right-align numeric values.
defaultCellValue: (string) What value to put by default into empty cells.
defaultColumnValues: (array) Per-column default cell value. This is an array of the form: array(fieldName => value, ...).
hideColumnLinks: (array) By default sorting links are enabled on all columns. With this option it is possible to disable sorting links on specific columns. This is an array of the form: array(fieldName, ...). This option only affects drivers that support sorting.
encoding: (string) The content encoding. If the mbstring extension is present the default value is set from mb_internal_encoding(), otherwise it is ISO-8859-1.
extraVars: (array) Variables to be added to the generated HTTP queries.
excludeVars: (array) Variables to be removed from the generated HTTP queries.
columnAttributes: (array) Column cells attributes. This is an array of the form: array(fieldName => array(attribute => value, ...) ...) This option is only used by XML/HTML based drivers.
onMove: (string) Name of a Javascript function to call on onclick/onsubmit events when the user is either paging or sorting the data. This function receives a single object argument of the form: { page: <page>, sort: [{field: <field>, direction: <direction>}, ...], data: <user_data> }. Remark: setting this option doesn't remove the href attribute, you should return false from your handler function to void it (eg: for AJAX, etc..).
onMoveData: (string) User data passed in the "data" member of the object argument passed to onMove. No JSON serialization is performed, this is assigned as a raw string to the "data" attribute. It's up to you to add quotes, slashes, etc...

--- DRIVER INTERFACE ---

Methods (none required):

Constructor
setContainer()
getContainer()
init()
defaultCellFormatter()
buildHeader()
buildBody()
buildRow()
buildEmptyRow()
buildFooter()
finalize()
flatten()
render()
getPaging() (deprecated)

Properties (all read-only):

$_columns
$_columnsNum
$_currentSort
$_firstRecord
$_lastRecord
$_multiSort
$_options
$_page
$_pageLimit
$_pagesNum
$_records
$_recordsNum
$_requestPrefix
$_sortableFields
$_totalRecordsNum

Options that drivers may handle:

encoding
fillWithEmptyRows
numberAlign
extraVars
excludeVars

Author: Olivier Guilyardi <olivier@samalyse.com>
Author: Mark Wiesemann <wiesemann@php.net>
Author: Sascha Grossenbacher <saschagros@bluewin.ch>
Version: $Revision$
Abstract:
Access: public

[ Top ]

Class Variables

$_columns = array()

[line 158]

Columns' fields names and labels

Drivers can read the content of this property but must not change it.

Var: Structure: array(<columnIndex> => array(field => <fieldName>, label=> <label>), ...) Where <columnIndex> is zero-based
Access: protected

Type:

array

[ Top ]

$_columnsNum =

[line 204]

Number of columns

Drivers can read the content of this property but must not change it.

Access: protected

Type:

int

[ Top ]

$_currentSort = array()

[line 184]

Fields/directions the data is currently sorted by

Drivers can read the content of this property but must not change it.

Var: Structure: array(fieldName => direction, ....)
Access: protected

Type:

array

[ Top ]

$_defaultDirections = array()

[line 306]

The default directions to sort by

Drivers can read the content of this property but must not change it.

Var: Structure: array(field => ASC|DESC, ...)
Access: protected

Type:

array

[ Top ]

$_features = array()

[line 326]

Special driver features

Access: protected

Type:

array

[ Top ]

$_firstRecord =

[line 234]

First record number (starting from 1), in the current page

Drivers can read the content of this property but must not change it.

Access: protected

Type:

int

[ Top ]

$_lastRecord =

[line 244]

Last record number (starting from 1), in the current page

Drivers can read the content of this property but must not change it.

Access: protected

Type:

int

[ Top ]

$_multiSort = false

[line 194]

Whether the backend support sorting by multiple fields

Drivers can read the content of this property but must not change it.

Access: protected

Type:

bool

[ Top ]

$_options = array()

[line 318]

Common and driver-specific options

Drivers can read the content of this property but must not change it.

See: Structures_DataGrid_Renderer::_addDefaultOptions()
See: Structures_DataGrid_Renderer::setOption()
Access: protected

Type:

array

[ Top ]

$_page = 1

[line 256]

Current page

Page number starting from 1.

Drivers can read the content of this property but must not change it.

Access: protected

Type:

int

[ Top ]

$_pageLimit = null

[line 266]

Number of records per page

Drivers can read the content of this property but must not change it.

Access: protected

Type:

int

[ Top ]

$_pagesNum =

[line 276]

Number of pages

Drivers can read the content of this property but must not change it.

Access: protected

Type:

int

[ Top ]

$_records = array()

[line 174]

Records content

Drivers can read the content of this property but must not change it.

Var: Structure: array( <rowIndex> => array( <columnIndex> => array(<cellValue>, ...), ...), ...) Where <rowIndex> and <columnIndex> are zero-based
Access: protected

Type:

array

[ Top ]

$_recordsNum = 0

[line 214]

Number of records in the current page

Drivers can read the content of this property but must not change it.

Access: protected

Type:

int

[ Top ]

$_requestPrefix = ''

[line 286]

GET/POST/Cookie parameters prefix

Drivers can read the content of this property but must not change it.

Access: protected

Type:

string

[ Top ]

$_sortableFields = array()

[line 296]

Which fields the datagrid may be sorted by

Drivers can read the content of this property but must not change it.

Var: Field names
Access: protected

Type:

array

[ Top ]

$_totalRecordsNum =

[line 224]

Total number of records as reported by the datasource

Drivers can read the content of this property but must not change it.

Access: protected

Type:

int

[ Top ]

$_urlMapper = null

[line 371]

URL mapper instance, if provided

Access: protected

Type:

object Net_URL_Mapper

[ Top ]

Method Detail

Structures_DataGrid_Renderer (Constructor) [line 381]

Structures_DataGrid_Renderer Structures_DataGrid_Renderer(
)

Instantiate the driver and set default options and features

Drivers may overload this method in order to change/add default options.

See: Structures_DataGrid_Renderer::_addDefaultOptions()
Access: public

[ Top ]

build [line 792]

void build(
array
$chunk, integer
$startRow, [boolean
$eof = false])

Build the grid

Drivers must not overload this method. Pre and post-build operations can be performed in init() and finalize()

Access: public

Parameters:

array	`$chunk`	—	2D array of records
integer	`$startRow`	—	Starting row number of current chunk
boolean	`$eof`	—	Whether the current chunk is the last chunk

[ Top ]

buildBody [line 657]

void buildBody(
)

Build the body

Drivers may overload() this method, if buildRow() and buildEmptyRow() are not flexible enough.

Return: or PEAR_Error
Access: protected

[ Top ]

buildEmptyRow [line 707]

void buildEmptyRow(
int
$index)

Build an empty row

Drivers must overload this method if they need to do something with empty rows that remain at the end of the body.

This method will only be called if the "fillWithEmptyRows" option is enabled.

Return: or PEAR_Error
Abstract:
Access: protected

Parameters:

int $index — Row index (zero-based)

[ Top ]

buildFooter [line 720]

void buildFooter(
)

Build the footer

Drivers may optionally implement this method.

Return: or PEAR_Error
Abstract:
Access: protected

[ Top ]

buildHeader [line 615]

void buildHeader(
array
$columns)

Build the header

Drivers may optionally implement this method.

Return: or PEAR_Error
Abstract:
Access: protected

Parameters:

array $columns — Columns' fields names and labels (This is a convenient reference to the $_columns protected property)

[ Top ]

buildRow [line 689]

void buildRow(
int
$index, array
$data)

Build a body row

This is a very simple method for drivers to build a row. For more flexibility, drivers should overload buildBody()

Return: or PEAR_Error
Abstract:
Access: protected

Parameters:

int	`$index`	—	Row index (zero-based)
array	`$data`	—	Record data. Structure: array(0 => <value0>, 1 => <value1>, ...)

[ Top ]

defaultCellFormatter [line 775]

string defaultCellFormatter(
string
$value)

Default formatter for all cells

Drivers may optionally implement this method.

Return: Formatted cell value
Abstract:
Access: protected

Parameters:

string $value — Cell value

[ Top ]

finalize [line 734]

void finalize(
)

Finish building the datagrid.

Drivers may optionally implement this method for any post-build() operations.

Return: or PEAR_Error
Abstract:
Access: protected

[ Top ]

flatten [line 760]

mixed flatten(
)

Retrieve output from the container object

Drivers may optionally implement this method.

This method is meant to retrieve final output from the container.

Usually the container is an object (ex: HTMLTable instance), and the final output a string.

The driver knows how to retrieve such final output from a given container (ex: HTMLTable::toHTML()), and this is where to do it.

Sometimes the container may not be an object, but the final output itself. In this case, this method should simply return the container.

This method mustn't output anything directly to the standard output.

Return: Output
Abstract:
Access: protected

[ Top ]

getContainer [line 579]

object Container getContainer(
)

Return the container used by the driver

Drivers should implement this method when they have some kind of support for rendering containers.

Return: of the class supported by the driver or PEAR_Error
Abstract:
Access: public

[ Top ]

getFeatures [line 1188]

array getFeatures(
)

List special driver features

Return: Of the form: array(feature => true|false, etc...)
Access: public

[ Top ]

getOutput [line 919]

mixed getOutput(
)

Returns the output from the renderer (e.g. HTML table, XLS object, ...)

Drivers must not overload this method. Output generation has to be implemented in flatten().

Return: The output from the renderer
Access: public

[ Top ]

getUrlMapper [line 1223]

object Net_URL_Mapper getUrlMapper(
)

Return the URL mapper

Return: instance or null
Access: public

[ Top ]

hasFeature [line 1200]

bool hasFeature(
string
$name)

Tell if the driver as a specific feature

Access: public

Parameters:

string $name — Feature name

[ Top ]

init [line 598]

void init(
)

Create or/and prepare the container

Drivers may optionally implement this method for any pre-build() operations.

For the container support, it is responsible for creating the container if it has not already been provided by the user with the setContainer() method. It is where preliminary container setup should also be done.

Abstract:
Access: protected

[ Top ]

isBuilt [line 1045]

bool isBuilt(
)

Query the grid build status

Return: Whether the grid has already been built or not
Access: public

[ Top ]

render [line 942]

void render(
)

Render to the standard output

This method may be overloaded by renderer drivers in order to prepare writing to the standard output (like calling header(), etc...).

Return: or object PEAR_Error
Access: public

[ Top ]

setColumns [line 484]

void setColumns(
array
$columns)

Provide columns

This method is supposed to be called ONLY by the code that loads the driver. In most cases, that'll be the Structures_DataGrid class.

Access: public

Parameters:

array $columns — Array of Structures_DataGrid_Column objects

[ Top ]

setContainer [line 563]

mixed setContainer(
object Container
$container)

Attach a container object

Drivers that provide support for the Structures_DataGrid::fill() method must implement this method.

Return: True or PEAR_Error
Abstract:
Access: public

Parameters:

object Container $container — of the class supported by the driver

[ Top ]

setCurrentSorting [line 506]

void setCurrentSorting(
array
$currentSort, [bool
$multiSortCapable = false])

Specify how the datagrid is currently sorted

This method is supposed to be called ONLY by the code that loads the driver. In most cases, that'll be the Structures_DataGrid class.

The multiSort capabilities is related to the multiSort DataSource feature. In short : the DataGrid checks if the DataSource supports multiSort and informs the Renderer about it.

Access: public

Parameters:

array	`$currentSort`	—	Structure: array(fieldName => direction, ....)
bool	`$multiSortCapable`	—	Whether the backend support sorting by multiple fields

[ Top ]

setLimit [line 523]

void setLimit(
int
$currentPage, int
$rowsPerPage, int
$totalRowNum)

Specify page and row limits

This method is supposed to be called ONLY by the code that loads the driver. In most cases, that'll be the Structures_DataGrid class.

Access: public

Parameters:

int	`$currentPage`	—	Current page number
int	`$rowsPerPage`	—	Maximum number of rows per page
int	`$totalRowNum`	—	Total number of data rows

[ Top ]

setOption [line 470]

void setOption(
string
$name, mixed
$value)

Set a single option

Access: public

Parameters:

string	`$name`	—	Option name
mixed	`$value`	—	Option value

[ Top ]

setOptions [line 458]

void setOptions(
mixed
$options)

Set multiple options

Access: public

Parameters:

mixed $options — An associative array of the form: array("option_name" => "option_value",...)

[ Top ]

setRendered [line 990]

void setRendered(
[bool
$status = false])

Sets the rendered status. This can be used to "flush the cache" in case you need to render the datagrid twice with the second time having changes

This is quite an obsolete method...

Access: public

Parameters:

bool $status — The rendered status of the DataGrid

[ Top ]

setRequestPrefix [line 1005]

void setRequestPrefix(
string
$prefix)

Set the HTTP Request prefix

Access: public

Parameters:

string $prefix — The prefix string

[ Top ]

setStreaming [line 548]

void setStreaming(
int
$status)

Tell the renderer whether streaming is enabled or not

This method is supposed to be called ONLY by the code that loads the driver. In most cases, that'll be the Structures_DataGrid class.

Access: public

Parameters:

int $status — Whether streaming is enabled or not

[ Top ]

setUrlMapper [line 1212]

void setUrlMapper(
object
$instance)

Set the URL mapper

Access: public

Parameters:

object $instance — Net_URL_Mapper instance

[ Top ]

streamBody [line 628]

void streamBody(
array
$records, integer
$startRow, [boolean
$eof = false])

Stream a chunk of records

Return: or PEAR_Error
Access: protected

Parameters:

array	`$records`	—	2D array of records
integer	`$startRow`	—	Starting row number
boolean	`$eof`	—	Whether the current chunk is the last chunk

[ Top ]

_addDefaultOptions [line 430]

void _addDefaultOptions(
array
$options)

Adds some default options.

This method is meant to be called by drivers. It allows adding some default options.

See: Structures_DataGrid_Renderer::setOption()
Access: protected

Parameters:

array $options — An associative array of the from: array(optionName => optionValue, ...)

[ Top ]

_buildOnMoveCall [line 1161]

string _buildOnMoveCall(
string
$page, mixed
$sortSpec)

Build a Javascript handler call for a given page and sorting spec

Return: JS function string, semi-colon included
Access: protected

Parameters:

string	`$page`	—	Page number (can also be "%d" for replacement by Pager, etc...)
mixed	`$sortSpec`	—	Array of fields and directions, or raw javascript string

[ Top ]

_buildSortingHttpQuery [line 1069]

string _buildSortingHttpQuery(
string
$field, string
$direction, [bool
$convertAmpersand = false], [array
$extraParameters = array()])

Build an HTTP query for sorting a given column

This is a handy method that most drivers can use in order to build the HTTP queries that are used to sort columns.

It takes the global "extraVars", "excludeVars" options as well as the $_requestPrefix property into account and can also convert the ampersand to XML/HTML entities according to the "encoding" option.

Return: Query string of the
Access: protected

Parameters:

string	`$field`	—	Sort field name
string	`$direction`	—	Sort direction
bool	`$convertAmpersand`	—	Whether to convert ampersands to XML/HTML compliant entities
array	`$extraParameters`	—	Optional extra HTTP parameters

[ Top ]

_noSupport [line 974]

object PEAR_Error _noSupport(
string
$method)

Return an error related to an unsupported public method

When a given public method is not implemented/supported by the driver it must return a PEAR_Error object with code DATAGRID_ERROR_UNSUPPORTED. This is a helper method for generating such PEAR_Error objects.

Example:

 function anUnsupportedMethod()

 {
     return $this->_noSupport(__FUNCTION__);
 }

Return: with code DATAGRID_ERROR_UNSUPPORTED
Access: protected

Parameters:

string $method — The name of the unsupported method

[ Top ]

_setFeatures [line 446]

void _setFeatures(
array
$features)

Add special driver features

This method is meant to be called by drivers. It allows specifying the special features that are supported by the current driver.

Access: protected

Parameters:

array $features — An associative array of the form: array(feature => true|false, ...)

[ Top ]