# -*- coding: utf-8 -*-
<%inherit file="content_layout.html"/>
<%page args="toc, extension, paged"/>
<%namespace  name="formatting" file="formatting.html"/>
<%namespace  name="nav" file="nav.html"/>
<%def name="title()">Mako Documentation - Filtering and Buffering</%def>
<%!
    filename = 'filtering'
%>
## This file is generated.  Edit the .txt files instead of this one.


<%call expr="formatting.section(toc=toc,paged=paged,extension=extension,path='filtering')">


<%call expr="formatting.section(toc=toc,paged=paged,extension=extension,path='filtering_expression')">

<p>As described in the Syntax chapter, the "<code><%text filter='h'>|</%text></code>" operator can be applied to a "<code><%text filter='h'>${}</%text></code>" expression to apply escape filters to the output:
</p>
<%call expr="formatting.code()"><%text>${"this is some text" | u}
</%text></%call><p>The above expression applies URL escaping to the expression, and produces <code><%text filter='h'>this+is+some+text</%text></code>.
</p>
<p>The built-in escape flags are:
</p>
<ul>
 <li>
     <code><%text filter='h'>u</%text></code> : URL escaping, provided by <code><%text filter='h'>urllib.quote_plus(string.encode('utf-8'))</%text></code>
 </li>

 <li>
     <code><%text filter='h'>h</%text></code> : HTML escaping, provided by <code><%text filter='h'>markupsafe.escape(string)</%text></code>  (new as of 0.3.4 - prior versions use <code><%text filter='h'>cgi.escape(string, True)</%text></code>)
 </li>

 <li>
     <code><%text filter='h'>x</%text></code> : XML escaping
 </li>

 <li>
     <code><%text filter='h'>trim</%text></code> : whitespace trimming, provided by <code><%text filter='h'>string.strip()</%text></code>
 </li>

 <li>
     <code><%text filter='h'>entity</%text></code> : produces HTML entity references for applicable strings, derived from <code><%text filter='h'>htmlentitydefs</%text></code>
 </li>

 <li>
     <code><%text filter='h'>unicode</%text></code> (<code><%text filter='h'>str</%text></code> on Python 3): produces a Python unicode string (this function is applied by default).
 </li>

 <li>
     <code><%text filter='h'>decode.<some encoding></%text></code> : decode input into a Python unicode with the specified encoding
 </li>

 <li>
     <code><%text filter='h'>n</%text></code> : disable all default filtering; only filters specified in the local expression tag will be applied.
 </li>
</ul>
<p>To apply more than one filter, separate them by a comma:
</p>
<%call expr="formatting.code()"><%text>${"  <tag>some value</tag> " | h,trim}
</%text></%call><p>The above produces <code><%text filter='h'>&lt;tag&gt;some value&lt;/tag&gt;</%text></code>, with no leading or trailing whitespace.  The HTML escaping function is applied first, the "trim" function second.
</p>
<p>Naturally, you can make your own filters too.  A filter is just a Python function that accepts a single string argument, and returns the filtered result.  The expressions after the <code><%text filter='h'>|</%text></code> operator draw upon the local namespace of the template in which they appear, meaning you can define escaping functions locally:
</p>
<%call expr="formatting.code()"><%text><%!
    def myescape(text):
        return "<TAG>" + text + "</TAG>"
%>

Heres some tagged text: ${"text" | myescape}
</%text></%call><p>Or from any Python module:
</p>
<%call expr="formatting.code()"><%text><%!
    import myfilters
%>

Heres some tagged text: ${"text" | myfilters.tagfilter}
</%text></%call><p>A page can apply a default set of filters to all expression tags using the <code><%text filter='h'>expression_filter</%text></code> argument to the <code><%text filter='h'>%page</%text></code> tag:
</p>
<%call expr="formatting.code()"><%text><%page expression_filter="h"/>

Escaped text:  ${"<html>some html</html>"}
</%text></%call><p>Result:
</p>
<%call expr="formatting.code()"><%text>Escaped text: &lt;html&gt;some html&lt;/html&gt;
</%text></%call>
<%call expr="formatting.section(toc=toc,paged=paged,extension=extension,path='filtering_expression_defaultfilters')">

