Revisions

Introduction

The NRS Common Web Mapping Service provides a simple, powerful and lightweight mapping capability for applications which support web-browser based clients. The CWM is integrated with the NRS ISSS service-based architecture. It fully supports the ISSS Operational Spatial Database.

The CWM provides an HTML component (including CSS and JavaScript) which can be added to host application web pages to display and interact with maps and spatial data. The component provides a simple API to let host pages interact with the map to display and manipulate spatial data. The component is implemented using modern development practices for JavaScript, CSS and HTML5.

The CWM supplies services which can be requested by the mapping component and other applications to facilitate interacting with and displaying spatial data.

Purpose

This document assists developers to design and build host applications which utilize the CWM Map Component and associated services.

Audience

This document is targeted at developers who are responsible for designing and implementing spatially-enabled applications within the Natural Resource Sector.

Scope / Exclusions

This document addresses the development of browser-based web mapping applications using the CWM map component.

It does not describe how to configure and manage data and layers which the map client accesses. It does not describe how to store and manage spatial data within application data models, apart from best practices which simplify the development of spatial functionality for web clients.

Assumptions

This document assumes familiarity with

• the principles of web mapping and spatial data handling in client applications
• the OpenLayers documentation.

Related Documents

• NRS GeoServer Administrator Guide

Overview

The CWM Client component is a web component which can be deployed in a host web page to provide web map display along with spatial data search and manipulation. It is primarily intended to support web mapping needs within the BC Government Natural Resource Sector.

CWM is intended to support “Map-in-an-App” style applications, as well as the common “App-in-a-Map” paradigm.

The visual appearance and operation of the CWM map display is designed to be minimalist and unobtrusive in order to harmonize with the widest variety of web page designs. At the same time, the client offers a very rich set of functionality. It takes full advantage of the dynamic display capabilities of modern HTML5 technology.

The CWM Client component is designed take full advantage of the powerful capabilities of modern browsers. All map functionality is executed within the client browser itself, with only spatial data being provided by external services. This provides a performant, feature-rich client experience. It offers maximum flexibility to developers needing to provide custom spatial functionality in their applications.

Wherever possible the CWM Client utilizes modern, mature open source components. Its core code libraries are OpenLayers 2 and jQuery. As well as simplifying code development these libraries provide a high degree of browser platform independence.

The CWM Client supports modern open web mapping standards to provide connectivity to web map services. It supports connecting to WMS and WFS map services. Other spatial standards supported include WKT, GPX, KML, GML, GeoJSON, and Shapefile.

BC Government spatial data services supported include:

• GeoMark (import and export)

• BC GeoNames service (location search)

• BC Physical Address GeoCoder (address geocoding)

• BC Government tiled base maps

The CWM client provides numerous functions which can be configured according to the needs of the host application. These include:

• Display of many different tiled base maps

• Connection to web map services to provide spatial data for display and querying

• Connection to spatial query services to support location searching and geocoding

• Creation and editing of spatial geometry for display and upload

• Measurement of Distance and Area

• Import and Export of spatial datasets, in a variety of formats including WKT, GPX, KML, GeoJSON, GeoMark and ESRI Shapefile

• Printing of maps

• A Javascript API to allow the host page to interact with spatial data and the CWM map

Architecture

The following diagram shows the architecture of the CWM Client web component, how it is deployed in a host web application, and how it connects to external mapping services.

CWM Map User Interface

The following image shows a typical CWM map layout and display. It shows most of the available tools and controls configured for operation.

Installation

Supported Browsers

The client component is tested to work on the following browsers:

• Internet Explorer 11 and up. (A subset of CWM will function in IE8-10. Functions which do not work in IE11 degrade gracefully, and are identified where known)

• Chrome (current version)

• Firefox (current version)

• Safari (current version)

In order to be functional across a wide range of browser types and versions, the CWM framework is conservative in what web client technologies are used. In addition, the libraries it uses (OpenLayers and jQuery) support a wide range of browser profiles. However, in order to provide some functions in the most user-friendly way some new browser APIs are utilized. Wherever possible, alternatives are provided that will work on older browsers.

Dependencies

The following Javascript libraries are used by the CWM Component.

• OpenLayers v2.13

• jQuery v1.11.2

• JSTS v0.13.2

• Proj4js v1.1.0

• Rbush v1.3.0

