juplo.de Git - maven-thymeleaf-skin/blob - src/site/xhtml/usage.xhtml

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   2 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   3  <head>
   4  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   5  </head>
   6  <body>
   7   <h2>Activation</h2>
   8   <p>
   9     To use this skin in your project, you have to configure the skin element of
  10     <a href="http://maven.apache.org/doxia/doxia-sitetools/doxia-decoration-model/decoration.html">the site descriptor</a>
  11     (<code>site.xml</code>):
  12   </p>
  13   <pre><code class="xml">&lt;project name="xxx"&gt;
  14   [...]
  15   &lt;skin&gt;
  16     &lt;groupId&gt;${project.groupId}&lt;/groupId&gt;
  17     &lt;artifactId&gt;${project.artifactId}&lt;/artifactId&gt;
  18     &lt;version&gt;${project.version}&lt;/version&gt;
  19   &lt;/skin&gt;
  20   [...]
  21 &lt;/project&gt;
  22   </code></pre>
  23   <h2>Configuration</h2>
  24   <p>
  25    In order to take full advantage of the generated templates, you should consider to tune the follwoing custom properties:
  26   </p>
  27   <ul>
  28   <li><strong>path</strong></li>
  29   <li><strong>prefix</strong></li>
  30   <li><strong>crumbs</strong></li>
  31   <li><strong>command</strong></li>
  32   </ul>
  33   <h3>path</h3>
  34   <p>The value of this configuration option is used to build the absolute path for the generated pages.</p>
  35   <p>The skin builds three variants of the page-uri, that are made selectable for Thymeleaf as content of the template:</p>
  36   <ul>
  37   <li>
  38     <strong>site_uri:</strong>
  39     Concatenation of the configured <code>prefix</code> and <code>path</code>, the version of the project and the relative path of the page
  40   </li>
  41   <li>
  42     <strong>canonical_uri:</strong>
  43     Concatenation of the configured <code>path</code> and the relative path of the page
  44   </li>
  45   <li>
  46     <strong>relative_uri:</strong>
  47     Solely the relative path of the page
  48   </li>
  49   </ul>
  50   <h3>prefix</h3>
  51   <p>If set, the <code>path</code> is prefixed with the value, when generating the <code>site_uri</code>.</p>
  52   <h3>crumbs</h3>
  53   <p>Some crumbs, that should be prepended to the breadcrumbs that are computed for the pages.</p>
  54   <p>The crumbs have to be specified in double quotes and must be separated by commas. Example:</p>
  55   <pre>"/index.html", "/projects.html"</pre>
  56   <h3>command</h3>
  57   <p>A Thymelaf-"Command", that will be included in the opening <code>&lt;html&gt;</code>-tag.</p>
  58   <p>This command can be used to decorate the template with the designe of your website. Example:</p>
  59   <pre>th:replace="
  60   ~{/templates/layout.html :: layout(
  61     uri='' + ~{:: code[class='site_uri']/text()},
  62     title=~{:: title},
  63     maincontent=~{:: .maincontent},
  64     json='MERGE:' + ~{:: pre[class='json']/text()})}"</pre>
  65   <p>
  66     This example uses a fragment-definition from a layout, that is defined
  67     in a template <code>/templates/layout.html</code> and supplies the uri
  68     of the page, that it selects from the <code>site_uri</code> and the
  69     title and the main content of the page.
  70   </p>
  71   <p>
  72     It also uses the JSON, that reflects the structure of all pages of the
  73     generated site, to provide the layout with additional information.
  74     The <code>MERGE:</code> is a feature of
  75     <a href="https://juplo.de/thymeproxy/">Thymeproxy</a>, that enables you
  76     to specify a sitemap of your website as JSON and dynamically merge
  77     additional elements into it, that are needed by the markup-logic of the
  78     layout to generate appropriate menu structures and breadcrumbs.
  79   </p>
  80   <h2>A complete example</h2>
  81   <p>As example, take a look at the site descriptor of this project:</p>
  82   <pre><code class="xml">
  83 &lt;?xml version="1.0" encoding="UTF-8"?&gt;
  84 &lt;project
  85     xmlns="http://maven.apache.org/DECORATION/1.1.0"
  86     xlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  87     xsi:schemaLocation="
  88       http://maven.apache.org/DECORATION/1.1.0
  89       http://maven.apache.org/xsd/decoration-1.1.0.xsd
  90       "
  91     name="Apache Maven Thymeleaf-Skin"
  92     &gt;
  93   &lt;skin&gt;
  94     &lt;groupId&gt;${project.groupId}&lt;/groupId&gt;
  95     &lt;artifactId&gt;${project.artifactId}&lt;/artifactId&gt;
  96     &lt;version&gt;${project.version}&lt;/version&gt;
  97   &lt;/skin&gt;
  98   &lt;body&gt;
  99     &lt;menu&gt;
 100       &lt;item name="About" href="index.html"/&gt;
 101       &lt;item name="Usage Examples" href="usage.html"/&gt;
 102       &lt;item name="Project Information" href="project-info.html"/&gt;
 103     &lt;/menu&gt;
 104     &lt;menu ref="reports"/&gt;
 105   &lt;/body&gt;
 106   &lt;custom&gt;
 107     &lt;thymeproxy&gt;
 108       &lt;path&gt;/maven-thymeleaf-skin/&lt;/path&gt;
 109       &lt;crumbs&gt;"/index.html","/projects.html"&lt;/crumbs&gt;
 110       &lt;command&gt;th:replace="~{/templates/layout.html :: layout(uri='' + ~{:: code[class='site_uri']/text()}, title=~{:: title}, maincontent=~{:: .maincontent}, json='MERGE:' + ~{:: pre[class='json']/text()})}"&lt;/command&gt;
 111     &lt;/thymeproxy&gt;
 112   &lt;/custom&gt;
 113 &lt;/project&gt;
 114   </code></pre>
 115  </body>
 116 </html>