HexagonJS
Edit Page
Data Table
Tables for displaying data with sorting, filtering, selection and pagination.
Examples

Simple Example

HTML

<h4>Simple Example</h4>
<div id="example"></div>

JavaScript

var table = new hx.DataTable('#example')
table.feed(hx.dataTable.objectFeed({
  headers: [
    {name: 'Name', id: 'name'},
    {name: 'Age', id: 'age'},
    {name: 'Profession', id: 'profession'}
  ],
  rows: [
    {
      id: 0, // hidden details can go here (not in the cells object)
      cells: {'name': 'Bob', 'age': 25, 'profession': 'Developer'}
    },
    {
      id: 1,
      cells: {'name': 'Jan', 'age': 41, 'profession': 'Artist'}
    },
    {
      id: 2,
      cells: {'name': 'Dan', 'age': 41, 'profession': 'Builder'}
    }
  ]
}))

Lazy Example

HTML

<h4>Lazy Example</h4>
<div id="lazy-example"></div>

JavaScript

var finalSize = undefined
var backendRows = [
  {
    id: 0, // hidden details can go here (not in the cells object)
    cells: {'name': 'Bob', 'age': 25, 'profession': 'Developer'}
  },
  {
    id: 1,
    cells: {'name': 'Jan', 'age': 41, 'profession': 'Artist'}
  },
  {
    id: 2,
    cells: {'name': 'Dan', 'age': 41, 'profession': 'Builder'}
  }
]

new hx.DataTable('#lazy-example', {
  pageSize: 2,
  pageSizeOptions: [1, 2, 3, 10],
  filterEnabled: false,
  feed: {
    headers: function (cb) {
      return cb([
        {name: 'Name', id: 'name'},
        {name: 'Age', id: 'age'},
        {name: 'Profession', id: 'profession'}
      ])
    },
    rows: function (range, cb) {
      return cb({
        rows: backendRows.slice(range.start, range.end + 1),
        filteredCount: (finalSize !== undefined || range.end >= 2) ? finalSize = 3 : undefined
      })
    },
    totalCount: function (cb) {
      return cb(undefined)
    }
  }
}).render()

Advanced Search Example

HTML

<h4>Advanced Search Example</h4>
<div id="advanced-search-example-container"></div>

JavaScript

var tableFeed = hx.dataTable.objectFeed({
  headers: [
    { name: 'Name', id: 'name' },
    { name: 'Age', id: 'age' },
    { name: 'Profession', id: 'profession' }
  ],
  rows: [
    {
      id: 0,
      cells: { 'name': 'Bob', 'age': 25, 'profession': 'Developer' }
    },
    {
      id: 1,
      cells: { 'name': 'Jan', 'age': 41, 'profession': 'Artist' }
    },
    {
      id: 2,
      cells: { 'name': 'Dan', 'age': 41, 'profession': 'Builder' }
    }
  ]
})

// Use the fluid api to append the content
hx.select('#advanced-search-example-container')
  .add(hx.dataTable({
    feed: tableFeed,
    filterEnabled: false, // Disable the normal filter
    showSearchAboveTable: true, // Show the search above the table instead of below
    advancedSearchEnabled: true // Enable the advanced search
  }))

Advanced Search Criteria Example

HTML

<h4>Advanced Search Criteria Example</h4>
<div id="advanced-criteria-example"></div>

JavaScript

var tableFeed = hx.dataTable.objectFeed({
  headers: [
    { name: 'Name', id: 'name' },
    { name: 'Age', id: 'age' },
    { name: 'Profession', id: 'profession' }
  ],
  rows: [
    {
      id: 0,
      cells: { 'name': 'Bob', 'age': 25, 'profession': 'Developer' }
    },
    {
      id: 1,
      cells: { 'name': 'Jan', 'age': 41, 'profession': 'Artist' }
    },
    {
      id: 2,
      cells: { 'name': 'Dan', 'age': 41, 'profession': 'Builder' }
    }
  ]
})

// Use the fluid api to append the content
hx.select('#advanced-criteria-example')
  .add(hx.dataTable({
    feed: tableFeed,
    filterEnabled: false, // Disable the normal filter
    advancedSearchEnabled: true, // Enable the advanced search
    advancedSearchCriteria: hx.filter.types(), // Enable all the filter types
    advancedSearch: [
      [
        {column: "age", term: "26", criteria: "greater"}
      ],
      [
        {column: "name", term: "Bob", criteria: "exact"}
      ]
    ]
  }))
