Mercurial > genshi > mirror

annotate doc/filters.txt @ 720:acf7c5ee36e7 experimental-newctxt

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
newctxt branch: Merged revisions [678:835] via svnmerge from [source:trunk].
author cmlenz
date Fri, 11 Apr 2008 08:42:11 +0000
parents 4d486f15c986
children f33ecf3c319e
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
720
acf7c5ee36e7 newctxt branch: Merged revisions [678:835] via svnmerge from [source:trunk].
cmlenz
parents: 533
diff changeset
22 HTML form from values provided as a simple dictionary. When using this filter,
505
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
533
4d486f15c986 Thanks to Dave Abrahams for pointing out some deficiencies in the transformer
athomas
parents: 519
diff changeset
167 >>> print html | Transformer('body/em').map(unicode.upper, TEXT) \
519
9e11fa7f4603 Cut and copy transformer operations can now operate on selected attributes.
athomas
parents: 510
diff changeset
168 ... .unwrap().wrap(tag.u).end() \
9e11fa7f4603 Cut and copy transformer operations can now operate on selected attributes.
athomas
parents: 510
diff changeset
169 ... .select('body/u') \
9e11fa7f4603 Cut and copy transformer operations can now operate on selected attributes.
athomas
parents: 510
diff changeset
170 ... .prepend('underlined ')
505
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
171 <html>
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
172 <head><title>Some Title</title></head>
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
173 <body>
519
9e11fa7f4603 Cut and copy transformer operations can now operate on selected attributes.
athomas
parents: 510
diff changeset
174 Some <u>underlined BODY</u> text.
505
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
175 </body>
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
176 </html>
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 This example sets up a transformation that:
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
179
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
180 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
181 2. uppercases any text nodes in the element,
519
9e11fa7f4603 Cut and copy transformer operations can now operate on selected attributes.
athomas
parents: 510
diff changeset
182 3. strips off the `<em>` start and close tags,
9e11fa7f4603 Cut and copy transformer operations can now operate on selected attributes.
athomas
parents: 510
diff changeset
183 4. wraps the content in a `<u>` tag, and
533
4d486f15c986 Thanks to Dave Abrahams for pointing out some deficiencies in the transformer
athomas
parents: 519
diff changeset
184 5. inserts the text `underlined` inside the `<u>` tag.
505
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 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
187 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
188
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
189 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
190 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
191
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 505
diff changeset
192 .. code-block:: pycon
505
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 >>> from genshi import QName
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
195 >>> from genshi.filters.transform import ENTER, EXIT
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
196
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
197 >>> class RenameTransformation(object):
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
198 ... def __init__(self, name):
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
199 ... self.name = QName(name)
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
200 ... def __call__(self, stream):
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
201 ... for mark, (kind, data, pos) in stream:
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
202 ... if mark is ENTER:
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
203 ... data = self.name, data[1]
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
204 ... elif mark is EXIT:
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
205 ... data = self.name
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
206 ... yield mark, (kind, data, pos)
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
207
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
208 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
209 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
210 tag name.
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
211
533
4d486f15c986 Thanks to Dave Abrahams for pointing out some deficiencies in the transformer
athomas
parents: 519
diff changeset
212 Custom transformations can be applied using the `apply()` method of a
4d486f15c986 Thanks to Dave Abrahams for pointing out some deficiencies in the transformer
athomas
parents: 519
diff changeset
213 transformer instance:
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 505
diff changeset
214
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 505
diff changeset
215 .. code-block:: pycon
505
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
216
533
4d486f15c986 Thanks to Dave Abrahams for pointing out some deficiencies in the transformer
athomas
parents: 519
diff changeset
217 >>> xform = Transformer('body//em').map(unicode.upper, TEXT) \
4d486f15c986 Thanks to Dave Abrahams for pointing out some deficiencies in the transformer
athomas
parents: 519
diff changeset
218 >>> xform = xform.apply(RenameTransformation('u'))
505
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
219 >>> print html | xform
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
220 <html>
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
221 <head><title>Some Title</title></head>
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
222 <body>
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
223 Some <u>BODY</u> text.
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
224 </body>
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
225 </html>
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
226
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 505
diff changeset
227 .. 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
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 Translator
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
231 ==========
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
232
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
233 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
234 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
235 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
236 ``gettext``-style translation function.
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 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
239 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
240
1cc1c38c6d6d Add transformer/translator filters to the doc page on stream filters.
cmlenz
parents: 438
diff changeset
241 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
242
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 505
diff changeset
243 .. note:: The translation filter was added in Genshi 0.4.
Copyright (C) 2012-2017 Edgewall Software