diff options
Diffstat (limited to 'docs/content/en/functions/collections')
-rw-r--r-- | docs/content/en/functions/collections/After.md | 4 | ||||
-rw-r--r-- | docs/content/en/functions/collections/Complement.md | 2 | ||||
-rw-r--r-- | docs/content/en/functions/collections/Dictionary.md | 35 | ||||
-rw-r--r-- | docs/content/en/functions/collections/First.md | 2 | ||||
-rw-r--r-- | docs/content/en/functions/collections/IndexFunction.md | 86 | ||||
-rw-r--r-- | docs/content/en/functions/collections/KeyVals.md | 6 | ||||
-rw-r--r-- | docs/content/en/functions/collections/NewScratch.md | 4 | ||||
-rw-r--r-- | docs/content/en/functions/collections/Querify.md | 25 | ||||
-rw-r--r-- | docs/content/en/functions/collections/Slice.md | 10 | ||||
-rw-r--r-- | docs/content/en/functions/collections/Sort.md | 2 | ||||
-rw-r--r-- | docs/content/en/functions/collections/Where.md | 16 |
11 files changed, 72 insertions, 120 deletions
diff --git a/docs/content/en/functions/collections/After.md b/docs/content/en/functions/collections/After.md index 0cf25c7dd..38cf755a0 100644 --- a/docs/content/en/functions/collections/After.md +++ b/docs/content/en/functions/collections/After.md @@ -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/ diff --git a/docs/content/en/functions/collections/Complement.md b/docs/content/en/functions/collections/Complement.md index b2a4b42a4..1c785de0b 100644 --- a/docs/content/en/functions/collections/Complement.md +++ b/docs/content/en/functions/collections/Complement.md @@ -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 diff --git a/docs/content/en/functions/collections/Dictionary.md b/docs/content/en/functions/collections/Dictionary.md index f46b02e75..2ac875d28 100644 --- a/docs/content/en/functions/collections/Dictionary.md +++ b/docs/content/en/functions/collections/Dictionary.md @@ -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/ diff --git a/docs/content/en/functions/collections/First.md b/docs/content/en/functions/collections/First.md index cb2397af1..07634d6b8 100644 --- a/docs/content/en/functions/collections/First.md +++ b/docs/content/en/functions/collections/First.md @@ -34,4 +34,4 @@ Use `first` and [`where`] together. {{ end }} ``` -[`where`]: /functions/collections/where +[`where`]: /functions/collections/where/ diff --git a/docs/content/en/functions/collections/IndexFunction.md b/docs/content/en/functions/collections/IndexFunction.md index 6482884fd..977e14d1e 100644 --- a/docs/content/en/functions/collections/IndexFunction.md +++ b/docs/content/en/functions/collections/IndexFunction.md @@ -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 -``` - -You may write multiple indices as a slice: - -```go-html-template -{{ $map := dict "a" 100 "b" 200 "c" (dict "d" 10 "e" 20) }} -{{ $slice := slice "c" "e" }} -{{ index $map $slice }} → 20 -``` - -## Example: load data from a path based on front matter parameters +{{ $m := dict "a" 100 "b" 200 "c" (slice 10 20 30) }} +{{ index $m "c" 1 }} → 20 -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 +{{ $m := dict "a" 100 "b" 200 "c" (dict "d" 10 "e" 20) }} +{{ index $m "c" "e" }} → 20 ``` -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.— +You may also use a slice of keys to access a nested value: ```go-html-template -{{ index .Site.Data.locations "oslo" }} +{{ $m := dict "a" 100 "b" 200 "c" (dict "d" 10 "e" 20) }} +{{ $s := slice "c" "e" }} +{{ index $m $s }} → 20 ``` -The variable for `.Params.location` is a string and can therefore replace `oslo` in the example above: +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 .Params.location }} -=> map[website:https://www.oslo.kommune.no pop_city:658390 pop_metro:1717900] -``` +{{ .Site.Params.foo }} -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 +{{ $k := "foo" }} +{{ index .Site.Params $k }} ``` diff --git a/docs/content/en/functions/collections/KeyVals.md b/docs/content/en/functions/collections/KeyVals.md index 3d21ca6fd..6a2109e78 100644 --- a/docs/content/en/functions/collections/KeyVals.md +++ b/docs/content/en/functions/collections/KeyVals.md @@ -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). diff --git a/docs/content/en/functions/collections/NewScratch.md b/docs/content/en/functions/collections/NewScratch.md index 96f85a8d0..cee20d754 100644 --- a/docs/content/en/functions/collections/NewScratch.md +++ b/docs/content/en/functions/collections/NewScratch.md @@ -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 diff --git a/docs/content/en/functions/collections/Querify.md b/docs/content/en/functions/collections/Querify.md index ea0434fc5..07e27bd7e 100644 --- a/docs/content/en/functions/collections/Querify.md +++ b/docs/content/en/functions/collections/Querify.md @@ -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> +{{ collections.Querify "a" 1 "b" 2 }} +{{ collections.Querify (slice "a" 1 "b" 2) }} +``` + +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 }} -{{ $qs := slice "q" "test" "page" 3 }} -<a href="https://www.google.com?{{ (querify $qs) | safeURL }}">Search</a> +<a href="{{ $href }}">Link</a> ``` -Both of these examples render the following HTML: +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> ``` diff --git a/docs/content/en/functions/collections/Slice.md b/docs/content/en/functions/collections/Slice.md index 56c068d4b..385f9b658 100644 --- a/docs/content/en/functions/collections/Slice.md +++ b/docs/content/en/functions/collections/Slice.md @@ -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 }} +``` diff --git a/docs/content/en/functions/collections/Sort.md b/docs/content/en/functions/collections/Sort.md index 2277f883c..815260f20 100644 --- a/docs/content/en/functions/collections/Sort.md +++ b/docs/content/en/functions/collections/Sort.md @@ -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: diff --git a/docs/content/en/functions/collections/Where.md b/docs/content/en/functions/collections/Where.md index f18ae507b..629d11eeb 100644 --- a/docs/content/en/functions/collections/Where.md +++ b/docs/content/en/functions/collections/Where.md @@ -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: |