# Autotable

## Functionality
Displays a table based on an array of objects. Each object is interpreted as a table row, and its properties as the table’s columns. Columns can be configured individually. The table supports:

- Sortable columns
- Filterable rows
- Render hyperlink based on cell value
- Pagination in the form of “load more” button

**Note**: the table assumes it can load _all_ required data at once on initialization, and rerenders itself after each user interaction. No data is retrieved from the server as long as the page is not reloaded.

## Usage in Nunjucks template
Import and call the macro:

``` nunjucks
{% import "components/core/auto-table/autotable.html" as autoTable %}
{{ autoTable.autoTable(id, url, sortby, config) }}
{{ autoTable.autoTableTemplates() }}
```

**Note**: The autotable templates need to be loaded _just once_ on the page, even if you have multiple auto tables:

## Usage in Python
The front-end server should return JSON for the configured endpoint. The autotable’s fetch method sends an `'Accept': 'application/json'` header that can be used in Python as follows:

``` python
from dashboard.lib.ajax import prefers_json

if (prefers_json(request)):
    return jsonify({'rows': rows})
```

The API endpoint payload should be an object containing the property `rows` with a list of items that all have the same properties:

``` json
{
    "rows": [
        {
            "id": 1,
            "name": "Jesse",
            "has_kids": False,
            "money": 9000
        },
        {
            "id": 2,
            "name": "Anne",
            "has_kids": True,
            "money": 0
        },
        ...
    ]
}
```

## Configuration

The Nunjucks macro supports the following parameters:

| Parameter    | Type   | Default  | Description |
| ------------ | ------ | -------- | ----------- |
| id | String | _(required)_ | The unique ID of the table, to make sure it doesn’t interfere with other `auto-table` on the page |
| url | String | _(required)_ | The API endpoint where the table should get its data from (formatted as JSON object; see more information below) |
| sortby | String | _(required)_ | The column that is sorted on by default |
| config | Object | _(required)_ | The column configuration for the table. This is where you can define what columns are displayed, whether they are sortable, filterable, etc. (see more below) |

The configuration is passed like this (for `config` contents, see below):

``` nunjucks
{{ autoTable.autoTable(
    id = 'users',
    url = '/users/',
    sortby = 'name',
    config) }}
```

### Configuring the table
The table’s config is an object set in Nunjucks that contains all info on how to display each of the columns in the autotable.

| Property    | Type   | Description |
| ------------ | ------ | ----------- |
| column | String | Corresponds to the property in the rows received from the API |
| title | String | Column’s title to be displayed in the table header |
| filterable | Boolean | Whether the column can be filtered. Renders a dropdown with all unique values of the data set for this column |
| sortable | Boolean | Whether the column can be sorted (A-Z). Ascending by default, user can switch between asc/desc |
| link | Object | Will display a hyperlink instead of the column’s value. Uses `text` as link text, and `path` as base path appended by the `column` property (Ex: `/user/1` for Jesse in the examples above)

Example:

``` nunjucks
{% set config = [
    {
        "column": "name",
        "title": "Name"
    },
    {
        "column": "has_kids",
        "title": "Has kids?",
        "filterable": true
    },
    {
        "column": "money",
        "title": "Happiness level",
        "sortable": true
    },
    {
        "column": "id",
        "title": "",
        "link": {
            "text": "Details",
            "path": "/user/"
        }
    }
] %}
```