Docs For Class Structures

Structures_DataGrid (Constructor) [line 305]

void Structures_DataGrid(
[string
$limit = null], [int
$page = null], [string
$rendererType = null])

Constructor

Builds the DataGrid class. The Core functionality and Renderer are seperated for maintainability and to keep cohesion high.

Access: public
Example: example not found

Parameters:

string	`$limit`	—	The number of records to display per page.
int	`$page`	—	The current page viewed. In most cases, this is useless. Note: if you specify this, the "page" GET variable will be ignored.
string	`$rendererType`	—	The type of renderer to use. You may prefer to use the $type argument of render, fill or getOutput

[ Top ]

addColumn [line 1023]

mixed addColumn(
object
$column, [string
$position = 'last'], [string
$relativeTo = null])

Add a column, with optional position

Return: PEAR_Error on failure, void otherwise
Access: public
Example: example not found

Parameters:

object	`$column`	—	The Structures_DataGrid_Column object (reference to)
string	`$position`	—	One of: "last", "first", "after" or "before" (default: "last")
string	`$relativeTo`	—	The name (label) or field name of the relative column, if $position is "after" or "before"

[ Top ]

attachRenderer [line 769]

mixed attachRenderer(
object
$renderer)

Attach an already instantiated Rendering driver

Return: Renderer instance or a PEAR_Error object
See: Structures_DataGrid::setRenderer()
Access: public

Parameters:

object $renderer — Driver object, subclassing Structures_DataGrid_Renderer

[ Top ]

bind [line 1171]

bool bind(
mixed
$container, [array
$options = array()], [string
$type = null])

A simple way to add a record set to the datagrid

Return: True if successful, otherwise PEAR_Error.
Access: public
Example: example not found
Example: example not found

Parameters:

mixed	`$container`	—	The record set in any of the supported data source types
array	`$options`	—	Optional. The options to be used for the data source
string	`$type`	—	Optional. The data source type

[ Top ]

bindDataSource [line 1189]

mixed bindDataSource(
mixed
$source)

Bind an already instantiated DataSource driver

Return: True if successful, otherwise PEAR_Error
Access: public

Parameters:

mixed $source — The data source driver object

[ Top ]

build [line 1549]

mixed build(
)

Build the datagrid

Return: Either true or a PEAR_Error object
Access: public

[ Top ]

dataSourceFactory [line 437]

Structures_DataGrid_DataSource|PEAR_Error dataSourceFactory(
mixed
$source, [array
$options = array()], [string
$type = null])

Datasource driver Factory

A clever method which loads and instantiate data source drivers.

Can be called in various ways:

Detect the source type and load the appropriate driver with default options:

 $driver = Structures_DataGrid::dataSourceFactory($source);

Detect the source type and load the appropriate driver with custom options:

 $driver = Structures_DataGrid::dataSourceFactory($source, $options);

Load a driver for an explicit type (faster, bypasses detection routine):

 $driver = Structures_DataGrid::dataSourceFactory($source, $options, $type);

Return: driver object or PEAR_Error on failure
Access: public
Uses: Structures_DataGrid::_detectSourceType()

Parameters:

mixed	`$source`	—	The data source respective to the driver
array	`$options`	—	An associative array of the form: array(optionName => optionValue, ...)
string	`$type`	—	The data source type constant (of the form DATAGRID_SOURCE_*)

[ Top ]

dump [line 335]

void dump(
)

Method used for debugging purposes only. Displays a dump of the DataGrid object.

Access: public

[ Top ]

enableStreaming [line 1717]

void enableStreaming(
[integer
$bufferSize = 500])

Enable streaming support for reading from DataSources and writing with Renderers and set the buffer size (number of records)

Access: public

Parameters:

integer $bufferSize — Number of records that should be buffered

[ Top ]

fill [line 809]

mixed fill(
object
$container, [array
$options = array()], [string
$type = null])

Fill a rendering container with data

Return: Either true or a PEAR_Error object
Access: public
Example: example not found
Example: example not found

Parameters:

object	`$container`	—	A rendering container of any of the supported types (example: an HTML_Table object, a Spreadsheet_Excel_Writer object, etc...)
array	`$options`	—	Options for the corresponding rendering driver
string	`$type`	—	Explicit type in case the container type can't be detected

[ Top ]

generateColumns [line 1738]

void generateColumns(
[array
$fields = array()])

Generate columns from a fields list

This is a shortcut for adding simple columns easily, instead of creating them manually and calling addColumn() for each.

The generated columns are appended to the current column set.

