diff options
Diffstat (limited to 'docs/content/en/functions/go-template/range.md')
| -rw-r--r-- | docs/content/en/functions/go-template/range.md | 152 |
1 files changed, 96 insertions, 56 deletions
diff --git a/docs/content/en/functions/go-template/range.md b/docs/content/en/functions/go-template/range.md index cf01633b4..e8642e50b 100644 --- a/docs/content/en/functions/go-template/range.md +++ b/docs/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 |