Table structure

Tables are represented using JavaScript Object Notation (JSON), with the following simple structure.

A table is an object
A table contains an array of columns called "columns".
A table contains an array of rows called "rows".
Each column and each row is an object.

{
  "columns":[
    column1,
    column2,
    ...
  ],
  "rows":[
    row1,
    row2,
    row3,
    row4,
    row5,
    ...
  ]
}

A table may also contain the following properties:

reference	Reference for the table. Can be any string.
name	A name for the table. XML entities should not be escaped.
description	A description of the table, containing HTML markup if necessary.
options	An object containing table processing options. In particular, this can contain Table display options which control the appearance of the table.

Columns

The column objects support the following properties. Columns may contain other properties, for example Table display options.

reference	A reference for the column. This can be any string. Where columns represent member types, this should be the node reference of the member type (not the node version reference). The reference defaults to the column's 0-based position in the columns array. All processes that read tables should implement this default, for example using the following code: for ( var j in table.columns ) { if ( table.columns[j].reference === undefined ) { table.columns[j].reference = j; } } Where numbers are used for column references, processes should not presume that they relate to the position in the columns array.
name	The name of the column. XML entities should not be escaped.
description	A description of the column, containing HTML markup if necessary.
type	The data type of the fields within the column. See section on data types below. Defaults to text.
format	Provides additional information about how the fields should be formatted and processed. For columns of type text: html - the text is valid html markup - the text may contain html markup, but has not been validated and formatted. This is the default for text fields. line - the text contains a single line, no html markup. text - the text may contain multiple lines, but no html markup.
decimals	For columns of type number, or which include number fields, the number of decimals places to display.
hidden	Set to true to hide the column from display. This suppresses the output of the column completely; it does not just show it and then hide it using CSS.

Data types

Tables support the following data types.

text	The field contains a single string which may contain multiple lines.
number	The field contains a single number.
reference	The field contains a node reference or node version reference.
boolean	The field contains a boolean value.
date	The field contains a date in format yyyy-mm-dd
timestamp	The field contains a timestamp in format yyyy-mm-ddThh:mm:ss, plus optional fractional seconds.
link	The field contains an object with two properties: reference - a node reference or node version reference name - a node name
object	The field contains an unspecified object (or array).
table	A table object, which conforms to this standard for a table structure.
[a][o][t][n][l]	This is a recipe for specifying a type with multiple parts or repeats. It is used to faithfully reproduce node data. The parts mean: a - array o - object t - text n - number l - link (which is an object containing reference and name) The single values t, n and l are not used: text, number and link are used in their place. All valid combinations are listed below.
otn	The field contains an object with a text and a number property.
otl	The field contains an object with a text property and a link property, which is an object with a reference and a name property.
onl	The field contains an object with a number property and a link property.
otnl	The field contains an object with a text property, a number property and a link property.
at	The field contains an array of text strings.
an	The field contains an array of numbers.
al	The field contains an array of link objects.
aotn	The field contains an array of objects, each one of which contains a text property and a number property.
aotl	The field contains an array of objects, each one of which contains a text property and a link property.
aonl	The field contains an array of objects, each one of which contains a number property and a link property.
aotnl	The field contains an array of objects, each one of which contains a text property, a number property and a link property.

Rows

Each row is an object containing multiple properties. The property names correspond to the values of the reference properties on the columns.

The types of the properties correspond to the types defined on the columns.

Properties may be missing. The values undefined and null are equivalent to missing.

Properties the names of which do not correspond to values of reference properties of columns are permitted, but may be ignored or removed by table processing.

Options

Tables support the following options. Other options may be used by other processes, for example Table display options.

columns

Provides overrides for columns properties. These can be useful for adding properties to columns without modifying the columns themselves. This can be either:

An array of objects in which columns are identified by position.
```
options:
  columns:[
    {
      "fieldCSSClass": "danger"
    },
    {
    },
    {
      "fieldStyle": "font-size:1.2em;"
    }
  ]
}
```
This means 'set the fieldCSSClass property of the first column to "danger", and the fieldStyle property of the third column to "font-size:1.2em;"'. The second column has to be specified.
An objects in which columns are identified by reference.
```
options:
  columns:{
    "errmsg":{
      "fieldCSSClass": "danger"
    },
    "actions":{
      "fieldStyle": "font-size:1.2em;"
    }
  }
}
```
This means 'set the fieldCSSClass property of the column with reference "errmsg" to "danger", and the fieldStyle property of the column with reference "actions" to "font-size:1.2em;"'.

Example table

{
    "name": "Pets",
    "description": "List of my pets",
    "columns": [
        {
            "reference": "reference",
            "name": "Reference",
            "type": "text"
        },
        {
            "reference": "name",
            "name": "Name",
            "type": "text"
        },
        {
            "reference": "metrici.products.pets.library.SpeciesName",
            "name": "Species",
            "type": "text"
        },
        {
            "reference": "metrici.products.pets.library.DateOfBirth",
            "name": "Date of Birth",
            "type": "date"
        }
    ],
    "rows": [
        {
            "reference": "metrici.samples.pets.Fido.1",
            "name": "Fido",
            "metrici.products.pets.library.SpeciesName": "Dog",
            "metrici.products.pets.library.DateOfBirth": "2010-01-14"
        },
        {
            "reference": "metrici.samples.pets.Pet3.1",
            "metrici.products.pets.library.SpeciesName": "Sea Monkey"
        },
        {
            "reference": "metrici.samples.pets.Jaws.1",
            "name": "Jaws",
            "metrici.products.pets.library.SpeciesName": "Goldfish",
            "metrici.products.pets.library.DateOfBirth": "2007-07-01"
        }
    ]
}

Secondary format

Because the column reference defaults to the position of the column within the columns array, it is possible to omit column references and to use arrays in place of objects for the rows. This is known as the secondary format. The table below will be interpreted the same as the earlier example, except that there will be no meaningful column references:

{
    "name": "Pets",
    "description": "List of my pets",
    "columns": [
        {
            "name": "Reference"
        },
        {
            "name": "Name"
        },
        {
            "name": "Species"
        },
        {
            "name": "Date of Birth",
            "type": "date"
        }
    ],
    "rows": [
        [
            "metrici.samples.pets.Fido.1",
            "Fido",
            "Dog",
            "2010-01-14"
        ],
        [
            "metrici.samples.pets.Pet3.1",
            null,
            "Sea Monkey"
        ],
        [
            "metrici.samples.pets.Jaws.1",
            "Jaws",
            "Goldfish",
            "2007-07-01"
        ]
    ]
}

This secondary format may be used where convenient and where column references are not significant, for example when writing out data for the charting functions.

The processing for table modification is different in the secondary format, and the primary (object based ) and secondary (array based) formats should not be mixed in the same table. Processes that modify tables should take care to ensure processing is applied correctly, and that the output tables are valid in one format or the other.