Structures_DataGrid_Renderer_Smarty

Structures_DataGrid_Renderer_Smarty – Smarty Rendering Driver

Supported operations modes

This driver supports the following operation modes:

Supported operations modes of this driver
Mode Supported?
Container Support yes
Output Buffering yes
Direct Rendering no
Streaming no
Object Preserving yes

Options

This driver accepts the following options:

Options for this driver
Option Type Description Default Value
associative bool By default the column set and the records are numerically indexed arrays. By setting this option to true the keys will be field names instead. false
buildFooter bool Whether to build the footer. true
buildHeader bool Whether to build the header. true
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. array()
convertEntities bool Whether or not to convert html entities. This calls htmlspecialchars(). true
defaultCellValue string What value to put by default into empty cells. null
defaultColumnValues array Per-column default cell value. This is an array of the form: array(fieldName => value, ...). array()
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. 'ISO-8859-1'
excludeVars array Variables to be removed from the generated HTTP queries. array()
extraVars array Variables to be added to the generated HTTP queries. array()
fillWithEmptyRows bool Ensures that all pages have the same number of rows. false
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. array()
numberAlign bool Whether to right-align numeric values. true
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..). null
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... ''
selfPath string The complete path for sorting and paging links. $_SERVER['PHP_SELF']
sortingResetsPaging bool Whether sorting HTTP queries reset paging. true
varPrefix string Prefix for smarty variables and functions assigned by this driver. Can be used in conjunction with Structure_DataGrid::setRequestPrefix() for displaying several grids on a single page. ''

General notes

To use this driver you need the Smarty template engine from http://smarty.php.net

This driver does not support the render() method, it is only able to:

Either fill() a Smarty object by assigning variables and registering the {getPaging} smarty function. It's up to you to call Smarty::display() after the Smarty object has been filled.

Or return all variables as a PHP array from getOutput(), for maximum flexibility, so that you can assign them the way you like to your Smarty instance.

This driver assigns the following Smarty variables: 

- $columnSet:       array of columns specifications
                    structure:
                         array (
                             0 => array (
                                 'name'       => field name,
                                 'label'      => column label,
                                 'link'       => sorting link,
                                 'attributes' => attributes string,
                                 'direction'  => 'ASC', 'DESC' or '',
                                 'onclick'    => onMove call
                             ),
                             ...
                         )
- $recordSet:       array of records values
- $currentPage:     current page (starting from 1)
- $nextPage:        next page
- $previousPage:    previous page
- $recordLimit:     number of rows per page
- $pagesNum:        number of pages
- $columnsNum:      number of columns
- $recordsNum:      number of records in the current page
- $totalRecordsNum: total number of records
- $firstRecord:     first record number (starting from 1)
- $lastRecord:      last record number (starting from 1)
- $currentSort:     array with column names and the directions used for sorting
- $datagrid:        a reference that you can pass to {getPaging}

This driver registers a Smarty custom function named getPaging that can be called from Smarty templates with {getPaging} in order to print paging links. This function accepts the same parameters as the pagerOptions option of Structures_DataGrid_Renderer_Pager.

{getPaging} accepts an optional "datagrid" parameter which you can pass the $datagrid variable, to display paging for an arbitrary datagrid (useful with multiple dynamic datagrids on a single page).

Object Records : this drivers preserves object records if provided. This means that if your datasource provides objects instead of associative arrays as records, you can access their properties and methods in your smarty template, with something like: {$recordSet[col]->getSomeInformation()}.

Examples

Using the Smarty renderer

<?php
require_once 'Structures/DataGrid.php';    
require_once 'Smarty.class.php';

$datagrid =& new Structures_DataGrid(10);
$options = array('dsn' => 'mysql://username@localhost/mydatabase');
$datagrid->bind("SELECT * FROM mytable", $options);

$smarty = new Smarty();
$datagrid->fill($smarty);
$smarty->display('smarty-simple.tpl');
?>

Smarty template with sorting and paging (smarty-simple.tpl)

<?php
<!-- Show paging links using the custom getPaging function -->
{getPaging prevImg="<<" nextImg=">>" separator=" | " delta="5"}

<p>Showing records {$firstRecord} to {$lastRecord} 
from {$totalRecordsNum}, page {$currentPage} of {$pagesNum}</p>

<table cellspacing="0">
    <!-- Build header -->
    <tr>
        {section name=col loop=$columnSet}
            <th {$columnSet[col].attributes}>
                <!-- Check if the column is sortable -->
                {if $columnSet[col].link != ""}
                    <a href="{$columnSet[col].link}">{$columnSet[col].label}</a>
                    <!-- Show the current ordering with an arrow -->
                    {if $columnSet[col].direction == "ASC"}
                      &darr;
                    {elseif $columnSet[col].direction == "DESC"}
                      &uarr;
                    {/if}
                {else}
                    {$columnSet[col].label}
                {/if}
            </th>
        {/section}
    </tr>
    
    <!-- Build body -->
    {section name=row loop=$recordSet}
        <tr {if $smarty.section.row.iteration is even}bgcolor="#EEEEEE"{/if}>
            {section name=col loop=$recordSet[row]}
                <td {$columnSet[col].attributes}>{$recordSet[row][col]}</td>
            {/section}
        </tr>
    {/section}
</table>
?>
Pager rendering driver (Previous) Excel Spreadsheet Rendering Driver (Next)
Last updated: Sat, 16 Feb 2019 — Download Documentation
Do you think that something on this page is wrong? Please file a bug report.
View this page in:
  • English

User Notes:

Note by: rex_schrader
2010-11-14 21:39 UTC
Note that the Structures_DataGrid::setRequestPrefix() function does not control output variable names if you use the Structures_DataGrid::fill() function. Instead, you must pass in 'varPrefix' as a renderer option.

Example:
$smarty = new Smarty();
$datagrid->fill($smarty, array('varPrefix' => 'myPrefix_'));
$smarty->display('smarty-simple.tpl');