From 0052ceb7a1bbdade944d66da5ff10c04f3b82066 Mon Sep 17 00:00:00 2001 From: Evert Timberg Date: Sun, 29 Nov 2015 10:58:01 -0500 Subject: [PATCH] Initial update to scale documentation --- docs/01-Scales.md | 70 +++++++++++++++++++++++++++++++++++------------ 1 file changed, 52 insertions(+), 18 deletions(-) diff --git a/docs/01-Scales.md b/docs/01-Scales.md index 7882b46a3..c35a43451 100644 --- a/docs/01-Scales.md +++ b/docs/01-Scales.md @@ -8,30 +8,30 @@ anchor: scales Scales in v2.0 of Chart.js are significantly more powerful, but also different than those of v1.0. - Multiple x & y axes are now supported. - A built-in label auto-skip feature now detects would-be overlapping ticks and labels and removes every nth label to keep things displaying normally. -- Scale labels +- Scale titles are now supported Every scale extends a core scale class with the following options: Name | Type | Default | Description --- |:---:| --- | --- -type | String | Chart specific. | Type of scale being employed. Custom scales can be created. Options: ["category"](#scales-category-scale), ["linear"](#scales-linear-scale), ["logarithmic"](#scales-logarithmic-scale), ["time"](#scales-time-scale), ["radialLinear"](#scales-radial-linear-scale) -display | Boolean | true | If true, show the scale including gridlines, ticks, and labels. Overrides *gridLines.show*, *scaleLabel.show*, and *ticks.show*. +type | String | Chart specific. | Type of scale being employed. Custom scales can be created and registered with a string key. Options: ["category"](#scales-category-scale), ["linear"](#scales-linear-scale), ["logarithmic"](#scales-logarithmic-scale), ["time"](#scales-time-scale), ["radialLinear"](#scales-radial-linear-scale) +display | Boolean | true | If true, show the scale including gridlines, ticks, and labels. Overrides *gridLines.display*, *scaleLabel.display*, and *ticks.display*. **gridLines** | Array | - | Options for the grid lines that run perpendicular to the axis. -*gridLines*.show | Boolean | true | If true, show the grid lines. +*gridLines*.display | Boolean | true | *gridLines*.color | Color | "rgba(0, 0, 0, 0.1)" | Color of the grid lines. -*gridLines*.lineWidth | Number | 1 | Width of the grid lines in number of pixels. -*gridLines*.drawOnChartArea | Boolean | true | If true, draw lines on the chart area inside the axis lines. +*gridLines*.lineWidth | Number | 1 | Stroke width of grid lines +*gridLines*.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 *gridLines*.drawTicks | Boolean | true | If true, draw lines beside the ticks in the axis area beside the chart. -*gridLines*.zeroLineWidth | Number | 1 | Width of the grid line for the first index (index 0). -*gridLines*.zeroLineColor | Color | "rgba(0, 0, 0, 0.25)" | Color of the grid line for the first index (index 0). +*gridLines*.zeroLineWidth | Number | 1 | Stroke width of the grid line for the first index (index 0). +*gridLines*.zeroLineColor | Color | "rgba(0, 0, 0, 0.25)" | Stroke color of the grid line for the first index (index 0). *gridLines*.offsetGridLines | Boolean | false | If true, offset labels from grid lines. -**scaleLabel** | Array | | Label for the entire axis. -*scaleLabel*.show | Boolean | false | If true, show the scale label. -*scaleLabel*.labelString | String | "" | The text for the label. (i.e. "# of People", "Response Choices") -*scaleLabel*.fontColor | Color | "#666" | Font color for the scale label. -*scaleLabel*.fontFamily| String | "Helvetica Neue" | Font family for the scale label, follows CSS font-family options. -*scaleLabel*.fontSize | Number | 12 | Font size for the scale label. -*scaleLabel*.fontStyle | String | "normal" | Font style for the scale label, follows CSS font-style options (i.e. normal, italic, oblique, initial, inherit). +**scaleLabel** | Array | | Title for the entire axis. +*scaleLabel*.display | Boolean | false | +*scaleLabel*.labelString | String | "" | The text for the title. (i.e. "# of People", "Response Choices") +*scaleLabel*.fontColor | Color | "#666" | Font color for the scale title. +*scaleLabel*.fontFamily| String | "Helvetica Neue" | Font family for the scale title, follows CSS font-family options. +*scaleLabel*.fontSize | Number | 12 | Font size for the scale title. +*scaleLabel*.fontStyle | String | "normal" | Font style for the scale title, follows CSS font-style options (i.e. normal, italic, oblique, initial, inherit). **ticks** | Array | | Settings for the labels that run along the axis. *ticks*.beginAtZero | Boolean | false | If true the scale will be begin at 0, if false the ticks will begin at your smallest data value. *ticks*.fontColor | Color | "#666" | Font color for the tick labels. @@ -43,12 +43,12 @@ display | Boolean | true | If true, show the scale including gridlines, ticks, a *ticks*.padding | Number | 10 | Padding between the tick label and the axis. *Note: Only applicable to horizontal scales.* *ticks*.mirror | Boolean | false | Flips tick labels around axis, displaying the labels inside the chart instead of outside. *Note: Only applicable to vertical scales.* *ticks*.reverse | Boolean | false | Reverses order of tick labels. -*ticks*.show | Boolean | true | If true, show the ticks. +*ticks*.display | Boolean | true | If true, show the ticks. *ticks*.suggestedMin | Number | - | User defined minimum number for the scale, overrides minimum value *except for if* it is higher than the minimum value. *ticks*.suggestedMax | Number | - | User defined maximum number for the scale, overrides maximum value *except for if* it is lower than the maximum value. *ticks*.callback | Function | `function(value) { return '' + value; } ` | Returns the string representation of the tick value as it should be displayed on the chart. -The `userCallback` method may be used for advanced tick customization. The following callback would display every label in scientific notation +The `callback` method may be used for advanced tick customization. The following callback would display every label in scientific notation ```javascript { scales: { @@ -84,6 +84,32 @@ The linear scale extends the core scale class with the following tick template: ```javascript { position: "left", + ticks: { + callback: function(tickValue, index, ticks) { + var delta = ticks[1] - ticks[0]; + + // If we have a number like 2.5 as the delta, figure out how many decimal places we need + if (Math.abs(delta) > 1) { + if (tickValue !== Math.floor(tickValue)) { + // not an integer + delta = tickValue - Math.floor(tickValue); + } + } + + var logDelta = helpers.log10(Math.abs(delta)); + var tickString = ''; + + if (tickValue !== 0) { + var numDecimal = -1 * Math.floor(logDelta); + numDecimal = Math.max(Math.min(numDecimal, 20), 0); // toFixed has a max of 20 decimal places + tickString = tickValue.toFixed(numDecimal); + } else { + tickString = '0'; // never show decimal places for 0 + } + + return tickString; + } + } } ``` @@ -96,7 +122,15 @@ The log scale extends the core scale class with the following tick template: { position: "left", ticks: { - template: "<%var remain = value / (Math.pow(10, Math.floor(Chart.helpers.log10(value))));if (remain === 1 || remain === 2 || remain === 5) {%><%=value.toExponential()%><%} else {%><%= null %><%}%>", + callback: function(value) { + var remain = value / (Math.pow(10, Math.floor(Chart.helpers.log10(value)))); + + if (remain === 1 || remain === 2 || remain === 5) { + return value.toExponential(); + } else { + return ''; + } + } } } ```