Structures_DataGrid
[ class tree: Structures_DataGrid ] [ index: Structures_DataGrid ] [ all elements ]

Class: Structures_DataGrid

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

Class Overview


Structures_DataGrid Class


Author(s):

Variables

Methods


Inherited Variables

Inherited Methods


Class Details

[line 110]
Structures_DataGrid Class

A PHP class to implement the functionality provided by the .NET Framework's DataGrid control. This class can produce a data driven list in many formats based on a defined record set. Commonly, this is used for outputting an HTML table based on a record set from a database or an XML document. It allows for the output to be published in many ways, including an HTML table, an HTML Template, an Excel spreadsheet, an XML document. The data can be sorted and paged, each cell can have custom output, and the table can be custom designed with alternating color rows.

Quick Example:

  1.  <?php
  2.  require 'Structures/DataGrid.php';
  3.  $datagrid = new Structures_DataGrid();
  4.  $options = array('dsn' => 'mysql://user:password@host/db_name');
  5.  $datagrid->bind("SELECT * FROM my_table"$options);
  6.  $datagrid->render();
  7.  ?>



[ Top ]


Class Variables

$_urlMapper =  null

[line 283]

URL mapper instance, if activated
  • Access: protected

Type:   object Net_URL_Mapper


[ Top ]



Method Detail

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

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:

  1.  $driver Structures_DataGrid::dataSourceFactory($source);

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

  1.  $driver Structures_DataGrid::dataSourceFactory($source$options);

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

  1.  $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.


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.


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 ]


Documentation generated on Fri, 27 Jan 2012 13:30:07 +0000 by phpDocumentor 1.4.3. PEAR Logo Copyright © PHP Group 2004.