Documentation for the FTL liberies provided by ccm-cms

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

ccm-cms/web/themes/freemarker/ccm-cms/content-item.ftl

@@ -5,11 +5,24 @@
 "ui": "http://www.arsdigita.com/ui/1.0"}
 >
 
+<#--filedoc
+    This library provides functions and macros for processing the data of 
+    content items.
+-->
+
+<#--doc
+    Gets the current content item, or more exactly the model of the current
+    content item from the model. This function only works on cms pages and
+    not on navigation pages. For navigation pages use the functions
+    provided by ccm-navigation for extracting the index item.
+
+    @return The model of the current content item.
+-->
 <#function getContentItem>
     <#return model["/bebop:page/cms:contentPanel/cms:item"]>
 </#function>
 
-<#---
+<#--doc
     Includes the template for the type of the provided content item 
     for the provided view and style. The paramters view and style are
     optional. If not provided the default value "detail" is used for 
@@ -44,11 +57,13 @@
     
 </#macro>
 
-<#---
+<#--doc
     Retrieve the title of a content item.
 
     @param item The content item.
-#-->
+
+    @return The title of the content item.
+-->
 <#function getItemTitle item>
     <#if (item["./title"]?size > 0)>
         <#return item["./title"]>
@@ -59,7 +74,7 @@
     </#if>
 </#function>
 
-<#---
+<#--doc
     Get the title of the current page. This function tries several possible 
     sources for the title of the current page and uses to first source found.
 
@@ -70,6 +85,14 @@
     * If the title `AtoZ` is provided by Bebop the localized text 
       `layout.page.title.atoz` used.
     * If the title `Search` is provided by Bebop
+
+    @param useCategoryMenu The name of the category menu to use for retrieving 
+    the page title.
+
+    @param useRootIndexItemTitle Wether to use the title of the index item of 
+    the root category as page title.
+
+    @return The title of the current page.
 -->
 <#function getPageTitle useCategoryMenu='categoryMenu' useRootIndexItemTitle=false>
 
@@ -109,6 +132,16 @@
 
 </#function>
 
+<#--doc 
+    Retrieves the summary/lead text of an content item. The function
+    will check several possible sources.
+
+    @param item The item from which the the summary is read.
+
+    @return The value of the `summary` or `lead` property or the provided 
+    content item. If the content item does not have a such a property an 
+    empty string is returned.
+-->
 <#function getItemSummary item>
     <#if (item["./nav:attribute[./@name='lead']"]?size > 0)>
         <#return item["./nav:attribute[./@name='lead']"]>
@@ -123,6 +156,17 @@
     </#if>    
 </#function>
 
+<#--doc
+    Retrieve the value the `pageDescription` property of a conten item. 
+    If the provided content item does not have a `pageDescription` property
+    an empty string is returned.
+
+    @param item The content item from which the description is read.
+
+    @return The value of the `pageDescription` property of the provided content
+    item. If the provided content item does not have such a property an 
+    empty string is returned.
+-->
 <#function getPageDescription item>
     <#if (item["./pageDescription"]?size > 0)>
         <#return item["./pageDescription"]>
@@ -133,10 +177,27 @@
     </#if>
 </#function>
 
+<#--doc
+    Generated a link to a content using the OID of the content item.
+
+    @param oid The OID of the content.
+
+    @return A link to the content item identified by the provided OID.
+-->
 <#function generateContentItemLink oid>
     <#return "${contextPrefix}/redirect/?oid=${oid}">
 </#function>
 
+<#--doc
+    Generates the the edit link for the provided content item. The link
+    is generated using the `editLink` property which is only present in the 
+    model if the current user is permitted to edit the item.
+
+    @param item The item for which the edit link is generated.
+
+    @return An edit link for the item. If the provided item does not have an
+    `editLink` property an empty string is returned.
+-->
 <#function getEditLink item>
     <#if (item["./editLink"]?size > 0)>
         <#return "${contentTextPrefix}/ccm" + item["./editLink"]>

ccm-cms/web/themes/freemarker/ccm-cms/orgaunit.ftl

@@ -5,26 +5,74 @@
 "ui": "http://www.arsdigita.com/ui/1.0"}
 >
 
