= !MapGuide RFC 54 - Better Legend Control =

This page contains an 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||July 30, 2008||
||Last Modified||Kenneth Skovhede [[Timestamp]]||
||Author||Kenneth Skovhede||
||RFC Status||Draft||
||Implementation Status||pending||
||Proposed Milestone|| ||
||Assigned PSC guide(s)||Bruce Dechant?||
||'''Voting History'''||(vote date)||
||+1||    ||
||+0||    ||
||-0||    ||
||-1||    ||
 
== Overview ==

Change the schema of !MapDefinition and !LayerDefinition to contain properties that allow more control of the functionality and style in the legend.

== Motivation ==

This RFC is an extension to [wiki:MapGuideRfc50 RFC 50], and allows even more control over the legend. Some layer may not be turned off but might still be required to be visible in the legend. In the case where multiple layers comprise a single logical layer, the user should not be able to turn off the actual layers, but only the top level group.  This is not possible with the current schema.

At times, it may be desireable to provide a custom image for a layer or group. This will allow a user to supply custom images for raster layers, without having to replace the raster layer image for the entire server. Providing a custom image for a group will enable map designers to make a more visually pleasing solution to the mentioned case, where multiple layers comprise a single logical layer.

The original proposal was submitted by Jason Birch:
http://lists.osgeo.org/pipermail/mapguide-internals/2008-July/002576.html


== Proposed Solution ==

Two additional tags are going to be added to the schema of !MapDefinition. We will add an <!EnableVisibilityChange> tag and a <!AlternativeImageURL> for !MapLayerGroupCommonType. An additional tag named <!AlternativeImageURL> is going to be added to !LayerDefiniton. In !LayerDefinition there is no common base, so the tag will be added to <!PointTypeStyleType>, <!LineTypeStyleType>, <!AreaTypeStyleType> and <!CompositeTypeStyleType>.

The version of the !MapDefinition will change from 1.0 to 1.1, i.e. !MapDefinition-1.1.0.xsd.
The version of the !LayerDefinition will change from 1.3 to 1.4, i.e. !LayerDefiniton-1.4.0.xsd.

Details of the changes are described below.

!MapLayerGroupCommonType in !MapDefinition:
{{{
<xs:complexType name="MapLayerGroupCommonType">
  <xs:annotation>
    <xs:documentation>MapLayerGroupCommonType is a common subclass of MapLayerGroupCommonType and BaseMapLayerGroupCommonType</xs:documentation>
  </xs:annotation>
  <xs:sequence>
    <xs:element name="Name" type="xs:string">
      <xs:annotation>
        <xs:documentation>The name of this LayerGroup</xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="Visible" type="xs:boolean">
      <xs:annotation>
        <xs:documentation>Whether this group's visiblity should be visible or not when it first comes into range</xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="ShowInLegend" type="xs:boolean">
      <xs:annotation>
        <xs:documentation>Whether or not the LayerGroup should be shown in the legend</xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="ExpandInLegend" type="xs:boolean">
      <xs:annotation>
        <xs:documentation>Whether or not the LayerGroup should be initially expanded in the legend</xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="LegendLabel" type="xs:string">
      <xs:annotation>
        <xs:documentation>Label to be shown for the LayerGroup in the legend</xs:documentation>
      </xs:annotation>
    </xs:element>
	
    <xs:element name="EnableVisibilityChange" type="xs:boolean" minOccurs="0" default="true" >
      <xs:annotation>
        <xs:documentation>Whether or not the user can toggle the visibility of the LayerGroup in the legend</xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="AlternativeImageURL" type="xs:string" minOccurs="0" >
      <xs:annotation>
        <xs:documentation>An URL to an alternate image to display in the legend</xs:documentation>
      </xs:annotation>
    </xs:element>
	
  </xs:sequence>
</xs:complexType>
}}}

!LineTypeStyle in !LayerDefinition:
{{{
<xs:complexType name="LineTypeStyleType">
    <xs:annotation>
      <xs:documentation>Style specification of a line geometry type.</xs:documentation>
    </xs:annotation>
    <xs:sequence>
      <xs:element name="LineRule" type="LineRuleType" maxOccurs="unbounded">
        <xs:annotation>
          <xs:documentation>Rules to define a theme.</xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name="ShowInLegend" type="xs:boolean" minOccurs="0" default="true" />
      <xs:element name="AlternativeImageURL" type="xs:string" minOccurs="0" />
      <xs:element name="ExtendedData1" type="ExtendedDataType" minOccurs="0" />
    </xs:sequence>
</xs:complexType>
}}}

!PointTypeStyle in !LayerDefinition:
{{{
<xs:complexType name="PointTypeStyleType">
    <xs:annotation>
      <xs:documentation>Style specification of a point geometry type.</xs:documentation>
    </xs:annotation>
    <xs:sequence>
      <xs:element name="DisplayAsText" type="xs:boolean">
        <xs:annotation>
          <xs:documentation>Create a text layer.</xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name="AllowOverpost" type="xs:boolean">
        <xs:annotation>
          <xs:documentation>Allows labels from any map layer (including the current layer) to obscure features on the current layer.</xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name="PointRule" type="PointRuleType" maxOccurs="unbounded">
        <xs:annotation>
          <xs:documentation>One or more PointRules defining the PointTypeStyle.</xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name="ShowInLegend" type="xs:boolean" minOccurs="0" default="true" />
      <xs:element name="AlternativeImageURL" type="xs:string" minOccurs="0" />
      <xs:element name="ExtendedData1" type="ExtendedDataType" minOccurs="0" />
    </xs:sequence>
</xs:complexType>
}}}

!AreaTypeStyle in !LayerDefinition:
{{{
<xs:complexType name="AreaTypeStyleType">
    <xs:annotation>
      <xs:documentation>Style specification of a polygon geometry type.</xs:documentation>
    </xs:annotation>
    <xs:sequence>
      <xs:element name="AreaRule" type="AreaRuleType" maxOccurs="unbounded">
        <xs:annotation>
          <xs:documentation>Rules to define a theme.</xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name="ShowInLegend" type="xs:boolean" minOccurs="0" default="true"/>
      <xs:element name="AlternativeImageURL" type="xs:string" minOccurs="0" />
      <xs:element name="ExtendedData1" type="ExtendedDataType" minOccurs="0" />
    </xs:sequence>
</xs:complexType>
}}}

!CompositeTypeStyle in !LayerDefinition:
{{{
<xs:complexType name="CompositeTypeStyle">
  <xs:annotation>
    <xs:documentation>A style specification consisting of composite rules.</xs:documentation>
  </xs:annotation>
  <xs:sequence>
    <xs:element name="CompositeRule" type="CompositeRule" maxOccurs="unbounded">
      <xs:annotation>
        <xs:documentation>One or more CompositeRules defining the CompositeTypeStyle.</xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="ShowInLegend" type="xs:boolean" minOccurs="0" default="true"/>
    <xs:element name="AlternativeImageURL" type="xs:string" minOccurs="0" />
    <xs:element name="ExtendedData1" type="ExtendedDataType" minOccurs="0"/>
  </xs:sequence>
</xs:complexType>
}}}

== Implications ==

The existing schema documentation will be updated.
Since these are all extensions to the schema, no existing functionality will be affected.
Before these additions have any effect, they must be handled in the viewers, both the !WebLayout based, as well as the Fusion based viewer has to be updated. The !GetMapLegendImage function will also have to be updated to deal with these new properties as well.

== Test Plan ==

No new unit tests will be created for this. However, the existing unit tests will be run to ensure that they still pass. 

== Funding/Resources ==

Autodesk