From: Kai Moritz Date: Sun, 28 Feb 2021 21:47:45 +0000 (+0100) Subject: Added usage documentation X-Git-Tag: maven-thymeleaf-skin-1.1.0~1 X-Git-Url: http://juplo.de/gitweb/?a=commitdiff_plain;h=e0ea9aa9e4611ce6dd2c9f5ebd0b03208418e65d;p=maven-thymeleaf-skin Added usage documentation --- diff --git a/src/site/xhtml/usage.xhtml b/src/site/xhtml/usage.xhtml index 9487b3e..a9c4e0c 100644 --- a/src/site/xhtml/usage.xhtml +++ b/src/site/xhtml/usage.xhtml @@ -4,12 +4,13 @@ -

Usage

+

Activation

- To use this skin in your project, use the skin element of - the site.xml site descriptor: + To use this skin in your project, you have to configure the skin element of + the site descriptor + (site.xml):

-
<project name="xxx">
+  
<project name="xxx">
   [...]
   <skin>
     <groupId>${project.groupId}</groupId>
@@ -17,6 +18,95 @@
     <version>${project.version}</version>
   </skin>
   [...]
+</project>
+  
+

Configuration

+

+ In order to take full advantage of the generated templates, you should consider to tune the follwoing custom properties: +

+
    +
  • path
  • +
  • crumbs
  • +
  • command
  • +
+

path

+

The value of this configuration option is used to build the absolute path for the generated pages.

+

The skin builds three variants of the page-uri, that are made selectable for Thymeleaf as content of the template:

+
    +
  • + site_uri: + Concatenation of the configured path, the version of the project and the relative path of the page +
  • +
  • + canonical_uri: + Concatenation of the configured path and the relative path of the page +
  • +
  • + relative_uri: + Solely the relative path of the page +
  • +
+

crumbs

+

Some crumbs, that should be prepended to the breadcrumbs that are computed for the pages.

+

The crumbs have to be specified in double quotes and must be separated by commas. Example:

+
"/index.html", "/projects.html"
+

command

+

A Thymelaf-"Command", that will be included in the opening <html>-tag.

+

This command can be used to decorate the template with the designe of your website. Example:

+
th:replace="
+  ~{/templates/layout.html :: layout(
+    uri='' + ~{:: code[class='site_uri']/text()},
+    title=~{:: title},
+    maincontent=~{:: .maincontent},
+    json='MERGE:' + ~{:: pre[class='json']/text()})}"
+

+ This example uses a fragment-definition from a layout, that is defined + in a template /templates/layout.html and supplies the uri + of the page, that it selects from the site_uri and the + title and the main content of the page. +

+

+ It also uses the JSON, that reflects the structure of all pages of the + generated site, to provide the layout with additional information. + The MERGE: is a feature of + Thymeproxy, that enables you + to specify a sitemap of your website as JSON and dynamically merge + additional elements into it, that are needed by the markup-logic of the + layout to generate appropriate menu structures and breadcrumbs. +

+

A complete example

+

As example, take a look at the site descriptor of this project:

+

+<?xml version="1.0" encoding="UTF-8"?>
+<project
+    xmlns="http://maven.apache.org/DECORATION/1.1.0"
+    xlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="
+      http://maven.apache.org/DECORATION/1.1.0
+      http://maven.apache.org/xsd/decoration-1.1.0.xsd
+      "
+    name="Apache Maven Thymeleaf-Skin"
+    >
+  <skin>
+    <groupId>${project.groupId}</groupId>
+    <artifactId>${project.artifactId}</artifactId>
+    <version>${project.version}</version>
+  </skin>
+  <body>
+    <menu>
+      <item name="About" href="index.html"/>
+      <item name="Usage Examples" href="usage.html"/>
+      <item name="Project Information" href="project-info.html"/>
+    </menu>
+    <menu ref="reports"/>
+  </body>
+  <custom>
+    <thymeproxy>
+      <path>/maven-thymeleaf-skin/</path>
+      <crumbs>"/index.html","/projects.html"</crumbs>
+      <command>th:replace="~{/templates/layout.html :: layout(uri='' + ~{:: code[class='site_uri']/text()}, title=~{:: title}, maincontent=~{:: .maincontent}, json='MERGE:' + ~{:: pre[class='json']/text()})}"</command>
+    </thymeproxy>
+  </custom>
 </project>