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.


RFC Template Version(1.0)
Submission Date22 March 2010
Last ModifiedJackie Ng Timestamp
AuthorJackie Ng
RFC Statusretracted
Implementation Statuspending
Proposed Milestone2.2
Assigned PSC guide(s)(when determined)
Voting History(vote date)
no vote


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


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:


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.




Last modified 12 years ago Last modified on Apr 8, 2010, 4:14:23 PM
Note: See TracWiki for help on using the wiki.