Chart.js Chart

This field uses Chart.js (opens new window) to draw graphs and charts.

Pick from one of the five standard chart types and use the data function to set the data to display. The optional config function can be used to set the full chart configuration, overriding those set in the standard field properties.

See https://www.chartjs.org/docs/4.5.1/general/data-structures.html (opens new window) for the data structure of each chart type and https://www.chartjs.org/docs/4.5.1/configuration/ (opens new window) for the configuration.

Properties

Label	Description	Type Name
Summary	A brief description used to identify the chart in the Forms Designer. Use this setting to provide a short description that helps iCM users distinguish this chart from other charts. This summary will be displayed instead of the field name in the design area, it is not output on the published form.	SUMMARY
Chart Type	Choose from one of the five basic chart types: Bar Stacked bar Line Pie Doughnut	CHARTTYPE
Chart Orientation	Use this setting to toggle the orientation of the chart. The chart default will be vertical for bar charts (bars will extend vertically) and horizontal for line charts (lines extend horizontally). If your dataset follows the standard structure of labels and values then the behaviour is the following: Bar chart, horizontal: Labels will appear on the vertical axis and bars will extend horizontally. Bar chart, vertical/default: Labels will appear on the horizontal axis and bars will extend vertically. Line chart, horizontal/default: Labels will appear on the horizontal axis and lines extend horizontally. Line chart, vertical: Labels appear on the vertical axis and lines extend vertically. This will have no effect for pie or doughnut charts.	CHARTORIENTATION
Chart Title	Provide a chart title to be rendered above the chart. More customisation of the position or style can be done from the Config Function. The value of another field may be used by specifying the field's name wrapped with #s. For example, #NAME#. This must be the complete field name when an external type definition is used. This can be obtained by hovering the mouse over the required field. Form variable values can be accessed using "%VAR%" where VAR is the name of a form variable as it would be passed to helper.getVariable. This also allows properties of complex variables to be accessed, eg. "%USERPROFILE.EMAIL%".	CHARTTITLE
Aria Label	Accessible description for screen readers. This is for screen readers and should describe the chart contents. The value of another field may be used by specifying the field's name wrapped with #s. For example, #NAME#. This must be the complete field name when an external type definition is used. This can be obtained by hovering the mouse over the required field. Form variable values can be accessed using "%VAR%" where VAR is the name of a form variable as it would be passed to helper.getVariable. This also allows properties of complex variables to be accessed, eg. "%USERPROFILE.EMAIL%".	ARIALABEL
X Axis Label	Provide a label for the horizontal axis. More customisation of the position or style can be done from the Config Function. The value of another field may be used by specifying the field's name wrapped with #s. For example, #NAME#. This must be the complete field name when an external type definition is used. This can be obtained by hovering the mouse over the required field. Form variable values can be accessed using "%VAR%" where VAR is the name of a form variable as it would be passed to helper.getVariable. This also allows properties of complex variables to be accessed, eg. "%USERPROFILE.EMAIL%".	CHARTXLABEL
Y Axis Label	Provide a label for the vertical axis. More customisation of the position or style can be done from the Config Function. The value of another field may be used by specifying the field's name wrapped with #s. For example, #NAME#. This must be the complete field name when an external type definition is used. This can be obtained by hovering the mouse over the required field. Form variable values can be accessed using "%VAR%" where VAR is the name of a form variable as it would be passed to helper.getVariable. This also allows properties of complex variables to be accessed, eg. "%USERPROFILE.EMAIL%".	CHARTYLABEL
Data Function	Data function for specifying the data to be used in the chart on initialisation. This function is run server-side and should return the data object to be included in the Chart.js config. This value is passed to the Config Function, where it can be included in the final config. The returned object should follow one of the structures described in the Chart.js Documentation, specifying labels and one or more datasets.	CALCFUNCTION
Config Function	Config function for specifying the full config to be used by the chart on initialisation. This function is run client-side and should return the full Chart.js config to be used to render the chart. Any data from the data function will be passed as a variable, and the existing config based on the field properties will be available for modification. Advanced users may wish to create their own config from scratch in this function.	CONFFUNCTION
Handlers	A JavaScript function that is executed browser-side whenever the page loads or the field value changes. See Common Field Properties for an example	HANDLERS
Additional Styling Modifier	An optional CSS modifier for the field. See Common Field Properties for an example	ADDITIONALSTYLINGMODIFIER
Documentation	Add documentation to your field to help explain any complex functionality to future users. You might include information on what the field does and how it relates to other fields on the form. Notes added here are only ever visible in the Forms Designer, they can be searched for, viewed and downloaded from the action panel. See Common Field Properties for an example	DOCUMENTATION

Field Value

Charts are initially rendered server-side. You can update the data they display browser-side by setting the field's value, for example:

function(helper) { let newData = { labels: ['REVENUE', 'PLANNING', 'HOUSING', 'HIGHWAYS', 'OTHER'], datasets: [{ label: 'My Dataset', data: [10, 4, 11, 20, 3] }] }; helper.setFieldValue('CHARTFIELD', newData); }

