lektor-website/docs/templates/index.html

380 lines
15 KiB
HTML

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<link rel="stylesheet" href="../../static/styles.css?h=dff0aaad">
<link rel="stylesheet" href="../../static/pygments.css">
<link rel="shortcut icon" href="../../static/favicon.png?h=fa09bedd">
<title>Templates | Documentation | Lektor Static Content Management System</title>
</head>
<body class="default">
<nav class="navbar navbar-inverse navbar-static-top">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle collapsed"
data-toggle="collapse" data-target="#navbar"
aria-expanded="false" aria-controls="navbar">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="../../">Lektor</a>
</div>
<div id="navbar" class="collapse navbar-collapse">
<ul class="nav navbar-nav">
<li><a href="../../downloads/">Download</a></li>
<li class="active"><a href="../">Documentation</a></li>
<li><a href="../../showcase/">Showcase</a></li>
<li><a href="../../plugins/">Plugins</a></li>
<li><a href="../../community/">Community</a></li>
<li><a href="../../blog/">Blog</a></li>
</ul>
</div>
</div>
</nav>
<div class="body-wrapper">
<div class="container">
<div class="row">
<div class="col-sm-3">
<ul class="tree-nav nocontent">
<li><a href="../">Welcome</a></li>
<li><a href="../what/">What is Lektor</a>
<li><a href="../installation/">Installation</a>
<li><a href="../quickstart/">Quickstart</a>
<li><a href="../project/">Project</a>
<li><a href="../content/">Content</a>
<li class="active"><a href="./">Templates</a>
<ul>
<li><a href="urls/">URLs and Links</a>
<li><a href="navigation/">Navigation</a>
<li><a href="imageops/">Image Operations</a>
<li><a href="videoops/">Video Operations</a>
</ul>
<li><a href="../themes/">Themes</a>
<li><a href="../guides/">Guides</a>
<li><a href="../deployment/">Deployment</a>
<li><a href="../plugins/">Plugins</a>
<li><a href="../models/">Data Modelling</a>
<li><a href="../cli/">Command Line</a>
<li><a href="../api/">API</a>
<li><a href="../search/">Search</a>
</ul>
<div class="visible-md-block visible-lg-block">
<h4>This Page</h4>
<ul class="toc">
<li><a href="#template-folder-and-naming">Template Folder and Naming</a></li>
<li><a href="#template-context">Template Context</a></li>
<li><a href="#the-first-template">The First Template</a></li>
<li><a href="#layout-templates">Layout Templates</a></li>
<li><a href="#everything-about-templates">Everything about Templates</a></li>
</ul>
</div>
</div>
<div class="col-sm-9 doc-styling">
<h1>Templates</h1>
<ul class=page-meta>
</ul>
<p>Lektor uses the <a href="http://jinja.pocoo.org/" class="ext">Jinja2</a> templating language for
generating HTML out of your pages. You do not need to understand Jinja2 to
be able to generate beautiful websites but if you want to dive deep into the
powers of the templating language then you can learn more about it by
reading the <a href="http://jinja.pocoo.org/docs" class="ext">Jinja2 Documentation</a>.</p>
<div class="admonition admonition-info"><p>Templates are a very powerful component in Lektor. A lot of documentation
about the features of it can be found in the <a href="http://jinja.pocoo.org/docs" class="ext">Jinja2 Documentation</a> as well as the <a href="../api/templates/" class="ext">Lektor Template API
Documentation</a>.</p></div><h2 id="template-folder-and-naming">Template Folder and Naming</h2><p>All templates are stored within the <code>templates/</code> folder. Templates typically
carry a <code>.html</code> extension. The default naming convention which is used in
Lektor is that the template name matches the model name.</p>
<p>So if you have a model called <code>page</code> there would be a template named
<code>page.html</code>. Pages can however manually force a different template to be
rendered.</p>
<h2 id="template-context">Template Context</h2><p>When a template is rendered it's rendered in the context of a few variables.
Which ones are available often depends on the situation the template is
evaluated in but the following are always available:</p>
<table>
<thead><tr>
<th>Variable</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>this</code></td>
<td>The current <a href="../api/db/record/" class="ref">Record</a> that is being rendered.</td>
</tr>
<tr>
<td><code>site</code></td>
<td>The database <a href="../api/db/pad/" class="ref">Pad</a> that can be used to query the site.</td>
</tr>
<tr>
<td><code>alt</code></td>
<td>A string that identifies the <a href="../content/alts/" class="ref">Alternative</a> of the page.</td>
</tr>
<tr>
<td><code>config</code></td>
<td>Gives access to the Lektor project configuration.</td>
</tr>
</tbody>
</table>
<h2 id="the-first-template">The First Template</h2><p>So let's dive in making our first template. In case you went through the
<a href="../quickstart/" class="ref">Quickstart</a> you should already have an example model
to work with called <code>page</code>, otherwise just add one with the format shown
in the <a href="../models/" class="ref">Data Modelling Documentation</a>.</p>
<p>With that we can create a page template named <code>templates/page.html</code>:</p>
<div class="hll"><pre><span></span><span class="cp">{%</span> <span class="k">extends</span> <span class="s2">&quot;layout.html&quot;</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">block</span> <span class="nv">title</span> <span class="cp">%}{{</span> <span class="nv">this.title</span> <span class="cp">}}{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">block</span> <span class="nv">body</span> <span class="cp">%}</span>
<span class="p">&lt;</span><span class="nt">h2</span><span class="p">&gt;</span><span class="cp">{{</span> <span class="nv">this.title</span> <span class="cp">}}</span><span class="p">&lt;/</span><span class="nt">h2</span><span class="p">&gt;</span>
<span class="cp">{{</span> <span class="nv">this.body</span> <span class="cp">}}</span>
<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
</pre></div>
<p>If you are unfamiliar with Jinja this template might look very confusing, but
worry not. We will go through it step by step.</p>
<ul>
<li><code>{%</code> starts a Jinja section and <code>%}</code> ends it</li>
<li><code>extends</code> is a tag that instructs Jinja to extend another template. In
this case we extend our layout template. We will create this next.</li>
<li><code>block</code> creates or updates a block from the layout template. In this case
we have two blocks: one for the <code>title</code> of the page and another one for
the <code>body</code>.</li>
<li><code>{{</code> prints a variable and <code>}}</code> is the end of the print part. We do not
need to worry about escaping here as Jinja2 does that automatically for
us.</li>
</ul>
<h2 id="layout-templates">Layout Templates</h2><p>So we have this page template now, but what about this layout? Jinja2
supports template inheritance where one template can inherit code from
another. In this case we configured our page template to inherit from
<code>layout.html</code>. Let's create it:</p>
<div class="hll"><pre><span></span><span class="cp">&lt;!doctype html&gt;</span>
<span class="p">&lt;</span><span class="nt">meta</span> <span class="na">charset</span><span class="o">=</span><span class="s">&quot;utf-8&quot;</span><span class="p">&gt;</span>
<span class="p">&lt;</span><span class="nt">title</span><span class="p">&gt;</span><span class="cp">{%</span> <span class="k">block</span> <span class="nv">title</span> <span class="cp">%}</span>Welcome<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span> — My Website<span class="p">&lt;/</span><span class="nt">title</span><span class="p">&gt;</span>
<span class="p">&lt;</span><span class="nt">body</span><span class="p">&gt;</span>
<span class="p">&lt;</span><span class="nt">header</span><span class="p">&gt;</span>
<span class="p">&lt;</span><span class="nt">h1</span><span class="p">&gt;</span>My Website<span class="p">&lt;/</span><span class="nt">h1</span><span class="p">&gt;</span>
<span class="p">&lt;</span><span class="nt">nav</span><span class="p">&gt;</span>
Navigation can go here.
<span class="p">&lt;/</span><span class="nt">nav</span><span class="p">&gt;</span>
<span class="p">&lt;/</span><span class="nt">header</span><span class="p">&gt;</span>
<span class="p">&lt;</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;page&quot;</span><span class="p">&gt;</span>
<span class="cp">{%</span> <span class="k">block</span> <span class="nv">body</span> <span class="cp">%}{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
<span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>
<span class="p">&lt;/</span><span class="nt">body</span><span class="p">&gt;</span>
</pre></div>
<p>I hope you can see how the blocks work together now when template inheritance
is involved.</p>
<h2 id="everything-about-templates">Everything about Templates</h2><p>Templates are the bread and butter of creating expressive websites with
Lektor. As such this is one of the most complex topics in the documentation
and split into smaller parts. Feel free to experiment around to see what
you can do with it.</p>
<div class="child-pages nocontent">
<div class="row">
<div class="col-md-6 child">
<h4>
<i class="glyphicon glyphicon-list-alt"></i>
<a href="urls/">URLs and Links</a>
</h4>
<p class="summary">Explains how to manage URLs and links in templates.</p>
</div>
<div class="col-md-6 child">
<h4>
<i class="glyphicon glyphicon-list-alt"></i>
<a href="navigation/">Navigation</a>
</h4>
<p class="summary">Shows how to create a dynamic navigation with Lektor.</p>
</div>
</div>
<div class="row">
<div class="col-md-6 child">
<h4>
<i class="glyphicon glyphicon-list-alt"></i>
<a href="imageops/">Image Operations</a>
</h4>
<p class="summary">Shows how templates can work with images.</p>
</div>
<div class="col-md-6 child">
<h4>
<i class="glyphicon glyphicon-list-alt"></i>
<a href="videoops/">Video Operations</a>
</h4>
<p class="summary">Shows how templates can work with videos</p>
</div>
</div>
</div>
<div class="comment-box">
<h2>Comments</h2>
<div id="disqus_thread"></div>
<script>
var disqus_config = function() { this.page.identifier = "/docs/templates"; this.page.url = "https://www.getlektor.com/docs/templates/"; };
(function() {
var d = document, s = d.createElement('script');
s.src = '//lektordocumentation.disqus.com/embed.js';
s.setAttribute('data-timestamp', +new Date());
(d.head || d.body).appendChild(s);
})();
</script>
<noscript>
Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript"
rel="nofollow">comments powered by Disqus.</a>
</noscript>
</div>
</div>
</div>
</div>
</div>
<div class="bottomsummary">
<div class="container">
</div>
</div>
<footer>
<div class="container">
<div class="row">
<div class="col-sm-4 icon-bar">
<a href="https://github.com/lektor/lektor/" title="Lektor on GitHub"
><i class="fa fa-github"></i></a>
<a href="https://github.com/lektor/lektor/issues/" title="Report Issues for Lektor"
><i class="fa fa-bug"></i></a>
<a href="https://twitter.com/getlektor" title="Find Lektor on Twitter"
><i class="fa fa-twitter"></i></a>
<a href="https://gitter.im/lektor/lektor" title="Chat on Gitter"
><i class="fa fa-comment"></i></a>
<a href="https://github.com/lektor/lektor-website/tree/master/content/docs/templates/contents.lr" title="View source for this page"><i class="fa fa-code"></i></a>
</div>
<div class="col-sm-8">
<a href="../../license/">License & Copyright</a>
<a href="../../contact/">Contact</a>
Made with <i class="fa fa-fw fa-heart" title="Heart"><span hidden>Heart</span></i> in Carinthia
</div>
</div>
</div>
</footer>
<script type=text/javascript src="../../static/app.js?h=8b801996" charset="utf-8"></script>
<script>
((window.gitter = {}).chat = {}).options = {
room: 'lektor/lektor',
activationElement: null
};
document.write('<button class="js-gitter-toggle-chat-button">Toggle Chat</button>');
var dnt = navigator.doNotTrack || window.doNotTrack || navigator.msDoNotTrack;
if (dnt != "1" && dnt != "yes") {
window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;
ga('create', 'UA-70822533-1', 'auto');
ga('set', 'anonymizeIp', true);
ga('send', 'pageview');
} else {
console.debug("Respecting Do-Not-Track, not running analytics.");
}
</script>
<script async src='https://www.google-analytics.com/analytics.js'></script>
<script async defer id="github-bjs" src="https://buttons.github.io/buttons.js"></script>
<script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script>
<script src="https://sidecar.gitter.im/dist/sidecar.v1.js" async defer></script>
</body>
</html>