diff options
Diffstat (limited to 'docs/content/en/functions/collections')
28 files changed, 768 insertions, 511 deletions
diff --git a/docs/content/en/functions/collections/After.md b/docs/content/en/functions/collections/After.md index e27c1507f..0cf25c7dd 100644 --- a/docs/content/en/functions/collections/After.md +++ b/docs/content/en/functions/collections/After.md @@ -1,20 +1,15 @@ --- title: collections.After -linkTitle: after description: Slices an array to the items after the Nth item. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [after] + related: + - functions/collections/First + - functions/collections/Last returnType: any signatures: [collections.After INDEX COLLECTION] -relatedFunctions: - - collections.After - - collections.First - - collections.Last aliases: [/functions/after] --- @@ -22,10 +17,20 @@ The following shows `after` being used in conjunction with the [`slice`]function ```go-html-template {{ $data := slice "one" "two" "three" "four" }} -{{ range after 2 $data }} - {{ . }} -{{ end }} -→ ["three", "four"] +<ul> + {{ range after 2 $data }} + <li>{{ . }}</li> + {{ end }} +</ul> +``` + +The template above is rendered to: + +```html +<ul> + <li>three</li> + <li>four</li> +</ul> ``` ## Example of `after` with `first`: 2nd–4th most recent articles @@ -35,32 +40,32 @@ You can use `after` in combination with the [`first`] function and Hugo's [power 1. The top row is titled "Featured" and shows only the most recently published article (i.e. by `publishdate` in the content files' front matter). 2. The second row is titled "Recent Articles" and shows only the 2nd- to 4th-most recently published articles. -{{< code file="layouts/section/articles.html" >}} +{{< code file=layouts/section/articles.html >}} {{ define "main" }} -<section class="row featured-article"> - <h2>Featured Article</h2> - {{ range first 1 .Pages.ByPublishDate.Reverse }} - <header> - <h3><a href="{{ .Permalink }}">{{ .Title }}</a></h3> - </header> - <p>{{ .Description }}</p> -{{ end }} -</section> -<div class="row recent-articles"> - <h2>Recent Articles</h2> - {{ range first 3 (after 1 .Pages.ByPublishDate.Reverse) }} - <section class="recent-article"> - <header> - <h3><a href="{{ .Permalink }}">{{ .Title }}</a></h3> - </header> - <p>{{ .Description }}</p> - </section> + <section class="row featured-article"> + <h2>Featured Article</h2> + {{ range first 1 .Pages.ByPublishDate.Reverse }} + <header> + <h3><a href="{{ .RelPermalink }}">{{ .Title }}</a></h3> + </header> + <p>{{ .Description }}</p> {{ end }} -</div> + </section> + <div class="row recent-articles"> + <h2>Recent Articles</h2> + {{ range first 3 (after 1 .Pages.ByPublishDate.Reverse) }} + <section class="recent-article"> + <header> + <h3><a href="{{ .RelPermalink }}">{{ .Title }}</a></h3> + </header> + <p>{{ .Description }}</p> + </section> + {{ end }} + </div> {{ end }} {{< /code >}} [`first`]: /functions/collections/first [list/section page]: /templates/section-templates -[lists]: /templates/lists/#order-content +[lists]: /templates/lists/#sort-content [`slice`]: /functions/collections/slice/ diff --git a/docs/content/en/functions/collections/Append.md b/docs/content/en/functions/collections/Append.md index 31657288f..5632dccfb 100644 --- a/docs/content/en/functions/collections/Append.md +++ b/docs/content/en/functions/collections/Append.md @@ -1,22 +1,17 @@ --- title: collections.Append -linkTitle: append description: Appends one or more elements to a slice and returns the resulting slice. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [append] + related: + - functions/collections/Merge + - functions/collections/Slice returnType: any signatures: - - COLLECTION | collections.Append ELEMENT [ELEMENT]... - - COLLECTION | collections.Append COLLECTION -relatedFunctions: - - collections.Append - - collections.Merge - - collections.Slice + - collections.Append ELEMENT [ELEMENT...] COLLECTION + - collections.Append COLLECTION1 COLLECTION2 aliases: [/functions/append] --- diff --git a/docs/content/en/functions/collections/Apply.md b/docs/content/en/functions/collections/Apply.md index 4d972b853..abd6fca77 100644 --- a/docs/content/en/functions/collections/Apply.md +++ b/docs/content/en/functions/collections/Apply.md @@ -1,18 +1,13 @@ --- title: collections.Apply -linkTitle: apply description: Returns a new collection with each element transformed by the given function. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [apply] returnType: '[]any' signatures: [collections.Apply COLLECTION FUNCTION PARAM...] relatedFunctions: - - collections.Apply - collections.Delimit - collections.In - collections.Reverse @@ -25,7 +20,6 @@ The `apply` function takes three or more arguments, depending on the function be The first argument is the collection itself, the second argument is the function name, and the remaining arguments are passed to the function, with the string `"."` representing the collection element. - ```go-html-template {{ $s := slice "hello" "world" }} diff --git a/docs/content/en/functions/collections/Complement.md b/docs/content/en/functions/collections/Complement.md index 28b7ded3d..b2a4b42a4 100644 --- a/docs/content/en/functions/collections/Complement.md +++ b/docs/content/en/functions/collections/Complement.md @@ -1,21 +1,16 @@ --- title: collections.Complement -linkTitle: complement description: Returns the elements of the last collection that are not in any of the others. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [complement] + related: + - functions/collections/Intersect + - functions/collections/SymDiff + - functions/collections/Union returnType: any - signatures: ['collections.Complement COLLECTION [COLLECTION]...'] -relatedFunctions: - - collections.Complement - - collections.Intersect - - collections.SymDiff - - collections.Union + signatures: ['collections.Complement COLLECTION [COLLECTION...]'] aliases: [/functions/complement] --- @@ -35,7 +30,6 @@ Make your code simpler to understand by using a [chained pipeline]: [chained pipeline]: https://pkg.go.dev/text/template#hdr-Pipelines {{% /note %}} - ```go-html-template {{ $c3 | complement $c1 $c2 }} → [1 2] ``` @@ -65,7 +59,7 @@ To list everything except blog articles (`blog`) and frequently asked questions Although the example above demonstrates the `complement` function, you could use the [`where`] function as well: [`where`]: /functions/collections/where -{{% /note %}} +{{% /note %}} ```go-html-template {{ range where site.RegularPages "Type" "not in" (slice "blog" "faqs") }} diff --git a/docs/content/en/functions/collections/Delimit.md b/docs/content/en/functions/collections/Delimit.md index 0fc3ef537..6aea467ee 100644 --- a/docs/content/en/functions/collections/Delimit.md +++ b/docs/content/en/functions/collections/Delimit.md @@ -1,24 +1,19 @@ --- title: collections.Delimit -linkTitle: delimit description: Loops through any array, slice, or map and returns a string of all the values separated by a delimiter. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [delimit] - returnType: template.HTML + related: + - functions/collections/Apply + - functions/collections/In + - functions/collections/Reverse + - functions/collections/Seq + - functions/collections/Slice + - functions/strings/Split + returnType: string signatures: ['collections.Delimit COLLECTION DELIMITER [LAST]'] -relatedFunctions: - - collections.Apply - - collections.Delimit - - collections.In - - collections.Reverse - - collections.Seq - - collections.Slice - - strings.Split aliases: [/functions/delimit] --- @@ -26,8 +21,8 @@ Delimit a slice: ```go-html-template {{ $s := slice "b" "a" "c" }} -{{ delimit $s ", " }} → "b, a, c" -{{ delimit $s ", " " and "}} → "b, a and c" +{{ delimit $s ", " }} → b, a, c +{{ delimit $s ", " " and "}} → b, a and c ``` Delimit a map: @@ -38,6 +33,6 @@ The `delimit` function sorts maps by key, returning the values. ```go-html-template {{ $m := dict "b" 2 "a" 1 "c" 3 }} -{{ delimit $m ", " }} → "1, 2, 3" -{{ delimit $m ", " " and "}} → "1, 2 and 3" +{{ delimit $m ", " }} → 1, 2, 3 +{{ delimit $m ", " " and "}} → 1, 2 and 3 ``` diff --git a/docs/content/en/functions/collections/Dictionary.md b/docs/content/en/functions/collections/Dictionary.md index 28c387726..2e933aca9 100644 --- a/docs/content/en/functions/collections/Dictionary.md +++ b/docs/content/en/functions/collections/Dictionary.md @@ -1,40 +1,59 @@ --- title: collections.Dictionary -linkTitle: dict description: Creates a map from a list of key and value pairs. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [dict] + related: + - functions/collections/Group + - functions/collections/IndexFunction + - functions/collections/IsSet + - functions/collections/Where returnType: mapany - signatures: ['collections.Dictionary KEY VALUE [KEY VALUE]...'] -relatedFunctions: - - collections.Dictionary - - collections.Group - - collections.Index - - collections.IsSet - - collections.Where + signatures: ['collections.Dictionary KEY VALUE [VALUE...]'] aliases: [/functions/dict] --- -`dict` is especially useful for passing more than one value to a partial template. +```go-html-template +{{ $m := dict "a" 1 "b" 2 }} +``` + +The above produces this data structure: + +```json +{ + "a": 1, + "b": 2 +} +``` + 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.: -```go-text-template +```go-html-template {{ $m := dict (slice "a" "b" "c") "value" }} ``` -## Example: using `dict` to pass multiple values to a `partial` +The above produces this data structure: + +```json +{ + "a": { + "b": { + "c": "value" + } + } +} +``` + +## 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" >}} +{{< 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> @@ -45,7 +64,7 @@ fill="{{ .fill }}" width="{{ .width }}" height="{{ .height }}" viewBox="0 0 32 3 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" >}} +{{< code file=layouts/_default/list.html >}} {{ partial "svgs/external-links.svg" (dict "fill" "#01589B" "width" 10 "height" 20 ) }} {{< /code >}} diff --git a/docs/content/en/functions/collections/EchoParam.md b/docs/content/en/functions/collections/EchoParam.md deleted file mode 100644 index 7617eedd9..000000000 --- a/docs/content/en/functions/collections/EchoParam.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: collections.EchoParam -linkTitle: echoParam -description: Prints a parameter if it is set. -categories: [functions] -keywords: [] -menu: - docs: - parent: functions -function: - aliases: [echoParam] - returnType: any - signatures: [collections.EchoParam COLLECTION KEY] -relatedFunctions: [] -aliases: [/functions/echoparam] ---- - -For example, consider this site configuration: - -{{< code-toggle file=hugo copy=false >}} -[params.footer] -poweredBy = 'Hugo' -{{< /code-toggle >}} - -To print the value of `poweredBy`: - -```go-html-template -{{ echoParam site.Params.footer "poweredby" }} → Hugo -``` - -{{% note %}} -When using the `echoParam` function you must reference the key using lower case. See the previous example. - -The `echoParam` function will be deprecated in a future release. Instead, use either of the constructs below. -{{% /note %}} - -```go-html-template -{{ site.Params.footer.poweredBy }} → Hugo -{{ index site.Params.footer "poweredBy" }} → Hugo -``` diff --git a/docs/content/en/functions/collections/First.md b/docs/content/en/functions/collections/First.md index ddb045382..49a0362f5 100644 --- a/docs/content/en/functions/collections/First.md +++ b/docs/content/en/functions/collections/First.md @@ -1,53 +1,36 @@ --- title: collections.First -linkTitle: first -description: Slices an array to the first N elements. -categories: [functions] +description: Returns the given collection, limited to the first N elements. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [first] + related: + - functions/collections/After + - functions/collections/Last returnType: any - signatures: [collections.First LIMIT COLLECTION] -relatedFunctions: - - collections.After - - collections.First - - collections.Last + signatures: [collections.First N COLLECTION] aliases: [/functions/first] --- -`first` works in a similar manner to the [`limit` keyword in -SQL][limitkeyword]. It reduces the array to only the `first N` -elements. It takes the array and number of elements as input. - -`first` takes two arguments: -1. `number of elements` -2. `array` *or* `slice of maps or structs` - -{{< code file="layout/_default/section.html" >}} -{{ range first 10 .Pages }} - {{ .Render "summary" }} +```go-html-template +{{ range first 5 .Pages }} + {{ .Render "summary" }} {{ end }} -{{< /code >}} +``` -*Note: Exclusive to `first`, LIMIT can be '0' to return an empty array.* +Set `N` to zero to return an empty collection. -## `first` and `where` Together +```go-html-template +{{ $emptyPageCollection := first 0 .Pages}} +``` -Using `first` and [`where`] together can be very -powerful. Below snippet gets a list of posts only from [main -sections], sorts it by the `title` parameter, and then -ranges through only the first 5 posts in that list: +Use `first` and [`where`] together. -{{< code file="first-and-where-together.html" >}} -{{ range first 5 (where site.RegularPages "Type" "in" site.Params.mainSections).ByTitle }} - {{ .Content }} +```go-html-template +{{ range where .Pages "Section" "articles" | first 5 }} + {{ .Render "summary" }} {{ end }} -{{< /code >}} - +``` -[limitkeyword]: https://www.techonthenet.com/sql/select_limit.php [`where`]: /functions/collections/where -[main sections]: /functions/collections/where#mainsections diff --git a/docs/content/en/functions/collections/Group.md b/docs/content/en/functions/collections/Group.md index 29220f1f7..74aa869df 100644 --- a/docs/content/en/functions/collections/Group.md +++ b/docs/content/en/functions/collections/Group.md @@ -1,26 +1,21 @@ --- title: collections.Group -linkTitle: group -description: Groups a list of pages. -categories: [functions] +description: Groups the given page collection by the given key. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [group] + related: + - functions/collections/Dictionary + - functions/collections/IndexFunction + - functions/collections/IsSet + - functions/collections/Where returnType: any - signatures: [PAGES | collections.Group KEY] -relatedFunctions: - - collections.Dictionary - - collections.Group - - collections.Index - - collections.IsSet - - collections.Where + signatures: [collections.Group KEY PAGES] aliases: [/functions/group] --- -{{< code file="layouts/partials/groups.html" >}} +```go-html-template {{ $new := .Site.RegularPages | first 10 | group "New" }} {{ $old := .Site.RegularPages | last 10 | group "Old" }} {{ $groups := slice $new $old }} @@ -29,12 +24,12 @@ aliases: [/functions/group] <ul> {{ range .Pages }} <li> - <a href="{{ .Permalink }}">{{ .Title }}</a> + <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a> <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> </li> {{ end }} </ul> {{ end }} -{{< /code >}} +``` The page group you get from `group` is of the same type you get from the built-in [group methods](/templates/lists#group-content) in Hugo. The above example can be [paginated](/templates/pagination/#list-paginator-pages). diff --git a/docs/content/en/functions/collections/In.md b/docs/content/en/functions/collections/In.md index 57ffbd653..a3ec83d9b 100644 --- a/docs/content/en/functions/collections/In.md +++ b/docs/content/en/functions/collections/In.md @@ -1,21 +1,27 @@ --- title: collections.In -linkTitle: in -description: Reports whether an element is in an array or slice, or if a substring is in a string. +description: Reports whether the given value is a member of the given set. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [in] + related: + - functions/collections/Slice + - functions/strings/Contains + - functions/strings/ContainsAny + - functions/strings/ContainsNonSpace + - functions/strings/HasPrefix + - functions/strings/HasSuffix returnType: bool - signatures: [collections.In SET ITEM] -relatedFunctions: - - collections.Slice + signatures: [collections.In SET VALUE] aliases: [/functions/in] --- +The `SET` can be an [array], [slice], or [string]. +[array]: /getting-started/glossary/#array +[slice]: /getting-started/glossary/#slice +[string]: /getting-started/glossary/#string ```go-html-template {{ $s := slice "a" "b" "c" }} diff --git a/docs/content/en/functions/collections/IndexFunction.md b/docs/content/en/functions/collections/IndexFunction.md index cd063f36e..e595d2b41 100644 --- a/docs/content/en/functions/collections/IndexFunction.md +++ b/docs/content/en/functions/collections/IndexFunction.md @@ -1,71 +1,66 @@ --- title: collections.Index -linkTitle: index description: Looks up the index(es) or key(s) of the data structure passed into it. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [index] + related: + - functions/collections/Dictionary + - functions/collections/Group + - functions/collections/IsSet + - functions/collections/Where returnType: any signatures: - collections.Index COLLECTION INDEXES - collections.Index COLLECTION KEYS -relatedFunctions: - - collections.Dictionary - - collections.EchoParam - - collections.Group - - collections.Index - - collections.IsSet - - collections.Where 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.: -```go-text-template +```go-html-template {{ $slice := slice "a" "b" "c" }} -{{ index $slice 1 }} => b +{{ index $slice 0 }} → a +{{ index $slice 1 }} → b + {{ $map := dict "a" 100 "b" 200 }} -{{ index $map "b" }} => 200 +{{ index $map "b" }} → 200 ``` The function takes multiple indices as arguments, and this can be used to get nested values, e.g.: -```go-text-template +```go-html-template {{ $map := dict "a" 100 "b" 200 "c" (slice 10 20 30) }} -{{ index $map "c" 1 }} => 20 +{{ index $map "c" 1 }} → 20 {{ $map := dict "a" 100 "b" 200 "c" (dict "d" 10 "e" 20) }} -{{ index $map "c" "e" }} => 20 +{{ index $map "c" "e" }} → 20 ``` You may write multiple indices as a slice: -```go-text-template +```go-html-template {{ $map := dict "a" 100 "b" 200 "c" (dict "d" 10 "e" 20) }} {{ $slice := slice "c" "e" }} -{{ index $map $slice }} => 20 +{{ index $map $slice }} → 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: -``` -. -└── data - └── locations - ├── abilene.toml - ├── chicago.toml - ├── oslo.toml - └── provo.toml +```text +data/ + └── locations/ + ├── abilene.toml + ├── chicago.toml + ├── oslo.toml + └── provo.toml ``` Here is an example: -{{< code-toggle file="data/locations/oslo" copy=false >}} +{{< code-toggle file=data/locations/oslo >}} website = "https://www.oslo.kommune.no" pop_city = 658390 pop_metro = 1717900 @@ -73,7 +68,7 @@ pop_metro = 1717900 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 copy=false >}} +{{< code-toggle file=content/articles/oslo.md fm=true >}} title = "My Norwegian Vacation" location = "oslo" {{< /code-toggle >}} diff --git a/docs/content/en/functions/collections/Intersect.md b/docs/content/en/functions/collections/Intersect.md index 6a2c131b4..8bc60f8e1 100644 --- a/docs/content/en/functions/collections/Intersect.md +++ b/docs/content/en/functions/collections/Intersect.md @@ -1,26 +1,20 @@ --- title: collections.Intersect -linkTitle: intersect description: Returns the common elements of two arrays or slices, in the same order as the first array. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [intersect] + related: + - functions/collections/Complement + - functions/collections/SymDiff + - functions/collections/Union returnType: any signatures: [collections.Intersect SET1 SET2] -relatedFunctions: - - collections.Complement - - collections.Intersect - - collections.SymDiff - - collections.Union aliases: [/functions/intersect] --- -A useful example is to use it as `AND` filters when combined with where: -## AND filter in where query +A useful example is to use it as `AND` filters when combined with where: ```go-html-template {{ $pages := where .Site.RegularPages "Type" "not in" (slice "page" "about") }} @@ -32,6 +26,5 @@ The above fetches regular pages not of `page` or `about` type unless they are pi See [union](/functions/collections/union) for `OR`. - [partials]: /templates/partials/ [single]: /templates/single-page-templates/ diff --git a/docs/content/en/functions/collections/IsSet.md b/docs/content/en/functions/collections/IsSet.md index 93fb9f8f6..76b336ae3 100644 --- a/docs/content/en/functions/collections/IsSet.md +++ b/docs/content/en/functions/collections/IsSet.md @@ -1,28 +1,25 @@ --- title: collections.IsSet -linkTitle: isset description: Reports whether the key exists within the collection. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [isset] + related: + - functions/collections/Dictionary + - functions/collections/Group + - functions/collections/IndexFunction + - functions/collections/Where + - functions/go-template/if + - functions/go-template/with returnType: bool signatures: [collections.IsSet COLLECTION KEY] -relatedFunctions: - - collections.Dictionary - - collections.Group - - collections.Index - - collections.IsSet - - collections.Where aliases: [/functions/isset] --- For example, consider this site configuration: -{{< code-toggle file=hugo copy=false >}} +{{< code-toggle file=hugo >}} [params] showHeroImage = false {{< /code-toggle >}} diff --git a/docs/content/en/functions/collections/KeyVals.md b/docs/content/en/functions/collections/KeyVals.md index f3e0c559d..3d21ca6fd 100644 --- a/docs/content/en/functions/collections/KeyVals.md +++ b/docs/content/en/functions/collections/KeyVals.md @@ -1,21 +1,20 @@ --- title: collections.KeyVals -linkTitle: keyVals description: Returns a KeyVals struct. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [keyVals] - returnType: KeyValues + related: + - methods/pages/Related + returnType: types.KeyValues signatures: [collections.KeyVals KEY VALUES...] -relatedFunctions: [] 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 `Page` object. +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. + +[`Related`]: /methods/pages/related See [related content](/content-management/related). @@ -39,7 +38,6 @@ The resulting data structure is: To extract the key and values: ```go-html-template - {{ $kv.Key }} → foo {{ $kv.Values }} → [a b c] ``` diff --git a/docs/content/en/functions/collections/Last.md b/docs/content/en/functions/collections/Last.md index 3f8496354..8219e120d 100644 --- a/docs/content/en/functions/collections/Last.md +++ b/docs/content/en/functions/collections/Last.md @@ -1,20 +1,15 @@ --- title: collections.Last -linkTitle: last -description: Slices an array to the last N elements. -categories: [functions] +description: Returns the given collection, limited to the last N elements. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [last] + related: + - functions/collections/After + - functions/collections/First returnType: any - signatures: [collections.Last INDEX COLLECTION] -relatedFunctions: - - collections.After - - collections.First - - collections.Last + signatures: [collections.Last N COLLECTION] aliases: [/functions/last] --- @@ -23,3 +18,17 @@ aliases: [/functions/last] {{ .Render "summary" }} {{ end }} ``` + +Set `N` to zero to return an empty collection. + +```go-html-template +{{ $emptyPageCollection := last 0 .Pages}} +``` + +Use `last` and [`where`] together. + +```go-html-template +{{ range where .Pages "Section" "articles" | last 5 }} + {{ .Render "summary" }} +{{ end }} +``` diff --git a/docs/content/en/functions/collections/Merge.md b/docs/content/en/functions/collections/Merge.md index 908f1738a..3f5208cfc 100644 --- a/docs/content/en/functions/collections/Merge.md +++ b/docs/content/en/functions/collections/Merge.md @@ -1,19 +1,14 @@ --- title: collections.Merge -linkTitle: merge description: Returns the result of merging two or more maps. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [merge] + related: + - functions/collections/Append returnType: any signatures: [collections.Merge MAP MAP...] -relatedFunctions: - - collections.Append - - collections.Merge aliases: [/functions/merge] --- diff --git a/docs/content/en/functions/collections/NewScratch.md b/docs/content/en/functions/collections/NewScratch.md index 0df90bb96..793b2b4b5 100644 --- a/docs/content/en/functions/collections/NewScratch.md +++ b/docs/content/en/functions/collections/NewScratch.md @@ -1,22 +1,115 @@ --- title: collections.NewScratch -linkTitle: newScratch -description: Creates a new Scratch which can be used to store values in a thread safe way. -categories: [functions] +description: Returns a locally scoped "scratch pad" to store and manipulate data. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [newScratch] - returnType: Scratch + related: + - methods/page/scratch + - methods/page/store + returnType: maps.Scratch signatures: [collections.NewScratch ] -relatedFunctions: [] --- +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 pad]: /getting-started/glossary/#scratch-pad + +## Methods + +Set +: Sets the value of a given key. + +```go-html-template +{{ $s := newScratch }} +{{ $s.Set "greeting" "Hello" }} +``` + +Get +: Gets the value of a given key. + +```go-html-template +{{ $s := newScratch }} +{{ $s.Set "greeting" "Hello" }} +{{ $s.Get "greeting" }} → Hello +``` + +Add +: Adds a given value to existing value(s) of the given key. + +: For single values, `Add` accepts values that support Go's `+` operator. If the first `Add` for a key is an array or slice, the following adds will be appended to that list. + +```go-html-template +{{ $s := newScratch }} +{{ $s.Set "greeting" "Hello" }} +{{ $s.Add "greeting" "Welcome" }} +{{ $s.Get "greeting" }} → HelloWelcome +``` + +```go-html-template +{{ $s := newScratch }} +{{ $s.Set "total" 3 }} +{{ $s.Add "total" 7 }} +{{ $s.Get "total" }} → 10 +``` + +```go-html-template +{{ $s := newScratch }} +{{ $s.Set "greetings" (slice "Hello") }} +{{ $s.Add "greetings" (slice "Welcome" "Cheers") }} +{{ $s.Get "greetings" }} → [Hello Welcome Cheers] +``` + +SetInMap +: Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`. + +```go-html-template +{{ $s := newScratch }} +{{ $s.SetInMap "greetings" "english" "Hello" }} +{{ $s.SetInMap "greetings" "french" "Bonjour" }} +{{ $s.Get "greetings" }} → map[english:Hello french:Bonjour] +``` + +DeleteInMap +: Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`. + +```go-html-template +{{ $s := newScratch }} +{{ $s.SetInMap "greetings" "english" "Hello" }} +{{ $s.SetInMap "greetings" "french" "Bonjour" }} +{{ $s.DeleteInMap "greetings" "english" }} +{{ $s.Get "greetings" }} → map[french:Bonjour] +``` + +GetSortedMapValues +: Returns an array of values from `key` sorted by `mapKey`. + +```go-html-template +{{ $s := newScratch }} +{{ $s.SetInMap "greetings" "english" "Hello" }} +{{ $s.SetInMap "greetings" "french" "Bonjour" }} +{{ $s.GetSortedMapValues "greetings" }} → [Hello Bonjour] +``` + +Delete +: Removes the given key. + ```go-html-template -{{ $scratch := newScratch }} -{{ $scratch.Add "b" 2 }} -{{ $scratch.Add "b" 2 }} -{{ $scratch.Get "b" }} → 4 +{{ $s := newScratch }} +{{ $s.Set "greeting" "Hello" }} +{{ $s.Delete "greeting" }} +``` + +Values +: Returns the raw backing map. Do not use with `Scratch` or `Store` methods on a `Page` object due to concurrency issues. + +```go-html-template +{{ $s := newScratch }} +{{ $s.SetInMap "greetings" "english" "Hello" }} +{{ $s.SetInMap "greetings" "french" "Bonjour" }} + +{{ $map := $s.Values }} ``` diff --git a/docs/content/en/functions/collections/Querify.md b/docs/content/en/functions/collections/Querify.md index c94d51133..e195c417f 100644 --- a/docs/content/en/functions/collections/Querify.md +++ b/docs/content/en/functions/collections/Querify.md @@ -1,19 +1,15 @@ --- title: collections.Querify -linkTitle: querify description: Takes a set or slice of key-value pairs and returns a query string to be appended to URLs. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [querify] returnType: string signatures: - - collections.Querify KEY VALUE [KEY VALUE]... + - collections.Querify VALUE [VALUE...] - collections.Querify COLLECTION -relatedFunctions: +related: - collections.Querify - urlquery aliases: [/functions/querify] diff --git a/docs/content/en/functions/collections/Reverse.md b/docs/content/en/functions/collections/Reverse.md index 521adc6f2..12c964c76 100644 --- a/docs/content/en/functions/collections/Reverse.md +++ b/docs/content/en/functions/collections/Reverse.md @@ -1,16 +1,13 @@ --- title: collections.Reverse description: Reverses the order of a collection. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [] returnType: any signatures: [collections.Reverse COLLECTION] -relatedFunctions: +related: - collections.Apply - collections.Delimit - collections.In @@ -20,7 +17,6 @@ relatedFunctions: aliases: [/functions/collections.reverse] --- - ```go-html-template {{ slice 2 1 3 | collections.Reverse }} → [3 1 2] ``` diff --git a/docs/content/en/functions/collections/Seq.md b/docs/content/en/functions/collections/Seq.md index 65ff1432f..e7430e0d0 100644 --- a/docs/content/en/functions/collections/Seq.md +++ b/docs/content/en/functions/collections/Seq.md @@ -1,20 +1,16 @@ --- title: collections.Seq -linkTitle: seq description: Returns a slice of integers. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [seq] returnType: '[]int' signatures: - collections.Seq LAST - collections.Seq FIRST LAST - collections.Seq FIRST INCREMENT LAST -relatedFunctions: +related: - collections.Apply - collections.Delimit - collections.In @@ -40,3 +36,11 @@ Iterate over a sequence of integers: {{ end }} {{ $product }} → 24 ``` + +The example above is contrived. To calculate the product of 2 or more numbers, use the [`math.Product`] function: + +```go-html-template +{{ math.Product (seq 4) }} → 24 +``` + +[`math.Product`]: /functions/math/product diff --git a/docs/content/en/functions/collections/Shuffle.md b/docs/content/en/functions/collections/Shuffle.md index 8388d5332..18b8cc664 100644 --- a/docs/content/en/functions/collections/Shuffle.md +++ b/docs/content/en/functions/collections/Shuffle.md @@ -1,18 +1,13 @@ --- title: collections.Shuffle -linkTitle: shuffle description: Returns a random permutation of a given array or slice. -keywords: [ordering] -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [shuffle] returnType: any signatures: [collections.Shuffle COLLECTION] -relatedFunctions: +related: - collections.Reverse - collections.Shuffle - collections.Sort diff --git a/docs/content/en/functions/collections/Slice.md b/docs/content/en/functions/collections/Slice.md index a30800ed3..e24b394ca 100644 --- a/docs/content/en/functions/collections/Slice.md +++ b/docs/content/en/functions/collections/Slice.md @@ -1,17 +1,13 @@ --- title: collections.Slice -linkTitle: slice -description: Creates a slice (array) of all passed arguments. -categories: [functions] +description: Creates a slice of all passed arguments. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [slice] returnType: any signatures: [collections.Slice ITEM...] -relatedFunctions: +related: - collections.Append - collections.Apply - collections.Delimit @@ -22,8 +18,6 @@ relatedFunctions: aliases: [/functions/slice] --- -One use case is the concatenation of elements in combination with the [`delimit` function]: - ```go-html-template {{ $s := slice "a" "b" "c" }} {{ $s }} → [a b c] diff --git a/docs/content/en/functions/collections/Sort.md b/docs/content/en/functions/collections/Sort.md index bb0f82cde..6b9ea2c34 100644 --- a/docs/content/en/functions/collections/Sort.md +++ b/docs/content/en/functions/collections/Sort.md @@ -1,17 +1,13 @@ --- title: collections.Sort -linkTitle: sort description: Sorts slices, maps, and page collections. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [sort] returnType: any signatures: ['collections.Sort COLLECTION [KEY] [ORDER]'] -relatedFunctions: +related: - collections.Reverse - collections.Shuffle - collections.Sort @@ -27,7 +23,7 @@ The `ORDER` may be either `asc` (ascending) or `desc` (descending). The default The examples below assume this site configuration: -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} [params] grades = ['b','a','c'] {{< /code-toggle >}} @@ -36,10 +32,10 @@ grades = ['b','a','c'] Sort slice elements in ascending order using either of these constructs: -{{< code file="layouts/_default/single.html" copy=false >}} +```go-html-template {{ sort site.Params.grades }} → [a b c] {{ sort site.Params.grades "value" "asc" }} → [a b c] -{{< /code >}} +``` In the examples above, `value` is the `KEY` representing the value of the slice element. @@ -47,9 +43,9 @@ In the examples above, `value` is the `KEY` representing the value of the slice Sort slice elements in descending order: -{{< code file="layouts/_default/single.html" copy=false >}} +```go-html-template {{ sort site.Params.grades "value" "desc" }} → [c b a] -{{< /code >}} +``` In the example above, `value` is the `KEY` representing the value of the slice element. @@ -57,7 +53,7 @@ In the example above, `value` is the `KEY` representing the value of the slice e The examples below assume this site configuration: -{{< code-toggle file="hugo" copy=false >}} +{{< code-toggle file=hugo >}} [params.authors.a] firstName = "Marius" lastName = "Pontmercy" @@ -77,7 +73,7 @@ When sorting maps, the `KEY` argument must be lowercase. Sort map objects in ascending order using either of these constructs: -{{< code file="layouts/_default/single.html" copy=false >}} +```go-html-template {{ range sort site.Params.authors "firstname" }} {{ .firstName }} {{ end }} @@ -85,7 +81,7 @@ Sort map objects in ascending order using either of these constructs: {{ range sort site.Params.authors "firstname" "asc" }} {{ .firstName }} {{ end }} -{{< /code >}} +``` These produce: @@ -97,11 +93,11 @@ Jean Marius Victor Sort map objects in descending order: -{{< code file="layouts/_default/single.html" copy=false >}} +```go-html-template {{ range sort site.Params.authors "firstname" "desc" }} {{ .firstName }} {{ end }} -{{< /code >}} +``` This produces: @@ -111,25 +107,16 @@ Victor Marius Jean ## Sort a page collection -Although you can use the `sort` function to sort a page collection, Hugo provides [built-in methods for sorting page collections] by: +{{% note %}} +Although you can use the `sort` function to sort a page collection, Hugo provides [sorting and grouping methods] as well. -- weight -- linktitle -- title -- front matter parameter -- date -- expiration date -- last modified date -- publish date -- length +[sorting and grouping methods]: /methods/pages +{{% /note %}} In this contrived example, sort the site's regular pages by `.Type` in descending order: -{{< code file="layouts/_default/home.html" copy=false >}} +```go-html-template {{ range sort site.RegularPages "Type" "desc" }} - <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2> + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> {{ end }} -{{< /code >}} - - -[built-in methods for sorting page collections]: /templates/lists/#order-content +``` diff --git a/docs/content/en/functions/collections/SymDiff.md b/docs/content/en/functions/collections/SymDiff.md index ea9f20123..828c10ce5 100644 --- a/docs/content/en/functions/collections/SymDiff.md +++ b/docs/content/en/functions/collections/SymDiff.md @@ -1,17 +1,13 @@ --- title: collections.SymDiff -linkTitle: symdiff description: Returns the symmetric difference of two collections. -categories: [functions] +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [symdiff] returnType: any signatures: [COLLECTION | collections.SymDiff COLLECTION] -relatedFunctions: +related: - collections.Complement - collections.Intersect - collections.SymDiff @@ -25,4 +21,4 @@ Example: {{ slice 1 2 3 | symdiff (slice 3 4) }} → [1 2 4] ``` -Also see https://en.wikipedia.org/wiki/Symmetric_difference +Also see <https://en.wikipedia.org/wiki/Symmetric_difference>. diff --git a/docs/content/en/functions/collections/Union.md b/docs/content/en/functions/collections/Union.md index 119da6fb4..e2eb61313 100644 --- a/docs/content/en/functions/collections/Union.md +++ b/docs/content/en/functions/collections/Union.md @@ -1,17 +1,13 @@ --- title: collections.Union -linkTitle: union -description: Given two arrays or slices, returns a new array that contains the elements or objects that belong to either or both arrays/slices. -categories: [functions] +description: Given two arrays or slices, returns a new array that contains the elements that belong to either or both arrays/slices. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [union] returnType: any signatures: [collections.Union SET1 SET2] -relatedFunctions: +related: - collections.Complement - collections.Intersect - collections.SymDiff @@ -19,7 +15,7 @@ relatedFunctions: aliases: [/functions/union] --- -Given two arrays (or slices) A and B, this function will return a new array that contains the elements or objects that belong to either A or to B or to both. The elements supported are strings, integers, and floats (only float64). +Given two arrays (or slices) A and B, this function will return a new array that contains the elements or objects that belong to either A or to B or to both. ```go-html-template {{ union (slice 1 2 3) (slice 3 4 5) }} diff --git a/docs/content/en/functions/collections/Uniq.md b/docs/content/en/functions/collections/Uniq.md index 1b0a8f8f4..8266142ac 100644 --- a/docs/content/en/functions/collections/Uniq.md +++ b/docs/content/en/functions/collections/Uniq.md @@ -1,17 +1,13 @@ --- title: collections.Uniq -linkTitle: uniq -description: Takes in a slice or array and returns a slice with duplicate elements removed. -categories: [functions] +description: Returns the given collection, removing duplicate elements. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [uniq] returnType: any signatures: [collections.Uniq COLLECTION] -relatedFunctions: +related: - collections.Reverse - collections.Shuffle - collections.Sort @@ -19,7 +15,6 @@ relatedFunctions: aliases: [/functions/uniq] --- - ```go-html-template {{ slice 1 3 2 1 | uniq }} → [1 3 2] ``` diff --git a/docs/content/en/functions/collections/Where.md b/docs/content/en/functions/collections/Where.md index df6cec89f..e053ed3d5 100644 --- a/docs/content/en/functions/collections/Where.md +++ b/docs/content/en/functions/collections/Where.md @@ -1,17 +1,13 @@ --- title: collections.Where -linkTitle: where -description: Filters an array to only the elements containing a matching value for a given field. -categories: [functions] +description: Returns the given collection, removing elements that do not satisfy the comparison condition. +categories: [] keywords: [] -menu: - docs: - parent: functions -function: +action: aliases: [where] returnType: any - signatures: ['collections.Where COLLECTION KEY [OPERATOR] MATCH'] -relatedFunctions: + signatures: ['collections.Where COLLECTION KEY [OPERATOR] VALUE'] +related: - collections.Dictionary - collections.Group - collections.Index @@ -21,170 +17,434 @@ aliases: [/functions/where] toc: true --- -`where` filters an array to only the elements containing a matching -value for a given field. +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: -It works in a similar manner to the [`where` keyword in -SQL][wherekeyword]. +```text +collections.Where COLLECTION KEY [OPERATOR] VALUE + -------------------- + comparison condition +``` + +Hugo will test for equality if you do not provide an `OPERATOR` argument. For example: ```go-html-template -{{ range where .Pages "Section" "foo" }} - {{ .Content }} -{{ end }} +{{ $pages := where .Site.RegularPages "Section" "books" }} +{{ $books := where .Site.Data.books "genres" "suspense" }} ``` -It can be used by dot-chaining the second argument to refer to a nested element of a value. +## Arguments -{{< code-toggle file="content/example.md" fm=true copy=false >}} -title: Example -series: golang -{{< /code-toggle >}} +The where function takes three or four arguments. The `OPERATOR` argument is optional. -```go-html-template -{{ range where .Site.Pages "Params.series" "golang" }} - {{ .Content }} -{{ end }} -``` +COLLECTION +: (`any`) Typically a page collection or a [slice] of [maps]. -It can also be used with the logical operators `!=`, `>=`, `in`, etc. Without an operator, `where` compares a given field with a matching value equivalent to `=`. +[maps]: /getting-started/glossary/#map +[slice]: /getting-started/glossary/#slice + +KEY +: (`string`) The key of the page or map value to compare with `VALUE`. With page collections, commonly used comparison keys are `Section`, `Type`, and `Params`. To compare with a member of the page `Params` map, [chain] the subkey as shown below: ```go-html-template -{{ range where .Pages "Section" "!=" "foo" }} - {{ .Content }} -{{ end }} +{{ $result := where .Site.RegularPages "Params.foo" "bar" }} ``` -The following logical operators are available with `where`: +[chain]: /getting-started/glossary/#chain + +OPERATOR +: (`string`) The logical comparison [operator](#operators). + +VALUE +: (`any`) The value with which to compare. The values to compare must have comparable data types. For example: + +Comparison|Result +:--|:-- +`"123" "eq" "123"`|`true` +`"123" "eq" 123`|`false` +`false "eq" "false"`|`false` +`false "eq" false`|`true` + +When one or both of the values to compare is a slice, use the `in`, `not in` or `intersect` operators as described below. + +## Operators + +Use any of the following logical operators: `=`, `==`, `eq` -: `true` if a given field value equals a matching value +: (`bool`) Reports whether the given field value is equal to `VALUE`. `!=`, `<>`, `ne` -: `true` if a given field value doesn't equal a matching value +: (`bool`) Reports whether the given field value is not equal to `VALUE`. `>=`, `ge` -: `true` if a given field value is greater than or equal to a matching value +: (`bool`) Reports whether the given field value is greater than or equal to `VALUE`. `>`, `gt` -: `true` if a given field value is greater than a matching value +: `true` Reports whether the given field value is greater than `VALUE`. `<=`, `le` -: `true` if a given field value is lesser than or equal to a matching value +: (`bool`) Reports whether the given field value is less than or equal to `VALUE`. `<`, `lt` -: `true` if a given field value is lesser than a matching value +: (`bool`) Reports whether the given field value is less than `VALUE`. `in` -: `true` if a given field value is included in a matching value; a matching value must be an array or a slice +: (`bool`) Reports whether the given field value is a member of `VALUE`. Compare string to slice, or string to string. See [details](/functions/collections/in). `not in` -: `true` if a given field value isn't included in a matching value; a matching value must be an array or a slice +: (`bool`) Reports whether the given field value is not a member of `VALUE`. Compare string to slice, or string to string. See [details](/functions/collections/in). `intersect` -: `true` if a given field value that is a slice/array of strings or integers contains elements in common with the matching value; it follows the same rules as the [`intersect` function][intersect]. +: (`bool`) Reports whether the given field value (a slice) contains one or more elements in common with `VALUE`. See [details](/functions/collections/intersect). + +`like` {{< new-in 0.116.0 >}} +: (`bool`) Reports whether the given field value matches the regular expression specified in `VALUE`. Use the `like` operator to compare `string` values. The `like` operator returns `false` when comparing other data types to the regular expression. + +{{% note %}} +The examples below perform comparisons within a page collection, but the same comparisons are applicable to a slice of maps. +{{% /note %}} + +## String comparison -`like` -: `true` if a given field value matches a regular expression. Use the `like` operator to compare `string` values. Returns `false` when comparing other data types to the regular expression. +Compare the value of the given field to a [`string`]: + +[`string`]: /getting-started/glossary/#string -## Use `where` with boolean values -When using booleans you should not put quotation marks. ```go-html-template -{{ range where .Pages "Draft" true }} - <p>{{ .Title }}</p> -{{ end }} +{{ $pages := where .Site.RegularPages "Section" "eq" "books" }} +{{ $pages := where .Site.RegularPages "Section" "ne" "books" }} ``` -## Use `where` with `intersect` +## Numeric comparison + +Compare the value of the given field to an [`int`] or [`float`]: + +[`int`]: /getting-started/glossary/#int +[`float`]: /getting-started/glossary/#float ```go-html-template -{{ range where .Site.Pages "Params.tags" "intersect" .Params.tags }} - {{ if ne .Permalink $.Permalink }} - {{ .Render "summary" }} - {{ end }} -{{ end }} +{{ $sectionPages := where site.RegularPages "Section" "eq" "books" }} + +{{ $pages := where $sectionPages "Params.price" "eq" 42 }} +{{ $pages := where $sectionPages "Params.price" "ne" 42.67 }} +{{ $pages := where $sectionPages "Params.price" "ge" 42 }} +{{ $pages := where $sectionPages "Params.price" "gt" 42.67 }} +{{ $pages := where $sectionPages "Params.price" "le" 42 }} +{{ $pages := where $sectionPages "Params.price" "lt" 42.67 }} ``` -You can also put the returned value of the `where` clauses into a variable: +## Boolean comparison -{{< code file="where-intersect-variables.html" >}} -{{ $v1 := where .Site.Pages "Params.a" "v1" }} -{{ $v2 := where .Site.Pages "Params.b" "v2" }} -{{ $filtered := $v1 | intersect $v2 }} -{{ range $filtered }} -{{ end }} -{{< /code >}} +Compare the value of the given field to a [`bool`]: -## Use `where` with `like` +[`bool`]: /getting-started/glossary/#bool -This example matches pages where the "foo" parameter begins with "ab": +```go-html-template +{{ $sectionPages := where site.RegularPages "Section" "eq" "books" }} + +{{ $pages := where $sectionPages "Params.fiction" "eq" true }} +{{ $pages := where $sectionPages "Params.fiction" "eq" false }} +{{ $pages := where $sectionPages "Params.fiction" "ne" true }} +{{ $pages := where $sectionPages "Params.fiction" "ne" false }} +``` + +## Member comparison + +Compare a [`scalar`] to a [`slice`]. + +[`scalar`]: /getting-started/glossary/#scalar +[`slice`]: /getting-started/glossary/#slice + +For example, to return a collection of pages where the `color` page parameter is either "red" or "yellow": ```go-html-template -{{ range where site.RegularPages "Params.foo" "like" `^ab` }} - <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> -{{ end }} +{{ $sectionPages := where site.RegularPages "Section" "eq" "fruit" }} + +{{ $colors := slice "red" "yellow" }} +{{ $pages := where $sectionPages "Params.color" "in" $colors }} ``` -{{% readfile file="/functions/_common/regular-expressions.md" %}} +To return a collection of pages where the "color" page parameter is neither "red" nor "yellow": -## Use `where` with `first` +```go-html-template +{{ $sectionPages := where site.RegularPages "Section" "eq" "fruit" }} -Using `first` and `where` together can be very -powerful. Below snippet gets a list of posts only from [**main -sections**](#mainsections), sorts it using the [default -ordering](/templates/lists/) for lists (i.e., `weight => date`), and -then ranges through only the first 5 posts in that list: +{{ $colors := slice "red" "yellow" }} +{{ $pages := where $sectionPages "Params.color" "not in" $colors }} +``` -{{< code file="first-and-where-together.html" >}} -{{ range first 5 (where site.RegularPages "Type" "in" site.Params.mainSections) }} - {{ .Content }} -{{ end }} -{{< /code >}} +## Intersection comparison + +Compare a [`slice`] to a [`slice`], returning collection elements with common values. This is frequently used when comparing taxonomy terms. + +For example, to return a collection of pages where any of the terms in the "genres" taxonomy are "suspense" or "romance": + +```go-html-template +{{ $sectionPages := where site.RegularPages "Section" "eq" "books" }} + +{{ $genres := slice "suspense" "romance" }} +{{ $pages := where $sectionPages "Params.genres" "intersect" $genres }} +``` + +## Regular expression comparison -## Nest `where` clauses +{{< new-in 0.116.0 >}} -You can also nest `where` clauses to drill down on lists of content by more than one parameter. The following first grabs all pages in the "blog" section and then ranges through the result of the first `where` clause and finds all pages that are *not* featured: +To return a collection of pages where the "author" page parameter begins with either "victor" or "Victor": ```go-html-template -{{ range where (where .Pages "Section" "blog" ) "Params.featured" "!=" true }} +{{ $pages := where .Site.RegularPages "Params.author" "like" `(?i)^victor` }} ``` -## Unset fields +{{% include "functions/_common/regular-expressions.md" %}} + +{{% note %}} +Use the `like` operator to compare string values. Comparing other data types will result in an empty collection. +{{% /note %}} -Filtering only works for set fields. To check whether a field is set or exists, you can use the operand `nil`. +## Date comparison -This can be useful to filter a small amount of pages from a large pool. Instead of setting a field on all pages, you can set that field on required pages only. +### Predefined dates -Only the following operators are available for `nil` +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. -* `=`, `==`, `eq`: True if the given field is not set. -* `!=`, `<>`, `ne`: True if the given field is set. +[`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: ```go-html-template -{{ range where .Pages "Params.specialpost" "!=" nil }} - {{ .Content }} +{{ $startOfYear := time.AsTime (printf "%d-01-01" now.Year) }} +{{ $pages := where .Site.RegularPages "Date" "lt" $startOfYear }} +``` + +### Custom dates + +With custom front matter dates, the comparison depends on the front matter data format (TOML, YAML, or JSON). + +{{% note %}} +Using TOML for pages with custom front matter dates enables precise date comparisons. +{{% /note %}} + +With TOML, date values are first-class citizens. TOML has a date data type while JSON and YAML do not. If you quote a TOML date, it is a string. If you do not quote a TOML date value, it is [`time.Time`] value, enabling precise comparisons. + +In the TOML example below, note that the event date is not quoted. + +{{< code file="content/events/2024-user-conference.md" >}} ++++ +title = '2024 User Conference" +eventDate = 2024-04-01 ++++ +{{< /code >}} + +To return a collection of future events: + +```go-html-template +{{ $events := where .Site.RegularPages "Type" "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: + +```go-html-template +{{ $events := where .Site.RegularPages "Type" "events" }} +{{ $futureEvents := slice }} +{{ range $events }} + {{ if gt (time.AsTime .Params.eventDate) now }} + {{ $futureEvents = $futureEvents | append . }} + {{ end }} {{ end }} ``` -## Portable `where` filters -- `site.Params.mainSections` {#mainsections} +## Nil comparison -**This is especially important for themes.** +To return a collection of pages where the "color" parameter is present in front matter, compare to `nil`: + +```go-html-template +{{ $pages := where .Site.RegularPages "Params.color" "ne" nil }} +``` -To list the most relevant pages on the front page or similar, you -should use the `site.Params.mainSections` list instead of comparing -section names to hard-coded values like `"posts"` or `"post"`. +To return a collection of pages where the "color" parameter is not present in front matter, compare to `nil`: ```go-html-template -{{ $pages := where site.RegularPages "Type" "in" site.Params.mainSections }} +{{ $pages := where .Site.RegularPages "Params.color" "eq" nil }} ``` -If the user has not set this configuration parameter in their site configuration, it will default to the *section with the most pages*. +In both examples above, note that `nil` is not quoted. + +## Nested comparison -The user can override the default: +These are equivalent: -{{< code-toggle file="hugo" >}} +```go-html-template +{{ $pages := where .Site.RegularPages "Type" "tutorials" }} +{{ $pages = where $pages "Params.level" "eq" "beginner" }} +``` + +```go-html-template +{{ $pages := where (where .Site.RegularPages "Type" "tutorials") "Params.level" "eq" "beginner" }} +``` + +## Portable section comparison + +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 + +```go-html-template +{{ $pages := where .Site.RegularPages "Section" "in" .Site.MainSections }} +``` + +With this construct, a theme author can instruct users to specify their main sections in the site configuration: + +{{< code-toggle file=hugo >}} [params] - mainSections = ["blog", "docs"] +mainSections = ['blog','galleries'] {{< /code-toggle >}} -[intersect]: /functions/collections/intersect -[wherekeyword]: https://www.techonthenet.com/sql/where.php +If `params.mainSections` is not defined in the site configuration, the `MainSections` method returns a slice with one element---the top level section with the most pages. + +## Boolean/undefined comparison + +Consider this site content: + +```text +content/ +├── posts/ +│ ├── _index.md +│ ├── post-1.md <-- front matter: exclude = false +│ ├── post-2.md <-- front matter: exclude = true +│ └── post-3.md <-- front matter: exclude not defined +└── _index.md +``` + +The first two pages have an "exclude" field in front matter, but the last page does not. When testing for _equality_, the third page is _excluded_ from the result. When testing for _inequality_, the third page is _included_ in the result. + +### Equality test + +This template: + +```go-html-template +<ul> + {{ range where .Site.RegularPages "Params.exclude" "eq" false }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} +</ul> +``` + +Is rendered to: + +```html +<ul> + <li><a href="/posts/post-1/">Post 1</a></li> +</ul> +``` + +This template: + +```go-html-template +<ul> + {{ range where .Site.RegularPages "Params.exclude" "eq" true }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} +</ul> +``` + +Is rendered to: + +```html +<ul> + <li><a href="/posts/post-2/">Post 2</a></li> +</ul> +``` + +### Inequality test + +This template: + +```go-html-template +<ul> + {{ range where .Site.RegularPages "Params.exclude" "ne" false }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} +</ul> +``` + +Is rendered to: + +```html +<ul> + <li><a href="/posts/post-2/">Post 2</a></li> + <li><a href="/posts/post-3/">Post 3</a></li> +</ul> +``` + +This template: + +```go-html-template +<ul> + {{ range where .Site.RegularPages "Params.exclude" "ne" true }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} +</ul> +``` + +Is rendered to: + +```html +<ul> + <li><a href="/posts/post-1/">Post 1</a></li> + <li><a href="/posts/post-3/">Post 3</a></li> +</ul> +``` + +To exclude a page with an undefined field from a boolean _inequality_ test: + +1. Create a collection using a boolean comparison +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 + +This template: + +```go-html-template +{{ $p1 := where .Site.RegularPages "Params.exclude" "ne" true }} +{{ $p2 := where .Site.RegularPages "Params.exclude" "eq" nil }} +<ul> + {{ range $p1 | complement $p2 }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} +</ul> +``` + +Is rendered to: + +```html +<ul> + <li><a href="/posts/post-1/">Post 1</a></li> +</ul> +``` + +This template: + +```go-html-template +{{ $p1 := where .Site.RegularPages "Params.exclude" "ne" false }} +{{ $p2 := where .Site.RegularPages "Params.exclude" "eq" nil }} +<ul> + {{ range $p1 | complement $p2 }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} +</ul> +``` + +Is rendered to: + +```html +<ul> + <li><a href="/posts/post-1/">Post 2</a></li> +</ul> +``` diff --git a/docs/content/en/functions/collections/_index.md b/docs/content/en/functions/collections/_index.md new file mode 100644 index 000000000..51981f79b --- /dev/null +++ b/docs/content/en/functions/collections/_index.md @@ -0,0 +1,12 @@ +--- +title: Collections functions +linkTitle: collections +description: Template functions to work with arrays, slices, maps, and page collections. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to work with arrays, slices, maps, and page collections. |