• Shp v3.1.4

• AJV v4.0.1

• Download v4.0.0

These libraries are included in the CWM installation package and are deployed along with it.

Deployment

The CWM Client is a web component. It is not a standalone web site. It is deployed in a host page, which is the artifact that a browser actually displays. The life-cycle of the map is delimited by that of the host page. The host page may be a page in a multi-page application, or it may follow the style of a Single-Page Application (SPA), where the entire application exists inside a single page. A page may contain multiple instances of CWM maps, each with their own markup and initialization code. A multi-page application may contain many pages which contain different maps. A page can create and destroy instances of the CWM maps as many times as it needs to.

There are two different ways to use the CWM Client library in your web application:

• Deployed with the host application
• Linking to publically deployed instance.

Deployed with the host application

First, let's assume your application's source code located on your machine at /APP_SRC and the application is deployed to APP_URL. Start by downloading the CWM library. Copy the contents of this zip into the source code of your application, for this discussion let's assume it is copied to /APP_SRC/lib/cwm. Let's assume that this directory is exposed by the application as APP_URL/lib/cwm. The integration instructions that follow assume that publically deployed instance is being used, so some of the URLs used will have to be adjusted.

In the section Host Page Integration:

• Change URLs that begin with //$host$prefixPath to begin with APP_URL/lib/cwm.

Linking to publically deployed instance

The section Host Page Integration assumes that the application is using the publically deployed instance.

Host Page Integration

There are four pieces that need to be put in place to integrate the CWM client into an application.

• The CWM client stylesheet
• The <div> element that contains the CWM client UI
• The CWM client javascript library and it's dependencies
• The javascript code that initializes the CWM client

The stylesheet

Add this inside the <head> element of the page:

<link rel="stylesheet" type="text/css" href="//$host$prefixPath/cwm.css">

The styles have been named in a way that is intended to avoid conflicts with host page styling.

CWM styling attempts to provide a standard look and feel that is in harmony with current BC Government web standards.

CWM styles are not intended to be modified by developers. In some rare cases there may be conflicts with host page styles. If possible the host page styles should be altered to avoid conflict. Alternatively, CWM styles can be enhanced or modified to avoid the conflict (e.g. by introducing additional properties to explicitly set styling, or by judicious use of the “!important” declaration).

The <div> element

Each instance of the CWM client UI in the application will need a container <div>. The <div> must be identified by a unique id, and it must exist in the DOM before the CWM client can be initialized. The <div> must be sized and positioned by the application, the CWM client code does nothing to affect it's size or position. The <div> should not contain any elements, it will be populated by the CWM library.

Here is an example <div> that would be anywhere in the <body> of the application:

<div id="map" style="width: 800px; height: 512px; border: 1px solid black"></div>

Here is another example <div> that fills the browser frame, except for a 100px area on the right:

<div id="map" style="position: absolute; left: 0; top: 0; bottom: 0; right: 100px"></div>

The CWM client javascript library

The CWM client javascript library and it's dependencies should be loaded at the end of <body> element, but before the client initialization code.

<script src="//$host$prefixPath/lib/jquery-1.11.2.js"     ></script>
<script src="//$host$prefixPath/lib/proj4js-1.1.0.js"     ></script>
<script src="//$host$prefixPath/lib/OpenLayers-2.13.1.js" ></script>
<script src="//$host$prefixPath/lib/rbush-1.3.0.js"       ></script>
<script src="//$host$prefixPath/lib/jsts-util-0.13.2.js"  ></script>
<script src="//$host$prefixPath/lib/ajv-4.0.1.js"         ></script>
<script src="//$host$prefixPath/lib/shp-3.1.4.js"         ></script>
<script src="//$host$prefixPath/lib/download-4.0.0.js"    ></script>
<script src="//$host$prefixPath/CWM.js"                   ></script>

Initializing the CWM client

The CWM client object must be initialized before it can be used. To initialize the CWM client, one or more configuration objects must be provided to a factory method. The structure of the configuration objects is documented below in Configuration. The factory method CWM.createMap takes the id of the <div> to contain the CWM client UI, followed by a list of configuration objects. The configuration objects are either javascript objects, or URLs which are assumed to be references to files containing configuration represented in JSON.

The configuration objects have their values merged together, collapsing left-wards. This means that if two there are two configurations:

