From: Simon Brunel Date: Sat, 13 May 2017 12:13:05 +0000 (+0200) Subject: Document the new filling modes and options (#4251) X-Git-Tag: v2.6.0~2^2~9 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3ff5d489c14bbc1cd6b7fab383095cd2c25afe71;p=thirdparty%2FChart.js.git Document the new filling modes and options (#4251) --- diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 5ec896e40..041be7062 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -27,6 +27,7 @@ * [Polar Area](charts/polar.md) * [Bubble](charts/bubble.md) * [Scatter](charts/scatter.md) + * [Area](charts/area.md) * [Mixed](charts/mixed.md) * [Axes](axes/README.md) * [Cartesian](axes/cartesian/README.md) diff --git a/docs/charts/README.md b/docs/charts/README.md index 446220966..26677b04d 100644 --- a/docs/charts/README.md +++ b/docs/charts/README.md @@ -8,4 +8,6 @@ Chart.js comes with built-in chart types: * [doughnut and pie](./doughnut.md) * [bubble](./bubble.md) -To create a new chart type, see the [developer notes](../developers/charts.md#new-charts) \ No newline at end of file +[Area charts](area.md) can be built from a line or radar chart using the dataset `fill` option. + +To create a new chart type, see the [developer notes](../developers/charts.md#new-charts) diff --git a/docs/charts/area.md b/docs/charts/area.md new file mode 100644 index 000000000..d51f84754 --- /dev/null +++ b/docs/charts/area.md @@ -0,0 +1,72 @@ +# Area Charts + +Both [line](line.md) and [radar](radar.md) charts support a `fill` option on the dataset object which can be used to create area between two datasets or a dataset and a boundary, i.e. the scale `origin`, `start` or `end` (see [filling modes](#filling-modes)). + +> **Note:** this feature is implemented by the [`filler` plugin](/chartjs/Chart.js/blob/master/src/plugins/plugin.filler.js). + +## Filling modes + +| Mode | Type | Values | +| :--- | :--- | :--- | +| Absolute dataset index 1 | `Number` | `1`, `2`, `3`, ... | +| Relative dataset index 1 | `String` | `'-1'`, `'-2'`, `'+1'`, ... | +| Boundary 2 | `String` | `'start'`, `'end'`, `'origin'` | +| Disabled 3 | `Boolean` | `false` | + +> 1 dataset filling modes have been introduced in version 2.6.0
+> 2 prior version 2.6.0, boundary values was `'zero'`, `'top'`, `'bottom'` (deprecated)
+> 3 for backward compatibility, `fill: true` (default) is equivalent to `fill: 'origin'`
+ +**Example** +```javascript +new Chart(ctx, { + data: { + datasets: [ + {fill: 'origin'}, // 0: fill to 'origin' + {fill: '+2'}, // 1: fill to dataset 3 + {fill: 1}, // 2: fill to dataset 1 + {fill: false}, // 3: no fill + {fill: '-2'} // 4: fill to dataset 2 + ] + } +}) +``` + +## Configuration +| Option | Type | Default | Description | +| :--- | :--- | :--- | :--- | +| [`plugins.filler.propagate`](#propagate) | `Boolean` | `true` | Fill propagation when target is hidden + +### propagate +Boolean (default: `true`) + +If `true`, the fill area will be recursively extended to the visible target defined by the `fill` value of hidden dataset targets: + +**Example** +```javascript +new Chart(ctx, { + data: { + datasets: [ + {fill: 'origin'}, // 0: fill to 'origin' + {fill: '-1'}, // 1: fill to dataset 0 + {fill: 1}, // 2: fill to dataset 1 + {fill: false}, // 3: no fill + {fill: '-2'} // 4: fill to dataset 2 + ] + }, + options: { + plugins: { + filler: { + propagate: true + } + } + } +}) +``` + +`propagate: true`: +- if dataset 2 is hidden, dataset 4 will fill to dataset 1 +- if dataset 2 and 1 are hidden, dataset 4 will fill to `'origin'` + +`propagate: false`: +- if dataset 2 and/or 4 are hidden, dataset 4 will not be filled diff --git a/docs/charts/line.md b/docs/charts/line.md index a64f436cf..ba7911fe7 100644 --- a/docs/charts/line.md +++ b/docs/charts/line.md @@ -56,7 +56,7 @@ All point* properties can be specified as an array. If these are set to an array | `borderCapStyle` | `String` | Cap style of the line. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap) | `borderJoinStyle` | `String` | Line joint style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin) | `cubicInterpolationMode` | `String` | Algorithm used to interpolate a smooth curve from the discrete data points. [more...](#cubicInterpolationMode) -| `fill` | `Boolean/String` | How to fill the area under the line. [more...](#fill) +| `fill` | `Boolean/String` | How to fill the area under the line. See [area charts](area.md) | `lineTension` | `Number` | Bezier curve tension of the line. Set to 0 to draw straightlines. This option is ignored if monotone cubic interpolation is used. | `pointBackgroundColor` | `Color/Color[]` | The fill color for points. | `pointBorderColor` | `Color/Color[]` | The border color for points. @@ -77,20 +77,12 @@ The following interpolation modes are supported: * 'default' * 'monotone'. -The 'default' algorithm uses a custom weighted cubic interpolation, which produces pleasant curves for all types of datasets. +The 'default' algorithm uses a custom weighted cubic interpolation, which produces pleasant curves for all types of datasets. -The 'monotone' algorithm is more suited to `y = f(x)` datasets : it preserves monotonicity (or piecewise monotonicity) of the dataset being interpolated, and ensures local extremums (if any) stay at input data points. +The 'monotone' algorithm is more suited to `y = f(x)` datasets : it preserves monotonicity (or piecewise monotonicity) of the dataset being interpolated, and ensures local extremums (if any) stay at input data points. If left untouched (`undefined`), the global `options.elements.line.cubicInterpolationMode` property is used. -### fill -If `true`, fill the area under the line. The line is filled to the baseline. If the y axis has a 0 value, the line is filled to that point. If the axis has only negative values, the line is filled to the highest value. If the axis has only positive values, it is filled to the lowest value. - -String values to fill to specific locations are: -* `'zero'` -* `'top'` -* `'bottom'` - ### pointStyle The style of point. Options are: * 'circle' @@ -246,4 +238,4 @@ new Chart(ctx, { responsiveAnimationDuration: 0, // animation duration after a resize } }); -``` \ No newline at end of file +``` diff --git a/docs/charts/radar.md b/docs/charts/radar.md index 4728ad777..dd5d47b27 100644 --- a/docs/charts/radar.md +++ b/docs/charts/radar.md @@ -76,8 +76,8 @@ All point* properties can be specified as an array. If these are set to an array | `borderDashOffset` | `Number` | Offset for line dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset) | `borderCapStyle` | `String` | Cap style of the line. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap) | `borderJoinStyle` | `String` | Line joint style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin) -| `fill` | `Boolean/String` | How to fill the area under the line. [more...](#fill) -| `lineTension` | `Number` | Bezier curve tension of the line. Set to 0 to draw straightlines. +| `fill` | `Boolean/String` | How to fill the area under the line. See [area charts](area.md) +| `lineTension` | `Number` | Bezier curve tension of the line. Set to 0 to draw straightlines. | `pointBackgroundColor` | `Color/Color[]` | The fill color for points. | `pointBorderColor` | `Color/Color[]` | The border color for points. | `pointBorderWidth` | `Number/Number[]` | The width of the point border in pixels. @@ -142,4 +142,4 @@ data: { data: [20, 10, 4, 2] }] } -``` \ No newline at end of file +``` diff --git a/docs/style.css b/docs/style.css index 89e7c7053..acdd3e5e9 100644 --- a/docs/style.css +++ b/docs/style.css @@ -9,3 +9,7 @@ a.anchorjs-link { a.anchorjs-link:hover { color: rgba(65, 131, 196, 1); } + +sup { + font-size: 0.75em !important; +}