Docuemntation for the FTL libs provided by ccm-navigation

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

ccm-navigation/web/themes/freemarker/ccm-navigation/navigation.ftl

@@ -5,27 +5,54 @@
 "ui": "http://www.arsdigita.com/ui/1.0"}
 >
 
-<#-- 
+<#--filedoc
+    Functions for processing the data of the components provided by 
+    ccm-navigation.
+-->
+
+<#--doc 
     Get all categories from the category path.
+
+    @return All categories in the current category path.
 -->
 <#function getCategoryPath>
     <#return model["/bebop:page/nav:categoryPath/nav:category"]>
 </#function>
 
+<#--doc
+    Determines if the current page is the root page of a navigation.
+
+    @return `true` if teh current page is a root page, `false` otherwise.
+-->
 <#function isRootPage>
     <#return (model["/bebop:page/nav:categoryPath/nav:category"]?size <= 1)>
 </#function>
 
+<#--doc
+    Gets the currently selected category.
+
+    @return The currently selected category.
+-->
 <#function getSelectedCategory>
     <#return model["/bebop:page/nav:categoryPath/nav:category[last()]"]>
 </#function>
 
+<#--doc
+    Gets the ID of the currently selected category.
+
+    @return The ID of the currently selected category.
+-->
 <#function getSelectedCategoryId>
     <#return model["/bebop:page/nav:categoryPath/nav:category[last()]/@id"]>
 </#function>
 
-<#--
+<#--doc
     Get the title of the provided category.
+
+    @param The model of a category as returned by several functions in this 
+    library.
+
+    @return The title of the category.
 -->
 <#function getCategoryTitle category>
     <#return category["./@title"]>
@@ -33,6 +60,11 @@
 
 <#--
     Get the URL of the provided category.
+
+    @param The model of a category as returned by several functions in this 
+    library.
+
+    @return The URL of the category.
 -->
 <#function getCategoryUrl category>
     <#return category["./@url"]>
@@ -40,56 +72,103 @@
 
 <#--
     Get the ID get the provided category.
+
+    @param The model of a category as returned by several functions in this 
+    library.
+
+    @return The ID of the provided category.
 -->
 <#function getCategoryId category>
     <#return category["./@id"]>
 </#function>
 
+<#--doc
+    Determines of the provided category is selected.
+
+    @param The model of a category as returned by several functions in this 
+    library.
+
+    @return `true` if the category is selected, `false` if not.
+-->
 <#function isCategorySelected category>
     <#return (category["./@isSelected='true'"] == true)>
 </#function>
 
-<#--
+<#--doc
     Get the URL of the root category of the navigation with the provided id.
+
+    @param navigationId The ID of the navigation system to use.
+
+    @return The URL of the root category of the navigation system with the 
+    provided ID.
 -->
 <#function getNavigationRootUrl navigationId="categoryMenu">
     <#return model["/bebop:page/nav:categoryMenu[@id='${navigationId}']/nav:category/@url"]>
 </#function>
 
-<#--
+<#--doc
     Get title of the navigation with the provided id.
+
+    @param navigationId The ID of the navigation system to use.
+
+    @return The title of the navigation.
 -->
 <#function getNavigationTitle navigationId="categoryMenu">
     <#return model["/bebop:page/nav:categoryMenu[@id='${navigationId}']/nav:category/@title"]>
 </#function>
 
-<#--
+<#--doc
     Retrieves the first level of categories from the category menu with the provided ID. 
     If no id is provided "categoryMenu" is used.
+
+    @param menuId The ID of the category menu to use.
+
+    @return The first level of categories in the menu.
 -->
 <#function getCategoryMenu menuId="categoryMenu">
     <#return model["/bebop:page/nav:categoryMenu[@id='${menuId}']/nav:category/nav:category"]>
 </#function>
 
-<#--
+<#--doc
-    Retrieves the first level of categories from the category hierachy with the provided ID.
+    Retrieves the first level of categories from the category hierachy with the 
-    If no id is provided 'categoryNav' is used.
+    provided ID. If no id is provided 'categoryNav' is used.
+
+    @param hierarchyId The ID of the category hierachy to use.
+
+    @return The first level of categories in the hierarchy.
 -->
 <#function getCategoryHierarchy hierarchyId="categoryNav">
     <#return model["/bebop:page/nav:categoryHierarchy[@id='${hierarchyId}']/nav:category"]>
 </#function>
 
