ref: 93addfcbeec301e4f37b0f83bc5735f1939f1895
parent: 0ce4ec1edb6116cd2803ef1120b5943da1fc29c5
author: spf13 <[email protected]>
date: Fri Aug 29 20:57:38 EDT 2014
Adding documentation about 'where' and cleaning up docs around first.
--- a/docs/content/templates/content.md
+++ b/docs/content/templates/content.md
@@ -2,7 +2,7 @@
aliases:
- /layout/functions/
date: 2013-07-01
-linktitle: Single
+linktitle: Single Content
menu:
main:
parent: layout
--- a/docs/content/templates/functions.md
+++ b/docs/content/templates/functions.md
@@ -38,9 +38,30 @@
### first
Slices an array to only the first X elements.
+Works on [lists](/templates/list/), [taxonomies](/taxonomies/displaying/), [terms](/templates/terms/), [groups](/templates/list/)
+
eg.
{{ range first 10 .Data.Pages }} {{ .Render "summary"}}+ {{ end }}+
+### where
+Filters an array to only elements containing a matching value for a given field.
+
+Works on [lists](/templates/list/), [taxonomies](/taxonomies/displaying/), [terms](/templates/terms/), [groups](/templates/list/)
+
+eg.
+
+ {{ range where .Data.Pages "Section" "post" }}+ {{ .Content}}+ {{ end }}+
+*where and first can be stacked*
+
+eg.
+
+ {{ range first 5 (where .Data.Pages "Section" "post") }}+ {{ .Content}} {{ end }}--- a/docs/content/templates/list.md
+++ b/docs/content/templates/list.md
@@ -2,7 +2,7 @@
aliases:
- /layout/indexes/
date: 2013-07-01
-linktitle: List
+linktitle: List of Content
menu:
main:
parent: layout
@@ -296,3 +296,43 @@
{{ end }}</ul>
{{ end }}+
+## Filtering & Limiting Content
+
+Sometimes you only want to list a subset of the available content. A common
+request is to only display “Posts” on the homepage. Using the `where` function
+you can do just that.
+
+### First
+
+`first` works like the limit keyword in SQL. It reduces the array to only the
+first X elements. It takes the array and number of elements as input.
+
+ {{ range first 10 .Data.Pages }}+ {{ .Render "summary"}}+ {{ end }}+
+### Where
+
+`where` works in a similar manner to the where keyword in SQL. It selects all
+elements of the slice that match the provided field and value. It takes three
+arguments 'array or slice of maps or structs', 'key or field name' and 'match
+value'
+
+ {{ range where .Data.Pages "Section" "post" }}+ {{ .Content}}+ {{ end }}+
+### First & Where Together
+
+Using both together can be very powerful.
+
+ {{ range first 5 (where .Data.Pages "Section" "post") }}+ {{ .Content}}+ {{ end }}+
+If `where` or `first` receives invalid input or a field name that doesn’t exist they will provide an error and stop site generation.
+
+These are both template functions and work on not only
+[lists](/templates/list/), but [taxonomies](/taxonomies/displaying/),
+[terms](/templates/terms/) and [groups](/templates/list/).