Skip to content

layer-api.md

Latest commit

 

History

History
1308 lines (877 loc) · 24.4 KB

layer-api.md

File metadata and controls

1308 lines (877 loc) · 24.4 KB

Layer API Reference

The LayerApi class provides comprehensive methods for managing map layers in GeoView. It handles layer creation, removal, configuration, visibility, and interaction with various layer types including WMS, ESRI services, GeoJSON, and more.

Accessing the Layer API

The Layer API is available through the MapViewer instance:

// Get the map viewer
const mapViewer = cgpv.api.getMapViewer("mapId");

// Access the layer API
const layerApi = mapViewer.layer;

Layer Types Supported

  • Vector Layers: GeoJSON, WFS, OGC Feature, ESRI Feature, CSV, KML, WKB
  • Raster Layers: WMS, ESRI Dynamic, ESRI Image, XYZ Tiles, Vector Tiles, Image Static
  • Special: GeoCore, GeoPackage, Shapefile, RCS

Core Layer Management

Adding Layers

addGeoviewLayer()

Adds a layer to the map using a layer configuration object.

addGeoviewLayer(
  geoviewLayerConfig: TypeGeoviewLayerConfig,
  abortSignal?: AbortSignal
): GeoViewLayerAddedResult

Parameters:

  • geoviewLayerConfig - Layer configuration object (see Configuration Reference)
  • abortSignal - Optional AbortSignal to cancel the layer addition

Returns: GeoViewLayerAddedResult object containing:

  • layerConfig - The configuration used
  • layer - The created GeoView layer instance

Example:

const result = mapViewer.layer.addGeoviewLayer({
  geoviewLayerId: "myLayer",
  geoviewLayerName: "My WMS Layer",
  geoviewLayerType: "ogcWms",
  metadataAccessPath: "https://example.com/wms",
  listOfLayerEntryConfig: [
    {
      layerId: "layer1",
      layerName: "Layer 1",
    },
  ],
});

addGeoviewLayerByGeoCoreUUID()

Adds a layer from the GeoCore catalog using its UUID.

async addGeoviewLayerByGeoCoreUUID(
  uuid: string,
  layerEntryConfig?: string
): Promise<GeoViewLayerAddedResult | void>

Parameters:

  • uuid - The GeoCore layer UUID
  • layerEntryConfig - Optional layer entry configuration path

Example:

await mapViewer.layer.addGeoviewLayerByGeoCoreUUID(
  "12345678-1234-1234-1234-123456789012"
);

loadListOfGeoviewLayer()

Loads multiple layers from the map configuration.

async loadListOfGeoviewLayer(
  mapConfigLayerEntries: MapConfigLayerEntry[]
): Promise<void>

Parameters:

  • mapConfigLayerEntries - Array of map configuration layer entries

Removing Layers

removeLayerUsingPath()

Removes a layer and all its children using its layer path.

removeLayerUsingPath(layerPath: string): void

Parameters:

  • layerPath - The path of the layer to remove (e.g., 'layerId' or 'layerId/sublayerId')

Example:

mapViewer.layer.removeLayerUsingPath("myLayer");

removeAllGeoviewLayers()

Removes all layers from the map.

removeAllGeoviewLayers(): void

removeAllLayersInError()

Removes all layers that have an error status.

removeAllLayersInError(): void

Reloading Layers

reloadLayer()

Reloads a specific layer.

reloadLayer(layerPath: string): void

Parameters:

  • layerPath - The path of the layer to reload

Example:

mapViewer.layer.reloadLayer("myLayer");

reloadGeocoreLayers()

Reloads all GeoCore layers on the map.

reloadGeocoreLayers(): void

refreshLayers()

Refreshes all layers on the map.

refreshLayers(): void

Layer Information and Access

Getting Layers

getGeoviewLayerIds()

Gets all GeoView layer IDs/UUIDs.

getGeoviewLayerIds(): string[]

Returns: Array of layer IDs

