JavaScript/jQuery VectorMap - layers

Specifies properties for VectorMap UI component layers.

Type:

Array<Object>

|

Object

Default Value: undefined
Cannot be used in themes.

The vector map may contain several different layers. Each layer can be of "area", "line" or "marker" type.

The Z-order of layers depends on their order in the layers array in the following way: the first layer occupies the background, the last layer is brought to the foreground.

View Demo

borderColor

Specifies a color for the border of the layer elements.

Type:

String

Default Value: '#9d9d9d'

This property does not apply if the layer type is "line".

This property supports the following colors:

borderWidth

Specifies the line width (for layers of a line type) or width of the layer elements border in pixels.

Type:

Number

Default Value: 1

color

Specifies a color for layer elements.

Type:

String

Default Value: '#d2d2d2'

This property supports the following colors:

colorGroupingField

Specifies the field that provides data to be used for coloring of layer elements.

Type:

String

Default Value: undefined

If you need for the color of a specific map area to depend on the value of one of its attributes, assign the name of this attribute to the colorGroupingField property. The attribute must contain numeric values. After that, specify groups into which attribute values must be classified. For this purpose, assign an array to the colorGroups property. Each group in this array will be assigned a color from the palette.

View Demo

colorGroups

Allows you to paint layer elements with similar attributes in the same color.

Type:

Array<Number>

Default Value: undefined

If you have specified the field that provides area-coloring data, you need to specify groups into which this data must be classified. For this purpose, assign an array of numbers to the colorGroups property. Each pair of numbers in this array defines a range of data values.

For example, imagine that the colorGroups array contains four items: [0, 1, 2, 3]. This array specifies three ranges, or groups: 0-1, 1-2 and 2-3. Thus, data values will be split up into three groups. Each group will be assigned a color from the palette in order to paint the corresponding areas. Areas of those data values that do not match neither group will be drawn in a default color.

View Demo

customize

A function that customizes each layer element individually.

Type:

Function

Function parameters:
elements:

Array<Layer Element>

The array of layer elements.

Cannot be used in themes.

This function allows you to access and modify layer elements. You can use API listed in the methods and fields sections to get or set element properties.

NOTE
As an alternative to the function’s parameter you can use the this keyword.

View Demo

See Also

dataField

Specifies the name of the attribute containing marker data. Setting this property makes sense only if the layer type is "marker" and the elementType is "bubble", "pie" or "image".

Type:

String

Default Value: undefined

The marker data may contain a bubble value, pie chart values or an image URL.

dataSource

Specifies a data source for the layer.

Cannot be used in themes.

elementType

Specifies the type of a marker element. Setting this property makes sense only if the layer type is "marker".

Cannot be used in themes.

hoveredBorderColor

Specifies a color for the border of the layer element when it is hovered over.

Type:

String

Default Value: '#303030'

This property does not apply if the layer type is "line".

This property supports the following colors:

NOTE
Make sure that the hoverEnabled property is set to true, so that the hoveredBorderColor property takes effect.

hoveredBorderWidth

Specifies the pixel-measured line width (for layers of a line type) or width for the border of the layer element when it is hovered over.

Type:

Number

Default Value: 1

hoveredColor

Specifies a color for a layer element when it is hovered over.

Type:

String

Default Value: '#d2d2d2'

This property supports the following colors:

NOTE
Make sure that the hoverEnabled property is set to true, so that the hoveredColor property takes effect.

hoverEnabled

Specifies whether or not to change the appearance of a layer element when it is hovered over.

Type:

Boolean

Default Value: true

If this property is set to true, you can specify colors for the hovered layer element and its border using the hoveredColor and hoveredBorderColor properties, respectively.

label

Specifies marker label properties.

Type:

Object

A marker label is a text that accompanies a map marker. Usually, a marker label displays the name of a certain geographical point.

To specify a text to be used in a marker label, place it in a field of the marker object. After that, assign the name of this field to the label.dataField property. Finally, enable marker labels by assigning true to the label.enabled property.

maxSize

Specifies the pixel-measured diameter of the marker that represents the biggest value. Setting this property makes sense only if the layer type is "marker".

Type:

Number

Default Value: 50

When you use bubble markers on your map, their sizes depend on their values. The biggest value will be represented by the largest bubble. Similarly, the smallest value will be represented by the smallest bubble. Bubbles that represent values in between will have sizes proportional to the represented values. To specify the sizes of the largest and smallest bubbles, use the maxSize and minSize properties of the layers object.

minSize

Specifies the pixel-measured diameter of the marker that represents the smallest value. Setting this property makes sense only if the layer type is "marker".

Type:

Number

Default Value: 20

When you use bubble markers on your map, their sizes depend on their values. The biggest value will be represented by the largest bubble. Similarly, the smallest value will be represented by the smallest bubble. Bubbles that represent values in between will have sizes proportional to the represented values. To specify the sizes of the largest and smallest bubbles, use the maxSize and minSize properties of the layers object.

name

Specifies the layer name.

Type:

String

Cannot be used in themes.

opacity

Specifies the layer opacity (from 0 to 1).

Type:

Number

Default Value: 1

palette

The name of a predefined palette or a custom range of colors to be used as a palette.

Type:

Array<String>

|

Palette

Default Value: 'Material'

A palette defines a range of colors that are used to paint layer elements. This range is divided into segments by the value of the paletteSize property. Each segment contributes a color to the resulting array of colors. The more segments there are, the greater the variety of colors in this array. Available predefined palettes are listed in the accepted values.

Use the paletteIndex to iterate through the palette[] array within the customize function. For each element, apply the palette as follows:

