# Custom Table

Custom tables allow you to display data in a list format based on logic encoded by the user.

## How it Works

{{< staticImage "ux/CustomTable/Widget/CustomTableWidget.png" "Custom table widget" >}}

Once the logic for data retrieval is entered, the data will be displayed in the table.

What sets the custom table apart is that the data source can be external, internal, both, or even fabricated. Moreover, custom charts can be mixed in, and additional information can be included in the expandable panel.

{{< staticImage "ux/CustomTable/Widget/CustomTableWidgetExpand.png" "Custom table expanded row" >}}

## Configuration

{{% ux-widget-configuration %}}

- **Pagination type** allows you to specify the kind of pagination you want. There may be no pagination, pagination handled by the table component (local), or server-side pagination.

If server-side pagination is chosen, the script will receive parameters like the number of elements and the page, allowing the user to decide.

- **Page elements** specifies the number of elements to show per page.
- **Allow data grouping** enables the table to group items by elements in a column.
- **Show widget filters** instructs the widget to display its filters. These filters will be passed as an additional parameter to the data retrieval function.
- **Compact the size of the table rows** will make the table rows more compact to save vertical space.
- **Expandable rows** enables an information button for expanded data on each row. The code must fill this information, or an empty space will be displayed.

{{< staticImage "ux/CustomTable/Configuration/CustomTableWidgetConfigGeneral.png" "Custom table general configuration" >}}

### Column Configuration

{{< staticImage "ux/CustomTable/Configuration/CustomTableWidgetConfigColumn.png" "Custom table column configuration" >}}

The data that will be displayed in table. In order to finish the configuration for this you must add one column at least and select a primary key. 
For every column you can define the next data:
* *Name* to show in headers
* *JSON field* is the field to read in data returned by the function. Primary key use that field
* *Sortable* permits sorting for this column
* *Groupable* allow group by this field in table
* *Filterable* allow filter by this field in table
* *Data type* of the filter (only when filterable)
* *Divisor* draws a separator between this column and the next
* *Show entity actions* enables context menu for the column allowing to perform some actions depending of the item value.

Columns supports drag&drop in order to determine the position in the table.

### Code Tab

This is where you input the necessary code to retrieve the data to be displayed.

{{< staticImage "ux/CustomTable/Configuration/CustomTableWidgetConfigCode.png" "Custom table code configuration" >}}

Depending on the options selected in the general tab, the parameters received by the function will be displayed.

The function must always return an array of JSON objects compatible with the specified configuration for the component to be able to render them.

Each time the code is updated, it must be evaluated where a preview of the result can be seen.
Finally you **MUST** return an array with a json that matches the *columns configuration*.

{{< staticImage "ux/CustomTable/Configuration/CustomTableWidgetConfigPreview.png" "Custom table code preview" >}}

### Function

Depending of the configuration receives the following parameters:

{{% ux-widget-param-entitydata %}}

{{% ux-widget-param-relatedEntities %}}

{{% ux-widget-param-timeseriesdata %}}

{{% ux-widget-param-alarmdata %}}

* *filters* introduced by the user. These filters are: 
    * **generic** widget generic filter
    * **period** widget date period filter
    * **column** json object with each column filter
    * **sort** an array containing every sorted column with its direction sorted by user preferences
    * **inherit** json object with inherited filter if 'shared filter' is enabled. This filter is composed by 'and' filter that contains standar filter, private/template filter and headers filters from the source widget.

An example:
```JSON
{
    "filters": {
        "generic": "filter introduced by the user",
        "period": {"from":"2023-03-27T10:59:27+02:00","to":null},
        "column": {
            [column value field]: {
                operator: "eq",
                value: "filter introduced by the user in colum"
            },
            [column value field]: {
                operator: "gt",
                value: "filter introduced by the user in colum"
            }
        },
        "sort": [
            {
                column: "column value field",
                direction: "asc" or "desc"
            },
            {
                column: "column value field",
                direction: "asc" or "desc"
            }
        ],
        "inherit": {
            "and": [
              { "eq": {"field.identifier._current.value": "value"}},
              { "eq": {"field2.identifier._current.value": "value2"}}
            ]
        }
    }
}
```
* *pageElements* and *page* that determines the current page to display. Only enabled when **server pagination** enabled in *table parameters*. Disabling **server pagination** quits this parameters and function must be evaluated again.

* *callback* function used to send table data only when the api/http petitions are promised

```javascript
callback(data);
```

or

```javascript
callback([{
  "field1": "value1",
  "field2": "value2"
}]);
```

{{% ux-widget-code-utils %}}

**openDashboard** -> (workspaceId, dashboardId, newPage) -> Opens the selected dashboard in selected workspace

**openEntityDashboard** -> (entityIdentifier[, organization[user if empty], resourceType['entity.device' if empty] , newPage]) -> Opens the entity's temporary dashboard


### Data format

Returned data must have one of the following formats (per item):

* *simple json data*

```
{
    "jsonfield": "value to display. It can be HTML."
}
```

* *'complex' json data*

```
{
    "jsonfield": {
        "value": "value to display. It can be HTML",
        "_style": "cell custom style",
        "_chart": "displays an echarts chart. Overrides others in this item",
        "_extension": "jsonfield like (value, _style, _chart)  plus _table. Only enabled when expandable rows enabled"
    }
}
```

*NOTE* _extension field can combine _chart and _table elements in the same item

* Element _chart
Must have an echarts config json.

* Element _table
Displays a table inside the column and overrides others in this item.

```
{
    columns: ['each', 'item', 'is', 'a', 'column],
    data: [
        ['data 1', 'in', 'columns', 'order', { jsonfield (without _extension is supported) }],
        ['data 2', 'in', 'columns', 'order', { jsonfield (without _extension is supported) }]
    ]

}
```

## Examples

{{% children sort="weight" depth="10" %}}

---