getGeoviewLayerPaths()

Gets all GeoView layer paths.

getGeoviewLayerPaths(): string[]

Returns: Array of layer paths

getGeoviewLayers()

Gets all GeoView layer instances.

getGeoviewLayers(): AbstractBaseLayer[]

Returns: Array of layer instances

getGeoviewLayer()

Gets a specific GeoView layer by path (throws error if not found).

getGeoviewLayer(layerPath: string): AbstractBaseLayer

Parameters:

  • layerPath - The path of the layer to retrieve

Returns: The layer instance

Throws: LayerNotFoundError if layer doesn't exist

getGeoviewLayerIfExists()

Gets a specific GeoView layer by path (returns undefined if not found).

getGeoviewLayerIfExists(layerPath: string): AbstractBaseLayer | undefined

Parameters:

  • layerPath - The path of the layer to retrieve

Returns: The layer instance or undefined

Example:

const layer = mapViewer.layer.getGeoviewLayerIfExists("myLayer");
if (layer) {
  console.log("Layer found:", layer);
}

Layer Configuration

getLayerEntryConfig()

Gets the configuration for a specific layer entry (throws error if not found).

getLayerEntryConfig(layerPath: string): ConfigBaseClass | undefined

Parameters:

  • layerPath - The path of the layer

Returns: The layer configuration object

getLayerEntryConfigIfExists()

Gets the configuration for a specific layer entry (returns undefined if not found).

getLayerEntryConfigIfExists(layerPath: string): ConfigBaseClass | undefined

Parameters:

  • layerPath - The path of the layer

Returns: The layer configuration object or undefined

getLayerEntryConfigs()

Gets all layer entry configurations.

getLayerEntryConfigs(): ConfigBaseClass[]

Returns: Array of layer configuration objects

getLayerEntryConfigIds()

Gets all layer entry configuration IDs.

getLayerEntryConfigIds(): string[]

Returns: Array of layer configuration IDs

isLayerEntryConfigRegistered()

Checks if a layer entry configuration is registered.

isLayerEntryConfigRegistered(layerPath: string): boolean

Parameters:

  • layerPath - The path of the layer to check

Returns: True if registered, false otherwise

OpenLayers Integration

getOLLayer()

Gets the OpenLayers layer instance (throws error if not found).

getOLLayer(layerPath: string): BaseLayer

Parameters:

  • layerPath - The path of the layer

Returns: The OpenLayers layer instance

getOLLayerIfExists()

Gets the OpenLayers layer instance (returns undefined if not found).

getOLLayerIfExists(layerPath: string): BaseLayer | undefined

Parameters:

  • layerPath - The path of the layer

Returns: The OpenLayers layer instance or undefined

getOLLayerAsync()

Gets the OpenLayers layer instance asynchronously (waits for layer to be created).

getOLLayerAsync(
  layerPath: string,
  timeout?: number,
  checkFrequency?: number
): Promise<BaseLayer>

Parameters:

  • layerPath - The path of the layer
  • timeout - Maximum wait time in milliseconds (default: 10000)
  • checkFrequency - Check interval in milliseconds (default: 100)

Returns: Promise resolving to the OpenLayers layer instance

Example:

const olLayer = await mapViewer.layer.getOLLayerAsync("myLayer", 5000);

Layer Display and Interaction

Visibility

setOrToggleLayerVisibility()

Sets or toggles the visibility of a layer.

setOrToggleLayerVisibility(
  layerPath: string,
  newValue?: boolean
): boolean

Parameters:

  • layerPath - The path of the layer
  • newValue - Optional visibility value (true/false). If omitted, toggles current state

Returns: The new visibility state

Example:

// Toggle visibility
mapViewer.layer.setOrToggleLayerVisibility("myLayer");

// Set explicit visibility
mapViewer.layer.setOrToggleLayerVisibility("myLayer", true);

setAllLayersVisibility()

Sets the visibility of all layers.

setAllLayersVisibility(newValue: boolean): void

