From 57275b6d791b4d82f04cc78f90792194951a66ce Mon Sep 17 00:00:00 2001 From: jensp Date: Wed, 5 Jun 2019 13:34:13 +0000 Subject: [PATCH] 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 | 171 ++++++++++++++++++ .../freemarker/ccm-cms/content-item.ftl | 4 + 2 files changed, 175 insertions(+) create mode 100644 ccm-cms/doc/ccm-cms-freemarker.md diff --git a/ccm-cms/doc/ccm-cms-freemarker.md b/ccm-cms/doc/ccm-cms-freemarker.md new file mode 100644 index 000000000..429652d5d --- /dev/null +++ b/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 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 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`. \ No newline at end of file diff --git a/ccm-cms/web/themes/freemarker/ccm-cms/content-item.ftl b/ccm-cms/web/themes/freemarker/ccm-cms/content-item.ftl index d156a8001..98c63a04e 100644 --- a/ccm-cms/web/themes/freemarker/ccm-cms/content-item.ftl +++ b/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 ""> @@ -99,6 +101,8 @@ <#return item["./pageDescription"]> <#elseif (item["./nav:attribute[./@name='pageDescription']"]?size > 0)> <#return item["./nav:attribute[./@name='pageDescription']"]> + <#else> + <#return "">