= !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 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 can provide more descriptive text like "Visit http://xxx.xx for more details of the building" which is much more user firendly.


2. Also, we may assign an FDO expression to URL element which designates a layer level URL setting for features, but at the the same time, we may as well would like to override it for a specific feature. For example: the URL xml element has been assigned Fdo expression value
{{{
Concat('http://www.map.com/fid=', FeatId)
}}}
where '!FeatId' property is the property to identify a unique feature of the feature class. The the URL of a feature should be like "http://www.map.com/fid=123" with FeatID=123. When a user wants to change the URL of this feature to something else, e.g a hard coded string "http://www.google.com", we have to specify where to store this 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 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 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.

Then 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>
}}}


== 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.