Monday, 26 August 2013

MapGuide 2.6 feature showcase: New WebLayout

Here's the first of many posts, covering some of the new features in MapGuide Open Source 2.6.

For this release, we introduce a new version of the Web Layout schema.

With the AJAX viewer, we've seen a common pattern with regards to customizations:
  • Wanting to change the default selection color
  • Wanting to change the default image format
  • Wanting to add an application-specific javascript entry point function to their AJAX viewer
All these things currently possible, except:
  1. They require actual modifications to the AJAX viewer files
  2. These modifications are global and not application-specific
So for 2.6, we've introduced a new WebLayout schema that lets you plug this specific information directly into the WebLayout, avoiding the need to modify any AJAX viewer files.

The new WebLayout schema supports the following new features:
  • The ability to control the selection color
  • The ability to control the map/selection image formats
  • The ability to control the tolerance of point selections
  • The ability to call JavaScript code upon initialization of the viewer
Editor support doesn't currently exist in Maestro for this new version, so to use a 2.6 schema WebLayout currently requires editing XML by hand.

To turn an existing WebLayout into a 2.6, one you have to make the following changes.

Firstly, make the document use WebLayout-2.6.0.xsd as the XML schema

To change the selection color, include a SelectionColor element, containing the RGBA color string

To change the selection tolerance of point selections, include a PointSelectionBuffer element, specifying the tolerance in pixels

To change the map/selection image formats, include a MapImageFormat and/or SelectionImageFormat element respectively, specifying the desired image formats. Note that if you pick an image format that doesn't support transparency (ie. JPG), selections will obscure the map beneath it. MapGuide or the AJAX viewer will not do any kind of validation to prevent this.

Finally, to specify JavaScript code to execute upon viewer initialization, specify your JavaScript code in a StartupScript element.

The code you specify in the StartupScript element has the same scope as any Invoke Script command, thus any function from the AJAX Viewer API is available for you to use. Previously, you would've needed to do something like this to achieve the same effect. The StartupScript element eliminates the need for such code as it will only be called after all initialization is complete, avoiding the need to monitor for DOM readiness before calling your code as per the linked example.

One thing to note is that due to how XML schema validation works, if you specify any of these optional elements, you must specify them in the following order after the Map element:
  • EnablePingServer
  • SelectionColor
  • PointSelectionBuffer
  • MapImageFormat
  • SelectionImageFormat
  • StartupScript
We'll eventually add editor support in Maestro so you no longer have to worry about such details.

With these changes, customizing the AJAX viewer should be that much simpler.

No comments: