class DataTable implements JsonSerializable (View source)

The DataTable object is used to hold the data passed into a visualization.

A DataTable is a basic two-dimensional table. All data in each column must have the same data type. Each column has a descriptor that includes its data type, a label for that column (which might be displayed by a visualization), and an ID, which can be used to refer to a specific column (as an alternative to using column indexes). The DataTable object also supports a map of arbitrary properties assigned to a specific value, a row, a column, or the whole DataTable. Visualizations can use these to support additional features; for example, the Table visualization uses custom properties to let you assign arbitrary class names or styles to individual cells.

Constants

VERSION

Google's datatable version

VIZ_CLASS

Google's visualization class name.

Methods

__construct( string $timezone = null)

Creates a new DataTable

static  Cell
cell( mixed $v, string $f = '', array $p = array())

Create a new DataCell for a value in a Row

static  DataTable
createFromJson( string $jsonString)

Parses a string of JSON data into a DataTable.

setTimezone( string $timezone)

Sets the Timezone that Carbon will use when parsing dates This will use the passed timezone, falling back to the default from php.ini, and falling back from that to America/Los_Angeles

getTimeZone()

Returns the current timezone used in the DataTable

setDateTimeFormat( string $dateTimeFormat)

Sets the format to be used by Carbon::createFromFormat()

string
getDateTimeFormat()

Returns the set DateTime format.

DataTable;
bare()

Returns a bare clone of the DataTable.

addColumn( mixed $typeOrColDescArr, string $label = '', Format $format = null, string $role = '')

Adds a column to the DataTable

addColumns( array $arrayOfColumns)

Adds multiple columns to the DataTable

addBooleanColumn( string $label = '', Format $format = null, string $role = '')

Supplemental function to add a boolean column with less params.

addStringColumn( string $label = '', Format $format = null, string $role = '')

Supplemental function to add a string column with less params.

addDateColumn( string $label = '', Format $format = null, string $role = '')

Supplemental function to add a date column with less params.

addDateTimeColumn( string $label = '', Format $format = null, string $role = '')

Supplemental function to add a datetime column with less params.

addTimeOfDayColumn( string $label = '', Format $format = null, string $role = '')

Supplemental function to add a timeofday column with less params.

addNumberColumn( string $label = '', Format $format = null, string $role = '')

Supplemental function to add a number column with less params.

addRoleColumn( string $type, string $role)

Adds a new column for defining a data role.

dropColumn( int $colIndex)

Drops a column and its data from the DataTable

formatColumn( integer $index, Format $format)

Sets the format of the column.

formatColumns( array $colFormatArr)

Sets the format of multiple columns.

addRow( array $cellArray = array())

Add a row to the DataTable

addRows( array $arrayOfRows)

Adds multiple rows to the DataTable.

array
getRows()

Returns the rows array from the DataTable

int
getRowCount()

Returns the number of rows in the DataTable

getColumn( int $index)

Returns a column based on it's index.

array
getColumns()

Returns the column array from the DataTable

array
getColumnsByType( string $type)

Returns the columns whos type match the given value.

int
getColumnCount()

Returns the number of columns in the DataTable

string
getColumnLabel( integer $index)

Returns the label of a column based on it's index.

string
getColumnType( integer $index)

Returns the type of a column based on it's index.

array
getColumnTypes()

Returns the types of columns currently defined.

array
getColumnLabels()

Returns the labels of columns currently defined.

array
getFormattedColumns()

Returns the column array from the DataTable

bool
hasFormattedColumns()

Boolean value if there are any formatted columns

string
toJson()

Convert the DataTable to JSON

array
jsonSerialize()

Custom serialization of the DataTable.

Details

at line 89
__construct( string $timezone = null)

Creates a new DataTable

Parameters

string $timezone

at line 126
static Cell cell( mixed $v, string $f = '', array $p = array())

Create a new DataCell for a value in a Row

v: The cell value. The data type should match the column data type. If null, the whole object should be empty and have neither v nor f properties.

f: [Optional] A string version of the v value, formatted for display. The values should match, so if you specify Date(2008, 0, 1) for v, you should specify "January 1, 2008" or some such string for this property. This value is not checked against the v value. The visualization will not use this value for calculation, only as a label for display. If omitted, a string version of v will be used.

