DataTable API Reference

This page explains the GoogleVisualr::DataTable class, constructor, and methods.

A GoogleVisualr::DataTable object, as its name suggests, is a 2D mutable table of values that is used to generate Google charts.

Constructors

GoogleVisualr::DataTable have two constructors.

  # Creates an empty data_table instance
  data_table = GoogleVisualr::DataTable.new

  # Creates a populated data_table instance
  data_table = GoogleVisualr::DataTable.new(data)

GoogleVisualr::DataTable.new

Creates an empty data_table instance. Use new_column/s, add_row/s and set_cell methods to populate the data_table.

GoogleVisualr::DataTable.new(data_object)

Creates a data_table by passing a JavaScript-string-literal like data object into the data parameter. This object can contain formatting options.


Syntax Description of a Data Object

The data object consists of two required top-level properties, cols and rows.

cols property

cols is an array of objects describing the ID and type of each column. Each property is an object with the following properties (case-sensitive):

  • type [Required] The data type of the data in the column. Supports the following string values:
    • 'string' - String value. Example values: v:'foo', :v:'bar'
    • 'number' - Number value. Example values: v:7, v:3.14, v:-55
    • 'boolean' - Boolean value ('true' or 'false'). Example values: v:true, v:false
    • 'date' - Date object, with the time truncated. Example value: v:Date.parse('2010-01-01')
    • 'datetime' - DateTime/Time object, time inclusive. Example value: v:DateTime.parse('2010-01-01 14:20:25')
    • 'timeofday' - Array of 3 numbers or 4 numbers, [Hour,Minute,Second,(Optional) Milliseconds]. Example value: v:[8, 15, 0]
  • label [Optional] A string value that some charts display for this column. Example: label:'Height'
  • id [Optional] A unique (basic alphanumeric) string ID of the column. Be careful not to choose a JavaScript keyword. Example: id:'col_1'
  • role [Optional] A string value that describes the purpose of the data in that column. Example, a column might hold data describing tooltip text, data point annotations, or uncertainty indicators. See Roles (Experimental) on usage example.
  • pattern [Optional] A number (or date) format string specifying how to display the column value; used in conjunction with role.
rows property

The rows property holds an array of row objects. Each row object has one required property called c, which is an array of cells in that row.

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

  • v [Optional] The cell value. The data type should match the column data type.
  • f [Optional] A string version of the v value, formatted strictly for display only. 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. 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 either specify "null", or set empty string for a cell in an array, or omit trailing array members. So, to indicate a row with null for the first two cells, you could specify [ '', '', {cell_val} ] or [ null, null, {cell_val} ].

Example

Let's attempt to recreate this chart. Look at the code below!



Code

In your controller, create the data_table object, set new columns, add row values, then instantiate the chart with configuration options.

  data_table  = GoogleVisualr::DataTable.new(
    {
      :cols =>  [
        { :id => 'A', :label => 'NEW A'  , :type => 'string' },
        { :id => 'B', :label => 'B-label', :type => 'number' },
        { :id => 'C', :label => 'C-label', :type => 'date'   }
      ],
      :rows =>  [
        { :c => [ {:v => 'a'}, {:v => 1.0, :f => 'One'}  , {:v => Date.parse('2008-02-28 00:31:26'), :f => '2/28/08 12:31 AM'} ] },
        { :c => [ {:v => 'b'}, {:v => 2.0, :f => 'Two'}  , {:v => Date.parse('2008-03-30 00:31:26'), :f => '3/30/08 12:31 AM'} ] },
        { :c => [ {:v => 'c'}, {:v => 3.0, :f => 'Three'}, {:v => Date.parse('2008-04-30 00:31:26'), :f => '4/30/08 12:31 AM'} ] }
      ]
    }
  )

  opts    = { :width => 600, :allowHtml => true, :showRowNumber => true }
  @chart  = GoogleVisualr::Interactive::Table.new(data_table, opts)

In your view, use the render_chart method to generate JavaScript, during rendering of the view.

  <div id='chart'></div>
  <%= render_chart @chart, 'chart' %>

Methods

Note: The methods listed here are not exhaustive, and may not be updated timely. Please also refer to the (documented) source for more details.


new_column(type [,label [,id] [,role] [,pattern]])

Adds a new column to the data_table.

