Structures_DataGrid_Renderer_XLS – Excel Spreadsheet 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 no
Direct Rendering not really, see below
Streaming no
Object Preserving no


This driver accepts the following options:

Options for this driver
Option Type Description Default Value
bodyFormat mixed The format for body cells (either 0 [= "no format"] or a Spreadsheet_Excel_Writer_Format object) Please see the NOTE ABOUT FORMATTING below. 0
border int Border drawn around the whole datagrid: 0 => none, 1 => thin, 2 => thick (NOT IMPLEMENTED YET) 0
buildFooter bool Whether to build the footer. true
buildHeader bool Whether to build the header. 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()
filename string The filename of the spreadsheet 'spreadsheet.xls'
fillWithEmptyRows bool Ensures that all pages have the same number of rows. false
headerBorder int Border between the header and body: 0 => none, 1 => thin, 2 => thick (NOT IMPLEMENTED YET) 0
headerFormat mixed The format for header cells (either 0 [= "no format"] or a Spreadsheet_Excel_Writer_Format object) Please see the NOTE ABOUT FORMATTING below. 0
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
sendToBrowser bool Should the spreadsheet be send to the browser? (true = send to browser, false = write to a file) true
startCol int The Worksheet column number to start rendering at 0
startRow int The Worksheet row number to start rendering at 0
tempDir string A temporary directory to be used by Spreadsheet_Excel_Writer (cp. "General Notes" section). null
version int If you don't pass a worksheet object to this renderer, you can set the BIFF version with this option. The only accepted value by Spreadsheet_Excel_Writer is 8 (for usage of the BIFF8 format). All other values will lead to the older format (which is needed if you get errors in Excel, e.g. about a broken file). 8
worksheet object Optional reference to a Spreadsheet_Excel_Writer_Worksheet object. You can leave this to null except if your workbook contains several worksheets and you want to fill a specific one. null

General notes

This driver does not support the flatten() method. You can not retrieve its output with DataGrid::getOutput(). You can either render it directly to the browser or save it to a file. See the "sendToBrowser" and "filename" options.

This driver has container support. You can use Structures_DataGrid::fill() with it; that's even recommended.

If PHP's safe_mode is enabled, Spreadsheet_Excel_Writer sometimes fails to generate the Excel file. You can avoid this problem by setting the 'tempDir' option to a (temporary) directory that is writable by PHP.


You can specify some formatting with the 'headerFormat' and 'bodyFormat' options, or with setBodyFormat() and setHeaderFormat().

But beware of the following from the Spreadsheet_Excel_Writer manual: "Formats can't be created directly by a new call. You have to create a format using the addFormat() method from a Workbook, which associates your Format with this Workbook (you can't use the Format with another Workbook)."

What this means is that if you want to pass a format to this driver you have to "derive" the Format object out of the workbook used in the driver.

The easiest way to do this is:

// Create a workbook
$workbook = new Spreadsheet_Excel_Writer();

// Specify that spreadsheet must be sent the browser

// Create your format
$format_bold =& $workbook->addFormat();

// Fill the workbook, passing the format as an option
$options = array('headerFormat' => &$format_bold);
$datagrid->fill($workbook, $options);
Smarty Rendering Driver (Previous) XML 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:

There are no user contributed notes for this page.