A = { "map":{ "print":{ "title": "#1" }}}

B = { "map":{ "print":{ "title": "#2" }}}

that are given to createMap as [A,B], then the resulting print.title value would be "#2". If they given to createMap as [B,A], then the resulting print.title value would be "#1".

However, when a configuration value is an array, then succeeding configuration values will be appended, instead of replacing the earlier value. So, if there are two configurations:

A = { "map": { "tools": [ { "toolType": "MARKUP_TOOLBAR" }]}}

B = { "map": { "tools": [ { "toolType": "MEASURE" }]}}

that are given to createMap as [A,B], then the resulting tools would be [{toolType:"MARKUP_TOOLBAR"},{toolType:"MEASURE"}]. This allows splitting apart the configuration into separate objects when it is convienient.

The third argument to createMap is an options object. The options are:

• validate (type: boolean, default: true)

  The configuration objects are validated against a schema, and createMap will fail if an configuration object is not valid. Set this option to false to suppress this validation.

• validateFail (type: boolean, default: true)

  If a configuration object fails to validate, then createMap will fail. Set this option to false to see the error message but allow createMap to continue.

• parameters (type: object, default: {})

  This option facilitates parameter substitution into configuration objects. If a value in a configuration object is a string containing a substring like <%= foo %> and the parameters object has a key named "foo", then the stringified value of "foo" will be substituted in the configuration object's value. If-and-only-if the configuration value is exactly a string like <%= foo %>, then the value from the parameters object will be substituted exactly, without stringification. In all cases, any substitution happens before the configuration object is validated.

The createMap method returns a Promise. The caller can attach a done handler, and/or a fail handler. The done handler will get two arguments:

• api (type: CWM.MapApi)

  The API that the host application uses for interacting with the CWM client object. This object's interface is documented, and can be relied on to not change between releases.

• map (type: CWM.Map)

  The internal object representing the CWM client. It's interface is undocumented, and shouldn't be relied on to remain constant between releases. There is one method on this object that may be needed:

  • map.destroy() will dispose of the CWM client object, and disconnect it from the containing <div>.

The sample initialization script presented below must occur in the HTML <body> after the CWM client libraries (see previous section). This assumes that configuration files exist at the same location as the application's HTML file, and are called map-config.json and overlay-config.json.

<script>

// This function is called when the page is fully loaded.
$( function() {

    // Create a map on the DIV with id 'map', using map-config.json and overlay-config.json for configuration.
    CWM.createMap(
        'map',
        [
          "map-config.json",
          "overlay-config.json",
        ]
      )
      .done( mapCreated )
      .fail( mapFailed )

    // mapCreated is called when the map is successfully initialized.
    // The argument is a reference to a CWM.MapApi object, so the host application can interact with the map.
    function mapCreated( api ) {
        console.log( "map created" )
    }

    // mapFailed is called when the map failed to initialize.
    // If this function is called, then the map is not usable.
    function mapFailed( err ) {
        console.warn( "createMap failed:", err )
    }
} )

</script>

Sample page

Here is a complete HTML file that puts all the pieces above together. The map is styled so that it fills the entire browser window.

<!DOCTYPE html>
<html>

<head>
    <title>CWM Sample</title>
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

    <!-- CWM style sheet - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <link rel="stylesheet" type="text/css" href="//$host$prefixPath/cwm.css">
</head>

<body>
    <!-- CWM map div - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <div id="map" style="position: absolute; top: 0; left: 0; right: 0; bottom: 0;"></div>

    <!-- CWM libraries - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <script src="//$host$prefixPath/lib/jquery-1.11.2.js"     ></script>
    <script src="//$host$prefixPath/lib/proj4js-1.1.0.js"     ></script>
    <script src="//$host$prefixPath/lib/OpenLayers-2.13.1.js" ></script>
    <script src="//$host$prefixPath/lib/rbush-1.3.0.js"       ></script>
    <script src="//$host$prefixPath/lib/jsts-util-0.13.2.js"  ></script>
    <script src="//$host$prefixPath/lib/ajv-4.0.1.js"         ></script>
    <script src="//$host$prefixPath/lib/shp-3.1.4.js"         ></script>
    <script src="//$host$prefixPath/lib/download-4.0.0.js"    ></script>
    <script src="//$host$prefixPath/CWM.js"                   ></script>

    <!-- CWM initialization  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <script>
    $( function() {
        CWM.createMap(
              'map',
              [
                "map-config.json",
                "overlay-config.json",
              ]
          )
          .done( mapCreated )
          .fail( mapFailed )
    } )

    function mapCreated( api ) {
        console.log( "map created" )
    }

    function mapFailed( err ) {
        console.warn( "createMap failed:", err )
    }
    </script>

