# Custom Chart

Custom charts allow for the display of data in graphical format based on user-defined logic.

## How it Works

{{< staticImage "ux/CustomChart/Widget/CustomChartWidget.png" "Custom chart widget" >}}

Once the logic for data retrieval is entered, the data will be displayed on the widget.

What sets the custom chart apart from others is that the data source can be external, internal, both, or even fabricated. Moreover, multiple charts can be combined within the same widget.

This widget is compatible with eCharts library version 5. Multiple examples can be accessed via the following link: [eCharts](https://echarts.apache.org/examples/en/index.html)

## Configuration

{{% ux-widget-configuration %}}

- **Show widget filters** instructs the widget to display its filters. These filters will be passed as an additional parameter to the data retrieval function.

{{< staticImage "ux/CustomChart/Configuration/CustomChartWidgetConfigCode.png" "Custom chart code configuration" >}}

Here, you input the necessary code to obtain the information to be displayed.

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

The function must always return a JSON object that is compatible with eCharts' chart configuration.

Every time the code is updated, it must be evaluated where a preview of the result can be seen.

{{< staticImage "ux/CustomChart/Configuration/CustomChartWidgetConfigPreview.png" "Custom chart 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
    * **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},
        "inherit": {
            "and": [
              { "eq": {"field.identifier._current.value": "value"}},
              { "eq": {"field2.identifier._current.value": "value2"}}
            ]
        }
    }
}
```

* *callback* (optional) function used to send chart data (only when the api/http petitions are promised, use return instead)

```javascript
callback(chartConfig);
```
or

```javascript
callback({
  title: {
    text: 'Referer of a Website',
    subtext: 'Fake Data',
    left: 'center'
  },
  tooltip: {
    trigger: 'item'
  },
  legend: {
    orient: 'vertical',
    left: 'left'
  },
  series: [
    {
      name: 'Access From',
      type: 'pie',
      radius: '50%',
      data: [
        { value: 1048, name: 'Search Engine' },
        { value: 735, name: 'Direct' },
        { value: 580, name: 'Email' },
        { value: 484, name: 'Union Ads' },
        { value: 300, name: 'Video Ads' }
      ]
    }
  ]
});
```
or
```javascript
return chartConfig;
```

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

**echarts** -> [echarts core library](https://echarts.apache.org/examples/en/index.html)

**ecStat** -> [echarts stats library](https://github.com/ecomfe/echarts-stat?tab=readme-ov-file#api-reference)

**addChartEvent** -> (event, handler[(event, chartInstance) => {}] [, query]) - adds an event handler [doc](https://echarts.apache.org/en/api.html#events.Mouse%20events)


### Final code structure build by the application

```javascript
async function main(entityData,timeserieData,filters,page,pageElements,callback) {
  // YOUR CODE HERE WITH RETURN OR CALLBACK
}
```

### Examples

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

---