<p>In addition to the <code><%text filter='h'>expression_filter</%text></code> argument, the <code><%text filter='h'>default_filters</%text></code> argument to both <code><%text filter='h'>Template</%text></code> and <code><%text filter='h'>TemplateLookup</%text></code> can specify filtering for all expression tags at the programmatic level.  This array-based argument, when given its default argument of <code><%text filter='h'>None</%text></code>, will be internally set to <code><%text filter='h'>["unicode"]</%text></code> (or <code><%text filter='h'>["str"]</%text></code> on Python 3), except when <code><%text filter='h'>disable_unicode=True</%text></code> is set in which case it defaults to <code><%text filter='h'>["str"]</%text></code>:
</p>
<%call expr="formatting.code(syntaxtype='python')"><%text>
t = TemplateLookup(directories=['/tmp'], default_filters=['unicode'])
</%text></%call><p>To replace the usual <code><%text filter='h'>unicode</%text></code>/<code><%text filter='h'>str</%text></code> function with a specific encoding, the <code><%text filter='h'>decode</%text></code> filter can be substituted:
</p>
<%call expr="formatting.code(syntaxtype='python')"><%text>
t = TemplateLookup(directories=['/tmp'], default_filters=['decode.utf8'])
</%text></%call><p>To disable <code><%text filter='h'>default_filters</%text></code> entirely, set it to an empty list:
</p>
<%call expr="formatting.code(syntaxtype='python')"><%text>
t = TemplateLookup(directories=['/tmp'], default_filters=[])
</%text></%call><p>Any string name can be added to <code><%text filter='h'>default_filters</%text></code> where it will be added to all expressions as a filter.  The filters are applied from left to right, meaning the leftmost filter is applied first.
</p>
<%call expr="formatting.code(syntaxtype='python')"><%text>
t = Template(templatetext, default_filters=['unicode', 'myfilter'])
</%text></%call><p>To ease the usage of <code><%text filter='h'>default_filters</%text></code> with custom filters, you can also add imports (or other code) to all templates using the <code><%text filter='h'>imports</%text></code> argument:
</p>
<%call expr="formatting.code(syntaxtype='python')"><%text>
t = TemplateLookup(directories=['/tmp'], 
    default_filters=['unicode', 'myfilter'], 
    imports=['from mypackage import myfilter'])
</%text></%call><p>The above will generate templates something like this:
</p>
<%call expr="formatting.code(syntaxtype='python')"><%text>
# ....
from mypackage import myfilter

def render_body(context):
    context.write(myfilter(unicode("some text")))
</%text></%call>
</%call>
<%call expr="formatting.section(toc=toc,paged=paged,extension=extension,path='filtering_expression_turning')">

<p>In all cases the special <code><%text filter='h'>n</%text></code> filter, used locally within an expression, will <strong>disable</strong> all filters declared in the <code><%text filter='h'><%page></%text></code> tag as well <code><%text filter='h'>default_filters</%text></code>.  Such as:
</p>
<%call expr="formatting.code()"><%text>${'myexpression' | n}
</%text></%call><p>Will render <code><%text filter='h'>myexpression</%text></code> with no filtering of any kind, and
</p>
<%call expr="formatting.code()"><%text>${'myexpression' | n, trim}
</%text></%call><p>will render <code><%text filter='h'>myexpression</%text></code> using the <code><%text filter='h'>trim</%text></code> filter only.  <br></br>
</p>

</%call>
</%call>
<%call expr="formatting.section(toc=toc,paged=paged,extension=extension,path='filtering_filtering')">

<p>The <code><%text filter='h'>%def</%text></code> tag has a filter argument which will apply the given list of filter functions to the output of the <code><%text filter='h'>%def</%text></code>:
</p>
<%call expr="formatting.code()"><%text><%def name="foo()" filter="h, trim">
    <b>this is bold</b>
</%def>
</%text></%call><p>When the filter attribute is applied to a def as above, the def is automatically <strong>buffered</strong> as well.  This is described next.
</p>

</%call>
<%call expr="formatting.section(toc=toc,paged=paged,extension=extension,path='filtering_buffering')">