p: [Optional] An object that is a map of custom values applied to the cell. These values can be of any JavaScript type. If your visualization supports any cell-level properties, it will describe them; otherwise, this property will be ignored. Example: p:{style: 'border: 1px solid green;'}.

Parameters

mixed $v Value of the Cell
string $f Formatted version of the cell, as a string
array $p Cell specific customization options

Return Value

Cell

at line 146
static DataTable createFromJson( string $jsonString)

Parses a string of JSON data into a DataTable.

Most google examples can be passed to this method with some tweaks. PHP requires that only double quotes are used on identifiers. For example: - {label: 'Team'} would be invalid - {"label": "Team"} would be accepted.

Parameters

string $jsonString JSON string to decode

Return Value

DataTable

Exceptions

InvalidJson

at line 183
DataTable setTimezone( string $timezone)

Sets the Timezone that Carbon will use when parsing dates This will use the passed timezone, falling back to the default from php.ini, and falling back from that to America/Los_Angeles

Parameters

string $timezone

Return Value

DataTable

Exceptions

InvalidTimeZone

at line 205
DateTimeZone getTimeZone()

Returns the current timezone used in the DataTable

Return Value

DateTimeZone

at line 222
DataTable setDateTimeFormat( string $dateTimeFormat)

Sets the format to be used by Carbon::createFromFormat()

This method is used to set the format to be used to parse a string passed to a cell in a date column, that was parsed incorrectly by Carbon::parse()

Parameters

string $dateTimeFormat

Return Value

DataTable

Exceptions

InvalidConfigValue

at line 243
string getDateTimeFormat()

Returns the set DateTime format.

Return Value

string DateTime format

at line 259
DataTable; bare()

Returns a bare clone of the DataTable.

This method clone the DataTable and strip the rows off. Useful when loading charts via ajax, and you need the initial DataTable structure to pre-load the chart's format.

Return Value

DataTable;

at line 291
DataTable addColumn( mixed $typeOrColDescArr, string $label = '', Format $format = null, string $role = '')

Adds a column to the DataTable

First signature has the following parameters: type - A string with the data type of the values of the column. The type can be one of the following: 'string' 'number' 'bool' 'date' 'datetime' 'timeofday'.

columnLabel - [Optional] A string with the label of the column. The column label is typically displayed as part of the visualization, for example as a column header in a table, or as a legend label in a pie chart. If not value is specified, an empty string is assigned. optId - [Optional] A string with a unique identifier for the column. If not value is specified, an empty string is assigned.

Parameters

mixed $typeOrColDescArr Column type or an array describing the column.
string $label A label for the column. (Optional)
Format $format A column format object. (Optional)
string $role A role for the column. (Optional)

Return Value

DataTable

Exceptions

InvalidConfigValue
InvalidConfigProperty

at line 315
DataTable addColumns( array $arrayOfColumns)

Adds multiple columns to the DataTable

Parameters

array $arrayOfColumns Array of columns to batch add to the DataTable.

Return Value

DataTable

Exceptions

InvalidConfigValue

at line 344
DataTable addBooleanColumn( string $label = '', Format $format = null, string $role = '')

Supplemental function to add a boolean column with less params.

Parameters

string $label A label for the column.
Format $format A column format object. (Optional)
string $role A role for the column. (Optional)

Return Value

DataTable

Exceptions

InvalidLabel
InvalidColumnType

at line 360
DataTable addStringColumn( string $label = '', Format $format = null, string $role = '')

Supplemental function to add a string column with less params.

Parameters

string $label A label for the column.
Format $format A column format object. (Optional)
string $role A role for the column. (Optional)

Return Value

DataTable

Exceptions

InvalidLabel
InvalidColumnType

at line 376
DataTable addDateColumn( string $label = '', Format $format = null, string $role = '')

Supplemental function to add a date column with less params.

Parameters

string $label A label for the column.
Format $format A column format object. (Optional)
string $role A role for the column. (Optional)

Return Value

DataTable

Exceptions

InvalidLabel
InvalidColumnType

at line 393
DataTable addDateTimeColumn( string $label = '', Format $format = null, string $role = '')

Supplemental function to add a datetime column with less params.

Parameters

string $label A label for the column.
Format $format A column format object. (Optional)
string $role A role for the column. (Optional)

Return Value

DataTable

Exceptions

InvalidLabel
InvalidColumnType

at line 410
DataTable addTimeOfDayColumn( string $label = '', Format $format = null, string $role = '')