Api
Prototypes
hx.DataTableextendsEventEmitter
A component to allow tables to be created dynamically using Javascript that contains features such as filtering, sorting and pagination.
Constructors
hx.DataTableselectorString / HTMLElementoptionsObject
Creates a table object using a selector and some options.
Arguments
selectorString / HTMLElement
A CSS selector string which uniquely identifies the element to create the table in, or the Element to create the table in.
options
The options to use when creating the data table
Properties
addFilterTextString
The text to display on the add filter button
Default: hx.userFacingText('dataTable', 'addFilter')
advancedSearchArray[Array[Object]]
The advanced search array to use. If a value is passed in, showAdvancedSearch and advancedSearchEnabled are both set to true, showing and enabling the advanced search. See the Using the Advanced Search section at the bottom of the page for more information on the advanced search
advancedSearchCriteriaArray[String]
An array of types that the advanced search for the data table is allowed to use. The values that can be used can be found in hx.filter.types(). Setting this to undefined disables the ability to change the filter criteria and uses 'contains' filtering.
This value can be set per-column
Default: undefined
advancedSearchEnabledBoolean
Whether the advanced search should be enabled. If an advancedSearch is passed in, this is set to true. If filterEnabled is set to false and this is set to true, the advanced search will be shown on it's own with no toggle for switching the filter type. See the Using the Advanced Search section at the bottom of the page for more information on the advanced search
Default: false
advancedSearchPlaceholderString
The text to display in the advanced search filter input boxes
Default: hx.userFacingText('dataTable', 'search')
advancedSearchTextString
The text to display on the advanced search toggle
Default: hx.userFacingText('dataTable', 'advancedSearch')
allowHeaderWrapBoolean
A boolean to determine whether table headers should be allowed to wrap onto multiple lines.
Default: false
anyColumnTextString
The text to display for the 'any column' option when creating advanced search filters
Default: hx.userFacingText('dataTable', 'anyColumn')
cellRendererelementHTMLElementcellObjectrowObject
A function for rendering body cells.
Default:
function (element, cell, row) {
  hx.select(element).text(cell);
}
Arguments
elementHTMLElement
The element that is being populated.
cell
The data for the cell.
row
The entire row object.
clearFiltersTextString
The text to display on the clear filters button
Default: hx.userFacingText('dataTable', 'clearFilters')
clearSelectionTextString
The text to display on the 'clear selection' link when rows have been selected
Default: [hx.userFacingText('dataTable','clearSelection')]
collapsibleRendererelementHTMLElementrowObject
A function for rendering collapsibles. For rows to be collapsible, this function must be provided.
Arguments
elementHTMLElement
The collapsible content that is being populated.
row
The entire row object
columns
An object that allows the setting of column specific renderers as well as the ability to disable sorting for a specific column. To set a one of the options for a column, an object can be defined:
{
  "columnid": {
    sortEnabled: true,
    cellRenderer: function (element, cell, row) {
      hx.select(element).text(cell);
    }
  }
}
Columns will use the default options if a column specific value is not provided.
Properties
allowHeaderWrapBoolean
Column specific version of the allowHeaderWrap option
cellRendererelementHTMLElementcellObjectrowObject
Column specific version of the cellRenderer option
Arguments
elementHTMLElement
The element that is being populated.
cell
The data for the cell.
row
The entire row object.
headerCellRendererelementHTMLElementcellObjectheadersObject
Column specific version of the headerCellRenderer option
Arguments
elementHTMLElement
The element that is being populated.
cell
The data for the cell.
headers
The entire headers object.
maxWidthNumber
A value that can be used to set the max width for a column to enable more structured table layouts. The max width does not take into account the padding applied to the cells and will stretch to fit the heading if there is not enough room for the heading text and icon At least one column must not have the max width set otherwise the table will ignore all values.
sortEnabledBoolean
Column specific version of the sortEnabled option
compactString / Boolean
A value to determine whether compact mode should be enabled. There are three possible values:
  • 'auto': Detect the size of the window and switch between compact and standard modes automatically.
  • true: Always use compact mode
  • false: Always use standard mode.
Default: 'auto'
displayModeString
A string to determine what display mode the table should use.
There are currently two possible values:
  • 'paginate': show a single page at a time with a pagination option.
  • 'all': Show all the rows on a single page.
