From e0ea9aa9e4611ce6dd2c9f5ebd0b03208418e65d Mon Sep 17 00:00:00 2001 From: Kai Moritz Date: Sun, 28 Feb 2021 22:47:45 +0100 Subject: [PATCH] Added usage documentation --- src/site/xhtml/usage.xhtml | 98 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 94 insertions(+), 4 deletions(-) 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>
   
  
-- 
2.20.1