Documentation for Freemarker themes
git-svn-id: https://svn.libreccm.org/ccm/trunk@6133 8810af33-2d31-482b-a856-94f89814c4dfmaster
jensp
parent
c64fbce5a6
commit
8560fba73e
|
|
@ -3,8 +3,60 @@
|
|||
<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>
|
||||
<p>Freemarker themes have a different structure than the usual "old style" themes of LibreCCM. Each Freemaker based theme must have a theme manifest file called <code>theme.json</code> on the root of its directory structure. This file provides several informations for processing the theme and serves as a central configuration point. The file must have the following structure:</p>
|
||||
<pre><code>{
|
||||
"name": "an-example-theme",
|
||||
"templates": {
|
||||
"applications": [
|
||||
{
|
||||
"application-name": "someApp",
|
||||
"application-class": "somePageClass",
|
||||
"template": "/templates/someApp.html.ftl"
|
||||
},
|
||||
...
|
||||
],
|
||||
"contentitems": [
|
||||
{
|
||||
"view": "list",
|
||||
"contentType": "com.arsdigita.cms.contenttypes.Article",
|
||||
"template": "/templates/contentitems/list/article.html.ftl"
|
||||
},
|
||||
{
|
||||
"view": "details",
|
||||
"contentType": "com.arsdigita.cms.contenttypes.Article",
|
||||
"template": "/templates/contentitems/detail/article.html.ftl"
|
||||
},
|
||||
{
|
||||
"view": "details",
|
||||
"contentType": "com.arsdigita.cms.contenttypes.Article",
|
||||
"style": "fancy",
|
||||
"template": "/templates/contentitems/detail/article.html.ftl"
|
||||
},
|
||||
...
|
||||
],
|
||||
"default-application-template": "/templates/default-layout.html.ftl",
|
||||
"default-contentitem-template": "/templates/contentitems/detail/default.html.ftl",
|
||||
},
|
||||
"data-time-formats": [
|
||||
{
|
||||
"style": "event",
|
||||
"lang": "de",
|
||||
"format": "dd. MMM. YYYY"
|
||||
},
|
||||
{
|
||||
"style": "event",
|
||||
"lang": "en",
|
||||
"format": "MM/dd/YY"
|
||||
},
|
||||
...
|
||||
]
|
||||
}</code></pre>
|
||||
<p>The <code>name</code> key defines the name of the theme which should be unique per installation. The <code>templates</code> contains several subkeys which define the templates to use.</p>
|
||||
<p>The objects in the array of the <code>applications</code> key specify which template is used for an application. To determine which template should be used the attributes <code>application</code> and and <code>class</code> of from the root element of the XML data model are used. The value of the <code>application</code> attribute is matched against the value for the <code>application-name</code> field, the value of the class attribute against the value of the <code>application-class</code> field.</p>
|
||||
<p>CCM will first try to find a a template definition which matches both the <code>class</code> and the <code>application</code>. If none is found a template definition which a matching <code>application-name</code> and an empty <code>application-class</code> will be looked up. If there is no match the template defined as <code>default-application-template</code> is used.</p>
|
||||
<p>There is one special value value for the <code>template</code> field: <code>XSL_FALLBACK.XSL</code>. If the <code>template</code> field is set to this value CCM will fallback to the old XSL themes.</p>
|
||||
<p>For content items the procedure is similar, only the names of the fields in the template definition differ. The <code>view</code> field is used internally to select either the detail or the list view. The <code>contentType</code> field is the content types of the content items. The third field <code>style</code> is optional and can be used to select different templates depending on the theme context. For more informations please refer to the documentation of the <code>contentItem</code> macro provided by the ccm-cms module.</p>
|
||||
<p>The <code>date-time-formats</code> section is used to define date-time formats to use with the <code>formatDateTime</code> function provided by <code>ccm-themedirector</code>.</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>
|
||||
|
|
|
|||
|
|
@ -80,7 +80,37 @@ central configuration point. The file must have the following structure:
|
|||
]
|
||||
}
|
||||
|
||||
The `name` key defines the name of the theme which should be unique per
|
||||
installation. The `templates` contains several subkeys which define the
|
||||
templates to use.
|
||||
|
||||
The objects in the array of the `applications` key specify which template is
|
||||
used for an application. To determine which template should be used the
|
||||
attributes `application` and and `class` of from the root element of the
|
||||
XML data model are used. The value of the `application` attribute is matched
|
||||
against the value for the `application-name` field, the value of the class
|
||||
attribute against the value of the `application-class` field.
|
||||
|
||||
CCM will first try to find a a template definition
|
||||
which matches both the `class` and the `application`. If none is found
|
||||
a template definition which a matching `application-name` and an empty
|
||||
`application-class` will be looked up. If there is no match the template defined
|
||||
as `default-application-template` is used.
|
||||
|
||||
There is one special value value for the `template` field: `XSL_FALLBACK.XSL`.
|
||||
If the `template` field is set to this value CCM will fallback to the old XSL
|
||||
themes.
|
||||
|
||||
For content items the procedure is similar, only the names of the fields in the
|
||||
template definition differ. The `view` field is used internally to select either
|
||||
the detail or the list view. The `contentType` field is the content types of the
|
||||
content items. The third field `style` is optional and can be used to select
|
||||
different templates depending on the theme context. For more informations please
|
||||
refer to the documentation of the `contentItem` macro provided by the ccm-cms
|
||||
module.
|
||||
|
||||
The `date-time-formats` section is used to define date-time formats to use
|
||||
with the `formatDateTime` function provided by `ccm-themedirector`.
|
||||
|
||||
## Predefined variables and functions
|
||||
|
||||
|
|
|
|||
Binary file not shown.
Loading…
Reference in New Issue