- Added a "decorator" kw argument to <%def>,

  allows custom decoration functions to wrap
  rendering callables.  Mainly intended for
  custom caching algorithms, not sure what
  other uses there may be (but there may be).
  Examples are in the "filtering" docs.

2 files changed, 38 insertions, 0 deletions

diff --git a/doc/build/content/defs.txt b/doc/build/content/defs.txt
index a7e6bf5..932597b 100644
--- a/doc/build/content/defs.txt
+++ b/doc/build/content/defs.txt
@@ -298,3 +298,4 @@ The above layout would produce:
 
 The number of things you can do with `<%call>` and/or the `<%namespacename:defname>` calling syntax is enormous.  You can create form widget libraries, such as an enclosing `<FORM>` tag and nested HTML input elements, or portable wrapping schemes using `<div>` or other elements.  You can create tags that interpret rows of data, such as from a database, providing the individual columns of each row to a `body()` callable which lays out the row any way it wants.  Basically anything you'd do with a "custom tag" or tag library in some other system, Mako provides via `<%def>`s and plain Python callables which are invoked via `<%namespacename:defname>` or `<%call>`.
 
+
diff --git a/doc/build/content/filtering.txt b/doc/build/content/filtering.txt
index 86a332f..83cca0d 100644
--- a/doc/build/content/filtering.txt
+++ b/doc/build/content/filtering.txt
@@ -161,4 +161,41 @@ The above call is equivalent to the unbuffered call:
 
     ${somedef(17, 'hi', use_paging=True)}
     
+### Decorating
+
+This is a feature that's new as of version 0.2.5.   Somewhat like a filter for a %def but more flexible, the `decorator` argument to `%def` allows the creation of a function that will work in a similar manner to a Python decorator.   The function can control whether or not the function executes.   The original intent of this function is to allow the creation of custom cache logic, but there may be other uses as well.
+
+`decorator` is intended to be used with a regular Python function, such as one defined in a library module.  Here we'll illustrate the python function defined in the template for simplicities' sake:
+
+    <%!
+        def bar(fn):
+            def decorate(context, *args, **kw):
+                context.write("BAR")
+                fn(*args, **kw)
+                context.write("BAR")
+                return ''
+            return decorate
+    %>
+    
+    <%def name="foo()" decorator="bar">
+        this is foo
+    </%def>
+    
+    ${foo()}
     
+The above template will return, with more whitespace than this, `"BAR this is foo BAR"`.  The function is the render callable itself (or possibly a wrapper around it), and by default will write to the context.  To capture its output, use the `capture` callable in the `mako.runtime` module (available in templates as just  `runtime`):
+
+    <%!
+        def bar(fn):
+            def decorate(context, *args, **kw):
+                return "BAR" + runtime.capture(context, fn, *args, **kw) + "BAR"
+            return decorate
+    %>
+
+    <%def name="foo()" decorator="bar">
+        this is foo
+    </%def>
+
+    ${foo()}
+
+The decorator can be used with top-level defs as well as nested defs.  Note that when calling a top-level def from the `Template` api, i.e. `template.get_def('somedef').render()`, the decorator has to write the output to the `context`, i.e. as in the first example.  The return value gets discarded.
\ No newline at end of file