Default: 'paginate'
expandedRowsArray
The expanded rows to initialise the table with
feedFeed
The feed to use when creating the table. See the Feed and hx.dataTable objects for information on feeds.
filterString
The filter to apply when creating the table
filterEnabledBoolean
A boolean to determine whether filtering should be enabled.
Default: true
headerCellRendererelementHTMLElementcellObjectheadersObject
A function for rendering header cells.
Default:
function (element, cell, headers) {
  hx.select(element).text(cell.name);
}
Arguments
elementHTMLElement
The element that is being populated.
cell
The data for the cell.
headers
The entire headers object.
highlightOnHoverBoolean
Whether the row should hightlight when the user hovers over it
Default: true
loadingTextString
The text to display when data is loading
Default: [hx.userFacingText('dataTable','loading')]
noDataMessageString
Default: [hx.userFacingText('dataTable','noData')]
noDataMessageString
A string that is displayed when there is no data in the table.
Default: ['No Data']
noSortTextString
The text to display on the mobile sort menu for 'No Sort'
Default: [hx.userFacingText('dataTable', 'noSort')]
pageSizeNumber
A number to determine how many rows should be shown on a page.
Default: 15
pageSizeOptionsArray[Number]
An array of numbers to determine the page sizes that can be selected by the user.
If a value is provided, a dropdown is shown to allow the user to change the rows displayed on a page.
retainHorizontalScrollOnRenderBoolean
A boolean to determine whether the horizontal scroll should be retained when re-rendering the current page of data.
Default: true
retainVerticalScrollOnRenderBoolean
A boolean to determine whether the vertical scroll should be retained when re-rendering the current page of data.
Default: false
rowCollapsibleLookuprowObjectBoolean
A function for determining whether a row has a collapsible.
Default:
function (row) {
  return false;
}
Arguments
row
The data for the current row.
Returns
Whether the row should have a collapsible
rowEnabledLookuprowObjectBoolean
A function for determining whether a row should be visually disabled and prevented from being selected.
Default:
function (row) {
  return !row.disabled;
}
Arguments
row
The data for the current row.
Returns
Whether the row should be disabled. True means that the row should be enabled, false means it should be disabled.
rowIDLookuprowObjectString
Gets the unique id for a row.
Default:
function (row) {
  return row.id;
}
This could be changed to use one of the column values as the id (providing it is unique across all the data in the table)
Arguments
row
The data for the current row.
Returns
The id of the row provided
rowSelectableLookuprowObjectBoolean
A function for determining whether a row can be selected at the time it is clicked.
Default:
function (row) {
  return true;
}
Arguments
row
The data for the current row.
Returns
Whether the row can be selected.
rowsPerPageTextString
The text to display next to the 'rows per page' picker
Default: [hx.userFacingText('dataTable','rowsPerPage')]
searchPlaceholderString
The placeholder for the 'search' box
Default: [hx.userFacingText('dataTable','search')]
selectEnabledBoolean
A boolean to determine whether the selection of rows should be enabled.
Default: false
selectedRowsArray
The selected rows to initialise the table with
selectedRowsTextString
The text to display in the selected rows information bar.
The '$total' variables can be substituted in, e.g for a table with 3 rows and 1 row selected:
options = {
  selectedRowsText: '$selected of $total selected.'
}
// Would evalate to '1 of 3 selected.'
Default: [hx.userFacingText('dataTable', 'selectedRows')]
showAdvancedSearchBoolean
Whether to show the advanced search and the toggle for switching between the regular filter and the advanced search.
If advancedSearchEnabled is true or an advancedSearch is passed in, this is set to true.
See the Using the Advanced Search section at the bottom of the page for more information on the advanced search
Default: false
showSearchAboveTableBoolean
Whether to show the Search/Advanced search above the table
Default: false
singleSelectionBoolean
A boolean to determine whether the table should be in single select mode.
This mode only allows one row to be selected at a time.
selectEnabled must also be true for this to take effect.
Default: false
sort
The sort to apply when creating the table. No sorting is applied by default
Properties
columnString
The column id to sort on
directionString
The sort direction. Can be either 'asc' or 'desc'
sortByTextString
The text to display next to the sort picker shown in compact mode.
Default: [hx.userFacingText('dataTable','sortBy')]
sortEnabledBoolean
A boolean to determine whether sorting should be enabled. This can also be set on a per-column basis using the columns option.
Default: true
Options
These methods are for getting/setting the value of the options available on data tables. For more information about what each option controls and the values they can be set to, see the options parameter of the DataTable constructor.
collapsibleRendererFunction
Gets the collapsibleRenderer option
Returns
function
The collapsibleRenderer option
collapsibleRenderervalueFunctioncallbackFunctionDataTable
Sets the collapsibleRenderer option
Arguments
value
The value for the collapsibleRenderer option
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
compactBoolean
Gets the compact option
Returns
The compact option
compactvalueBooleancallbackFunctionDataTable
Sets the compact option
Arguments
valueBoolean
The value for the compact option
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
displayModeString
Gets the displayMode option
Returns
The displayMode option
displayModevalueStringcallbackFunctionDataTable
Sets the displayMode option
Arguments
valueString
The value for the displayMode option
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
feedObject
Gets the feed option
Returns
Object
The feed option
feedvalueObjectcallbackFunctionDataTable
Sets the feed option
Arguments
value
The value for the feed option
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
filterString
Gets the filter option
Returns
The filter option
filtervalueStringcallbackFunctionDataTable
Sets the filter option
Arguments
valueString
The value for the filter option
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
filterEnabledBoolean
Gets the filterEnabled option
Returns
The filterEnabled option
filterEnabledvalueBooleancallbackFunctionDataTable
Sets the filterEnabled option
Arguments
valueBoolean
The value for the filterEnabled option
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
noDataMessageString
Gets the noDataMessage option
Returns
The noDataMessage option
noDataMessagevalueStringcallbackFunctionDataTable
Sets the noDataMessage option
Arguments
valueString
The value for the noDataMessage option
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
pageSizeNumber
Gets the pageSize option
Returns
The pageSize option
pageSizevalueNumbercallbackFunctionDataTable
Sets the pageSize option
Arguments
valueNumber
The value for the pageSize option
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
pageSizeOptionsArray[Number]
Gets the pageSizeOptions option
Returns
The pageSizeOptions option
pageSizeOptionsvalueArray[Number]callbackFunctionDataTable
Sets the pageSizeOptions option
Arguments
The value for the pageSizeOptions option
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
retainHorizontalScrollOnRenderBoolean
Gets the retainHorizontalScrollOnRender option
Returns
The retainHorizontalScrollOnRender option
retainHorizontalScrollOnRendervalueBooleancallbackFunctionDataTable
Sets the retainHorizontalScrollOnRender option
Arguments
valueBoolean
The value for the retainHorizontalScrollOnRender option
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
retainVerticalScrollOnRenderBoolean
Gets the retainVerticalScrollOnRender option
Returns
The retainVerticalScrollOnRender option
retainVerticalScrollOnRendervalueBooleancallbackFunctionDataTable
Sets the retainVerticalScrollOnRender option
Arguments
valueBoolean
The value for the retainVerticalScrollOnRender option
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
rowCollapsibleLookupFunction
Gets the rowCollapsibleLookup option
Returns
function
The rowCollapsibleLookup option
rowCollapsibleLookupvalueFunctioncallbackFunctionDataTable
Sets the rowCollapsibleLookup option
Arguments
value
The value for the rowCollapsibleLookup option
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
rowEnabledLookupFunction
Gets the rowEnabledLookup option
Returns
function
The rowEnabledLookup option
rowEnabledLookupvalueFunctioncallbackFunctionDataTable
Sets the rowEnabledLookup option
Arguments
value
The value for the rowEnabledLookup option
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
rowIDLookupFunction
Gets the rowIDLookup option
Returns
function
The rowIDLookup option
rowIDLookupvalueFunctioncallbackFunctionDataTable
Sets the rowIDLookup option
Arguments
value
The value for the rowIDLookup option
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
rowSelectableLookupFunction
Gets the rowSelectableLookup option
Returns
function
The rowSelectableLookup option
rowSelectableLookupvalueFunctioncallbackFunctionDataTable
Sets the rowSelectableLookup option
Arguments
value
The value for the rowSelectableLookup option
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
selectEnabledBoolean
Gets the selectEnabled option
Returns
The selectEnabled option
selectEnabledvalueBooleancallbackFunctionDataTable
Sets the selectEnabled option
Arguments
valueBoolean
The value for the selectEnabled option
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
singleSelectionBoolean
Gets the singleSelection option
Returns
The singleSelection option
singleSelectionvalueBooleancallbackFunctionDataTable
Sets the singleSelection option
Arguments
valueBoolean
The value for the singleSelection option
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
sortObject
Gets the sort option
Returns
Object
The sort option
sortvalueObjectcallbackFunctionDataTable
Sets the sort option
Arguments
value
The value for the sort option
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
allowHeaderWrapBoolean
Gets the allowHeaderWrap option
Returns
The allowHeaderWrap option
allowHeaderWrapvalueBooleancallbackFunctionDataTable
Sets the allowHeaderWrap option
Arguments
valueBoolean
The value for the allowHeaderWrap option
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
allowHeaderWrapcolumnStringBoolean
Gets the allowHeaderWrap value for a column of the table if one has been set.
Arguments
columnString
The id of the column to get the allowHeaderWrap value for
Returns
The allowHeaderWrap option for the column
allowHeaderWrapcolumnStringvalueBooleancallbackFunctionDataTable
Sets the allowHeaderWrap value for a column of the table
Arguments
columnString
The id of the column to set the allowHeaderWrap value for
valueBoolean
The value to set
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
cellRendererFunction
Gets the cellRenderer option
Returns
function
The cellRenderer option
cellRenderervalueFunctioncallbackFunctionDataTable
Sets the cellRenderer option
Arguments
value
The value for the cellRenderer option
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
cellRenderercolumnStringFunction
Gets the cellRenderer value for a column of the table if one has been set.
Arguments
columnString
The id of the column to get the cellRenderer value for
Returns
function
The cellRenderer option for the column
cellRenderercolumnStringvalueFunctioncallbackFunctionDataTable
Sets the cellRenderer value for a column of the table
Arguments
columnString
The id of the column to set the cellRenderer value for
value
The value to set
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
headerCellRendererFunction
Gets the headerCellRenderer option
Returns
function
The headerCellRenderer option
headerCellRenderervalueFunctioncallbackFunctionDataTable
Sets the headerCellRenderer option
Arguments
value
The value for the headerCellRenderer option
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
headerCellRenderercolumnStringFunction
Gets the headerCellRenderer value for a column of the table if one has been set.
Arguments
columnString
The id of the column to get the headerCellRenderer value for
Returns
function
The headerCellRenderer option for the column
headerCellRenderercolumnStringvalueFunctioncallbackFunctionDataTable
Sets the headerCellRenderer value for a column of the table
Arguments
columnString
The id of the column to set the headerCellRenderer value for
value
The value to set
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
sortEnabledBoolean
Gets the sortEnabled option
Returns
The sortEnabled option
sortEnabledvalueBooleancallbackFunctionDataTable
Sets the sortEnabled option
Arguments
valueBoolean
The value for the sortEnabled option
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
sortEnabledcolumnStringBoolean
Gets the sortEnabled value for a column of the table if one has been set.
Arguments
columnString
The id of the column to get the sortEnabled value for
Returns
The sortEnabled option for the column
sortEnabledcolumnStringvalueBooleancallbackFunctionDataTable
Sets the sortEnabled value for a column of the table
Arguments
columnString
The id of the column to set the sortEnabled value for
valueBoolean
The value to set
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
maxWidthcolumnStringNumber
Gets the maxWidth value for a column of the table if one has been set.
Arguments
columnString
The id of the column to get the maxWidth value for
Returns
The maxWidth option for the column
maxWidthcolumnStringvalueNumbercallbackFunctionDataTable
Sets the maxWidth value for a column of the table
Arguments
columnString
The id of the column to set the maxWidth value for
valueNumber
The value to set
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
showAdvancedSearchvalueBooleanDataTable
Sets the showAdvancedSearch option
Arguments
valueBoolean
The value for the showAdvancedSearch option
Returns
DataTable
This data table
showAdvancedSearchBoolean
Gets the showAdvancedSearch option
Returns
The value of the showAdvancedSearch option
advancedSearchEnabledvalueBooleanDataTable
Sets the advancedSearchEnabled option
Arguments
valueBoolean
The value for the advancedSearchEnabled option
Returns
DataTable
This data table
advancedSearchEnabledBoolean
Gets the advancedSearchEnabled option
Returns
The value of the advancedSearchEnabled option
showSearchAboveTablevalueBooleanDataTable
Sets the showSearchAboveTable option
Arguments
valueBoolean
The value for the showSearchAboveTable option
Returns
DataTable
This data table
showSearchAboveTableBoolean
Gets the showSearchAboveTable option
Returns
The value of the showSearchAboveTable option
advancedSearchArray[Array[Object]]
Gets the currently advanced search
Returns
The currently set array of advanced search filter
advancedSearchvalueArray[Array[Object]]DataTable
Sets the advanced search
Arguments
The advanced search array to set
Returns
DataTable
This data table
advancedSearchCriteriaArray[String]
Gets the current advancedSearchCriteria
Returns
The currently set array of advancedSearchCriteria filter
advancedSearchCriteriavalueArray[String]DataTable
Sets the advancedSearchCriteria
Arguments
The advancedSearchCriteria array to set
Returns
DataTable
This data table
advancedSearchCriteriacolumnStringArray[String]
Gets the advancedSearchCriteria value for a column of the table if one has been set.
Arguments
columnString
The id of the column to get the advancedSearchCriteria value for
Returns
The advancedSearchCriteria option for the column
advancedSearchCriteriacolumnStringvalueArray[String]callbackFunctionDataTable
Sets the advancedSearchCriteria value for a column of the table
Arguments
columnString
The id of the column to set the advancedSearchCriteria value for
The value to set
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
Events
allowheaderwrapchange
Emitted when the allowHeaderWrap option is changed
Properties
causeString
Can be 'user' or 'api', depending on what caused the change. 'api' means an call to the javascript api caused the change, 'user' means that the change was caused by inputting
valueAny
The value of the allowHeaderWrap option.
cellrendererchange
Emitted when the cellRenderer option is changed
Properties
causeString
Can be 'user' or 'api', depending on what caused the change. 'api' means an call to the javascript api caused the change, 'user' means that the change was caused by inputting
valueAny
The value of the cellRenderer option.
collapsiblerendererchange
Emitted when the collapsibleRenderer option is changed
Properties
causeString
Can be 'user' or 'api', depending on what caused the change. 'api' means an call to the javascript api caused the change, 'user' means that the change was caused by inputting
valueAny
The value of the collapsibleRenderer option.
compactchange
Emitted when the compact option is changed
Properties
causeString
Can be 'user' or 'api', depending on what caused the change. 'api' means an call to the javascript api caused the change, 'user' means that the change was caused by inputting
If the cause is 'user', and the value is 'auto', this value will contain the actual compact mode (it will be true for compact, false for desktop)
valueAny
The value of the compact option.
displaymodechange
Emitted when the displayMode option is changed
Properties
causeString
Can be 'user' or 'api', depending on what caused the change. 'api' means an call to the javascript api caused the change, 'user' means that the change was caused by inputting
valueAny
The value of the displayMode option.
expandedrowschange
Emitted when a row is expanded or collapsed
Properties
causeString
Can be 'user' or 'api', depending on what caused the change. 'api' means an call to the javascript api caused the change, 'user' means that the change was caused by inputting
row
The row that was expanded or collapsed (if this event was caused by the user clicking on the expand toggle)
rowValueBoolean
Whether or not the row that was clicked on is now expanded (if this event was caused by the user clicking on the expand toggle)
The expanded rows (a list of ids).
feedchange
Emitted when the feed option is changed
Properties
causeString
Can be 'user' or 'api', depending on what caused the change. 'api' means an call to the javascript api caused the change, 'user' means that the change was caused by inputting
valueAny
The value of the feed option.
filterchange
Emitted when the filter option is changed
Properties
causeString
Can be 'user' or 'api', depending on what caused the change. 'api' means an call to the javascript api caused the change, 'user' means that the change was caused by inputting
valueAny
The value of the filter option.
filterenabledchange
Emitted when the filterEnabled option is changed
Properties
causeString
Can be 'user' or 'api', depending on what caused the change. 'api' means an call to the javascript api caused the change, 'user' means that the change was caused by inputting
valueAny
The value of the filterEnabled option.
headercellrendererchange
Emitted when the headerCellRenderer option is changed
Properties
causeString
Can be 'user' or 'api', depending on what caused the change. 'api' means an call to the javascript api caused the change, 'user' means that the change was caused by inputting
valueAny
The value of the headerCellRenderer option.
nodatamessagechange
Emitted when the noDataMessage option is changed
Properties
causeString
Can be 'user' or 'api', depending on what caused the change. 'api' means an call to the javascript api caused the change, 'user' means that the change was caused by inputting
valueAny
The value of the noDataMessage option.
pagechange
Emitted when the page is changed
Properties
causeString
Can be 'user' or 'api', depending on what caused the change. 'api' means a call to the javascript api caused the change, 'user' means that the change was caused by inputting
valueAny
The selected page number, starting from 1.
pagesizechange
Emitted when the pageSize option is changed
Properties
causeString
Can be 'user' or 'api', depending on what caused the change. 'api' means an call to the javascript api caused the change, 'user' means that the change was caused by inputting
valueAny
The value of the pageSize option.
pagesizeoptionschange
Emitted when the pageSizeOptions option is changed
Properties
causeString
Can be 'user' or 'api', depending on what caused the change. 'api' means an call to the javascript api caused the change, 'user' means that the change was caused by inputting
valueAny
The value of the pageSizeOptions option.
render
Emitted when the table is rendered.
retainhorizontalscrollonrenderchange
Emitted when the retainHorizontalScrollOnRender option is changed
Properties
causeString
Can be 'user' or 'api', depending on what caused the change. 'api' means an call to the javascript api caused the change, 'user' means that the change was caused by inputting
valueAny
The value of the retainHorizontalScrollOnRender option.
retainverticalscrollonrenderchange
Emitted when the retainVerticalScrollOnRender option is changed
Properties
causeString
Can be 'user' or 'api', depending on what caused the change. 'api' means an call to the javascript api caused the change, 'user' means that the change was caused by inputting
valueAny
The value of the retainVerticalScrollOnRender option.
rowclick
An object containing the row data and the row node.
Properties
data
The data for the row
nodeHTMLElement
The node for the row
rowcollapsiblelookupchange
Emitted when the rowCollapsibleLookup option is changed
Properties
causeString
Can be 'user' or 'api', depending on what caused the change. 'api' means an call to the javascript api caused the change, 'user' means that the change was caused by inputting
valueAny
The value of the rowCollapsibleLookup option.
rowenabledlookupchange
Emitted when the rowEnabledLookup option is changed
Properties
causeString
Can be 'user' or 'api', depending on what caused the change. 'api' means an call to the javascript api caused the change, 'user' means that the change was caused by inputting
valueAny
The value of the rowEnabledLookup option.
rowidlookupchange
Emitted when the rowIDLookup option is changed
Properties
causeString
Can be 'user' or 'api', depending on what caused the change. 'api' means an call to the javascript api caused the change, 'user' means that the change was caused by inputting
valueAny
The value of the rowIDLookup option.
rowselectablelookupchange
Emitted when the rowSelectableLookup option is changed
Properties
causeString
Can be 'user' or 'api', depending on what caused the change. 'api' means an call to the javascript api caused the change, 'user' means that the change was caused by inputting
valueAny
The value of the rowSelectableLookup option.
selectedrowschange
Emitted when a row is selected or deselected.
Properties
causeString
Can be 'user' or 'api', depending on what caused the change. 'api' means an call to the javascript api caused the change, 'user' means that the change was caused by inputting
row
The row that was selected (if this event was caused by the user clicking on the row check)
rowValueBoolean
Whether or not the row that was clicked on is now selected (if this event was caused by the user clicking on the row check)
The selected rows (a list of ids).
selectedrowsclear
Emitted when the row selection is cleared by clicking on the 'clear selection' text.
selectenabledchange
Emitted when the selectEnabled option is changed
Properties
causeString
Can be 'user' or 'api', depending on what caused the change. 'api' means an call to the javascript api caused the change, 'user' means that the change was caused by inputting
valueAny
The value of the selectEnabled option.
singleselectionchange
Emitted when the singleSelection option is changed
Properties
causeString
Can be 'user' or 'api', depending on what caused the change. 'api' means an call to the javascript api caused the change, 'user' means that the change was caused by inputting
valueAny
The value of the singleSelection option.
sortchange
Emitted when the sort option is changed
Properties
causeString
Can be 'user' or 'api', depending on what caused the change. 'api' means an call to the javascript api caused the change, 'user' means that the change was caused by inputting
valueAny
The value of the sort option.
sortenabledchange
Emitted when the sortEnabled option is changed
Properties
causeString
Can be 'user' or 'api', depending on what caused the change. 'api' means an call to the javascript api caused the change, 'user' means that the change was caused by inputting
valueAny
The value of the sortEnabled option.
Methods
expandedRowsvalueArray[String]
Gets the expanded rows
Returns
value
The array of expanded row ids
expandedRowsvalueArray[String]callbackFunctionDataTable
Sets the expanded rows
Arguments
The array of row ids to set as expanded
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
pageNumber
Gets the current page
Returns
The currently selected page
pagevalueNumbercallbackFunctionDataTable
Sets the current page
Arguments
valueNumber
The current page to set
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
rendercallbackFunctionDataTable
Renders the table.
Arguments
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
renderSuppressedBoolean
Gets the suppressed state of the table.
Returns
Whether the table render is suppressed
renderSuppressedsuppressBooleanDataTable
A method for preventing the render from changing anything until unsuppressed.
Arguments
suppressBoolean
Whether to suppress the render
Returns
DataTable
This DataTable
rowsForIdsidsArray[String]callbackFunction
Converts row ids to row objects using the table's data feed.
Arguments
The array of row ids to get from the data
callbackrowsArray[Object]
The function to call once the rows have been retrieved
Arguments
The array of row objects returned from the feed
selectedRowsvalueArray[String]
Gets the selected rows
Returns
value
The array of selected row ids
selectedRowsvalueArray[String]callbackFunctionDataTable
Sets the selected rows
Arguments
The array of row ids to set as selected
callback
The function to call once rendering is complete
Returns
DataTable
This DataTable
Objects
Feed
A feed is the type of object used by a data table to get the data for display. A feed should be an object with the following functions:
{
  headers: function (cb) { ... }
  totalCount: function (cb) { ... }
  rows: function (range, cb) { ... }
  rowsForIds: function (ids, cb) { ... }
}
There are predefined feeds for objects and urls in the hx.dataTable object. A data table expects data to be returned in the callback of each function with a specific value. If a custom feed is created, it must return the values expected by the table.
Functions
headerscallbackFunction
A function to get a list of header objects
Arguments
callbackdataArray[Object]
The function to call once the data has been retrieved.
Arguments
The headers for a data set. The data is expected in the following format:
[
  {
    name: 'columnName', // The name for the heading to display in the table
    id: 'columnID' // The unique ID for the column
  },
  ... // Additional headers
]
rowsrangeObjectcallbackFunction
A function to get the row data for the range object specified along with the filtered count
Arguments
range
The range to get the rows for. An example object can be seen below:
{
  start: 0,
  end: 14,
  filter: "",
  sort: {
    column: 'name'
    direction: 'desc'
  },
  useAdvancedSearch: true, // Whether to filter using the advanced search
  advancedSearch: [
    [
      { column: 'any', term: '' }
    ]
  ]
}
The above example would be expected to return the first 15 rows of data, sorted by the 'name' column in descending order.
Properties
The end of the range. Might be undefined if the all displayMode is used.
filterString
The filter being used.
sort
The sort being used.
Properties
columnString
The column being sorted. Can be a column id or indicating no sort.
directionString
The sort direction. Can be "asc", "desc" or undefined.
startNumber
The start of the range. Might be undefined if the all displayMode is used.
callbackdataObject
The function to call once the data has been retrieved.
Arguments
data
Properties
filteredCountNumber
The number of all filtered rows in the feed. Can be undefined if the feed is lazy and the final size is unknown.
The rows for a range of the data set. The data is expected in the following format:
[
  {
    id: 0, // The ID for a row
    // hidden details can be specified here (not in the cells object)
    cells: {
      'columnID': 'value' // The cell values for a row in columnID/value pairs
    }
  },
  ... // Additional rows
]
A cell value must be provided for each column id for every row
rowsForIdsidsArray[String]lookupRowFunctioncallbackFunction
Gets the rows for an array of id's in the data. This is used when DataTable::rowsForIds is called.
Arguments
The array of row id's to lookup.
lookupRow
The row id lookup function for the table
callbackdataArray[Object]
The function to call once the data has been retrieved.
Arguments
The array of row data retrieved from the id lookup
totalCountcallbackFunction
A function to get the total number of rows in the data set.
Arguments
callbackdataNumber
The function to call once the data has been retrieved.
Arguments
dataNumber
The total number of rows. This can be undefined if you don't know the total number of rows in the data set.
hx.dataTable
An object containing the default Feed object constructors and helpers for making custom feeds.
See the Using Feeds section for more information about using and creating Feeds.
Functions
getAdvancedSearchFiltercellValueLookupFunctiontermLookupFunctionFunction
Gets an advanced search filter when using a custom feed
Arguments
cellValueLookupcellAnyString
The function used to get a searchable string from a cell with it's value as an object
Default: hx.identity
Arguments
cellAny
The cell from the data being searched for a given column
Returns
A searcheable string
termLookupfilterTermStringrowSearchTermStringBoolean
The function used to determine whether a row should be shown in the results
Default:
function(term, rowSearchTerm) {
  var whitespaceSplitRegex = /\s+/
  var stripLeadingAndTrailingWhitespaceRegex = /^\s+|\s+$/g
  var arr = term.replace(stripLeadingAndTrailingWhitespaceRegex, '').split(whitespaceSplitRegex)
  var validPart = hx.find(arr, function(part) {
    return ~rowSearchTerm.indexOf(part)
  })
  return hx.defined(validPart)
}
Arguments
filterTermString
The term entered in the filter
rowSearchTermString
The term for the given row/column value
Returns
A boolean to indicate whether the term has been found in the row
Returns
functionfiltersArray[Array[Object]]rowObject
The function for checking if a single row matches the filters
Arguments
filtersArray[Array[Object]]
The advanced search filters
row
The row object
objectFeeddataObjectoptionsObjectFeed
The default feed object for using object based data
Arguments
data
The data to use in the feed. The data is expected in the following format:
{
  headers: [
    { name: 'Name', id: 'name' },
    ... // Additional Headers
  ],
  rows: [
    {
      // hidden details can go here (not in the cells object)
      id: 0,
      cells: {
        'name': 'Bob',
        ... // Additional cell data (each header should have linked cell data for each row)
      }
    },
    ... // Additional Rows
  ]
}
options
The options to use in the feed.
Properties
cellValueLookupcellAnyString
The function used to get a searchable string from a cell with it's value as an object
Default: hx.identity
Arguments
cellAny
The cell from the data being searched for a given column
Returns
A searcheable string
comparecell1Stringcell2StringNumber
The compare function used to sort the rows.
Default: hx.sort.compare
Arguments
cell1String
The first cell value to compare
cell2String
The second cell value to compare
Returns
-1 if cell1 should be ordered before cell2, 0 if it is the same, +1 if it should be ordered after cell2
filtertermStringrowObject
Determines if the row should be included in the filtered data set. The default filter function just checks for inclusion of the search term in any of the cell's text.
Default:
function (term, row) {
  var rowSearchTerm = Object.keys(row.cells).map(function (key) { return row.cells[key]}).join(' ').toLowerCase()
  term = term.toLowerCase.split(' ');
  for (var i in term) {
    var part = term[i];
    if (rowSearchTerm.indexOf(part) === -1) {
      return false
    }
  }
  return false
}
Arguments
termString
The search term
row
The row data
termLookupfilterTermStringrowSearchTermStringBoolean
The function used to determine whether a row should be shown in the results
Default:
function(term, rowSearchTerm) {
  var whitespaceSplitRegex = /\s+/
  var stripLeadingAndTrailingWhitespaceRegex = /^\s+|\s+$/g
  var arr = term.replace(stripLeadingAndTrailingWhitespaceRegex, '').split(whitespaceSplitRegex)
  var validPart = hx.find(arr, function(part) {
    return ~rowSearchTerm.indexOf(part)
  })
  return hx.defined(validPart)
}
Arguments
filterTermString
The term entered in the filter
rowSearchTermString
The term for the given row/column value
Returns
A boolean to indicate whether the term has been found in the row
Returns
Feed
A feed object. See the object for more information on what a feed contains.
urlFeedurlStringoptionsObjectFeed
Creates a url fee using the provided url. The feed will then make requests to retrieve the various chunks of data as they are required.
Arguments
The url to use in the feed.
options
The options to use in the feed.
Properties
cacheBoolean
Whether or not to cache values in memory - if you always want fresh data, this should be set to false.
Default: false
extraAny
Extra information to pass through to the requests made for data. This can be useful for identifying the table, or providing extra options when requesting data from the server.
Returns
Feed
A feed object. See the object for more information on what a feed contains.
Functions
hx.dataTableoptionsObjectSelection
Creates a new DataTable set up on a detached element, wrapped in a selection
Arguments
options
See the options object for constructing DataTable
Returns
Selection
A selection containing an element with an DataTable initialised on it
Getting Started