-<#--
+<#--doc
     Gets the subcategories of the provided category.
+
+    @param ofCategory The model of the category.
+
+    @return The sub categories of the provided category.
 -->
 <#function getSubCategories ofCategory>
     <#return ofCategory["./nav:category"]>
 </#function>
 
+<#--doc
+    Gets the subcategories of the category with the provided id.
+
+    @param categoryId The ID of the category to use.
+
+    @return The sub categories of the category with the provided ID.
+-->
 <#function getSubCategoriesOfCategoryWithId categoryId>
     <#return model["/bebop:page/nav:categoryMenu//nav:category[@id=${categoryId}]/nav:category"]>
 </#function>
 
+<#--doc
+    Gets the greeting/index item of the current navigation page. The returned
+    model can be processed with usual functions for processing content items.
+
+    @return The model of the index item.
+-->
 <#function getGreetingItem>    
     <#return model["/bebop:page/nav:greetingItem/cms:item"]>
 </#function>

ccm-navigation/web/themes/freemarker/ccm-navigation/object-list.ftl

@@ -5,6 +5,20 @@
 "ui": "http://www.arsdigita.com/ui/1.0"}
 >
 
+<#--filedoc
+    Functions for accessing objects lists and their properties.
+-->
+
+<#--doc
+    Retrieve the item (models) of an object list. This function can deal with 
+    several different types of object lists, including `SimpleObjectList`, 
+    `ComplexObjectList` and `CustomziableObjectList`.
+
+    @param listId The ID of the object list from the the items are retrieved.
+
+    @return The models for the entries in the object list. If no list with 
+    the provided `listId` is found and empty sequence is returned.
+-->
 <#function getItems listId>
     <#if (model["/bebop:page/nav:simpleObjectList[@id='${listId}']/nav:objectList"]?size > 0)>
         <#--  <#assign items=model["/bebop:page/nav:simpleObjectList[@id='${listId}']/nav:objectList/nav:item"]>  -->
@@ -17,7 +31,7 @@
         <#--  <#assign items=model["/bebop:page/nav:simpleObjectList[@id='${listId}']/nav:objectList/nav:item"]>  -->
     <#elseif (model["/bebop:page/nav:customizableObjectList[@id='${listId}']/nav:objectList"]?size > 0)>
         <#--  <pre>Found customizable object list ${listId}</pre>  -->
-        <#return model["/bebop:page/nav:simpleObjectList[@id='${listId}']/nav:objectList/nav:item"]>
+        <#return model["/bebop:page/nav:customizableObjectList[@id='${listId}']/nav:objectList/nav:item"]>
         <#--  <#assign items=model["/bebop:page/nav:simpleObjectList[@id='${listId}']/nav:objectList/nav:item"]>  -->
     <#else>
         <#return []>
@@ -25,6 +39,14 @@
     </#if>
 </#function>
 
+<#--doc
+    Gets the number of objects/items in an object list.
+
+    @param listId The ID of the object list to use.
+
+    @return The number of objects in the list. If no list with the provided
+    `listId` is found `0` is returned.
+-->
 <#function getObjectCount listId>
     <#if (model["/bebop:page/*[@id='${listId}']/nav:noContent"]?size > 0)>
         <#return 0>
@@ -37,6 +59,13 @@
     </#if>
 </#function>
 
+<#--doc
+    Gets the base URL for the paginator of an object list.
+
+    @param listId The ID of the object list to use.
+
+    @return The base URL for the the paginator.
+-->
 <#function getPaginatorBaseUrl listId>
     <#assign baseUrl = model["/bebop:page/*[@id='${listId}']/nav:objectList/nav:paginator/@baseURL"]>
     <#if (baseUrl?contains("?"))>
@@ -46,14 +75,36 @@
     </#if>
 </#function>
 
