ractive-ez-table/readme.md

Ractive Ez UI Table

# Ractive Ez Table

Table component for ractive.js

[Demo](https://bartvanbeurden.github.io/ractive-ez-demo/)

## Install

    npm i ractive-ez-table

```js
import 'ractive-ez-table';
import 'ractive-ez-table/themes/blue.less';
```

Requires less-loader.

## Usage

### Table

This component contains the actual tabular data

```html
<EzTable 
    items="{{ items }}"
    columns="{{ columns }}"
    groups="{{ groups }}"
    sortColumn="{{ sortColumn }}"
    selectedItems="{{ selectedItems }}"
    selectionMode="multi"
    itemHeight="30"
    labelHeight="30"
    enableGrouping
    enableSorting
    enableDragging
    enableDropping
    enableVirtualization
    on-dropitem="@this.onDropItem($1, $2)" />
```

- `items`*: Array, the tabular data
- `columns`*: Column definition
  - `name`*: unique name for the column
  - `label`*: Display name
  - `path`*: Item path to bind to this column
  - `width`*: Column width
  - `isVisible`: false if the column should be hidden
  - `viewTemplate`: Ractive template to use when viewing the item property
  - `editTemplate`: Ractive template to use when editing the item property
  - `groupValueTemplate`: Ractive template to use when grouping multiple items
  - `groupLabelTemplate`: Ractive template to use when grouping multiple items (defaults to "label: groupValueTemplate (count)")
- `groups`: Array containing columns that are "grouped by". Should always contain items that are also in `columns`.
- `sortColumn`: the column to sort on
- `selectedItems`: Array containing all the items that are selected
- `selectionMode`: `single`, `multi`, `none`
- `itemHeight`: Height (in pixels) of a single row
- `labelHeight`: Height (in pixels) of a group label
- `enableGrouping`: If true, allow group by column
- `enableSorting`: If true, allow sort by column
- `enableDragging`: If true, allow rows to be dragged
- `enableDropping`: If true, allow content to be dropped
- `enableVirtualization`: If true, enable row virtualization (rows out of view will not be rendered to improve performance)
- `dataMapper`: Used when dragging/dropping is enabled to handle drag data

#### Drag & Drop

In order to support basic drag & drop capabilities you need to define a dataMapper for every content type you wish to support.

```js
new Ractive({
    data() {
        return {
            dataMapper: {
                "application/x-ez-ractive+user": {
                    parse: content => JSON.parse(content),
                    stringify: item => JSON.stringify(item)
                },
                "application/x-ez-ractive+admin": {
                    parse: content => JSON.parse(content)
                }
            }
        }
    },

    onDropItem(data, droppedOnItem) {
        // droppedOnItem contains the item on which the data is dropped, or null if it has been dropped on the table in general

        if (data["application/x-ez-ractive+admin"]) {
            const admins = data["application/x-ez-ractive+admin"];
            // do something special with admins
        } else if (data["application/x-ez-ractive+user"]) {
            const users = data["application/x-ez-ractive+user"];
            this.push("items", users);
        }
    }
});
```

The data mapper is an object that provides a `parse` and/or `stringify` method for each content type to support.

- `parse`: function that parses a content string and returns a parsed item. When omitted, items of this content type cannot be dropped on the table
- `stringify`: function that stringifies an item. When omitted, items of this content type cannot be dragged from the table

#### Styling

Each table cell has a class name equal to the name of the column. You can use this class to select each cell of a column. For example:

```css
.ez-table .ez-table-cell.age {
    text-align: right;
}

// only apply this style to the body, not the headers
.ez-table .body .ez-table-cell.company {
    font-weight: bold;
}
```

#### Configuration

The current configuration of the table can be retrieved/updated via following methods:
- `EzTable#getConfiguration()`
- `EzTable#setConfiguration(config)`

Following configuration settings are saved:
- Grouping
- Visibility
- Sort Direction
- Sort Column

### Table Controls

This component provides advanced controls for the table configuration.  
Specifically, it allows drag & drop of columns to group by, and allows the user to show/hide specific columns.

```html
<EzTableControls 
    columns="{{ columns }}"
    groups="{{ groups }}"
    groupLabel="Drag columns here" />
```

- `columns`: See `<EzTable>` component
- `groups`: See `<EzTable>` component
- `groupLabel`: Text to be displayed when no columns are grouped.