</body>
</html>

Configuration

This section describes how to configure the appearance and behaviour of a single CWM map. This is done by constructing a JSON object.

Previous versions of CWM used a Javascript object for configuration. This is still possible using the legacy host integration method detailed above, but that method is deprecated.

The object describes a set of properties that are used by the CWM framework to construct, render and operate a map. At the highest level, the configuration object looks like:

{
    "map": {
        // map configuration
    },
    "overlays": [
        // overlay configuration
    ]
}

Every CWM configuration object will look like this at the top-level. However, generally only one of map or overlays will be present.

Each of the sections is described by a JSON Schema, which fully describes what a valid object looks like. These schemas are used in the CWM framework to validate the configuration file when the application initializes the CWM map. If the validation fails, the map will not be functional.

The configuration sections are described below.

Map Configuration

The map configuration controls the user interface that the CWM framework will present to the user. The sets of user interface elements that are configured:

• Tools
• Base maps
• Coordinate formats
• Print layouts

Also configurable are the style used by highlight, identify, markup, selection, and search internal layers.

Tools

This ia a table of all the tools that are available for use on the map. The tools property in the map configuration contains the set of identifiers that configure what tools the map will use. Each tool appears at a specific location on the map, one of:

• Navigation, bar on left of map
• Main, toolbar at top left of map
• AOI, toolbar under main toolbar
• Selection, toolbar under main toolbar
• {|Layers}, toolbar at top right of map
• Decorators, widgets on bottom edge of map

AOI tools will appear in the Main toolbar if the AOI_TOOLBAR tool is not used. Ditto for Selection tools.

Base Map

One or more Base Maps can be defined for a given map. The user can switch between them using a map control.

CWM provides a number of predefined base maps. These include standard government base maps (maintained by DataBC), open base maps, and commercial base maps. The use of commercial base maps is subject to the licensing arrangements of the BC government. The CWM project has verified the licensing to the best of its ability.

Predefined Base maps can be added to a map configuration by specifying their code.

Coordinate Formats

Client-side Print Layouts

CWM supports client-side printing via HTML Print Templates. Client-side printing means that the map and surround are rendered in the browser. The map.print.layouts collection contains all the print layouts defined. Client-side print layouts are defined with "type": "local". Client-side printing uses a print template, which is an HTML page, along with a Javascript file (normally this code does not need to be changed).

A sample print template is included with the CWM assets. Other templates may be created and deployed as needed.

To construct a new print template, start by copying cwm/assets/print-landscape.html to a new file (for example, cwm/assets/print-new.html). Modify the CSS in the <style> tag and contents of the <body> to adjust the layout to your needs. The print engine populates the template by inserting content into <div> elements with certain ids. The ids it uses are:

Any property put into the param object in a print layout configuration is the id of the element that will get that properties value. For example, if the print layout config is like this:

{
    "map": {
        "print": {
            "layouts": [
                {
                    "type":  "local",
                    "name":  "local-layout-1",
                    "title": "New layout",
                    "url":   "cwm/assets/print-new.html",
                    "param": {
                        "logo":        "<img src=\"logo_bcgov.gif\" />",
                        "legendTitle": "Legend",
                        "information": "More information"
                    }
                }
            ]
        }
    }
}

The ids logo, legendTitle, and information in print template will populated with the values of those properties from this configutation.

Server-side Print Layouts

CWM supports server-side printing via the Map Image Service (MIS). Server-side printing means that the map and surround are rendered on another machine, and the resulting image (a PDF) is sent to the browser. The map.print.layouts collection contains all the print layouts defined. Server-side print layouts are defined with "type": "server". A server-side print layout using MIS will need to follow the following pattern:

{
    "map": {
        "print": {
            "layouts": [
                {
                    "type":  "server",
                    "name":  "<layout-name>",
                    "title": "<layout-title>",
                    "url":   "<mis-service-url>",
                    "layout": "<layout>",
                    "authorization": {
                        "access_token": "<oauth-token>"
                    }
                }
            ]
        }
    }
}

