# Charts

{% hint style="success" %}
This is the official documentation of the `@forestadmin/agent` Node.js agent.
{% endhint %}

A well-known adage says, "a picture is worth a thousand words": charts help people better understand and remember information.

Forest Admin Dashboards and Analytics are meant to answer that need.

![Dashboard example](https://3861847666-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9UN5oBJhgzLadOqi7jx6%2Fuploads%2Fgit-blob-5ae091dcef45c5f92710b5196b358da04ce67887%2Fchart-dashboard-on-live-demo.png?alt=media)

## From your admin panel

Charts can be configured from the interface, without the need to write any code.

This is documented in the [User Guide](https://docs.forestadmin.com/user-guide/dashboards/charts)

## From your agent

Sometimes, chart data are closely tied to your business. Forest Admin allows you to code how the data fueling any given chart is computed.

This is done in 3 steps:

* Implement the chart data retrieval using the Agent API,
* Either:
  * create a new Chart on a Dashboard, and choose "API" as the data source,
  * or create a new Chart in the "Analytics" tab of a Collection,
* Enter the URL of the Chart you just implemented (`/forest/_charts/<chartName>` or `/forest/_charts/<collectionName>/<chartName>`).

![](https://3861847666-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9UN5oBJhgzLadOqi7jx6%2Fuploads%2Fgit-blob-a8cc720c87548edcbae1f237a9f7c271f575a081%2Fchart-api.png?alt=media)

Note that, when defining a chart from your agent:

* The type of chart defined in your agent must match your selection when adding it to a dashboard or record.
* The name of the chart must be URL-safe.

### Chart context

When defining a chart handler, the callback receives a `context` object and a `resultBuilder`.

The `context` object provides access to:

| Property                    | Availability           | Description                                                           |
| --------------------------- | ---------------------- | --------------------------------------------------------------------- |
| `context.dataSource`        | All charts             | Access to your collections for querying data                          |
| `context.caller`            | All charts             | Information about the current user (email, team, role, timezone, ...) |
| `context.parameters`        | All charts             | Custom query string / body parameters sent to the chart endpoint      |
| `context.recordId`          | Collection charts only | The id of the record the chart is displayed on                        |
| `context.compositeRecordId` | Collection charts only | The composite primary key as an array                                 |
| `context.getRecord(fields)` | Collection charts only | Helper to fetch the current record                                    |

```javascript
agent.addChart('example', async (context, resultBuilder) => {
  // Access the current user
  const { email, timezone } = context.caller;

  // Access custom parameters from the request
  const { startDate } = context.parameters;

  // Query your data
  const rows = await context.dataSource
    .getCollection('orders')
    .aggregate({}, { operation: 'Count' });

  return resultBuilder.value(rows[0]?.value ?? 0);
});
```

### Relation to Smart Charts

[Smart Charts](https://docs.forestadmin.com/developer-guide-agents-nodejs/frontend-customization/smart-charts) allow the implementation of any charts types that are not supported natively (density maps, cohorts, ...).

Coding a Chart handler from your agent, on the other hand, gives you the full freedom in how the data powering a native chart is computed.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.forestadmin.com/developer-guide-agents-nodejs/agent-customization/charts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.