Mercurial > genshi > mirror

annotate doc/filters.txt @ 510:1bdccd3bda00 trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Use syntax highlighting on all the other doc pages, too.
author cmlenz
date Wed, 06 Jun 2007 10:41:41 +0000
parents 1cc1c38c6d6d
children 9e11fa7f4603
rev   line source
438
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
1 .. -*- mode: rst; encoding: utf-8 -*-
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
2
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
3 ==============
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
4 Stream Filters
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
5 ==============
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
6
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
7 `Markup Streams`_ showed how to write filters and how they are applied to
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
8 markup streams. This page describes the features of the various filters that
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
9 come with Genshi itself.
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
10
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
11 .. _`Markup Streams`: streams.html
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
12
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
13 .. contents:: Contents
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
14 :depth: 1
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
15 .. sectnum::
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
16
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
17
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
18 HTML Form Filler
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
19 ================
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
20
505
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
21 The filter ``genshi.filters.html.HTMLFormFiller`` can automatically populate an
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
22 HTML form from values provided as a simple dictionary. When using thi filter,
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
23 you can basically omit any ``value``, ``selected``, or ``checked`` attributes
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
24 from form controls in your templates, and let the filter do all that work for
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
25 you.
438
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
26
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
27 ``HTMLFormFiller`` takes a dictionary of data to populate the form with, where
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
28 the keys should match the names of form elements, and the values determine the
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 505
diff changeset
29 values of those controls. For example:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 505
diff changeset
30
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 505
diff changeset
31 .. code-block:: pycon
438
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
32
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
33 >>> from genshi.filters import HTMLFormFiller
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
34 >>> from genshi.template import MarkupTemplate
505
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
35
438
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
36 >>> template = MarkupTemplate("""<form>
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
37 ... <p>
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
38 ... <label>User name:
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
39 ... <input type="text" name="username" />
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
40 ... </label><br />
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
41 ... <label>Password:
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
42 ... <input type="password" name="password" />
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
43 ... </label><br />
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
44 ... <label>
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
45 ... <input type="checkbox" name="remember" /> Remember me
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
46 ... </label>
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
47 ... </p>
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
48 ... </form>""")
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
49 >>> filler = HTMLFormFiller(data=dict(username='john', remember=True))
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
50 >>> print template.generate() | filler
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
51 <form>
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
52 <p>
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
53 <label>User name:
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
54 <input type="text" name="username" value="john"/>
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
55 </label><br/>
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
56 <label>Password:
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
57 <input type="password" name="password"/>
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
58 </label><br/>
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
59 <label>
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
60 <input type="checkbox" name="remember" checked="checked"/> Remember me
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
61 </label>
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
62 </p>
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
63 </form>
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
64
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
65 .. note:: This processing is done without in any way reparsing the template
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
66 output. As any stream filter it operates after the template output is
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
67 generated but *before* that output is actually serialized.
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
68
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
69 The filter will of course also handle radio buttons as well as ``<select>`` and
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
70 ``<textarea>`` elements. For radio buttons to be marked as checked, the value in
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
71 the data dictionary needs to match the ``value`` attribute of the ``<input>``
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
72 element, or evaluate to a truth value if the element has no such attribute. For
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
73 options in a ``<select>`` box to be marked as selected, the value in the data
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
74 dictionary needs to match the ``value`` attribute of the ``<option>`` element,
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
75 or the text content of the option if it has no ``value`` attribute. Password and
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
76 file input fields are not populated, as most browsers would ignore that anyway
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
77 for security reasons.
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
78
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
79 You'll want to make sure that the values in the data dictionary have already
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
80 been converted to strings. While the filter may be able to deal with non-string
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
81 data in some cases (such as check boxes), in most cases it will either not
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
82 attempt any conversion or not produce the desired results.
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
83
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
84 You can restrict the form filler to operate only on a specific ``<form>`` by
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
85 passing either the ``id`` or the ``name`` keyword argument to the initializer.
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
86 If either of those is specified, the filter will only apply to form tags with
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
87 an attribute matching the specified value.
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
88
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
89
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
90 HTML Sanitizer
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
91 ==============
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
92
505
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
93 The filter ``genshi.filters.html.HTMLSanitizer`` filter can be used to clean up
438
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
94 user-submitted HTML markup, removing potentially dangerous constructs that could
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 505
diff changeset
95 be used for various kinds of abuse, such as cross-site scripting (XSS) attacks:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 505
diff changeset
96
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 505
diff changeset
97 .. code-block:: pycon
438
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
98
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
99 >>> from genshi.filters import HTMLSanitizer
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
100 >>> from genshi.input import HTML
505
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
101
438
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
102 >>> html = HTML("""<div>
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
103 ... <p>Innocent looking text.</p>
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
104 ... <script>alert("Danger: " + document.cookie)</script>
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
105 ... </div>""")
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
106 >>> sanitize = HTMLSanitizer()
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
107 >>> print html | sanitize
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
108 <div>
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
109 <p>Innocent looking text.</p>
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
110 </div>
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
111
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
112 In this example, the ``<script>`` tag was removed from the output.
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
113
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
114 You can determine which tags and attributes should be allowed by initializing
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
115 the filter with corresponding sets. See the API documentation for more
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
116 information.
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
117
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
118 Inline ``style`` attributes are forbidden by default. If you allow them, the
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
119 filter will still perform sanitization on the contents any encountered inline
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
120 styles: the proprietary ``expression()`` function (supported only by Internet
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
121 Explorer) is removed, and any property using an ``url()`` which a potentially
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 505
diff changeset
122 dangerous URL scheme (such as ``javascript:``) are also stripped out:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 505
diff changeset
123
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 505
diff changeset
124 .. code-block:: pycon
438
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
125
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
126 >>> from genshi.filters import HTMLSanitizer
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
127 >>> from genshi.input import HTML
505
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
128
438
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
129 >>> html = HTML("""<div>
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
130 ... <br style="background: url(javascript:alert(document.cookie); color: #000" />
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
131 ... </div>""")
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
132 >>> sanitize = HTMLSanitizer(safe_attrs=HTMLSanitizer.SAFE_ATTRS | set(['style']))
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
133 >>> print html | sanitize
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
134 <div>
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
135 <br style="color: #000"/>
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
136 </div>
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
137
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
138 .. warning:: You should probably not rely on the ``style`` filtering, as
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
139 sanitizing mixed HTML, CSS, and Javascript is very complicated and
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
140 suspect to various browser bugs. If you can somehow get away with
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
141 not allowing inline styles in user-submitted content, that would
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents:
diff changeset
142 definitely be the safer route to follow.
505
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
143
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
144
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
145 Transformer
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
146 ===========
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
147
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
148 The filter ``genshi.filters.transform.Transformer`` provides a convenient way to
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
149 transform or otherwise work with markup event streams. It allows you to specify
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
150 which parts of the stream you're interested in with XPath expressions, and then
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 505
diff changeset
151 attach a variety of transformations to the parts that match:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 505
diff changeset
152
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 505
diff changeset
153 .. code-block:: pycon
505
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
154
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
155 >>> from genshi.builder import tag
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
156 >>> from genshi.core import TEXT
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
157 >>> from genshi.filters import Transformer
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
158 >>> from genshi.input import HTML
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
159
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
160 >>> html = HTML('''<html>
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
161 ... <head><title>Some Title</title></head>
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
162 ... <body>
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
163 ... Some <em>body</em> text.
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
164 ... </body>
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
165 ... </html>''')
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
166
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
167 >>> print html | Transformer('body//em').apply(unicode.upper, TEXT) \
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
168 ... .unwrap().wrap(tag.u)
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
169 <html>
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
170 <head><title>Some Title</title></head>
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
171 <body>
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
172 Some <u>BODY</u> text.
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
173 </body>
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
174 </html>
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
175
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
176 This example sets up a transformation that:
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
177
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
178 1. matches any `<em>` element anywhere in the body,
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
179 2. uppercases any text nodes in the element,
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
180 3. strips off the `<em>` start and close tags, and
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
181 4. wraps the content in a `<u>` tag.
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
182
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
183 A number of commonly useful transformations are available for this filter.
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
184 Please consult the API documentation a complete list.
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
185
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
186 In addition, you can also perform custom transformations. For example, the
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 505
diff changeset
187 following defines a transformation that changes the name of a tag:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 505
diff changeset
188
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 505
diff changeset
189 .. code-block:: pycon
505
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
190
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
191 >>> from genshi import QName
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
192 >>> from genshi.filters.transform import ENTER, EXIT
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
193
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
194 >>> class RenameTransformation(object):
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
195 ... def __init__(self, name):
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
196 ... self.name = QName(name)
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
197 ... def __call__(self, stream):
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
198 ... for mark, (kind, data, pos) in stream:
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
199 ... if mark is ENTER:
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
200 ... data = self.name, data[1]
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
201 ... elif mark is EXIT:
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
202 ... data = self.name
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
203 ... yield mark, (kind, data, pos)
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
204
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
205 A transformation can be any callable object that accepts an augmented event
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
206 stream. In this case we define a class, so that we can initialize it with the
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
207 tag name.
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
208
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
209 Custom transformations can be applied using the `|` operator on the transformer
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 505
diff changeset
210 instance:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 505
diff changeset
211
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 505
diff changeset
212 .. code-block:: pycon
505
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
213
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
214 >>> xform = Transformer('body//em').apply(unicode.upper, TEXT)
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
215 >>> xform |= RenameTransformation('u')
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
216 >>> print html | xform
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
217 <html>
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
218 <head><title>Some Title</title></head>
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
219 <body>
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
220 Some <u>BODY</u> text.
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
221 </body>
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
222 </html>
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
223
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 505
diff changeset
224 .. note:: The transformation filter was added in Genshi 0.5.
505
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
225
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
226
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
227 Translator
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
228 ==========
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
229
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
230 The ``genshi.filters.i18n.Translator`` filter implements basic support for
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
231 internationalizing and localizing templates. When used as a filter, it
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
232 translates a configurable set of text nodes and attribute values using a
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
233 ``gettext``-style translation function.
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
234
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
235 The ``Translator`` class also defines the ``extract`` class method, which can
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
236 be used to extract localizable messages from a template.
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
237
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
238 Please refer to the API documentation for more information on this filter.
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 505
diff changeset
239
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 505
diff changeset
240 .. note:: The translation filter was added in Genshi 0.4.
Copyright (C) 2012-2017 Edgewall Software