+<#--filedoc
+    Functions for retrieving several properties from a content item
+    of type OrganizationalUnit.
+-->
+
+<#--doc
+    Provides a list of the available tabs for the item.
+
+    @param item The organizatinal unit item.
+
+    @return A list of the available tabs.
+-->
 <#function getAvailableTabs item>
     <#return item["./orgaUnitTabs/availableTabs/availableTab"]>
 </#function>
 
+<#--doc
+    Retrieves the type of the item
+
+    @param The item to use.
+
+    @return The type the item.
+-->
 <#function getTypeNameKey item>
     <#return item["./type/label"]>
 </#function>
 
+<#--doc
+    The label of the provided tab.
+
+    @param The tab model (as provided by `getAvailableTabs`) from the which the 
+    label is read
+
+    @return The label of the tab.
+-->
 <#function getTabLabel tab>
     <#return tab["./@label"]>
 </#function>
 
+<#--doc
+    Checks if the provided tab is selected.
+
+    @param The tab model (from `getAvailableTabs`).
+
+    @return `true` If the tab is selected, `false` otherwise.
+-->
 <#function isTabSelected tab>
     <#return (tab["./@selected"] == "true")>
 </#function>
 
+<#--doc
+    Creates the link the provided tab.
+
+    @param The tab model (from `getAvailableTab`).
+
+    @return The link to the tab.
+-->
 <#function getTabLink tab>
     <#return "?selectedTab=" + tab["./@label"]>
 </#function>
 
+<#--doc
+    Gets the model of the selected tab from the item model.
+
+    @param The item (model) from the tab model is retrieved.
+
+    @return The model of the selected tab.
+-->
 <#function getSelectedTab item>
 
     <#--  <#assign selectedTab=item["./orgaUnitTabs/availableTabs/*[@selected='true']/@label"]>
@@ -34,6 +82,13 @@
     <#return item["./orgaUnitTabs/selectedTab/*"]>
 </#function>
 
+<#--doc
+    Gets the type the selected tab.
+
+    @param item The item (model)
+
+    @return The type of the selected tab.
+-->
 <#function getTypeOfSelectedTab item>
 
     <#assign nodeName = item["./orgaUnitTabs/selectedTab/*"]?node_name>
@@ -44,46 +99,126 @@
     </#if>
 </#function>
 
+<#--doc
+    Reads a property from tab model (retrieved by `getSelectedTab`).
+
+    @param tab The tab model.
+
+    @param name The name of the property.
+
+    @return The value of the property.
+-->
 <#function getPropertyFromTab tab name>
     <#return tab["./*[name()='${name}']"]>
 </#function>
 
+<#--doc
+    Gets the complete content of a tab model
+
+    @param tab The tab model.
+
+    @return The content of the tab.
+-->
 <#function getTabContent tab>
     <#return tab["."]>
 </#function>
 
+<#--doc
+    Gets the value of the `addendum`property from the overview tab.
+
+    @param The data model to use.
+
+    @return The value of the addendum property.
+-->
 <#function getAddendum data>
     <#return data["./addendum"].@@text>
 </#function>
 
+<#--doc
+    Get the members of an organizational unit from the data of the members tab.
+
+    @param data The data model of a members tab.
+
+    @return The data models for the members of the organizational unit.
+-->
 <#function getMembers data>
     <#return data["./members"]>
 </#function>
 
+<#--doc
+    Get the role of a member.
+
+    @param The model of a member.
+
+    @return The role of the member.
+-->
 <#function getMemberRole member>
     <#return member["./@role"]>
 </#function>
 
+<#--doc
+    Get the status of a member.
+
+    @param The model of a member.
+
+    @return The status of the member.
+-->
 <#function getMemberStatus member>
     <#return member["./@status"]>
 </#function>
 
+<#--doc
+    Get the contact entries of a member.
+
+    @param The model of a member.
+
+    @return The contact entries of the member.
+-->
 <#function getContactEntries member>
     <#return member["contacts/contact[@contactType = $contact-type]/contactentries"]>
 </#function>
 