jQuery
index.js
$(function() {
    $("#vectorMapContainer").dxVectorMap({
        // ...
        layers: [{
            dataSource: DevExpress.viz.map.sources.world,
            palette: "Material",
            paletteSize: 7,
            customize: function(elements) {
                elements.forEach(function(element, index) {
                    element.applySettings({
                        paletteIndex: index % 7
                    });
                });
            }
        }]
    });
});
Angular
app.component.html
app.component.ts
app.module.ts
<dx-vector-map ... >
    <dxi-layer
        [dataSource]="worldMap"
        palette="Material" 
        [paletteSize]="7"
        [customize]="colorizeMap">
    </dxi-layer>
</dx-vector-map>
import { Component } from '@angular/core';
import * as mapsData from 'devextreme-dist/js/vectormap-data/world.js';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    constructor() {
        this.colorizeMap = this.colorizeMap.bind(this);
    }

    worldMap: any = mapsData.world;

    colorizeMap(elements) {
        elements.forEach((element, index) => {
            element.applySettings({
                paletteIndex: index % 7
            });
        });
    }
}
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';

import { DxVectorMapModule } from 'devextreme-angular';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        DxVectorMapModule
    ],
    providers: [ ],
    bootstrap: [AppComponent]
})
export class AppModule { }
Vue
App.vue
<template>
    <DxVectorMap ... >
        <DxLayer
            :data-source="worldMap"
            palette="Material" 
            :palette-size="7"
            :customize="colorizeMap" 
        />
    </DxVectorMap>
</template>

<script>
import * as mapsData from 'devextreme-dist/js/vectormap-data/world.js';

import DxVectorMap, {
    DxLayer
} from 'devextreme-vue/vector-map';

export default {
    components: {
        DxVectorMap,
        DxLayer
    },
    data() {
        return {
            worldMap: mapsData.world
        }
    },
    methods: {
        colorizeMap(elements) {
            elements.forEach((element, index) => {
                element.applySettings({
                    paletteIndex: index % 7
                });
            });
        }
    }
}
</script>
React
App.js
import React from 'react';

import { VectorMap, Layer } from 'devextreme-react/vector-map';
import * as mapsData from 'devextreme-dist/js/vectormap-data/world.js'

const worldMap = mapsData.world;

function colorizeMap(elements) {
    elements.forEach((element, index) => {
        element.applySettings({
            paletteIndex: index % 7
        });
    });
}

export default function App() {
    return (
        <VectorMap>
            <Layer
                dataSource={worldMap}
                paletteSize={7}
                customize={this.colorizeMap}
                palette="Material" 
            />
        </VectorMap>
    );
}

paletteIndex

The position of a color in the palette[] array. Should not exceed the value of the paletteSize property.

Type:

Number

Use this property to specify a different color for each layer element. Refer to the palette description for a code example.

paletteSize

Specifies the number of colors in a palette.

Type:

Number

Default Value: 0

Assign a number that is greater than 0 to this property in order to use palettes.

selectedBorderColor

Specifies a color for the border of the layer element when it is selected.

Type:

String

Default Value: '#303030'

This property does not apply if the layer type is "line".

This property supports the following colors:

selectedBorderWidth

Specifies a pixel-measured line width (for layers of a line type) or width for the border of the layer element when it is selected.

Type:

Number

Default Value: 2

selectedColor

Specifies a color for the layer element when it is selected.

Type:

String

Default Value: '#d2d2d2'

This property supports the following colors:

selectionMode

Specifies whether single or multiple map elements can be selected on a vector map.

Default Value: 'single'

Several properties and methods are connected with the selection operation. To specify whether single or multiple areas can be selected at a time, use the selectionMode property. To determine whether a certain area is selected when the UI component is created, use the isSelected field of the object returned by the customize callback function.

At runtime, you can do the following operations.

  • Obtain the current selection state of a layer element using its selected() method.

  • Change the current selection state of a layer element using its selected(state) method. Pass true or false to this method.

  • Deselect all the selected layer elements using the clearSelection() method of the map layer.

The change of the selection state invokes the callback function assigned to the onSelectionChanged property. Within this function, you can handle the selection event in the manner you require.

size

Specifies the size of markers. Setting this property makes sense only if the layer type is "marker" and the elementType is "dot", "pie" or "image".

Type:

Number

Default Value: 8

sizeGroupingField

Specifies the field that provides data to be used for sizing bubble markers. Setting this property makes sense only if the layer type is "marker" and the elementType is "bubble".

Type:

String

Default Value: undefined

If you need the size of the bubble marker to depend on the value of one of its attributes, assign the name of this attribute to the sizeGroupingField property. The attribute must contain numeric values. After that, specify groups into which attribute values must be classified by assigning an array to the sizeGroups property.

NOTE
If you need to classify a bubble by its value, leave the sizeGroupingField property unassigned.

sizeGroups

Allows you to display bubbles with similar attributes in the same size. Setting this property makes sense only if the layer type is "marker" and the elementType is "bubble".

Type:

Array<Number>

Default Value: undefined

If you have specified the field that provides marker-sizing data, you need to specify groups into which this data must be classified. For this purpose, assign an array of numbers to the sizeGroups property. Each pair of numbers in this array defines a range of data values.

For example, consider that the sizeGroups array contains four items: [0, 1, 2, 3]. This array specifies three ranges, or groups: 0-1, 1-2 and 2-3. Thus, data values will be split up into three groups. Each group will be assigned a size correlating with the group values. This size will be calculated automatically taking into account the minSize and maxSize values. Markers of those data values that do not match neither group will have a default size.

type

Specifies layer type.

Cannot be used in themes.