diff options
Diffstat (limited to 'docs/post/goisforlovers/index.html')
| -rwxr-xr-x | docs/post/goisforlovers/index.html | 403 |
1 files changed, 403 insertions, 0 deletions
diff --git a/docs/post/goisforlovers/index.html b/docs/post/goisforlovers/index.html new file mode 100755 index 0000000..100168e --- /dev/null +++ b/docs/post/goisforlovers/index.html @@ -0,0 +1,403 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <title>(Hu)go Template Primer</title> + + <meta name="description" content=""> + + <meta itemprop="name" content="(Hu)go Template Primer"> + <meta itemprop="description" content=""> + + <meta name="twitter:card" content="summary"> + <meta name="twitter:title" content="(Hu)go Template Primer"> + <meta name="twitter:description" content=""> + + + <meta name="og:title" content="(Hu)go Template Primer"> + <meta name="og:description" content=""> + <meta name="og:type" content="website"> + <link rel="stylesheet" type="text/css" href="http://hugo.spf13.com/css/style.css"> + <script src="http://hugo.spf13.com/js/caption.js"></script> +</head> + +<body> + +<header> + <a href="http://hugo.spf13.com/">/posts</a> + + · <a href="http://hugo.spf13.com/about/" style="color:black;">/About Hugo</a> + + + +</header> +
+
+
+<div class="content">
+ <h1>(Hu)go Template Primer <aside><a href="http://hugo.spf13.com/tags/go/" class="w3-tag">/go</a> <a href="http://hugo.spf13.com/tags/golang/" class="w3-tag">/golang</a> <a href="http://hugo.spf13.com/tags/templates/" class="w3-tag">/templates</a> <a href="http://hugo.spf13.com/tags/themes/" class="w3-tag">/themes</a> <a href="http://hugo.spf13.com/tags/development/" class="w3-tag">/development</a> </aside></h1>
+ + +<p>Hugo uses the excellent <a href="http://golang.org/>">go</a> <a href="http://golang.org/pkg/html/template/>">html/template</a> library for +its template engine. It is an extremely lightweight engine that provides a very +small amount of logic. In our experience that it is just the right amount of +logic to be able to create a good static website. If you have used other +template systems from different languages or frameworks you will find a lot of +similarities in go templates.</p> + +<p>This document is a brief primer on using go templates. The <a href="http://golang.org/pkg/html/template/>">go docs</a> +provide more details.</p> + +<h2 id="introduction-to-go-templates">Introduction to Go Templates</h2> + +<p>Go templates provide an extremely simple template language. It adheres to the +belief that only the most basic of logic belongs in the template or view layer. +One consequence of this simplicity is that go templates parse very quickly.</p> + +<p>A unique characteristic of go templates is they are content aware. Variables and +content will be sanitized depending on the context of where they are used. More +details can be found in the <a href="http://golang.org/pkg/html/template/>">go docs</a>.</p> + +<h2 id="basic-syntax">Basic Syntax</h2> + +<p>Go lang templates are html files with the addition of variables and +functions.</p> + +<p><strong>Go variables and functions are accessible within {{ }}</strong></p> + +<p>Accessing a predefined variable “foo”:</p> + +<pre><code>{{ foo }} +</code></pre> + +<p><strong>Parameters are separated using spaces</strong></p> + +<p>Calling the add function with input of 1, 2:</p> + +<pre><code>{{ add 1 2 }} +</code></pre> + +<p><strong>Methods and fields are accessed via dot notation</strong></p> + +<p>Accessing the Page Parameter “bar”</p> + +<pre><code>{{ .Params.bar }} +</code></pre> + +<p><strong>Parentheses can be used to group items together</strong></p> + +<pre><code>{{ if or (isset .Params "alt") (isset .Params "caption") }} Caption {{ end }} +</code></pre> + +<h2 id="variables">Variables</h2> + +<p>Each go template has a struct (object) made available to it. In hugo each +template is passed either a page or a node struct depending on which type of +page you are rendering. More details are available on the +<a href="http://hugo.spf13.com/layout/variables">variables</a> page.</p> + +<p>A variable is accessed by referencing the variable name.</p> + +<pre><code><title>{{ .Title }}</title> +</code></pre> + +<p>Variables can also be defined and referenced.</p> + +<pre><code>{{ $address := "123 Main St."}} +{{ $address }} +</code></pre> + +<h2 id="functions">Functions</h2> + +<p>Go template ship with a few functions which provide basic functionality. The go +template system also provides a mechanism for applications to extend the +available functions with their own. <a href="http://hugo.spf13.com/layout/functions">Hugo template +functions</a> provide some additional functionality we believe +are useful for building websites. Functions are called by using their name +followed by the required parameters separated by spaces. Template +functions cannot be added without recompiling hugo.</p> + +<p><strong>Example:</strong></p> + +<pre><code>{{ add 1 2 }} +</code></pre> + +<h2 id="includes">Includes</h2> + +<p>When including another template you will pass to it the data it will be +able to access. To pass along the current context please remember to +include a trailing dot. The templates location will always be starting at +the /layout/ directory within Hugo.</p> + +<p><strong>Example:</strong></p> + +<pre><code>{{ template "chrome/header.html" . }} +</code></pre> + +<h2 id="logic">Logic</h2> + +<p>Go templates provide the most basic iteration and conditional logic.</p> + +<h3 id="iteration">Iteration</h3> + +<p>Just like in go, the go templates make heavy use of range to iterate over +a map, array or slice. The following are different examples of how to use +range.</p> + +<p><strong>Example 1: Using Context</strong></p> + +<pre><code>{{ range array }} + {{ . }} +{{ end }} +</code></pre> + +<p><strong>Example 2: Declaring value variable name</strong></p> + +<pre><code>{{range $element := array}} + {{ $element }} +{{ end }} +</code></pre> + +<p><strong>Example 2: Declaring key and value variable name</strong></p> + +<pre><code>{{range $index, $element := array}} + {{ $index }} + {{ $element }} +{{ end }} +</code></pre> + +<h3 id="conditionals">Conditionals</h3> + +<p>If, else, with, or, & and provide the framework for handling conditional +logic in Go Templates. Like range, each statement is closed with <code>end</code>.</p> + +<p>Go Templates treat the following values as false:</p> + +<ul> +<li>false</li> +<li>0</li> +<li>any array, slice, map, or string of length zero</li> +</ul> + +<p><strong>Example 1: If</strong></p> + +<pre><code>{{ if isset .Params "title" }}<h4>{{ index .Params "title" }}</h4>{{ end }} +</code></pre> + +<p><strong>Example 2: If -> Else</strong></p> + +<pre><code>{{ if isset .Params "alt" }} + {{ index .Params "alt" }} +{{else}} + {{ index .Params "caption" }} +{{ end }} +</code></pre> + +<p><strong>Example 3: And & Or</strong></p> + +<pre><code>{{ if and (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")}} +</code></pre> + +<p><strong>Example 4: With</strong></p> + +<p>An alternative way of writing “if” and then referencing the same value +is to use “with” instead. With rebinds the context <code>.</code> within its scope, +and skips the block if the variable is absent.</p> + +<p>The first example above could be simplified as:</p> + +<pre><code>{{ with .Params.title }}<h4>{{ . }}</h4>{{ end }} +</code></pre> + +<p><strong>Example 5: If -> Else If</strong></p> + +<pre><code>{{ if isset .Params "alt" }} + {{ index .Params "alt" }} +{{ else if isset .Params "caption" }} + {{ index .Params "caption" }} +{{ end }} +</code></pre> + +<h2 id="pipes">Pipes</h2> + +<p>One of the most powerful components of go templates is the ability to +stack actions one after another. This is done by using pipes. Borrowed +from unix pipes, the concept is simple, each pipeline’s output becomes the +input of the following pipe.</p> + +<p>Because of the very simple syntax of go templates, the pipe is essential +to being able to chain together function calls. One limitation of the +pipes is that they only can work with a single value and that value +becomes the last parameter of the next pipeline.</p> + +<p>A few simple examples should help convey how to use the pipe.</p> + +<p><strong>Example 1 :</strong></p> + +<pre><code>{{ if eq 1 1 }} Same {{ end }} +</code></pre> + +<p>is the same as</p> + +<pre><code>{{ eq 1 1 | if }} Same {{ end }} +</code></pre> + +<p>It does look odd to place the if at the end, but it does provide a good +illustration of how to use the pipes.</p> + +<p><strong>Example 2 :</strong></p> + +<pre><code>{{ index .Params "disqus_url" | html }} +</code></pre> + +<p>Access the page parameter called “disqus_url” and escape the HTML.</p> + +<p><strong>Example 3 :</strong></p> + +<pre><code>{{ if or (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")}} +Stuff Here +{{ end }} +</code></pre> + +<p>Could be rewritten as</p> + +<pre><code>{{ isset .Params "caption" | or isset .Params "title" | or isset .Params "attr" | if }} +Stuff Here +{{ end }} +</code></pre> + +<h2 id="context-aka-the-dot">Context (aka. the dot)</h2> + +<p>The most easily overlooked concept to understand about go templates is that {{ . }} +always refers to the current context. In the top level of your template this +will be the data set made available to it. Inside of a iteration it will have +the value of the current item. When inside of a loop the context has changed. . +will no longer refer to the data available to the entire page. If you need to +access this from within the loop you will likely want to set it to a variable +instead of depending on the context.</p> + +<p><strong>Example:</strong></p> + +<pre><code> {{ $title := .Site.Title }} + {{ range .Params.tags }} + <li> <a href="{{ $baseurl }}/tags/{{ . | urlize }}">{{ . }}</a> - {{ $title }} </li> + {{ end }} +</code></pre> + +<p>Notice how once we have entered the loop the value of {{ . }} has changed. We +have defined a variable outside of the loop so we have access to it from within +the loop.</p> + +<h1 id="hugo-parameters">Hugo Parameters</h1> + +<p>Hugo provides the option of passing values to the template language +through the site configuration (for sitewide values), or through the meta +data of each specific piece of content. You can define any values of any +type (supported by your front matter/config format) and use them however +you want to inside of your templates.</p> + +<h2 id="using-content-page-parameters">Using Content (page) Parameters</h2> + +<p>In each piece of content you can provide variables to be used by the +templates. This happens in the <a href="http://hugo.spf13.com/content/front-matter">front matter</a>.</p> + +<p>An example of this is used in this documentation site. Most of the pages +benefit from having the table of contents provided. Sometimes the TOC just +doesn’t make a lot of sense. We’ve defined a variable in our front matter +of some pages to turn off the TOC from being displayed.</p> + +<p>Here is the example front matter:</p> + +<pre><code>--- +title: "Permalinks" +date: "2013-11-18" +aliases: + - "/doc/permalinks/" +groups: ["extras"] +groups_weight: 30 +notoc: true +--- +</code></pre> + +<p>Here is the corresponding code inside of the template:</p> + +<pre><code> {{ if not .Params.notoc }} + <div id="toc" class="well col-md-4 col-sm-6"> + {{ .TableOfContents }} + </div> + {{ end }} +</code></pre> + +<h2 id="using-site-config-parameters">Using Site (config) Parameters</h2> + +<p>In your top-level configuration file (eg, <code>config.yaml</code>) you can define site +parameters, which are values which will be available to you in chrome.</p> + +<p>For instance, you might declare:</p> + +<pre><code class="language-yaml">params: + CopyrightHTML: "Copyright &#xA9; 2013 John Doe. All Rights Reserved." + TwitterUser: "spf13" + SidebarRecentLimit: 5 +</code></pre> + +<p>Within a footer layout, you might then declare a <code><footer></code> which is only +provided if the <code>CopyrightHTML</code> parameter is provided, and if it is given, +you would declare it to be HTML-safe, so that the HTML entity is not escaped +again. This would let you easily update just your top-level config file each +January 1st, instead of hunting through your templates.</p> + +<pre><code>{{if .Site.Params.CopyrightHTML}}<footer> +<div class="text-center">{{.Site.Params.CopyrightHTML | safeHtml}}</div> +</footer>{{end}} +</code></pre> + +<p>An alternative way of writing the “if” and then referencing the same value +is to use “with” instead. With rebinds the context <code>.</code> within its scope, +and skips the block if the variable is absent:</p> + +<pre><code>{{with .Site.Params.TwitterUser}}<span class="twitter"> +<a href="https://twitter.com/{{.}}" rel="author"> +<img src="/images/twitter.png" width="48" height="48" title="Twitter: {{.}}" + alt="Twitter"></a> +</span>{{end}} +</code></pre> + +<p>Finally, if you want to pull “magic constants” out of your layouts, you can do +so, such as in this example:</p> + +<pre><code><nav class="recent"> + <h1>Recent Posts</h1> + <ul>{{range first .Site.Params.SidebarRecentLimit .Site.Recent}} + <li><a href="{{.RelPermalink}}">{{.Title}}</a></li> + {{end}}</ul> +</nav> +</code></pre> +
+</div>
+
+
+
+<footer>
+ <p><small><em>Written April 2, 2014. </em>
+
+ </small></p>
+
+ <p>
+ <a href="http://hugo.spf13.com/post/hugoisforlovers/">← Getting Started with Hugo</a> <a href="http://hugo.spf13.com/post/migrate-from-jekyll/" style="float:right;">Migrate to Hugo from Jekyll →</a>
+ </p>
+
+</span>
+
+</footer>
+
+
+
+
+
+
+
+
+</body>
+</html>
|