| 1 |
<?xml version="1.0" encoding="UTF-8"?> |
|---|
| 2 |
<section xmlns:db="http://docbook.org/docbook-ng" |
|---|
| 3 |
xmlns:xi="http://www.w3.org/2001/XInclude" |
|---|
| 4 |
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" |
|---|
| 5 |
xml:id="globaloverviewcherrypy"> |
|---|
| 6 |
<title>Filters</title> |
|---|
| 7 |
<para>Filters are one of the most important features of CherryPy. The |
|---|
| 8 |
CherryPy core can call user-defined functions at specific points during |
|---|
| 9 |
request processing; a filter is a class which defines those functions. |
|---|
| 10 |
Filters are designed to be called at a low level—the HTTP request/response |
|---|
| 11 |
level—and therefore should only be used in that context.</para> |
|---|
| 12 |
<para>CherryPy comes with a set of built-in filters, but they're turned off |
|---|
| 13 |
by default. To enable them, you must use the configuration system as |
|---|
| 14 |
follows:</para> |
|---|
| 15 |
<itemizedlist> |
|---|
| 16 |
<listitem>First you must decide where to enable the filter. CherryPy |
|---|
| 17 |
maintains a tree of published objects; you must decide which branch should |
|---|
| 18 |
use the filter. The filter will then apply to that branch and all its |
|---|
| 19 |
children in the tree. Remember that the tree is accessed as a path and |
|---|
| 20 |
then mapped internally by the core to match the correct exposed |
|---|
| 21 |
object.</listitem> |
|---|
| 22 |
<listitem>Second in the config file you must turn the filter on like this |
|---|
| 23 |
: <code>filterName.on = True</code></listitem> |
|---|
| 24 |
</itemizedlist> |
|---|
| 25 |
<example> |
|---|
| 26 |
<title>Turning on a default filter</title> |
|---|
| 27 |
<programlisting linenumbering="numbered"> |
|---|
| 28 |
[/entries/view] |
|---|
| 29 |
tidyFilter.on = True |
|---|
| 30 |
tidyFilter.tmpDir = "/tmp" |
|---|
| 31 |
tidyFilter.strictXml = True |
|---|
| 32 |
</programlisting> |
|---|
| 33 |
</example> |
|---|
| 34 |
<para>On the first line we define that the tidy filter will be used by the |
|---|
| 35 |
core whenever the path <code>/entries/view</code> (or one of its sub-paths) |
|---|
| 36 |
is called. On the two last lines we also define some parameters used by the |
|---|
| 37 |
filter.</para> |
|---|
| 38 |
<para>CherryPy lets you write your own filters as we will see in the |
|---|
| 39 |
developer reference chapter. However, the way to use them is different from |
|---|
| 40 |
the default filters. You do not declare custom filters within the |
|---|
| 41 |
configuration file; instead, use the <code>_cpFilterList</code> attribute in |
|---|
| 42 |
your source code:</para> |
|---|
| 43 |
<example> |
|---|
| 44 |
<title>Using a non default filter</title> |
|---|
| 45 |
<programlisting linenumbering="numbered"> |
|---|
| 46 |
import cherrypy |
|---|
| 47 |
from myfiltermodule import MyFilterClass |
|---|
| 48 |
|
|---|
| 49 |
class Entry: |
|---|
| 50 |
_cpFilterList = [ MyFilterClass() ] |
|---|
| 51 |
def view(self, id): |
|---|
| 52 |
# do suff... |
|---|
| 53 |
view.exposed = True |
|---|
| 54 |
|
|---|
| 55 |
class Root: pass |
|---|
| 56 |
|
|---|
| 57 |
cherrypy.root = Root() |
|---|
| 58 |
cherrypy.root.entries = Entry() |
|---|
| 59 |
cherrypy.server.start() |
|---|
| 60 |
</programlisting> |
|---|
| 61 |
</example> |
|---|
| 62 |
<para>As all objects below <code>cherrypy.root.entries</code> will inherit |
|---|
| 63 |
the filter, there is no need to re-specify it in each |
|---|
| 64 |
<code>_cpFilterList</code> underneath.</para> |
|---|
| 65 |
<para>Keep in mind that the user-defined filters are called in the order you |
|---|
| 66 |
add them to the list.</para> |
|---|
| 67 |
</section> |
|---|
