# Charts

## Supported Charts

Currently we support five kinds of charts in your template

1. Bar chart - both horizontal and vertical with ability to stack y-axis
2. Line chart
3. Pie chart
4. Doughnut chart - uses pie chart menu with the ability to set the cutout percentage to create doughnut chart
5. Radar chart

## Data structures

### General structure

Generally, you would have JSON data that looks like this for your modification,

```javascript
{
  "template": "bfba4ccf-7153-4ae4-9e2e-6c736eaffef5",
  "modifications": [
    {
      "name": "radar_chart_4",
      "labels": [
        "Speed",
        "Passing",
        "Dribbling",
        "Defense",
        "Attacking",
        "Heading"
      ],
      "datasets": [
        {
          "backgroundColor": "rgba(0, 112, 0, 0.5)",
          "data": [
            89,
            95,
            70,
            40,
            90,
            80
          ],
          "label": "Player #1"
        }
      ]
    }
  ]
}
```

Chart modification data consists of two main fields,

| Field      | Description                 |
| ---------- | --------------------------- |
| `labels`   | List of labels for the data |
| `datasets` | List of `dataset` object    |

### Dataset object

Dataset object consists of three fields,

| Field             | Description                                                                       |
| ----------------- | --------------------------------------------------------------------------------- |
| `data`            | List of numbers. The index of the number corresponds to the index of the `labels` |
| `label`           | The label or title for the dataset                                                |
| `backgroundColor` | Either a color formatted string or a list of color formatted strings              |

#### `backgroundColor`

The format depends on the type of chart.

**Color formatted string,**

* Bar chart
* Line chart
* Radar chart

**List of color formatted strings,**

* Pie chart
* Doughnut chart

Color must be formatted according to these formats,

* Hex - `#FFFFFF` 
* RGBA - `rgba(255, 255, 105, 0.8)` which support alpha transparency

{% hint style="info" %}
Pie and doughnut charts needs to take list of colors because each color represent each cut out, while the other type of charts only need a single color to represent the data.
{% endhint %}

### Data validation

Our API will validate your modification and return a user friendly error message. However, it is useful to know what is considered as a valid chart modification because chart can be trickier than the rest of the template's objects.

#### Rules

1. `labels` must be unique
2. `labels` length must match the length of the `data`
3. Dataset's `label` must be unique
4. If `backgroundColor` requires list of colors, then the length must match the length of the `labels`
5. `backgroundColor` must have the right format i.e. either hex or RGBA value

{% hint style="info" %}
Don't worry about the complexity. Our API will return proper error messages when any of the rules are not met. 
{% endhint %}

#### Using Test API Console for guidance

![Use our built-in Test API Console to know which modification are available](https://1726200576-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MYeUDPAhozAcUAcc2Lr%2F-McX2Fondl7UtqJ6gWRX%2F-McX3hshrgOAR-fHZBaT%2Fimage.png?alt=media\&token=ddc24aac-0e22-4775-a49b-8e8951dcaa2e)

{% hint style="info" %}
It is also a good idea to play around in our Test API Console page to get a feel about the correct modification. Only successful image generation will count towards your quota.
{% endhint %}

## Using Data Editor

Template editor comes with an easy to use data editor in case you want *to create a static chart* (not modified through API) or *to create a default chart* which can be overridden through API.

![Data editor user interface](https://1726200576-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MYeUDPAhozAcUAcc2Lr%2F-Mc86olLxzr8-88h7Gfd%2F-Mc8AIE9MgMZR1sdzhp7%2Fimage.png?alt=media\&token=103b35da-f713-49a3-92af-4c23badd7e55)

Data editor comes in two modes, 

* User friendly UI that validates the data as you type and will generate the proper JSON.
* JSON editor that allows you write the JSON yourself.

In both mode, data will always be validated so you don't have to worry about making mistake. The error will guide you on what to fix.

### Overriding default chart

As mentioned, you can create a default chart with all the colors and styles using data editor.

When sending the image creation request, you can choose to override the data and use the colors set with by the data editor. To do this, send the request with the same dataset `label` that you want to override.

{% tabs %}
{% tab title="Sample JSON generated by data editor" %}

```javascript
{
  "labels": [
    "Passing",
    "Dribbling"
  ],
  "datasets": [
    {
      "label": "Player #1",
      "data": [
        95,
        70
      ],
      "backgroundColor": "rgba(0, 112, 0, 0.5)"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

You can send a modification request like so to override the `data` and use existing `backgroundColor`

{% tabs %}
{% tab title="Modification Request" %}

```javascript
{
  "template": "bfba4ccf-7153-4ae4-9e2e-6c736eaffef5",
  "modifications": [
    {
      "name": "radar_chart_4",
      "datasets": [
        {
          "data": [
            30,
            40,
          ],
          "label": "Player #1"
        }
      ]
    }
  ]
}
```

{% endtab %}

{% tab title="Response" %}

```javascript
{
  "labels": [
    "Passing",
    "Dribbling"
  ],
  "datasets": [
    {
      "label": "Player #1",
      "data": [
        30,
        40
      ],
      "backgroundColor": "rgba(0, 112, 0, 0.5)"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

{% hint style="danger" %}
It is important that you **set the same dataset's `label` in the modification request** so it knows which dataset to merge with.
{% endhint %}