MapGuide RFC 132 - Fusion OpenLayers upgrade

This page contains a change request (RFC) for the MapGuide Open Source project. More MapGuide RFCs can be found on the RFCs page.


RFC Template Version(1.0)
Submission Date19 Mar 2013
Last Modified7 Nov 2013
AuthorJackie Ng
RFC Statusadopted
Implementation Statuscompleted
Proposed Milestone2.6
Assigned PSC guide(s)(when determined)
Voting History(vote date)
no voteZac,Tom,Bob,Bruce


Update 7 Nov 2013: This RFC was implemented before the release of OpenLayers 2.13, which included some important fixes for IE10. Fusion trunk has been updated to now use OpenLayers 2.13.1. The same motivation and benefits of this RFC still apply

This RFC proposes to upgrade the OpenLayers in Fusion to the latest stable release (2.12)


Fusion is using a somewhat old version of OpenLayers.

Upgrading to the latest stable release of OpenLayers (2.12) offers a bunch of useful new features that Fusion can take advantage of:

  • Touch input support, allowing for our Fusion templates to be somewhat serviceable on an Android/iOS phone or tablet device, as swipe and pinch zoom functionality can be leveraged automatically for map panning, zooming and navigation.
  • Tile Queues, for improved tile loading.
  • New CacheRead? and CacheWrite? controls for limited client-side caching of tile images.
  • Client Zoom, allowing for map tile images to be stretched client-side to fit the current view of the map. This one feature alone presents some new scenarios that previously were not possible, such as the ability to have a Map Definition with dynamic layers combined with an OpenStreetMap? background that can be zoomed to at any arbitrary level (as OSM tiles will be stretched client-side by OpenLayers).

The second problem is that we are using a custom build of OpenLayers, whose version is currently unknown (The author suspects 2.10, but the version string in OpenLayers.js has been overwritten by a subversion revision), and whose audit trail of custom modifications is very difficult to follow.

If a user decides to customize their OpenLayers.js (to add features we excluded from our fusion.cfg build profile), we need to ensure any Fusion-specific customizations are rolled into their custom build as well. As it currently stands, it is difficult to do this and verify this.

Proposed Solution

Upgrade Fusion's internal copy of OpenLayers to 2.12

To improve our audit trail of customizations to OpenLayers and to make future OpenLayers upgrades or custom OpenLayers builds easier, Fusion-specific modifications to OpenLayers are kept under lib/OpenLayers/ext. Whenever a new built OpenLayers.js needs to be checked in, the files and folders under lib/OpenLayers/ext can be copied into a standard OpenLayers distribution (overwriting any existing files) to be built with our fusion.cfg build configuration file.

Currently, we are keeping OpenLayers.Util and our implementation of OpenLayers.Layer.MapGuide under this directory. These are the only 2 parts of standard OpenLayers with known Fusion-specific modifications.

The client-zoom feature is controlled by the existing FractionalZoom? extension property of the Map widget. This value already defaults to true, so it will automatically be enabled for scenarios that allow for it.

Under client-zoom the following behaviour occurs:

  • MapGuide dynamic layers + OSM (fractionalZoom = true): Map is fully dynamic and OSM tiles are stretched accordingly
  • MapGuide dynamic layers + OSM (fractionalZoom = false): Scales "snap" to OSM scales and are stretched accordingly when going below the smallest supported OSM scale.

The client-zoom feature has no effect if the map has no tiled layers.

The client-zoom technique does not work in conjunction with Google/Bing? layers and only if the available commercial layers are exclusively OpenStreetMap?. See implications

This implementation work has already been completed on the ol212 sandbox branch of Fusion. Upon adoption of this RFC, the changes will be merged back into Fusion trunk that's automatically linked by our MapGuide Oem tree.


The following components in OpenLayers 2.12 are deprecated and we should look at replacing such instances in our core/widget code before another future OpenLayers upgrade:

OpenLayers 2.12 along with the current JxLib? presents an issue on Firefox 18+, this is due to the version of MooTools? used by JxLib? causing "too much recursion" errors under Firefox 18+. As part of this RFC, the MooTools? used by JxLib? will be upgraded to 1.2.6

For this RFC, the OpenLayers client-zoom feature is only available for a Map Definition with all dynamic layers in conjunction with an OpenStreetMap? background, which can be activated by setting the FractionalZoom? map widget extension property to true (already the default value, no there no actual need to set such value)

The OpenLayers client-zoom feature cannot be used with Google and Bing layers as:

a) These layers aren't Grid-based. Client zoom only works with layers inheriting from OpenLayers.Layer.Grid

b) Client-side stretching of such tiles constitutes content modification of their tiles and violates the terms of use.

The OpenLayers client-zoom feature has no effect on a MapGuide Map Definition with a combination of tiled and dynamic layers. It will behave like previous versions of Fusion. Likewise, when said map is mixed with a commercial layer, MapGuide tiled layers will only line up with commercial layers if they use the same finite scale list. Ability to client-zoom scale MapGuide tiled layers to match the current dynamic map view is possible, but it is not implemented for this RFC.

If we're viewing a map with Google + Bing + OSM and set the FractionalZoom? property of the Map widget to true, switching to a Google or Bing layer will disable client-zoom while that layer is active.

Such limitations should be ideally communicated to the user in the tools/editors department.

Test Plan

Test and verify our changes on our current suite of supported browsers

Funding / Resources


Last modified 4 years ago Last modified on Nov 7, 2013 1:59:34 AM