+<#--doc
+    Gets the index of the first item shown on the current page.
+
+    @param listId The ID of the object list to use.
+
+    @return The index of the first item shown on the current page.
+-->
 <#function getPaginatorBegin listId>
     <#return model["/bebop:page/*[@id='${listId}']/nav:objectList/nav:paginator/@objectBegin"]?number>
 </#function>
 
+<#--doc
+    Gets the index of the last item shown on the curent page.
+
+    @param listId The ID of the object list to use.
+
+    @return The index of the last item shown on the current page.
+-->
 <#function getPaginatorEnd listId>
     <#return model["/bebop:page/*[@id='${listId}']/nav:objectList/nav:paginator/@objectEnd"]?number>
 </#function>
 
+<#--doc
+    Get the number of pages of an object list.
+
+    @param listId The ID of the object list to use.
+
+    @return The number of pages of the object list. If no list with the 
+    provided `listId` is found the function will return `0`.
+-->
 <#function getPageCount listId>
     <#if (model["/bebop:page/*[@id='${listId}']/nav:objectList/nav:paginator/@pageCount"]?size == 1)>
         <#return model["/bebop:page/*[@id='${listId}']/nav:objectList/nav:paginator/@pageCount"]?number>
@@ -63,38 +114,101 @@
     
 </#function>
 
+<#--doc
+    Gets the number of the current page.
+
+    @param listId The ID of the object list to use.
+
+    @return The number of the page currently shown.
+-->
 <#function getPageNumber listId>
     <#return model["/bebop:page/*[@id='${listId}']/nav:objectList/nav:paginator/@pageNumber"]?number>
 </#function>
 
+<#--doc
+    Gets the name of the page URL parameter.
+
+    @param listId The ID of the object list to use.
+
+    @return The name of the page URL parameter.
+-->
 <#function getPageParam listId>
     <#return model["/bebop:page/*[@id='${listId}']/nav:objectList/nav:paginator/@pageParam"]>
 </#function>
 
+<#--doc
+    Gets the maximum number of items on a page.
+
+    @param listId The ID of the object list to use.
+
+    @return The maxium number of items on a page.
+-->
 <#function getPageSize listId>
     <#return model["/bebop:page/*[@id='${listId}']/nav:objectList/nav:paginator/@pageSize"]?number>
 </#function>
 
+<#--doc
+    Gets the link to the previous page.
+
+    @param listId The ID of the object list to use.
+
+    @return The link to the previous page.
+-->
 <#function getPrevPageLink listId>
     <#return getPaginatorBaseUrl(itemId) + getPageParam(listId) + "="  + (getPageNumber(listId) - 1)>
 </#function>
 
+<#--doc
+    Gets the link to the next page.
+
+    @param listId The ID of the object list to use.
+
+    @return The link to the next page.
+-->
 <#function getNextPageLink listId>
     <#return getPaginatorBaseUrl(itemId) + getPageParam(listId) + "="  + (getPageNumber(listId) + 1)>
 </#function>
 
+<#--doc
+    Gets the link to the first page.
+
+    @param listId The ID of the object list to use.
+
+    @return The link to the first page.
+-->
 <#function getFirstPageLink listId>
     <#return getPaginatorBaseUrl(itemId) + getPageParam(listId) + "=1">
 </#function>
 
+<#--doc
+    Gets the link to the last page.
+
+    @param listId The ID of the object list to use.
+
+    @return The link to the last page.
+-->
 <#function getLastPageLink listId>
     <#return getPaginatorBaseUrl(itemId) + getPageParam(listId) + "=" + getPageCount(itemId)>
 </#function>
 
+<#--doc
+    Gets the title of an item from an object list.
+
+    @param item The model of the list entry for the item.
+
+    @return The title of the item.
+-->
 <#function getItemTitle item>
     <#return item["./nav:attribute[@name='title']"]>
 </#function>
 
+<#--doc
+    Gets the link to the detail view of an item in a list.
+
+    @param item The model of the list entry for the item.
+
+    @return The link to the detail view of the item.
+-->
 <#function getItemLink item>
     <#if (item["./nav:path"]?size > 0)>
         <#return item["./nav:path"].@@text>
@@ -103,26 +217,77 @@
     </#if>
 </#function>
 
