Using keys or legends

• Introduction
• Key configuration properties
• Active key elements
• Using interactive keys on your charts
• Formatted key labels
  • What macros are available to use?
• 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):

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

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>
    new RGraph.Line({
        id: 'cvs_interactive',
        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,
            marginLeft: 55,
            marginRight: 35,
            marginBottom: 35,
            marginTop: 55,
            xaxisLabels: ['Mon','Tue','Wed','Thu','Fri','Sat','Sun'],
            linewidth: 6,
            spline: true,
            key: ['Rob','Julie','Jack'],
            keyPosition: 'margin',
            keyInteractive: true,
            title: 'A Line chart with interactive key',
            textSize: 16,
            shadow: false,
            backgroundGridVlines: false,
            backgroundGridBorder: false,
            xaxis: false,
            yaxis: false
        }
    }).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 the title property (ie strings or numbers).


• %{property:xaxisLabels[%{index}]}
  With this macro, you can fetch corresponding values from arrays - such as the xaxisLabels 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 of 1575886.2 you could get this: $1,575,886.20c. The properties to control the formatting are shown below.
  
  
  Name: keyFormattedPoint
  

  Description: 

  This character is used as the decimal point.

  Default: .

  Name: keyFormattedThousand
  

  Description: 

  This character is used as the thousand separator.

  Default: ,

  Name: keyFormattedDecimals
  

  Description: 

  This specifies the number of decimals that are shown.

  Default:  0

  Name: keyFormattedUnitsPre
  

  Description: 

  These units are prepended to the number.

  Default: [an empty string]

  Name: keyFormattedUnitsPost
  

  Description: 

  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 an HTML 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.