Where:

• <layout-name>

  The name that will be used to identify the layout internally. This name is not seen by user, should not contain whitespace, and must be unique.

• <layout-title>

  The title of the layout, that will be seen by user in the print layout drop-down list.

• <mis-service-url>

  The URL of the Map Image Service. At this time, the URL is (depending on deployment environment):

• <layout>

  The Map Image Service has a predefined list of map layout templates defined. The templates curretly defined are:

• <oauth-token>

  Access to the Map Image Service needs to be by an authenticated user. The OAuth token will be need to be retrieved by somehow (outside scope of this document), and placed into this property. The createMap parameter substitution mechanism discussed at Initializing the CWM client will be useful for this.

Map Configuration Schema

Here is the entire schema structure for the map configuration.

Overlay configuration

The CWM map can display multiple Overlays of map data.

An Overlay is a separate layer image in the OpenLayers map. It can be made visible or invisible independently of other overlays. It can be tiled or a single image. Its opacity can be controlled. It can display any number of service layers. In the case of overlays supplied by external services, the content is obtained by one or more network requests.

Layer

An Overlay Layer is a service layer within an Overlay which is based on a WMS or ArcGIS Map Service layer.

Layers can be made visible and invisible, but this will generally require a redrawing of the Overlay via network requests.

The only exception is when an Overlay is showing a single layer, and that layer is made invisible. In this case CWM makes the overlay invisible.

An overlay layer is defined by the following commonly used properties (see the Schema for the full set):

Overlay Configuration schema

Here is the entire schema structure for the overlay configuration.

Javascript API

The CWM Client provides a Javascript API to allow host pages to configure, control and query the state of the client model and user interface.

CWM

Methods

createMap( div, configurations, option )

Configures and creates a CWM Map. Loads configuration dynamically, from objects or JSON file resources.

Returns: Promise

The done handler will get the CWM.MapApi object as first parameter. The fail handler will get an error message as first parameter.

Params:

• div String

  Id of the <div> that will contain the map

• configurations Array

  Array of configuration to be applied to the CWM map object. Each element is an object or a URL pointing to a JSON object. Config objects are applied in order starting from beginning of array.

• option Object

  Optional arguments

  • validate Boolean - Perform validation on configuration objects, default true.
  • validateFail Boolean - Fail this method if validating a configuration object fails, default true.
  • parameters Object - Any pattern like <%= (token) %> appearing a configuration object is replaced with the value of option.parameters[ (token) ] (if it is defined).

CWM.MapBuilder

Configures and creates a CWM map component. The map configuration objects must already be loaded into the page context, e.g. via inline script elements.

Methods

addMapConfig( mapConfig )

Add to the map's UI configuration.

Params:

• mapConfig CWM.MapConfig

addOverlayConfig( overlayConfig )

Add to the map's overlay configuration.

Params:

• overlayConfig CWM.OverlayConfig

createMap( mapDiv )

Create a new map, and return a CWM.MapApi object. as its interface.

Returns: CWM.MapApi

Params:

• mapDiv String

  The id of the <div> that will contain the map viewport.

CWM.MapApi

The public API that the host application will use to interact with the CWM client map.

This object is returned by a successful call to CWM.createMap, and gives the host application the ability to control some aspects of the CWM client map.

This API is broken down further into sub-objects. These are the sub-objects available on the MapAPI object:

• CWM.MapApi.viewport
• CWM.MapApi.navigation
• CWM.MapApi.aoi
• CWM.MapApi.identify
• CWM.MapApi.selection
• CWM.MapApi.highlight
• CWM.MapApi.marker
• CWM.MapApi.markup
• CWM.MapApi.print
• CWM.MapApi.link
• CWM.MapApi.overlay

CWM.MapApi.viewport

Public API for controlling viewport of the CWM map.

Methods

viewport.refresh( )

Refreshes the map content (e.g. after viewport size change).

CWM.MapApi.navigation

Public API for controlling navigation on the CWM map.

Methods

navigation.getCenter( )

Returns the current center of the viewport in geographic coordinates.

Returns: LatLon

navigation.getExtent( )

Returns the current bounds of the viewport in geographic coordinates.

Returns: Array

[LatMin,LonMin,LatMax,LonMax]

navigation.pan( point, maxRadius )