Parameters:

  • newValue - The visibility state to apply to all layers

setItemVisibility()

Sets the visibility of a specific legend item within a layer.

setItemVisibility(
  layerPath: string,
  item: TypeLegendItem,
  visibility: boolean,
  updateLegendLayers?: boolean
): void

Parameters:

  • layerPath - The path of the layer
  • item - The legend item to modify
  • visibility - The visibility state
  • updateLegendLayers - Whether to update legend layers (default: true)

Opacity

setLayerOpacity()

Sets the opacity of a layer.

setLayerOpacity(
  layerPath: string,
  opacity: number,
  emitOpacityChange?: boolean
): void

Parameters:

  • layerPath - The path of the layer
  • opacity - Opacity value (0-1)
  • emitOpacityChange - Whether to emit opacity change event (default: true)

Example:

// Set layer to 50% opacity
mapViewer.layer.setLayerOpacity("myLayer", 0.5);

Highlighting

highlightLayer()

Highlights a layer by reducing opacity of other layers.

highlightLayer(layerPath: string): void

Parameters:

  • layerPath - The path of the layer to highlight

Example:

mapViewer.layer.highlightLayer("myLayer");

removeHighlightLayer()

Removes layer highlighting and restores original opacity.

removeHighlightLayer(): void

removeLayerHighlights()

Removes all highlights from a specific layer.

removeLayerHighlights(layerPath: string): void

Parameters:

  • layerPath - The path of the layer

Layer Properties

setLayerName()

Sets the name of a layer.

setLayerName(layerPath: string, name: string): void

Parameters:

  • layerPath - The path of the layer
  • name - The new layer name

Example:

mapViewer.layer.setLayerName("myLayer", "Updated Layer Name");

Layer Data Manipulation

GeoJSON

setGeojsonSource()

Updates the GeoJSON source data for a GeoJSON layer.

setGeojsonSource(
  layerPath: string,
  geojson: GeoJSONObject | string
): void

Parameters:

  • layerPath - The path of the GeoJSON layer
  • geojson - GeoJSON object or string

Throws: LayerNotGeoJsonError if layer is not a GeoJSON layer

Example:

const geojson = {
  type: "FeatureCollection",
  features: [
    {
      type: "Feature",
      geometry: {
        type: "Point",
        coordinates: [-75.6972, 45.4215],
      },
      properties: {
        name: "Ottawa",
      },
    },
  ],
};

mapViewer.layer.setGeojsonSource("myGeoJsonLayer", geojson);

Feature Fields

redefineFeatureFields()

Redefines feature field names or aliases.

redefineFeatureFields(
  layerPath: string,
  fieldNames: string[],
  fields: 'alias' | 'name'
): void

Parameters:

  • layerPath - The path of the layer
  • fieldNames - Array of field names/aliases
  • fields - Whether to redefine 'alias' or 'name'

Throws: LayerDifferingFieldLengths if array lengths don't match

Example:

mapViewer.layer.redefineFeatureFields(
  "myLayer",
  ["Population", "Area", "Density"],
  "alias"
);

replaceFeatureOutfields()

Replaces the outfields configuration for a layer.

replaceFeatureOutfields(
  layerPath: string,
  types: TypeOutfieldsType[],
  fieldNames: string[],
  fieldAliases?: string[]
): void

Parameters:

  • layerPath - The path of the layer
  • types - Array of field types (e.g., 'string', 'number', 'date')
  • fieldNames - Array of field names
  • fieldAliases - Optional array of field aliases

Throws: LayerDifferingFieldLengths if array lengths don't match

Example:

mapViewer.layer.replaceFeatureOutfields(
  "myLayer",
  ["string", "number", "number"],
  ["name", "population", "area"],
  ["Name", "Population", "Area (km²)"]
);

Spatial Operations

Bounds

calculateBounds()

Calculates the bounds/extent of a layer.

calculateBounds(layerPath: string): Extent | undefined