Using Feeds

Data tables contain multiple options for displaying the data, as well as flexibility in how the data is provided. There are two functions that are available for creating feeds, however custom feeds can also be created.
Using hx.dataTable.objectFeed
An object feed expects the data to be provided as a whole when the feed is created. The below code shows a basic use of the object feed.
var tableData = {
  headers: [
    { name: 'Name', id: 'name' },
    { name: 'Age', id: 'age' },
    { name: 'Profession', id: 'profession' }
  ],
  rows: [
    {
      id: 0,
      cells: { 'name': 'Bob', 'age': 25, 'profession': 'Developer' }
    },
    {
      id: 1,
      cells: { 'name': 'Jan', 'age': 41, 'profession': 'Artist' }
    },
    {
      id: 2,
      cells: { 'name': 'Dan', 'age': 41, 'profession': 'Builder' }
    }
  ]
}
var table = new hx.DataTable('#selector')
table.feed(hx.dataTable.objectFeed(tableData))
Alternatively, if the data is returned from a URL request, it can be set as follows:
hx.json('path_to_your_request.file', function(err, data){
  if (!err) table.feed(hx.dataTable.objectFeed(tableData));
})
The object feed handles the sorting and filtering of the data internally making it the preferred choice for small or static data sets.
Using hx.dataTable.urlFeed
A url feed expects a single url to handle multiple requests and return different types of data. They can be created using:
hx.dataTable.urlFeed('request_url', {
  cache: true, // Whether to attempt caching of data
  extra: // Any extra data to be sent with every request
})
There are four different request types made by the url feed, all of which will be POST requests:

