Legend

This tutorial describes how the legend can be manipulated.

Introduction

The JSCharting legend is a powerful and fully customizable data grid that allows customizing columns with data attributes and calculations through the use of expressions. Custom entries can be used to populate the legend with any data or information. Some legend features include:

• Flexible and automated positioning
• Legend title
• Data columns with expressions
• Column headers
• AxisMarker entries
• Custom entries
• SmartPalette legend with ColorBar or ranges
• Entry icon customization
• Interactivity events
• Chart with only a legend: Legend Alone Sample

Layout / Position

The legend can be positioned anywhere around the chart area by setting the legend.position property.

Legend Entry Orientation

When using a position name such as 'topLeft' the legend entries are automatically laid out either vertically or horizontally depending on the position. However, with absolute or relative positioning, this setting should be specified with the legend.layout property:

chartOptions.legend_layout = "horizontal";

Styling

Styling the legend box is similar to styling the title and annotations. Properties such as fill, outline, radius, shadow are all available.

Entries

Legend entries represent data on the chart. Series have individual legendEntry properties but the legend object has a defaultEntry property that specifies the defaults for all entries and is recommended unless entry specific customization is required.

Data Grid

The legend.template property can be populated with a space or comma delimited string of expressions and tokens that define the data shown for each column.

The legendEntry value and name properties can contain tokens and expressions as well. By default, when the legend template includes '%name' or '%value', it refers to these properties rather than '%name' and '%value' of the actual target item. The default values of these properties are

{ name: "%name", value: "%sum" }

These properties are useful because they allow customizing the data shown for each legend column on a per-entry basis. Items represented by the legend are not necessarily of the same type. For example, the legend can contain series and point entries at the same time.

The legend.header property can be used to specify labels for each column defined in legend.template property. It, too, is delimited by spaces or commas if commas are found in the string. The header property must contain the same number of items as the template.

Arbitrary token values can also be used in the template and custom text for those tokens can be specified for each legend entry like so:

{
  template: "%name %icon %value %customVal",
  name: "%name",
  value: "%sum",
  attributes: { customVal: "Custom Text" }
}

Data series and points

By default, each series gets an entry in the legend. However, when a series has a palette property set, a legend entry for each point of the series is added in place of the series legend entry.

When series have entries in the legend a particular point entry can be added to the legend by setting the points legendEntry_visible to true. Similarly, any series legend entry can be removed from the legend by setting its legendEntry_visible to false.

SmartPalette

When a chart.palette property is set with a smartPalette config object, the legend will show a ColorBar by default. If the smartPalette options define color ranges, the legend will display these ranges instead.

AxisMarkers

AxisMarkers entries are added to the legend by default as well. These can be removed by setting their legendEntry_visible property to false.

Custom entries

Custom legend entries can be added to the legend through the legend.customEntries property. Tokens used with custom entries are evaluated using the series collection token list which refers to series on the chart.

Customizing Entries

Column Text

Legend template property defines columns for a legend that apply to all entries. Custom entries can define custom text for columns by adding them to the entry.attributes property.

Icon

The legend entry icon is fully customizable. Any icon from the icon library can be specified, or even a svg path can be specified. The chart will scale the given path to the appropriate size to fit it in the legend.

Sorting

Legend entries are listed in the order their series are added to the chart. However, setting legend.reverse reverses the order of the entries. A custom sort order can also be implemented by setting the sortOrder property of individual series legend entries.

Events & Interactivity

By default, legend entries are interactive and when clicked they provide a useful action depending on what the entry represents. These behavior can also be disabled by adding a click event handler that returns false.

In general, legend entries represent series and in standard charts clicking the legend entry toggles the corresponding series visibility. However, legend entries can also show points, axis marker, and custom entries.

Point entry click event action can differ between chart types. For example, a pie chart where entries represent slices can highlight or explode the pie slice. With standard types like line, column and zooming enabled or with organizational type, clicking a point entry can scroll the point into view.

Entries can also be customized with event handlers to perform any desired actions. With custom legend entry icons, legend entries can even be used as clickable buttons similar to uiItems. Sample Map Entry Zoom Sample demonstrates this using a custom entry to reset zoom that appears after a country entry is clicked. It also demonstrates how clicked entries can be highlighted (made bold) programmatically.

States

Legend entries are clickable and therefore visual states are provided to indicate when mouse hovers or the entry is disabled. The two entry states are named 'hover' and 'hidden'.

Legend entries support cascading states which means that if a setting is applied to the normal state, it will affect subsequent states like hover and hidden. Internally this cascading processes higher level setting and modifies it to reflect the new state more accurately unless otherwise specified. This may help reduce the amount of code necessary to achieve an obviously desired effect. For example, setting a font propagates that font to subsequent states.

All legend related tasks