Supplemental function to add a timeofday column with less params.

Parameters

string $label A label for the column.
Format $format A column format object. (Optional)
string $role A role for the column. (Optional)

Return Value

DataTable

Exceptions

InvalidLabel
InvalidColumnType

at line 426
DataTable addNumberColumn( string $label = '', Format $format = null, string $role = '')

Supplemental function to add a number column with less params.

Parameters

string $label A label for the column.
Format $format A column format object. (Optional)
string $role A role for the column. (Optional)

Return Value

DataTable

Exceptions

InvalidLabel
InvalidColumnType

at line 442
DataTable addRoleColumn( string $type, string $role)

Adds a new column for defining a data role.

Parameters

string $type Type of data the column will define.
string $role Type of role that the data will represent.

Return Value

DataTable

Exceptions

InvalidColumnType
InvalidColumnRole

at line 473
DataTable dropColumn( int $colIndex)

Drops a column and its data from the DataTable

Parameters

int $colIndex

Return Value

DataTable

Exceptions

InvalidColumnIndex

at line 495
DataTable formatColumn( integer $index, Format $format)

Sets the format of the column.

Parameters

integer $index
Format $format

Return Value

DataTable

Exceptions

InvalidColumnIndex

at line 512
DataTable formatColumns( array $colFormatArr)

Sets the format of multiple columns.

Parameters

array $colFormatArr

Return Value

DataTable

Exceptions

InvalidConfigValue

at line 561
DataTable addRow( array $cellArray = array())

Add a row to the DataTable

Each cell in the table is described by an array with the following properties:

v [Optional] The cell value. The data type should match the column data type. If null, the whole object should be empty and have neither v nor f properties.

f [Optional] A string version of the v value, formatted for display. The values should match, so if you specify Date(2008, 0, 1) for v, you should specify "January 1, 2008" or some such string for this property. This value is not checked against the v value. The visualization will not use this value for calculation, only as a label for display. If omitted, a string version of v will be used.

p [Optional] An object that is a map of custom values applied to the cell. These values can be of any JavaScript type. If your visualization supports any cell-level properties, it will describe them; otherwise, this property will be ignored. Example: p:{style: 'border: 1px solid green;'}.

Cells in the row array should be in the same order as their column descriptions in cols. To indicate a null cell, you can specify null. To indicate a row with null for the first two cells, you would specify [null, null, {cell_val}].

Parameters

array $cellArray Array of values or DataCells.

Return Value

DataTable

Exceptions

InvalidRowDefinition
InvalidRowProperty
InvalidCellCount

at line 592
DataTable addRows( array $arrayOfRows)

Adds multiple rows to the DataTable.

Parameters

array $arrayOfRows

Return Value

DataTable

Exceptions

InvalidConfigValue
InvalidRowDefinition

See also

addRow()

at line 614
array getRows()

Returns the rows array from the DataTable

Return Value

array

at line 625
int getRowCount()

Returns the number of rows in the DataTable

Return Value

int

at line 639
Column getColumn( int $index)

Returns a column based on it's index.

Parameters

int $index

Return Value

Column

Exceptions

InvalidColumnIndex

at line 652
array getColumns()

Returns the column array from the DataTable

Return Value

array

at line 666
array getColumnsByType( string $type)

Returns the columns whos type match the given value.

Parameters

string $type

Return Value

array

Exceptions

InvalidColumnType

at line 689
int getColumnCount()

Returns the number of columns in the DataTable

Return Value

int

at line 703
string getColumnLabel( integer $index)

Returns the label of a column based on it's index.

Parameters

integer $index

Return Value

string

Exceptions

InvalidColumnIndex

at line 717
string getColumnType( integer $index)

Returns the type of a column based on it's index.

Parameters

integer $index

Return Value

string

Exceptions

InvalidColumnIndex

at line 729
array getColumnTypes()

Returns the types of columns currently defined.

Return Value

array

at line 745
array getColumnLabels()

Returns the labels of columns currently defined.

Return Value

array

at line 761
array getFormattedColumns()

Returns the column array from the DataTable

Return Value

array

at line 780
bool hasFormattedColumns()

Boolean value if there are any formatted columns

Return Value

bool

at line 792
string toJson()

Convert the DataTable to JSON

Return Value

string JSON representation of the DataTable.

at line 821
array jsonSerialize()

Custom serialization of the DataTable.

Return Value

array