root/branches/cherrypy-2.x/docs/book/xml/builtinfilters.xml

<?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="builtinfilters">
    <title>Builtin Filters</title>
    <section id="baseurlfilter">
        <title>baseurlfilter</title>
        <para>The baseurlfilter changes the base url of a request. It is useful for running CherryPy
        behind Apache with mod_rewrite.</para>
        <para>The baseurlfilter has the following configuration options</para>
        <itemizedlist>
            <listitem>
                <para>base_url_filter.base_url</para>
            </listitem>
            <listitem>
                <para>base_url_filter.use_x_forwarded_host</para>
            </listitem>
        </itemizedlist>
    </section>
    <section id="cachefilter">
        <title>cachefilter</title>
        <para>The cachefilter stores responses in memory. If an identical request is subsequently
        made, then the cached response is output without calling the page handler.</para>
    </section>
    <section id="decodingfilter">
        <title>decodingfilter</title>
        <para>The decoding filter can be configured to automatically decode incoming requests.</para>
        <para>The decodingfilter has the following configuration options:</para>
        <itemizedlist>
            <listitem>
                <para>decoding_filter.encoding</para>
            </listitem>
        </itemizedlist>
    </section>
    <section id="encodingfilter">
        <title>encodingfilter</title>
        <para>The encodingfilter can be configured to automatically encode outgoing responses.</para>
        <para>The encodingfilter has the following configuration options:</para>
        <itemizedlist>
            <listitem>
                <para>encoding_filter.encoding: Force all text responses to be encoded with this
                encoding.</para>
            </listitem>
            <listitem>
                <para>encoding_filter.default_encoding: Default all text responses to this encoding (if
                the user-agent does not request otherwise).</para>
            </listitem>
        </itemizedlist>
    </section>
    <section id="gzipfilter">
        <title>gzipfilter</title>
        <para>The gzipfilter will automatically gzip outgoing requests, if it is supported by the
        client.</para>
        <para>The gzipfilter does not have any configuration options.</para>
    </section>
    <section id="logdebuginfofilter">
        <title>logdebuginfofilter</title>
        <para>The logdebuinfofilter adds debug information to each page. The filter is automatically
        turned on when "server.environment" is set to "development".</para>
        <para>The logdebuginfofilter has the following configuration options:</para>
        <itemizedlist>
            <listitem>
                <para>log_debug_info_filter.mime_types, ['text/html']</para>
            </listitem>
            <listitem>
                <para>log_debug_info_filter.log_as_comment, False</para>
            </listitem>
            <listitem>
                <para>log_debug_info_filter.log_build_time, True</para>
            </listitem>
            <listitem>
                <para>log_debug_info_filter.log_page_size, True</para>
            </listitem>
        </itemizedlist>
    </section>
    <section id="nsgmlsfilter">
        <title>nsgmlsfilter</title>
        <para>The nsgmlsfilter parses and validates SGML responses.</para>
    </section>
    <section id="sessionauthfilter">
        <title>sessionauthenticatefilter</title>
        <para>The sessionauthenticatefilter provides simple form-based authentication and access
        control.</para>
    </section>
    <section id="sessionfilter">
        <title>sessionfilter</title>
        <para> The Session Filter has its own section</para>
    </section>
    <section id="staticfilter">
        <title>staticfilter</title>
        <para>The static filter allows CherryPy to serve static files.</para>
        <para>The staticfilter has the following configuration options:</para>
        <itemizedlist>
            <listitem>
                <para>static_filter.file</para>
            </listitem>
            <listitem>
                <para>static_filter.dir</para>
            </listitem>
            <listitem>
                <para>static_filter.root</para>
            </listitem>
        </itemizedlist>
    </section>
    <section id="tidyfilter">
        <title>tidyfilter</title>
        <para>The tidyfilter cleans up returned html by running the response through Tidy.</para>
        <para>Note that we use the standalone Tidy tool rather than the python mxTidy module. This is
        because this module doesn't seem to be stable and it crashes on some HTML pages (which means
        that the server would also crash.)</para>
        <para>The tidyfilter has the following configuration options:</para>
        <itemizedlist>
            <listitem>
                <para>tidy_filter.tmp_dir</para>
            </listitem>
            <listitem>
                <para>tidy_filter.strict_xml, False</para>
            </listitem>
            <listitem>
                <para>tidy_filter.tidy_path</para>
            </listitem>
        </itemizedlist>
    </section>
    <section id="virtualhostfilter">
        <title>virtualhostfilter</title>
        <para>The virtualhostfilter changes the ObjectPath based on the Host. Use this filter when
        running multiple sites within one CP server.</para>
        <para>The virtualhostfilter has the following configuration options:</para>
        <itemizedlist>
            <listitem>
                <para>virtual_host_filter.prefix, '/'</para>
            </listitem>
        </itemizedlist>
    </section>
    <section id="wsgiappfilter">
        <title>wsgiappfilter</title>
        <para>The wsgiappfilter allows the application developer or deployer to mount
        WSGI-compatible applications and middleware to locations on the CherryPy
        object tree.</para>
        <para>Applications can be added to the tree by using the
            cherrypy.lib.cptools.WSGIApp convenience class to directly mount applications to the
            CherryPy tree.  You can also add an instance of the filter to a class's _cp_filters
            list.
        </para>
        <para>The cherrypy.lib.cptools.WSGIApp and WSGIAppFilter class contsructors takes the 
            following parameters:
        </para>
        <itemizedlist>
            <listitem>
                <para>wsgi_app (required) - the WSGI application callable.</para>
            </listitem>
            <listitem>
                <para>env_update - a optional dictionary of parameters used to update the WSGI environment.</para>
            </listitem>
        </itemizedlist>
    </section>
    <section id="xmlrpcfilter">
        <title>xmlrpcfilter</title>
        <para>The xmlrpcfilter converts XMLRPC to the CherryPy2 object system and vice-versa.</para>
        <para>PLEASE NOTE: before_request_body: Unmarshalls the posted data to a methodname and
        parameters. - These are stored in cherrypy.request.rpcMethod and .rpcParams - The method is
        also stored in cherrypy.request.path, so CP2 will find the right method to call for you,
        based on the root's position. before_finalize: Marshalls cherrypy.response.body to xmlrpc. -
        Until resolved: cherrypy.response.body must be a python source string; this string is
        'eval'ed to return the results. This will be resolved in the future. - Content-Type and
        Content-Length are set according to the new (marshalled) data</para>
        <para>The xmlrpcfilter does not have any configuration options.</para>
    </section>
</section>