npm package: @supertab/supertab-beta
Description: This repository contains Vue component which provides additional features for tabulator regarding filtering, sorting, UI etc.
Latest version: 0.1.39

# Supertab

This repository contains Vue component which provides additional features for tabulator regarding filtering, sorting, UI etc.

## Description:
Component provides additional step in column filtering, filter operation can be selected (eg. contains, greater or equal etc.). It provides columns layout and selected filters saving to local storage (last selected filters and columns layout are saved automatically). Multi-column sort and columns toggling are also supported.


**Column customization**

Supertab reads column configuration from _*headerFilterParams*_ column property.

| Column option | Short description | Value type | Available values |
| ------ | ------ | ------ | ------ |
| columnType | Column value type | int | _*1 (TEXT), 2 (NUMERIC), 3 (SELECT), 4 (DATETIME), 5 (BOOLEAN)*_ |
| defaultFilter | Default filter type which will be pre-selected | string | _*startsWith, greaterOrEqual, lowerOrEqual, eq, neq, contains, notContains, endsWith, included, notIn*_ |
| isRange | Enable filter by range | boolean | _*false is default*_ |
| values | Option is used to show available options in case column is filtered by SELECT option | array[] | _*[{text: 'Option 1', value: 1}]*_ |

## Package installation:
```ps
npm install @supertab/supertab-beta
```

## Configuration

**Plugin initialization**

Initialize supertab plugin in main.js

```js
import SupertabPlugin from '@supertab/supertab-beta'

Vue.use(SupertabPlugin, {
  locale: 'sr'
 })
```
**NOTE:**
Currently supported english (en) and serbian (sr) plugin localization.

**One-time auth configuration**

If getting data for table requeires authorization, configure methods for retrieving refresh and access token, setting access token and refresh token API endpoint.

```js
Vue.use(SupertabPlugin,
  {
    locale: 'sr',
    refreshTokenUrl: 'http://localhost:8080/api/example/token/refresh',
    getRefreshToken: getRefreshToken,
    getAccessToken: getAccessToken,
    setAccessToken: setAccessToken,
    isValidUser: isUserActive
  }
)
```

**Supertab component configuration**

Configuration which can be passed to Supertab component as props is listed bellow:

| Prop | Short description | Type | Requeired |
| ------ | ------ | ------ | ------ |
| ref | Access component through refs | string | Yes |
| refName | Represents name of component ref. Same value like ref attribute | string | Yes |
| supertabKey | Unique table key | string | Yes |
| data | Data for table | Array | Yes |
| options | Table configuration | Object | Yes |
| layouts | Array of predefined layouts and filters | Array | No |


```html
<Supertab ref='tabulator' refName='tabulator' supertabKey='localTabulator' v-bind:data="data" v-bind:options="tabulatorOptions" class="tabulator-root" ></Supertab>
```

## Basic example:

Tabulator options example: 

```js
tabulatorOptions: {
    layout: 'fitColumns',
    responsiveLayout: true,
    pagination: 'local',
    resizableColumns: 'header',
    layoutColumnsOnNewData: true,
    ajaxFiltering: false,
    ajaxSorting: false,
    paginationSizeSelector: [10, 25, 50],
    paginationSize: 10,
    columns: [
        {
            title: 'Name',
            field: 'name',
            headerSort: true,
            headerFilterParams: {
                columnType: ColumnFilterType.TEXT,
                defaultFilter: 'contains'
            },
            hozAlign: 'left',
            cssClass: 'multi-line-cell'
        },
        {
            title: 'Change in % (last 24h)',
            field: 'percent_change_24h',
            headerSort: true,
            hozAlign: 'left',
            headerFilterParams: {
                columnType: ColumnFilterType.NUMERIC,
                defaultFilter: 'greaterOrEqual'
            },
            visible: false
        },
        {
            title: 'Category',
            field: 'category',
            headerSort: true,
            hozAlign: 'left',
            formatter: (cell, formatterPatern, renderer) => {
                if (cell.getValue() === 1) {
                    return 'Category One'
                }
                if (cell.getValue() === 2) {
                    return 'Category Two'
                }
                if (cell.getValue() === 3) {
                    return 'Category Three'
                }
                return 'Category Unknown'
            },
            headerFilterParams: {
                columnType: ColumnFilterType.SELECT,
                values:
                [
                    {
                        text: 'Category 1',
                        value: 1
                    },
                    {
                        text: 'Category 2',
                        value: 2
                    },
                    {
                        text: 'Category 3',
                        value: 3
                    }
                ]
            },
            visible: false
        }
    ]
}
```