Parameters:

  • layerPath - The path of the layer

Returns: The extent as [minX, minY, maxX, maxY] or undefined

Example:

const bounds = mapViewer.layer.calculateBounds("myLayer");
if (bounds) {
  console.log("Layer bounds:", bounds);
  // Zoom to layer bounds
  mapViewer.map.getView().fit(bounds, { padding: [50, 50, 50, 50] });
}

recalculateBoundsAll()

Recalculates bounds for all layers.

recalculateBoundsAll(): void

Event Handling

The Layer API provides extensive event handling for layer lifecycle and interactions.

Layer Configuration Events

onLayerConfigAdded()

Registers a callback for when a layer configuration is added.

onLayerConfigAdded(callback: LayerBuilderDelegate): void

Callback Signature:

type LayerBuilderDelegate = (
  sender: LayerApi,
  event: LayerBuilderEvent
) => void;

interface LayerBuilderEvent {
  layerConfig: ConfigBaseClass;
  layer: AbstractGeoViewLayer;
}

Example:

mapViewer.layer.onLayerConfigAdded((sender, event) => {
  console.log("Layer config added:", event.layerConfig);
});

offLayerConfigAdded()

Unregisters a layer configuration added callback.

offLayerConfigAdded(callback: LayerBuilderDelegate): void

onLayerConfigRemoved()

Registers a callback for when a layer configuration is removed.

onLayerConfigRemoved(callback: LayerPathDelegate): void

Callback Signature:

type LayerPathDelegate = (sender: LayerApi, event: LayerPathEvent) => void;

interface LayerPathEvent {
  layerPath: string;
}

offLayerConfigRemoved()

Unregisters a layer configuration removed callback.

offLayerConfigRemoved(callback: LayerPathDelegate): void

onLayerConfigError()

Registers a callback for when a layer configuration error occurs.

onLayerConfigError(callback: LayerConfigErrorDelegate): void

Callback Signature:

type LayerConfigErrorDelegate = (
  sender: LayerApi,
  event: LayerConfigErrorEvent
) => void;

interface LayerConfigErrorEvent {
  layerPath: string;
  error: Error;
}

offLayerConfigError()

Unregisters a layer configuration error callback.

offLayerConfigError(callback: LayerConfigErrorDelegate): void

Layer Lifecycle Events

onLayerCreated()

Registers a callback for when a layer is created.

onLayerCreated(callback: LayerDelegate): void

Callback Signature:

type LayerDelegate = (sender: LayerApi, event: LayerEvent) => void;

interface LayerEvent {
  layerPath: string;
  layer: AbstractBaseLayer;
}

Example:

mapViewer.layer.onLayerCreated((sender, event) => {
  console.log("Layer created:", event.layerPath);
});

offLayerCreated()

Unregisters a layer created callback.

offLayerCreated(callback: LayerDelegate): void

onLayerFirstLoaded()

Registers a callback for when a layer loads for the first time.

onLayerFirstLoaded(callback: LayerDelegate): void

offLayerFirstLoaded()

Unregisters a layer first loaded callback.

offLayerFirstLoaded(callback: LayerDelegate): void

onLayerLoading()

Registers a callback for when a layer starts loading.

onLayerLoading(callback: LayerDelegate): void

offLayerLoading()

Unregisters a layer loading callback.

offLayerLoading(callback: LayerDelegate): void

onLayerLoaded()

Registers a callback for when a layer finishes loading.

onLayerLoaded(callback: LayerDelegate): void

offLayerLoaded()

Unregisters a layer loaded callback.

offLayerLoaded(callback: LayerDelegate): void

onLayerAllLoaded()

Registers a callback for when all configured layers have loaded.

onLayerAllLoaded(callback: LayerConfigDelegate): void

Callback Signature:

type LayerConfigDelegate = (sender: LayerApi, event: LayerConfigEvent) => void;

interface LayerConfigEvent {
  layerConfigs: ConfigBaseClass[];
}

offLayerAllLoaded()