+<#--doc
+    Checks if the model of the list entry of an item contains a value for the
+    `lead` property.
+
+    @param item The model of the list entry for the item.
+
+    @return `true` if the model provides a value of the `lead` property, 
+    `false` if not.
+-->
 <#function hasItemLead item>
     <#return (item["./nav:attribute[@name='lead']"]?size > 0)>
 </#function>
 
+<#--doc
+    Gets the value of the `lead` property of an item.
+
+    @param item The model of the list entry for the item.
+
+    @return The value of the `lead` property.
+-->
 <#function getItemLead item>
     <#return item["./nav:attribute[@name='lead']"]>
 </#function>
 
+<#--doc
+    A generic function for checking if the model of a list entry for an item
+    has a specific property.
+
+    @param item The model of the list entry for the item.
+
+    @param property The name of the property to check for.
+
+    @return `true` If the provided model provides an value for the property, 
+    `false` if not.
+-->
 <#function hasItemProperty item property>
     <#return (item["./nav:attribute[@name='${property}']"]?size > 0)>
 </#function>
 
+<#--doc
+    A generic function for retrieving the value of an property from the model
+    for a list entry for an item.
+
+    @param item The model of the list entry for the item.
+
+    @param property The name of the property to retrieve.
+
+    @return The value of the property.
+-->
 <#function getItemProperty item property>
     <#return item["./nav:attribute[@name='${property}']"]>
 </#function>
 
+<#--doc
+    Checks if the provided item has an associated image. 
+
+    @param item The model of the list entry for the item.
+
+    @return `true` if the item has an associated image, `false` if not.
+-->
 <#function hasImage item>
     <#return (item["./nav:attribute[@name='imageAttachments.image.id']"]?size > 0 || item["./imageAttachments"]?size > 0)>
 </#function>
 
+<#--doc
+    Get the ID of an associated image.
+
+    @param item The model of the list entry for the item.
+
+    @return The ID of the associated image.
+-->
 <#function getImageId item>
     <#if (item["./nav:attribute[@name='imageAttachments.image.id']"]?size > 0)>
         <#return item["./nav:attribute[@name='imageAttachments.image.id'][1]"]>
@@ -131,10 +296,24 @@
     </#if>
 </#function>
 
+<#--doc
+    Generates the URL for an associated image.
+
+    @param item The model of the list entry for the item.
+
+    @return The URL of the associated image. 
+-->
 <#function getImageUrl item>
     <#return dispatcherPrefix + '/cms-service/stream/image/?image_id=' + getImageId(item)>
 </#function>
 
+<#--doc
+    Gets the caption for the associated image.
+
+    @param item The model of the list entry for the item.
+
+    @return The caption for the associated image.
+-->
 <#function getImageCaption item>
     <#if (item["./nav:attribute[@name='imageAttachments.image.id']"]?size > 0)>
         <#return item["./nav:attribute[@name='imageAttachments.image.caption'][1]"].@@text>
@@ -143,6 +322,14 @@
     </#if>
 </#function>
 
+<#--doc
+    Retrieves the filters for an object list.
+
+    @param listId The ID of the list to use.
+
+    @return The filters for the list. An empty sequence is returned if no list 
+    with the provided `listId`  could be found or if the list does not have any filters.
+-->
 <#function getFilters listId>
     <#if (model["/bebop:page/nav:simpleObjectList[@id='${listId}']/filterControls"]?size > 0)>
         <#return model["/bebop:page/nav:simpleObjectList[@id='${listId}']//filterControls/filters/filter"]>
@@ -155,14 +342,35 @@
     </#if>
 </#function>
 
+<#--doc
+    Get the label of a filter.
+
+    @param filter model of a filter as returned by `getFilters`.
+
+    @return The label of the filter.
+-->
 <#function getFilterLabel filter>
     <#return filter["./@label"]>
 </#function>
 
+<#--doc
+    Get the type of a filter.
+
+    @param filter model of a filter as returned by `getFilters`.
+
+    @return The type of the filter.
+-->
 <#function getFilterType filter>
     <#return filter["./@type"]>
 </#function>
 
