Documentation for ccm-cms-assets-relatedlink.ftl

git-svn-id: https://svn.libreccm.org/ccm/trunk@6291 8810af33-2d31-482b-a856-94f89814c4df

ccm-cms-assets-relatedlink/web/themes/freemarker/ccm-cms-assets-relatedlink.ftl

@@ -5,6 +5,25 @@
 "ui": "http://www.arsdigita.com/ui/1.0"}
 >
 
+<#--filedoc
+    Functions for processing related links.
+-->
+
+<#--doc
+    Generates a sorted sequence of hashes (see Freemarker documentation) 
+    from the related links of a content item.
+
+    @param item The model of the content item to use.
+
+    @param linkListName: The name of the link list to use.
+
+    @return A sorted sequence of hashes. Each hash provides the following keys:
+    * `linkType`: The type of the link. Either `externalLink`, `internalLink` or `caption`.
+    * `title`: The title of the link.
+    * `description`: The description of the link.
+    * `linkOrder`: The sort of the link.
+    * `targetUri`: The URL of the link.
+-->
 <#function getRelatedLinks item linkListName="NONE">
 
     <#return item["./links[./linkListName='${linkListName}']"]?map(
@@ -19,6 +38,13 @@
     <#--  <#return item["./links[./linkListName='${linkListName}']"]?sort_by("linkOrder")>  -->
 </#function>
 
+<#--doc
+    *Internal* function for determing the type a related link.
+
+    @param link The link
+
+    @return The type of the link. Either `externalLink`, `internalLink` or `caption`.
+-->
 <#function _getLinkType link>
     <#if (link["./targetType"].@@text == "externalLink" && link["./targetURI"] == "caption")>
         <#return "caption">
@@ -41,6 +67,13 @@
     <#return link["./linkOrder"].@@text>
 </#function>  -->
 
+<#--doc
+    *Internal* function for getting parameters for the link.
+
+    @param link The link
+
+    @return Parameters for an internal link.
+-->
 <#function _getInternalLinkParameters link>
     <#if (_getLinkType(link) == "caption")>
         <#return "">
@@ -56,6 +89,13 @@
     </#if>
 </#function>
 
+<#--doc
+    *Internal* function for constructing the target URI of a related link.
+
+    @param link The link model to use.
+
+    @return The URL for the target of the link.
+-->
 <#function _getTargetUri link>
     <#if (_getLinkType(link) == "caption")>
         <#return "">