Move the viewport to center it on a point in geographic coordinates, with the bounds of viewport adjusted so that the given radius from the center is visible.

Params:

• point LatLon

  Center of viewport

• maxRadius Number

  Distance from center to be made visible

navigation.isMouseWheelEnabled( )

Is the mouse wheel enabled for zooming?

Returns: Boolean

True if mouse wheel is enabled for zooming

navigation.setMouseWheelEnabled( enable )

Enable or disable mouse wheel zooming on the map

Params:

• enable Boolean

  Enable mouse wheel zooming

navigation.onChange( callback )

When the visible extent of the map is changed, this callback will be invoked.

• This method can be called many times with different callbacks, and all will be called when event is triggered.
• If this method is called with no arguments, all callbacks will be removed from this event.

Params:

• callback Function

  Callback will receive no arguments, return value is ignored.

navigation.zoom.toBC( )

Zoom viewport to show the full extent of BC.

navigation.zoom.toAOI( )

Zoom viewport to show the full extent of the current AOI.

navigation.zoom.toExtent( bounds )

Zoom viewport to show the given extent.

Params:

• bounds Array|Geometry

  An array like [LatMin,LonMin,LatMax,LonMax], or a geometry object

navigation.zoom.toLevel( point, level )

Move viewport to center on a point, and set zoom level.

Params:

• point Array

  An array like [Lat,Lon]

• level Number

  Zoom level, 0 is whole world

navigation.zoom.toRadius( point, radius )

Move viewport to center on a point, and set extent so that given radius from point is visible.

Params:

• point Array

  An array like [Lat,Lon]

• radius Number

  Minimum offset from point so show in viewport extent

navigation.zoom.toSelection( )

Center the viewport so that all selected features are visible. Does nothing if no features are selected.

navigation.zoom.toHighlight( )

Center the viewport so that all highlighted features are visible. Does nothing if no features are highlighted.

navigation.zoom.getLevel( )

Get the current zoom level

Returns: Number

Current zoom level

CWM.MapApi.aoi

Public API for controlling the area-of-interest on the CWM map.

Methods

aoi.getCount( )

Get the number of geometries currently defined in the AOI.

Returns: Number

aoi.getGeometries( )

Get all the geometries currently in the AOI.

Returns: Array

An array of geometry objects

aoi.getPrimaryGeometry( )

Get the first (primary) AOI geometry.

Returns: Geometry

aoi.getSecondaryGeometries( )

Get the non-first (secondary) AOI geometries.

Returns: Array

An array of geometry objects

aoi.clear( )

Clear all geometries in the AOI.

aoi.removeLast( )

Remove the most-recently added geometry.

aoi.addGeometry( geometry )

Add a geometry to the AOI.

The first geometry added to AOI after aoi.clear() will be the primary geometry. Subsequent additions are the secondary geometries.

Params:

• geometry Geometry

  Addition to AOI.

aoi.onChange( callback )

When the AOI changes, this callback will be invoked.

• This method can be called many times with different callbacks, and all will be called when event is triggered.
• If this method is called with no arguments, all callbacks will be removed from this event.

Params:

• callback Function

  Callback will receive no arguments, return value is ignored.

CWM.MapApi.identify

Public API for controlling the identified features on the CWM map.

Methods

identify.clear( )

Clear the set of identified features. Hides panel if visible. Triggers onChange; don't call this method from this callback.

identify.getFeatures( )

Get all the features currently identified.

Returns: Array

An array of {CWM.Feature}s

identify.showFeatures( order, layer, features )

Shows the identify panel. If arguments are provided, adds features details for a layer. If the layer already exists on the panel, it's set of features is replaced. Triggers onChange; don't call this method from this callback.

Params:

• order Integer

  [ignored, set to null]

• layer Layer

  A Layer object

• features Array

  An array of features

identify.onChange( callback )

When the displayed list of identified features changes, this callback will be invoked.

• This method can be called many times with different callbacks, and all will be called when event is triggered.
• If this method is called with no arguments, all callbacks will be removed from this event.

Params:

• callback Function

  Callback will receive no arguments, return value is ignored.

identify.onStart( callback )

When an identify features operation starts, this callback will be invoked.

• This method can be called many times with different callbacks, and all will be called when event is triggered.
• If this method is called with no arguments, all callbacks will be removed from this event.

Params:

