diff options
Diffstat (limited to 'content/en/functions/go-template')
20 files changed, 838 insertions, 104 deletions
diff --git a/content/en/functions/go-template/_common/_index.md b/content/en/functions/go-template/_common/_index.md new file mode 100644 index 000000000..47d5812fb --- /dev/null +++ b/content/en/functions/go-template/_common/_index.md @@ -0,0 +1,13 @@ +--- +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. +--> diff --git a/content/en/functions/go-template/_common/text-template.md b/content/en/functions/go-template/_common/text-template.md new file mode 100644 index 000000000..71718c3fd --- /dev/null +++ b/content/en/functions/go-template/_common/text-template.md @@ -0,0 +1,7 @@ +--- +# Do not remove front matter. +--- + +See Go's [text/template] documentation for more information. + +[text/template]: https://pkg.go.dev/text/template diff --git a/content/en/functions/go-template/_common/truthy-falsy.md b/content/en/functions/go-template/_common/truthy-falsy.md new file mode 100644 index 000000000..c8fc9e09e --- /dev/null +++ b/content/en/functions/go-template/_common/truthy-falsy.md @@ -0,0 +1,5 @@ +--- +# 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. diff --git a/content/en/functions/go-template/_index.md b/content/en/functions/go-template/_index.md new file mode 100644 index 000000000..9075756aa --- /dev/null +++ b/content/en/functions/go-template/_index.md @@ -0,0 +1,14 @@ +--- +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 diff --git a/content/en/functions/go-template/and.md b/content/en/functions/go-template/and.md new file mode 100644 index 000000000..6bc8c60a5 --- /dev/null +++ b/content/en/functions/go-template/and.md @@ -0,0 +1,26 @@ +--- +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" %}} diff --git a/content/en/functions/go-template/block.md b/content/en/functions/go-template/block.md new file mode 100644 index 000000000..f8a082037 --- /dev/null +++ b/content/en/functions/go-template/block.md @@ -0,0 +1,55 @@ +--- +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" %}} diff --git a/content/en/functions/go-template/break.md b/content/en/functions/go-template/break.md new file mode 100644 index 000000000..14074d7c0 --- /dev/null +++ b/content/en/functions/go-template/break.md @@ -0,0 +1,33 @@ +--- +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" %}} diff --git a/content/en/functions/go-template/continue.md b/content/en/functions/go-template/continue.md new file mode 100644 index 000000000..c8030b8b7 --- /dev/null +++ b/content/en/functions/go-template/continue.md @@ -0,0 +1,34 @@ +--- +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" %}} diff --git a/content/en/functions/go-template/define.md b/content/en/functions/go-template/define.md new file mode 100644 index 000000000..4d09c14f3 --- /dev/null +++ b/content/en/functions/go-template/define.md @@ -0,0 +1,55 @@ +--- +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" %}} diff --git a/content/en/functions/go-template/else.md b/content/en/functions/go-template/else.md new file mode 100644 index 000000000..ccb8b722c --- /dev/null +++ b/content/en/functions/go-template/else.md @@ -0,0 +1,69 @@ +--- +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 diff --git a/content/en/functions/go-template/end.md b/content/en/functions/go-template/end.md new file mode 100644 index 000000000..07d004de5 --- /dev/null +++ b/content/en/functions/go-template/end.md @@ -0,0 +1,65 @@ +--- +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 diff --git a/content/en/functions/go-template/if.md b/content/en/functions/go-template/if.md new file mode 100644 index 000000000..e63c382e1 --- /dev/null +++ b/content/en/functions/go-template/if.md @@ -0,0 +1,54 @@ +--- +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 diff --git a/content/en/functions/go-template/len.md b/content/en/functions/go-template/len.md index b8be621e8..43f150a5f 100644 --- a/content/en/functions/go-template/len.md +++ b/content/en/functions/go-template/len.md @@ -1,26 +1,20 @@ --- title: len description: Returns the length of a string, slice, map, or collection. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/strings/Count + - functions/strings/CountRunes + - functions/strings/CountWords + - functions/strings/RuneCount returnType: int - signatures: [len INPUT] -relatedFunctions: - - len - - strings.Count - - strings.CountRunes - - strings.CountWords - - strings.RuneCount + signatures: [len VALUE] aliases: [/functions/len] --- -{{% readfile file="/functions/_common/go-template-functions.md" %}} - With a string: ```go-html-template @@ -53,3 +47,5 @@ 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" %}} diff --git a/content/en/functions/go-template/not.md b/content/en/functions/go-template/not.md new file mode 100644 index 000000000..4c7747c7b --- /dev/null +++ b/content/en/functions/go-template/not.md @@ -0,0 +1,35 @@ +--- +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" %}} diff --git a/content/en/functions/go-template/or.md b/content/en/functions/go-template/or.md new file mode 100644 index 000000000..0d8619608 --- /dev/null +++ b/content/en/functions/go-template/or.md @@ -0,0 +1,26 @@ +--- +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" %}} diff --git a/content/en/functions/go-template/range.md b/content/en/functions/go-template/range.md index cf01633b4..e8642e50b 100644 --- a/content/en/functions/go-template/range.md +++ b/content/en/functions/go-template/range.md @@ -1,36 +1,95 @@ --- title: range -description: Iterates over slices, maps, and page collections. -categories: [functions] +description: Iterates over a non-empty collection, binds context (the dot) to successive elements, and executes the block. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/go-template/break + - functions/go-template/continue + - functions/go-template/else + - functions/go-template/end returnType: signatures: [range COLLECTION] -relatedFunctions: - - with - - range aliases: [/functions/range] toc: true --- -{{% readfile file="/functions/_common/go-template-functions.md" %}} +{{% include "functions/go-template/_common/truthy-falsy.md" %}} -## Slices +```go-html-template +{{ $s := slice "foo" "bar" "baz" }} +{{ range $var }} + {{ . }} → foo bar baz +{{ end }} +``` -Template: +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 }} ``` -Result: +{{% 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> @@ -38,7 +97,7 @@ Result: <p>baz</p> ``` -Template: +This template code: ```go-html-template {{ $s := slice "foo" "bar" "baz" }} @@ -47,7 +106,7 @@ Template: {{ end }} ``` -Result: +Is rendered to: ```html <p>foo</p> @@ -55,7 +114,7 @@ Result: <p>baz</p> ``` -Template: +This template code: ```go-html-template {{ $s := slice "foo" "bar" "baz" }} @@ -64,7 +123,7 @@ Template: {{ end }} ``` -Result: +Is rendered to: ```html <p>0: foo</p> @@ -72,9 +131,9 @@ Result: <p>2: baz</p> ``` -## Maps +## Array or slice of maps -Template: +This template code: ```go-html-template {{ $m := slice @@ -87,7 +146,7 @@ Template: {{ end }} ``` -Result: +Is rendered to: ```html <p>John is 30</p> @@ -95,9 +154,9 @@ Result: <p>Joey is 24</p> ``` -## Page collections +## Array or slice of pages -Template: +This template code: ```go-html-template {{ range where site.RegularPages "Type" "articles" }} @@ -105,7 +164,7 @@ Template: {{ end }} ``` -Result: +Is rendered to: ```html <h2><a href="/articles/article-3/">Article 3</a></h2> @@ -113,47 +172,28 @@ Result: <h2><a href="/articles/article-1/">Article 1</a></h2> ``` -## Break - -Use the `break` statement to stop the innermost iteration and bypass all remaining iterations. +## Maps -Template: +This template code: ```go-html-template -{{ $s := slice "foo" "bar" "baz" }} -{{ range $s }} - {{ if eq . "bar" }} - {{ break }} - {{ end }} - <p>{{ . }}</p> +{{ $m := dict "name" "John" "age" 30 }} +{{ range $k, $v := $m }} + <p>key = {{ $k }} value = {{ $v }}</p> {{ end }} ``` -Result: - -```html -<p>foo</p> -``` - -## Continue - -Use the `continue` statement to stop the innermost iteration and continue to the next iteration. - -Template: +Is rendered to: ```go-html-template -{{ $s := slice "foo" "bar" "baz" }} -{{ range $s }} - {{ if eq . "bar" }} - {{ continue }} - {{ end }} - <p>{{ . }}</p> -{{ end }} +<p>key = age value = 30</p> +<p>key = name value = John</p> ``` -Result: +Unlike ranging over an array or slice, Hugo sorts by key when ranging over a map. -```html -<p>foo</p> -<p>baz</p> -``` +{{% include "functions/go-template/_common/text-template.md" %}} + +[`else`]: /functions/go-template/else +[`break`]: /functions/go-template/break +[`continue`]: /functions/go-template/continue diff --git a/content/en/functions/go-template/return.md b/content/en/functions/go-template/return.md new file mode 100644 index 000000000..2a166c718 --- /dev/null +++ b/content/en/functions/go-template/return.md @@ -0,0 +1,110 @@ +--- +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 >}} diff --git a/content/en/functions/go-template/template.md b/content/en/functions/go-template/template.md new file mode 100644 index 000000000..a78ec5c65 --- /dev/null +++ b/content/en/functions/go-template/template.md @@ -0,0 +1,49 @@ +--- +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 diff --git a/content/en/functions/go-template/urlquery.md b/content/en/functions/go-template/urlquery.md index cbbfdfa7d..946828f56 100644 --- a/content/en/functions/go-template/urlquery.md +++ b/content/en/functions/go-template/urlquery.md @@ -1,23 +1,17 @@ --- 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: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] + related: + - functions/collections/Querify returnType: string - signatures: ['urlquery INPUT [INPUT]...'] -relatedFunctions: - - collections.Querify - - urlquery + signatures: ['urlquery VALUE [VALUE...]'] aliases: [/functions/urlquery] --- -{{% readfile file="/functions/_common/go-template-functions.md" %}} - This template code: ```go-html-template @@ -30,3 +24,5 @@ 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" %}} diff --git a/content/en/functions/go-template/with.md b/content/en/functions/go-template/with.md index 06ca38150..197181953 100644 --- a/content/en/functions/go-template/with.md +++ b/content/en/functions/go-template/with.md @@ -1,35 +1,87 @@ --- title: with -description: Rebinds the context (`.`) within its scope and skips the block if the variable is absent or empty. -categories: [functions] +description: Binds context (the dot) to the expression and executes the block if expression is truthy. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] - returnType: any - signatures: [with PIPELINE] -relatedFunctions: - - with - - range + 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 --- -{{% readfile file="/functions/_common/go-template-functions.md" %}} +{{% include "functions/go-template/_common/truthy-falsy.md" %}} -An alternative way of writing an `if` statement and then referencing the same value is to use `with` instead. `with` rebinds the context (`.`) within its scope and skips the block if the variable is absent, unset or empty. +```go-html-template +{{ $var := "foo" }} +{{ with $var }} + {{ . }} → foo +{{ end }} +``` -The set of *empty* values is defined by [the Go templates package](https://golang.org/pkg/text/template/). Empty values include `false`, the number zero, and the empty string. +Use with the [`else`] statement: -If you want to render a block if an index or key is present in a slice, array, channel or map, regardless of whether the value is empty, you should use [`isset`](/functions/collections/isset) instead. +```go-html-template +{{ $var := "foo" }} +{{ with $var }} + {{ . }} → foo +{{ else }} + {{ print "var is falsy" }} +{{ end }} +``` -The following example checks for a [user-defined site variable](/variables/site/) called `twitteruser`. If the key-value is not set, the following will render nothing: +Intialize a variable, scoped to the current block: -{{< code file="layouts/partials/twitter.html" >}} -{{ 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 >}} +```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 |