Unregisters an all layers loaded callback.

offLayerAllLoaded(callback: LayerConfigDelegate): void

onLayerError()

Registers a callback for when a layer error occurs.

onLayerError(callback: LayerErrorDelegate): void

Callback Signature:

type LayerErrorDelegate = (sender: LayerApi, event: LayerErrorEvent) => void;

interface LayerErrorEvent {
  layerPath: string;
  error: Error;
}

Example:

mapViewer.layer.onLayerError((sender, event) => {
  console.error("Layer error:", event.layerPath, event.error);
});

offLayerError()

Unregisters a layer error callback.

offLayerError(callback: LayerErrorDelegate): void

Layer Status Events

onLayerStatusChanged()

Registers a callback for when a layer's status changes.

onLayerStatusChanged(callback: LayerStatusChangedDelegate): void

Callback Signature:

type LayerStatusChangedDelegate = (
  sender: LayerApi,
  event: LayerStatusChangedEvent
) => void;

interface LayerStatusChangedEvent {
  layerPath: string;
  status: TypeLayerStatus; // 'registered', 'loading', 'loaded', 'error', etc.
}

Example:

mapViewer.layer.onLayerStatusChanged((sender, event) => {
  console.log(`Layer ${event.layerPath} status: ${event.status}`);
});

offLayerStatusChanged()

Unregisters a layer status changed callback.

offLayerStatusChanged(callback: LayerStatusChangedDelegate): void

Layer Visibility Events

onLayerVisibilityToggled()

Registers a callback for when a layer's visibility is toggled.

onLayerVisibilityToggled(callback: LayerVisibilityToggledDelegate): void

Callback Signature:

type LayerVisibilityToggledDelegate = (
  sender: LayerApi,
  event: LayerVisibilityToggledEvent
) => void;

interface LayerVisibilityToggledEvent {
  layerPath: string;
  visible: boolean;
}

Example:

mapViewer.layer.onLayerVisibilityToggled((sender, event) => {
  console.log(`Layer ${event.layerPath} visibility: ${event.visible}`);
});

offLayerVisibilityToggled()

Unregisters a layer visibility toggled callback.

offLayerVisibilityToggled(callback: LayerVisibilityToggledDelegate): void

onLayerItemVisibilityToggled()

Registers a callback for when a layer item's visibility is toggled.

onLayerItemVisibilityToggled(callback: LayerItemVisibilityToggledDelegate): void

Callback Signature:

type LayerItemVisibilityToggledDelegate = (
  sender: LayerApi,
  event: LayerItemVisibilityToggledEvent
) => void;

interface LayerItemVisibilityToggledEvent {
  layerPath: string;
  item: TypeLegendItem;
  visible: boolean;
}

offLayerItemVisibilityToggled()

Unregisters a layer item visibility toggled callback.

offLayerItemVisibilityToggled(callback: LayerItemVisibilityToggledDelegate): void

Advanced Features

Layer Sets

The Layer API maintains several specialized layer sets for different purposes:

legendsLayerSet

Manages layer legend information.

mapViewer.layer.legendsLayerSet;

featureInfoLayerSet

Manages feature information from map clicks.

mapViewer.layer.featureInfoLayerSet;

hoverFeatureInfoLayerSet

Manages feature information from hover interactions.

mapViewer.layer.hoverFeatureInfoLayerSet;

allFeatureInfoLayerSet

Manages all feature information (click + hover).

mapViewer.layer.allFeatureInfoLayerSet;

Geometry API

Access geometry manipulation functions:

mapViewer.layer.geometry;

See Geometry API Documentation for details.

Feature Highlighting

Access feature and bbox highlighting:

mapViewer.layer.featureHighlight;

Methods:

  • highlightFeatures(features, style) - Highlight specific features
  • clearHighlights() - Clear all feature highlights

Error Handling

The Layer API can throw various errors:

