config/Options/common/legend.ts

  1. /**
  2. * Copyright (c) 2017 ~ present NAVER Corp.
  3. * billboard.js project is licensed under the MIT license
  4. */
  5. /**
  6. * legend config options
  7. */
  8. export default {
  9. /**
  10. * Legend options
  11. * @name legend
  12. * @memberof Options
  13. * @type {object}
  14. * @property {object} legend Legend object
  15. * @property {boolean} [legend.show=true] Show or hide legend.
  16. * @property {boolean} [legend.hide=false] Hide legend
  17. * If true given, all legend will be hidden. If string or array given, only the legend that has the id will be hidden.
  18. * @property {string|HTMLElement} [legend.contents.bindto=undefined] Set CSS selector or element reference to bind legend items.
  19. * - **NOTE:** Should be used along with `legend.contents.template`.
  20. * @property {string|Function} [legend.contents.template="<span style='color:#fff;padding:5px;background-color:{=COLOR}'>{=TITLE}</span>"] Set item's template.<br>
  21. * - If set `string` value, within template the 'color' and 'title' can be replaced using template-like syntax string:
  22. * - {=COLOR}: data color value
  23. * - {=TITLE}: data title value
  24. * - If set `function` value, will pass following arguments to the given function:
  25. * - title {string}: data's id value
  26. * - color {string}: color string
  27. * - data {Array}: data array
  28. * @property {string} [legend.position=bottom] Change the position of legend.<br>
  29. * Available values are: `bottom`, `right` and `inset` are supported.
  30. * @property {object} [legend.inset={anchor: 'top-left',x: 10,y: 0,step: undefined}] Change inset legend attributes.<br>
  31. * This option accepts object that has the keys `anchor`, `x`, `y` and `step`.
  32. * - **anchor** decides the position of the legend:
  33. * - top-left
  34. * - top-right
  35. * - bottom-left
  36. * - bottom-right
  37. * - **x** and **y**:
  38. * - set the position of the legend based on the anchor.
  39. * - **step**:
  40. * - defines the max step the legend has (e.g. If 2 set and legend has 3 legend item, the legend 2 columns).
  41. * @property {boolean} [legend.equally=false] Set to all items have same width size.
  42. * @property {number} [legend.padding=0] Set padding value
  43. * @property {boolean} [legend.item.interaction=true] Set legend item interaction.
  44. * - **NOTE:**
  45. * - This setting will not have effect on `.toggle()` method.
  46. * - `legend.item.onXXX` listener options will work if set, regardless of this option value.
  47. * @property {boolean} [legend.item.interaction.dblclick=false] Set legend item to interact on double click.
  48. * - **NOTE:**
  49. * - Double clicking will make focused clicked dataseries only, hiding all others.
  50. * - for single click case, `click + altKey(Win)/optionKey(Mac OS)` to have same effect.
  51. * - To return initial state(which all dataseries are showing), double click current focused legend item again.
  52. * - for single click case, `click + altKey(Win)/optionKey(Mac OS)` to have same effect.
  53. * - In this case, default `click` interaction will be disabled.
  54. * @property {Function} [legend.item.onclick=undefined] Set click event handler to the legend item.
  55. * - **NOTE:**
  56. * - When set, default `click` interaction will be disabled.
  57. * - When `interaction.dblclick=true` is set, will be called on double click.
  58. * @property {Function} [legend.item.onover=undefined] Set mouse/touch over event handler to the legend item.
  59. * - **NOTE:** When set, default `mouseover` interaction will be disabled.
  60. * @property {Function} [legend.item.onout=undefined] Set mouse/touch out event handler to the legend item.
  61. * - **NOTE:** When set, default `mouseout` interaction will be disabled.
  62. * @property {number} [legend.item.tile.width=10] Set width for 'rectangle' legend item tile element.
  63. * @property {number} [legend.item.tile.height=10] Set height for 'rectangle' legend item tile element.
  64. * @property {number} [legend.item.tile.r=5] Set the radius for 'circle' legend item tile type.
  65. * @property {string} [legend.item.tile.type="rectangle"] Set legend item shape type.<br>
  66. * - **Available Values:**
  67. * - circle
  68. * - rectangle
  69. * @property {boolean} [legend.format] Set formatter function for legend text.
  70. * The argument:<br>
  71. * - `id`: Legend text value. When `data.names` is specified, will pass from it, otherwise will pass data id.
  72. * - `dataId`: When `data.names` specified, will pass the original data id. Otherwise will be undefined.
  73. * @property {boolean} [legend.tooltip=false] Show full legend text value using system tooltip(via `<title>` element).
  74. * @property {boolean} [legend.usePoint=false] Whether to use custom points in legend.
  75. * @see [Demo: format](https://naver.github.io/billboard.js/demo/#Legend.LegendFormat)
  76. * @see [Demo: item.interaction](https://naver.github.io/billboard.js/demo/#Legend.LegendItemInteraction)
  77. * @see [Demo: item.tile.type](https://naver.github.io/billboard.js/demo/#Legend.LegendItemTileType)
  78. * @see [Demo: position](https://naver.github.io/billboard.js/demo/#Legend.LegendPosition)
  79. * @see [Demo: contents.template](https://naver.github.io/billboard.js/demo/#Legend.LegendTemplate1)
  80. * @see [Demo: usePoint](https://naver.github.io/billboard.js/demo/#Legend.usePoint)
  81. * @example
  82. * legend: {
  83. * show: true,
  84. * hide: true,
  85. * //or hide: "data1"
  86. * //or hide: ["data1", "data2"]
  87. * contents: {
  88. * bindto: "#legend", // <ul id='legend'></ul>
  89. *
  90. * // will be as: <li style='background-color:#1f77b4'>data1</li>
  91. * template: "<li style='background-color:{=COLOR}'>{=TITLE}</li>"
  92. *
  93. * // or using function
  94. * template: function(id, color, data) {
  95. * // if you want omit some legend, return falsy value
  96. * if (id !== "data1") {
  97. * return "<li style='background-color:"+ color +">"+ id +"</li>";
  98. * }
  99. * }
  100. * },
  101. * position: "bottom", // bottom, right, inset
  102. * inset: {
  103. * anchor: "top-right" // top-left, top-right, bottom-left, bottom-right
  104. * x: 20,
  105. * y: 10,
  106. * step: 2
  107. * },
  108. * equally: false,
  109. * padding: 10,
  110. * item: {
  111. * // will disable default interaction
  112. * interaction: false,
  113. *
  114. * // set legend interact on double click
  115. * // by double clicking, will make focused clicked dataseries only, hiding all others.
  116. * interaction: {
  117. * dblclick: true
  118. * }
  119. *
  120. * // when set below callback, will disable corresponding default interactions
  121. * onclick: function(id, visible) {
  122. * // toggle based on the data visibility
  123. * this[visible ? "hide" : "show"](id);
  124. * },
  125. * onover: function(id, visible) { ... },
  126. * onout: function(id, visible) { ... },
  127. *
  128. * // set tile's size
  129. * tile: {
  130. * // set tile type
  131. * type: "circle" // or "rectangle" (default)
  132. *
  133. * // width & height, are only applicable for 'rectangle' legend type
  134. * width: 15,
  135. * height: 15
  136. *
  137. * // radis is only applicable for 'circle' legend type
  138. * r: 10
  139. * }
  140. * },
  141. * format: function(id, dataId) {
  142. * // set ellipsis string when length is > 5
  143. * // to get full legend value, combine with 'legend.tooltip=true'
  144. * if (id.length > 5) {
  145. * id = id.substr(0, 5) + "...";
  146. * }
  147. *
  148. * return id;
  149. * },
  150. * tooltip: true,
  151. * usePoint: true
  152. * }
  153. */
  154. legend_contents_bindto: <string | HTMLElement | undefined>undefined,
  155. legend_contents_template: <string | (() => string)
  156. | undefined>"<span style='color:#fff;padding:5px;background-color:{=COLOR}'>{=TITLE}</span>",
  157. legend_equally: false,
  158. legend_hide: false,
  159. legend_inset_anchor: <"top-left" | "top-right" | "bottom-left" | "bottom-right">"top-left",
  160. legend_inset_x: 10,
  161. legend_inset_y: 0,
  162. legend_inset_step: <number | undefined>undefined,
  163. legend_item_interaction: <boolean | {dblclick?: boolean}>true,
  164. legend_item_dblclick: false,
  165. legend_item_onclick: <Function | undefined>undefined,
  166. legend_item_onover: <Function | undefined>undefined,
  167. legend_item_onout: <Function | undefined>undefined,
  168. legend_item_tile_width: 10,
  169. legend_item_tile_height: 10,
  170. legend_item_tile_r: 5,
  171. legend_item_tile_type: <"rectangle" | "circle">"rectangle",
  172. legend_format: <Function | undefined>undefined,
  173. legend_padding: 0,
  174. legend_position: <"bottom" | "right" | "inset">"bottom",
  175. legend_show: true,
  176. legend_tooltip: false,
  177. legend_usePoint: false
  178. };