= !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 22, 2011||
||Author||Sam Wang||
||RFC Status||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 for more detailed information of the building directly, we could provide more descriptive hint such like 'Visit URL www.xxx.com for more details of Empore State Building' which is more user firendly. URL Description 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('http://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 'http://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 the override of URL content for a specific feature which can be a string FDO expression.</xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name="DescriptionOverride" type="xs:string" minOccurs="0">
        <xs:annotation>
          <xs:documentation>Specify the override of URL description for a specific feature which can be a string FDO expression..</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="UrlData" 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:[[BR]]

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.

So when new shcema containing these information is applied(as proposed above), a sample of the new XML should look like:

{{{
<UrlData>
 <Content>Concat('http://map.google.com/location=', ADDRESS)</Content>
 <Description>Concat('Feature at location:', ADDRESS)</Description>
 <ContentOverride>URL</ContentOverride>
 <DescriptionOverride>DESCRIPTION</DescriptionOverride>
</UrlData>
}}}


Normally, if a feature does not individually override its layer's setting. Then the URL and description of this feature of should be the evaluated value of the FDO expression specified. That is to say, if the ADDRESS property value of this feature is "627 5th Avenue", then the URL of this feature is "http://map.google.com/location=627 5th Avenue" and respectively description of this feature is "'Feature at location: 627 5th Avenue". Otherwise if user want to use a different URL, he can override this value and store it in URL property and if he wants to use a different URL description, he can store it in DESCRIPTION property. Both overriden setttings(specified in "ContentOverride" and "DescriptionOverride" elements) take precedence over layer setting(specified in "Content" and "Description" elements).
  

== Implications ==
A new version 2.4 of the layer definition schema was recently added to support RFC 113, and the schema changes proposed in this RFC will be added to this version.  Backward compatibility with older versions of the schema will be maintained, and schema documentation will also 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.