• callback Function

  Callback will receive no arguments, return value is ignored.

identify.onLayer( callback )

When an identify features operation gets the result for a layer, this callback will be invoked.

• This method can be called many times with different callbacks, and all will be called when event is triggered.
• If this method is called with no arguments, all callbacks will be removed from this event.

Params:

• callback Function(order,layer,features)

  Callback will receive 3 arguments, return value is ignored.

identify.onFinish( callback )

When an identify features operation is finished, this callback will be invoked.

• This method can be called many times with different callbacks, and all will be called when event is triggered.
• If this method is called with no arguments, all callbacks will be removed from this event.

Params:

• callback Function

  Callback will receive no arguments, return value is ignored.

CWM.MapApi.selection

Public API for controlling the selected features on the CWM map.

Methods

selection.clear( )

Clear the set of selected features.

selection.getCount( )

Get the size of the selection set.

Returns: Number

Number of features selected.

selection.getAttributes( )

REMOVED Use code like this to achieve the same effect:

var attributes = $.map( api.selection.getFeatures(), function ( f ) {
    // filter out layers that don't have the attribute needed
    if ( f.layerId != '<layer-id>' ) return;

    return f.attributes[ '<attribute-name>' ]
} )

selection.getFeatures( )

Get the features in the selection set.

Returns: Array

Array of CWM.Feature

selection.remove( features )

Remove some features from the selection set.

Params:

• features CWM.Feature|Array

  A CWM.Feature or an array of same.

selection.addFeaturesByAttribute( layer, attribute, values, onSuccess, onFailure )

Add to selection set from the selection layer, by taking features matching some values for a particular attribute. This operation happens asynchronously.

Params:

• layer Layer

  (optional) Layer to search for features to add. The object returned by overlay.getOverlay(i).getLayer(j) can be used here. The layerId from overlay.getOverlay(i).getLayer(j).getId() can be used here.

  This parameter can be omitted, if the map is configured with exactly 1 selectable layer. If the map has more than 1 selectable layer, then this parameter must specified. The layer specified must be marked selectable.

• attribute String

  The name of the attribute to match against.

• values Array

  The values to match attribute with.

• onSuccess Function(features)

  (optional) Callback invoked when the features are successfully fetched and added to selection. Receives 1 argument, return value is ignored.

• onFailure Function(code,status,response)

  (optional) Callback invoked when the features were not successfully fetched. Receives 3 arguments, return value is ignored.

selection.onChange( callback )

When the set of selection features changes, this callback will be invoked.

• This method can be called many times with different callbacks, and all will be called when event is triggered.
• If this method is called with no arguments, all callbacks will be removed from this event.

Params:

• callback Function

  Callback will receive no arguments, return value is ignored.

CWM.MapApi.highlight

Public API for controlling the highlighted features on the CWM map.

Methods

highlight.clear( )

Clear the set of highlighted features.

highlight.getCount)( )

Get the size of the selection set.

Returns: Number

Number of features selected.

highlight.getGeometries( )

Get an array of geometries that are currently highlighted.

Returns: Array

Array of geometries

highlight.addGeometry( geometry )

Add geometries to the highlight set.

Params:

• geometry Geometry

highlight.addGeometriesFromLayerByAttribute( layer, attribute, values, onSuccess, onFailure )

Add to highlight set some features selected from a layer. Takes features matching some values for a particular attribute. This operation happens asynchronously.

Params:

• layer Layer

  Layer to search for features to add. The object returned by overlay.getOverlay(i).getLayer(j) can be used here. The layerId from overlay.getOverlay(i).getLayer(j).getId() can be used here.

  DEPRECATED The layer can also be specified like: 'OVERLAY_ID/LAYER_NAME', where OVERLAY_ID is the id or title of overlay from config, and LAYER_NAME is the internal name of a layer in that overlay.

• attribute String

  The name of the attribute to match against.

• values Array

  The values to match attribute with.

• onSuccess Function(features)

  Callback invoked when the features are successfully fetched and added to selection. Receives 1 argument, return value is ignored.

• onFailure Function(code,status,response)

  Callback invoked when the features were not successfully fetched. Receives 3 arguments, return value is ignored.

CWM.MapApi.marker

Public API for controlling the location markers on the CWM map.

Methods

marker.clear( )

Clear the marker set.

marker.addMarker( marker, style )

