|
438
|
1 .. -*- mode: rst; encoding: utf-8 -*-
|
|
|
2
|
|
|
3 ==============
|
|
|
4 Stream Filters
|
|
|
5 ==============
|
|
|
6
|
|
|
7 `Markup Streams`_ showed how to write filters and how they are applied to
|
|
|
8 markup streams. This page describes the features of the various filters that
|
|
|
9 come with Genshi itself.
|
|
|
10
|
|
|
11 .. _`Markup Streams`: streams.html
|
|
|
12
|
|
|
13 .. contents:: Contents
|
|
|
14 :depth: 1
|
|
|
15 .. sectnum::
|
|
|
16
|
|
|
17
|
|
|
18 HTML Form Filler
|
|
|
19 ================
|
|
|
20
|
|
|
21 The filter ``genshi.filters.HTMLFormFiller`` can automatically populate an HTML
|
|
|
22 form from values provided as a simple dictionary. When using thi filter, you can
|
|
|
23 basically omit any ``value``, ``selected``, or ``checked`` attributes from form
|
|
|
24 controls in your templates, and let the filter do all that work for you.
|
|
|
25
|
|
|
26 ``HTMLFormFiller`` takes a dictionary of data to populate the form with, where
|
|
|
27 the keys should match the names of form elements, and the values determine the
|
|
511
|
28 values of those controls. For example:
|
|
|
29
|
|
|
30 .. code-block:: pycon
|
|
438
|
31
|
|
|
32 >>> from genshi.filters import HTMLFormFiller
|
|
|
33 >>> from genshi.template import MarkupTemplate
|
|
|
34 >>> template = MarkupTemplate("""<form>
|
|
|
35 ... <p>
|
|
|
36 ... <label>User name:
|
|
|
37 ... <input type="text" name="username" />
|
|
|
38 ... </label><br />
|
|
|
39 ... <label>Password:
|
|
|
40 ... <input type="password" name="password" />
|
|
|
41 ... </label><br />
|
|
|
42 ... <label>
|
|
|
43 ... <input type="checkbox" name="remember" /> Remember me
|
|
|
44 ... </label>
|
|
|
45 ... </p>
|
|
|
46 ... </form>""")
|
|
|
47 >>> filler = HTMLFormFiller(data=dict(username='john', remember=True))
|
|
|
48 >>> print template.generate() | filler
|
|
|
49 <form>
|
|
|
50 <p>
|
|
|
51 <label>User name:
|
|
|
52 <input type="text" name="username" value="john"/>
|
|
|
53 </label><br/>
|
|
|
54 <label>Password:
|
|
|
55 <input type="password" name="password"/>
|
|
|
56 </label><br/>
|
|
|
57 <label>
|
|
|
58 <input type="checkbox" name="remember" checked="checked"/> Remember me
|
|
|
59 </label>
|
|
|
60 </p>
|
|
|
61 </form>
|
|
|
62
|
|
|
63 .. note:: This processing is done without in any way reparsing the template
|
|
|
64 output. As any stream filter it operates after the template output is
|
|
|
65 generated but *before* that output is actually serialized.
|
|
|
66
|
|
|
67 The filter will of course also handle radio buttons as well as ``<select>`` and
|
|
|
68 ``<textarea>`` elements. For radio buttons to be marked as checked, the value in
|
|
|
69 the data dictionary needs to match the ``value`` attribute of the ``<input>``
|
|
|
70 element, or evaluate to a truth value if the element has no such attribute. For
|
|
|
71 options in a ``<select>`` box to be marked as selected, the value in the data
|
|
|
72 dictionary needs to match the ``value`` attribute of the ``<option>`` element,
|
|
|
73 or the text content of the option if it has no ``value`` attribute. Password and
|
|
|
74 file input fields are not populated, as most browsers would ignore that anyway
|
|
|
75 for security reasons.
|
|
|
76
|
|
|
77 You'll want to make sure that the values in the data dictionary have already
|
|
|
78 been converted to strings. While the filter may be able to deal with non-string
|
|
|
79 data in some cases (such as check boxes), in most cases it will either not
|
|
|
80 attempt any conversion or not produce the desired results.
|
|
|
81
|
|
|
82 You can restrict the form filler to operate only on a specific ``<form>`` by
|
|
|
83 passing either the ``id`` or the ``name`` keyword argument to the initializer.
|
|
|
84 If either of those is specified, the filter will only apply to form tags with
|
|
|
85 an attribute matching the specified value.
|
|
|
86
|
|
|
87
|
|
|
88 HTML Sanitizer
|
|
|
89 ==============
|
|
|
90
|
|
|
91 The filter ``genshi.filters.HTMLSanitizer`` filter can be used to clean up
|
|
|
92 user-submitted HTML markup, removing potentially dangerous constructs that could
|
|
511
|
93 be used for various kinds of abuse, such as cross-site scripting (XSS) attacks:
|
|
|
94
|
|
|
95 .. code-block:: pycon
|
|
438
|
96
|
|
|
97 >>> from genshi.filters import HTMLSanitizer
|
|
|
98 >>> from genshi.input import HTML
|
|
|
99 >>> html = HTML("""<div>
|
|
|
100 ... <p>Innocent looking text.</p>
|
|
|
101 ... <script>alert("Danger: " + document.cookie)</script>
|
|
|
102 ... </div>""")
|
|
|
103 >>> sanitize = HTMLSanitizer()
|
|
|
104 >>> print html | sanitize
|
|
|
105 <div>
|
|
|
106 <p>Innocent looking text.</p>
|
|
|
107 </div>
|
|
|
108
|
|
|
109 In this example, the ``<script>`` tag was removed from the output.
|
|
|
110
|
|
|
111 You can determine which tags and attributes should be allowed by initializing
|
|
|
112 the filter with corresponding sets. See the API documentation for more
|
|
|
113 information.
|
|
|
114
|
|
|
115 Inline ``style`` attributes are forbidden by default. If you allow them, the
|
|
|
116 filter will still perform sanitization on the contents any encountered inline
|
|
|
117 styles: the proprietary ``expression()`` function (supported only by Internet
|
|
|
118 Explorer) is removed, and any property using an ``url()`` which a potentially
|
|
511
|
119 dangerous URL scheme (such as ``javascript:``) are also stripped out:
|
|
|
120
|
|
|
121 .. code-block:: pycon
|
|
438
|
122
|
|
|
123 >>> from genshi.filters import HTMLSanitizer
|
|
|
124 >>> from genshi.input import HTML
|
|
|
125 >>> html = HTML("""<div>
|
|
|
126 ... <br style="background: url(javascript:alert(document.cookie); color: #000" />
|
|
|
127 ... </div>""")
|
|
|
128 >>> sanitize = HTMLSanitizer(safe_attrs=HTMLSanitizer.SAFE_ATTRS | set(['style']))
|
|
|
129 >>> print html | sanitize
|
|
|
130 <div>
|
|
|
131 <br style="color: #000"/>
|
|
|
132 </div>
|
|
|
133
|
|
|
134 .. warning:: You should probably not rely on the ``style`` filtering, as
|
|
|
135 sanitizing mixed HTML, CSS, and Javascript is very complicated and
|
|
|
136 suspect to various browser bugs. If you can somehow get away with
|
|
|
137 not allowing inline styles in user-submitted content, that would
|
|
|
138 definitely be the safer route to follow.
|
|
511
|
139
|
|
|
140
|
|
|
141 Translator
|
|
|
142 ==========
|
|
|
143
|
|
|
144 The ``genshi.filters.i18n.Translator`` filter implements basic support for
|
|
|
145 internationalizing and localizing templates. When used as a filter, it
|
|
|
146 translates a configurable set of text nodes and attribute values using a
|
|
|
147 ``gettext``-style translation function.
|
|
|
148
|
|
|
149 The ``Translator`` class also defines the ``extract`` class method, which can
|
|
|
150 be used to extract localizable messages from a template.
|
|
|
151
|
|
|
152 Please refer to the API documentation for more information on this filter.
|
|
|
153
|
|
|
154 .. note:: The translation filter was added in Genshi 0.4.
|
