Documentation for ccm-cms-types-filestorageitem.ftl

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

ccm-cms-types-filestorageitem/web/themes/freemarker/ccm-cms-types-filestorageitem.ftl

@@ -5,10 +5,28 @@
 "ui": "http://www.arsdigita.com/ui/1.0"}
 >
 
+<#--filedoc
+    Functions for processing File Storage Items.
+-->
+
+<#--doc
+    Determines if a file storage item has a description.
+
+    @param item The model of the file storage item to use.
+
+    @return `true` if the file storage item has a description, `false` otherwise.
+-->
 <#function hasDescription item>
     <#return (item["./description"]?size > 0 || item["./nav:attribute[@name = 'description']"]?size > 0)>
 </#function>
 
+<#--doc
+    Gets the description of a file storage item.
+
+    @param item The model of the file storage item to use.
+
+    @return The description of the file storage item.
+-->
 <#function getDescription item>
     <#if (item["./description"]?size > 0)>
         <#return item["./description"]>
@@ -17,6 +35,13 @@
     </#if>
 </#function>
 
+<#--doc
+    The ID of the file of the file storage item.
+
+    @param item The model of the file storage item to use.
+
+    @return The ID of the file.
+-->
 <#function getFileId item>
     <#if (item["./file/id"]?size > 0)>
         <#return item["./file/id"]>
@@ -25,10 +50,24 @@
     </#if>
 </#function>
 
+<#--doc
+    Determines if the file name property is set.
+
+    @param item The model of the file storage item to use.
+
+    @return `true` if the file name property has a value, `false` if not.
+-->
 <#function hasFileName item>
     <#return (item["./file/name"]?size > 0 || item["./nav:attribute[@name = 'file.name']"]?size > 0)>
 </#function>
 
+<#--doc
+    Gets the name of the file of file storage item.
+
+    @param item The model of the file storage item to use.
+
+    @return The name of the file. 
+-->
 <#function getFileName item>
     <#if (item["./file/name"]?size > 0)>
         <#return item["./file/name"]>
@@ -37,6 +76,17 @@
     </#if>
 </#function>
 
+<#--doc
+    Constructs the link for downloading or viewing associated file.
+
+    @param item The model of the file storage item to use.
+
+    @param mode The mode for the link. Either `stream` or `download`. If the 
+    mode is set to stream and the client has an application for viewing the file
+    the file is shown. Otherwise the file is downloaded.
+
+    @return The link for downloading or viewing the file.
+-->
 <#function getFileLink item mode="download" useFileName=true>
     <#if (mode == "stream" && useFileName && hasFileName(item))>
         <#return "${dispatcherPrefix}/cms-service/stream/asset/${getFileName(item)}?asset_id=${getFileId(item)}">