headers

{
  type: 'headers',
  extra: // As defined in the options
}
The data returned should be in the following format:
[
  {
    "name": "columnName", // The name for the heading to display in the table
    "id": "columnID" // The unique ID for the column
  },
  ... // Additional headers
]

totalCount

{
  type: 'totalCount',
  extra: // As defined in the options
}
The data returned should be in the following format:
{
  "count": 123 // The total number of rows in the data set
}
If the total is unknown, this can return undefined.

rows

The URL feed expects the server to perform any sorting/filtering as part of the 'rows' request.
{
  type: 'rows',
  range: {
    start: 0, // The start index to get
    end: 14, // The end index to get
    sort: {
      column: undefined, // the sort column
      direction: undefined // The sort direction
    },
    filter: undefined, // The current filter.
    useAdvancedSearch: false // Whether the advanced search is enabled
    advancedSearch: undefined // The currently set advanced search
  }
  extra: // As defined in the options
}
The data returned should be in the following format:
{
  "filteredCount": 10, // The number of rows in the filtered set
  "rows": [
    {
      "id": 0, // The ID for a row
      // hidden details can be specified here (not in the cells object)
      "cells": {
        "columnID": "value" // The cell values for a row in columnID/value pairs
      }
    },
    ... // Additional rows
  ]
}

