Chart View

The chart view shows data as 2D graphs and is powered by Apache ECharts.

<chart name="chart.sales.per.month" title="Sales per month"> (1)
  <search-fields> (2)
     <field type="datetime" name="fromDateTime" title="From Date"/>
     <field type="datetime" name="toDateTime" title="To Date"/>
  </search-fields>
  <dataset type="jpql"> (3)
  <![CDATA[
  SELECT
      SUM(self.totalAmount) AS amount,
      MONTH(self.orderDate) AS month,
      _customer.fullName AS customer
  FROM
      Order self
  LEFT JOIN
      self.customer AS _customer
  WHERE
      YEAR(self.orderDate) = YEAR(current_date)
      AND self.orderDate > :fromDateTime
      AND self.orderDate < :toDateTime
  GROUP BY
      _customer,
      MONTH(self.orderDate)
  ORDER BY
      month
  ]]>
  </dataset>
  <category key="month" type="month"/> (4)
  <series key="amount" groupBy="customer" type="bar"/> (5)
</chart>
1 define a chart view
2 define search fields (the input values can be used as query params)
3 define the data source for the chart (jpql, sql or rpc)
4 define the category axis
5 define the series for the chart

The chart view is not bound to any object but depends on dataset retrieved with JPQL/SQL queries or the given rpc (method call).

The optional <search-fields> can be used to define input fields to provide query parameter values or context for the rpc calls.

Chart types

Following chart types are supported:

  • pie

  • bar

  • hbar

  • line

  • area

  • donut

  • radar

  • gauge

  • scatter

A chart view requires following information:

  • name - unique name for the chart

  • title - chart title

  • stacked - whether to create stacked chart

  • onInit - action to call during chart init

  • <dataset> - JPQL/SQL select query with select name aliases

  • <category> - defines the X-Axis of the chart with

    • key - the dataset field to be used to categorize the data (used as X-Axis data points)

    • type - category type can be, numeric, date, time, month, year or text

    • title - category title displayed on X-Axis

  • <series> - list of data series defines the Y-Axis (for the moment only one series is allowed)

    • key - the dataset field to be used as Y-Axis data points

    • groupBy - the dataset field use to group the related data

    • title - the title for the Y-Axis

    • type - graph type, (pie, bar, hbar, line, area)

    • side - Y-Axis side (left or right)

  • <config> - custom configuration data

    • name - name of the configuration item

    • value - configuration value

  • <actions> - add actions on chart menu

Config

Charts can be configured with specific config values. These configurations may not be applicable to all chart types.

Most important config values are:

  • width - width of the chart

  • height - height of the chart

  • xFormat - custom x-axis format, like MM-YYYY or DD/MM/YYYY

  • percent - used with pie chart, show labels in percent

  • colors - specify base colors for charts, each color is used to provide 4 gradient shades

  • shades - number of gradient shades used for colors

  • hideLegend - show/hide the legend

  • axisScale - used with radar chart, define the axis scales. Values can be :

    • fixed : use a fixed scale for all axis. Value should be provided by max config.

    • distinct : use a distinct scale by axis, based on the series values. This is the default.

    • unique : use a unique scale for all axis, based on the series values.

  • maxSeries - maximum number of series (dimensions) to display. When the dataset produces more series than this limit, only the top N series by value are shown. Pie, donut, radar, line, area, and scatter charts aggregate the remaining series into an "Others" bucket; bar and horizontal bar charts drop tail series to preserve scale accuracy. Defaults to 200. Set to 0 to disable the limit. This is useful for charts with large datasets to prevent excessive memory consumption.

  • zoomThreshold - controls the data zoom slider for x-axis categories (or y-axis for horizontal bar charts). Defaults to 50. Use a positive value as a threshold, 0 to show zoom controls fully zoomed out (all data visible), or a negative value to disable zoom entirely.

  • min/max - used with gauge and radar chart(max support), define the minimum and maximum values.

  • onClick - call specified action with clicked data in context

Colors

Colors can be specified with colors config value. It can be either :

  • a pre-defined palette name : material, roma, chartjs, roma or macarons

  • comma-separated list of named and/or hex colors

If shades config value is provided (should be greater than 1), it will generate a smooth range of variations for each color by adjusting the brightness.

<chart ...>
  ...
  ...
  <!-- named and/or colors -->
  <config name="colors" value="red,green" />
  <config name="colors" value="#f44336,#4caf50" />
  <config name="colors" value="#f44336,green" />

  <!-- or pre-defined palette name -->
  <config name="colors" value="roma" />

  <!-- with custom shades -->
  <config name="shades" value="10" />

</chart>

Series limit

When a chart dataset produces a large number of series (e.g. thousands of distinct products), the browser may consume excessive memory. The maxSeries config limits the number of displayed series by keeping the top N by value. Pie, donut, radar, line, area, and scatter charts aggregate the remaining series into an "Others" bucket; bar and horizontal bar charts drop tail series to preserve scale accuracy.

<chart name="chart.sale.turnover.by.product" title="Turnover by product">
  ...
  <!-- Show only the top 20 products, aggregate the rest into "Others" -->
  <config name="maxSeries" value="20" />
</chart>

The default value is 200. To disable the limit entirely, set it to 0:

<config name="maxSeries" value="0" />

Data zoom threshold

When a chart has many x-axis categories (or y-axis categories for horizontal bar charts), a data zoom slider is automatically enabled to let users pan and zoom without overwhelming the view. The zoomThreshold config controls this behaviour:

  • Positive value — zoom slider is enabled only when the number of data points exceeds the value. The initial view shows the first N items. Defaults to 50.

  • Zero — zoom slider is always shown, fully zoomed out (all data visible). Useful when you want precise zoom controls regardless of how many data points are present.

  • Negative value — zoom is disabled entirely; no zoom controls are rendered.

<chart name="chart.sale.per.day" title="Sales per day">
  ...
  <!-- Enable zoom slider only when more than 20 data points are present -->
  <config name="zoomThreshold" value="20" />

  <!-- Always show zoom controls, fully zoomed out -->
  <config name="zoomThreshold" value="0" />

  <!-- Disable zoom controls entirely -->
  <config name="zoomThreshold" value="-1" />
</chart>

Actions

Adding actions on chart menu (gear icon on the top right) is supported using following syntax :

<chart ...>
  ...
  <actions>
    <action name="myBtn1" title="Act1" action="com.axelor.Hello:myAction1"/>
    <action name="myBtn2" title="Act2" action="some-action2"/>
  </actions>
</chart>

where :

  • name : Name of the action

  • title : Title of the button displayed on chart menu

  • action : Action to execute.

<actions> should have at least one <action>. The action will get current chart name and data in context. Example :

{
  "_chart": "chart.sales.per.month.pie",              (1)
  "_data": [{...}, ...],                              (2)
  "_domainAction": "chart:chart.sales.per.month.pie", (3)
  "_parent": {...},                                   (4)
  "fromDate": "2022-04-20",                           (5)
  "_signal": "myBtn1"                                 (6)
}
1 : Name of the chart
2 : Dataset of the chart
3 : Dashlet action
4 : Parent context
5 : Fields data defined in <search-fields>
6 : Action signal (ie, the name)