config/Options/common/tooltip.ts

  1. /**
  2. * Copyright (c) 2017 ~ present NAVER Corp.
  3. * billboard.js project is licensed under the MIT license
  4. */
  5. /**
  6. * tooltip config options
  7. */
  8. export default {
  9. /**
  10. * Tooltip options
  11. * @name tooltip
  12. * @memberof Options
  13. * @type {object}
  14. * @property {object} tooltip Tooltip object
  15. * @property {boolean} [tooltip.show=true] Show or hide tooltip.
  16. * @property {boolean} [tooltip.doNotHide=false] Make tooltip keep showing not hiding on interaction.
  17. * @property {boolean} [tooltip.grouped=true] Set if tooltip is grouped or not for the data points.
  18. * - **NOTE:** The overlapped data points will be displayed as grouped even if set false.
  19. * @property {boolean} [tooltip.linked=false] Set if tooltips on all visible charts with like x points are shown together when one is shown.
  20. * @property {string} [tooltip.linked.name=""] Groping name for linked tooltip.<br>If specified, linked tooltip will be groped interacting to be worked only with the same name.
  21. * @property {Function} [tooltip.format.title] Set format for the title of tooltip.<br>
  22. * Specified function receives x of the data point to show.
  23. * @property {Function} [tooltip.format.name] Set format for the name of each data in tooltip.<br>
  24. * Specified function receives name, ratio, id and index of the data point to show. ratio will be undefined if the chart is not donut/pie/gauge.
  25. * @property {Function} [tooltip.format.value] Set format for the value of each data value in tooltip. If undefined returned, the row of that value will be skipped to be called.
  26. * - Will pass following arguments to the given function:
  27. * - `value {string}`: Value of the data point. If data row contains multiple or ranged(ex. candlestick, area range, etc.) value, formatter will be called as value length.
  28. * - `ratio {number}`: Ratio of the data point in the `pie/donut/gauge` and `area/bar` when contains grouped data. Otherwise is `undefined`.
  29. * - `id {string}`: id of the data point
  30. * - `index {number}`: Index of the data point
  31. * @property {Function} [tooltip.position] Set custom position function for the tooltip.<br>
  32. * This option can be used to modify the tooltip position by returning object that has top and left.
  33. * - Will pass following arguments to the given function:
  34. * - `data {Array}`: Current selected data array object.
  35. * - `width {number}`: Width of tooltip.
  36. * - `height {number}`: Height of tooltip.
  37. * - `element {SVGElement}`: Tooltip event bound element
  38. * - `pos {object}`: Current position of the tooltip.
  39. * @property {Function|object} [tooltip.contents] Set custom HTML for the tooltip.<br>
  40. * If tooltip.grouped is true, data includes multiple data points.<br><br>
  41. * Specified function receives `data` array and `defaultTitleFormat`, `defaultValueFormat` and `color` functions of the data point to show.
  42. * - **Note:**
  43. * - defaultTitleFormat:
  44. * - if `axis.x.tick.format` option will be used if set.
  45. * - otherwise, will return function based on tick format type(category, timeseries).
  46. * - defaultValueFormat:
  47. * - for Arc type (except gauge, radar), the function will return value from `(ratio * 100).toFixed(1)`.
  48. * - for Axis based types, will be used `axis.[y|y2].tick.format` option value if is set.
  49. * - otherwise, will parse value and return as number.
  50. * @property {string|HTMLElement} [tooltip.contents.bindto=undefined] Set CSS selector or element reference to bind tooltip.
  51. * - **NOTE:** When is specified, will not be updating tooltip's position.
  52. * @property {string} [tooltip.contents.template=undefined] Set tooltip's template.<br><br>
  53. * Within template, below syntax will be replaced using template-like syntax string:
  54. * - **{{ ... }}**: the doubly curly brackets indicate loop block for data rows.
  55. * - **{=CLASS_TOOLTIP}**: default tooltip class name `bb-tooltip`.
  56. * - **{=CLASS_TOOLTIP_NAME}**: default tooltip data class name (ex. `bb-tooltip-name-data1`)
  57. * - **{=TITLE}**: title value.
  58. * - **{=COLOR}**: data color.
  59. * - **{=NAME}**: data id value.
  60. * - **{=VALUE}**: data value.
  61. * @property {object} [tooltip.contents.text=undefined] Set additional text content within data loop, using template syntax.
  62. * - **NOTE:** It should contain `{ key: Array, ... }` value
  63. * - 'key' name is used as substitution within template as '{=KEY}'
  64. * - The value array length should match with the data length
  65. * @property {boolean} [tooltip.init.show=false] Show tooltip at the initialization.
  66. * @property {number} [tooltip.init.x=0] Set x Axis index(or index for Arc(donut, gauge, pie) types) to be shown at the initialization.
  67. * @property {object} [tooltip.init.position] Set the position of tooltip at the initialization.
  68. * @property {Function} [tooltip.onshow] Set a callback that will be invoked before the tooltip is shown.
  69. * @property {Function} [tooltip.onhide] Set a callback that will be invoked before the tooltip is hidden.
  70. * @property {Function} [tooltip.onshown] Set a callback that will be invoked after the tooltip is shown
  71. * @property {Function} [tooltip.onhidden] Set a callback that will be invoked after the tooltip is hidden.
  72. * @property {string|Function|null} [tooltip.order=null] Set tooltip data display order.<br><br>
  73. * **Available Values:**
  74. * - `desc`: In descending data value order
  75. * - `asc`: In ascending data value order
  76. * - `null`: It keeps the data display order<br>
  77. * **NOTE:** When `data.groups` is set, the order will follow as the stacked graph order.<br>
  78. * If want to order as data bound, set any value rather than asc, desc or null. (ex. empty string "")
  79. * - `function(data1, data2) { ... }`: [Array.sort compareFunction](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#Parameters)
  80. * @see [Demo: Hide Tooltip](https://naver.github.io/billboard.js/demo/#Tooltip.HideTooltip)
  81. * @see [Demo: Tooltip Grouping](https://naver.github.io/billboard.js/demo/#Tooltip.TooltipGrouping)
  82. * @see [Demo: Tooltip Format](https://naver.github.io/billboard.js/demo/#Tooltip.TooltipFormat)
  83. * @see [Demo: Linked Tooltip](https://naver.github.io/billboard.js/demo/#Tooltip.LinkedTooltips)
  84. * @see [Demo: Tooltip Position](https://naver.github.io/billboard.js/demo/#Tooltip.TooltipPosition)
  85. * @see [Demo: Tooltip Template](https://naver.github.io/billboard.js/demo/#Tooltip.TooltipTemplate)
  86. * @example
  87. * tooltip: {
  88. * show: true,
  89. * doNotHide: true,
  90. * grouped: false,
  91. * format: {
  92. * title: function(x) { return "Data " + x; },
  93. * name: function(name, ratio, id, index) { return name; },
  94. *
  95. * // If data row contains multiple or ranged(ex. candlestick, area range, etc.) value,
  96. * // formatter will be called as value length times.
  97. * value: function(value, ratio, id, index) { return ratio; }
  98. * },
  99. * position: function(data, width, height, element, pos) {
  100. * // data: [{x, index, id, name, value}, ...]
  101. * // width: Tooltip width
  102. * // height: Tooltip height
  103. * // element: Tooltip event bound element
  104. * // pos: {
  105. * // x: Current mouse event x position,
  106. * // y: Current mouse event y position,
  107. * // xAxis: Current x Axis position (the value is given for axis based chart type only)
  108. * // yAxis: Current y Axis position value or function(the value is given for axis based chart type only)
  109. * // }
  110. *
  111. * // yAxis will work differently per data lenghts
  112. * // - a) Single data: `yAxis` will return `number` value
  113. * // - b) Multiple data: `yAxis` will return a function with property value
  114. *
  115. * // a) Single data:
  116. * // Get y coordinate
  117. * pos.yAxis; // y axis coordinate value of current data point
  118. *
  119. * // b) Multiple data:
  120. * // Get y coordinate of value 500, where 'data1' scales(y or y2).
  121. * // When 'data.axes' option is used, data can bound to different axes.
  122. * // - when "data.axes={data1: 'y'}", wil return y value from y axis scale.
  123. * // - when "data.axes={data1: 'y2'}", wil return y value from y2 axis scale.
  124. * pos.yAxis(500, "data1"); // will return y coordinate value of data1
  125. *
  126. * pos.yAxis(500); // get y coordinate with value of 500, using y axis scale
  127. * pos.yAxis(500, null, "y2"); // get y coordinate with value of 500, using y2 axis scale
  128. *
  129. * return {
  130. * top: 0,
  131. * left: 0
  132. * }
  133. * },
  134. *
  135. * contents: function(d, defaultTitleFormat, defaultValueFormat, color) {
  136. * return ... // formatted html as you want
  137. * },
  138. *
  139. * // specify tooltip contents using template
  140. * // - example of HTML returned:
  141. * // <ul class="bb-tooltip">
  142. * // <li class="bb-tooltip-name-data1"><span>250</span><br><span style="color:#00c73c">data1</span></li>
  143. * // <li class="bb-tooltip-name-data2"><span>50</span><br><span style="color:#fa7171">data2</span></li>
  144. * // </ul>
  145. * contents: {
  146. * bindto: "#tooltip",
  147. * template: '<ul class={=CLASS_TOOLTIP}>{{' +
  148. * '<li class="{=CLASS_TOOLTIP_NAME}"><span>{=VALUE}</span><br>' +
  149. * '<span style=color:{=COLOR}>{=NAME}</span></li>' +
  150. * '}}</ul>'
  151. * }
  152. *
  153. * // with additional text value
  154. * // - example of HTML returned:
  155. * // <ul class="bb-tooltip">
  156. * // <li class="bb-tooltip-name-data1"><span>250</span><br>comment1<span style="color:#00c73c">data1</span>text1</li>
  157. * // <li class="bb-tooltip-name-data2"><span>50</span><br>comment2<span style="color:#fa7171">data2</span>text2</li>
  158. * // </ul>
  159. * contents: {
  160. * bindto: "#tooltip",
  161. * text: {
  162. * // a) 'key' name is used as substitution within template as '{=KEY}'
  163. * // b) the length should match with the data length
  164. * VAR1: ["text1", "text2"],
  165. * VAR2: ["comment1", "comment2"],
  166. * },
  167. * template: '<ul class={=CLASS_TOOLTIP}>{{' +
  168. * '<li class="{=CLASS_TOOLTIP_NAME}"><span>{=VALUE}</span>{=VAR2}<br>' +
  169. * '<span style=color:{=COLOR}>{=NAME}</span>{=VAR1}</li>' +
  170. * '}}</ul>'
  171. * }
  172. *
  173. * // sort tooltip data value display in ascending order
  174. * order: "asc",
  175. *
  176. * // specifying sort function
  177. * order: function(a, b) {
  178. * // param data passed format
  179. * {x: 5, value: 250, id: "data1", index: 5, name: "data1"}
  180. * ...
  181. * },
  182. *
  183. * // show at the initialization
  184. * init: {
  185. * show: true,
  186. * x: 2, // x Axis index (or index for Arc(donut, gauge, pie) types)
  187. * position: {
  188. * top: "150px", // specify as number or as string with 'px' unit string
  189. * left: 250 // specify as number or as string with 'px' unit string
  190. * }
  191. * },
  192. *
  193. * // fires prior tooltip is shown
  194. * onshow: function(selectedData) {
  195. * // current dataset selected
  196. * // ==> [{x: 4, value: 150, id: "data2", index: 4, name: "data2"}, ...]
  197. * selectedData;
  198. * },
  199. *
  200. * // fires prior tooltip is hidden
  201. * onhide: function(selectedData) {
  202. * // current dataset selected
  203. * // ==> [{x: 4, value: 150, id: "data2", index: 4, name: "data2"}, ...]
  204. * selectedData;
  205. * },
  206. *
  207. * // fires after tooltip is shown
  208. * onshown: function(selectedData) {
  209. * // current dataset selected
  210. * // ==> [{x: 4, value: 150, id: "data2", index: 4, name: "data2"}, ...]
  211. * selectedData;
  212. * },
  213. *
  214. * // fires after tooltip is hidden
  215. * onhidden: function(selectedData) {
  216. * // current dataset selected
  217. * // ==> [{x: 4, value: 150, id: "data2", index: 4, name: "data2"}, ...]
  218. * selectedData;
  219. * },
  220. *
  221. * // Link any tooltips when multiple charts are on the screen where same x coordinates are available
  222. * // Useful for timeseries correlation
  223. * linked: true,
  224. *
  225. * // Specify name to interact those with the same name only.
  226. * linked: {
  227. * name: "some-group"
  228. * }
  229. * }
  230. */
  231. tooltip_show: true,
  232. tooltip_doNotHide: false,
  233. tooltip_grouped: true,
  234. tooltip_format_title: <(() => string) | undefined>undefined,
  235. tooltip_format_name: <(() => string) | undefined>undefined,
  236. tooltip_format_value: <(() => number) | undefined>undefined,
  237. tooltip_position: <(() => {top: number, left: number}) | undefined>undefined,
  238. tooltip_contents: <(() => string) | {
  239. bindto: string,
  240. template: string,
  241. text?: {[key: string]: string[]}
  242. }>{},
  243. tooltip_init_show: false,
  244. tooltip_init_x: 0,
  245. tooltip_init_position: undefined,
  246. tooltip_linked: false,
  247. tooltip_linked_name: "",
  248. tooltip_onshow: () => {},
  249. tooltip_onhide: () => {},
  250. tooltip_onshown: () => {},
  251. tooltip_onhidden: () => {},
  252. tooltip_order: <string | Function | null>null
  253. };