# HG changeset patch
# User Ludovic Chabant <ludovic@chabant.com>
# Date 1425880750 25200
# Node ID 33903b1705a7c286f15b18867b9be2609fd9d792
# Parent  f51b69ad09ae7b49ae25d3800f5e761cd4389fb4
docs: Documentation for iterators and filtering.

diff -r f51b69ad09ae -r 33903b1705a7 docs/docs/03_content/07_assets.md
--- a/docs/docs/03_content/07_assets.md	Sun Mar 08 22:58:58 2015 -0700
+++ b/docs/docs/03_content/07_assets.md	Sun Mar 08 22:59:10 2015 -0700
@@ -31,6 +31,16 @@
 Then, on the page, you can access those assets with the assets variable and the
 name of the asset (without the extension):
 
+    {%raw%}
     ![map to our place]({{ assets.map }})
     ![our place]({{ assets['street-view'] }})
+    {%endraw%}
 
+You can also loop over a page's assets:
+
+    {%raw%}
+    {% for a in assets %}
+    <img src="{{a}}" alt="" />
+    {% endfor %}
+    {%endraw%}
+
diff -r f51b69ad09ae -r 33903b1705a7 docs/docs/03_content/08_iterators.md
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/docs/03_content/08_iterators.md	Sun Mar 08 22:59:10 2015 -0700
@@ -0,0 +1,39 @@
+---
+title: Iterators
+needs_pygments: true
+---
+
+PieCrust returns _iterator objects_ as template data in several cases:
+`pagination.posts`, `assets`, `site.pages`, etc. Any time there's a list of
+_stuff_, you can bet it's returned as an _iterator object_.
+
+At first glance, there's not much difference with a simple list:
+
+{%highlight 'django'%}
+{%raw%}
+{% for page in site.pages %}
+* [{{page.title}}]({{page.url}})
+{% endfor %}
+{%endraw%}
+{%endhighlight%}
+
+But the iterator includes features that, although they can be emulated with
+enough templating code, are much faster to achieve with the shortcut functions
+available here.
+
+For example, if you want to get the first 10 pages that have the tag `pastry`,
+you can do this:
+
+{%highlight 'jinja'%}
+{%raw%}
+{% for page in site.pages.has_tags('pastry').limit(10) %}
+* [{{page.title}}]({{page.url}})
+{% endfor %}
+{%endraw%}
+{%endhighlight%}
+
+You can even achieve more elaborate filtering with the [filter syntax][flt],
+too.
+
+[flt]: {{docurl('content/filtering')}}
+
diff -r f51b69ad09ae -r 33903b1705a7 docs/docs/03_content/09_filtering.md
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/docs/03_content/09_filtering.md	Sun Mar 08 22:59:10 2015 -0700
@@ -0,0 +1,39 @@
+---
+title: Filtering
+---
+
+The PieCrust filtering syntax can be used to select items returned by an
+[iterator object][it] -- including [pagination items][pag] and [assets][ass].
+
+Filters are _named_, and using one on an iterator object just requires to pass
+that name:
+
+{%highlight 'jinja'%}
+{%raw%}
+{% for page in site.pages.filter('my_filter') %}
+...
+{% endfor %}
+{%endraw%}
+{%endhighlight%}
+
+The named filter should be available in the page's configuration header. For
+instance, the following filter matches pages that have the `pastry` tag (_i.e._
+a `tags` metadata value that contains `pastry`) and are not drafts (_i.e._ don't
+have a `draft` metadata value set to `true`):
+
+    ---
+    title: Something
+    my_filter:
+        has_tags: pastry
+        not:
+            is_draft: true
+    ---
+
+See the [templating data reference page][tpldata] for a full list of the
+available filter clauses.
+
+
+[it]: {{docurl('content/iterators')}}
+[pag]: {{docurl('content/pagination')}}
+[ass]: {{docurl('content/assets')}}
+