+<#--doc
+    Checks if the organizational unit item has an associated contact item.
+
+    @param The data model of the overview tab.
+
+    @return `true` if the organizational unit has an associated contact item, 
+    `false` if not.
+-->
 <#function hasOrgaUnitContact data>
     <#return (data["./contacts/contact"]?size > 0)>
 </#function>
 
+<#--doc
+    Gets the associated contact item.
+
+    @param The data model of the overview tab.
+
+    @return The model of the assocatiated contact item.
+-->
 <#function getOrgaUnitContact data>
     <#return data["./contacts/contact[1]"]>
 </#function>
 
+<#--doc
+    Gets the person associated with the orga unit contact.
+
+    @param The data model of the overview tab.
+
+    @return The model of the associated person.
+-->
 <#function getOrgaUnitContactPerson data>
     <#return data["./contacts/contact[1]/person"]>
 </#function>
 
+<#--doc
+    Gets the contact entries of the associated contact item.
+
+    @param The data model of the overview tab.
+
+    @return The contact entries of the associated contact item.
+-->
 <#function getOrgaUnitContactEntries data>
     <#return data["./contacts/contact[1]/contactentries"]>
 </#function>

ccm-cms/web/themes/freemarker/ccm-cms/person.ftl

@@ -5,34 +5,108 @@
 "ui": "http://www.arsdigita.com/ui/1.0"}
 >
 
+<#--filedoc
+    Functions for accessing the properties of the content item of type person
+    or of subtype of person.
+-->
+
+<#--doc
+    Get the surname of the provided person item.
+
+    @param item The item from which the property is read.
+
+    @return The value of the `surname` property of the provided item.
+-->
 <#function getSurname item>
     <#return item["./surname"]>
 </#function>
 
+<#--doc
+    Get the given name of the provided person item.
+
+    @param item The item from which the property is read.
+
+    @return The value of the `givenname` property of the provided item.
+-->
 <#function getGivenName item>
     <#return item["./givenname"]>
 </#function>
 
+<#--doc
+    Get the name prefix of the provided person item.
+
+    @param item The item from which the property is read.
+
+    @return The value of the `titlepre` property of the provided item.
+-->
 <#function getTitlePre item>
     <#return item["./titlepre"]>
 </#function>
 
+<#--doc
+    Get the name suffix of the provided person item.
+
+    @param item The item from which the property is read.
+
+    @return The value of the `titlepost` property of the provided item.
+-->
 <#function getTitlePost item>
     <#return item["./titlepost"]>
 </#function>
 
+<#--doc
+    Get the link to the homepage from the contact data of the provided person 
+    item.
+
+    @param item The item from which the property is read.
+
+    @param contactType The type of the contact to use.
+
+    @param entry The contact entry providing the link to the homepage.
+
+    @return The link to the homepage.
+-->
 <#function getHomepageLink item contactType="commonContact" entry="homepage">
     <#return item["./contacts/contact[./@contactType='${contactType}']/contactentries[./keyId='${entry}']/value"]>
 </#function>
 
+<#--doc
+    Retrieve (the model) of the an contact item associated with the provided
+    person item.
+
+    @param item The person item.
+
+    @param contactType The type of the contact to retrieve.
+
+    @return The model of the associated contact item.
+-->
 <#function getContact item contactType="commonContact">
     <#return item["./contacts/contact[@contactType='${contactType}']"]>
 </#function>
 
+<#--doc
+    Retreives the contact entries of a contact associated with a person item.
+
+    @param item The person item.
+
+    @param contactType The type of the contact to retrieve.
+
+    @return The models of the contact entries of the associated contact item.
+-->
 <#function getContactEntries item contactType="commonContact">
     <#return item["./contacts/contact[@contactType='${contactType}']/contactentries"]>
 </#function>
 
+<#--doc
+    Retreives the address item associated with the contact associated with the 
+    provided person item.
+
+    @param item The person item.
+
+    @param contactType The type of the contact to retrieve.
+
+    @return The model of the assocaiated address item.
+-->
 <#function getAddress item contactType="commonContact">
     <#return item["./contacts/contact[@contactType='${contactType}']/address"]>
 </#function>