Introduce scriptable options (bubble chart)

[simonbrunel]

New options.resolve helper that determines the final value to use from an array of input values (fallback) and a given context and/or index. For now, only the bubble chart support scriptable options, see documentation for details (sample)

Add scriptable options documentation and update the bubble chart dataset properties table with their scriptable and indexable capabilities and default values. Also move point style description under the element configuration section.

Replaces #4664 and #4665
Enhances #3355
Fixes #4656

[simonbrunel]

I initially implemented scriptable options as a function taking 2 arguments: an index and the context (see the datalabels plugin) - index being 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 the context.

Thoughts?

[simonbrunel]

To illustrate my previous message: let's say a third party library provides the following function:

function colorize(i) {
	return color_palette[i % color_palette.length];
}

Then, if index is provided, it's easy to plug an option to that function:

point: {
    color: colorize
}

Instead of:

point: {
    color: function(context) {
        return colorize(context.dataIndex);
    }
}

However, not sure how this use case is common or will work as-is most of the time, and having this first index argument might be burden later if we realize it's more confusing than helpful. So I think function(context) is better, just want to be sure we are all on the same page.

[simonbrunel]

Since this is part of the public API, we need to be sure we want to expose all these properties.

Thoughts?

[etimberg]

I'm OK with these properties

[simonbrunel]

At least, we need to expose chart, datasetIndex and dataIndex properties.

The other values can be retrieved as follow:

• datasetCount: chart.data.datasets.length
• dataset: chart.data.datasets[datasetIndex]
• dataCount: chart.data.datasets[datasetIndex].data.length
• data: chart.data.datasets[datasetIndex].data[dataIndex]

dataset is always needed to resolve options (since it contains some of them), so it would not cost more to include it to the context. I think most use cases of scriptable options will be to derive the data value, however data is (almost) never required to resolve options, so it's an additional cost to expose it to the context. I'm really not sure about exposing (right now) datasetCount and dataCount.

If we expose only chart, datasetIndex, dataIndex and dataset:

• datasetCount: chart.data.datasets.length
• dataCount: dataset.data.length
• data: dataset.data[dataIndex]

[etimberg]

I think chart, datasetIndex, dataIndex and dataset is the minimum. The only reason to include the other properties is to save users code if they want to get those values.

I'm also OK with the minimal set of properties to keep our code smaller.

[simonbrunel]

We can start with the minimal set and add more if requested. Like that we limit probabilities of later deprecations.

[simonbrunel]

data or value? (I picked data to be consistent with dataIndex and dataCount)

[etimberg]

I like data

[simonbrunel]

I asked because data can be confusing: could be chart.data, dataset.data or dataset.data[i]

[etimberg]

yup, I was thinking about that more. maybe change it to dataValue?

[simonbrunel]

Will remove it to expose the minimal set.

[etimberg]

Had a first pass look at this. No glaring issues. Will have a more indepth look on the weekend

[etimberg]

I like data

[etimberg]

I'm OK with these properties

[etimberg]

can probably move this out into a helper once this is merged. I think similar code is used in a number of tests

[simonbrunel]

Good point, I moved it under the jasmine namespace

[simonbrunel]

@etimberg this is the way how to read the current value with the minimal context. What do you think?

[etimberg]

Looks good 👍