rowsForIds

{
  type: 'rowsForIds',
  ids: [1, 2, 3] // The array of ids to get row data for
  extra: // As defined in the options
}
The data returned should be in the following format:
[
  {
    "id": 0, // The ID for a row
    // hidden details can be specified here (not in the cells object)
    "cells": {
      "columnID": "value" // The cell values for a row in columnID/value pairs
    }
  },
  ... // Additional rows
]
Creating a custom feed
In situations where the feeds provided in the hx.dataTable object are not suitable, custom feeds can be created. For instance, if using POST is not suitable, an alternative could be created:
// Serializes an object into param=value&param[child]=value
function serialize (obj, prefix) {
  var arr = []
  for (var p in obj) {
    if (obj.hasOwnProperty(p)) {
      var k = prefix ? prefix + '[' + p + ']' : p, v = obj[p]
      arr.push(typeof v == 'object' ?
        serialize(v, k) :
        encodeURIComponent(k) + '=' + encodeURIComponent(v))
    }
  }
  return arr.join('&')
}

function createCustomURLFeed (url) {
  var fetcher = function (data, cb) {
    // Serializes the data so it can be passed over as a GET request
    hx.json(url + '?' + serialize(data), function (err, data) { cb(data) })
  }

  // Return the feed object with headers, rows, rowsForIds and totalCount properties
  return {
    headers: function (cb) {
      fetcher({ type: 'headers' }, cb)
    },
    rows: function (range, cb) {
      fetcher({ type: 'rows', range: range }, cb)
    },
    rowsForIds: function (ids, lookupRow, cb) {
      fetcher({ type: 'rowsForIds', ids: ids }, cb)
    },
    totalCount: function (cb) {
      fetcher({ type: 'totalCount' }, cb)
    }
  }
}

