View source for Template:Chart data/doc

{{documentation}}

'''Chart data''' is a template that displays a chart on a wiki page, using [https://www.chartjs.org/ Chart.js] through [[MediaWiki:Gadget-Charts-core.js]].

While you can construct the JSON for the script yourself, this template is intended to make constructing it easier by providing the wrapper and allowing you to write the configuration in lua.

==Usage==
<pre>{{Chart data|module name|width=width of chart|height=height of chart}}</pre>

The module name (Module: optional) is the name of a data module that returns the full configuration of the chart as a [https://www.mediawiki.org/wiki/Extension:Scribunto/Lua_reference_manual#mw.loadData <code>mw.loadData</code>]-compatible table. Chart data will then load that module and encode it into JSON with [https://www.mediawiki.org/wiki/Extension:Scribunto/Lua_reference_manual#mw.text.jsonEncode <code>mw.text.jsonEncode</code>].

Optional parameters height and width can be used to specify the height and width of the chart, using any unit. Ideally these should try to avoid fixed widths (px) and use relative units instead (%, vh, vw).

===Example===
<pre>{{Chart data|Chart data/xp chart|width=40vw|height=40vh}}</pre>
This will load [[Module:Chart data/xp chart]] and provide 40vw width and 40vh height.

{{Chart data|Chart data/xp chart|width=40vw|height=40vh}}

==Constructing a chart==
Data for a chart can be stored in any module - using a subpage of [[Module:Chart data]] (eg [[Module:Chart data/xp chart]]) is a convenient place if no other location is appropriate.

The returned table has three main fields in the top level table: <tt>type</tt>, which specifies the chart type; <tt>data</tt> which specifies all the data used in the chart; and <tt>options</tt> which spcifies any other configuration used in the chart. One should refer to [https://www.chartjs.org/docs/latest/ the full Chart.js documentation] for all possible options - everything except function types are supported.

===Common things to change===
;Change axes labels
The axes labels are found in key <code>options.scales.xAxes[#].scaleLabel.labelString</code>. xAxes and yAxes are arrays, so you can set separate labels for each axis. You may also need to set <code>...scaleLabel.display = true</code> to make the labels show up.

;Change tooltips
Tooltip options are in key <code>options.tooltips</code>, with the full config options available [https://www.chartjs.org/docs/latest/configuration/tooltip.html here].

;Change labels colours of datasets
Dataset options are found under key <code>data.datasets[#]</code>, and can (and should) be different per dataset. Labels are set with the label field. You can set the backgroundColor and borderColor options separately, and you may need to set showLine=true and/or fill=false.

Be careful when choosing colours so that they work in both light and dark mode adequetely (use the pre-provided colour schemes).

If you have a number of lines, you should considerhaving some of them be [https://www.chartjs.org/docs/latest/charts/line.html#line-styling dashed lines] (borderDash option).

===Helper functions===
[[Module:Chart data]] provides several helper functions for creating charts.

;<code>convertToXYFormat(y, [x])</code>
Provide this function with either just an array of y-values, or with both an array of y- and x-values. It will construct the [https://www.chartjs.org/docs/latest/charts/line.html#point Point-style] data array for use with line and scatter charts.

If no x-value array is provided, the y-values will be paired with their index (beginning at 1).

;<code>generateXYFromFunc(func, start_x, end_x, [step])</code>
This will generate Point-style data using the provided function, where y=func(x). Data is generated for x from start_x to end_x by step (default step is 1 if not specified).

;<code>jagexInterpolation(low_chance, high_chance, start_level, end_level)</code>
This will interpolate values for skilling chances using the same function as Jagex, using the specified low_chance and high_chance, from start_level to end_level by step size 1. This is a specialised version of generateXYFromFunc.

;Colours
5 preset colours are specified by the <code>colors</code> (or <code>colours</code>) array, which each element has a bg and bd key specified which are suggested colours to use for datasets. If you need more than 5 datasets, consider using dashed lines, changing point style, or similar (or multiple things). See [[Module:Chart data/test chart]] for an example config which generates this chart:

{{Chart data|Chart data/test chart|width=40vw|height=40vh}}

If you are using a bar chart or similar and you need more colours, consider using one of the following to get some new colours for datasets. Make sure to preview your chart in both light and dark mode to make sure it is still viewable in both.

* http://mkweb.bcgsc.ca/brewer/
* https://carto.com/carto-colors/
* https://github.com/EmilHvitfeldt/r-color-palettes
* https://learnui.design/tools/data-color-picker.html

<includeonly>[[Category:Formatting templates]][[Category:Mathematical templates]][[Category:Calculator templates]]</includeonly>