mirror/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-08-20 21:31:32 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge commit '35dec7c96f7ee3eb17dd444f7067f0c776fb56ae'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2023-12-04 15:24:01 +01:00
parent 9f978d387f 35dec7c96f
commit d19ed4d4e6
810 changed files with 24147 additions and 7766 deletions
Download Patch File Download Diff File Expand all files Collapse all files

152
docs/content/en/functions/go-template/range.md
View File

@@ -1,27 +1,86 @@
---
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 }}
```
{{% 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" }}
@@ -30,7 +89,7 @@ Template:
{{ end }}
```
Result:
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
## Maps
Use the `break` statement to stop the innermost iteration and bypass all remaining iterations.
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