Additional options

As well as the options available on the data table prototype, there are a few extra options when setting the data that can change the table behaviour by default.
Multi column / grouped headers
It is possible to add grouping to headers by specifying a columns
{
  headers:[
    { id: 'name', name: 'Name', groups: ['Group 1']},
    { id: 'age', name: 'Age' },
    { id: 'gender', name: 'Gender', groups: ['Group 2']},
    { id: 'dob', name: 'Date of Birth', groups: ['Group 2']},
    { id: 'salary', name: 'Salary (£)', groups: ['Group 2']}
  ],
  rows: [
    //...
  ]
}
Wrapping header text for indivual columns
It is possible to override the allowHeaderWrap option for an individual column by providing the allowWrap property in the header colums:
{
  headers:[
    { id: 'name', name: 'Name' },
    { id: 'age', name: 'Age' },
    { id: 'gender', name: 'Gender' },
    { id: 'dob', name: 'Date of Birth' allowWrap: true },
    { id: 'salary', name: 'Salary (£)' }
  ],
  rows: [
    //...
  ]
}
Disabling rows
When a row is rendered, the rowEnabledLookup function is called. If it returns false, the row will visually disabled and unselectable. By default, a row can be made unselectable using a property in the row object:
[
  {
    id: 'rowId',
    disabled: true,
    cells: {
      ...// Row data
    }
  },
  ... // Additional rows
]
This does not disable row collapsibles.
Making Rows unselectable
When a row is selected, the rowSelectableLookup function is called to check whether the row is selectable. If it returns false, the row will not be selected. By default, the rowSelectableLookup function allows all rows to be selected. However, by setting the rowSelectableLookup, the row can be made unselectable:
dataTable.rowSelectableLookup(function (row) {
  return !row.unselectable;
})
[
  {
    id: 'rowId',
    unselectable: true,
    cells: {
      ...// Row data
    }
  },
  ... // Additional rows
]

