Table display options

Table display, or rendering, is controlled by properties in the table's options object and in the columns. Standard properties are covered in Table structure. This section documents additional properties used in the rendering process.

Table option properties

format

The format of the rendered table. Supported values are:

  • table – render as an HTML table. This is the default.
  • list – render each row down the page, possibly in columns.
  • none – render each row down the page, without any surrounding columns.
cssClass

CSS class or classes used to render the table. The default is "maTable datatable-plain", which renders the table using striped rendering, but without sorting and filtering.

The class maTable switches on the datatable component. This is then controlled by additional classes.

stripes Format every other row with a grey background to give a striped appearance.
hover Highlight rows when hovered over.
responsive On small screens, wrap columns under the first cell.
sort Allow user to sort by column.
paginate Show the table as a number of pages.
filter Allow the user to filter the columns by text entry.
colreorder Allow the user to change the order of the columns.
save Save user changes. Switched on automatically when sort, paginate, filter or colreorder are used.
rowreorder Allow the user to change the order of the columns. See the Row reorder component.

There are three standard classes for applying sets of options.

datatable stripes hover paginate filter sort responsive
datatable-nosort stripes hover paginate filter responsive
datatable-plain stripes hover

Options can be switched off using noXXXX, where XXXX is the class. So for example "maTable datatable nosort nopaginate" would use stripes, hover, filter and responsive.

When the maTable class is used with the paginate option, the table will automatically scroll to the page with the row containing the class "selected".

When the maTable class is used with the sort option, the initial sort order can be set by adding the classes sort-asc (for sort ascending) or sort-desc (for sort descending) to one or more columns.

style

CSS style to be added to the table.

rowCSSClass

CSS class or classes to be added to each row.

rowCSSClassColumn

Number or reference of column holding CSS classes to be added to the row.

rowStyle

CSS style to be added to each row.

rowStyleColumn

Number or reference of column holding style to be added to the row. This will be added before the rowStyle, i.e. the rowStyle overrides the style read from the individual rows.

rowHiddenColumn

Number or reference of column which, if a true value, will suppress the output of the row. For example, "rowHiddenColumn":"hidden" will suppress all rows with a propery of hidden. Can be used to create filter-like column scripts.

sortColumn

Number or reference of column holding sort order. The columns should hold a number or text. If omitted, the rows are not sorted before being displayed.

sortDescending

If true, sort descending. Otherwise, sort ascending.

showCaption

Set to true to show table caption (if there is one). Table caption is taken from the table name property. Default is false.

microformat

Whether the table should be output with additional options so that the microformat parser can interpret it. This is used for tables that are output to be read by browser-based scripts, for example for charting. Boolean, default false.

listColumns

When format is list, the number of columns for the listing display. Default is 1.

l10n

A prefix to use to create localization identifiers on the table. The following changes are made.

  • A data-l10n-id atttribute with a value of id-Heading is added to each of the column headers. These can then be translated using pattern matching.

Column properties

In addition to the type, format, decimals and hidden column properties, the render process uses the following column properties:

cssClass

CSS class or classes used to render the column heading.

The class datatable-column-filter will convert the column heading to a drop-down filter field. The class datatable-column-filter-list, which must be used in associated with datatable-column-filter, will assume the items in the fields are comma-delimited lists and create a filter based on this. When using lists, the search is on a partial match, i.e. item "A" will also find "A B".

style

CSS style to be added to the column heading.

fieldCSSClass

CSS class or classes used to render each field in the column, but not the heading.

fieldStyle

CSS style to be added to each field in the column, but not the heading.

html

HTML to use in the column heading. If omitted, the column name is used.

Column properties can be coded in the column themselves, or in the columns property of the table options. Where the same property is coded in both, the properties from the table options object take precedence (table.options.columns[n].x overrides table.columns[n].x).