documon
Version:
A documentation system for mortals. Use with any language.
148 lines (124 loc) • 5.48 kB
HTML
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Templates</title>
<meta name="description" content="more.templates">
<!-- Normalize -->
<link rel="stylesheet" href="assets/vendor/normalize.css">
<!-- prettify -->
<link rel="stylesheet" href="assets/vendor/prettify/codamike.css">
<script src="assets/vendor/prettify/prettify.js"></script>
<!-- Documon Pages Info. (Used by various classes to identify this page.) -->
<script>
var pageCtx = {
id : "more.templates",
name: "Templates"
}
</script>
<!-- theme
<link rel="stylesheet" href="assets/fonts/Fira_Sans/FiraSans.css">
<link rel="stylesheet" href="assets/fonts/Inconsolata/inconsolata.css">
-->
<link rel="stylesheet" href="assets/css/pages.css">
<script src="assets/js/documon/Storage.js"></script>
<script src="assets/js/documon/Access.js"></script>
<script src="assets/js/documon/Pages.js"></script>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-106684927-1', 'auto');
ga('send', 'pageview');
</script>
</head>
<body>
<div class="page">
<div class="more"><h1 id="templates">Templates</h1>
<p>The templating system is wide open, giving you full control over how the HTML is rendered. By default we're using straight javascript with template literals for patching together chunks of HTML.</p>
<p>To create or modify a template, you'll only have to ensure:</p>
<ul>
<li>The "Required Files" exist.</li>
<li>All "jst" template files return a string.</li>
</ul>
<h3 id="required-files">Required Files</h3>
<p>The following files are called directly by Documon and must exist within the template folder.</p>
<table>
<thead>
<tr>
<th id="file">file</th>
<th id="description">description</th>
<th id="arguments">arguments</th>
<th id="used_by">used by</th>
</tr>
</thead>
<tbody>
<tr>
<td>_config.js</td>
<td>Configures the "assets" folder (see below).</td>
<td></td>
<td><a href="documon.documon">documon.js</a></td>
</tr>
<tr>
<td>index.jst</td>
<td>The main "app" page.</td>
<td>context</td>
<td><a href="documon.documon">documon.js</a></td>
</tr>
<tr>
<td>indexShortcut.jst</td>
<td>Shortcut to the home page.</td>
<td>context</td>
<td><a href="documon.documon">documon.js</a></td>
</tr>
<tr>
<td>page.jst</td>
<td>Standard wrapper template for all pages.</td>
<td>context, content</td>
<td><a href="documon.documon">documon.js</a></td>
</tr>
<tr>
<td>package.jst</td>
<td>An index page that lists a package's members.</td>
<td>context</td>
<td><a href="documon.organizer">organizer.js</a></td>
</tr>
<tr>
<td>class.jst</td>
<td>This contains class description, Methods, Properties and Events (MPE).</td>
<td><a href="documon.organizer">organizer.js</a></td>
<td></td>
</tr>
</tbody>
</table>
<p>Each template (jst) must return a single function that accepts a "context" argument and returns a string.</p>
<p>Example:</p>
<pre><code>module.exports = function (ctx){
return "<html><body>${ctx.id}</body></html>";
};</code></pre>
<p>The argument provided is a simple object structure containing page data.</p>
<p>The "page.jst" file receives a second argument "content", which is the main textual body content for the page that was formerly rendered by either <strong>index, package</strong> or <strong>class</strong> JST template.</p>
<p>To review the structured data, run Documon with teh <a href="more.options">"dumpData" option</a> enabled -- the "tagged" javascript files show the json-like structure, which you can use as a reference.</p>
<h3 id="the-_configsjs-file">The _configs.js file</h3>
<p>The "_config.js" file is essentially a central configuration "object" that documon reads for template specific options and can also be used by the template developer to store global options/settings.</p>
<p>The _config.js file should export the following:</p>
<pre><code>module.exports = {
assetsFolder : "assets"
}</code></pre>
<p>Documon only reads the "assetsFolder" property, all other properties in the "exports" object are not used by Documon, but can be used by templates as needed, so you're free to load up the object as you see fit.</p>
<p>The "assetsFolder" is the name of a folder in the templates folder that contains all the required assets such as javascript, css, images, etc. -- This entire folder will get copied over "as is" (including sub-folders) to the resulting web site that Documon generates.</p>
<p>For example, if the template folder structure looks like:</p>
<pre><code>/path/to/template
/path/to/template/myAssets</code></pre>
<p>… and you need the "myAssets" folder to wind up in the resulting website, you'll set the "assetsFolder" property in "_config.js" as:</p>
<pre><code>module.exports = {
assetsFolder : "myAssets"
}</code></pre>
<p>… then the "myAssets" folder will get copied into the final doumentation as:</p>
<pre><code>/docs/myAssets</code></pre></div>
</div>
<div class="footer">Generated by <a href="http://www.documon.net" target="_blank">Documon</a></div>
</body>
</html>