Custom Functions

Custom functions can be called from the handlers of other fields using .invokeCustomFieldFn.

updateConfig(config) - Pass a new set of configuration to the chart

function (helper) { const curconfig = helper.invokeCustomFieldFn("FIELD1", "getConfig"); curconfig.options.plugins.title.display = false; curconfig.data.datasets[0].data.push(45); curconfig.data.labels.push(8); helper.invokeCustomFieldFn("CHARTFIELDNAME", "updateConfig", curconfig); }

getChart() - Return the complete Chart.js object function (helper) { helper.invokeCustomFieldFn("CHARTFIELDNAME", "getChart").options.plugins.title.display = false; helper.invokeCustomFieldFn("CHARTFIELDNAME", "getChart").update(); }

initChart() - Reset the chart to its initial state function (helper) { helper.invokeCustomFieldFn("CHARTFIELDNAME", "initChart"); }

Examples

Chart.js Demo
1. Each chart below demonstrates a different chart.js Chart type. All data is generated server-side via the Data Manipulation Function. The final doughnut chart also demonstrates the Config Manipulation Function.
2. Bar Chart
  
  This chart uses the standard vertical bar type with the following data function:
  function(helper, value) { return { labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'], datasets: [{ label: 'Online Transactions', data: [8420, 7650, 9310, 10240, 11580, 10970, 9830, 8740, 11200, 12450, 11890, 9760], backgroundColor: 'rgba(0,112,185,0.82)', borderColor: 'rgba(0,112,185,1)', borderWidth: 1 }] }; }
5. Stacked Bar
  
  This chart uses the standard stacked bar type with the following data function:
  function(helper, value) { return { labels: ['Q1 2023', 'Q2 2023', 'Q3 2023', 'Q4 2023', 'Q1 2024', 'Q2 2024'], datasets: [{ label: 'iCM Online', data: [12400, 14200, 15800, 17100, 19600, 22300], backgroundColor: 'rgba(0,112,185,0.85)' }, { label: 'Telephone', data: [18900, 17400, 16200, 14800, 13500, 12100], backgroundColor: 'rgba(255,153,0,0.85)' }, { label: 'In Person / Post', data: [9200, 8100, 7400, 6600, 5800, 4900], backgroundColor: 'rgba(108,117,125,0.75)' } ] }; }
8. Line Chart
  
  This chart uses the standard line type chart with the following data function:
  function(helper, value) { return { labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct'], datasets: [{ label: 'Housing Benefit Change (redesigned Apr)', data: [18.4, 17.9, 18.1, 12.3, 11.8, 11.2, 10.9, 10.6, 10.4, 10.1], borderColor: 'rgba(0,112,185,1)', backgroundColor: 'rgba(0,112,185,0.08)', tension: 0.3, fill: true, pointRadius: 5 }, { label: 'Council Tax Reduction (no change)', data: [22.1, 21.8, 22.4, 22.0, 21.7, 22.3, 21.9, 22.1, 21.8, 22.0], borderColor: 'rgba(108,117,125,0.9)', backgroundColor: 'rgba(108,117,125,0.05)', tension: 0.3, fill: true, borderDash: [6, 3], pointRadius: 5 } ] }; }
11. Pie Chart
  
  This chart uses the standard pie chart type chart with the following data function:
  function(helper, value) { return { labels: [ 'REVENUE', 'PLANNING', 'HOUSING', 'HIGHWAYS', 'OTHER' ], datasets: [{ data: [22, 17, 11, 6, 3], backgroundColor: [ 'rgba(0,153,68,0.88)', 'rgba(255,153,0,0.88)', 'rgba(220,50,47,0.88)', 'rgba(108,117,125,0.88)', 'rgba(44,62,80,0.75)' ], borderWidth: 2, borderColor: '#fff' }] }; }
14. Doughnut Chart
  
  This chart uses the doughnut chart type chart with an extra configuration function.
  
  Data function:
  function(helper, value) { return { labels: [ 'REVENUE', 'PLANNING', 'HOUSING', 'HIGHWAYS', 'OTHER' ], datasets: [{ data: [22, 17, 11, 6, 3], backgroundColor: [ 'rgba(0,153,68,0.88)', 'rgba(255,153,0,0.88)', 'rgba(220,50,47,0.88)', 'rgba(108,117,125,0.88)', 'rgba(44,62,80,0.75)' ], borderWidth: 2, borderColor: '#fff' }] }; }
  Configuration function:
  function(helper, data, config) { // CONFFUNCTION receives: // config — base config built from field properties // data — return value of CALCFUNCTION config.data = data; config.options = config.options || {}; // Widen the doughnut hole to make room for a centre annotation config.options.cutout = '68%'; // Move legend to the right so it sits beside the chart config.options.plugins = config.options.plugins || {}; config.options.plugins.legend = { position: 'right', labels: { padding: 16 } }; return config; }