Documentation for the Freemarker functions provided by ccm-cms

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

ccm-cms/doc/ccm-cms-freemarker.md

@@ -0,0 +1,171 @@
+# Freemarker functions for ccm-cms
+
+## Functions for all content types
+
+Import path
+: `/ccm-cms/content-item.ftl`
+
+This functions and macros work for all content item types. Unless stated 
+otherwise all functions support the detail view as well as the list view
+generated by the `ObjectList` components of the ccm-navigation module.
+
+### `Node getContentItem()`
+
+Retrieves the content item of the current page. This works only on pages
+generated by the ContentSection application. To get the index item of
+a navigation page use the functions provided by the ccm-navigation module.
+
+This function is primarly used to as parameter for other functions dealing
+with content items. 
+
+### `@contentItem item: Node view: String style: String`
+
+This macro generates the detail view of a content item. Using the type of the
+provided content items, the provided type and the provided type this macro
+internally tries to find a view definition in for the provided parameters in
+the theme manifest. The template defined in this definition is used to 
+generate the HTML representation of the item. 
+
+The parameters `view` and `style` are optional. The `view` parameter defaults
+to `detail`, the default value for the `style` parameter is an empty string.
+
+### `String getItemTitle(item: Node)`
+
+This function retrieves the title of the provided content items.
+
+### `String getPageTitle(useCategoryMenu: String, useRootIndexItemTitle: boolean)`
+
+Retrieves the title of the current page. The title retrieved depends on the 
+provided parameters. Both parameters are optional. `useCategoryMenu`is used
+to select the category menu which is used to retrieve the page title. The default value is `categoryMenu`. The `useRootIndexItemTitle` defaults to `false` and is used to determine if the title of the category or the title of the index item is used as page title for the index page of an category.
+
+### `String getItemSummary(item: Node)`
+
+Retrieves the summary/lead text of the provided content item if the item has a property. The following property names are tried: `lead`, `summary`. If none is
+found an empty string is returned.
+
+### `String getPageDescription(item: Node)`
+
+Retrieves the value of the `pageDescription` property of the provided content item if the item has such a property. If not an empty string is returned. 
+
+### `String generateContentItemLink(oid: String)`
+
+Generates a link to the content item with the provided OID.
+
+### `String getEditLink(item: Node)`
+
+This function generates a link for editing the provided content item is the
+link is available. If the link is not available, for example if the current user is not permitted to edit the item, an empty string is returned.
+
+## Functions of types derivated from OrganizationalUnit
+
+Import Path
+: `/ccm-cms/orgaunit.ftl`
+
+### `Sequence getAvailableTabs(item: Node)`
+
+Returns a sequence of the information tabs available for the provided
+organizational unit item. For processing the return values of this functions
+the other functions provided by this file should be used.
+
+### `String getTypeNameKey(item: Node)`
+
+Retrieves the type of the provided orga unit item.
+
+### `String getTabLabel(tab: Node)`
+
+Retrieves the label of the provided tab.
+
+### `boolean isTabSelected(tab: Node)`
+
+Checks if the provided tab is the currently selected tab.
+
+### `String getTabLink(tab: Node)`
+
+Retrieves the link for the provided tab.
+
+### `Node getSelectedTab(item: Node)`
+
+Retrieves the data of the selected tab.
+
+### `String getTypeOfSelectedTab(item: Node)`
+
+Returns the type of the selected tab.
+
+### `Node getPropertyFromTab(tab: Node)`
+
+Returns a property from the provided tab.
+
+### `Mixed getTabContent(tab: Node)`
+
+Returns the content of the provided tab.
+
+### `String getAddedum(data: Node)`
+
+Retrieves the value of the addendum property from the provided tab data (as returned by `getTabContent`) if the data contains such a property.
+
+### Sequence<Node> getMembers(data: Node)`
+
+Retrieves the members of the orga unit from the provided tab data (as returned by `getTabContent`) if the data contains such a property.
+
+### `String getMemberRole(member: Node)`
+
+Retrieves the role of the provided member.
+
+### `String getMemberStatus(member: Node)`
+
+Retrieves the status of the provided member.
+
+### `Sequence<Node> getContactEntries(member: Node)`
+
+Retrieves the contact entries of the provided member. For processing the members  the functions provided by `person.ftl` can be used.
+
+### `boolean hasOrgaUnitContact(data: Node)`
+
+Returns `true` if the provided data contains a contact item.
+
+### `Node getOrgaUnitContact(data: Node)`
+
+Retrieves the contact item for the orga unit from the provided data.
+
+### `Node getOrgaUnitContactPerson(data: Node)`
+
+Retrieves the person associated with the provided contact.
+
+### `Node getOrgaUnitContactEntries(data: Node)`
+
+Retrieves the contact entries of the provided contact item. For further processing the functions provided by the `ccm-cms-types-contact` module 
+should be used.
+
+## Functions for person items 
+
+Import path
+: `/ccm-cms/person.ftl`
+
+This functions can be used to process content items derivated from 
+the `GenericPerson` type.
+
+### `String getSurname(item: Node)`
+
+Gets the surname from the provided person item.
+
+### `String getGivenName(item: Node)`
+
+Gets the given name from the provided person item.
+
+### `String getTitlePre(item: Node)`
+
+Gets the value of the `titlePre` property of the provided person item.
+
+### `String getTitlePost(item: Node)`
+
+Gets the value of the `titlePost` property of the provided person item.
+
+### `String getHomepageLink(item: Node, contactType: string="commonContact", entry: String="homepage")`
+
+Retrieves the link to the homepage of the provided person item if the item has an contact entry for a homepage. The optional parameters `contactType` and `entry` can be used to select the contact and the entry from which the value is read. The default value for `contactType` is `commonContact`. For `entry` the default value is `homepage`.
+
+### `String getAddress(item: Node, contactType: String="commonContact")`
+
+Retrieves the addres item associated with contact of the provided person. 
+The contact to use can be selected using the optional parameters `contactType`. The default value is `commonContact`.

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

@@ -91,6 +91,8 @@
         <#return item["./lead"]>
     <#elseif (item["./summary"]?size > 0)>
         <#return item["./summary"]>
+    <#else>
+        <#return "">
     </#if>    
 </#function>
 
@@ -99,6 +101,8 @@
         <#return item["./pageDescription"]>
     <#elseif (item["./nav:attribute[./@name='pageDescription']"]?size > 0)>
         <#return item["./nav:attribute[./@name='pageDescription']"]>
+    <#else>
+        <#return "">
     </#if>
 </#function>