MapGuide RFC 88 - AJAX Viewer support for custom initial view

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

Status

RFC Template Version	(1.0)
Submission Date	22 March 2010
Last Modified	Jackie Ng Timestamp
Author	Jackie Ng
RFC Status	draft
Implementation Status	pending
Proposed Milestone	2.2
Assigned PSC guide(s)	(when determined)
Voting History	(vote date)
+1
+0
-0
-1
no vote

Overview

This proposal is to extend the AJAX viewer to support a custom initial view, by simply passing additonal parameters to the Viewer URL.

Motivation

There have been many instances on the mapguide user mailing lists (examples: ​1, ​2, ​3) of the need to be able to load any given Web Layout with an initial view.

Although ​code samples exist to show how this can be done. This is something that could be supported by the AJAX viewer out of the box, with some simple modifications.

Proposed Solution

Modify the AJAX viewer (all 3 languages) to accept the following 4 optional request parameters:

• X: Specifies the X-coordinate of the custom view center.
• Y: Specifies the Y-coordinate of the custom view center.
• SCALE: Specifies the custom scale of the initial view.
• BBOX: Specifies the initial custom view as a set of bounding box coordinates (<xmin>,<ymin>,<xmax>,<ymax>)

If any of these parameters are specified, they will be used instead of the values specified in the Web Layout document.

The ultimate effect (and aim of the RFC) is that instead of having to specify the custom point/scale in the web layout document, it can be specified at runtime by passing these values to the AJAX viewer URL as request parameters.

Though the 4 parameters are optional, restrictions will be placed on how the viewer will accept these parameters:

• If the X parameter is specified but the Y parameter isn't, the X parameter is ignored. Same applies vice versa. The web layout X/Y values are used instead.
• The SCALE parameter can be specified without the X and Y parameters. The X and Y coordinates from the web layout will be used instead.
• X and Y parameters can be specified without the SCALE parameter. The scale from the web layout will be used instead.
• BBOX is mutually exclusive to the other parameters. If the BBOX is specified along with X, Y or SCALE, this constitutes an illegal parameter set and an exception will be thrown.

If invalid parameter values are encountered (eg. A non-numeric X, Y, SCALE or a BBOX without 4 point values), an exception is thrown and initialization is aborted. The exception thrown will be:

• .net: System.ArgumentException
• java: java.lang.IllegalArgumentException
• PHP: Custom InvalidArgumentException class

Implications

This is a client-side modification. No schema changes are required. No existing APIs are affected. No new APIs are added.

This affects the "Initial View and Scale" command. Invoking this command will use the overridden position/scale values if specified.

Test Plan

Verify all possible permutations of the 4 view parameters for all 3 viewers:

• Custom X and Y will start the map at the specified point at the default scale.
• Custom Scale will start the map at the default point at the specified scale.
• Custom X, Y and Scale will start the map at the specified point and scale.
• Custom BBOX will start the map at the specified extent, regardless of whether a custom X, Y or SCALE was passed in.
• An invalid BBOX parameter or any other illegal combinations of parameters will result in a throw exception.

Funding/Resources

Community

References

• ​A PHP code sample demonstrating the current technique of custom initial view