mirror of
https://github.com/gohugoio/hugo.git
synced 2025-08-21 21:35:28 +02:00
Merge commit '8b9803425e63e1b1801f8d5d676e96368d706722'
This commit is contained in:
Bjørn Erik Pedersen
@@ -65,7 +65,7 @@ You can use `after` in combination with the [`first`] function and Hugo's [power
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
[`first`]: /functions/collections/first
|
||||
[list/section page]: /templates/section-templates
|
||||
[`first`]: /functions/collections/first/
|
||||
[list/section page]: /templates/section-templates/
|
||||
[lists]: /templates/lists/#sort-content
|
||||
[`slice`]: /functions/collections/slice/
|
||||
|
||||
@@ -58,7 +58,7 @@ To list everything except blog articles (`blog`) and frequently asked questions
|
||||
{{% note %}}
|
||||
Although the example above demonstrates the `complement` function, you could use the [`where`] function as well:
|
||||
|
||||
[`where`]: /functions/collections/where
|
||||
[`where`]: /functions/collections/where/
|
||||
{{% /note %}}
|
||||
|
||||
```go-html-template
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: collections.Dictionary
|
||||
description: Creates a map from a list of key and value pairs.
|
||||
description: Returns a map composed of the given key-value pairs.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
@@ -8,10 +8,12 @@ action:
|
||||
related:
|
||||
- functions/collections/Slice
|
||||
returnType: mapany
|
||||
signatures: ['collections.Dictionary KEY VALUE [VALUE...]']
|
||||
signatures: ['collections.Dictionary [VALUE...]']
|
||||
aliases: [/functions/dict]
|
||||
---
|
||||
|
||||
Specify the key-value pairs as individual arguments:
|
||||
|
||||
```go-html-template
|
||||
{{ $m := dict "a" 1 "b" 2 }}
|
||||
```
|
||||
@@ -25,6 +27,12 @@ The above produces this data structure:
|
||||
}
|
||||
```
|
||||
|
||||
To create an empty map:
|
||||
|
||||
```go-html-template
|
||||
{{ $m := dict }}
|
||||
```
|
||||
|
||||
|
||||
Note that the `key` can be either a `string` or a `string slice`. The latter is useful to create a deeply nested structure, e.g.:
|
||||
|
||||
@@ -43,26 +51,3 @@ The above produces this data structure:
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Pass values to a partial template
|
||||
|
||||
The partial below creates an SVG and expects `fill`, `height` and `width` from the caller:
|
||||
|
||||
### Partial definition
|
||||
|
||||
{{< code file=layouts/partials/svgs/external-links.svg >}}
|
||||
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
fill="{{ .fill }}" width="{{ .width }}" height="{{ .height }}" viewBox="0 0 32 32" aria-label="External Link">
|
||||
<path d="M25.152 16.576v5.696q0 2.144-1.504 3.648t-3.648 1.504h-14.848q-2.144 0-3.648-1.504t-1.504-3.648v-14.848q0-2.112 1.504-3.616t3.648-1.536h12.576q0.224 0 0.384 0.16t0.16 0.416v1.152q0 0.256-0.16 0.416t-0.384 0.16h-12.576q-1.184 0-2.016 0.832t-0.864 2.016v14.848q0 1.184 0.864 2.016t2.016 0.864h14.848q1.184 0 2.016-0.864t0.832-2.016v-5.696q0-0.256 0.16-0.416t0.416-0.16h1.152q0.256 0 0.416 0.16t0.16 0.416zM32 1.152v9.12q0 0.48-0.352 0.8t-0.8 0.352-0.8-0.352l-3.136-3.136-11.648 11.648q-0.16 0.192-0.416 0.192t-0.384-0.192l-2.048-2.048q-0.192-0.16-0.192-0.384t0.192-0.416l11.648-11.648-3.136-3.136q-0.352-0.352-0.352-0.8t0.352-0.8 0.8-0.352h9.12q0.48 0 0.8 0.352t0.352 0.8z"></path>
|
||||
</svg>
|
||||
{{< /code >}}
|
||||
|
||||
### Partial call
|
||||
|
||||
The `fill`, `height` and `width` values can be stored in one object with `dict` and passed to the partial:
|
||||
|
||||
{{< code file=layouts/_default/list.html >}}
|
||||
{{ partial "svgs/external-links.svg" (dict "fill" "#01589B" "width" 10 "height" 20 ) }}
|
||||
{{< /code >}}
|
||||
|
||||
[partials]: /templates/partials/
|
||||
|
||||
@@ -34,4 +34,4 @@ Use `first` and [`where`] together.
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
[`where`]: /functions/collections/where
|
||||
[`where`]: /functions/collections/where/
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: collections.Index
|
||||
description: Looks up the index(es) or key(s) of the data structure passed into it.
|
||||
description: Returns the object, element, or value associated with the given key or keys.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
@@ -8,88 +8,44 @@ action:
|
||||
related: []
|
||||
returnType: any
|
||||
signatures:
|
||||
- collections.Index COLLECTION INDEXES
|
||||
- collections.Index COLLECTION KEYS
|
||||
- collections.Index COLLECTION KEY...
|
||||
aliases: [/functions/index,/functions/index-function]
|
||||
---
|
||||
|
||||
The `index` functions returns the result of indexing its first argument by the following arguments. Each indexed item must be a map or a slice, e.g.:
|
||||
Each indexed item must be a map or a slice:
|
||||
|
||||
```go-html-template
|
||||
{{ $slice := slice "a" "b" "c" }}
|
||||
{{ index $slice 0 }} → a
|
||||
{{ index $slice 1 }} → b
|
||||
{{ $s := slice "a" "b" "c" }}
|
||||
{{ index $s 0 }} → a
|
||||
{{ index $s 1 }} → b
|
||||
|
||||
{{ $map := dict "a" 100 "b" 200 }}
|
||||
{{ index $map "b" }} → 200
|
||||
{{ $m := dict "a" 100 "b" 200 }}
|
||||
{{ index $m "b" }} → 200
|
||||
```
|
||||
|
||||
The function takes multiple indices as arguments, and this can be used to get nested values, e.g.:
|
||||
Use two or more keys to access a nested value:
|
||||
|
||||
```go-html-template
|
||||
{{ $map := dict "a" 100 "b" 200 "c" (slice 10 20 30) }}
|
||||
{{ index $map "c" 1 }} → 20
|
||||
{{ $map := dict "a" 100 "b" 200 "c" (dict "d" 10 "e" 20) }}
|
||||
{{ index $map "c" "e" }} → 20
|
||||
{{ $m := dict "a" 100 "b" 200 "c" (slice 10 20 30) }}
|
||||
{{ index $m "c" 1 }} → 20
|
||||
|
||||
{{ $m := dict "a" 100 "b" 200 "c" (dict "d" 10 "e" 20) }}
|
||||
{{ index $m "c" "e" }} → 20
|
||||
```
|
||||
|
||||
You may write multiple indices as a slice:
|
||||
You may also use a slice of keys to access a nested value:
|
||||
|
||||
```go-html-template
|
||||
{{ $map := dict "a" 100 "b" 200 "c" (dict "d" 10 "e" 20) }}
|
||||
{{ $slice := slice "c" "e" }}
|
||||
{{ index $map $slice }} → 20
|
||||
{{ $m := dict "a" 100 "b" 200 "c" (dict "d" 10 "e" 20) }}
|
||||
{{ $s := slice "c" "e" }}
|
||||
{{ index $m $s }} → 20
|
||||
```
|
||||
|
||||
## Example: load data from a path based on front matter parameters
|
||||
|
||||
Assume you want to add a `location = ""` field to your front matter for every article written in `content/vacations/`. You want to use this field to populate information about the location at the bottom of the article in your `single.html` template. You also have a directory in `data/locations/` that looks like the following:
|
||||
|
||||
```text
|
||||
data/
|
||||
└── locations/
|
||||
├── abilene.toml
|
||||
├── chicago.toml
|
||||
├── oslo.toml
|
||||
└── provo.toml
|
||||
```
|
||||
|
||||
Here is an example:
|
||||
|
||||
{{< code-toggle file=data/locations/oslo >}}
|
||||
website = "https://www.oslo.kommune.no"
|
||||
pop_city = 658390
|
||||
pop_metro = 1717900
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The example we will use will be an article on Oslo, whose front matter should be set to exactly the same name as the corresponding file name in `data/locations/`:
|
||||
|
||||
{{< code-toggle file=content/articles/oslo.md fm=true >}}
|
||||
title = "My Norwegian Vacation"
|
||||
location = "oslo"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The content of `oslo.toml` can be accessed from your template using the following node path: `.Site.Data.locations.oslo`. However, the specific file you need is going to change according to the front matter.
|
||||
|
||||
This is where the `index` function is needed. `index` takes 2 arguments in this use case:
|
||||
|
||||
1. The node path
|
||||
2. A string corresponding to the desired data; e.g.—
|
||||
Use the `collections.Index` function to access a nested value when the key is variable. For example, these are equivalent:
|
||||
|
||||
```go-html-template
|
||||
{{ index .Site.Data.locations "oslo" }}
|
||||
```
|
||||
|
||||
The variable for `.Params.location` is a string and can therefore replace `oslo` in the example above:
|
||||
|
||||
```go-html-template
|
||||
{{ index .Site.Data.locations .Params.location }}
|
||||
=> map[website:https://www.oslo.kommune.no pop_city:658390 pop_metro:1717900]
|
||||
```
|
||||
|
||||
Now the call will return the specific file according to the location specified in the content's front matter, but you will likely want to write specific properties to the template. You can do this by continuing down the node path via dot notation (`.`):
|
||||
|
||||
```go-html-template
|
||||
{{ (index .Site.Data.locations .Params.location).pop_city }}
|
||||
=> 658390
|
||||
{{ .Site.Params.foo }}
|
||||
|
||||
{{ $k := "foo" }}
|
||||
{{ index .Site.Params $k }}
|
||||
```
|
||||
|
||||
@@ -8,13 +8,13 @@ action:
|
||||
related:
|
||||
- methods/pages/Related
|
||||
returnType: types.KeyValues
|
||||
signatures: [collections.KeyVals KEY VALUES...]
|
||||
signatures: [collections.KeyVals KEY VALUE...]
|
||||
aliases: [/functions/keyvals]
|
||||
---
|
||||
|
||||
The primary application for this function is the definition of the `namedSlices` parameter in the options map passed to the [`Related`] method on the `Pages` object.
|
||||
The primary application for this function is the definition of the `namedSlices` value in the options map passed to the [`Related`] method on the `Pages` object.
|
||||
|
||||
[`Related`]: /methods/pages/related
|
||||
[`Related`]: /methods/pages/related/
|
||||
|
||||
See [related content](/content-management/related).
|
||||
|
||||
|
||||
@@ -15,8 +15,8 @@ action:
|
||||
|
||||
The `collections.NewScratch` function creates a locally scoped [scratch pad] to store and manipulate data. To create a scratch pad that is attached to a `Page` object, use the [`Scratch`] or [`Store`] method.
|
||||
|
||||
[`Scratch`]: /methods/page/scratch
|
||||
[`Store`]: /methods/page/store
|
||||
[`Scratch`]: /methods/page/scratch/
|
||||
[`Store`]: /methods/page/store/
|
||||
[scratch pad]: /getting-started/glossary/#scratch-pad
|
||||
|
||||
## Methods
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: collections.Querify
|
||||
description: Takes a set or slice of key-value pairs and returns a query string to be appended to URLs.
|
||||
description: Returns a URL query string composed of the given key-value pairs.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
@@ -9,24 +9,29 @@ action:
|
||||
- functions/go-template/urlquery.md
|
||||
returnType: string
|
||||
signatures:
|
||||
- collections.Querify VALUE [VALUE...]
|
||||
- collections.Querify COLLECTION
|
||||
- collections.Querify [VALUE...]
|
||||
aliases: [/functions/querify]
|
||||
---
|
||||
|
||||
`querify` takes a set or slice of key-value pairs and returns a [query string](https://en.wikipedia.org/wiki/Query_string) that can be appended to a URL.
|
||||
Specify the key-value pairs as individual arguments, or as a slice. The following are equivalent:
|
||||
|
||||
The following examples create a link to a search results page on Google.
|
||||
|
||||
```go-html-template
|
||||
<a href="https://www.google.com?{{ (querify "q" "test" "page" 3) | safeURL }}">Search</a>
|
||||
|
||||
{{ $qs := slice "q" "test" "page" 3 }}
|
||||
<a href="https://www.google.com?{{ (querify $qs) | safeURL }}">Search</a>
|
||||
{{ collections.Querify "a" 1 "b" 2 }}
|
||||
{{ collections.Querify (slice "a" 1 "b" 2) }}
|
||||
```
|
||||
|
||||
Both of these examples render the following HTML:
|
||||
To append a query string to a URL:
|
||||
|
||||
```go-html-template
|
||||
{{ $qs := collections.Querify "a" 1 "b" 2 }}
|
||||
{{ $href := printf "https://example.org?%s" $qs }}
|
||||
|
||||
<a href="{{ $href }}">Link</a>
|
||||
```
|
||||
|
||||
Hugo renders this to:
|
||||
|
||||
```html
|
||||
<a href="https://www.google.com?page=3&q=test">Search</a>
|
||||
<a href="https://example.org?a=1&b=2">Link</a>
|
||||
```
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: collections.Slice
|
||||
description: Creates a slice of all passed arguments.
|
||||
description: Returns a slice composed of the given values.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
@@ -8,7 +8,7 @@ action:
|
||||
related:
|
||||
- functions/collections/Dictionary
|
||||
returnType: any
|
||||
signatures: [collections.Slice ITEM...]
|
||||
signatures: ['collections.Slice [VALUE...]']
|
||||
aliases: [/functions/slice]
|
||||
---
|
||||
|
||||
@@ -16,3 +16,9 @@ aliases: [/functions/slice]
|
||||
{{ $s := slice "a" "b" "c" }}
|
||||
{{ $s }} → [a b c]
|
||||
```
|
||||
|
||||
To create an empty slice:
|
||||
|
||||
```go-html-template
|
||||
{{ $s := slice }}
|
||||
```
|
||||
|
||||
@@ -144,7 +144,7 @@ After sorting:
|
||||
{{% note %}}
|
||||
Although you can use the `sort` function to sort a page collection, Hugo provides [sorting and grouping methods] as well.
|
||||
|
||||
[sorting and grouping methods]: /methods/pages
|
||||
[sorting and grouping methods]: /methods/pages/
|
||||
{{% /note %}}
|
||||
|
||||
In this contrived example, sort the site's regular pages by `.Type` in descending order:
|
||||
|
||||
@@ -12,7 +12,7 @@ toc: true
|
||||
aliases: [/functions/where]
|
||||
---
|
||||
|
||||
The `where` function returns the given collection, removing elements that do not satisfy the comparison condition. The comparison condition is comprised of the `KEY`, `OPERATOR`, and `VALUE` arguments:
|
||||
The `where` function returns the given collection, removing elements that do not satisfy the comparison condition. The comparison condition is composed of the `KEY`, `OPERATOR`, and `VALUE` arguments:
|
||||
|
||||
```text
|
||||
collections.Where COLLECTION KEY [OPERATOR] VALUE
|
||||
@@ -204,10 +204,10 @@ Use the `like` operator to compare string values. Comparing other data types wil
|
||||
|
||||
There are four predefined front matter dates: [`date`], [`publishDate`], [`lastmod`], and [`expiryDate`]. Regardless of the front matter data format (TOML, YAML, or JSON) these are [`time.Time`] values, allowing precise comparisons.
|
||||
|
||||
[`date`]: /methods/page/date
|
||||
[`publishdate`]: /methods/page/publishdate
|
||||
[`lastmod`]: /methods/page/lastmod
|
||||
[`expirydate`]: /methods/page/expirydate
|
||||
[`date`]: /methods/page/date/
|
||||
[`publishdate`]: /methods/page/publishdate/
|
||||
[`lastmod`]: /methods/page/lastmod/
|
||||
[`expirydate`]: /methods/page/expirydate/
|
||||
[`time.Time`]: https://pkg.go.dev/time#Time
|
||||
|
||||
For example, to return a collection of pages that were created before the current year:
|
||||
@@ -243,7 +243,7 @@ To return a collection of future events:
|
||||
{{ $futureEvents := where $events "Params.eventDate" "gt" now }}
|
||||
```
|
||||
|
||||
When working with YAML or JSON, or quoted TOML values, custom dates are strings; you cannot compare them with `time.Time` values. String comparisons may be possible if the custom date layout is consistent from one page to the next. However, to be safe, filter the pages by ranging through the collection:
|
||||
When working with YAML or JSON, or quoted TOML values, custom dates are strings; you cannot compare them with `time.Time` values. String comparisons may be possible if the custom date layout is consistent from one page to the next. To be safe, filter the pages by ranging through the collection:
|
||||
|
||||
```go-html-template
|
||||
{{ $events := where .Site.RegularPages "Type" "events" }}
|
||||
@@ -288,7 +288,7 @@ These are equivalent:
|
||||
|
||||
Useful for theme authors, avoid hardcoding section names by using the `where` function with the [`MainSections`] method on a `Site` object.
|
||||
|
||||
[`MainSections`]: /methods/site/mainsections
|
||||
[`MainSections`]: /methods/site/mainsections/
|
||||
|
||||
```go-html-template
|
||||
{{ $pages := where .Site.RegularPages "Section" "in" .Site.MainSections }}
|
||||
@@ -403,7 +403,7 @@ To exclude a page with an undefined field from a boolean _inequality_ test:
|
||||
2. Create a collection using a nil comparison
|
||||
3. Subtract the second collection from the first collection using the [`collections.Complement`] function.
|
||||
|
||||
[`collections.Complement`]: /functions/collections/complement
|
||||
[`collections.Complement`]: /functions/collections/complement/
|
||||
|
||||
This template:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user