Data table for Ember based on a JSONAPI compliant backend.

Have a look at ember-paper-data-table to get a data table styled with ember-paper.

If you're using Ember > v3.8

ember install ember-data-table

For Ember < v3.8, use version 1.x of the addon

ember install [email protected]

Include the DataTableRouteMixin in the route which model you want to show in the data table. Configure the model name.

import Ember from 'ember';
import DataTableRouteMixin from 'ember-data-table/mixins/route';

export default Ember.Route.extend(DataTableRouteMixin, {
  modelName: 'blogpost'
});

Next, include the data table in your template:

{{data-table
  content=model
  fields="firstName lastName age created modified"
  isLoading=isLoadingModel
  filter=filter
  sort=sort
  page=page
  size=size
}}

Note: the filtering, sorting and pagination isn't done at the frontend. By including the DataTableRouteMixin in the route each change to the filter, sort, page and size params will result in a new request to the backend. The DataTableRouteMixin also sets an isLoadingModel flag while the route's model is being loaded.

Have a look at Customizing the data table to learn how you can customize the data table's header and body.

The following parameters can be passed to the data-table component:

By default the data table will make each column sortable. The search text box is only shown if the filter parameter is bound. Pagination is only shown if the pagination metadata is set on the model (see the Ember Data Table Serializer mixin).

The way the data is shown in the table can be customized by defining a content block instead of a fields parameter.

{{#data-table content=model filter=filter sort=sort page=page size=size onClickRow=(action "clickRow") as |t|}}
  {{#t.content as |c|}}
    {{#c.header}}
      {{th-sortable field='firstName' currentSorting=sort label='First name'}}
      {{th-sortable field='lastName' currentSorting=sort label='Last name'}}
      <th>Age</th>
      {{th-sortable field='created' currentSorting=sort label='Created'}}
      <th>Modified</th>
    {{/c.header}}
    {{#c.body as |row|}}
      <td>{{row.firstName}}</td>
      <td>{{row.lastName}}</td>
      <td>{{row.age}}</td>
      <td>{{moment-format row.created}}</td>
      <td>{{moment-format row.modified}}</td>
    {{/c.body}}
  {{/t.content}}
{{/data-table}}

Have a look at the helper components.

The user can add actions on top of the data table by providing a menu block.

{{#data-table content=model filter=filter sort=sort page=page size=size isLoading=isLoadingModel as |t|}}
  {{#t.menu as |menu|}}
    {{#menu.general}}
      {{#paper-button onClick=(action "export") accent=true noInk=true}}Export{{/paper-button}}
      {{#paper-button onClick=(action "print") accent=true noInk=true}}Print{{/paper-button}}          
    {{/menu.general}}
    {{#menu.selected as |selection datatable|}}
      {{#paper-button onClick=(action "delete" selection table) accent=true noInk=true}}Delete{{/paper-button}}
    {{/menu.selected}}
  {{/t.menu}}
  {{#t.content as |c|}}
    ...
  {{/t.content}}
{{/data-table}}

The menu block consists of a general and a selected block. The menu.general is shown by default. The menu.selected is shown when one or more rows in the data table are selected.

When applying an action on a selection, the currently selected rows can be provided to the action by the selection parameter. The user must reset the selection by calling clearSelection() on the data table. E.g.

actions:
  myAction(selection, datatable) {
    console.log("Hi, you reached my action for selection: " + JSON.stringify(selection));
    datatable.clearSelection();
  }    

The following components may be helpful when customizing the data table:

• Sortable header

The th-sortable component makes a column in the data table sortable. It displays a table header <th> element including an ascending/descending sorting icon in case the table is currently sorted by the given column.

{{th-sortable field='firstName' currentSorting=sort label='First name'}}

The following parameters are passed to the th-sortable component:

Note: the data table will update the currentSorting variable, but the user needs to handle the reloading of the data. The Ember Data Table Route mixin may be of use.

The following mixins may be helpful to use with the data table:

• Serializer mixin
• Route mixin
• Default Query Params mixin

Upon installation, the DataTableSerializerMixin is automatically included in your application serializer to add parsing of the filter, sortig and pagination meta data from the links in the JSONAPI responses. The data is stored in Ember's model metadata.

To include the DataTableSerializerMixin in your application, add the mixin to your application serializer:

import DS from 'ember-data';
import DataTableSerializerMixin from 'ember-data-table/mixins/serializer';

export default DS.JSONAPISerializer.extend(DataTableSerializerMixin, {

});

E.g.

meta: {
  count: 42
},
links: {
  previous: '/posts?page[number]=1&page[size]=10'
  next: '/posts?page[number]=3&page[size]=10'
}

will be parsed to

meta: {
  count: 42,
  pagination: {
    previous: { number: 1, size: 10 },
    next: { number: 3, size: 10 }
  }
}

The route providing data for the data-table component often looks similar. The model hook needs to query a list of resources of a specific model from the server. This list needs to be reloaded when the sorting, page or page size changes. The DataTableRouteMixin provides a default implementation of this behaviour. Just include the mixin in your route and specify the model to be queried as modelName.

import Ember from 'ember';
import DataTableRouteMixin from 'ember-data-table/mixins/route';

export default Ember.Route.extend(DataTableRouteMixin, {
  modelName: 'post'
});

The DataTableRouteMixin specifies the filter, page, sort and size variables as queryParams of the route with the refreshModel flag set to true. As such the data is reloaded when one of the variables changes. A user can add custom options to be passed in the query to the server by defining a mergeQueryOptions(parms) function in the route. The function must return an object with the options to be merged.

import Ember from 'ember';
import DataTableRouteMixin from 'ember-data-table/mixins/route';

export default Ember.Route.extend(DataTableRouteMixin, {
  modelName: 'post',
  mergeQueryOptions(params) {
    return { included: 'author' };
  }
});

Note: if the mergeQueryOptions returns a filter option on a specific field (e.g. title), the nested key needs to be provided as a string. Otherwise the filter param across all fields will be overwritten breaking the general search.

E.g.

mergeQueryOptions(params) {
    return {
        included: 'author',
        'filter[title]': params.title
    };
}

The DataTableRouteMixin also sets the isLoadingModel flag on the controller while the route's model is being loaded. Passing this flag to the data table's isLoading property will show a spinner while data is loaded.

The DefaultQueryParams mixin provides sensible defaults for the page (default: 0), size (default: 25) and filter (default: '') query parameters. The mixin can be mixed in a controller that uses the page and filter query params.

import Ember from 'ember';
import DefaultQueryParamsMixin from 'ember-data-table/mixins/default-query-params';

export default Ember.Controller.extend(DefaultQueryParamsMixin, {
  ...
});

Note: if you want the search text field to be enabled on a data table, the filter parameter may not be undefined. Therefore you must initialize it on an empty query string (as done by the DefaultQueryParams mixin).