X-Git-Url: http://juplo.de/gitweb/?a=blobdiff_plain;f=src%2Fsite%2Fxhtml%2Fusage.xhtml;h=a9c4e0c5bd1b14bc6b642aff26f2bb89cb8e44fd;hb=e0ea9aa9e4611ce6dd2c9f5ebd0b03208418e65d;hp=3c573e4c9d1879b8a0b358544699204e8c48b7b0;hpb=26697cca1a5f86bbec6f08ded69c5a800e71c3a0;p=maven-thymeleaf-skin diff --git a/src/site/xhtml/usage.xhtml b/src/site/xhtml/usage.xhtml index 3c573e4..a9c4e0c 100644 --- a/src/site/xhtml/usage.xhtml +++ b/src/site/xhtml/usage.xhtml @@ -4,7 +4,110 @@ -

Usage

TODO...

Activation

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

<project name="xxx">
+  [...]
+  <skin>
+    <groupId>${project.groupId}</groupId>
+    <artifactId>${project.artifactId}</artifactId>
+    <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>
+