**NOTE:**
Attribute supertabKey must be unique per application due it is used to store tabulator filters, layouts and sorts by this key.

**Predefined filters and layouts:**
Multiple predefined filters and layouts can be defined through the configuration. Predefined filters and layouts should be passed as attribute value to Supertab component (_*:layouts*_ attribute). JSON contains 2 arrays under filter and layout name with keys _*columns*_ and _*filters*_. Under _*columns*_, put array which represents tabulator columns configuration with main properties (_*field, title, headerSort, hozAlign, visible*_). Under _*filters*_, put array of objects with following properties: _*field, title, inputFilterType, inputFilterValue*_. _*inputFilterType*_ uses value from one of available filter codes _*startsWith, greaterOrEqual, lowerOrEqual, eq, neq, contains, notContains, endsWith, included, notIn*_.

Example of predefined filters and layout:
```js
{
'Layout/filter name': {
    columns: [
        {
            field: 'id',
            title: 'Id',
            headerSort: true,
            hozAlign: 'left',
            visible: true
        },
        {
            field: 'name',
            title: 'Name',
            headerSort: true,
            hozAlign: 'left',
            visible: true
        },
        {
            field: 'category',
            title: 'Category',
            headerSort: true,
            hozAlign: 'left',
            visible: false
        }
    ],
    filters: [
        {
            title: 'Name',
            field: 'name',
            inputFilterType: 'notContains',
            inputFilterValue: 'coin'
        },
        {
            title: 'Category',
            field: 'category',
            inputFilterType: 'included',
            inputFilterValue: [
                1,
                2
            ]
        }
    ]
},
'Another filter': {
    columns: [],
    filters: [
        {
            title: 'Name',
            field: 'name',
            inputFilterType: 'contains',
            inputFilterValue: 'coin'
        },
        {
            title: 'Category',
            field: 'category',
            inputFilterType: 'included',
            inputFilterValue: [
                2
            ]
        }
    ]
}
```

**Initial filters:**
To setup initial filters for each column set _*initialFilters*_ property inside _*headerFilterParams*_ property. _*initialFilters*_ value should be type of Object, where property names are names of filter operations and values of those properties are filter values.

Example columns options with initial filters:

```js
tabulatorOptions: {
    layout: 'fitColumns',
    responsiveLayout: true,
    pagination: 'local',
    resizableColumns: 'header',
    layoutColumnsOnNewData: true,
    ajaxFiltering: false,
    ajaxSorting: false,
    paginationSizeSelector: [10, 25, 50],
    paginationSize: 10,
    columns: [
        {
            title: 'Id',
            field: 'id',
            headerSort: true,
            headerFilterParams: {
              columnType: ColumnFilterType.NUMERIC,
              defaultFilter: 'contains',
              initialFilters: {
                included: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
              }
            },
            hozAlign: 'left'
        },
        {
            title: 'Name',
            field: 'name',
            headerSort: true,
            headerFilterParams: {
              columnType: ColumnFilterType.TEXT,
              defaultFilter: 'contains',
              initialFilters: {
                contains: 'coin'
              }
            },
            hozAlign: 'left',
            cssClass: 'multi-line-cell'
        }
    ]
}
```

**Filters format sent to backend:**
| Operation | Query string format |
| ------ | ------ |
| Greater or equal | _*columnName*_=gte._*filterValue*_ |
| Lower or equal | _*columnName*_=lte._*filterValue*_ |
| Equal | _*columnName*_=eq._*filterValue*_ |
| Not equal | _*columnName*_=neq._*filterValue*_ |
| Contains | _*columnName*_=cs._*filterValue*_ |
| Not contains | _*columnName*_=ncs._*filterValue*_ |
| Ends with | _*columnName*_=enw._*filterValue*_ |
| Starts with | _*columnName*_=stw._*filterValue*_ |
| Included | _*columnName*_=in.(_*filterValue1*_, _*filterValue2*_, ...) |
| Not Included | _*columnName*_=nin.(_*filterValue1*_, _*filterValue2*_, ...) |


## More resources:
[NPM package page](https://www.npmjs.com/package/@supertab/supertab-beta)

[Scripts](docs/scripts.md)

[Examples (screenshots)](docs/examples.md)