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>crumbs</strong></li>
  30   <li><strong>command</strong></li>
  31   </ul>
  32   <h3>path</h3>
  33   <p>The value of this configuration option is used to build the absolute path for the generated pages.</p>
  34   <p>The skin builds three variants of the page-uri, that are made selectable for Thymeleaf as content of the template:</p>
  35   <ul>
  36   <li>
  37     <strong>site_uri:</strong>
  38     Concatenation of the configured <code>path</code>, the version of the project and the relative path of the page
  39   </li>
  40   <li>
  41     <strong>canonical_uri:</strong>
  42     Concatenation of the configured <code>path</code> and the relative path of the page
  43   </li>
  44   <li>
  45     <strong>relative_uri:</strong>
  46     Solely the relative path of the page
  47   </li>
  48   </ul>
  49   <h3>crumbs</h3>
  50   <p>Some crumbs, that should be prepended to the breadcrumbs that are computed for the pages.</p>
  51   <p>The crumbs have to be specified in double quotes and must be separated by commas. Example:</p>
  52   <pre>"/index.html", "/projects.html"</pre>
  53   <h3>command</h3>
  54   <p>A Thymelaf-"Command", that will be included in the opening <code>&lt;html&gt;</code>-tag.</p>
  55   <p>This command can be used to decorate the template with the designe of your website. Example:</p>
  56   <pre>th:replace="
  57   ~{/templates/layout.html :: layout(
  58     uri='' + ~{:: code[class='site_uri']/text()},
  59     title=~{:: title},
  60     maincontent=~{:: .maincontent},
  61     json='MERGE:' + ~{:: pre[class='json']/text()})}"</pre>
  62   <p>
  63     This example uses a fragment-definition from a layout, that is defined
  64     in a template <code>/templates/layout.html</code> and supplies the uri
  65     of the page, that it selects from the <code>site_uri</code> and the
  66     title and the main content of the page.
  67   </p>
  68   <p>
  69     It also uses the JSON, that reflects the structure of all pages of the
  70     generated site, to provide the layout with additional information.
  71     The <code>MERGE:</code> is a feature of
  72     <a href="https://juplo.de/thymeproxy/">Thymeproxy</a>, that enables you
  73     to specify a sitemap of your website as JSON and dynamically merge
  74     additional elements into it, that are needed by the markup-logic of the
  75     layout to generate appropriate menu structures and breadcrumbs.
  76   </p>
  77   <h2>A complete example</h2>
  78   <p>As example, take a look at the site descriptor of this project:</p>
  79   <pre><code class="xml">
  80 &lt;?xml version="1.0" encoding="UTF-8"?&gt;
  81 &lt;project
  82     xmlns="http://maven.apache.org/DECORATION/1.1.0"
  83     xlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  84     xsi:schemaLocation="
  85       http://maven.apache.org/DECORATION/1.1.0
  86       http://maven.apache.org/xsd/decoration-1.1.0.xsd
  87       "
  88     name="Apache Maven Thymeleaf-Skin"
  89     &gt;
  90   &lt;skin&gt;
  91     &lt;groupId&gt;${project.groupId}&lt;/groupId&gt;
  92     &lt;artifactId&gt;${project.artifactId}&lt;/artifactId&gt;
  93     &lt;version&gt;${project.version}&lt;/version&gt;
  94   &lt;/skin&gt;
  95   &lt;body&gt;
  96     &lt;menu&gt;
  97       &lt;item name="About" href="index.html"/&gt;
  98       &lt;item name="Usage Examples" href="usage.html"/&gt;
  99       &lt;item name="Project Information" href="project-info.html"/&gt;
 100     &lt;/menu&gt;
 101     &lt;menu ref="reports"/&gt;
 102   &lt;/body&gt;
 103   &lt;custom&gt;
 104     &lt;thymeproxy&gt;
 105       &lt;path&gt;/maven-thymeleaf-skin/&lt;/path&gt;
 106       &lt;crumbs&gt;"/index.html","/projects.html"&lt;/crumbs&gt;
 107       &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;
 108     &lt;/thymeproxy&gt;
 109   &lt;/custom&gt;
 110 &lt;/project&gt;
 111   </code></pre>
 112  </body>
 113 </html>