From ccf8cb9b33cb2b4e06d1e3550536d3dea5d178fe Mon Sep 17 00:00:00 2001 From: jensp Date: Sun, 3 Nov 2019 09:24:34 +0000 Subject: [PATCH] Docuemntation for the FTL libs provided by ccm-navigation git-svn-id: https://svn.libreccm.org/ccm/trunk@6285 8810af33-2d31-482b-a856-94f89814c4df --- .../freemarker/ccm-navigation/navigation.ftl | 97 +++++- .../freemarker/ccm-navigation/object-list.ftl | 291 +++++++++++++++++- 2 files changed, 378 insertions(+), 10 deletions(-) diff --git a/ccm-navigation/web/themes/freemarker/ccm-navigation/navigation.ftl b/ccm-navigation/web/themes/freemarker/ccm-navigation/navigation.ftl index 4db6ab1dd..25c7559c5 100644 --- a/ccm-navigation/web/themes/freemarker/ccm-navigation/navigation.ftl +++ b/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"]> +<#--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)> +<#--doc + Gets the currently selected category. + + @return The currently selected category. +--> <#function getSelectedCategory> <#return model["/bebop:page/nav:categoryPath/nav:category[last()]"]> +<#--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"]> -<#-- +<#--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"]> +<#--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)> -<#-- +<#--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"]> -<#-- +<#--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"]> -<#-- +<#--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"]> -<#-- - Retrieves the first level of categories from the category hierachy with the provided ID. - If no id is provided 'categoryNav' is used. +<#--doc + Retrieves the first level of categories from the category hierachy with the + 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"]> -<#-- +<#--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"]> +<#--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"]> +<#--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"]> \ No newline at end of file diff --git a/ccm-navigation/web/themes/freemarker/ccm-navigation/object-list.ftl b/ccm-navigation/web/themes/freemarker/ccm-navigation/object-list.ftl index 6a5f15c70..ba5ad68ca 100644 --- a/ccm-navigation/web/themes/freemarker/ccm-navigation/object-list.ftl +++ b/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)> <#-- 
Found customizable object list ${listId}
--> - <#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 @@ +<#--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 @@ +<#--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 @@ +<#--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> +<#--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> +<#--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 @@ +<#--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> +<#--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"]> +<#--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> +<#--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)> +<#--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)> +<#--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"> +<#--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)> +<#--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']"]> +<#--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 @@ +<#--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)> +<#--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']"]> +<#--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)> +<#--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}']"]> +<#--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)> +<#--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 @@ +<#--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)> +<#--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 @@ +<#--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 @@ +<#--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"]> +<#--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"]> +<#--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 @@ +<#--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"]> +<#--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"]> +<#--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 @@ +<#--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 @@ +<#--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 @@ +<#--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 @@ +<#--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 @@ +<#--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"]> +<#--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"]> +<#--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"]> +<#--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>