From: Jukka Kurkela Date: Mon, 8 Jun 2020 21:31:54 +0000 (+0300) Subject: Document the context properties for ticks (#7399) X-Git-Tag: v3.0.0-beta.2~101 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2a8962c32559f82bab932b78bb1669f16dffda59;p=thirdparty%2FChart.js.git Document the context properties for ticks (#7399) Document the context properties for ticks --- diff --git a/docs/docs/axes/cartesian/category.md b/docs/docs/axes/cartesian/category.md index cd572635b..8dda94b28 100644 --- a/docs/docs/axes/cartesian/category.md +++ b/docs/docs/axes/cartesian/category.md @@ -39,7 +39,7 @@ let chart = new Chart(ctx, { ## Tick Configuration Options -The category scale provides the following options for configuring tick marks. They are nested in the `ticks` sub object. These options extend the [common tick configuration](README.md#tick-configuration). +The category scale provides the following options for configuring tick marks. They are nested in the `ticks` sub object. These options extend the [common tick configuration](index.md#tick-configuration). | Name | Type | Default | Description | ---- | ---- | ------- | ----------- diff --git a/docs/docs/axes/cartesian/index.md b/docs/docs/axes/cartesian/index.md index 5095c32f3..88328a710 100644 --- a/docs/docs/axes/cartesian/index.md +++ b/docs/docs/axes/cartesian/index.md @@ -11,7 +11,7 @@ Axes that follow a cartesian grid are known as 'Cartesian Axes'. Cartesian axes ## Common Configuration -All of the included cartesian axes support a number of common options. +All of the included cartesian axes support a number of common options. These options extend the [common configuration available to all types of axes](../index.md#common-configuration). | Name | Type | Default | Description | ---- | ---- | ------- | ----------- @@ -19,7 +19,6 @@ All of the included cartesian axes support a number of common options. | `position` | `string` | | Position of the axis. [more...](#axis-position) | `axis` | `string` | | Which type of axis this is. Possible values are: `'x'`, `'y'`. If not set, this is inferred from the first character of the ID which should be `'x'` or `'y'`. | `offset` | `boolean` | `false` | If true, extra space is added to the both edges and the axis is scaled to fit into the chart area. This is set to `true` for a bar chart by default. -| `id` | `string` | | The ID is used to link datasets and scale axes together. [more...](#axis-id) | `gridLines` | `object` | | Grid line configuration. [more...](../styling.md#grid-line-configuration) | `scaleLabel` | `object` | | Scale title configuration. [more...](../labelling.md#scale-title-configuration) | `ticks` | `object` | | Tick configuration. [more...](#tick-configuration) @@ -30,7 +29,7 @@ An axis can either be positioned at the edge of the chart, at the center of the To position the axis at the edge of the chart, set the `position` option to one of: `'top'`, `'left'`, `'bottom'`, `'right'`. To position the axis at the center of the chart area, set the `position` option to `'center'`. In this mode, either the `axis` option is specified or the axis ID starts with the letter 'x' or 'y'. -To position the axis with respect to a data value, set the `position` option to an object such as: +To position the axis with respect to a data value, set the `position` option to an object such as: ```javascript { @@ -41,6 +40,7 @@ To position the axis with respect to a data value, set the `position` option to This will position the axis at a value of -20 on the axis with ID "x". For cartesian axes, only 1 axis may be specified. ### Tick Configuration + The following options are common to all cartesian axes but do not apply to other axes. | Name | Type | Default | Description diff --git a/docs/docs/axes/cartesian/linear.md b/docs/docs/axes/cartesian/linear.md index 9e223001b..431a69bb0 100644 --- a/docs/docs/axes/cartesian/linear.md +++ b/docs/docs/axes/cartesian/linear.md @@ -6,6 +6,8 @@ The linear scale is use to chart numerical data. It can be placed on either the ## Configuration Options +These options extend the [common configuration for all cartesian axes](index.md#configuration-options). + | Name | Type | Description | ---- | ---- | ----------- | `beginAtZero` | `boolean` | if true, scale will include 0 if it is not already included. @@ -14,7 +16,7 @@ The linear scale is use to chart numerical data. It can be placed on either the ## Tick Configuration Options -The following options are provided by the linear scale. They are all located in the `ticks` sub options. These options extend the [common tick configuration](README.md#tick-configuration). +The following tick options are provided by the linear scale. They are all located in the `ticks` sub options. These options extend the [common tick configuration](index.md#tick-configuration). | Name | Type | Default | Description | ---- | ---- | ------- | ----------- diff --git a/docs/docs/axes/cartesian/logarithmic.md b/docs/docs/axes/cartesian/logarithmic.md index 16eb071d7..33258f7a1 100644 --- a/docs/docs/axes/cartesian/logarithmic.md +++ b/docs/docs/axes/cartesian/logarithmic.md @@ -6,7 +6,7 @@ The logarithmic scale is use to chart numerical data. It can be placed on either ## Tick Configuration Options -The following options are provided by the linear scale. They are all located in the `ticks` sub options. These options extend the [common tick configuration](README.md#tick-configuration). +The following options are provided by the logarithmic scale. They are all located in the `ticks` sub options. These options extend the [common tick configuration](index.md#tick-configuration). | Name | Type | Default | Description | ---- | ---- | ------- | ----------- diff --git a/docs/docs/axes/cartesian/time.md b/docs/docs/axes/cartesian/time.md index 7553ae550..557b1fb41 100644 --- a/docs/docs/axes/cartesian/time.md +++ b/docs/docs/axes/cartesian/time.md @@ -30,7 +30,7 @@ When providing data for the time scale, Chart.js supports all of the formats tha ## Configuration Options -The following options are provided by the time scale. You may also set options provided by the [common tick configuration](README.md#tick-configuration). +The following options are provided by the time scale. You may also set options provided by the [common tick configuration](index.md#tick-configuration). | Name | Type | Default | Description | ---- | ---- | ------- | ----------- diff --git a/docs/docs/axes/index.md b/docs/docs/axes/index.md index cfefc2862..6466d327a 100644 --- a/docs/docs/axes/index.md +++ b/docs/docs/axes/index.md @@ -2,9 +2,9 @@ title: Axes --- -Axes are an integral part of a chart. They are used to determine how data maps to a pixel value on the chart. In a cartesian chart, there is 1 or more X axis and 1 or more Y axis to map points onto the 2 dimensional canvas. These axes are known as ['cartesian axes'](./cartesian/README.md#cartesian-axes). +Axes are an integral part of a chart. They are used to determine how data maps to a pixel value on the chart. In a cartesian chart, there is 1 or more X axis and 1 or more Y axis to map points onto the 2 dimensional canvas. These axes are known as ['cartesian axes'](./cartesian/index.md#cartesian-axes). -In a radial chart, such as a radar chart or a polar area chart, there is a single axis that maps points in the angular and radial directions. These are known as ['radial axes'](./radial/README.md#radial-axes). +In a radial chart, such as a radar chart or a polar area chart, there is a single axis that maps points in the angular and radial directions. These are known as ['radial axes'](./radial/index.md#radial-axes). Scales in Chart.js >v2.0 are significantly more powerful, but also different than those of v1.0. @@ -15,11 +15,11 @@ Scales in Chart.js >v2.0 are significantly more powerful, but also different tha ## Common Configuration -The following properties are common to all axes provided by Chart.js. +The following options are common to all axes provided by Chart.js. | Name | Type | Default | Description | ---- | ---- | ------- | ----------- -| `display` | boolean|string | `true` | Controls the axis global visibility (visible when `true`, hidden when `false`). When `display: 'auto'`, the axis is visible only if at least one associated dataset is visible. +| `display` | `boolean`\|`string` | `true` | Controls the axis global visibility (visible when `true`, hidden when `false`). When `display: 'auto'`, the axis is visible only if at least one associated dataset is visible. | `weight` | `number` | `0` | The weight used to sort the axis. Higher weights are further away from the chart area. ### Callbacks diff --git a/docs/docs/axes/labelling.md b/docs/docs/axes/labelling.md index cccb6578c..125977667 100644 --- a/docs/docs/axes/labelling.md +++ b/docs/docs/axes/labelling.md @@ -14,7 +14,7 @@ The scale label configuration is nested under the scale configuration in the `sc | `align` | `string` | `'center'` | Alignment of the axis title. Possible options are `'start'`, `'center'` and `'end'` | `labelString` | `string` | `''` | The text for the title. (i.e. "# of People" or "Response Choices"). | `font` | `Font` | `defaults.font` | See [Fonts](fonts.md) -| `padding` | number|object | `4` | Padding to apply around scale labels. Only `top` and `bottom` are implemented. +| `padding` | `number`\|`object` | `4` | Padding to apply around scale labels. Only `top` and `bottom` are implemented. ## Creating Custom Tick Formats diff --git a/docs/docs/axes/radial/index.md b/docs/docs/axes/radial/index.md index 32fe7c5fa..4622f6bc5 100644 --- a/docs/docs/axes/radial/index.md +++ b/docs/docs/axes/radial/index.md @@ -4,4 +4,4 @@ title: Radial Axes Radial axes are used specifically for the radar and polar area chart types. These axes overlay the chart area, rather than being positioned on one of the edges. One radial axis is included by default in Chart.js. -* [linear](./linear.md#linear-radial-axis) +* [radialLinear](./linear.md#linear-radial-axis) diff --git a/docs/docs/axes/styling.md b/docs/docs/axes/styling.md index 422124eec..fced70958 100644 --- a/docs/docs/axes/styling.md +++ b/docs/docs/axes/styling.md @@ -8,29 +8,31 @@ There are a number of options to allow styling an axis. There are settings to co The grid line configuration is nested under the scale configuration in the `gridLines` key. It defines options for the grid lines that run perpendicular to the axis. -| Name | Type | Default | Description -| ---- | ---- | ------- | ----------- -| `display` | `boolean` | `true` | If false, do not display grid lines for this axis. -| `borderColor` | `Color` | | If set, used as the color of the border line. If unset, the first `color` option is resolved and used. -| `borderWidth` | `number` | | If set, used as the width of the border line. If unset, the first `lineWidth` option is resolved and used. -| `circular` | `boolean` | `false` | If true, gridlines are circular (on radar chart only). -| `color` | Color|Color[]|function | `'rgba(0, 0, 0, 0.1)'` | The color of the grid lines. If specified as an array, the first color applies to the first grid line, the second to the second grid line and so on. -| `borderDash` | `number[]` | `[]` | Length and spacing of dashes on grid lines. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash). -| `borderDashOffset` | number|function | `0.0` | Offset for line dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset). -| `lineWidth` | number|number[]|function | `1` | Stroke width of grid lines. -| `drawBorder` | `boolean` | `true` | If true, draw border at the edge between the axis and the chart area. -| `drawOnChartArea` | `boolean` | `true` | If true, draw lines on the chart area inside the axis lines. This is useful when there are multiple axes and you need to control which grid lines are drawn. -| `drawTicks` | `boolean` | `true` | If true, draw lines beside the ticks in the axis area beside the chart. -| `tickMarkLength` | `number` | `10` | Length in pixels that the grid lines will draw into the axis area. -| `offsetGridLines` | `boolean` | `false` | If true, grid lines will be shifted to be between labels. This is set to `true` for a bar chart by default. -| `z` | `number` | `0` | z-index of gridline layer. Values <= 0 are drawn under datasets, > 0 on top. - -For function arguments, the function is passed a context object that is of the form: - -```javscript +| Name | Type | Scriptable | Indexable | Default | Description +| ---- | ---- | :-------------------------------: | :-----------------------------: | ------- | ----------- +| `display` | `boolean` | | | `true` | If false, do not display grid lines for this axis. +| `borderColor` | [`Color`](../general/colors.md) | | | | If set, used as the color of the border line. If unset, the first `color` option is resolved and used. +| `borderWidth` | `number` | | | | If set, used as the width of the border line. If unset, the first `lineWidth` option is resolved and used. +| `circular` | `boolean` | | | `false` | If true, gridlines are circular (on radar chart only). +| `color` | [`Color`](../general/colors.md) | Yes | Yes | `'rgba(0, 0, 0, 0.1)'` | The color of the grid lines. If specified as an array, the first color applies to the first grid line, the second to the second grid line and so on. +| `borderDash` | `number[]` | | | `[]` | Length and spacing of dashes on grid lines. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash). +| `borderDashOffset` | `number` | Yes | | `0.0` | Offset for line dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset). +| `lineWidth` | `number` | Yes | Yes | `1` | Stroke width of grid lines. +| `drawBorder` | `boolean` | | | `true` | If true, draw border at the edge between the axis and the chart area. +| `drawOnChartArea` | `boolean` | | | `true` | If true, draw lines on the chart area inside the axis lines. This is useful when there are multiple axes and you need to control which grid lines are drawn. +| `drawTicks` | `boolean` | | | `true` | If true, draw lines beside the ticks in the axis area beside the chart. +| `tickMarkLength` | `number` | | | `10` | Length in pixels that the grid lines will draw into the axis area. +| `offsetGridLines` | `boolean` | | | `false` | If true, grid lines will be shifted to be between labels. This is set to `true` for a bar chart by default. +| `z` | `number` | | | `0` | z-index of gridline layer. Values <= 0 are drawn under datasets, > 0 on top. + +The scriptable context has the following form: + +```javascript { - scale: // Scale object - tick: // Tick object + chart, + scale, + index, + tick } ``` @@ -38,16 +40,18 @@ For function arguments, the function is passed a context object that is of the f The tick configuration is nested under the scale configuration in the `ticks` key. It defines options for the tick marks that are generated by the axis. -| Name | Type | [Scriptable](../general/options.md#scriptable-options) | Default | Description -| ---- | ---- | ------- | ----------- +| Name | Type | Scriptable | Default | Description +| ---- | ---- | :-------------------------------: | ------- | ----------- | `callback` | `function` | | | Returns the string representation of the tick value as it should be displayed on the chart. See [callback](../axes/labelling.md#creating-custom-tick-formats). | `display` | `boolean` | | `true` | If true, show tick labels. | `font` | `Font` | Yes | `defaults.font` | See [Fonts](fonts.md) -| `major` | `object` | | `{}` | Major ticks configuration. +| `major` | `object` | | `{}` | [Major ticks configuration](#major-tick-configuration). | `padding` | `number` | | `0` | Sets the offset of the tick labels from the axis | `reverse` | `boolean` | | `false` | Reverses order of tick labels. | `z` | `number` | | `0` | z-index of tick layer. Useful when ticks are drawn on chart area. Values <= 0 are drawn under datasets, > 0 on top. +The scriptable context is the same as for the [Grid Line Configuration](#grid-line-configuration). + ## Major Tick Configuration The majorTick configuration is nested under the ticks configuration in the `major` key. It defines options for the major tick marks that are generated by the axis. @@ -55,3 +59,4 @@ The majorTick configuration is nested under the ticks configuration in the `majo | Name | Type | Default | Description | ---- | ---- | ------- | ----------- | `enabled` | `boolean` | `false` | If true, major ticks are generated. A major tick will affect autoskipping and `major` will be defined on ticks in the scriptable options context. + diff --git a/docs/docs/general/options.md b/docs/docs/general/options.md index 952da9b22..42d744c3b 100644 --- a/docs/docs/general/options.md +++ b/docs/docs/general/options.md @@ -20,7 +20,7 @@ color: function(context) { ## 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. +Indexable options also accept an array in which each item corresponds to the element at the same index. Note that if there are less items than data, the items are looped over. In many cases, using a [function](#scriptable-options) is more appropriate if supported. Example: @@ -46,4 +46,4 @@ The context object contains the following properties: - `datasetIndex`: index of the current dataset - `active`: true if element is active (hovered) -**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. +**Important**: since the context can represent different types of entities (dataset, data, ticks, etc.), some properties may be `undefined` so be sure to test any context property before using it. diff --git a/docs/docs/general/performance.md b/docs/docs/general/performance.md index c91e466bf..f3a9ee48d 100644 --- a/docs/docs/general/performance.md +++ b/docs/docs/general/performance.md @@ -8,11 +8,11 @@ Chart.js charts are rendered on `canvas` elements, which makes rendering quite f ### Rotation -[Specify a rotation value](https://www.chartjs.org/docs/latest/axes/cartesian/#tick-configuration) by setting `minRotation` and `maxRotation` to the same value, which avoids the chart from having to automatically determine a value to use. +[Specify a rotation value](../axes/cartesian/index.md#tick-configuration) by setting `minRotation` and `maxRotation` to the same value, which avoids the chart from having to automatically determine a value to use. ### Sampling -Set the [`ticks.sampleSize`](../axes/cartesian/README.md#tick-configuration) option. This will determine how large your labels are by looking at only a subset of them in order to render axes more quickly. This works best if there is not a large variance in the size of your labels. +Set the [`ticks.sampleSize`](../axes/cartesian/index.md#tick-configuration) option. This will determine how large your labels are by looking at only a subset of them in order to render axes more quickly. This works best if there is not a large variance in the size of your labels. ## Disable Animations diff --git a/docs/src/css/custom.css b/docs/src/css/custom.css index 74ba0f27f..fd462c15c 100644 --- a/docs/src/css/custom.css +++ b/docs/src/css/custom.css @@ -15,6 +15,10 @@ --ifm-color-primary-lighter: rgb(102, 212, 189); --ifm-color-primary-lightest: rgb(146, 224, 208); --ifm-code-font-size: 95%; + --ifm-code-color: #2472C8; + --ifm-code-background: transparent; + --ifm-code-padding-vertical: 1px; + --ifm-code-padding-horizontal: 3px; } .docusaurus-highlight-code-line {