Introduce scriptable options (bubble chart) #4671
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,9 +1,10 @@ | ||
| # General Configuration | ||
|
|
||
| These sections describe general configuration options that can apply elsewhere in the documentation. | ||
|
|
||
| * [Responsive](./responsive.md) defines responsive chart options that apply to all charts. | ||
| * [Device Pixel Ratio](./device-pixel-ratio.md) defines the ratio between display pixels and rendered pixels. | ||
| * [Interactions](./interactions/README.md) defines options that reflect how hovering chart elements works. | ||
| * [Options](./options.md) scriptable and indexable options syntax. | ||
| * [Colors](./colors.md) defines acceptable color values. | ||
| * [Font](./fonts.md) defines various font options. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,48 @@ | ||
| # Options | ||
|
|
||
| ## Scriptable Options | ||
|
|
||
| Scriptable options also accept a function which is called for each data and that takes the unique argument `context` representing contextual information (see [option context](options.md#option-context)). | ||
|
|
||
| Example: | ||
|
|
||
| ```javascript | ||
| color: function(context) { | ||
| return context.data < 0 ? 'red' : // draw negative values in red | ||
| index%2 ? 'blue' : 'green'; // else, alternate values in blue and green | ||
| } | ||
| ``` | ||
|
|
||
| > **Note:** scriptable options are only supported by a few bubble chart options. | ||
|
|
||
| ## Indexable Options | ||
|
|
||
| Indexable options also accept an array in which each item corresponds to the element at the same index. Note that this method requires to provide as many items as data, so, in most cases, using a [function](#scriptable-options) is more appropriated if supported. | ||
|
|
||
| Example: | ||
|
|
||
| ```javascript | ||
| color: [ | ||
| 'red', // color for data at index 0 | ||
| 'blue', // color for data at index 1 | ||
| 'green', // color for data at index 2 | ||
| 'black', // color for data at index 3 | ||
| //... | ||
| ] | ||
| ``` | ||
|
|
||
| ## Option Context | ||
|
|
||
| The option context is used to give contextual information when resolving options and currently only applies to [scriptable options](#scriptable-options). | ||
|
|
||
| The context object contains the following properties: | ||
|
|
||
| - `datasetIndex`: index of the current dataset | ||
| - `datasetCount`: number of datasets | ||
| - `dataset`: dataset at index `datasetIndex` | ||
| - `dataIndex`: index of the current data | ||
| - `dataCount`: number of data | ||
| - `data`: value of the current data | ||
|
There was a problem hiding this comment.
There was a problem hiding this comment. I asked because There was a problem hiding this comment. yup, I was thinking about that more. maybe change it to There was a problem hiding this comment. Will remove it to expose the minimal set. |
||
| - `chart`: the associated chart | ||
|
There was a problem hiding this comment. Since this is part of the public API, we need to be sure we want to expose all these properties. Thoughts? There was a problem hiding this comment. At least, we need to expose The other values can be retrieved as follow:
If we expose only
There was a problem hiding this comment. I think I'm also OK with the minimal set of properties to keep our code smaller. There was a problem hiding this comment. We can start with the minimal set and add more if requested. Like that we limit probabilities of later deprecations. |
||
|
|
||
| **Important**: since the context can represent different types of entities (dataset, data, etc.), some properties may be `undefined` so be sure to test any context property before using it. | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I initially implemented scriptable options as a function taking 2 arguments: an
indexand thecontext(see the datalabels plugin) -indexbeing the dataset index if the option is resolved for a dataset element (line of a line chart) or the data index if the option is for a data element (point of a line chart).Having the index as first argument would allow to integrate with external functions (e.g. returning a color for a given index (
return index % size)). After discussing with @etimberg, we agreed to remove that first argument and keep only thecontext.Thoughts?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
To illustrate my previous message: let's say a third party library provides the following function:
Then, if
indexis provided, it's easy to plug an option to that function:Instead of:
However, not sure how this use case is common or will work as-is most of the time, and having this first
indexargument might be burden later if we realize it's more confusing than helpful. So I thinkfunction(context)is better, just want to be sure we are all on the same page.