7.9 Ouput Filtering and #filter

Syntax:

#filter FILTER_CLASS_NAME
#filter $PLACEHOLDER_TO_A_FILTER_INSTANCE
#filter None

Output from $placeholders is passed through an ouput filter. The default filter merely returns a string representation of the placeholder value, unless the value is None, in which case the filter returns an empty string. Only top-level placeholders invoke the filter; placeholders inside expressions do not.

Certain filters take optional arguments to modify their behaviour. To pass arguments, use the long placeholder syntax and precede each filter argument by a comma. By convention, filter arguments don't take a $ prefix, to avoid clutter in the placeholder tag which already has plenty of dollar signs. For instance, the MaxLen filter takes an argument 'maxlen':

${placeholderName, maxlen=20}
${functionCall($functionArg), maxlen=$myMaxLen}

To change the output filter, use the 'filter' keyword to the Template class constructor, or the #filter directive at runtime (details below). You may use #filter as often as you wish to switch between several filters, if certain $placeholders need one filter and other $placeholders need another.

The standard filters are in the module Cheetah.Filters. Cheetah currently provides:

Filter
The default filter, which converts None to '' and everything else to str(whateverItIs). This is the base class for all other filters, and the minimum behaviour for all filters distributed with Cheetah.

ReplaceNone
Same.

MaxLen
Same, but truncate the value if it's longer than a certain length. Use the 'maxlen' filter argument to specify the length, as in the examples above. If you don't specify 'maxlen', the value will not be truncated.

Pager
Output a "pageful" of a long string. After the page, output HTML hyperlinks to the previous and next pages. This filter uses several filter arguments and environmental variables, which have not been documented yet.

WebSafe
Same as default, but convert HTML-sensitive characters ('

', '&', '

') to HTML entities so that the browser will display them literally rather than interpreting them as HTML tags. This is useful with database values or user input that may contain sensitive characters. But if your values contain embedded HTML tags you want to preserve, you do not want this filter.

The filter argument 'also' may be used to specify additional characters to escape. For instance, say you want to ensure a value displays all on one line. Escape all spaces in the value with '&nbsp', the non-breaking space:

${$country, also=' '}}

To switch filters using a class object, pass the class using the filter argument to the Template constructor, or via a placeholder to the #filter directive: #filter $myFilterClass. The class must be a subclass of Cheetah.Filters.Filter. When passing a class object, the value of filtersLib does not matter, and it does not matter where the class was defined.

To switch filters by name, pass the name of the class as a string using the filter argument to the Template constructor, or as a bare word (without quotes) to the #filter directive: #filter TheFilter. The class will be looked up in the filtersLib.

The filtersLib is a module containing filter classes, by default Cheetah.Filters. All classes in the module that are subclasses of Cheetah.Filters.Filter are considered filters. If your filters are in another module, pass the module object as the filtersLib argument to the Template constructor.

Writing a custom filter is easy: just override the .filter method.

    def filter(self, val, **kw):     # Returns a string.

Return the string that should be output for `val'. `val' may be any type. Most filters return `' for None. Cheetah passes one keyword argument: kw['rawExpr'] is the placeholder name as it appears in the template definition, including all subscripts and arguments. If you use the long placeholder syntax, any options you pass appear as keyword arguments. Again, the return value must be a string.

You can always switch back to the default filter this way: #filter None. This is easy to remember because "no filter" means the default filter, and because None happens to be the only object the default filter treats specially.

We are considering additional filters; see http://webware.colorstudy.net/twiki/bin/view/Cheetah/MoreFiltersfor the latest ideas.