Parameters
  • type [Required] The data type of the data in the column. Supports the following string values:
    • 'string' - String value. Example values: v:'foo', :v:'bar'
    • 'number' - Number value. Example values: v:7, v:3.14, v:-55
    • 'boolean' - Boolean value ('true' or 'false'). Example values: v:true, v:false
    • 'date' - Date object, with the time truncated. Example value: v:Date.parse('2010-01-01')
    • 'datetime' - DateTime/Time object, time inclusive. Example value: v:DateTime.parse('2010-01-01 14:20:25')
    • 'timeofday' - Array of 3 numbers or 4 numbers, [Hour,Minute,Second,(Optional) Milliseconds]. Example value: v:[8, 15, 0]
  • label [Optional] A string value that some charts display for this column. Example: label:'Height'
  • id [Optional] A unique (basic alphanumeric) string ID of the column. Be careful not to choose a JavaScript keyword. Example: id:'col_1'
  • role [Optional] A string value that describes the purpose of the data in that column. Example, a column might hold data describing tooltip text, data point annotations, or uncertainty indicators. See Roles (Experimental) on usage example.
  • pattern [Optional] A number (or date) format string specifying how to display the column value; used in conjunction with role.

  # Adds a column with data type and label
  data_table.new_column('string', 'Name')


new_columns(columns)

Adds multiple columns to the data_table.

Parameters
  • columns [Required] An array of column objects {:type, :label, :id, :role, :pattern}. Calls new_column for each column object.

  # Adds 2 columns with data type and label
  data_table.new_columns( [ { :type => 'string', :label => 'Name' }, { :type => 'number', :label => 'Age' }  ] )


add_row(row)

Adds a new row to the data_table. Call method without any parameters to add an empty row, otherwise, call method with a row object.

Parameters
  • row [Optional] An array of cell values specifying the data for the new row.
    • You can specify a value for a cell (e.g. 'hi') or specify a formatted value using cell objects (e.g. {v:55, f:'Fifty-five'}) as described in the constructor section.
    • You can mix simple values and cell objects in the same method call.
    • To create an empty cell, use nil or empty string.

  # Adds an empty row
  data_table.add_row()

  # Adds a row with a string and a date value
  data_table.add_row( [ 'Hermione', Date.parse('1999-01-01') ] )

  # Adds a row with two cells; second cell with a formatted value
  data_table.add_row( [ 'Hermione', {v: Date.parse('1999-01-01'), f: 'January First, Nineteen ninety-nine'} ] )

  data_table.add_row( [ 'Col1Val', nil, 'Col3Val' ] ) # 2nd column is empty
  data_table.add_row( [ 'Col1Val', '' , 'Col3Val' ] ) # 2nd column is empty


add_rows(array_or_num)

Adds multiple rows to the data_table. You can call this method with data to populate a set of new rows or create new empty rows.

Parameters
  • array_or_num [Required] Either an array or a number.
    • Array: An array of row objects used to populate a set of new rows. Each row is an object as described in add_row().
    • Number: A number specifying the number of new empty rows to create.

  # Adds 2 rows
  data_table.add_rows([
    ['John', 18],
    ['Jill', 22]
  ])

  # Adds 5 empty rows
  data_table.add_rows(5)


set_cell(row_index, column_index, value)

Sets the value (and formatted value) of a cell.

Parameters
  • row_index [Required] A number greater than or equal to zero, but smaller than the total number of rows.
  • column_index [Required] A number greater than or equal to zero, but smaller than the total number of columns.
  • value [Required] The cell value.
    • The data type should match the column data type.
    • Specify a value for a cell (e.g. 'hi').
    • Or specify a formatted value using cell objects (e.g. {v:55, f:'Fifty-five'}).

  # Sets a cell without a formatted value
  data_table.set_cell(0, 0, 'John')

  # Sets a cell with a formatted value
  data_table.set_cell(0, 1, {:v => 18, :f => '18 years old'})


format(formatter [, formatter]*)

Applies one or more formatters to the data_table to format the columns as specified by the formatter/s.

Parameters
  • formatter/s [Required] One, or an array of formatters.

  # Passes in 1 formatter
  data_table.format(formatter)

  # Passes in 3 formatters
  data_table.format(formatter_1, formatter_2, formatter_2)