cmlenz@438: .. -*- mode: rst; encoding: utf-8 -*-
cmlenz@438: 
cmlenz@438: ==============
cmlenz@438: Stream Filters
cmlenz@438: ==============
cmlenz@438: 
cmlenz@438: `Markup Streams`_ showed how to write filters and how they are applied to
cmlenz@438: markup streams. This page describes the features of the various filters that
cmlenz@438: come with Genshi itself.
cmlenz@438: 
cmlenz@438: .. _`Markup Streams`: streams.html
cmlenz@438: 
cmlenz@438: .. contents:: Contents
cmlenz@438:    :depth: 1
cmlenz@438: .. sectnum::
cmlenz@438: 
cmlenz@438: 
cmlenz@438: HTML Form Filler
cmlenz@438: ================
cmlenz@438: 
cmlenz@438: The filter ``genshi.filters.HTMLFormFiller`` can automatically populate an HTML
cmlenz@438: form from values provided as a simple dictionary. When using thi filter, you can
cmlenz@438: basically omit any ``value``, ``selected``, or ``checked`` attributes from form
cmlenz@438: controls in your templates, and let the filter do all that work for you.
cmlenz@438: 
cmlenz@438: ``HTMLFormFiller`` takes a dictionary of data to populate the form with, where
cmlenz@438: the keys should match the names of form elements, and the values determine the
cmlenz@438: values of those controls. For example::
cmlenz@438: 
cmlenz@438:   >>> from genshi.filters import HTMLFormFiller
cmlenz@438:   >>> from genshi.template import MarkupTemplate
cmlenz@438:   >>> template = MarkupTemplate("""<form>
cmlenz@438:   ...   <p>
cmlenz@438:   ...     <label>User name:
cmlenz@438:   ...       <input type="text" name="username" />
cmlenz@438:   ...     </label><br />
cmlenz@438:   ...     <label>Password:
cmlenz@438:   ...       <input type="password" name="password" />
cmlenz@438:   ...     </label><br />
cmlenz@438:   ...     <label>
cmlenz@438:   ...       <input type="checkbox" name="remember" /> Remember me
cmlenz@438:   ...     </label>
cmlenz@438:   ...   </p>
cmlenz@438:   ... </form>""")
cmlenz@438:   >>> filler = HTMLFormFiller(data=dict(username='john', remember=True))
cmlenz@438:   >>> print template.generate() | filler
cmlenz@438:   <form>
cmlenz@438:     <p>
cmlenz@438:       <label>User name:
cmlenz@438:         <input type="text" name="username" value="john"/>
cmlenz@438:       </label><br/>
cmlenz@438:       <label>Password:
cmlenz@438:         <input type="password" name="password"/>
cmlenz@438:       </label><br/>
cmlenz@438:       <label>
cmlenz@438:         <input type="checkbox" name="remember" checked="checked"/> Remember me
cmlenz@438:       </label>
cmlenz@438:     </p>
cmlenz@438:   </form>
cmlenz@438: 
cmlenz@438: .. note:: This processing is done without in any way reparsing the template
cmlenz@438:           output. As any stream filter it operates after the template output is
cmlenz@438:           generated but *before* that output is actually serialized.
cmlenz@438: 
cmlenz@438: The filter will of course also handle radio buttons as well as ``<select>`` and
cmlenz@438: ``<textarea>`` elements. For radio buttons to be marked as checked, the value in
cmlenz@438: the data dictionary needs to match the ``value`` attribute of the ``<input>``
cmlenz@438: element, or evaluate to a truth value if the element has no such attribute. For
cmlenz@438: options in a ``<select>`` box to be marked as selected, the value in the data
cmlenz@438: dictionary needs to match the ``value`` attribute of the ``<option>`` element,
cmlenz@438: or the text content of the option if it has no ``value`` attribute. Password and
cmlenz@438: file input fields are not populated, as most browsers would ignore that anyway
cmlenz@438: for security reasons.
cmlenz@438: 
cmlenz@438: You'll want to make sure that the values in the data dictionary have already
cmlenz@438: been converted to strings. While the filter may be able to deal with non-string
cmlenz@438: data in some cases (such as check boxes), in most cases it will either not
cmlenz@438: attempt any conversion or not produce the desired results.
cmlenz@438: 
cmlenz@438: You can restrict the form filler to operate only on a specific ``<form>`` by
cmlenz@438: passing either the ``id`` or the ``name`` keyword argument to the initializer.
cmlenz@438: If either of those is specified, the filter will only apply to form tags with
cmlenz@438: an attribute matching the specified value.
cmlenz@438: 
cmlenz@438: 
cmlenz@438: HTML Sanitizer
cmlenz@438: ==============
cmlenz@438: 
cmlenz@438: The filter ``genshi.filters.HTMLSanitizer`` filter can be used to clean up
cmlenz@438: user-submitted HTML markup, removing potentially dangerous constructs that could
cmlenz@438: be used for various kinds of abuse, such as cross-site scripting (XSS) attacks::
cmlenz@438: 
cmlenz@438:   >>> from genshi.filters import HTMLSanitizer
cmlenz@438:   >>> from genshi.input import HTML
cmlenz@438:   >>> html = HTML("""<div>
cmlenz@438:   ...   <p>Innocent looking text.</p>
cmlenz@438:   ...   <script>alert("Danger: " + document.cookie)</script>
cmlenz@438:   ... </div>""")
cmlenz@438:   >>> sanitize = HTMLSanitizer()
cmlenz@438:   >>> print html | sanitize
cmlenz@438:   <div>
cmlenz@438:     <p>Innocent looking text.</p>
cmlenz@438:   </div>
cmlenz@438: 
cmlenz@438: In this example, the ``<script>`` tag was removed from the output.
cmlenz@438: 
cmlenz@438: You can determine which tags and attributes should be allowed by initializing
cmlenz@438: the filter with corresponding sets. See the API documentation for more
cmlenz@438: information.
cmlenz@438: 
cmlenz@438: Inline ``style`` attributes are forbidden by default. If you allow them, the
cmlenz@438: filter will still perform sanitization on the contents any encountered inline
cmlenz@438: styles: the proprietary ``expression()`` function (supported only by Internet
cmlenz@438: Explorer) is removed, and any property using an ``url()`` which a potentially
cmlenz@438: dangerous URL scheme (such as ``javascript:``) are also stripped out::
cmlenz@438: 
cmlenz@438:   >>> from genshi.filters import HTMLSanitizer
cmlenz@438:   >>> from genshi.input import HTML
cmlenz@438:   >>> html = HTML("""<div>
cmlenz@438:   ...   <br style="background: url(javascript:alert(document.cookie); color: #000" />
cmlenz@438:   ... </div>""")
cmlenz@438:   >>> sanitize = HTMLSanitizer(safe_attrs=HTMLSanitizer.SAFE_ATTRS | set(['style']))
cmlenz@438:   >>> print html | sanitize
cmlenz@438:   <div>
cmlenz@438:     <br style="color: #000"/>
cmlenz@438:   </div>
cmlenz@438: 
cmlenz@438: .. warning:: You should probably not rely on the ``style`` filtering, as
cmlenz@438:              sanitizing mixed HTML, CSS, and Javascript is very complicated and
cmlenz@438:              suspect to various browser bugs. If you can somehow get away with
cmlenz@438:              not allowing inline styles in user-submitted content, that would
cmlenz@438:              definitely be the safer route to follow.