import {
  LayerNotFoundError,
  LayerNotGeoJsonError,
  LayerNotQueryableError,
  LayerWrongTypeError,
  LayerDifferingFieldLengths,
  LayerCreatedTwiceError,
} from "@/core/exceptions/layer-exceptions";

try {
  const layer = mapViewer.layer.getGeoviewLayer("nonexistent");
} catch (error) {
  if (error instanceof LayerNotFoundError) {
    console.error("Layer not found");
  }
}

Best Practices

1. Check Layer Existence

// Use safe methods when unsure if layer exists
const layer = mapViewer.layer.getGeoviewLayerIfExists("myLayer");
if (layer) {
  // Work with layer
}

2. Wait for Layers to Load

mapViewer.layer.onLayerAllLoaded((sender, event) => {
  console.log("All layers loaded");
  // Perform operations that require all layers
});

3. Handle Layer Errors

mapViewer.layer.onLayerError((sender, event) => {
  // Show user-friendly error message
  console.error(`Failed to load layer: ${event.layerPath}`);
});

4. Clean Up Event Listeners

const handleLayerLoaded = (sender, event) => {
  console.log("Layer loaded:", event.layerPath);
};

// Register
mapViewer.layer.onLayerLoaded(handleLayerLoaded);

// Later, clean up
mapViewer.layer.offLayerLoaded(handleLayerLoaded);

5. Use Async Methods for Dynamic Layers

// When adding layers dynamically, wait for them
const result = mapViewer.layer.addGeoviewLayer(config);
const olLayer = await mapViewer.layer.getOLLayerAsync(
  result.layerConfig.layerPath
);

Common Use Cases

Adding a WMS Layer

mapViewer.layer.addGeoviewLayer({
  geoviewLayerId: "wmsLayer",
  geoviewLayerName: "WMS Layer",
  geoviewLayerType: "ogcWms",
  metadataAccessPath: "https://example.com/wms",
  listOfLayerEntryConfig: [
    {
      layerId: "layer1",
      layerName: "Layer 1",
    },
  ],
});

Toggling Layer Visibility

const button = document.getElementById("toggle-layer");
button.addEventListener("click", () => {
  mapViewer.layer.setOrToggleLayerVisibility("myLayer");
});

Highlighting a Layer on Hover

const layerList = document.getElementById("layer-list");
layerList.addEventListener("mouseenter", (e) => {
  const layerPath = e.target.dataset.layerPath;
  mapViewer.layer.highlightLayer(layerPath);
});

layerList.addEventListener("mouseleave", () => {
  mapViewer.layer.removeHighlightLayer();
});

Updating GeoJSON Data

// Fetch new data
const response = await fetch("/api/updated-data");
const geojson = await response.json();

// Update layer
mapViewer.layer.setGeojsonSource("myGeoJsonLayer", geojson);

Layer Sets

The Layer API provides access to four Layer Sets that automatically manage layer-specific data:

  • legendsLayerSet - Legend and symbology information for all layers
  • featureInfoLayerSet - Feature information at specific locations (for map clicks)
  • allFeatureInfoLayerSet - All features from all layers (for data tables, exports)
  • hoverFeatureInfoLayerSet - Feature information under mouse cursor (for tooltips)

Quick Example:

// Access legend data
const legendsLayerSet = mapViewer.layer.legendsLayerSet;
Object.values(legendsLayerSet.resultSet).forEach((entry) => {
  console.log(`Legend for ${entry.layerName}:`, entry.items);
});

// Query features on click
mapViewer.onMapSingleClick((sender, payload) => {
  mapViewer.layer.featureInfoLayerSet.queryLayers(payload.lnglat).then(() => {
    // Access queried features
    Object.values(mapViewer.layer.featureInfoLayerSet.resultSet).forEach(
      (entry) => {
        console.log(
          `Features in ${entry.layerName}:`,
          entry.featureInfo?.features
        );
      }
    );
  });
});

For complete Layer Sets documentation, examples, and patterns, see:

? Layer Sets Guide

See Also