<p>One of Mako's central design goals is speed.  To this end, all of the textual content within a template and its various callables is by default piped directly to the single buffer that is stored within the <code><%text filter='h'>Context</%text></code> object.  While this normally is easy to miss, it has certain side effects.  The main one is that when you call a def using the normal expression syntax, i.e. <code><%text filter='h'>${somedef()}</%text></code>, it may appear that the return value of the function is the content it produced, which is then delivered to your template just like any other expression substitution, except that  normally, this is not the case; the return value of <code><%text filter='h'>${somedef()}</%text></code> is simply the empty string <code><%text filter='h'>''</%text></code>.  By the time you receive this empty string, the output of <code><%text filter='h'>somedef()</%text></code> has been sent to the underlying buffer.
</p>
<p>You may not want this effect, if for example you are doing something like this:
</p>
<%call expr="formatting.code()"><%text>${" results " + somedef() + " more results "}
</%text></%call><p>If the <code><%text filter='h'>somedef()</%text></code> function produced the content "<code><%text filter='h'>somedef's results</%text></code>", the above template would produce this output:
</p>
<%call expr="formatting.code()"><%text>somedef's results results more results
</%text></%call><p>This is because <code><%text filter='h'>somedef()</%text></code> fully executes before the expression returns the results of its concatenation; the concatenation in turn receives just the empty string as its middle expression.
</p>
<p>Mako provides two ways to work around this.  One is by applying buffering to the <code><%text filter='h'>%def</%text></code> itself:
</p>
<%call expr="formatting.code()"><%text><%def name="somedef()" buffered="True">
    somedef's results
</%def>
</%text></%call><p>The above definition will generate code similar to this:
</p>
<%call expr="formatting.code()"><%text>def somedef():
    context.push_buffer()
    try:
        context.write("somedef's results")
    finally:
        buf = context.pop_buffer()
    return buf.getvalue()
</%text></%call><p>So that the content of <code><%text filter='h'>somedef()</%text></code> is sent to a second buffer, which is then popped off the stack and its value returned.  The speed hit inherent in buffering the output of a def is also apparent.
</p>
<p>Note that the <code><%text filter='h'>filter</%text></code> argument on %def also causes the def to be buffered.  This is so that the final content of the %def can be delivered to the escaping function in one batch, which reduces method calls and also produces more deterministic behavior for the filtering function itself, which can possibly be useful for a filtering function that wishes to apply a transformation to the text as a whole.
</p>
<p>The other way to buffer the output of a def or any Mako callable is by using the built-in <code><%text filter='h'>capture</%text></code> function.  This function performs an operation similar to the above buffering operation except it is specified by the caller.
</p>
<%call expr="formatting.code()"><%text>${" results " + capture(somedef) + " more results "}
</%text></%call><p>Note that the first argument to the <code><%text filter='h'>capture</%text></code> function is <strong>the function itself</strong>, not the result of calling it.  This is because the <code><%text filter='h'>capture</%text></code> function takes over the job of actually calling the target function, after setting up a buffered environment.  To send arguments to the function, just send them to <code><%text filter='h'>capture</%text></code> instead:
</p>
<%call expr="formatting.code()"><%text>${capture(somedef, 17, 'hi', use_paging=True)}
</%text></%call><p>The above call is equivalent to the unbuffered call:
</p>
<%call expr="formatting.code()"><%text>${somedef(17, 'hi', use_paging=True)}
</%text></%call>
</%call>
<%call expr="formatting.section(toc=toc,paged=paged,extension=extension,path='filtering_decorating')">

<p>This is a feature that's new as of version 0.2.5.   Somewhat like a filter for a %def but more flexible, the <code><%text filter='h'>decorator</%text></code> argument to <code><%text filter='h'>%def</%text></code> 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.
</p>
<p><code><%text filter='h'>decorator</%text></code> 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:
</p>
<%call expr="formatting.code()"><%text><%!
    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()}
</%text></%call><p>The above template will return, with more whitespace than this, <code><%text filter='h'>"BAR this is foo BAR"</%text></code>.  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 <code><%text filter='h'>capture</%text></code> callable in the <code><%text filter='h'>mako.runtime</%text></code> module (available in templates as just  <code><%text filter='h'>runtime</%text></code>):
</p>
<%call expr="formatting.code()"><%text><%!
    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()}
</%text></%call><p>The decorator can be used with top-level defs as well as nested defs.  Note that when calling a top-level def from the <code><%text filter='h'>Template</%text></code> api, i.e. <code><%text filter='h'>template.get_def('somedef').render()</%text></code>, the decorator has to write the output to the <code><%text filter='h'>context</%text></code>, i.e. as in the first example.  The return value gets discarded.
</p>


</%call>
</%call>
</html>