= !MapGuide RFC 109 # - RenderMapLegend API enhancement =

This page contains a change request (RFC) for the !MapGuide Open Source project.
More !MapGuide RFCs can be found on the [wiki:MapGuideRfcs RFCs] page.


== Status ==

||RFC Template Version||(1.0)||
||Submission Date||3rd September 2010||
||Last Modified||Jackie Ng 3rd September 2010||
||Author||Jackie Ng||
||RFC Status||retracted||
||Implementation Status||pending||
||Proposed Milestone||2.3||
||Assigned PSC guide(s)||(when determined)||
||'''Voting History'''||(vote date)||
||+1||||
||+0||||
||-0||||
||-1||||
||no vote|| ||

== Overview ==

This RFC proposes to add an enhanced {{{RenderMapLegend()}}} API to the rendering service. This enhanced API allows the option to omit empty layer groups from being rendered into the resulting image.

== Motivation ==

Under the current {{{RenderMapLegend()}}} API, all layer groups are rendered regardless of whether it has any visible layers or not. For maps with lots of layer groups, this can produce unnecessary clutter in the overall legend image.

== Proposed Solution ==

Introduce a new overload of {{{RenderMapLegend()}}} to the {{{MgRenderingService}}} class:

{{{
    /////////////////////////////////////////////////////////////////
    /// \brief
    /// Renders the legend for the specified MgMap to the requested size and format
    ///
    /// \param map
    /// Input
    /// map object containing current state of map.
    /// \param width
    /// Input
    /// width of legend image in pixels
    /// \param height
    /// Input
    /// height of legend image in pixels
    /// \param backgroundColor
    /// Input
    /// background color. Specifies the map legend background color
    /// \param format
    /// Input
    /// image format. Defines the format of the resulting image
    /// \param omitEmptyLayerGroups
    /// Input
    /// indicates whether layer groups with no visible layers should be drawn in the resulting image. If true, these groups will not be drawn. If false, these groups will be drawn
    ///
    /// \return
    /// A byte reader containing the rendered image
    ///
    virtual MgByteReader* RenderMapLegend(
        MgMap* map,
        INT32 width,
        INT32 height,
        MgColor* backgroundColor,
        CREFSTRING format,
        bool omitEmptyLayerGroups) = 0;

}}}

When {{{omitEmptyLayerGroups}}} is {{{false}}}, this will function like the original API.
When {{{omitEmptyLayerGroups}}} is {{{true}}}, this will skip rendering the names of any layer groups that have no visible layers at the current map scale.

Because this API has a HTTP counterpart, we will also introduce a new version of the GETMAPLEGENDIMAGE operation:

=== Parameters ===
|| '''Name''' || '''Value'''  || '''Required''' || '''Description''' ||
|| [#Operation1.0 OPERATION] || GETMAPLEGENDIMAGE || Yes || Operation to execute ||
|| [#Version1.0 VERSION] || 2.3.0 || Yes || Operation version ||
|| [#ClientAgent2.1 CLIENTAGENT] || text || Optional || Descriptive text for client ||
|| [#Session1.0 SESSION] || session identifier || Yes || !MapGuide session identifier containing map to display ||
|| [#MapName1.0 MAPNAME] || text || Yes || Name of the map to display.[[BR]]This corresponds to the !GetName() value for the resource identifier. ||
|| [#Format1.0 FORMAT] || JPG/PNG/PNG8 || Yes || Image format for rendered image ||
|| [#Width1.0 WIDTH] || integer || Yes || Width of legend image ||
|| [#Height1.0 HEIGHT] || integer || Yes || Height of legend image ||
|| [#OmitEmptyLayerGroups1.0 OMITEMPTYLAYERGROUPS] || boolean || Optional || Indicates whether to omit layer groups from the rendered image. Default is false. ||

== Implications ==

This is an API addition. The existing API will still be available and function as before.

== Test Plan ==

Add new test case for Rendering Service unit test:

 * Create a map of Sheboygan which is the same as the existing rendering test map, but includes a visible Layer Group containing a Parcels layer (visible at 12000)
 * Set view scale of this map to > 12000
 * Render the legend of this map with {{{omitEmptyLayerGroups = true}}} and {{{omitEmptyLayerGroups = false}}}
 * When {{{omitEmptyLayerGroups = false}}}, verify the resulting image is as though the original API was called (layer group is drawn to the resulting image)
 * When {{{omitEmptyLayerGroups = true}}}, verify the empty layer group is not drawn to the resulting image.



== Funding / Resources ==

Community