# Webcharts Legends Reference

> Web components implementing legends to webcharts.

**Table of Contents**

[Introduction](#introduction)
| [Using webcharts-legends](#using-webcharts-legends)
| [Styling webcharts-legends](#styling-webcharts-legends)
| [Graph Tools](#ni-graph-tools)
| [Plot Legend](#ni-plot-legend)
| [Light Plot Legend](#ni-light-plot-legend)
| [Scale Legend](#ni-scale-legend)

## Introduction ##

Webcharts-legends is a collection of [web components](https://www.webcomponents.org/introduction)


## Using webcharts-legends ##

Webcharts and webcharts-legends are distributed through npm with the package names **ni-webcharts** and **ni-webcharts-legends**.

Add webcharts and webcharts-legends to your app:

    npm install --save ni-webcharts ni-webcharts-legends


Add webcharts to a webpage:

```html
<link rel="stylesheet" href="node_modules/ni-webcharts/styles/webchartsLight.css" />
<link rel="stylesheet" href="node_modules/ni-webcharts-legends/styles/webcharts-legends.css" />
<!-- webcharts scripts -->
<!-- webcharts legends scripts -->
<script type="text/javascript" src="node_modules/webcomponents-lite/webcomponents-lite.js"></script>
```

## Styling webcharts-legends ##

The way webcharts-legends look is configured using a mix of elements properties, described
below in this document, and CSS styles. A guide for styling with CSS is [here](styling.md).



## ni-graph-tools

> A custom element that provides a graph tools "legend".

Use it to add navigation controls to a graph, chart or intensity graph element.
It provides buttons to switch between pan mode, box zoom mode or to lock navigation.

It also provides a resetOffset button which resets the axes to the range of the data.

Example:
```html
<ni-cartesian-graph graph-ref="g1" value="[[2, 3, 5, 7, 11, 13, 17, 19],
                          [0, 1, 1, 2, 3, 5, 8, 13]]">
  <ni-cartesian-axis show label="Index" axis-position="bottom"></ni-cartesian-axis>
  <ni-cartesian-axis show label="Value" axis-position="left"></ni-cartesian-axis>
</ni-cartesian-graph>

<ni-graph-tools graph-ref="g1" mode="pan"></ni-graph-tools>
```


### ni-graph-tools properties

**graph-ref** - the graph id to connect to. Default: ''

**is-in-edit-mode** - makes the legend non-interactive


**mode** (string) - the mode of the graph tools. Default: 'pan'.
               Accepted values: 'locked', 'pan', 'zoom'

### ni-graph-tools methods

**asyncProcessAllImagesForComposition** - gathers all the required
       layers of a graph, chart etc (i.e. plot, axes, cursors, legend),
       adds a background color to them and creates a snapshot (as canvas).
       If no background color is specified, it uses the plot background color.
       It returns a promise, which can be used to get the generated snapshot
       image. Using *downloadSnapshot* function, this image can be downloaded
       to disk (see *downloadSnapshot* function below).
       asyncProcessAllImagesForComposition is available, to allow users to
       write their own custom download functions.

   Example:
   ```js
   var asyncSnapshot = function() {
       asyncProcessAllImagesForComposition().then(triggerDownload(), failureCallback);
       _parentGraph.graph.getEventHolder().removeEventListener('onDrawingDone', asyncSnapshot);
   };
   _parentGraph.graph.getEventHolder().addEventListener('onDrawingDone', asyncSnapshot);
   _parentGraph.updateGraphConfig();
   ```
       

**downloadSnapshot** - is a wrapper over *asyncProcessAllImagesForComposition*
       function, used to generate a filename and trigger the actual download of
       a graph snaphot. It also updates the plot dimensions to the page zoom,
       before calling *asyncProcessAllImagesForComposition*. This allows creating
       a high resolution snapshot, simply by zooming the page in.
       Updating the plot dimensions as the page is zoomed in/out, is a requirement,
       to make sure all layers of a snapshot are scaled accordingly.
       As a limitation, it may not be possible to create and download snapshots
       at every refresh of a plot.

   Example:
   ```js
   function takeGraphSnapshotOnClick() {
       downloadSnapshot();
   }
   ```
       


## ni-plot-legend

> A custom element that provides a plot legend.

Use it to visualize and change the plots of a graph or chart element.

It provides an expandable list with all the plots of the graphs.

Expand one of the plots and you get a panel where you can control the
parameters of the plot - like plot style, line width, dash style, colors ...

Example:
```html
<ni-cartesian-graph graph-ref="g1" value="[[2, 3, 5, 7, 11, 13, 17, 19],
                          [0, 1, 1, 2, 3, 5, 8, 13]]">
    <ni-cartesian-axis show label="Index" axis-position="bottom"></ni-cartesian-axis>
    <ni-cartesian-axis show label="Value" axis-position="left"></ni-cartesian-axis>
    <ni-cartesian-plot show label="Prime Numbers">
        <ni-cartesian-plot-renderer line-width="2" line-stroke="red">
        </ni-cartesian-plot-renderer>
    </ni-cartesian-plot>
    <ni-cartesian-plot show label="Fibonacci Numbers">
        <ni-cartesian-plot-renderer line-width="2" line-stroke="blue">
        </ni-cartesian-plot-renderer>
    </ni-cartesian-plot>
</ni-cartesian-graph>

<ni-plot-legend graph-ref="g1" mode="pan"></ni-plot-legend>
```


### ni-plot-legend properties

**graph-ref** - the graph id to connect to. Default: ''

**is-in-edit-mode** - makes the legend non-interactive


**mode** (string) - the mode of the plot legend. Default: 'full'.
               When in 'compact mode' only the plot icon and the plot name are shown.
               In full mode you can expand the plots and can fully configure them at runtime.

               Accepted values: 'full', 'compact' 


## ni-light-plot-legend

> A custom element that provides a light legend for showing plot icons and names.

Use it to visualize the plots of a graph or chart element.

It provides an svg image with all the plots of the graphs.

By changing position attribute you can place the legend over graph("nw", "ne", "sw", "se"), or
inside a container("container"). Default is "container".

Example:
```html
<ni-cartesian-graph graph-ref="g1" value="[[2, 3, 5, 7, 11, 13, 17, 19],
                          [0, 1, 1, 2, 3, 5, 8, 13]]">
    <ni-cartesian-axis show label="Index" axis-position="bottom"></ni-cartesian-axis>
    <ni-cartesian-axis show label="Value" axis-position="left"></ni-cartesian-axis>
    <ni-cartesian-plot show label="Prime Numbers">
        <ni-cartesian-plot-renderer line-width="2" line-stroke="red">
        </ni-cartesian-plot-renderer>
    </ni-cartesian-plot>
    <ni-cartesian-plot show label="Fibonacci Numbers">
        <ni-cartesian-plot-renderer line-width="2" line-stroke="blue">
        </ni-cartesian-plot-renderer>
    </ni-cartesian-plot>
</ni-cartesian-graph>

<ni-light-plot-legend show graph-ref="g1" position="ne"></ni-light-plot-legend>
```


### ni-light-plot-legend properties

**show** (boolean) - the visibility of the plot legend. Default: false.
                Accepted values: true, false

**graph-ref** (string) - the graph id to connect to. Default: ''.

**position** (string) - the position where the legend will be placed. Default: 'container'.
                Accepted values: 'nw', 'ne', 'sw', 'se', 'container'


## ni-scale-legend

> A custom element that provides a scale legend.

Use it to visualize and change the axis modes of a graph, chart or intensity graph element.

It provides a list with all the axes of the graphs.

Each axis in the list has two buttons - one to turn on/off the autoscaling for that axis and
the other one sets the scale range to the data range (without changing the autoScale mode)

Example:
```html
<ni-cartesian-graph graph-ref="g1" value="[[2, 3, 5, 7, 11, 13, 17, 19],
                          [0, 1, 1, 2, 3, 5, 8, 13]]">
    <ni-cartesian-axis show label="Index" axis-position="bottom"></ni-cartesian-axis>
    <ni-cartesian-axis show label="Value" axis-position="left"></ni-cartesian-axis>
    <ni-cartesian-plot show label="Prime Numbers">
        <ni-cartesian-plot-renderer line-width="2" line-stroke="red">
        </ni-cartesian-plot-renderer>
    </ni-cartesian-plot>
    <ni-cartesian-plot show label="Fibonacci Numbers">
        <ni-cartesian-plot-renderer line-width="2" line-stroke="blue">
        </ni-cartesian-plot-renderer>
    </ni-cartesian-plot>
</ni-cartesian-graph>

<ni-scale-legend graph-ref="g1" mode="pan"></ni-scale-legend>
```



## ni-cursor-legend

> A custom element that provides a cursor legend.

Use it to visualize, add, remove and configure cursors. It can be attached to a graph or chart element.

It provides a list with all the cursors of the graphs and a way to add/remove cursors.

Example:
```html
<ni-cartesian-graph graph-ref="g1" value="[[2, 3, 5, 7, 11, 13, 17, 19],
                          [0, 1, 1, 2, 3, 5, 8, 13]]">
    <ni-cartesian-axis show label="Index" axis-position="bottom"></ni-cartesian-axis>
    <ni-cartesian-axis show label="Value" axis-position="left"></ni-cartesian-axis>
    <ni-cartesian-plot show label="Prime Numbers">
        <ni-cartesian-plot-renderer line-width="2" line-stroke="red">
        </ni-cartesian-plot-renderer>
    </ni-cartesian-plot>
    <ni-cartesian-plot show label="Fibonacci Numbers">
        <ni-cartesian-plot-renderer line-width="2" line-stroke="blue">
        </ni-cartesian-plot-renderer>
    </ni-cartesian-plot>
</ni-cartesian-graph>

<ni-cursor-legend graph-ref="g1" mode="pan"></ni-cursor-legend>
```


### ni-cursor-legend properties

**graph-ref** - the graph id to connect to. Default: ''

**is-in-edit-mode** - makes the legend non-interactive