Access: public

Parameters:

array $fields — Fields and labels. Array of the form: array(field => label, ...) The default is an empty array, which means: all fields fetched from the datasource

[ Top ]

getColumnByField [line 1124]

object Either getColumnByField(
string
$fieldName)

Find a column by field name

Return: the column object (reference to) or false if there is no such column
Access: public

Parameters:

string $fieldName — The field name of the column to look for

[ Top ]

getColumnByName [line 1104]

object Either getColumnByName(
string
$name)

Find a column by name (label)

Return: the column object (reference to) or false if there is no such column
Access: public

Parameters:

string $name — The name (label) of the column to look for

[ Top ]

getColumnCount [line 922]

int getColumnCount(
)

Returns the number of columns

Return: the number of columns
Access: public

[ Top ]

getColumns [line 1080]

array getColumns(
)

Return the current columns

Return: Structures_DataGrid_Column objects (references to). This is a numerically indexed array (starting from 0).
Access: public

[ Top ]

getCurrentPage [line 882]

int getCurrentPage(
)

Retrieves the current page number when paging is implemented

Return: the current page number
Access: public

[ Top ]

getCurrentRecordNumberEnd [line 969]

int getCurrentRecordNumberEnd(
)

Returns the number of the last record of the current page

Return: the number of the last record currently shown
Access: public

[ Top ]

getCurrentRecordNumberStart [line 952]

int getCurrentRecordNumberStart(
)

Returns the number of the first record of the current page

Return: the number of the first record currently shown, or: 0 if there are no records, 1 if there is no row limit
Access: public

[ Top ]

getDataSource [line 646]

object DataSource getDataSource(
)

Get the currently loaded DataSource driver

Retrieves the DataSource object as a reference

Return: object reference or null if no driver is loaded
Access: public

[ Top ]

getOutput [line 579]

mixed getOutput(
[int
$type = null], [array
$options = array()])

Return the datagrid output

Return: The datagrid output (Usually a string: HTML, CSV, etc...) or a PEAR_Error
Access: public

Parameters:

int	`$type`	—	Renderer type (optional)
array	`$options`	—	An associative array of the form: array(optionName => optionValue, ...)

[ Top ]

getPageCount [line 907]

int getPageCount(
)

Returns the total number of pages

Return: the total number of pages or 1 if there are no records or if there is no row limit
Access: public

[ Top ]

getRecordCount [line 933]

int getRecordCount(
)

Returns the total number of records

Return: the total number of records
Access: public

[ Top ]

getRenderer [line 632]

object Renderer getRenderer(
)

Get the current or default Rendering driver

Retrieves the renderer object as a reference

Return: object reference
Access: public

[ Top ]

removeColumn [line 1145]

void removeColumn(
object
$column)

Remove a column

Access: public
Example: example not found

Parameters:

object $column — The Structures_DataGrid_Column object (reference to)

[ Top ]

render [line 517]

mixed render(
[mixed
$renderer = null], [array
$options = array()])

Render the datagrid

You can call this method several times with different renderers.

Return: True or PEAR_Error
Access: public

Parameters:

mixed	`$renderer`	—	Renderer type or instance (optional)is_object($source) &&
array	`$options`	—	An associative array of the form: array(optionName => optionValue, ...)

[ Top ]

setCurrentPage [line 895]

void setCurrentPage(
mixed
$page)

Define the current page number.

This method is used when paging is implemented

Access: public

Parameters:

mixed $page — The current page number (as string or int).

[ Top ]

setDataSourceOption [line 1689]

void setDataSourceOption(
string
$name, mixed
$value)

Set a single datasource option

Access: public

Parameters:

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

[ Top ]

setDataSourceOptions [line 1701]

void setDataSourceOptions(
array
$options)

Set multiple datasource options

Access: public

Parameters:

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

[ Top ]

setDefaultSort [line 1328]

mixed setDefaultSort(
array
$sortSpec)

Set default sorting specification

If there is no sorting query in the HTTP request, and if the sortRecordSet() method is not called, then the specification passed to setDefaultSort() will be used.

This is especially useful if you want the data to already be sorted when a user first see the datagrid.

This method needs to be called before bind().

Return: Either true or a PEAR_Error object
Access: public

Parameters:

array $sortSpec — Sorting specification Structure: array(fieldName => direction, ...)

[ Top ]

setRenderer [line 667]

mixed setRenderer(
string
$type, [array
$options = array()])

Set Renderer

Defines which renderer to be used by the DataGrid based on given $type and $options. To attach an existing renderer instance, use attachRenderer() instead.

