Client Views Map

The Map View is used to provide the user with a means of navigating geospatial data using a map.

ID

com.cohga.html.client.main.mapView

Sub-tags

Name

Type

Cardinality

Description

Name

Type

Cardinality

Description

label

String

0..1

Label to display in tab

location

String

1..1

Which region to add the view to

toolbar

toolbar

0..1

Actions and components to show at top of map

scalebar

toolbar

0..1

Actions and components to show at bottom of map

contextmenu

context menu

0..1

The definition for the right click menu

showloading

boolean

0..1

If a progress bar is included in the client setting this value to true should enable the progress bar when requesting map images from Weave.

scales

list of scale

0..1

A list of fixed scales to use for the map. If this value is set then the user will only be able to zoom to these fixed scales.

Only scales or resolutions should be set.

resolutions

list of resolution

0..1

A list of fixed resolutions to use for the map. If this value is set then the user will only be able to zoom to these fixed resolutions.

Only scales or resolutions should be set. If you have the choice choose resolutions because in the end the scales are converted to resolutions and because of the vagaries of JavaScript maths that conversion may not be as accurate as specifying the resolutions directly.

toc

table of contents

0..1

A reference to a toc model to represent the layers in the map.

Generally this value should be set and is really only optional to allow for a quick initial setup for testing purposes as a simple toc model will be generated based on the included  map engines if it is not set.

extents

list of map extents

1..1

Contains the initial, full and limit extents of the map

crs

String

0..1

Coordinate reference system to use for the map

control

map control

0..n

An additional map component to be placed on the map

mapEngine

map engine

1..n

A source for data to display on the map.

Alternatively rather than having one or more mapEngine tags you can have a single mapEngines tag that includes one or more mapEngine tags. This allows you to reference the same group of map engines in multiple clients using a client snippet.

highlight

highlight

0..1

The default style to use to highlight an individual entity (for example when selected in a data grid)

minScale

Number

0..1

The minimum scale to zoom to when the map is zoomed into the boundary of an object.

Useful for example when you may have small object to be zoomed to and you don't want the map scale to be set to 1:20 just to match the bounds of the object. By setting this value the map will zoom to the minScale value instead.

units

String

0..1

The map units that are to be used.

displayCrs

String

0..1

The CRS to use when displaying coordinates to the user, defaults to the same value as crs.

Scales

A list of scales can be added to the map which will prevent the user from zooming to arbitrary scales, that it they'll be limited to the values provided by this list.

The list is provided in the map view as a list of <scale> values within the <scales>

<scales> <scale>1000</scale> <scale>2000</scale> <scale>5000</scale> <scale>10000</scale> <scale>20000</scale> <scale>50000</scale> <scale>100000</scale> <scale>200000</scale> <scale>500000</scale> </scales>

or as a comma-separated list of values within the <scales>

<scales>1000,2000,5000,10000,20000,50000,100000,200000,500000</scales>

Table of Contents

A map view may be associated with a Table Of Contents model to provide the user with a more user-friendly listing of the layers available in the map.

If no table of contents is linked explicitly with the map then Weave will create a generic one providing the user with a simple list of the available layers.

<toc ref="toc.vectors"/>

Extents

