mirror of
https://github.com/gohugoio/hugo.git
synced 2025-08-21 21:35:28 +02:00
Bjørn Erik Pedersen
@@ -1,13 +0,0 @@
|
||||
---
|
||||
cascade:
|
||||
_build:
|
||||
list: never
|
||||
publishResources: false
|
||||
render: never
|
||||
---
|
||||
|
||||
<!--
|
||||
Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
|
||||
Include the rendered content using the "include" shortcode.
|
||||
-->
|
||||
@@ -1,7 +0,0 @@
|
||||
---
|
||||
# Do not remove front matter.
|
||||
---
|
||||
|
||||
See Go's [text/template] documentation for more information.
|
||||
|
||||
[text/template]: https://pkg.go.dev/text/template
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
# Do not remove front matter.
|
||||
---
|
||||
|
||||
In Go templates, the falsy values are `false`, `0`, any nil pointer or interface value, and any array, slice, map, or string of length zero. Everything else is truthy.
|
||||
@@ -1,14 +0,0 @@
|
||||
---
|
||||
title: Go template functions, operators, and statements
|
||||
linkTitle: go template
|
||||
description: Template functions, operators, and statements provided by Go's text/template package.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: functions
|
||||
---
|
||||
|
||||
These are the functions, operators, and statements provided by Go's [text/template] package.
|
||||
|
||||
[text/template]: https://pkg.go.dev/text/template
|
||||
@@ -1,26 +0,0 @@
|
||||
---
|
||||
title: and
|
||||
description: Returns the first falsy argument. If all arguments are truthy, returns the last argument.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: []
|
||||
related:
|
||||
- functions/go-template/not
|
||||
- functions/go-template/or
|
||||
returnType: any
|
||||
signatures: [and VALUE...]
|
||||
---
|
||||
|
||||
{{% include "functions/go-template/_common/truthy-falsy.md" %}}
|
||||
|
||||
```go-html-template
|
||||
{{ and 1 0 "" }} → 0 (int)
|
||||
{{ and 1 false 0 }} → false (bool)
|
||||
|
||||
{{ and 1 2 3 }} → 3 (int)
|
||||
{{ and "a" "b" "c" }} → c (string)
|
||||
{{ and "a" 1 true }} → true (bool)
|
||||
```
|
||||
|
||||
{{% include "functions/go-template/_common/text-template.md" %}}
|
||||
@@ -1,55 +0,0 @@
|
||||
---
|
||||
title: block
|
||||
description: Defines a template and executes it in place.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: []
|
||||
related:
|
||||
- functions/go-template/define
|
||||
- functions/go-template/end
|
||||
returnType:
|
||||
signatures: [block NAME CONTEXT]
|
||||
---
|
||||
|
||||
A block is shorthand for defining a template:
|
||||
|
||||
```go-html-template
|
||||
{{ define "name" }} T1 {{ end }}
|
||||
```
|
||||
|
||||
and then executing it in place:
|
||||
|
||||
```go-html-template
|
||||
{{ template "name" pipeline }}
|
||||
```
|
||||
The typical use is to define a set of root templates that are then customized by redefining the block templates within.
|
||||
|
||||
{{< code file=layouts/_default/baseof.html >}}
|
||||
<body>
|
||||
<main>
|
||||
{{ block "main" . }}
|
||||
{{ print "default value if 'main' template is empty" }}
|
||||
{{ end }}
|
||||
</main>
|
||||
</body>
|
||||
{{< /code >}}
|
||||
|
||||
{{< code file=layouts/_default/single.html >}}
|
||||
{{ define "main" }}
|
||||
<h1>{{ .Title }}</h1>
|
||||
{{ .Content }}
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
{{< code file=layouts/_default/list.html >}}
|
||||
{{ define "main" }}
|
||||
<h1>{{ .Title }}</h1>
|
||||
{{ .Content }}
|
||||
{{ range .Pages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
{{% include "functions/go-template/_common/text-template.md" %}}
|
||||
@@ -1,33 +0,0 @@
|
||||
---
|
||||
title: break
|
||||
description: Used with the range statement, stops the innermost iteration and bypasses all remaining iterations.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: []
|
||||
related:
|
||||
- functions/go-template/continue
|
||||
- functions/go-template/range
|
||||
returnType:
|
||||
signatures: [break]
|
||||
---
|
||||
|
||||
This template code:
|
||||
|
||||
```go-html-template
|
||||
{{ $s := slice "foo" "bar" "baz" }}
|
||||
{{ range $s }}
|
||||
{{ if eq . "bar" }}
|
||||
{{ break }}
|
||||
{{ end }}
|
||||
<p>{{ . }}</p>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Is rendered to:
|
||||
|
||||
```html
|
||||
<p>foo</p>
|
||||
```
|
||||
|
||||
{{% include "functions/go-template/_common/text-template.md" %}}
|
||||
@@ -1,34 +0,0 @@
|
||||
---
|
||||
title: continue
|
||||
description: Used with the range statement, stops the innermost iteration and continues to the next iteration.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: []
|
||||
related:
|
||||
- functions/go-template/break
|
||||
- functions/go-template/range
|
||||
returnType:
|
||||
signatures: [continue]
|
||||
---
|
||||
|
||||
This template code:
|
||||
|
||||
```go-html-template
|
||||
{{ $s := slice "foo" "bar" "baz" }}
|
||||
{{ range $s }}
|
||||
{{ if eq . "bar" }}
|
||||
{{ continue }}
|
||||
{{ end }}
|
||||
<p>{{ . }}</p>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Is rendered to:
|
||||
|
||||
```html
|
||||
<p>foo</p>
|
||||
<p>baz</p>
|
||||
```
|
||||
|
||||
{{% include "functions/go-template/_common/text-template.md" %}}
|
||||
@@ -1,55 +0,0 @@
|
||||
---
|
||||
title: define
|
||||
description: Defines a template.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: []
|
||||
related:
|
||||
- functions/go-template/block
|
||||
- functions/go-template/end
|
||||
- functions/go-template/template
|
||||
- functions/partials/Include
|
||||
- functions/partials/IncludeCached
|
||||
returnType:
|
||||
signatures: [define NAME]
|
||||
---
|
||||
|
||||
Use with the [`block`] statement:
|
||||
|
||||
```go-html-template
|
||||
{{ block "main" . }}
|
||||
{{ print "default value if 'main' template is empty" }}
|
||||
{{ end }}
|
||||
|
||||
{{ define "main" }}
|
||||
<h1>{{ .Title }}</h1>
|
||||
{{ .Content }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Use with the [`partial`] function:
|
||||
|
||||
```go-html-template
|
||||
{{ partial "inline/foo.html" (dict "answer" 42) }}
|
||||
|
||||
{{ define "partials/inline/foo.html" }}
|
||||
{{ printf "The answer is %v." .answer }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Use with the [`template`] function:
|
||||
|
||||
```go-html-template
|
||||
{{ template "foo" (dict "answer" 42) }}
|
||||
|
||||
{{ define "foo" }}
|
||||
{{ printf "The answer is %v." .answer }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
[`block`]: /functions/go-template/block
|
||||
[`template`]: /functions/go-template/block
|
||||
[`partial`]: /functions/partials/include/
|
||||
|
||||
{{% include "functions/go-template/_common/text-template.md" %}}
|
||||
@@ -1,69 +0,0 @@
|
||||
---
|
||||
title: else
|
||||
description: Begins an alternate block for if, with, and range statements.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: []
|
||||
related:
|
||||
- functions/go-template/if
|
||||
- functions/go-template/range
|
||||
- functions/go-template/with
|
||||
- functions/go-template/end
|
||||
returnType:
|
||||
signatures: [else VALUE]
|
||||
---
|
||||
|
||||
Use with the [`if`] statement:
|
||||
|
||||
```go-html-template
|
||||
{{ $var := "foo" }}
|
||||
{{ if $var }}
|
||||
{{ $var }} → foo
|
||||
{{ else }}
|
||||
{{ print "var is falsy" }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Use with the [`with`] statement:
|
||||
|
||||
```go-html-template
|
||||
{{ $var := "foo" }}
|
||||
{{ with $var }}
|
||||
{{ . }} → foo
|
||||
{{ else }}
|
||||
{{ print "var is falsy" }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Use with the [`range`] statement:
|
||||
|
||||
```go-html-template
|
||||
{{ $var := slice 1 2 3 }}
|
||||
{{ range $var }}
|
||||
{{ . }} → 1 2 3
|
||||
{{ else }}
|
||||
{{ print "var is falsy" }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Use `else if` to check multiple conditions.
|
||||
|
||||
```go-html-template
|
||||
{{ $var := 12 }}
|
||||
{{ if eq $var 6 }}
|
||||
{{ print "var is 6" }}
|
||||
{{ else if eq $var 7 }}
|
||||
{{ print "var is 7" }}
|
||||
{{ else if eq $var 42 }}
|
||||
{{ print "var is 42" }}
|
||||
{{ else }}
|
||||
{{ print "var is something else" }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
{{% include "functions/go-template/_common/text-template.md" %}}
|
||||
|
||||
[`if`]: /functions/go-template/if
|
||||
[`with`]: /functions/go-template/with
|
||||
[`range`]: /functions/go-template/range
|
||||
@@ -1,65 +0,0 @@
|
||||
---
|
||||
title: end
|
||||
description: Terminates if, with, range, block, and define statements.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: []
|
||||
related:
|
||||
- functions/go-template/block
|
||||
- functions/go-template/define
|
||||
- functions/go-template/if
|
||||
- functions/go-template/range
|
||||
- functions/go-template/with
|
||||
returnType:
|
||||
signatures: [end]
|
||||
---
|
||||
|
||||
Use with the [`if`] statement:
|
||||
|
||||
```go-html-template
|
||||
{{ $var := "foo" }}
|
||||
{{ if $var }}
|
||||
{{ $var }} → foo
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Use with the [`with`] statement:
|
||||
|
||||
```go-html-template
|
||||
{{ $var := "foo" }}
|
||||
{{ with $var }}
|
||||
{{ . }} → foo
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Use with the [`range`] statement:
|
||||
|
||||
```go-html-template
|
||||
{{ $var := slice 1 2 3 }}
|
||||
{{ range $var }}
|
||||
{{ . }} → 1 2 3
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Use with the [`block`] statement:
|
||||
|
||||
```go-html-template
|
||||
{{ block "main" . }}{{ end }}
|
||||
```
|
||||
|
||||
Use with the [`define`] statement:
|
||||
|
||||
```go-html-template
|
||||
{{ define "main" }}
|
||||
{{ print "this is the main section" }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
{{% include "functions/go-template/_common/text-template.md" %}}
|
||||
|
||||
[`block`]: /functions/go-template/block
|
||||
[`define`]: /functions/go-template/define
|
||||
[`if`]: /functions/go-template/if
|
||||
[`range`]: /functions/go-template/range
|
||||
[`with`]: /functions/go-template/with
|
||||
@@ -1,54 +0,0 @@
|
||||
---
|
||||
title: if
|
||||
description: Executes the block if the expression is truthy.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: []
|
||||
related:
|
||||
- functions/go-template/with
|
||||
- functions/go-template/else
|
||||
- functions/go-template/end
|
||||
- functions/collections/IsSet
|
||||
returnType:
|
||||
signatures: [if EXPR]
|
||||
---
|
||||
|
||||
{{% include "functions/go-template/_common/truthy-falsy.md" %}}
|
||||
|
||||
```go-html-template
|
||||
{{ $var := "foo" }}
|
||||
{{ if $var }}
|
||||
{{ $var }} → foo
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Use with the [`else`] statement:
|
||||
|
||||
```go-html-template
|
||||
{{ $var := "foo" }}
|
||||
{{ if $var }}
|
||||
{{ $var }} → foo
|
||||
{{ else }}
|
||||
{{ print "var is falsy" }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Use `else if` to check multiple conditions.
|
||||
|
||||
```go-html-template
|
||||
{{ $var := 12 }}
|
||||
{{ if eq $var 6 }}
|
||||
{{ print "var is 6" }}
|
||||
{{ else if eq $var 7 }}
|
||||
{{ print "var is 7" }}
|
||||
{{ else if eq $var 42 }}
|
||||
{{ print "var is 42" }}
|
||||
{{ else }}
|
||||
{{ print "var is something else" }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
{{% include "functions/go-template/_common/text-template.md" %}}
|
||||
|
||||
[`else`]: /functions/go-template/else
|
||||
@@ -1,51 +0,0 @@
|
||||
---
|
||||
title: len
|
||||
description: Returns the length of a string, slice, map, or collection.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: []
|
||||
related:
|
||||
- functions/strings/Count
|
||||
- functions/strings/CountRunes
|
||||
- functions/strings/CountWords
|
||||
- functions/strings/RuneCount
|
||||
returnType: int
|
||||
signatures: [len VALUE]
|
||||
aliases: [/functions/len]
|
||||
---
|
||||
|
||||
With a string:
|
||||
|
||||
```go-html-template
|
||||
{{ "ab" | len }} → 2
|
||||
{{ "" | len }} → 0
|
||||
```
|
||||
|
||||
With a slice:
|
||||
|
||||
```go-html-template
|
||||
{{ slice "a" "b" | len }} → 2
|
||||
{{ slice | len }} → 0
|
||||
```
|
||||
|
||||
With a map:
|
||||
|
||||
```go-html-template
|
||||
{{ dict "a" 1 "b" 2 | len }} → 2
|
||||
{{ dict | len }} → 0
|
||||
```
|
||||
|
||||
With a collection:
|
||||
|
||||
```go-html-template
|
||||
{{ site.RegularPages | len }} → 42
|
||||
```
|
||||
|
||||
You may also determine the number of pages in a collection with:
|
||||
|
||||
```go-html-template
|
||||
{{ site.RegularPages.Len }} → 42
|
||||
```
|
||||
|
||||
{{% include "functions/go-template/_common/text-template.md" %}}
|
||||
@@ -1,35 +0,0 @@
|
||||
---
|
||||
title: not
|
||||
description: Returns the boolean negation of its single argument.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: []
|
||||
related:
|
||||
- functions/go-template/and
|
||||
- functions/go-template/or
|
||||
returnType: bool
|
||||
signatures: [not VALUE]
|
||||
---
|
||||
|
||||
Unlike the `and` and `or` operators, the `not` operator always returns a boolean value.
|
||||
|
||||
```go-html-template
|
||||
{{ not true }} → false
|
||||
{{ not false }} → true
|
||||
|
||||
{{ not 1 }} → false
|
||||
{{ not 0 }} → true
|
||||
|
||||
{{ not "x" }} → false
|
||||
{{ not "" }} → true
|
||||
```
|
||||
|
||||
Use the `not` operator, twice in succession, to cast any value to a boolean value. For example:
|
||||
|
||||
```go-html-template
|
||||
{{ 42 | not | not }} → true
|
||||
{{ "" | not | not }} → false
|
||||
```
|
||||
|
||||
{{% include "functions/go-template/_common/text-template.md" %}}
|
||||
@@ -1,26 +0,0 @@
|
||||
---
|
||||
title: or
|
||||
description: Returns the first truthy argument. If all arguments are falsy, returns the last argument.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: []
|
||||
related:
|
||||
- functions/go-template/and
|
||||
- functions/go-template/not
|
||||
returnType: any
|
||||
signatures: [or VALUE...]
|
||||
---
|
||||
|
||||
{{% include "functions/go-template/_common/truthy-falsy.md" %}}
|
||||
|
||||
```go-html-template
|
||||
{{ or 0 1 2 }} → 1
|
||||
{{ or false "a" 1 }} → a
|
||||
{{ or 0 true "a" }} → true
|
||||
|
||||
{{ or false "" 0 }} → 0
|
||||
{{ or 0 "" false }} → false
|
||||
```
|
||||
|
||||
{{% include "functions/go-template/_common/text-template.md" %}}
|
||||
@@ -1,199 +0,0 @@
|
||||
---
|
||||
title: range
|
||||
description: Iterates over a non-empty collection, binds context (the dot) to successive elements, and executes the block.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: []
|
||||
related:
|
||||
- functions/go-template/break
|
||||
- functions/go-template/continue
|
||||
- functions/go-template/else
|
||||
- functions/go-template/end
|
||||
returnType:
|
||||
signatures: [range COLLECTION]
|
||||
aliases: [/functions/range]
|
||||
toc: true
|
||||
---
|
||||
|
||||
{{% include "functions/go-template/_common/truthy-falsy.md" %}}
|
||||
|
||||
```go-html-template
|
||||
{{ $s := slice "foo" "bar" "baz" }}
|
||||
{{ range $s }}
|
||||
{{ . }} → foo bar baz
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Use with the [`else`] statement:
|
||||
|
||||
```go-html-template
|
||||
{{ $s := slice "foo" "bar" "baz" }}
|
||||
{{ range $s }}
|
||||
<p>{{ . }}</p>
|
||||
{{ else }}
|
||||
<p>The collection is empty</p>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Within a range block:
|
||||
|
||||
- Use the [`continue`] statement to stop the innermost iteration and continue to the next iteration
|
||||
- Use the [`break`] statement to stop the innermost iteration and bypass all remaining iterations
|
||||
|
||||
## Understanding context
|
||||
|
||||
At the top of a page template, the [context] (the dot) is a `Page` object. Within the `range` block, the context is bound to each successive element.
|
||||
|
||||
With this contrived example that uses the [`seq`] function to generate a slice of integers:
|
||||
|
||||
```go-html-template
|
||||
{{ range seq 3 }}
|
||||
{{ .Title }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Hugo will throw an error:
|
||||
|
||||
can't evaluate field Title in type int
|
||||
|
||||
The error occurs because we are trying to use the `.Title` method on an integer instead of a `Page` object. Within the `range` block, if we want to render the page title, we need to get the context passed into the template.
|
||||
|
||||
{{% note %}}
|
||||
Use the `$` to get the context passed into the template.
|
||||
{{% /note %}}
|
||||
|
||||
This template will render the page title three times:
|
||||
|
||||
```go-html-template
|
||||
{{ range seq 3 }}
|
||||
{{ $.Title }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
Gaining a thorough understanding of context is critical for anyone writing template code.
|
||||
{{% /note %}}
|
||||
|
||||
[`seq`]: functions/collections/seq/
|
||||
[context]: /getting-started/glossary/#context
|
||||
|
||||
## Array or slice of scalars
|
||||
|
||||
This template code:
|
||||
|
||||
```go-html-template
|
||||
{{ $s := slice "foo" "bar" "baz" }}
|
||||
{{ range $s }}
|
||||
<p>{{ . }}</p>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Is rendered to:
|
||||
|
||||
```html
|
||||
<p>foo</p>
|
||||
<p>bar</p>
|
||||
<p>baz</p>
|
||||
```
|
||||
|
||||
This template code:
|
||||
|
||||
```go-html-template
|
||||
{{ $s := slice "foo" "bar" "baz" }}
|
||||
{{ range $v := $s }}
|
||||
<p>{{ $v }}</p>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Is rendered to:
|
||||
|
||||
```html
|
||||
<p>foo</p>
|
||||
<p>bar</p>
|
||||
<p>baz</p>
|
||||
```
|
||||
|
||||
This template code:
|
||||
|
||||
```go-html-template
|
||||
{{ $s := slice "foo" "bar" "baz" }}
|
||||
{{ range $k, $v := $s }}
|
||||
<p>{{ $k }}: {{ $v }}</p>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Is rendered to:
|
||||
|
||||
```html
|
||||
<p>0: foo</p>
|
||||
<p>1: bar</p>
|
||||
<p>2: baz</p>
|
||||
```
|
||||
|
||||
## Array or slice of maps
|
||||
|
||||
This template code:
|
||||
|
||||
```go-html-template
|
||||
{{ $m := slice
|
||||
(dict "name" "John" "age" 30)
|
||||
(dict "name" "Will" "age" 28)
|
||||
(dict "name" "Joey" "age" 24)
|
||||
}}
|
||||
{{ range $m }}
|
||||
<p>{{ .name }} is {{ .age }}</p>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Is rendered to:
|
||||
|
||||
```html
|
||||
<p>John is 30</p>
|
||||
<p>Will is 28</p>
|
||||
<p>Joey is 24</p>
|
||||
```
|
||||
|
||||
## Array or slice of pages
|
||||
|
||||
This template code:
|
||||
|
||||
```go-html-template
|
||||
{{ range where site.RegularPages "Type" "articles" }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Is rendered to:
|
||||
|
||||
```html
|
||||
<h2><a href="/articles/article-3/">Article 3</a></h2>
|
||||
<h2><a href="/articles/article-2/">Article 2</a></h2>
|
||||
<h2><a href="/articles/article-1/">Article 1</a></h2>
|
||||
```
|
||||
|
||||
## Maps
|
||||
|
||||
This template code:
|
||||
|
||||
```go-html-template
|
||||
{{ $m := dict "name" "John" "age" 30 }}
|
||||
{{ range $k, $v := $m }}
|
||||
<p>key = {{ $k }} value = {{ $v }}</p>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Is rendered to:
|
||||
|
||||
```go-html-template
|
||||
<p>key = age value = 30</p>
|
||||
<p>key = name value = John</p>
|
||||
```
|
||||
|
||||
Unlike ranging over an array or slice, Hugo sorts by key when ranging over a map.
|
||||
|
||||
{{% include "functions/go-template/_common/text-template.md" %}}
|
||||
|
||||
[`else`]: /functions/go-template/else
|
||||
[`break`]: /functions/go-template/break
|
||||
[`continue`]: /functions/go-template/continue
|
||||
@@ -1,110 +0,0 @@
|
||||
---
|
||||
title: return
|
||||
description: Used within partial templates, terminates template execution and returns the given value, if any.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: []
|
||||
related:
|
||||
- functions/partials/Include
|
||||
- functions/partials/IncludeCached
|
||||
returnType: any
|
||||
signatures: ['return [VALUE]']
|
||||
toc: true
|
||||
---
|
||||
|
||||
The `return` statement is a custom addition to Go's [text/template] package. Used within partial templates, the `return` statement terminates template execution and returns the given value, if any.
|
||||
|
||||
The returned value may be of any data type including, but not limited to, [`bool`], [`float`], [`int`], [`map`], [`resource`], [`slice`], and [`string`].
|
||||
|
||||
A `return` statement without a value returns an empty string of type `template.HTML`.
|
||||
|
||||
[`bool`]: /getting-started/glossary/#bool
|
||||
[`float`]: /getting-started/glossary/#float
|
||||
[`int`]: /getting-started/glossary/#int
|
||||
[`map`]: /getting-started/glossary/#map
|
||||
[`resource`]: /getting-started/glossary/#resource
|
||||
[`slice`]: /getting-started/glossary/#slice
|
||||
[`string`]: /getting-started/glossary/#string
|
||||
[text/template]: https://pkg.go.dev/text/template
|
||||
|
||||
{{% note %}}
|
||||
Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks. See [usage](#usage) notes below.
|
||||
{{% /note %}}
|
||||
|
||||
## Example
|
||||
|
||||
By way of example, let's create a partial template that _renders_ HTML, describing whether the given number is odd or even:
|
||||
|
||||
{{< code file="layouts/partials/odd-or-even.html" >}}
|
||||
{{ if math.ModBool . 2 }}
|
||||
<p>{{ . }} is even</p>
|
||||
{{ else }}
|
||||
<p>{{ . }} is odd</p>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
When called, the partial renders HTML:
|
||||
|
||||
```go-html-template
|
||||
{{ partial "odd-or-even.html" 42 }} → <p>42 is even</p>
|
||||
```
|
||||
|
||||
Instead of rendering HTML, let's create a partial that _returns_ a boolean value, reporting whether the given number is even:
|
||||
|
||||
{{< code file="layouts/partials/is-even.html" >}}
|
||||
{{ return math.ModBool . 2 }}
|
||||
{{< /code >}}
|
||||
|
||||
With this template:
|
||||
|
||||
```go-html-template
|
||||
{{ $number := 42 }}
|
||||
{{ if partial "is-even.html" $number }}
|
||||
<p>{{ $number }} is even</p>
|
||||
{{ else }}
|
||||
<p>{{ $number }} is odd</p>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Hugo renders:
|
||||
|
||||
```html
|
||||
<p>42 is even</p>
|
||||
```
|
||||
|
||||
See additional examples in the [partial templates] section.
|
||||
|
||||
[partial templates]: /templates/partials/#returning-a-value-from-a-partial
|
||||
|
||||
## Usage
|
||||
|
||||
{{% note %}}
|
||||
Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks
|
||||
{{% /note %}}
|
||||
|
||||
A partial that returns a value must contain only one `return` statement, placed at the end of the template.
|
||||
|
||||
For example:
|
||||
|
||||
{{< code file="layouts/partials/is-even.html" >}}
|
||||
{{ $result := false }}
|
||||
{{ if math.ModBool . 2 }}
|
||||
{{ $result = "even" }}
|
||||
{{ else }}
|
||||
{{ $result = "odd" }}
|
||||
{{ end }}
|
||||
{{ return $result }}
|
||||
{{< /code >}}
|
||||
|
||||
{{% note %}}
|
||||
The construct below is incorrect; it contains more than one `return` statement.
|
||||
{{% /note %}}
|
||||
|
||||
{{< code file="layouts/partials/do-not-do-this.html" >}}
|
||||
{{ if math.ModBool . 2 }}
|
||||
{{ return "even" }}
|
||||
{{ else }}
|
||||
{{ return "odd" }}
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
@@ -1,49 +0,0 @@
|
||||
---
|
||||
title: template
|
||||
description: Executes the given template, optionally passing context.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: []
|
||||
related:
|
||||
- functions/go-template/define
|
||||
- functions/partials/Include
|
||||
- functions/partials/IncludeCached
|
||||
returnType:
|
||||
signatures: ['template NAME [CONTEXT]']
|
||||
---
|
||||
|
||||
Use the `template` function to execute [internal templates]. For example:
|
||||
|
||||
```go-html-template
|
||||
{{ range (.Paginate .Pages).Pages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
{{ template "_internal/pagination.html" . }}
|
||||
```
|
||||
|
||||
You can also use the `template` function to execute a defined template:
|
||||
|
||||
```go-html-template
|
||||
{{ template "foo" (dict "answer" 42) }}
|
||||
|
||||
{{ define "foo" }}
|
||||
{{ printf "The answer is %v." .answer }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
The example above can be rewritten using an [inline partial] template:
|
||||
|
||||
```go-html-template
|
||||
{{ partial "inline/foo.html" (dict "answer" 42) }}
|
||||
|
||||
{{ define "partials/inline/foo.html" }}
|
||||
{{ printf "The answer is %v." .answer }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
{{% include "functions/go-template/_common/text-template.md" %}}
|
||||
|
||||
[`partial`]: /functions/partials/include/
|
||||
[inline partial]: /templates/partials/#inline-partials
|
||||
[internal templates]: /templates/internal
|
||||
@@ -1,28 +0,0 @@
|
||||
---
|
||||
title: urlquery
|
||||
description: Returns the escaped value of the textual representation of its arguments in a form suitable for embedding in a URL query.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: []
|
||||
related:
|
||||
- functions/collections/Querify
|
||||
returnType: string
|
||||
signatures: ['urlquery VALUE [VALUE...]']
|
||||
aliases: [/functions/urlquery]
|
||||
---
|
||||
|
||||
This template code:
|
||||
|
||||
```go-html-template
|
||||
{{ $u := urlquery "https://" "example.com" | safeURL }}
|
||||
<a href="https://example.org?url={{ $u }}">Link</a>
|
||||
```
|
||||
|
||||
Is rendered to:
|
||||
|
||||
```html
|
||||
<a href="https://example.org?url=https%3A%2F%2Fexample.com">Link</a>
|
||||
```
|
||||
|
||||
{{% include "functions/go-template/_common/text-template.md" %}}
|
||||
@@ -1,87 +0,0 @@
|
||||
---
|
||||
title: with
|
||||
description: Binds context (the dot) to the expression and executes the block if expression is truthy.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: []
|
||||
related:
|
||||
- functions/go-template/if
|
||||
- functions/go-template/else
|
||||
- functions/go-template/end
|
||||
- functions/collections/IsSet
|
||||
returnType:
|
||||
signatures: [with EXPR]
|
||||
aliases: [/functions/with]
|
||||
toc: true
|
||||
---
|
||||
|
||||
{{% include "functions/go-template/_common/truthy-falsy.md" %}}
|
||||
|
||||
```go-html-template
|
||||
{{ $var := "foo" }}
|
||||
{{ with $var }}
|
||||
{{ . }} → foo
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Use with the [`else`] statement:
|
||||
|
||||
```go-html-template
|
||||
{{ $var := "foo" }}
|
||||
{{ with $var }}
|
||||
{{ . }} → foo
|
||||
{{ else }}
|
||||
{{ print "var is falsy" }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Initialize a variable, scoped to the current block:
|
||||
|
||||
```go-html-template
|
||||
{{ with $var := 42 }}
|
||||
{{ . }} → 42
|
||||
{{ $var }} → 42
|
||||
{{ end }}
|
||||
{{ $var }} → undefined
|
||||
```
|
||||
|
||||
## Understanding context
|
||||
|
||||
At the top of a page template, the [context] (the dot) is a `Page` object. Inside of the `with` block, the context is bound to the value passed to the `with` statement.
|
||||
|
||||
With this contrived example:
|
||||
|
||||
```go-html-template
|
||||
{{ with 42 }}
|
||||
{{ .Title }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Hugo will throw an error:
|
||||
|
||||
can't evaluate field Title in type int
|
||||
|
||||
The error occurs because we are trying to use the `.Title` method on an integer instead of a `Page` object. Inside of the `with` block, if we want to render the page title, we need to get the context passed into the template.
|
||||
|
||||
{{% note %}}
|
||||
Use the `$` to get the context passed into the template.
|
||||
{{% /note %}}
|
||||
|
||||
This template will render the page title as desired:
|
||||
|
||||
```go-html-template
|
||||
{{ with 42 }}
|
||||
{{ $.Title }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
Gaining a thorough understanding of context is critical for anyone writing template code.
|
||||
{{% /note %}}
|
||||
|
||||
[context]: /getting-started/glossary/#context
|
||||
|
||||
{{% include "functions/go-template/_common/text-template.md" %}}
|
||||
|
||||
[`else`]: /functions/go-template/else
|
||||
Reference in New Issue
Block a user