<?xml version="1.0" encoding="UTF-8"?>
<section xmlns:db="http://docbook.org/docbook-ng"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
         xml:id="globaloverviewcherrypy">
  <title>Filters</title>
  <para>Filters are one of the most important features of CherryPy. The
  CherryPy core can call user-defined functions at specific points during
  request processing; a filter is a class which defines those functions.
  Filters are designed to be called at a low level—the HTTP request/response
  level—and therefore should only be used in that context.</para>
  <para>CherryPy comes with a set of built-in filters, but they're turned off
  by default. To enable them, you must use the configuration system as
  follows:</para>
  <itemizedlist>
    <listitem>First you must decide where to enable the filter. CherryPy
    maintains a tree of published objects; you must decide which branch should
    use the filter. The filter will then apply to that branch and all its
    children in the tree. Remember that the tree is accessed as a path and
    then mapped internally by the core to match the correct exposed
    object.</listitem>
    <listitem>Second in the config file you must turn the filter on like this
    : <code>filterName.on = True</code></listitem>
  </itemizedlist>
  <example>
    <title>Turning on a default filter</title>
    <programlisting linenumbering="numbered">
        [/entries/view]
        tidyFilter.on = True
        tidyFilter.tmpDir = "/tmp"
        tidyFilter.strictXml = True
      </programlisting>
  </example>
  <para>On the first line we define that the tidy filter will be used by the
  core whenever the path <code>/entries/view</code> (or one of its sub-paths)
  is called. On the two last lines we also define some parameters used by the
  filter.</para>
  <para>CherryPy lets you write your own filters as we will see in the
  developer reference chapter. However, the way to use them is different from
  the default filters. You do not declare custom filters within the
  configuration file; instead, use the <code>_cpFilterList</code> attribute in
  your source code:</para>
  <example>
    <title>Using a non default filter</title>
    <programlisting linenumbering="numbered">
        import cherrypy
        from myfiltermodule import MyFilterClass
        
        class Entry:
          _cpFilterList = [ MyFilterClass() ]
          def view(self, id): 
            # do suff...
          view.exposed = True
        
        class Root: pass
        
        cherrypy.root = Root()
        cherrypy.root.entries = Entry()
        cherrypy.server.start()
      </programlisting>
  </example>
  <para>As all objects below <code>cherrypy.root.entries</code> will inherit
  the filter, there is no need to re-specify it in each
  <code>_cpFilterList</code> underneath.</para>
  <para>Keep in mind that the user-defined filters are called in the order you
  add them to the list.</para>
</section>