Mirrors/Chart.js
1
0
Fork 0
mirror of https://github.com/chartjs/Chart.js.git synced 2024-10-06 12:19:08 +02:00
Code Issues Packages Projects Releases Wiki Activity

Getting Started.... again.

Browse Source
This commit is contained in:
Tanner Linsley 2015-09-29 16:32:43 -06:00
parent 39340fa412
commit 82541248a1
1 changed files with 56 additions and 365 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

421
docs/00-Getting-Started.md
View File

@ -25,49 +25,38 @@ require(['path/to/Chartjs'], function(Chart){
});
```
You can also grab Chart.js using bower:
You can also grab Chart.js using bower, npm, or CDN:
```bash
bower install Chart.js --save
```
Also, Chart.js is available from CDN:
```bash
npm install Chart.js --save
```
https://cdnjs.com/libraries/chart.js
###Creating a chart
To create a chart, we need to instantiate the `Chart` class. To do this, we need to pass in the 2d context of where we want to draw the chart. Here's an example.
To create a chart, we need to instantiate the `Chart` class. To do this, we need to pass in the node, jQuery instance, or 2d context of the canvas of where we want to draw the chart. Here's an example.
```html
<canvas id="myChart" width="400" height="400"></canvas>
```
```javascript
// Get the context of the canvas element we want to select
// Any of the following formats may be used
var ctx = document.getElementById("myChart");
var ctx = document.getElementById("myChart").getContext("2d");
var ctx = $("myChart");
```
Once you have the element or context, you're ready to instantiate a pre-defined chart-type or create your own!
The following example instantiates a the pre-defined Polar Area chart type with a config object of data and options.
```javascript
var myNewChart = Chart.PolarArea(ctx, {
data: data,
options: config
});
```
We can also get the context of our canvas with jQuery. To do this, we need to get the DOM node out of the jQuery collection, and call the `getContext("2d")` method on that.
```javascript
// Get context with jQuery - using jQuery's .get() method.
var ctx = $("#myChart").get(0).getContext("2d");
// This will get the first returned node in the jQuery collection.
var myNewChart = new Chart(ctx);
```
After we've instantiated the Chart class on the canvas we want to draw on, Chart.js will handle the scaling for retina displays.
With the Chart class set up, we can go on to create one of the charts Chart.js has available. In the example below, we would be drawing a Polar area chart.
```javascript
var myChart = Chart.PolarArea(ctx, {
data: data,
options: options
});
```
@ -76,233 +65,119 @@ To create a scatter chart, which is a special configuration of a line chart, we
```javascript
var myScatterChart = Chart.Scatter(ctx, {
data: data,
options: options
options: options
});
```
Alternatively, we can use the more advanced API to create simple chart types. . In the example below, we are creating a line chart
Alternatively, we can use the more advanced API to create simple or advanced chart types. In the example below, we are creating a line chart.
```javascript
var myChart = new Chart(ctx, {
type: 'line', // built in types are 'line', 'bar', 'radar', 'polarArea', 'doughnut',
type: 'line', // built in types are 'line', 'bar', 'radar', 'polarArea', 'doughnut', 'scatter'
data: data,
options: options
});
```
We call a method of the name of the chart we want to create. We pass in the data for that chart type, and the options for that chart as parameters. Chart.js will merge the global defaults with chart type specific defaults, then merge any options passed in as a second argument after data.
###Global chart configuration
This concept was introduced in Chart.js 1.0 to keep configuration DRY, and allow for changing options globally across chart types, avoiding the need to specify options for each instance, or the default for a particular chart type.
Chart.js merges configurations and options in a few places with the global defaults using chart type defaults and scales defaults. This way you can be as specific as you want in your individual chart configs, or change the defaults for Chart.js as a whole.
```javascript
Chart.defaults.global = {
// Animation settings
responsive: true,
responsiveAnimationDuration: 0,
maintainAspectRatio: true,
events: ["mousemove", "mouseout", "click", "touchstart", "touchmove", "touchend"],
hover: {
onHover: null,
mode: 'single',
animationDuration: 400,
},
onClick: null,
defaultColor: 'rgba(0,0,0,0.1)',
// Element defaults defined in element extensions
elements: {},
// Legend template string
legendTemplate: "<ul class=\"<%=name.toLowerCase()%>-legend\"><% for (var i = 0; i < data.datasets.length; i++){%><li><span style=\"background-color:<%=data.datasets[i].backgroundColor%>\"><%if(data.datasets[i].label){%><%=data.datasets[i].label%><%}%></span></li><%}%></ul>",
animation: {
// Length that animation should take in ms assuming 60fps.
// Set to 0 to disable animation
duration: 1000,
// Easing type. Possible values are:
// [easeInOutQuart, linear, easeOutBounce, easeInBack, easeInOutQuad,
// easeOutQuart, easeOutQuad, easeInOutBounce, easeOutSine, easeInOutCubic,
// easeInExpo, easeInOutBack, easeInCirc, easeInOutElastic, easeOutBack,
// easeInQuad, easeInOutExpo, easeInQuart, easeOutQuint, easeInOutCirc,
// easeInSine, easeOutExpo, easeOutCirc, easeOutCubic, easeInQuint,
// easeInElastic, easeInOutSine, easeInOutQuint, easeInBounce,
// easeOutElastic, easeInCubic]
easing: "easeOutQuart",
// Function - function to call each time an animation step occurs
onProgress: function() {},
// Function - function to call when animations finish
onComplete: function() {},
},
// Boolean - if true, resize the charts when the page resizes
responsive: false,
// Boolean - if true, try to maintain the screen aspect ratio
maintainAspectRatio: true,
// Array - events to bind tooltips to
events: ["mousemove", "mouseout", "click", "touchstart", "touchmove", "touchend"],
// Hover settings
hover: {
// Function - called when the user hovers over the items.
// Parameters: array of active elements
onHover: null,
// String - hover mode. Options are 'single', 'label', and 'dataset'
// 'single' gets the nearest element
// 'label' gets all of the elements at the given dataset index (do not use for scatter charts)
// 'dataset' gets all the elements in the given dataset
mode: 'single',
// Number - duration (in ms) of the tooltip animation. 0 to disable
animationDuration: 400,
},
// Function - click handler to bind to chart area
onClick: null,
// Tooltip configuration
tooltips: {
// Boolean - if true show tooltips
tooltips:{
enabled: true,
// Function - custom tooltip function to use
custom: null,
// String - color of tooltip background
backgroundColor: "rgba(0,0,0,0.8)",
// String - fonts to use
fontFamily: "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif",
// Number - font size
fontSize: 10,
// String - font style
fontStyle: "normal",
// String - font color
fontColor: "#fff",
// String - title fonts
titleFontFamily: "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif",
// Number - title font size
titleFontSize: 12,
// String - title font style
titleFontStyle: "bold",
// String - title font color
titleFontColor: "#fff",
// Number -
yPadding: 6,
// Number -
xPadding: 6,
// Number -
caretSize: 8,
// Number - radius of rounded corners
cornerRadius: 6,
// Number -
xOffset: 10,
// String - template string to use for tooltips in single mode
template: [
'<% if(label){ %>',
'<%=label %>:',
'<%=label %>: ',
'<% } %>',
'<%=value %>',
].join(''),
// String - template string to use for tooltips in label mode
multiTemplate: [
'<%if (datasetLabel){ %>',
'<%=datasetLabel %>:',
'<%=datasetLabel %>: ',
'<% } %>',
'<%=value %>'
].join(''),
// String -
multiKeyBackground: '#fff',
},
// String - default grey color. 'rgba(0,0,0,0.1)'
defaultColor: defaultColor,
// Element defaults
elements: {
// Default settings for all line elements
arc: {
backgroundColor: Chart.defaults.global.defaultColor,
borderColor: "#fff",
borderWidth: 2
},
line: {
// Number - Bezier curve tension. Set to 0 for no bezier curves
tension: 0.4,
// String - the fill color
backgroundColor: defaultColor,
// Number - width of the line
backgroundColor: Chart.defaults.global.defaultColor,
borderWidth: 3,
// String - color of the line
borderColor: defaultColor,
// String - cap style of the line. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap
borderColor: Chart.defaults.global.defaultColor,
borderCapStyle: 'butt',
// Array - Length and spacing of dashes. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash
borderDash: [],
// Number - Offset for line dashes. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset
borderDashOffset: 0.0,
// String - line join style. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin
borderJoinStyle: 'miter',
// Boolean - if true fill in the area between the line and the x axis with the background color
fill: true,
// Boolean -
fill: true, // do we fill in the area between the line and its base axis
skipNull: true,
// Boolean -
drawNull: false,
},
// Settings for all point elements
point: {
// Number - radius of point circle
radius: 3,
// String - fill color of point
backgroundColor: defaultColor,
// Number - width of stroke of point circle
backgroundColor: Chart.defaults.global.defaultColor,
borderWidth: 1,
// String - stroke color for point
borderColor: defaultColor,
// Number - extra radius added to radius for hit detection
borderColor: Chart.defaults.global.defaultColor,
// Hover
hitRadius: 1,
// Number - radius of point circle when hovered
hoverRadius: 4,
// Number - radius of circle stroke when hovered
hoverBorderWidth: 2,
hoverBorderWidth: 1,
},
// Settings for all bar elements
rectangle: {
// String - fill color of bar
backgroundColor: defaultColor,
// Number - width of stroke of line surrounding bar fill
backgroundColor: Chart.defaults.global.defaultColor,
borderWidth: 0,
borderColor: Chart.defaults.global.defaultColor,
}
// String - Border color
borderColor: defaultColor,
},
// Settings for all arc elements
arc: {
// String - fill color
backgroundColor: defaultColor,
// String - border color
borderColor: "#fff",
// Number - border stroke width
borderWidth: 2,
},
}
}
```
@ -313,188 +188,4 @@ If for example, you wanted all charts created to be responsive, and resize when
Chart.defaults.global.responsive = true;
```
Now, every time we create a chart, `options.responsive` will be `true`.
## Scales
Scales in v2.0 of Chart.js are significantly different than those of v1.0. Multiple x & y axes are now supported. Datasets include
additional properties to bind themselves to a specific axis.
### Category Scale
The category scale will be familiar to those who have used v1.0. Labels are drawn in from the labels array included in the chart data. The category scale has
the following options.
```javascript
{
// Boolean - if true, show the scale
display: true,
// String - position of the scale. possible options are "top" and "bottom" for category scales
position: "bottom",
// grid line settings
gridLines: {
// Boolean - if true, show the grid lines
show: true,
// String - color of the grid lines
color: "rgba(0, 0, 0, 0.05)",
// Number - width of the grid lines
lineWidth: 1,
// Boolean - if true draw lines on the chart area
drawOnChartArea: true,
// Boolean - if true draw ticks in the axis area
drawTicks: true,
// Number - width of the grid line for the first index (index 0)
zeroLineWidth: 1,
// String - color of the grid line for the first index
zeroLineColor: "rgba(0,0,0,0.25)",
// Boolean - if true, offset labels from grid lines
offsetGridLines: false,
},
// label settings
labels: {
// Boolean - if true show labels
show: true,
// Boolean - if true the chart will mirror the axis labels. If the labels are on the left, mirroring the axis will render them to the right
mirror: false,
// Number - controls the padding between the label and the axis
padding: 10,
// Number: maximum auto-rotation allowed for labels.
maxRotation: 90,
// String - template string for labels
template: "<%=value%>",
// Number - label font size
fontSize: 12,
// String - label font style
fontStyle: "normal",
// String - label font color
fontColor: "#666",
// String - label font family
fontFamily: "Helvetica Neue",
// Function - Can be used to filter the labels. Passed the data label & index
userCallback: null,
},
}
```
The `userCallback` method may be useful when there are a lot of labels. The following callback would show every fifth label on a category scale
```javascript
{
scales: {
xAxes: [{
labels: {
maxRotation: 0, // set maxRotation to 0 to turn off auto-rotation
// Return an empty string to draw the grid line but hide the label
// Return `null` or `undefined` to hide the grid line
userCallback: function(labelString, index) {
return (index % 5 === 0) ? labelString : '';
}
}
}]
}
}
```
### Linear Scale
The linear scale can be used to display numerical data. It can be placed on either the x or y axis. The scatter chart type automatically configures a line chart to
use one of these scales for the x axis.
The linear scale supports the following options
```javascript
{
// Boolean - if true, show the scale
display: true,
// String - position of axis. Vertical axes can have either "left" or "right"
position: "left",
// grid line settings
gridLines: {
// Boolean - if true, show the grid lines
show: true,
// String - color of the grid lines
color: "rgba(0, 0, 0, 0.05)",
// Number - width of the grid lines
lineWidth: 1,
// Boolean - if true draw lines on the chart area
drawOnChartArea: true,
// Boolean - if true draw ticks in the axis area
drawTicks: true,
// Number - width of the grid line representing a numerical value of 0
zeroLineWidth: 1,
// String - color of the grid line representing a numerical value of 0
zeroLineColor: "rgba(0,0,0,0.25)",
},
// Boolean - if true ensures that the scale always has a 0 point
beginAtZero: false,
// Object - if specified, allows the user to override the step generation algorithm.
// Contains the following values
// start: // number to start at
// stepWidth: // size of step
// steps: // number of steps
override: null,
// label settings
labels: {
// Boolean - if true show labels
show: true,
// String - template string for labels
template: "<%=value%>",
// Function - if specified this is passed the tick value, index, and the array of all tick values. Returns a string that is used as the label for that value
userCallback: null,
// Number - label font size
fontSize: 12,
// String - label font style
fontStyle: "normal",
// String - label font color
fontColor: "#666",
// String - label font family
fontFamily: "Helvetica Neue",
},
}
```
The `userCallback` function allows the user fine grained control over how labels are generated. For instance, to generate every second labels in scientific notation, one could do the following
```javascript
{
labels: {
userCallback: function(value, index, values) {
return (index % 2 === 0) ? values.toExponential() : '';
}
}
}
```
Now, every time we create a chart, `options.responsive` will be `true`.