281 lines
16 KiB
HTML
281 lines
16 KiB
HTML
<h1 id="creating-themes-for-libreccm-with-freemarker">Creating themes for LibreCCM with Freemarker</h1>
|
|
<p>Starting with version 2.5 the LibreCCM platform support <a href="https://freemarker.apache.org">Freemarker</a> as an alternative to XSL. Freemarker is a project of the Apache Foundation and a well known and mature template engine for Java. The support for Freemarker in version 2.5 is a backport from the upcoming version 7 of the LibreCCM platform.</p>
|
|
<p>Compared to XSL Freemarker is a lot easier to use, especially if you have worked with other template engines like Twig, Velocity etc before. In version 7 of the LibreCCM platform Freemarker will be become the primary template engine. XSL will still be supported, but we recommanded that you port your themes to Freemarker. Why Freemarker and not one of the other template engines? Freemarker is able to process XML in a <a href="https://freemarker.apache.org/docs/xgui.html">similar way than XSL</a>.</p>
|
|
<p>Freemarker also allows it to define <a href="https://freemarker.apache.org/docs/dgui_misc_userdefdir.html">user defined directivies</a> and <a href="https://freemarker.apache.org/docs/ref_directive_function.html">functions</a>. To make it easier to create impressive themes we provide functions and macros for Freemarker we provide several functions and macros which hide the complexity of the XML data model created by CCM from the template author. It is recommanded not to access the XML data model directly. Instead the provided functions should be used. Otherwise your theme might brake when the XML structure changes.</p>
|
|
<h2 id="general-structure-of-a-freemarker-theme">General structure of a Freemarker theme</h2>
|
|
<p>Freemarker themes have a different structure than the usual "old style" themes of LibreCCM.</p>
|
|
<p>ToDo</p>
|
|
<h2 id="predefined-variables-and-functions">Predefined variables and functions</h2>
|
|
<p>Several variables and functions are predefined and available without importing another file.</p>
|
|
<h3 id="variables">Variables</h3>
|
|
<h4 id="contextpath"><code>contextPath</code></h4>
|
|
<p>The context path in which CCM is running.</p>
|
|
<h4 id="contextprefix"><code>contextPrefix</code></h4>
|
|
<p>The context prefix.</p>
|
|
<h4 id="dispatcherprefix"><code>dispatcherPrefix</code></h4>
|
|
<p>Prefix for the CCM dispatcher (usually <code>/ccm</code>)</p>
|
|
<h4 id="host"><code>host</code></h4>
|
|
<p>The current host.</p>
|
|
<h4 id="model"><code>model</code></h4>
|
|
<p>The XML document created by LibreCCM.</p>
|
|
<h4 id="negotiatedlanguage"><code>negotiatedLanguage</code></h4>
|
|
<p>The language negoiated between the user agent and LibreCCM.</p>
|
|
<h4 id="requestscheme"><code>requestScheme</code></h4>
|
|
<p>The protocol (http or https).</p>
|
|
<h4 id="selectedlanguage"><code>selectedLanguage</code></h4>
|
|
<p>The language selected by the user.</p>
|
|
<h4 id="themeprefix"><code>themePrefix</code></h4>
|
|
<p>The prefix of the theme. Only available if a development theme is viewed.</p>
|
|
<h3 id="functions">Functions</h3>
|
|
<h4 id="getlocalizedtext"><code>getLocalizedText</code></h4>
|
|
<pre><code>String getLocalizedText(String key)</code></pre>
|
|
<p>Returns the localized text from the resource bundle of the theme.</p>
|
|
<h4 id="getcontentitemtemplate"><code>getContentItemTemplate</code></h4>
|
|
<pre><code>String getContentItemTemplate(String objectType, view="DETAIL", style="")</code></pre>
|
|
<p>This is an internal function!</p>
|
|
<p>Returns the path for the template of a content item of a specific type.</p>
|
|
<h4 id="formatdatetime"><code>_formatDateTime</code></h4>
|
|
<p>An internal functions date time formatting. This functions should not be used directly.</p>
|
|
<h2 id="functions-and-macros">Functions and Macros</h2>
|
|
<h3 id="common-functions">Common functions</h3>
|
|
<h4 id="language-related">Language related</h4>
|
|
<p>Import path: <code><#import /language.ftl as Lang></code></p>
|
|
<h5 id="getavailablelanguages"><code>getAvailableLanguages</code></h5>
|
|
<pre><code>Sequence getAvailableLanguages()</code></pre>
|
|
<p>Returns the available languages for the current document as sequence. These sequence can be used for creating links for selecting the language:</p>
|
|
<pre><code><ul class="language-selector">
|
|
<#list Lang.getAvailableLanguages()?sort as lang>
|
|
<li class="${(lang==negotiatedLanguage)?then('selected', '')}">${lang}</li>
|
|
</#list>
|
|
</ul></code></pre>
|
|
<p>This example uses the <code>list</code> directive from Freemarker to iterate over the available languages returned by <code>getAvailableLanguages</code> The Freemarker build-in <code>?then</code> is used together with the <code>negotiatedLanguage</code> variable to check if the curent language is the selected language. If this is the case a CSS class is added to the HTML.</p>
|
|
<h4 id="basic-functions">Basic functions</h4>
|
|
<p>Import path: <code><#import /utils.ftl as Utils></code></p>
|
|
<h5 id="getpageapplication">getPageApplication</h5>
|
|
<pre><code>getPageApplication()</code></pre>
|
|
<p>Return the application of the current page.</p>
|
|
<h5 id="getpagetitle">getPageTitle</h5>
|
|
<pre><code>getPageTitle()</code></pre>
|
|
<p>Returns the title of the current page</p>
|
|
<h5 id="getsitehostname">getSiteHostName</h5>
|
|
<pre><code>getSiteHostName()</code></pre>
|
|
<p>Returns the name of the host serving the site.</p>
|
|
<h5 id="getsitename">getSiteName</h5>
|
|
<pre><code>getSiteName()</code></pre>
|
|
<p>Returns the name of the site.</p>
|
|
<h5 id="getbooleanattrvalue">getBooleanAttrValue</h5>
|
|
<pre><code>getBooleanAttrValue(fromNode: Node attrName: String)</code></pre>
|
|
<p>A helper function which tries to convert the value of the attribute <code>attrName</code> of the node <code>fromNode</code> to a boolean. The following values are interpreted as true: <code>true</code>, <code>yes</code>. All other values are interpreted as <code>false</code>.</p>
|
|
<h6 id="parameters">Parameters</h6>
|
|
<p><code>fromNode</code> A XML node</p>
|
|
<p><code>attrName</code> The name of attribute to interpret as boolean</p>
|
|
<h6 id="returns">Returns</h6>
|
|
<p>A boolean for the value of the attribute. If the attribute is not present in the provided node the function returns <code>false</code>.</p>
|
|
<h5 id="formatdatetime-1">formatDateTime</h5>
|
|
<pre><code>formatDateTime(style: String date: Node)</code></pre>
|
|
<p>Formats the value of date/time value node according to the provided <code>style</code>. The is defined in the theme manifest in the <code>date-time-formats</code> section. It is possible to define different styles for different languages. The style definition in the theme manifest must be in the format expected by the Java <a href="https://docs.oracle.com/javase/8/docs/api/index.html?java/time/format/DateTimeFormatter.html">DateTimeFormatter</a> class.</p>
|
|
<h6 id="parameters-1">Parameters</h6>
|
|
<p><code>style</code> A date-time format defined in the theme manifest. The format must be formatted as expected by the <a href="https://docs.oracle.com/javase/8/docs/api/index.html?java/time/format/DateTimeFormatter.html">DateTimeFormatter</a> class.</p>
|
|
<p><code>date</code> The node providing the data of the date to format.</p>
|
|
<h6 id="returns-1">Returns</h6>
|
|
<p>A date formatted as defined in <code>style</code>.</p>
|
|
<h6 id="examples">Examples</h6>
|
|
<p>In the theme manifest in the following format is defined:</p>
|
|
<pre><code>"date-time-formats": [
|
|
...
|
|
{
|
|
"style": "news",
|
|
"lang": "de",
|
|
"format": "dd.MM.YYYY"
|
|
},
|
|
{
|
|
"style": "news",
|
|
"lang": "en",
|
|
"format": "MM/dd/YY"
|
|
},
|
|
...
|
|
]</code></pre>
|
|
<p>The use this format:</p>
|
|
<pre><code>Utils.formatDateTime('news', News.getDateTime(item))</code></pre>
|
|
<p><code>News.getDateTime</code> gets the date of a news item. If the date of the news is 2019-04-01 the return value of the function for german is</p>
|
|
<pre><code>01.04.2019</code></pre>
|
|
<p>and for english:</p>
|
|
<pre><code>4/1/19</code></pre>
|
|
<h3 id="ccm-cms-assets-fileattachment">ccm-cms-assets-fileattachment</h3>
|
|
<p>This module provides functions for dealing with file attachments. A possible usage these functions:</p>
|
|
<pre><code><#list FileAttachments.getFileAttachments(item)>
|
|
<div class="file-attachments">
|
|
|
|
<h2>
|
|
${getLocalizedText("layout.page.main.fileAttachments")}
|
|
</h2>
|
|
|
|
<ul class="file-attachments">
|
|
<#items as file>
|
|
<#if FileAttachments.getFileType(file) == "caption">
|
|
<li class="caption">
|
|
<strong>${FileAttachments.getFileName(file)}</strong>
|
|
<p>
|
|
${FileAttachments.getFileDescription(file)}
|
|
</p>
|
|
</li>
|
|
<#else>
|
|
<li class="file-attachment">
|
|
<a href="${FileAttachments.getFileUrl(file)}">
|
|
<span class="fa fa-download"></span>
|
|
${FileAttachments.getFileDescription(file)}
|
|
(${FileAttachments.getMimeTypeFileExtension(file)},
|
|
${FileAttachments.getFileSize(file, "KiB")} KB)
|
|
|
|
</a>
|
|
</li>
|
|
</#if>
|
|
</#items>
|
|
</ul>
|
|
</div>
|
|
</#list></code></pre>
|
|
<h4 id="getfileattachments">getFileAttachments</h4>
|
|
<pre><code>getFileAttachments(item: ContentItemNode): Sequence</code></pre>
|
|
<p>Return the file attachments of a content items</p>
|
|
<h5 id="parameters-2">Parameters</h5>
|
|
<p><code>item</code> The content item from which the file attachments are retrieved.</p>
|
|
<h5 id="returns-2">Returns</h5>
|
|
<p>A sequence of the file attachments of the provided content item.</p>
|
|
<h4 id="getfiletype">getFileType</h4>
|
|
<pre><code>getFileType(file)</code></pre>
|
|
<p>Returns the type of the file attachments which is either <code>caption</code> or <code>file</code>.</p>
|
|
<h5 id="parameters-3">Parameters</h5>
|
|
<p><code>file</code> The file attachment</p>
|
|
<h5 id="returns-3">Returns</h5>
|
|
<p>The type of the file attachment.</p>
|
|
<h4 id="getmimetype">getMimeType</h4>
|
|
<pre><code>getMimeType(file)</code></pre>
|
|
<p>Returns the mime type of the file.</p>
|
|
<h5 id="parameters-4">Parameters</h5>
|
|
<p><code>file</code> The file</p>
|
|
<h5 id="returns-4">Returns</h5>
|
|
<p>The mime type of the file.</p>
|
|
<h4 id="getmimetypefileextension">getMimeTypeFileExtension</h4>
|
|
<pre><code>getMimeTypeFileExtension(file)</code></pre>
|
|
<p>Returns the usual file extension for the mime type of the file.</p>
|
|
<h5 id="parameters-5">Parameters</h5>
|
|
<p><code>file</code> The file</p>
|
|
<h5 id="returns-5">Returns</h5>
|
|
<p>The usual file extension for the mime type of the file.</p>
|
|
<h4 id="getfilesize">getFileSize</h4>
|
|
<pre><code>getFileSize(file unit="byte")</code></pre>
|
|
<p>Returns the size of the file in the provided unit.</p>
|
|
<h5 id="parameters-6">Parameters</h5>
|
|
<p><code>file</code>The file</p>
|
|
<p><code>unit</code> Optional parameter for unit in which the size is returned. Default value is <code>byte</code>. Supported values are <code>byte</code>, <code>kB</code> <code>KiB</code>, <code>MB</code> and <code>MiB</code>. All other values are interpreted as <code>byte</code>.</p>
|
|
<h5 id="returns-6">Returns</h5>
|
|
<p>The size of the file in the provided unit.</p>
|
|
<h4 id="getfileid">getFileId</h4>
|
|
<pre><code>getFileId(file)</code></pre>
|
|
<p>Returns the ID of the file.</p>
|
|
<h5 id="parameters-7">Parameters</h5>
|
|
<p><code>file</code> The file</p>
|
|
<h5 id="returns-7">Returns</h5>
|
|
<p>The ID of the file.</p>
|
|
<h4 id="getfilename">getFileName</h4>
|
|
<pre><code>getFileName(file)</code></pre>
|
|
<p>Returns the name of file.</p>
|
|
<h5 id="parameters-8">Parameters</h5>
|
|
<p><code>file</code> The file</p>
|
|
<h5 id="returns-8">Returns</h5>
|
|
<p>The name of the file.</p>
|
|
<h4 id="getfiledescription">getFileDescription</h4>
|
|
<pre><code>getFileDescription(file)</code></pre>
|
|
<p>Returns the name of file.</p>
|
|
<h5 id="parameters-9">Parameters</h5>
|
|
<p><code>file</code> The file</p>
|
|
<h5 id="returns-9">Returns</h5>
|
|
<p>The description of the file.</p>
|
|
<h4 id="getfileurl">getFileUrl</h4>
|
|
<pre><code>getFileUrl(file)</code></pre>
|
|
<p>Returns the name of file.</p>
|
|
<h5 id="parameters-10">Parameters</h5>
|
|
<p><code>file</code> The file</p>
|
|
<h5 id="returns-10">Returns</h5>
|
|
<p>The URL of the file.</p>
|
|
<h3 id="ccm-cms-assets-imagestep">ccm-cms-assets-imagestep</h3>
|
|
<p>Provides functions for dealing with image attachments of a content item.</p>
|
|
<p>Import path: <code><#import "/ccm-cms-assets-imagestep.ftl" as Images></code></p>
|
|
<p>Example usage:</p>
|
|
<pre><code><#import "/ccm-cms-assets-imagestep.ftl" as Images>
|
|
|
|
<#list Images.getImageAttachments(item)>
|
|
<div class="image-attachments">
|
|
<#items as image>
|
|
<figure>
|
|
<div>
|
|
<a data-fancybox="gallery">
|
|
<img src="${Images.getImageUrl(image)}"
|
|
width="100%"
|
|
height="auto" />
|
|
</a>
|
|
</div>
|
|
<figcaption>
|
|
${Images.getImageCaption(image)}
|
|
</figcaption>
|
|
</figure>
|
|
</#items>
|
|
</div>
|
|
</#list></code></pre>
|
|
<h4 id="getimageattachments">getImageAttachments</h4>
|
|
<pre><code>getImageAttachments(item)</code></pre>
|
|
<p>Get the image attachments of a content item</p>
|
|
<h5 id="parameters-11">Parameters</h5>
|
|
<p><code>item</code> The content item.</p>
|
|
<h5 id="returns-11">Returns</h5>
|
|
<p>A sequence of the image attachments of the provided content item.</p>
|
|
<h4 id="getimageid">getImageId</h4>
|
|
<pre><code>getImageId(image)</code></pre>
|
|
<p>Get the ID of the provided image.</p>
|
|
<h5 id="parameters-12">Parameters</h5>
|
|
<p><code>image</code> The image.</p>
|
|
<h5 id="returns-12">Returns</h5>
|
|
<p>The id of the image.</p>
|
|
<h4 id="getimagename">getImageName</h4>
|
|
<pre><code>getImageName(image)</code></pre>
|
|
<p>Gets the name of the provided image.</p>
|
|
<h5 id="parameters-13">Parameters</h5>
|
|
<p><code>image</code> The image.</p>
|
|
<h5 id="returns-13">Returns</h5>
|
|
<p>The name of the image.</p>
|
|
<h4 id="getimagecaption">getImageCaption</h4>
|
|
<pre><code>getImageCaption(image)</code></pre>
|
|
<p>Gets the caption of the provided image.</p>
|
|
<h5 id="parameters-14">Parameters</h5>
|
|
<p><code>image</code> The image.</p>
|
|
<h5 id="returns-14">Returns</h5>
|
|
<p>The caption of the image.</p>
|
|
<h4 id="getimagesortkey">getImageSortKey</h4>
|
|
<pre><code>getImageSortKey(image)</code></pre>
|
|
<p>Gets the sort key of the provided image.</p>
|
|
<h5 id="parameters-15">Parameters</h5>
|
|
<p><code>image</code> The image.</p>
|
|
<h5 id="returns-15">Returns</h5>
|
|
<p>The sort key of the provided image.</p>
|
|
<h4 id="getimagewidth">getImageWidth</h4>
|
|
<pre><code>getImageWidth(image)</code></pre>
|
|
<p>Gets the width of the provided image.</p>
|
|
<h5 id="parameters-16">Parameters</h5>
|
|
<p><code>image</code> The image.</p>
|
|
<h5 id="returns-16">Returns</h5>
|
|
<p>The width of the provided image.</p>
|
|
<h4 id="getimageheight">getImageHeight</h4>
|
|
<pre><code>getImageHeight(image)</code></pre>
|
|
<p>Gets the height of the provided image.</p>
|
|
<h5 id="parameters-17">Parameters</h5>
|
|
<p><code>image</code> The image.</p>
|
|
<h5 id="returns-17">Returns</h5>
|
|
<p>The height of the provided image.</p>
|
|
<h4 id="getimageurl">getImageUrl</h4>
|
|
<pre><code>getImageUrl(image)</code></pre>
|
|
<p>Gets the URL of the provided image.</p>
|
|
<h5 id="parameters-18">Parameters</h5>
|
|
<p><code>image</code> The image.</p>
|
|
<h5 id="returns-18">Returns</h5>
|
|
<p>The URL of the provided image.</p>
|