Add attr_contains template filter to enable filtering docs with an at…

…tribute containing a given value.

docs/changes.rst

@@ -6,6 +6,7 @@ Changes
 4.1.0 to 4.2.0
 --------------
 
+* Add attr_contains template filter to enable filtering docs with an attribute containing a given value.
 * URL unquote file names so special characters can be used in URLs.
 
 4.0.0 to 4.1.0

docs/templates.rst

@@ -3,7 +3,19 @@
 Templates
 =========
 
-The template engine that comes with Logya is `jinja2 <http://jinja.pocoo.org/>`_. In addition to the many functions and filters jinja2 provides you can use the following filters/functions.
+The template engine that comes with Logya is `jinja2 <http://jinja.pocoo.org/>`_. In addition to the many functions and filters jinja2 provides you can use the following filters and global functions.
+
+attr_contains
+-------------
+
+The ``attr_contains`` filter returns a generator of documents that have the given attribute and its value contains the given test value. Consider the following `real world usage example <http://guitarstreams.com/chord/guitar/C/>`_:
+
+::
+
+    {% set lessons = index['lesson/guitar'].docs|attr_contains('chords', 'C') %}
+
+This template snippet selects the documents in the ``lesson/guitar`` index that have an attribute called ``chords`` containing the value ``C``. In this case the document attribute value is a list, but you can also check whether the value is ``in`` other Python sequence types, such as strings.
+
 
 filesource
 ----------

logya/template.py

@@ -9,7 +9,7 @@ def filesource(logya_inst, name, lines=None, raw=False):
     """Read and return source of text files.
 
     A template function that reads the source of the given file and returns it.
-    The content is escaped by default so it can be rendered safely on a Web page.
+    Content is escaped by default so it can be rendered safely on a Web page.
 
     The lines keyword argument is used to limit the number of lines returned.
 
@@ -62,12 +62,17 @@ def __init__(self, logya_inst):
             self.env.lstrip_blocks = True
             self.env.trim_blocks = True
 
-        # Add filesource global to allow for including the source of a file.
+        # Include the source of a file.
         self.env.globals['filesource'] = lambda x, lines=None, raw=False: filesource(
             logya_inst, x, lines=lines, raw=raw)
 
+        # Get a document from its URL.
         self.env.globals['get_doc'] = lambda x: get_doc(logya_inst, x)
 
+        # Filter docs list where the given attribute contains the given value.
+        self.env.filters['attr_contains'] = lambda docs, attr, val: (
+            doc for doc in docs if attr in doc and val in doc[attr])
+
     def get_page(self, doc, template):
         try:
             page = self.env.get_template(template)