Add a marker. A marker is an object { position: [x,y], extent: [x1,y1,x2,y2], name:string, description:string }.

Params:

• marker CWM.Marker

  Marker object

• style Style

  Style to use for marker

CWM.MapApi.markup

Public API for controlling printing features on the CWM map.

Methods

markup.clear( )

Clear the markup set.

markup.addGeometry( geometry, style )

Add a geomtry to the markup set.

Params:

• geometry Geometry

  Markup geometry to add

• style Style

  Style to use for markup

print.clear( callback )

Set the function to be called when the server-side print layout needs to get an OAuth authentication token. The provided function will receive a function as a argument, and this function must be called with the token as the first argument. If a token can't be obtained, then the function should be called with first parameter undefined, and an optional error message as second argument.

Params:

• callback Function(done)

  Callback invoked when an OAuth token is needed. Callback should get token, and then call done(token), or done(null,errorMessage).

CWM.MapApi.util

Public utility functions

CWM.MapApi.link

Public API for linking two instances of CWM client together, so that their navigation is synchronized.

Methods

link.movementWith( otherMap )

Synchronize the movement of otherMap with this map object. Whenever the user zooms or pans this map, then otherMap will make the same movement.

The link can be made bi-directional, by calling this method on otherMap as well.

Params:

• otherMap CWM.MapApi

  The other map

CWM.MapApi.overlay

Public API for accessing the collection of Overlay objects defined for the CWM client map. Each Overlay object contains 1 or more Layer objects.

Methods

overlay.getOverlayCount( )

Get the number of overlays defined.

Returns: Number

Number of overlays defined

overlay.getOverlay( indexOrId )

Get an overlay object.

Returns: Overlay

Params:

• indexOrId Number|String

  Index (0 based) or id of overlay

overlay.getOverlay(i).getId( )

Gets the id of an overlay.

Returns: String

Id of overlay

overlay.getOverlay(i).getTitle( )

Gets the title of an overlay.

Returns: String

Title of overlay

overlay.getOverlay(i).isVisible( )

Gets the visibility of an overlay.

Returns: Boolean

If the overlay is visible

overlay.getOverlay(i).setVisible( visible )

Sets the visibility of an overlay.

Params:

• visible Boolean

  The visibility of overlay

overlay.getOverlay(i).getLayerCount( )

Get the number of layers defined for the overlay.

Returns: Number

Number of layers defined

overlay.getOverlay(i).getLayer( indexOrId )

Get a layer object.

Returns: Layer

Params:

• indexOrId Number|String

  Index (0 based) or id of layer

overlay.getOverlay(i).getLayer(j).getId( )

Gets the id of a layer.

Returns: String

Id of layer

overlay.getOverlay(i).getLayer(j).getTitle( )

Gets the title of a layer.

Returns: String

Title of layer

overlay.getOverlay(i).getLayer(j).getName( )

Gets the name of a layer. This is the name used to refer on the layer on the service providing it, like GeoServer.

Returns: String

Name of layer

overlay.getOverlay(i).getLayer(j).getStyleName( )

Gets the name of the style to be used for this layer.

Returns: String

Style name of layer

overlay.getOverlay(i).getLayer(j).isVisible( )

Gets the visibility of a layer. The visibility of the layer is determined by the this flag, and the visibility of the containing overlay.

Returns: Boolean

If the layer is marked as visible.

overlay.getOverlay(i).getLayer(j).setVisible( visible )

Sets the visibility of a layer.

Params:

• visible Boolean

  The visibility of layer

CWM.Feature

An object representing a geometric feature. It has a representation of the feature's geometry, and a set of attributes.

Properties

geometry

Representation of the feature's geometry

type: geometry

coordinateSystem

Coordinate system used by the geometry

type: {CWM.CRS}

layerName

Name of layer this feature came from

type: {String}

layerId

Id of layer this feature came from

type: {String}

attributes

Attributes for this feature.

type: {Object}

Methods

getGeometryAsGeographic( )

Get a copy of geometry of the feature re-projected to geographic coordinates.

Returns: Geometry

getGeometryAsMap( )

Get a copy of geometry of the feature re-projected to map coordinates.

Returns: Geometry

getGeometryAsBCAlbers( )

Get a copy of geometry of the feature re-projected to BC Albers coordinates.

Returns: Geometry

Glossary

References