+<#--doc
+    Get the options of a select filter.
+
+    @param filter model of a filter as returned by `getFilters`.
+
+    @return The options of the select filter.
+-->
 <#function getSelectFilterOptions filter>
     <#if (filter["./@type"] == "select")>
         <#return filter["./option"]>
@@ -171,14 +379,35 @@
     </#if>
 </#function>
 
+<#--doc
+    Get the currently selected option of a select filter.
+
+    @param filter model of a filter as returned by `getFilters`.
+
+    @return The currently selected option.
+-->
 <#function getSelectFilterSelection filter>
     <#return filter["./selected"]>
 </#function>
 
+<#--doc
+    The label for an option of a select filter.
+
+    @param filter model of an option as returned by `getSelectFilterOptions`.
+
+    @return The label of the option.
+-->
 <#function getSelectFilterOptionLabel option>
     <#return option["./label"]>
 </#function>
 
+<#--doc
+    Gets the search string of an category filter.
+
+    @param filter model of a filter as returned by `getFilters`.
+
+    @return The search string.
+-->
 <#function getCategoryFilterSearchString filter>
     <#if filter["./@type"] == "categoryFilter">
         <#return filter["./searchString"]>
@@ -187,6 +416,13 @@
     </#if>
 </#function>
 
+<#--doc
+    Gets the separator for a category filter.
+
+    @param filter The model of a filter as returned by `getFilters`.
+
+    @return The separator for separating the categories in the search string.
+-->
 <#function getCategoryFilterSeparator filter>
     <#if filter["./@type"] == "categoryFilter">
         <#return filter["./separator"]>
@@ -195,6 +431,13 @@
     </#if>
 </#function>
 
+<#--doc
+    Determines if a category allows the selection of multiple categories.
+
+    @param filter The model of a filter as returned by `getFilters`.
+
+    @return `true` if the filter allows multiple selections, `false` otherwise.
+-->
 <#function getCategoryFilterMultiple filter>
     <#if filter["./@type"] == "categoryFilter">
         <#return filter["./multiple"] == "true">
@@ -203,6 +446,13 @@
     </#if>
 </#function>
 
+<#--doc
+    Gets the selectable categories for a category filter.
+
+    @param filter The model of a filter as returned by `getFilters`.
+
+    @return The selectable categories.
+-->
 <#function getCategoryFilterCategories filter>
     <#if filter["./@type"] == "categoryFilter">
         <#return filter["./categories/categories"]>
@@ -211,6 +461,13 @@
     </#if>
 </#function>
 
+<#--doc
+    Gets the groups of a category filter.
+
+    @param filter The model of a filter as returned by `getFilters`.
+
+    @return The groups of a category filter.
+-->
 <#function getCategoryFilterCategoryGroups filter>
     <#if filter["./@type"] == "categoryFilter">
         <#return filter["./categories/categoryGroup"]>
@@ -219,20 +476,52 @@
     </#if>
 </#function>
 
+<#--doc
+    Gets the label of a category group.
+
+    @param group The model of a category group as returned by 
+    `getCategoryFilterCategoryGroups`.
+
+    @return The label for the group.
+-->
 <#function getCategoryGroupLabel group>
     <#return group["./label"]>
 </#function>
 
+<#--doc
+    Gets the categories in a group.
+
+    @param group The model of a category group as returned by 
+    `getCategoryFilterCategoryGroups`.
+
+    @return The categories in the group.
+-->
 <#function getCategoryFilterCategoryGroupsCategories groups>
    
     <#return group["./categories/categoryGroup/category"]>
    
 </#function>
 
+<#--doc
+    Gets the ID of a category of a category filter.
+
+    @param category The model of a category as returned by 
+    `getCategoryFilterCategoryGroupsCategories`.
+
+    @return The ID of the category.
+-->
 <#function getCategoryFilterCategoryId category>
     <#return category["./@id"]>
 </#function>
 
+<#--doc
+    Gets the label of a category of a category filter.
+
+    @param category The model of a category as returned by 
+    `getCategoryFilterCategoryGroupsCategories`.
+
+    @return The label of the category.
+-->
 <#function getCategoryFilterCategoryLabel category>
     <#return category.@@text>
 </#function>