The administrator can set the initial extent (used when the client starts and when the user uses the ‘home extent' button), full extent (used when the user uses the 'full extent' button) and limit extent (used to restrict the users movement).

Note that these values can also be set in the defaults section of the client config, but the values set in the map view take precedence.

Coordinate Reference System

You can specify a default coordinate reference system that you wish to be used for the map. Obviously, it should be one that is supported by the map engine, and preferably (for performance reasons) the default for the map engine.

The default if not set will be EPSG:4326.

Map Controls

Keyboard

com.cohga.client.mapctrl.keyboard

Adds keyboard control to the map panel (when the map has focus) allowing the user to pan and zoom the map using the keyboard

Mouse wheel

com.cohga.client.mapctrl.navigation

Adds mouse wheel control to the map panel (when the map has focus) allowing the user to zoom in and out of the map using the mouse wheel

Scale Line

com.cohga.client.mapctrl.scaleLine

Display the current scale on the map as a line

Display the current scale on the map as a line

Scale

com.cohga.client.mapctrl.scale

Display the current scale on the map as text

Scale Bar

weave.mapctrl.scalebar

Display the current scale or scale text, or both on the map

Mouse Position

com.cohga.client.mapctrl.mousePosition

Display the current cursor position on the map

additional properties

name

default

description

name

default

description

numDigits

5

Number of digits of precision to display

granularity

10

Maximum number of pixels the mouse can move in one go before the position isn't updated

prefix

""

Text to place before the coordinates

suffix

""

Text to place after the coordinates

separator

", "

Text to place between the coordinates

halo

false

Set 'true' to enable white halo around text

background

false

Set 'true' to enable white background around text

displayProjection

 

Set the the EPSG code for the coordinate display, e.g displayProjection=”EPSG:4283”. The default is same as the map

Pan/Zoom Bar

com.cohga.client.mapctrl.panZoomBar

Add a control to the map to allow the user to directly pan and zoom the map

Zoom In/Out

com.cohga.client.mapctrl.zoomInOutPanel

Add simple zoom in and out buttons. This is a simpler alternative to the above Pan/Zoom bar.

Overview Map

com.cohga.client.mapctrl.overviewMap

Display an overview map on the map

additional properties

name

default

description

name

default

description

minRatio

8

The ratio of the overview map resolution to the main map resolution at which to zoom farther out on the overview map

maxRatio

32

The ratio of the overview map resolution to the main map resolution at which to zoom farther in on the overview map

width

180

The default width in pixels of the overview map window

height

180

The default height in pixels of the overview map window

ratios

The ratio values are used to determine if the overview map extent should be changed.

From a coding perspective, we divide the current overview map resolution by the main map resolution and compare the values to the min and max resolutions to determine if the overview map should adjust its extent.

The appropriate values are dependent upon the scales set for the main map engine in the map view.
If you want to stop the zooming try setting minRatio to a large value and maxRatio to a small value.

Attribution

com.cohga.client.mapctrl.attribution

This control requires at least version 2.4.15.

Add the 'attribution' control then add an 'attribution' option to one or more client map engines.

Touch

com.cohga.client.mapctrl.touch

Enable touch navigation for the map panel.

Highlight

You can alter the style used to highlight an individual entity (only from 2.5.18 onward) by adding a highlight tag to the map view which has the following properties

Highlight

Name

Type

Description

Name

Type

Description

vector

vector

The styling for polygon and line based entities

marker

marker

The styling for point based entities

buffer

vector

The styling for buffers

autoClear

boolean

Should the highlights be automatically removed after a fixed delay or when the map is next refreshed, default true (from 2.5.23)

autoClearDelay

integer

Number of milliesconds to wait before automatically removing the highlights if autoClear is enabled  (from 2.5.23)

Vector

Name

Type

Description

Name

Type

Description

strokeColor

string

The colour for the outline (this is a CSS colour so may have to be forced to be a string if the config file reader determines that the value you have set is an integer)

strokeOpacity

float

The opacity for the outline, 0.0 - 1.0

strokeWidth

integer

The width of the outline

fillColor

string

The colour of the fill (this is a CSS colour so may have to be forced to be a string if the config file reader determines that the value you have set is an integer)

fillOpacity

float

The opacity of the fill, 0.0 - 1.0

Marker

Name

Type

Description

Name

Type

Description

icon

string

A URL pointing to the icon to use

width

int

The width of the icon

height

int

The height of the icon

offsetx

int

The x offset for the hotspot within the icon

offsety

int

The y offset for the hotspot within the icon



Map Engines

The map engine configures the actual source for the map image. Different types of map engines can be specified and and more than one map engine can be used.

Previously one of the map engines needed to be specified as the "base layer" by setting isBaseLayer to true for that particular map engine, this is no longer the case.

There is no specific user controllable base layer as part of the map view any more, it is maintained internally by Weave.

Multiple map engines

A single map engine can represent a single map layer, for example the aerial photography from 1968, or multiple map layers, for example all of the vector data related to water utilities. They can also be combined in the client configuration so that multiple images are overlayed to combine the data from more than one map engine.

Example of using three map engine to display raster, vector and a separate selection layer.

Note that to properly use the above configuration you may also need to update your toc model or add an image slider. Also, there are issues with transparency that will need to be considered (especially if you're unlucky enough to have to support Internet Explorer 6).

A toc model suitable for the above map engine configuration would set the map engine for the selection and raster layers to the same engines as configured above, rather than leaving them assigned to the original map engine.

For example assuming that we previously had a single map engine, mapengine.main, that contained raster and vector layers and was also used to draw the selection. In this case the toc model and client config could be something like:

But if we wanted to switch to the client configuration with the three map engines then our toc model would become something like:

Which makes the default map engine mapengine.vector, and changed the selection layers map engine to mapengine.selection and the aerial photography switched to mapengine.raster.

Then on the client side, the map panel will now contain three separate map layers, one for each map engine, which may improve performance because it cuts down on the number of layers that must be drawn on the server when the user toggles a single layers visibility.

For example, the selection layers are drawn a lot quicker in the above example because when the selection is changed only the selection layers need to be redrawn, not all of the other layers that are now in the mapengine.vector layer.

Transparency and multiple map engines

This may also make it clearer as to why transparency is now an issue, previously all of the map layers were drawn on the map server at once and the map server knew how to overlay the individual layers to ensure that lower layers show through the transparency of higher layers, but now that overlaying is performed on the client, so if the client doesn't support transparency properly (IE6 with 8-bit PNG images) or if the map engine doesn't provide full transparency support (ArcIMS) then the map panel on the client can look terrible. Sometimes that can be resolved by switching the image generation to 24 or 32-bit PNG or disabling anti-aliasing.

The following 2 images show the difference between using a single map engine, where the map server is retrieving the data, generating a single map image, and sending that to the client for display, and multiple map engines, where multiple images are sent to the client where they're overlayed.

In the above situation, since one map server is generating the map image it can produce the best image, making proper use of anti-aliasing and transparency, both full and partial. But because the image includes all map layers a change to any of the layers requires a whole new image to be drawn, which could mean that every map update is slow(er).

In this situation, multiple map servers are generating the images, which means that a change to one of the layers will result in the request for a map image that has fewer layers to draw, which should result in quicker response times. Of course, this is the case if you're toggling the visibility of a single layer, if you're panning or zooming the map then the same number of map layers will need to be drawn, but there could still be a performance advantage if the map servers are running on multiple physical servers, or a server has spare capacity, since they'll be able to generate the map images at the same time (3 map servers generating 3 images with 2 layers each will be quicker than 1 map server generating 1 image with 6 layers).

The downside to this arrangement is that the map server can't optimise the final image, and further, if the map server doesn't support transparency properly then any anti-aliasing around transparent areas can look terrible. Also, some map engines (ArcIMS I'm looking at you) don't support partial transparency, so if you, for example, specify a 50% transparent yellow fill for a polygon layer and there are no layers below that layer then rather than producing a final image that has the area filled with a transparent yellow fill it will instead produce an opaque fill that is 50% yellow and 50% whatever the background colour is set to. This means that when you overlay the image on top of another image rather than getting the bottom image showing through with a yellow tint, you instead don't see the bottom image at all and just see the yellow/background colour image.

Opacity and multiple map engines

This is assuming that the top image doesn't have its opacity altered to be less than 100%, which is a different issue altogether.
Since the map engine can have its opacity set to less than 100% in the client configuration it's possible to overlay a map image from a map server that doesn't support transparency at all and still have the underlying map image show through, for example setting the opacity to 0.5 (50%) would show a mix of 50% of the underlying image and 50% of the top image. The problem here is that the overall image appears washed out.

The images below show combining a raster image with a vector image that properly supports transparency (generated by GeoServer) with the vector images' opacity set to 1 (100%)

+ =

compared to combining a raster image with a vector that doesn't support transparency, but this time with the vector opacity set to 0.5 (50%)

+ =

Image Slider

An alternative for when you have multiple overlayed map engines on the client is that you can use a slider to transition between layers. The image transition slider allows the user to dynamically adjust the opacity of a single map engine.

Two options when using a single image slider are that if you have map engines that support transparency then you can transition the underlying image and still have the overlaying image visible, or if you don't have full transparency support then you can use it to transition the overlaying image and completely replace the underlying image.

The following 3 images show an example when the transition slider is attached to a raster image map engine that's overlayed on top of a vector map engine that does not support transparency (this could also be reversed with the vector map engine on top and the transition slider attached to it to accomplish exactly the same thing). The top image shows the slider at 10%, the second at 50% and the third at 100% (when the slider is at 0% you'll only see the vector image).

You can see that the vector image is gradually replaced entirely by the raster image (the area where the two images intersect is what the client would expect to see). And you can imagine if the map engines were reversed, with the raster below the vector and the slider attached to the vector, then the process would be the same, but with the vector layer replacing the raster rather than the raster replacing the vector (since the vector image is opaque). If the map engines were reversed but the slider was still attached to the raster map engine then there would be no visible effect from the slider since the opaque vector image on top would be occluding the raster image anyway, regardless of its opacity.

The following 3 images show an example with the transition slider again attached to the raster image, but in this case, the raster map engine is below the vector map engine, but in this case, the vector map engine supports transparency, so as the slider progresses from 10% to 50% to 100% the vector layer is still visible and the raster that shows through the transparent parts of the vector image (and again when the slider is at 0% you'll only see the vector image).

In this case, the raster image is gradually exposed through the vector image. If this configuration was kept (vector on top, raster below and image slider attached to raster image) but the vector images' map server didn't support transparency then moving the slider would have no visible effect, since the layer would be hiding the raster layer no matter what opacity the raster layer is set to.

The simplest example of this is to transition between a vector and a raster layer

Here we've kept the map engine configuration in the client the same as we have in the earlier example but we've added the image trans slider to allow the user to fade in and out the vector image. This example assumes that the vector image is opaque, if it were transparent you could attach the slider to the raster image instead and you'd always have the vector image visible.

You may have noticed that the Photography layer has been removed from the toc model, which means that the only way for the user to view the aerial photography is to use the slider since it doesn't make a lot of sense to allow the user to toggle the display of the layer via the toc panel and also use the slider to change its visibility.

If you had multiple raster layers that you wish to attach to the slider you could create something like the following toc model

Then depending upon the ordering of the map engines in the client configuration, you can attach the slider to the vector or raster map engines while also giving the user the ability to choose which raster layer to display.

Client-side map engines

All of the map engines configured in the client in the previous examples use the Weave server to generate the map images on behalf of the client, that is the Weave client is communicating with the Weave server to generate the map images and the Weave server is calling the map engine to create the images which are then sent back to the client.

An alternative to this is to have the client directly call the map engine to generate the images and bypass the Weave server altogether. Unfortunately at this stage, ArcIMS and ArcGIS SOAP are NOT directly supported in this configuration but can be used if accessed via WMS, which is supported by the client.

One reason for doing this would be to improve performance as it removes the extra layer of interaction with the Weave server, but it does mean that the client will require direct access to the map engine, whereas previously since it was the Weave server that was supplying the client with the images no access was required to the actual map engine by the client. So while performance may improve security will decrease and configuration complexity will increase.

Another limitation of this method is that as far as the user is concerned there is only a single layer coming from the map engine, even if the image generated by the map engine is composed of multiple feature layers. This means that if you add multiple map engines to the client configuration all pointing to client-side map engines then the toc model must be set up to include a single layer entry for each engine, and the user can only display or hide the whole layer, not individual layers within the map engine.

One issue that arises when using a map engine that only the client knows about is when it comes time to generate a report with a map embedded in it. Currently, this requires a duplicate map engine to be configured for the server to use and the client map engine configuration setup to tell Weave that it should use this map engine when it needs to generate a map on the server.

So for example let's look at what we'd need to set up the client with a very simple WMS map engine

All we've done here is set the map engine type to wms (the default is 'weave') and provided it with the URL that it needs to access the server. From there the client will directly interact with the WMNS server and not Weave when it needs to draw a map image.

From here if we want the user to be able to generate a report containing a map then we need to alter the client map engine configuration to tell it how the server can access this map engine.

To do this we need to first add a new map engine configuration pointing to the WMS server then alter the client map engine configuration to point to this new map engine

Here we've created a new server-side map engine that reflects the map engine used by the client and then set up the client to tell the server to use this map engine when it needs to generate a map image. We've also restricted the layers available through that map service to a single layer. The id used for the layers is taken from the WMS map service, in the example URL I used 0:2 is the id for a 2005 aerial photography layer.

Tiled map engines

The client-side map stuff is all well and good but the best reason for using a client-side map engine is that the client can then use a tiled map service. This is a map service where the map is generated in smaller tiles rather than as a single whole image, this provides large advantages in performance because once an individual tile is cached in the client browser they don't need to download or generate that tile again, which results in significant speed improvements for the client compared to generating a complete map image each time the user alter the map display.

The downside to tiled map engines is that they are fixed images and the user can not turn on and off the display of sub-layers within the map image. Whilst this generally isn't an issue for aerial photography-type map images or some other raster-based layers it can be a problem with vector layers.

For example, if you have a map engine composed of three vector layers and you want to give the user the option to turn on and off the display of each of the layers individually you would need to generate 8 tile caches. One with no layers, three for when only one layer is visible, three for when the combinations of two layers are visible and one for when all layers are visible. If you wanted to add a new layer to the mix then you'd need 16 tile caches, another layer would mean 32 tile caches, I'm sure you can see where this is going.

For this reason, if you have a large number of vector layers and you want to provide the user with the ability to selectively display or hide some of the layers then you'll probably still need to use a non-tiled weave layer. But if you have a limited number of layers, wish to create a very simple map environment or just want to add a single raster layer then tiles may be an option.

The easiest (and least useful) way to set up a tile cache is to add the singleTile flag to a WMS client-side map engine and set it to false. This will tell the client to send requests to the WMS server asking for small tiles rather than a single large image. But unless the WMS map engine is specifically configured to handle requests for tiles the performance of this setup will be severely compromised.

Alternatively, the client map engine can be configured to use a specialized tile caching mechanism instead of WMS. This is where the map engine supplying the tiles is specifically designed and configured to supply image tiles rather than imposing this on a map engine that wasn't specifically designed for it like WMS.

Weave currently supports (at least) two different tiling mechanisms TileCache and TMS. These two tiling mechanisms use specially crafted URLs to determine which tile to fetch and mainly differ in the formatting of the URL.

Setting up and tiled map engine using one of these mechanisms is similar to the WMS map engine but the type should be tilecache or TMS, and both still require the url parameter.

In the case of the TileCache version it also requires a layername parameter. This is used when constructing the url and allows the same tile cache to server multiple sets of tiles.
You'll also notice that we set singleTile to false (which isn't really necessary since a tile cache layer already knows that it's generated using tiles) and changed the format (the default is image/png for TileCache tiles). For a TMS tile cache the layername isn't required

Depending upon the actual tile cache implementation used to provide the tiles there may be two options available, one to generate the tiles as requested and the other to pre-generate the tiles. The first option has the advantage that only the tiles actually viewed by the users are ever generated, thereby reducing disk storage, but the performance will be slow the first time the tiles are generated. The second option has the advantage that it's lightning fast right from the start, but has the disadvantage that the whole tile cache needs to be generated before it's available even those tiles that will never be seen by any users and therefore use more disk storage (up front, over time the other option can also result in large disk usage as most of the map areas are viewed).

It can take many hours of processing to pre-generate a tile cache and use hundreds of gigabytes of disk space, depending upon how large an area is covered and how many levels of tiles are generated.

Currently Weave provides commands to build TileCache formatted tile cache for any map engine supported by Weave.

Map Engine Options

Below is a list of the options that are available for use when setting up a map engine

Option

Description

Option

Description

refreshInterval

Used to automatically refresh the map engine. Should be set to a positive integer that specifies the number of second between refreshes. If not set then no map refresh will occur.

transitionEffect

Determines how the browser displays the transitions between map images when a zoom in or out has been performed. Setting this option to force will ensure that the previous map image will be scaled and displayed while waiting for the new map image. If this option isn't set then a blank map image will be displayed while waiting for the new map image to arrive.

singleTile

Indicates that this map engine generates its display by requesting a single map image from the server, as opposed to requesting multiple smaller tiled map images. Default is true but this generally does not need to be set explicitly since it is determined from the map engine type.

selection

Indicates that this map engine will display selections and should be set to true for any map engine that will be displaying selections, default is false. Only one map engine should have this set to true.

alpha

Indicates to the browser if this map engine has an alpha channel, default is true, set it to false if you know the map engine will always be opaque, for example for an aerial photo layer covering the entire map area.

ratio

Indicates how big the map image (the buffer) should be compared to the size of the map panel itself, i.e. a value of 1.0 will generate requests for maps that are the same size as the map panel, a value of 2.0 will generate images that are twice the size of the map panel. This allows the user to pan the map without having to request a new map image from the server, at the cost of generating a bigger (and therefore slower) map image on the first request. The default is 1.5

isBaseLayer

This is obsolete and should not be set as an option as it is controlled internally by Weave, which will set it to false if it is set anyway.

minScale

The minimum scale at which the client will draw the map engine  (for supported map engines).

maxScale

The maximum scale at which the client will draw the map engine  (for supported map engines).