Start of documentation for Freemarker support
git-svn-id: https://svn.libreccm.org/ccm/trunk@5994 8810af33-2d31-482b-a856-94f89814c4dfmaster
jensp
parent
4f5ca34d58
commit
17aaa191d5
|
|
@ -0,0 +1,24 @@
|
||||||
|
### Common functions
|
||||||
|
|
||||||
|
#### Language related
|
||||||
|
|
||||||
|
Import path: `<#import /utils.ftl as Utils>`
|
||||||
|
|
||||||
|
##### `getAvailableLanguages`
|
||||||
|
|
||||||
|
Sequence getAvailableLanguages()
|
||||||
|
|
||||||
|
Returns the available languages for the current document as sequence. These sequence can be used for creating links for selecting the language:
|
||||||
|
|
||||||
|
```
|
||||||
|
<ul class="language-selector">
|
||||||
|
<#list Lang.getAvailableLanguages()?sort as lang>
|
||||||
|
<li class="${(lang==negotiatedLanguage)?then('selected', '')}">${lang}</li>
|
||||||
|
</#list>
|
||||||
|
</ul>
|
||||||
|
```
|
||||||
|
|
||||||
|
This example uses the `list` directive from Freemarker to iterate over the available languages returned by `getAvailableLanguages` The Freemarker build-in `?then` is used together with the `negotiatedLanguage` variable to
|
||||||
|
check if the curent language is the selected language. If this is the case
|
||||||
|
a CSS class is added to the HTML.
|
||||||
|
|
||||||
|
|
@ -0,0 +1,7 @@
|
||||||
|
all: html pdf
|
||||||
|
|
||||||
|
html:
|
||||||
|
pandoc -t html -o themes-with-freemarker.html themes-with-freemarker.md ../../ccm-themedirector/doc/freemarker/ccm-themedirector.md
|
||||||
|
|
||||||
|
pdf:
|
||||||
|
pandoc -t latex -o themes-with-freemarker.pdf themes-with-freemarker.md ../../ccm-themedirector/doc/freemarker/ccm-themedirector.md
|
||||||
|
|
@ -0,0 +1,50 @@
|
||||||
|
<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 /utils.ftl as Utils></code></p>
|
||||||
|
<h5 id="sequence-getavailablelanguages"><code>Sequence 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>
|
||||||
|
|
@ -0,0 +1,104 @@
|
||||||
|
# Creating themes for LibreCCM with Freemarker
|
||||||
|
|
||||||
|
Starting with version 2.5 the LibreCCM platform support
|
||||||
|
[Freemarker](https://freemarker.apache.org) 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.
|
||||||
|
|
||||||
|
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
|
||||||
|
[similar way than XSL](https://freemarker.apache.org/docs/xgui.html).
|
||||||
|
|
||||||
|
Freemarker also allows it to define
|
||||||
|
[user defined directivies](https://freemarker.apache.org/docs/dgui_misc_userdefdir.html)
|
||||||
|
and [functions](https://freemarker.apache.org/docs/ref_directive_function.html).
|
||||||
|
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.
|
||||||
|
|
||||||
|
## General structure of a Freemarker theme
|
||||||
|
|
||||||
|
Freemarker themes have a different structure than the usual "old style" themes of LibreCCM.
|
||||||
|
|
||||||
|
ToDo
|
||||||
|
|
||||||
|
## Predefined variables and functions
|
||||||
|
|
||||||
|
Several variables and functions are predefined and available without
|
||||||
|
importing another file.
|
||||||
|
|
||||||
|
### Variables
|
||||||
|
|
||||||
|
#### `contextPath`
|
||||||
|
|
||||||
|
The context path in which CCM is running.
|
||||||
|
|
||||||
|
#### `contextPrefix`
|
||||||
|
|
||||||
|
The context prefix.
|
||||||
|
|
||||||
|
#### `dispatcherPrefix`
|
||||||
|
|
||||||
|
Prefix for the CCM dispatcher (usually `/ccm`)
|
||||||
|
|
||||||
|
#### `host`
|
||||||
|
|
||||||
|
The current host.
|
||||||
|
|
||||||
|
#### `model`
|
||||||
|
|
||||||
|
The XML document created by LibreCCM.
|
||||||
|
|
||||||
|
#### `negotiatedLanguage`
|
||||||
|
|
||||||
|
The language negoiated between the user agent and LibreCCM.
|
||||||
|
|
||||||
|
#### `requestScheme`
|
||||||
|
|
||||||
|
The protocol (http or https).
|
||||||
|
|
||||||
|
#### `selectedLanguage`
|
||||||
|
|
||||||
|
The language selected by the user.
|
||||||
|
|
||||||
|
#### `themePrefix`
|
||||||
|
|
||||||
|
The prefix of the theme. Only available if a development theme is viewed.
|
||||||
|
|
||||||
|
### Functions
|
||||||
|
|
||||||
|
#### `getLocalizedText`
|
||||||
|
|
||||||
|
```
|
||||||
|
String getLocalizedText(String key)
|
||||||
|
```
|
||||||
|
|
||||||
|
Returns the localized text from the resource bundle of the theme.
|
||||||
|
|
||||||
|
#### `getContentItemTemplate`
|
||||||
|
|
||||||
|
```
|
||||||
|
String getContentItemTemplate(String objectType, view="DETAIL", style="")
|
||||||
|
```
|
||||||
|
|
||||||
|
This is an internal function!
|
||||||
|
|
||||||
|
Returns the path for the template of a content item of a specific type.
|
||||||
|
|
||||||
|
#### `_formatDateTime`
|
||||||
|
|
||||||
|
An internal functions date time formatting. This functions should not be
|
||||||
|
used directly.
|
||||||
|
|
||||||
|
## Functions and Macros
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Binary file not shown.
Loading…
Reference in New Issue