Using keys or legends
- Introduction
- Key configuration properties
- Active key elements
- Using interactive keys on your charts
- Formatted key labels
- HTML Keys
Introduction
Using a key on your chart allows you to provide information about what the datasets that are displayed on the chart represent.
Keys can be used in two different modes - a horizontal one designed to sit in the margins of the chart, and a vertical one that is designed to sit over the chart.
Key configuration properties
The available key properties and their defaults are listed below (some chart types have slightly different defaults to suit):
Property | Description | Default |
---|---|---|
key | An array of key elements (this is the text that is displayed in the key. | [] (An empty array) |
keyHalign | The horizontal alignment of the key | right |
keyValign | [Pie chart only] The vertical alignment of the key. By default this is null but you can set this to center in order to vertically center the key. There's a demo in the download archive that shows this called pie-vertically-centered-key.html This property takes precedence over the keyPositionY property. | null |
keyPosition | This determines the positioning/layout of the key. Possible values are graph and margin. | graph |
keyPositionMarginBoxed | When the key is in margin mode this determines if it sits in a box. | false |
keyPositionMarginHSpace | When the key is in margin mode this adds horizontal space to the key items (ie they're more spaced out). | 0 |
keyPositionGraphBoxed | When the key is in graph mode this determines if it sits in a box. | true |
keyPositionX | This allows you to specify an X coordinate for the key. | null |
keyPositionY | This allows you to specify a Y coordinate for the key. | null |
keyPositionOffsetx | This allows you to offset the X coordinate for the key by a given amount. | null |
keyPositionOffsety | This allows you to offset the Y coordinate for the key by a given amount. | null |
keyShadow | This controls whether the key has a shadow or not. | false |
keyShadowOffsetx | This controls the X offset for the shadow. | 2 |
keyShadowOffsety | This controls the Y offset for the shadow. | 2 |
keyShadowColor | This controls the color of the shadow. | #666 |
keyShadowBlur | This controls the blur that's applied to the shadow. | 3 |
keyColors | If the calculated colors are not what you want to see - this allows you to specify your own colors. | null |
keyColorShape | This is the shape that the color blob takes on. | square (can be an array of shapes) |
keyBackground | The background of the key. | white |
keyRounded | Whether the corners of the key are square or rounded. | true |
keyLinewidth | The linewidth used for the key. | 1 |
keyLabelsFont | The font used for the key text. | [same as the textFont setting] |
keyLabelsSize | The size of the text in the key. | [same as the textSize setting] |
keyLabelsColor | The color of the text in the key. | black |
keyLabelsBold | Whether the text in the key is bold or not. | false |
keyLabelsItalic | Whether the text in the key is italic or not. | false |
keyLabelsOffsetx | The offset that gets applied to the X coordinate to the key text. | 0 |
keyLabelsOffsety | The offset that gets applied to the Y coordinate to the key text. | 0 |
keyTextAccessible | By default the key text IS NOT accessible but by using this setting you can override this. | null |
keyInteractive | Whether the key is interactive or not. Not all chart types support this. | false |
keyInteractiveHighlightChartFill | The highlight fill color that's used to highlight the chart by the interactive key. | rgba(255,255,255,0.7) |
keyInteractiveHighlightChartStroke | The highlight stroke color that's used to highlight the chart by the interactive key. | black |
keyFormattedDecimals | This stipulates how many decimals are used in the key labels. Formatted key labels are documented below. | 0 |
keyFormattedPoint | The character(s) that's used as the decimal separator in the %{value_formatted} macro. Formatted key labels are documented below. | . |
keyFormattedThousand | The character(s) that's used as the thousand separator in the %{value_formatted} macro. Formatted key labels are documented below. | , |
keyFormattedUnitsPre | The units to add to the value. These units are positioned before the number. Formatted key labels are documented below. | [an empty string] |
keyFormattedUnitsPost | The units to add to the value. These units are positioned after the number. Formatted key labels are documented below. | [an empty string] |
keyFormattedValueSpecific | Instead of the key code calculating the value - which might not be what you want in some cases - you can use this property to specify the exact values that you want to be used in the key (this specifies just the values - not the whole string). | null |
keyFormattedItemsCount | You can use this property to specify the number of key items that should be shown. Normally this is calculated automatically for you. | null |
An array of key elements (this is the text that is displayed in the key.
Default: [] (An empty array)
keyHalign
The horizontal alignment of the key
Default: right
keyValign
[Pie chart only] The vertical alignment of the key. By default this is
null
but you can set this to center
in order to vertically center the key. There's a demo in the download archive that shows this called pie-vertically-centered-key.html
This property takes precedence over the keyPositionY
property.Default: null
keyPosition
This determines the positioning/layout of the key. Possible values are graph and margin.
Default: graph
keyPositionMarginBoxed
When the key is in margin mode this determines if it sits in a box.
Default: false
keyPositionMarginHSpace
When the key is in margin mode this adds horizontal space to the key items (ie they're more spaced out).
Default: 0
keyPositionGraphBoxed
When the key is in graph mode this determines if it sits in a box.
Default: true
keyPositionX
This allows you to specify an X coordinate for the key.
Default: null
keyPositionY
This allows you to specify a Y coordinate for the key.
Default: null
keyPositionOffsetx
This allows you to offset the X coordinate for the key by a given amount.
Default: null
keyPositionOffsety
This allows you to offset the Y coordinate for the key by a given amount.
Default: null
keyShadow
This controls whether the key has a shadow or not.
Default: false
keyShadowOffsetx
This controls the X offset for the shadow.
Default: 2
keyShadowOffsety
This controls the Y offset for the shadow.
Default: 2
keyShadowColor
This controls the color of the shadow.
Default: #666
keyShadowBlur
This controls the blur that's applied to the shadow.
Default: 3
keyColors
If the calculated colors are not what you want to see - this allows you to specify your own colors.
Default: null
keyColorShape
This is the shape that the color blob takes on.
Default: square (can be an array of shapes)
keyBackground
The background of the key.
Default: white
keyRounded
Whether the corners of the key are square or rounded.
Default: true
keyLinewidth
The
linewidth
used for the key.Default: 1
keyLabelsFont
The font used for the key text.
Default: [same as the textFont setting]
keyLabelsSize
The size of the text in the key.
Default: [same as the textSize setting]
keyLabelsColor
The color of the text in the key.
Default: black
keyLabelsBold
Whether the text in the key is bold or not.
Default: false
keyLabelsItalic
Whether the text in the key is italic or not.
Default: false
keyLabelsOffsetx
The offset that gets applied to the X coordinate to the key text.
Default: 0
keyLabelsOffsety
The offset that gets applied to the Y coordinate to the key text.
Default: 0
keyTextAccessible
By default the key text IS NOT accessible but by using this setting you can override this.
Default: null
keyInteractive
Whether the key is interactive or not. Not all chart types support this.
Default: false
keyInteractiveHighlightChartFill
The highlight fill color that's used to highlight the chart by the interactive key.
Default: rgba(255,255,255,0.7)
keyInteractiveHighlightChartStroke
The highlight stroke color that's used to highlight the chart by the interactive key.
Default: black
keyFormattedDecimals
This stipulates how many decimals are used in the key labels. Formatted key labels are documented below.
Default: 0
keyFormattedPoint
The character(s) that's used as the decimal separator in the
%{value_formatted}
macro. Formatted key labels are documented below.Default: .
keyFormattedThousand
The character(s) that's used as the thousand separator in the
%{value_formatted}
macro. Formatted key labels are documented below.Default: ,
keyFormattedUnitsPre
The units to add to the value. These units are positioned before the number. Formatted key labels are documented below.
Default: [an empty string]
keyFormattedUnitsPost
The units to add to the value. These units are positioned after the number. Formatted key labels are documented below.
Default: [an empty string]
keyFormattedValueSpecific
Instead of the key code calculating the value - which might not be what you want in some cases - you can use this property to specify the exact values that you want to be used in the key (this specifies just the values - not the whole string).
Default: null
keyFormattedItemsCount
You can use this property to specify the number of key items that should be shown. Normally this is calculated automatically for you.
Default: null
Active key elements
When you hover over or click on a key element/entry then the RGraph registry will hold details of the relevant key entry. So in your event listener, you will be able to determine the key entry like this:
key = RGraph.Registry.get('key-element');
And you could use it like this:
// Assume that the line
variable is your line chart object
line.canvas.onmousemove = function (e)
{
var key = RGraph.Registry.get('key-element');
if (key) {
// Log the details of the object to the console
console.log(key);
}
};
Using interactive keys on your charts
canvas
text for the key
- not dom
text. You can enable textAccessible
if you want but
the interactive key will ignore it.
Formerly the interactive key was only implemented for the Line chart
and Pie chart
.
As of mid-2013, however, it was
rewritten and is now available with a lot more chart types. The
demo pages for the interactive key are available in
the download archive.
Having been rewritten
the interactive key now uses the drawing api
Rect
object and the dynamic library:
<script src="RGraph.common.core.js"></script> <script src="RGraph.common.dynamic.js"></script> <script src="RGraph.common.key.js"></script> <script src="RGraph.drawing.rect.js"></script> <script> line = new RGraph.Line({ id: 'cvs', data: [ [458,435,466,148,396,485,456], [153,245,256,33,216,248,344], [55,56,43,374,76,78,85] ], options: { textSize: 12, marginTop: 45, marginLeft: 35, marginRight: 35, marginBottom: 35, marginInner: 15, xaxisLabels: ['Monday','Tuesday','Wednesday','Thursday','Friday','Saturday','Sunday'], tickmarksStyle: 'endcircle', linewidth: 3, xaxisTickmarksStyle: 12, spline: true, key: ['Rob','Julie','Jack'], keyPosition: 'margin', keyInteractive: true, title: 'A Line chart with interactive key', titleSize: 16 } }).draw(); </script>
Formatted key labels
Since version 6.12
you've been able to use
formatting macros in your key labels. For example you might
want the value as a part of your key labels and this is an
easy way to do it. To use the macros you can change your
array of key labels to a single string like
this:
key: '%{property:labels[%{index}]}: %{value_formatted}' keyFormattedDecimals: 2 keyFormattedUnitsPre: '£', // keyFormattedUnitsPost: 'p', // keyFormattedpoint: '.', // keyFormattedThousand: ',', // keyFormattedValueSpecific: null,
What macros are available to use?
-
%{index}
This gets replaced with the index of the relevant key item. -
%{property:title}
This macro fetches single value properties like thetitle
property (ie strings or numbers). -
%{property:xaxisLabels[%{index}]}
With this macro, you can fetch corresponding values from arrays - such as thexaxisLabels
property. As shown here, you can combine this macro with the%{index}
macro to fetch the relevant value. -
%{global:foo.bar.myGlobal}
%{global:foo.bar.myGlobal[%{index}]}
This macro gives you access to global variables - both strings/numbers and also arrays. -
%{value}
%{value_formatted}
With these macros, you can add the value of the data-point to your key. The%{value_formatted}
property gives you a formatted value instead of the raw number. For example instead of1575886.2
you could get this:$1,575,886.20c
. The properties to control the formatting are shown below.
keyFormattedPoint
This character is used as the decimal point.
Default: .
keyFormattedThousand
This character is used as the thousand separator.
Default: ,
keyFormattedDecimals
This specifies the number of decimals that are shown.
Default: 0
keyFormattedUnitsPre
These units are prepended to the number.
Default: [an empty string]
keyFormattedUnitsPost
These units are appended to the number.
Default: [an empty string] -
%{function:getKeyLabel(%{index})}
This option allows you to call a function that formats and returns the desired text. When the template macros are parsed by RGraph this is parsed last so you can use other macros in the arguments, as shown, and they end up looking like this:
%{function:getValue(3)}
So those values get passed to the function and you can use them to generate and return the correct value. The return value is then used as the resultant string.Note
An RGraph Registry variable is available to the function for you to get hold of the chart object and you can get that like this:
var obj = RGraph.Registry.get('key-label-templates-function-object');
HTML keys
In December 2013 a function was added to RGraph that allows you to use anhtml
key next to your chart. This key is made up
of div
and span
tags so you may find it easier to interact with.
You can read more about HTML keys on this page.