Legend View

The Xweather JavaScript SDK includes support for a dynamic legend view, which allows you to easily add and remove individual legends for specific Xweather Raster Maps layers as needed. Each legend image displayed will automatically be configured based on your legend view's configuration options. If you're using the SDK's map view feature, then a legend view will automatically be added and managed by the map view instance. However, you may want to display a legend view on its own or in conjunction with another view, such as our interactive map feature.

The legend view feature is part of the Views module of the library. Therefore, you'll need to use the views() method on your AerisWeather instance in order to begin using any of the map view-related features. Read more about working with the Views module.

Configuration

The following options are supported when configuring your LegendView instance:

Option	Type	Description	Default
account	`Account`	Xweather account used when requesting data for dynamic legends, such as the `alerts` legend.
size	`ISize`	Output size of legends displayed in the view.	`{ width: 400, height: 40 }`
autosize	`boolean`	Whether individual legends should be sized automatically based on its style configuration.	`false`
format	`string`	Output format, either `svg` or `png`.	`svg`
metric	`boolean`	Whether legend data units should be output in Metric units.	`false`

Setting Up a Legend View

Initialize a legend view with your DOM target where it will be rendered and desired configuration options using the new views.Legend(target, opts) constructor. For example, the following will render a legend view in the DOM target with id map-legend where each legend item will have a size of 400x40 (excluding dynamic legends):

// using Promises
aeris.views().then((views) => {
    const legend = new views.Legend('#legend', {
        size: {
            width: 600,
            height: 40
        }
    });
});

Alternatively, if you're providing a callback function to the views() method:

// using callback function
aeris.views((views) => {
    const legend = new views.Legend('#legend', {
        size: {
            width: 600,
            height: 40
        }
    });
});

Adding Legends

Legend elements are added to a legend view using the add() method, which takes a legend or layer code string as the type to add and any configuration option overrides.

The following will add a radar legend to a legend view with the default configuration:

aeris.views().then((views) => {
    const legend = new views.Legend('#legend', {
        size: {
            width: 600,
            height: 40
        }
    });
    
    legend.add('radar');
});

In addition to the configuration options outlined above, you can also include custom style options when adding a legend to the view. Include a styles property in your options, which should be an object of LegendStyle type. The following example will render the same radar legend, but with each cell configured to be drawn at a size of 5x20:

aeris.views().then((views) => {
    const legend = new views.Legend('#legend', {
        size: {
            width: 600,
            height: 40
        }
    });
    
    legend.add('radar', {
        styles: {
            cell: {
                size: {
                    width: 10,
                    height: 20
                }
            }
        }
    });
});

However, you'll notice that the cells are narrower than 5pt and the bottom of the text labels are being clipped. This is because we are setting a static width and height in the legend view, which means each legend item in the view will adjust its configuration to fit that width. If you wanted to enforce the 5pt cell widths, you would need to remove the static size for your legend view and set autosize to true:

aeris.views().then((views) => {
    const legend = new views.Legend('#legend', {
        autosize: true
    });
    
    legend.add('radar', {
        styles: {
            cell: {
                size: {
                    width: 10,
                    height: 20
                }
            }
        }
    });
});

Radar legend with custom cell size and autosize enabled

Note that enabling autosize may result in your legend view and/or individual legend items extending beyond the bounds of its container. Therefore, if you require a maximum width for your legends, it's recommended to set autosize to false and set a static size instead.

Review the LegendStyle type documentation for the full listing of supported style options.

Removing Legends

Removing individual legend elements from your legend view is similar to that when adding them. Simply provide the legend or layer code string to the remove() method to remove the legend associated with that code if it exists in the view:

legend.remove('radar');

Review the LegendView API documentation for additional information regarding the available properties and methods when working with legend views.

Overlays Data/Map Requests