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

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):

Version:

  • $Revision$

Variables

Methods


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



[ 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.


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.


[ 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.


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:

  1.  function anUnsupportedMethod()
  2.  {
  3.      return $this->_noSupport(__FUNCTION__);
  4.  }

  • 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 ]


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