Using the Advanced Search

The advanced search is a feature that enables filtering across multiple columns.
There are several ways to use the advanced search. It can be used on it's own or can be toggled on/off by the user.
To show the advanced search toggle, the data table can be set up with:
{
  filterEnabled: true,
  showAdvancedSearch: true
}

HTML

<div id="advanced-search-toggle"></div>

JavaScript

var dt = new hx.DataTable('#advanced-search-toggle', {
  feed: tableFeed,
  filterEnabled: true,
  showAdvancedSearch: true
})
dt.render()
This creates the table with the advanced search available but still shows the standard filter until the user enables the advanced search.
The advanced search can also be used on it's own. To do this, use the following:
{
  filterEnabled: false,
  advancedSearchEnabled: true
}
The advancedSearchEnabled option is used here. It causes showAdvancedSearch to be true and shows the advanced search.

HTML

<div id="advanced-search-only"></div>

JavaScript

var dt = new hx.DataTable('#advanced-search-only', {
  feed: tableFeed,
  filterEnabled: false,
  advancedSearchEnabled: true
})
dt.render()
How the advanced search works
The advanced search uses an array of nested arrays of objects with a column and term property The logic behind the filtering uses Disjunctive Normal Form (an OR of AND s)
Below is an example of an advanced search:
[
  [
    { column: 'any', term: 'a' },
    // AND
    { column: 'name', term: 'b' }
  ],
  // OR
  [
    { column: 'profession', term: 'c' }
  ]
]
This would search for rows that match the following criteria:
(Any column contains 'a' and the name column contains 'b') or (The profession column contains 'c')
The table user interface mirrors this functionality, allowing the user to add filters row by row and decide whether they are AND or OR filters and splits the array(s) accordingly.

HTML

<div id="advanced-search-with-data"></div>

JavaScript

var dt = new hx.DataTable('#advanced-search-with-data', {
  feed: tableFeed,
  advancedSearch: [
    [
      { column: 'any', term: 'a' },
      { column: 'name', term: 'b' }
    ],
    [
      { column: 'profession', term: 'd' }
    ]
  ]
})
dt.render()
When using the advanced search, the rows function will be given some additional properties as part of the range object:
The URL feed expects the server to perform any sorting/filtering as part of the 'rows' request.
{
  type: 'rows',
  range: {
    start: 0,
    end: 14,
    sort: {
      column: undefined,
      direction: undefined
    },
    filter: undefined,
    useAdvancedSearch: true // Indicates that the filtering should be done using the advanced search
    advancedSearch: [ // The currently set advanced search
      [
        { column: 'any', term: 'a' },
        { column: 'name', term: 'b' }
      ],
      [
        { column: 'profession', term: 'd' }
      ]
    ]
  }
  extra: {}
}
As the advanced search and filter can be used interchangeably, the properties will be passed over with each request. The useAdvancedSearch should be used to determine whether to filter using the advanced search or the regular filter.