= !MapGuide RFC 119 - Enhance URL information in vector layer definition =

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||July 19, 2011||
||Last Modified||Sam Wang July 19, 2011||
||Author||Sam Wang||
||RFC Status||Not ready for review||
||Implementation Status||pending||
||Proposed Milestone||2.4||
||Assigned PSC guide(s)||Bruce Dechant||
||'''Voting History'''||||
||+1|| ||
||+0|| ||
||-0|| ||
||-1|| ||
||no vote|| ||

== Overview ==

This RFC proposes a solution to enhance representation of URL information for features in vector layer definition.

== Motivation ==

Current layer definition schema(2.3.0) already defines an element "URL" of type string in "!VectorLayerDefinition" complex type to store URL information. However, this is quite simple and may far from enough for applications. We can enhance this in the following two aspects:

1. Description of the URL. The URL is just a universal resource locator in some certain formats, but we may want to display to user more readable text. For example, when user finds a building whose name is 'Empore State Building' in a map, instead of showing user a URL directly so that he can jump to that link for more detailed information of the building, we could provide more descriptive hint such like 'Visit URL http://xxx.xx for more details of Empore State Building' which is much more user firendly. This URL Description element can also be a string FDO expression. 

2. URL override setting. The URL defined in vector layer definition 2.3.0 is a string FDO exprerssion. This can be very flexible but also raises a problem. Consider a scenario that the URL element has been assigned the following FDO expression
{{{
Concat('map.google.com/fid=', FeatId)
}}}
where '!FeatId' property is the property to identify a unique feature of the feature class. So the URL of a feature in this layer should be in the form 'map.google.com/fid=[!FeatId]' where [!FeatId] part will be replaced with the actual '!FeatId' property value for each feature. However if user wants to change the URL of a specific feature(and only this one) which turns out to be 'map.bing.com/fid=[!FeatId]' for some reason. It is obvious that we can not change URL element value that will affect all other features. So what we can do is to specify a property of the feature class that the layer is based on where we can store this overriden value.
  
== Proposed Solution ==
We need to change the vector layer definition a little bit. First we add a XML complex type named "URLDataType" to represent URL information.

{{{
 <xs:complexType name="URLDataType">
    <xs:annotation>
      <xs:documentation>URL information for features.</xs:documentation>
    </xs:annotation>
    <xs:sequence>
      <xs:element name="Content" type="xs:string" minOccurs="0">
        <xs:annotation>
          <xs:documentation>The real address of the URL. This can be a string FDO expression.</xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name="Description" type="xs:string" minOccurs="0">
        <xs:annotation>
          <xs:documentation>The description of the URL. This can be a string FDO expression.</xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name="ContentOverride" type="xs:string" minOccurs="0">
        <xs:annotation>
          <xs:documentation>Specify the property name of the feature class that the layer is based on where the override of URL content for a specific feature can be stored.</xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name="DescriptionOverride" type="xs:string" minOccurs="0">
        <xs:annotation>
          <xs:documentation>Specify the property name of the feature class that the layer is based on where the override of URL description for a specific feature can be stored.</xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name="ExtendedData1" type="ExtendedDataType" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>
}}}
The meaning of child elements in this complex type are well explained by their annotations.

And change the original "URL" element in "!VectorLayerDefinition" from simple type "xs:string" to complex type "URLDataType".
{{{
 <xs:element name="Url" type="URLDataType" minOccurs="0">
   <xs:annotation>
     <xs:documentation>The optional URL information associated with each feature.</xs:documentation>
   </xs:annotation>
 </xs:element>
}}}


Now the normal workflow for evaluating the URL content of a feature is:

The application first check '!ContentOverride' child element of the URL element. If its value is not empty and happens to be one of the property names of the feature class the layer is based on, then fetch the actual value(which may be a string FDO expression) from that property of the feature and evaluate the actual value as a FDO expression. Otherwise, ignore it and check 'Content' child and evaluate its value as a FDO expression.

The same rule applies to URL description.

== Implications ==
A new version 2.4 of the layer definition will be added to reflect this change and backward compability with older version of schema should be maintianed.
Also existing schema documentation will be updated.

== Test Plan ==

The existing unit tests (!MdfModel unit test) will be updated adding test of the new complex type added and the new version handling. The !MdfModel unit test verifies that the versioning / roundtripping behavior is working correctly.

== Funding / Resources ==

Funding and developer resources to be provided by Autodesk.