Where.md - hugo - [fork] hugo port for 9front
HTML git clone https://git.drkhsh.at/hugo.git
DIR Log
DIR Files
DIR Refs
DIR Submodules
DIR README
DIR LICENSE
---
Where.md (12571B)
---
1 ---
2 title: collections.Where
3 description: Returns the given collection, removing elements that do not satisfy the comparison condition.
4 categories: []
5 keywords: []
6 params:
7 functions_and_methods:
8 aliases: [where]
9 returnType: any
10 signatures: ['collections.Where COLLECTION KEY [OPERATOR] VALUE']
11 aliases: [/functions/where]
12 ---
13
14 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:
15
16 ```text
17 collections.Where COLLECTION KEY [OPERATOR] VALUE
18 --------------------
19 comparison condition
20 ```
21
22 Hugo will test for equality if you do not provide an `OPERATOR` argument. For example:
23
24 ```go-html-template
25 {{ $pages := where .Site.RegularPages "Section" "books" }}
26 {{ $books := where .Site.Data.books "genres" "suspense" }}
27 ```
28
29 ## Arguments
30
31 The where function takes three or four arguments. The `OPERATOR` argument is optional.
32
33 COLLECTION
34 : (`any`) A [page collection](g) or a [slice](g) of [maps](g).
35
36 KEY
37 : (`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](g) the subkey as shown below:
38
39 ```go-html-template
40 {{ $result := where .Site.RegularPages "Params.foo" "bar" }}
41 ```
42
43 OPERATOR
44 : (`string`) The logical comparison [operator](#operators).
45
46 VALUE
47 : (`any`) The value with which to compare. The values to compare must have comparable data types. For example:
48
49 Comparison|Result
50 :--|:--
51 `"123" "eq" "123"`|`true`
52 `"123" "eq" 123`|`false`
53 `false "eq" "false"`|`false`
54 `false "eq" false`|`true`
55
56 When one or both of the values to compare is a slice, use the `in`, `not in`, or `intersect` operators as described below.
57
58 ## Operators
59
60 Use any of the following logical operators:
61
62 `=`, `==`, `eq`
63 : (`bool`) Reports whether the given field value is equal to `VALUE`.
64
65 `!=`, `<>`, `ne`
66 : (`bool`) Reports whether the given field value is not equal to `VALUE`.
67
68 `>=`, `ge`
69 : (`bool`) Reports whether the given field value is greater than or equal to `VALUE`.
70
71 `>`, `gt`
72 : `true` Reports whether the given field value is greater than `VALUE`.
73
74 `<=`, `le`
75 : (`bool`) Reports whether the given field value is less than or equal to `VALUE`.
76
77 `<`, `lt`
78 : (`bool`) Reports whether the given field value is less than `VALUE`.
79
80 `in`
81 : (`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).
82
83 `not in`
84 : (`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).
85
86 `intersect`
87 : (`bool`) Reports whether the given field value (a slice) contains one or more elements in common with `VALUE`. See [details](/functions/collections/intersect).
88
89 `like`
90 : (`bool`) Reports whether the given field value matches the [regular expression](g) 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.
91
92 > [!note]
93 > The examples below perform comparisons within a page collection, but the same comparisons are applicable to a slice of maps.
94
95 ## String comparison
96
97 Compare the value of the given field to a [`string`](g):
98
99 ```go-html-template
100 {{ $pages := where .Site.RegularPages "Section" "eq" "books" }}
101 {{ $pages := where .Site.RegularPages "Section" "ne" "books" }}
102 ```
103
104 ## Numeric comparison
105
106 Compare the value of the given field to an [`int`](g) or [`float`](g):
107
108 ```go-html-template
109 {{ $books := where site.RegularPages "Section" "eq" "books" }}
110
111 {{ $pages := where $books "Params.price" "eq" 42 }}
112 {{ $pages := where $books "Params.price" "ne" 42.67 }}
113 {{ $pages := where $books "Params.price" "ge" 42 }}
114 {{ $pages := where $books "Params.price" "gt" 42.67 }}
115 {{ $pages := where $books "Params.price" "le" 42 }}
116 {{ $pages := where $books "Params.price" "lt" 42.67 }}
117 ```
118
119 ## Boolean comparison
120
121 Compare the value of the given field to a [`bool`](g):
122
123 ```go-html-template
124 {{ $books := where site.RegularPages "Section" "eq" "books" }}
125
126 {{ $pages := where $books "Params.fiction" "eq" true }}
127 {{ $pages := where $books "Params.fiction" "eq" false }}
128 {{ $pages := where $books "Params.fiction" "ne" true }}
129 {{ $pages := where $books "Params.fiction" "ne" false }}
130 ```
131
132 ## Member comparison
133
134 Compare a [`scalar`](g) to a [`slice`](g).
135
136 For example, to return a collection of pages where the `color` page parameter is either "red" or "yellow":
137
138 ```go-html-template
139 {{ $fruit := where site.RegularPages "Section" "eq" "fruit" }}
140
141 {{ $colors := slice "red" "yellow" }}
142 {{ $pages := where $fruit "Params.color" "in" $colors }}
143 ```
144
145 To return a collection of pages where the "color" page parameter is neither "red" nor "yellow":
146
147 ```go-html-template
148 {{ $fruit := where site.RegularPages "Section" "eq" "fruit" }}
149
150 {{ $colors := slice "red" "yellow" }}
151 {{ $pages := where $fruit "Params.color" "not in" $colors }}
152 ```
153
154 ## Intersection comparison
155
156 Compare a `slice` to a `slice`, returning collection elements with common values. This is frequently used when comparing taxonomy terms.
157
158 For example, to return a collection of pages where any of the terms in the "genres" taxonomy are "suspense" or "romance":
159
160 ```go-html-template
161 {{ $books := where site.RegularPages "Section" "eq" "books" }}
162
163 {{ $genres := slice "suspense" "romance" }}
164 {{ $pages := where $books "Params.genres" "intersect" $genres }}
165 ```
166
167 ## Regular expression comparison
168
169 To return a collection of pages where the "author" page parameter begins with either "victor" or "Victor":
170
171 ```go-html-template
172 {{ $pages := where .Site.RegularPages "Params.author" "like" `(?i)^victor` }}
173 ```
174
175 {{% include "/_common/functions/regular-expressions.md" %}}
176
177 > [!note]
178 > Use the `like` operator to compare string values. Comparing other data types will result in an empty collection.
179
180 ## Date comparison
181
182 ### Predefined dates
183
184 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.
185
186 For example, to return a collection of pages that were created before the current year:
187
188 ```go-html-template
189 {{ $startOfYear := time.AsTime (printf "%d-01-01" now.Year) }}
190 {{ $pages := where .Site.RegularPages "Date" "lt" $startOfYear }}
191 ```
192
193 ### Custom dates
194
195 With custom front matter dates, the comparison depends on the front matter data format (TOML, YAML, or JSON).
196
197 > [!note]
198 > Using TOML for pages with custom front matter dates enables precise date comparisons.
199
200 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.
201
202 In the TOML example below, note that the event date is not quoted.
203
204 ```text {file="content/events/2024-user-conference.md"}
205 +++
206 title = '2024 User Conference"
207 eventDate = 2024-04-01
208 +++
209 ```
210
211 To return a collection of future events:
212
213 ```go-html-template
214 {{ $events := where .Site.RegularPages "Type" "events" }}
215 {{ $futureEvents := where $events "Params.eventDate" "gt" now }}
216 ```
217
218 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:
219
220 ```go-html-template
221 {{ $events := where .Site.RegularPages "Type" "events" }}
222 {{ $futureEvents := slice }}
223 {{ range $events }}
224 {{ if gt (time.AsTime .Params.eventDate) now }}
225 {{ $futureEvents = $futureEvents | append . }}
226 {{ end }}
227 {{ end }}
228 ```
229
230 ## Nil comparison
231
232 To return a collection of pages where the "color" parameter is present in front matter, compare to `nil`:
233
234 ```go-html-template
235 {{ $pages := where .Site.RegularPages "Params.color" "ne" nil }}
236 ```
237
238 To return a collection of pages where the "color" parameter is not present in front matter, compare to `nil`:
239
240 ```go-html-template
241 {{ $pages := where .Site.RegularPages "Params.color" "eq" nil }}
242 ```
243
244 In both examples above, note that `nil` is not quoted.
245
246 ## Nested comparison
247
248 These are equivalent:
249
250 ```go-html-template
251 {{ $pages := where .Site.RegularPages "Type" "tutorials" }}
252 {{ $pages = where $pages "Params.level" "eq" "beginner" }}
253 ```
254
255 ```go-html-template
256 {{ $pages := where (where .Site.RegularPages "Type" "tutorials") "Params.level" "eq" "beginner" }}
257 ```
258
259 ## Portable section comparison
260
261 Useful for theme authors, avoid hardcoding section names by using the `where` function with the [`MainSections`] method on a `Site` object.
262
263 ```go-html-template
264 {{ $pages := where .Site.RegularPages "Section" "in" .Site.MainSections }}
265 ```
266
267 With this construct, a theme author can instruct users to specify their main sections in the site configuration:
268
269 {{< code-toggle file=hugo >}}
270 mainSections = ['blog','galleries']
271 {{< /code-toggle >}}
272
273 If `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.
274
275 ## Boolean/undefined comparison
276
277 Consider this site content:
278
279 ```text
280 content/
281 ├── posts/
282 │ ├── _index.md
283 │ ├── post-1.md <-- front matter: exclude = false
284 │ ├── post-2.md <-- front matter: exclude = true
285 │ └── post-3.md <-- front matter: exclude not defined
286 └── _index.md
287 ```
288
289 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.
290
291 ### Equality test
292
293 This template:
294
295 ```go-html-template
296 <ul>
297 {{ range where .Site.RegularPages "Params.exclude" "eq" false }}
298 <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
299 {{ end }}
300 </ul>
301 ```
302
303 Is rendered to:
304
305 ```html
306 <ul>
307 <li><a href="/posts/post-1/">Post 1</a></li>
308 </ul>
309 ```
310
311 This template:
312
313 ```go-html-template
314 <ul>
315 {{ range where .Site.RegularPages "Params.exclude" "eq" true }}
316 <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
317 {{ end }}
318 </ul>
319 ```
320
321 Is rendered to:
322
323 ```html
324 <ul>
325 <li><a href="/posts/post-2/">Post 2</a></li>
326 </ul>
327 ```
328
329 ### Inequality test
330
331 This template:
332
333 ```go-html-template
334 <ul>
335 {{ range where .Site.RegularPages "Params.exclude" "ne" false }}
336 <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
337 {{ end }}
338 </ul>
339 ```
340
341 Is rendered to:
342
343 ```html
344 <ul>
345 <li><a href="/posts/post-2/">Post 2</a></li>
346 <li><a href="/posts/post-3/">Post 3</a></li>
347 </ul>
348 ```
349
350 This template:
351
352 ```go-html-template
353 <ul>
354 {{ range where .Site.RegularPages "Params.exclude" "ne" true }}
355 <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
356 {{ end }}
357 </ul>
358 ```
359
360 Is rendered to:
361
362 ```html
363 <ul>
364 <li><a href="/posts/post-1/">Post 1</a></li>
365 <li><a href="/posts/post-3/">Post 3</a></li>
366 </ul>
367 ```
368
369 To exclude a page with an undefined field from a boolean _inequality_ test:
370
371 1. Create a collection using a boolean comparison
372 1. Create a collection using a nil comparison
373 1. Subtract the second collection from the first collection using the [`collections.Complement`] function.
374
375 This template:
376
377 ```go-html-template
378 {{ $p1 := where .Site.RegularPages "Params.exclude" "ne" true }}
379 {{ $p2 := where .Site.RegularPages "Params.exclude" "eq" nil }}
380 <ul>
381 {{ range $p1 | complement $p2 }}
382 <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
383 {{ end }}
384 </ul>
385 ```
386
387 Is rendered to:
388
389 ```html
390 <ul>
391 <li><a href="/posts/post-1/">Post 1</a></li>
392 </ul>
393 ```
394
395 This template:
396
397 ```go-html-template
398 {{ $p1 := where .Site.RegularPages "Params.exclude" "ne" false }}
399 {{ $p2 := where .Site.RegularPages "Params.exclude" "eq" nil }}
400 <ul>
401 {{ range $p1 | complement $p2 }}
402 <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
403 {{ end }}
404 </ul>
405 ```
406
407 Is rendered to:
408
409 ```html
410 <ul>
411 <li><a href="/posts/post-1/">Post 2</a></li>
412 </ul>
413 ```
414
415 [`collections.Complement`]: /functions/collections/complement/
416 [`date`]: /methods/page/date/
417 [`lastmod`]: /methods/page/lastmod/
418 [`MainSections`]: /methods/site/mainsections/
419 [`time.Time`]: https://pkg.go.dev/time#Time