havoc/sizif_web_public.git

Samo Penic

2019-02-20 83c3f647c35477564b77cbc5b36d37d793d5442a

commit \| author \| age
83c3f6	1	# Tooltips
SP	2
	3	## Tooltip Configuration
	4
	5	The tooltip configuration is passed into the `options.tooltips` namespace. The global options for the chart tooltips is defined in `Chart.defaults.global.tooltips`.
	6
	7	\| Name \| Type \| Default \| Description
	8	\| -----\| ---- \| --------\| -----------
	9	\| `enabled` \| `Boolean` \| `true` \| Are on-canvas tooltips enabled
	10	\| `custom` \| `Function` \| `null` \| See [custom tooltip](#external-custom-tooltips) section.
	11	\| `mode` \| `String` \| `'nearest'` \| Sets which elements appear in the tooltip. [more...](../general/interactions/modes.md#interaction-modes).
	12	\| `intersect` \| `Boolean` \| `true` \| if true, the tooltip mode applies only when the mouse position intersects with an element. If false, the mode will be applied at all times.
	13	\| `position` \| `String` \| `'average'` \| The mode for positioning the tooltip. [more...](#position-modes)
	14	\| `callbacks` \| `Object` \| \| See the [callbacks section](#tooltip-callbacks)
	15	\| `itemSort` \| `Function` \| \| Sort tooltip items. [more...](#sort-callback)
	16	\| `filter` \| `Function` \| \| Filter tooltip items. [more...](#filter-callback)
	17	\| `backgroundColor` \| `Color` \| `'rgba(0,0,0,0.8)'` \| Background color of the tooltip.
	18	\| `titleFontFamily` \| `String` \| `"'Helvetica Neue', 'Helvetica', 'Arial', sans-serif"` \| title font
	19	\| `titleFontSize` \| `Number` \| `12` \| Title font size
	20	\| `titleFontStyle` \| `String` \| `'bold'` \| Title font style
	21	\| `titleFontColor` \| `Color` \| `'#fff'` \| Title font color
	22	\| `titleSpacing` \| `Number` \| `2` \| Spacing to add to top and bottom of each title line.
	23	\| `titleMarginBottom` \| `Number` \| `6` \| Margin to add on bottom of title section.
	24	\| `bodyFontFamily` \| `String` \| `"'Helvetica Neue', 'Helvetica', 'Arial', sans-serif"` \| body line font
	25	\| `bodyFontSize` \| `Number` \| `12` \| Body font size
	26	\| `bodyFontStyle` \| `String` \| `'normal'` \| Body font style
	27	\| `bodyFontColor` \| `Color` \| `'#fff'` \| Body font color
	28	\| `bodySpacing` \| `Number` \| `2` \| Spacing to add to top and bottom of each tooltip item.
	29	\| `footerFontFamily` \| `String` \| `"'Helvetica Neue', 'Helvetica', 'Arial', sans-serif"` \| footer font
	30	\| `footerFontSize` \| `Number` \| `12` \| Footer font size
	31	\| `footerFontStyle` \| `String` \| `'bold'` \| Footer font style
	32	\| `footerFontColor` \| `Color` \| `'#fff'` \| Footer font color
	33	\| `footerSpacing` \| `Number` \| `2` \| Spacing to add to top and bottom of each footer line.
	34	\| `footerMarginTop` \| `Number` \| `6` \| Margin to add before drawing the footer.
	35	\| `xPadding` \| `Number` \| `6` \| Padding to add on left and right of tooltip.
	36	\| `yPadding` \| `Number` \| `6` \| Padding to add on top and bottom of tooltip.
	37	\| `caretPadding` \| `Number` \| `2` \| Extra distance to move the end of the tooltip arrow away from the tooltip point.
	38	\| `caretSize` \| `Number` \| `5` \| Size, in px, of the tooltip arrow.
	39	\| `cornerRadius` \| `Number` \| `6` \| Radius of tooltip corner curves.
	40	\| `multiKeyBackground` \| `Color` \| `'#fff'` \| Color to draw behind the colored boxes when multiple items are in the tooltip
	41	\| `displayColors` \| `Boolean` \| `true` \| if true, color boxes are shown in the tooltip
	42	\| `borderColor` \| `Color` \| `'rgba(0,0,0,0)'` \| Color of the border
	43	\| `borderWidth` \| `Number` \| `0` \| Size of the border
	44
	45	### Position Modes
	46	Possible modes are:
	47	* 'average'
	48	* 'nearest'
	49
	50	'average' mode will place the tooltip at the average position of the items displayed in the tooltip. 'nearest' will place the tooltip at the position of the element closest to the event position.
	51
	52	New modes can be defined by adding functions to the Chart.Tooltip.positioners map.
	53
	54	Example:
	55	```javascript
	56	/**
	57	* Custom positioner
	58	* @function Chart.Tooltip.positioners.custom
	59	* @param elements {Chart.Element[]} the tooltip elements
	60	* @param eventPosition {Point} the position of the event in canvas coordinates
	61	* @returns {Point} the tooltip position
	62	*/
	63	Chart.Tooltip.positioners.custom = function(elements, eventPosition) {
	64	/** @type {Chart.Tooltip} */
	65	var tooltip = this;
	66
	67	/* ... */
	68
	69	return {
	70	x: 0,
	71	y: 0
	72	};
	73	}
	74	```
	75
	76	### Sort Callback
	77
	78	Allows sorting of [tooltip items](#tooltip-item-interface). Must implement at minimum a function that can be passed to [Array.prototype.sort](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort). This function can also accept a third parameter that is the data object passed to the chart.
	79
	80	### Filter Callback
	81
	82	Allows filtering of [tooltip items](#tooltip-item-interface). Must implement at minimum a function that can be passed to [Array.prototype.filter](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Array/filter). This function can also accept a second parameter that is the data object passed to the chart.
	83
	84	## Tooltip Callbacks
	85
	86	The tooltip label configuration is nested below the tooltip configuration using the `callbacks` key. The tooltip has the following callbacks for providing text. For all functions, 'this' will be the tooltip object created from the Chart.Tooltip constructor.
	87
	88	All functions are called with the same arguments: a [tooltip item](#tooltip-item-interface) and the data object passed to the chart. All functions must return either a string or an array of strings. Arrays of strings are treated as multiple lines of text.
	89
	90	\| Name \| Arguments \| Description
	91	\| ---- \| --------- \| -----------
	92	\| `beforeTitle` \| `Array[tooltipItem], data` \| Returns the text to render before the title.
	93	\| `title` \| `Array[tooltipItem], data` \| Returns text to render as the title of the tooltip.
	94	\| `afterTitle` \| `Array[tooltipItem], data` \| Returns text to render after the title.
	95	\| `beforeBody` \| `Array[tooltipItem], data` \| Returns text to render before the body section.
	96	\| `beforeLabel` \| `tooltipItem, data` \| Returns text to render before an individual label. This will be called for each item in the tooltip.
	97	\| `label` \| `tooltipItem, data` \| Returns text to render for an individual item in the tooltip.
	98	\| `labelColor` \| `tooltipItem, chart` \| Returns the colors to render for the tooltip item. [more...](#label-color-callback)
	99	\| `labelTextColor` \| `tooltipItem, chart` \| Returns the colors for the text of the label for the tooltip item.
	100	\| `afterLabel` \| `tooltipItem, data` \| Returns text to render after an individual label.
	101	\| `afterBody` \| `Array[tooltipItem], data` \| Returns text to render after the body section
	102	\| `beforeFooter` \| `Array[tooltipItem], data` \| Returns text to render before the footer section.
	103	\| `footer` \| `Array[tooltipItem], data` \| Returns text to render as the footer of the tooltip.
	104	\| `afterFooter` \| `Array[tooltipItem], data` \| Text to render after the footer section
	105
	106	### Label Callback
	107
	108	The label callback can change the text that displays for a given data point. A common example to round data values; the following example rounds the data to two decimal places.
	109
	110	```javascript
	111	var chart = new Chart(ctx, {
	112	type: 'line',
	113	data: data,
	114	options: {
	115	tooltips: {
	116	callbacks: {
	117	label: function(tooltipItem, data) {
	118	var label = data.datasets[tooltipItem.datasetIndex].label \|\| '';
	119
	120	if (label) {
	121	label += ': ';
	122	}
	123	label += Math.round(tooltipItem.yLabel * 100) / 100;
	124	return label;
	125	}
	126	}
	127	}
	128	}
	129	});
	130	```
	131
	132	### Label Color Callback
	133
	134	For example, to return a red box for each item in the tooltip you could do:
	135	```javascript
	136	var chart = new Chart(ctx, {
	137	type: 'line',
	138	data: data,
	139	options: {
	140	tooltips: {
	141	callbacks: {
	142	labelColor: function(tooltipItem, chart) {
	143	return {
	144	borderColor: 'rgb(255, 0, 0)',
	145	backgroundColor: 'rgb(255, 0, 0)'
	146	}
	147	},
	148	labelTextColor:function(tooltipItem, chart){
	149	return '#543453';
	150	}
	151	}
	152	}
	153	}
	154	});
	155	```
	156
	157
	158	### Tooltip Item Interface
	159
	160	The tooltip items passed to the tooltip callbacks implement the following interface.
	161
	162	```javascript
	163	{
	164	// X Value of the tooltip as a string
	165	xLabel: String,
	166
	167	// Y value of the tooltip as a string
	168	yLabel: String,
	169
	170	// Index of the dataset the item comes from
	171	datasetIndex: Number,
	172
	173	// Index of this data item in the dataset
	174	index: Number,
	175
	176	// X position of matching point
	177	x: Number,
	178
	179	// Y position of matching point
	180	y: Number,
	181	}
	182	```
	183
	184	## External (Custom) Tooltips
	185
	186	Custom tooltips allow you to hook into the tooltip rendering process so that you can render the tooltip in your own custom way. Generally this is used to create an HTML tooltip instead of an oncanvas one. You can enable custom tooltips in the global or chart configuration like so:
	187
	188	```javascript
	189	var myPieChart = new Chart(ctx, {
	190	type: 'pie',
	191	data: data,
	192	options: {
	193	tooltips: {
	194	// Disable the on-canvas tooltip
	195	enabled: false,
	196
	197	custom: function(tooltipModel) {
	198	// Tooltip Element
	199	var tooltipEl = document.getElementById('chartjs-tooltip');
	200
	201	// Create element on first render
	202	if (!tooltipEl) {
	203	tooltipEl = document.createElement('div');
	204	tooltipEl.id = 'chartjs-tooltip';
	205	tooltipEl.innerHTML = "<table></table>";
	206	document.body.appendChild(tooltipEl);
	207	}
	208
	209	// Hide if no tooltip
	210	if (tooltipModel.opacity === 0) {
	211	tooltipEl.style.opacity = 0;
	212	return;
	213	}
	214
	215	// Set caret Position
	216	tooltipEl.classList.remove('above', 'below', 'no-transform');
	217	if (tooltipModel.yAlign) {
	218	tooltipEl.classList.add(tooltipModel.yAlign);
	219	} else {
	220	tooltipEl.classList.add('no-transform');
	221	}
	222
	223	function getBody(bodyItem) {
	224	return bodyItem.lines;
	225	}
	226
	227	// Set Text
	228	if (tooltipModel.body) {
	229	var titleLines = tooltipModel.title \|\| [];
	230	var bodyLines = tooltipModel.body.map(getBody);
	231
	232	var innerHtml = '<thead>';
	233
	234	titleLines.forEach(function(title) {
	235	innerHtml += '<tr><th>' + title + '</th></tr>';
	236	});
	237	innerHtml += '</thead><tbody>';
	238
	239	bodyLines.forEach(function(body, i) {
	240	var colors = tooltipModel.labelColors[i];
	241	var style = 'background:' + colors.backgroundColor;
	242	style += '; border-color:' + colors.borderColor;
	243	style += '; border-width: 2px';
	244	var span = '<span style="' + style + '"></span>';
	245	innerHtml += '<tr><td>' + span + body + '</td></tr>';
	246	});
	247	innerHtml += '</tbody>';
	248
	249	var tableRoot = tooltipEl.querySelector('table');
	250	tableRoot.innerHTML = innerHtml;
	251	}
	252
	253	// `this` will be the overall tooltip
	254	var position = this._chart.canvas.getBoundingClientRect();
	255
	256	// Display, position, and set styles for font
	257	tooltipEl.style.opacity = 1;
	258	tooltipEl.style.position = 'absolute';
	259	tooltipEl.style.left = position.left + window.pageXOffset + tooltipModel.caretX + 'px';
	260	tooltipEl.style.top = position.top + window.pageYOffset + tooltipModel.caretY + 'px';
	261	tooltipEl.style.fontFamily = tooltipModel._bodyFontFamily;
	262	tooltipEl.style.fontSize = tooltipModel.bodyFontSize + 'px';
	263	tooltipEl.style.fontStyle = tooltipModel._bodyFontStyle;
	264	tooltipEl.style.padding = tooltipModel.yPadding + 'px ' + tooltipModel.xPadding + 'px';
	265	tooltipEl.style.pointerEvents = 'none';
	266	}
	267	}
	268	}
	269	});
	270	```
	271
	272	See [samples](http://www.chartjs.org/samples/) for examples on how to get started with custom tooltips.
	273
	274	## Tooltip Model
	275	The tooltip model contains parameters that can be used to render the tooltip.
	276
	277	```javascript
	278	{
	279	// The items that we are rendering in the tooltip. See Tooltip Item Interface section
	280	dataPoints: TooltipItem[],
	281
	282	// Positioning
	283	xPadding: Number,
	284	yPadding: Number,
	285	xAlign: String,
	286	yAlign: String,
	287
	288	// X and Y properties are the top left of the tooltip
	289	x: Number,
	290	y: Number,
	291	width: Number,
	292	height: Number,
	293	// Where the tooltip points to
	294	caretX: Number,
	295	caretY: Number,
	296
	297	// Body
	298	// The body lines that need to be rendered
	299	// Each object contains 3 parameters
	300	// before: String[] // lines of text before the line with the color square
	301	// lines: String[], // lines of text to render as the main item with color square
	302	// after: String[], // lines of text to render after the main lines
	303	body: Object[],
	304	// lines of text that appear after the title but before the body
	305	beforeBody: String[],
	306	// line of text that appear after the body and before the footer
	307	afterBody: String[],
	308	bodyFontColor: Color,
	309	_bodyFontFamily: String,
	310	_bodyFontStyle: String,
	311	_bodyAlign: String,
	312	bodyFontSize: Number,
	313	bodySpacing: Number,
	314
	315	// Title
	316	// lines of text that form the title
	317	title: String[],
	318	titleFontColor: Color,
	319	_titleFontFamily: String,
	320	_titleFontStyle: String,
	321	titleFontSize: Number,
	322	_titleAlign: String,
	323	titleSpacing: Number,
	324	titleMarginBottom: Number,
	325
	326	// Footer
	327	// lines of text that form the footer
	328	footer: String[],
	329	footerFontColor: Color,
	330	_footerFontFamily: String,
	331	_footerFontStyle: String,
	332	footerFontSize: Number,
	333	_footerAlign: String,
	334	footerSpacing: Number,
	335	footerMarginTop: Number,
	336
	337	// Appearance
	338	caretSize: Number,
	339	cornerRadius: Number,
	340	backgroundColor: Color,
	341
	342	// colors to render for each item in body[]. This is the color of the squares in the tooltip
	343	labelColors: Color[],
	344
	345	// 0 opacity is a hidden tooltip
	346	opacity: Number,
	347	legendColorBackground: Color,
	348	displayColors: Boolean,
	349	}
	350	```