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 |
---|---|---|---|
label | String | 0..1 | Label to display in tab |
location | String | 1..1 | Which region to add the view to |
toolbar | 0..1 | Actions and components to show at top of map | |
scalebar | 0..1 | Actions and components to show at bottom of map | |
contextmenu | 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 |
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 |
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 |
---|---|---|
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 |
---|---|---|
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 |
---|---|---|
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 |
---|---|---|
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 |
---|---|---|
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 |
---|---|
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 |
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 |
selection | Indicates that this map engine will display selections and should be set to |
alpha | Indicates to the browser if this map engine has an alpha channel, default is |
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 |
isBaseLayer | This is obsolete and should not be set as an option as it is controlled internally by Weave, which will set it to |
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). |