MapGuide RFC 128 - Web Layout enhancements

This page contains a 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 Oct 2012
Last Modified	22 Oct 2012
Author	Jackie Ng
RFC Status	ready for review
Implementation Status
Proposed Milestone	2.5
Assigned PSC guide(s)	(when determined)
Voting History	(vote date)
+1
+0
-0
-1
no vote

Overview

This RFC proposes to update the WebLayout schema to expose settings for commonly customized properties/behaviour in the AJAX viewer.

Motivation

There are certain bits of the AJAX viewer that are commonly customized, but they can only be customized by modifying the viewer template files because such behaviour is not exposed in the WebLayout schema:

• Selection Color
• Map/Overlay Image Format
• Point Selection Pixel buffer

In addition, there is a lack of a well-defined javascript entry point that can be invoked after the viewer has been loaded. Currently hack-ish solutions like ​this have to be employed.

Such customizations can be (and should be) declaratively driven through a Web Layout using a schema that supports such elements.

Proposed Solution

Bump the WebLayout schema version to 2.5.0. Introduce the following optional XML schema elements to the WebLayoutType root element

    <xs:element name="SelectionColor" type="xs:string" minOccurs="0" />
    <xs:element name="PointSelectionBuffer" type="xs:integer" minOccurs="0" />
    <xs:element name="MapImageFormat" type="xs:string" minOccurs="0" />
    <xs:element name="SelectionImageFormat" type="xs:string" minOccurs="0" />
    <xs:element name="StartupScript" type="xs:string" minOccurs="0" />

• SelectionColor - Defines the HTML selection color (RGBA) to use (default: 0000FFFF)
• PointSelectionBuffer - Selections by mouse click are inflated by this value (in pixels) to form the querying geometry that is passed to QueryMapFeatures (default: 2)
• MapImageFormat - The image format for rendered maps (PNG/PNG8/JPG/GIF) (default: PNG)
• SelectionImageFormat - The image format for selection overlays (PNG/PNG8/GIF) (default: PNG). JPG is technically supported by RenderDynamicOverlay, but why would you want an opaque selection image on top of your map?
• StartupScript - The javascript code to execute once the viewer has been loaded (default: empty string)

Where such elements are not specified in the WebLayout document, the existing default values are used instead.

Similarly, the MgWebLayout class also needs to be updated to match as well so that the .net/PHP/Java viewers can access these new elements:

class MG_WEBAPP_API MgWebLayout : public MgGuardDisposable
{
PUBLISHED_API:
    ...

    ///////////////////////////////////////////////////////////////////////////
    /// <summary>
    /// Returns the selection color in HTML RGBA format
    /// </summary>
    /// <returns>
    /// The selection color in HTML RGBA format
    /// </returns>
    STRING GetSelectionColor();

    ///////////////////////////////////////////////////////////////////////////
    /// <summary>
    /// Returns the point selection buffer size in pixels
    /// </summary>
    /// <returns>
    /// The point selection buffer size in pixels
    /// </returns>
    INT32 GetPointSelectionBuffer();

    ///////////////////////////////////////////////////////////////////////////
    /// <summary>
    /// Returns the map image format
    /// </summary>
    /// <returns>
    /// The map image format
    /// </returns>
    STRING GetMapImageFormat();

    ///////////////////////////////////////////////////////////////////////////
    /// <summary>
    /// Returns the selection overlay image format
    /// </summary>
    /// <returns>
    /// The selection overlay image format
    /// </returns>
    STRING GetSelectionImageFormat();

    ///////////////////////////////////////////////////////////////////////////
    /// <summary>
    /// Returns the startup script code that is executed when the viewer has loaded
    /// </summary>
    /// <returns>
    /// The startup script code
    /// </returns>
    STRING GetStartupScript();

    ...
};

If startup script code is specified, it is executed in the context of the main viewer frame (ie. The script code is injected into mainframe.templ). It therefore has the same JavaScript scope as any existing invoke script command and follows the same rules in terms of syntax and API access. This code is encapsulated in a StartupFunc() function that is called by OnMapLoaded()

If there is no startup script code specified, this function will be empty and does nothing when called.

This RFC has already been implemented in ​this sandbox. Upon adoption of this RFC, the changes in this sandbox will be merged back into the trunk code stream.

Implications

All these new properties are optional, loading Web Layouts of previous schema versions will use the same default values.

The next version of Infrastructure Studio and Maestro need to be updated to allow editing these properties in the Web Layout editor. Such editors should ensure that:

• Selection colors are valid RGBA HTML colors
• Image formats can only be one of: PNG/PNG8/JPG/GIF

Due to #852. The alpha component of the selection color is currently not respected by the renderer. However if/when this gets fixed, the updated schema as proposed by this RFC will provide the necessary means to customize the alpha component of the selection color.

Test Plan

Verify new WebLayout properties through all 3 viewers (.net/PHP/Java). Verify old WebLayouts (2.4.0 and older) behave as before with these changes.

Funding / Resources

Community