Return: Renderer instance or PEAR_Error
See: Structures_DataGrid::attachRenderer()
Access: public

Parameters:

string	`$type`	—	The defined renderer string
array	`$options`	—	Rendering options

[ Top ]

setRendererOption [line 1652]

void setRendererOption(
string
$name, mixed
$value, [bool
$common = false])

Set a single renderer option

Access: public

Parameters:

string	`$name`	—	Option name
mixed	`$value`	—	Option value
bool	`$common`	—	Whether to use this option for all renderers (true) or only for the current one (false)

[ Top ]

setRendererOptions [line 1667]

void setRendererOptions(
array
$options, [bool
$common = false])

Set multiple renderer options

Access: public

Parameters:

array	`$options`	—	An associative array of the form: array("option_name" => "option_value",...)
bool	`$common`	—	Whether to use these options for all renderers (true) or only for the current one (false)

[ Top ]

setRequestPrefix [line 991]

void setRequestPrefix(
string
$prefix)

Set the global GET/POST variables prefix

If you need to change the request variables, you can define a prefix. This is extra useful when using multiple datagrids.

This method needs to be called before bind().

Access: public

Parameters:

string $prefix — The prefix to use on request variables;

[ Top ]

setUrlFormat [line 1786]

void setUrlFormat(
mixed
$format, [string
$prefix = null], [string
$scriptname = null])

Enable and configure URL mapping

If this is set, it will be parsed instead of GET/POST. This is only supported on PHP5, as it depends on Net_URL_Mapper.

There are three possible placeholders, :pager, :orderBy and :direction. :page or (:orderBy and :direction) can be used alone.

It is possible to use multipe DataGrid instances on one page with different prefixes.

Instead of a format string you might also pass a Net_URL_Mapper instance to this method, in which case $prefix and $scriptname will be ignored. This instance must be properly set up, connected to url patterns, etc... This is especially useful when you've already configured URL mapping globally for your application and want Structures_DataGrid to integrate.

See: http://pear.php.net/Net_URL_Mapper
Throws: Net_URL_Mapper_InvalidException
Access: public
Example: example not found

Parameters:

mixed	`$format`	—	The URL format string or a Net_URL_Mapper instance
string	`$prefix`	—	Sets the url prefix
string	`$scriptname`	—	Set the scriptname if mod_rewrite not available

[ Top ]

sortRecordSet [line 1298]

void sortRecordSet(
array
$sortSpec, [string
$direction = 'ASC'])

Sorts the records by the defined field.

Do not use this method if data is coming from a database as sorting is much faster coming directly from the database itself.

Access: public

Parameters:

array	`$sortSpec`	—	Sorting specification Structure: array(fieldName => direction, ...)
string	`$direction`	—	Deprecated. Put the direction(s) into $sortSpec

[ Top ]

Class: Structures_DataGrid

Class Overview

Author(s):

Variables

Methods

Inherited Variables

Inherited Methods

Class Details

Class Variables

$_urlMapper = null

Method Detail

Structures_DataGrid (Constructor) [line 305]

Parameters:

addColumn [line 1023]

Parameters:

attachRenderer [line 769]

Parameters:

bind [line 1171]

Parameters:

bindDataSource [line 1189]

Parameters:

build [line 1549]

dataSourceFactory [line 437]

Parameters:

dump [line 335]

enableStreaming [line 1717]

Parameters:

fill [line 809]

Parameters:

generateColumns [line 1738]

Parameters:

getColumnByField [line 1124]

Parameters:

getColumnByName [line 1104]

Parameters:

getColumnCount [line 922]

getColumns [line 1080]

getCurrentPage [line 882]

getCurrentRecordNumberEnd [line 969]

getCurrentRecordNumberStart [line 952]

getDataSource [line 646]

getOutput [line 579]

Parameters:

getPageCount [line 907]

getRecordCount [line 933]

getRenderer [line 632]

removeColumn [line 1145]

Parameters:

render [line 517]

Parameters:

setCurrentPage [line 895]

Parameters:

setDataSourceOption [line 1689]

Parameters:

setDataSourceOptions [line 1701]

Parameters:

setDefaultSort [line 1328]

Parameters:

setRenderer [line 667]

Parameters:

setRendererOption [line 1652]

Parameters:

setRendererOptions [line 1667]

Parameters:

setRequestPrefix [line 991]

Parameters:

setUrlFormat [line 1786]

Parameters:

sortRecordSet [line 1298]

Parameters: