genshi/genshi-test: doc/filters.txt annotate

annotate doc/filters.txt @ 938:a5a1c9a11135 tip

update tags

author	convert-repo
date	Tue, 31 May 2011 20:05:15 +0000
parents	4376010bb97e
children

rev	line source
438 6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	1 .. -- mode: rst; encoding: utf-8 --
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	2
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	3 ==============
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	4 Stream Filters
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	5 ==============
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	6
6fd7e4dc0318 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
6fd7e4dc0318 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
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	9 come with Genshi itself.
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	10
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	11 .. _`Markup Streams`: streams.html
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	12
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	13 .. contents:: Contents
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	14 :depth: 1
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	15 .. sectnum::
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	16
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	17
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	18 HTML Form Filler
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	19 ================
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	20
505 a332cb9c70d5 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
683 96f35907853e Fix typo: thi -> this. jruigrok parents: 533 diff changeset	22 HTML form from values provided as a simple dictionary. When using this filter,
505 a332cb9c70d5 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
a332cb9c70d5 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
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	25 you.
438 6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	26
6fd7e4dc0318 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
6fd7e4dc0318 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 ca7d707d51b0 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 505 diff changeset	29 values of those controls. For example:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 505 diff changeset	30
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 505 diff changeset	31 .. code-block:: pycon
438 6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	32
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	33 >>> from genshi.filters import HTMLFormFiller
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	34 >>> from genshi.template import MarkupTemplate
505 a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	35
438 6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	36 >>> template = MarkupTemplate("""<form>
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	37 ... <p>
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	38 ... <label>User name:
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	39 ... <input type="text" name="username" />
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	40 ... </label><br />
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	41 ... <label>Password:
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	42 ... <input type="password" name="password" />
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	43 ... </label><br />
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	44 ... <label>
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	45 ... <input type="checkbox" name="remember" /> Remember me
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	46 ... </label>
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	47 ... </p>
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	48 ... </form>""")
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	49 >>> filler = HTMLFormFiller(data=dict(username='john', remember=True))
853 4376010bb97e Convert a bunch of print statements to py3k compatible syntax. cmlenz parents: 683 diff changeset	50 >>> print(template.generate() \| filler)
438 6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	51 <form>
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	52 <p>
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	53 <label>User name:
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	54 <input type="text" name="username" value="john"/>
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	55 </label><br/>
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	56 <label>Password:
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	57 <input type="password" name="password"/>
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	58 </label><br/>
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	59 <label>
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	60 <input type="checkbox" name="remember" checked="checked"/> Remember me
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	61 </label>
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	62 </p>
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	63 </form>
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	64
6fd7e4dc0318 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
6fd7e4dc0318 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
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	67 generated but before that output is actually serialized.
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	68
6fd7e4dc0318 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
6fd7e4dc0318 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
6fd7e4dc0318 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>``
6fd7e4dc0318 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
6fd7e4dc0318 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
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	74 dictionary needs to match the ``value`` attribute of the ``<option>`` element,
6fd7e4dc0318 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
6fd7e4dc0318 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
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	77 for security reasons.
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	78
6fd7e4dc0318 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
6fd7e4dc0318 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
6fd7e4dc0318 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
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	82 attempt any conversion or not produce the desired results.
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	83
6fd7e4dc0318 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
6fd7e4dc0318 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.
6fd7e4dc0318 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
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	87 an attribute matching the specified value.
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	88
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	89
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	90 HTML Sanitizer
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	91 ==============
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	92
505 a332cb9c70d5 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 6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	94 user-submitted HTML markup, removing potentially dangerous constructs that could
510 ca7d707d51b0 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:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 505 diff changeset	96
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 505 diff changeset	97 .. code-block:: pycon
438 6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	98
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	99 >>> from genshi.filters import HTMLSanitizer
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	100 >>> from genshi.input import HTML
505 a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	101
438 6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	102 >>> html = HTML("""<div>
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	103 ... <p>Innocent looking text.</p>
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	104 ... <script>alert("Danger: " + document.cookie)</script>
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	105 ... </div>""")
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	106 >>> sanitize = HTMLSanitizer()
853 4376010bb97e Convert a bunch of print statements to py3k compatible syntax. cmlenz parents: 683 diff changeset	107 >>> print(html \| sanitize)
438 6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	108 <div>
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	109 <p>Innocent looking text.</p>
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	110 </div>
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	111
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	112 In this example, the ``<script>`` tag was removed from the output.
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	113
6fd7e4dc0318 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
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	115 the filter with corresponding sets. See the API documentation for more
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	116 information.
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	117
6fd7e4dc0318 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
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	119 filter will still perform sanitization on the contents any encountered inline
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	120 styles: the proprietary ``expression()`` function (supported only by Internet
6fd7e4dc0318 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 ca7d707d51b0 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:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 505 diff changeset	123
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 505 diff changeset	124 .. code-block:: pycon
438 6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	125
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	126 >>> from genshi.filters import HTMLSanitizer
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	127 >>> from genshi.input import HTML
505 a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	128
438 6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	129 >>> html = HTML("""<div>
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	130 ... <br style="background: url(javascript:alert(document.cookie); color: #000" />
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	131 ... </div>""")
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	132 >>> sanitize = HTMLSanitizer(safe_attrs=HTMLSanitizer.SAFE_ATTRS \| set(['style']))
853 4376010bb97e Convert a bunch of print statements to py3k compatible syntax. cmlenz parents: 683 diff changeset	133 >>> print(html \| sanitize)
438 6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	134 <div>
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	135 <br style="color: #000"/>
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	136 </div>
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	137
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	138 .. warning:: You should probably not rely on the ``style`` filtering, as
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	139 sanitizing mixed HTML, CSS, and Javascript is very complicated and
6fd7e4dc0318 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
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	141 not allowing inline styles in user-submitted content, that would
6fd7e4dc0318 Added documentation page on the builtin stream filters. cmlenz parents: diff changeset	142 definitely be the safer route to follow.
505 a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	143
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	144
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	145 Transformer
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	146 ===========
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	147
a332cb9c70d5 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
a332cb9c70d5 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
a332cb9c70d5 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 ca7d707d51b0 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:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 505 diff changeset	152
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 505 diff changeset	153 .. code-block:: pycon
505 a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	154
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	155 >>> from genshi.builder import tag
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	156 >>> from genshi.core import TEXT
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	157 >>> from genshi.filters import Transformer
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	158 >>> from genshi.input import HTML
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	159
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	160 >>> html = HTML('''<html>
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	161 ... <head><title>Some Title</title></head>
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	162 ... <body>
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	163 ... Some <em>body</em> text.
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	164 ... </body>
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	165 ... </html>''')
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	166
853 4376010bb97e Convert a bunch of print statements to py3k compatible syntax. cmlenz parents: 683 diff changeset	167 >>> print(html \| Transformer('body/em').map(unicode.upper, TEXT)
4376010bb97e Convert a bunch of print statements to py3k compatible syntax. cmlenz parents: 683 diff changeset	168 ... .unwrap().wrap(tag.u).end()
4376010bb97e Convert a bunch of print statements to py3k compatible syntax. cmlenz parents: 683 diff changeset	169 ... .select('body/u')
4376010bb97e Convert a bunch of print statements to py3k compatible syntax. cmlenz parents: 683 diff changeset	170 ... .prepend('underlined '))
505 a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	171 <html>
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	172 <head><title>Some Title</title></head>
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	173 <body>
519 9f1d90d6abd4 Cut and copy transformer operations can now operate on selected attributes. athomas parents: 510 diff changeset	174 Some <u>underlined BODY</u> text.
505 a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	175 </body>
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	176 </html>
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	177
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	178 This example sets up a transformation that:
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	179
a332cb9c70d5 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,
a332cb9c70d5 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 9f1d90d6abd4 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,
9f1d90d6abd4 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 dfb45908fadc 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 a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	185
a332cb9c70d5 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.
a332cb9c70d5 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.
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	188
a332cb9c70d5 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 ca7d707d51b0 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:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 505 diff changeset	191
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 505 diff changeset	192 .. code-block:: pycon
505 a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	193
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	194 >>> from genshi import QName
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	195 >>> from genshi.filters.transform import ENTER, EXIT
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	196
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	197 >>> class RenameTransformation(object):
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	198 ... def __init__(self, name):
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	199 ... self.name = QName(name)
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	200 ... def __call__(self, stream):
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	201 ... for mark, (kind, data, pos) in stream:
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	202 ... if mark is ENTER:
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	203 ... data = self.name, data[1]
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	204 ... elif mark is EXIT:
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	205 ... data = self.name
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	206 ... yield mark, (kind, data, pos)
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	207
a332cb9c70d5 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
a332cb9c70d5 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
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	210 tag name.
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	211
533 dfb45908fadc 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
dfb45908fadc Thanks to Dave Abrahams for pointing out some deficiencies in the transformer athomas parents: 519 diff changeset	213 transformer instance:
510 ca7d707d51b0 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 505 diff changeset	214
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 505 diff changeset	215 .. code-block:: pycon
505 a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	216
533 dfb45908fadc 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) \
dfb45908fadc Thanks to Dave Abrahams for pointing out some deficiencies in the transformer athomas parents: 519 diff changeset	218 >>> xform = xform.apply(RenameTransformation('u'))
853 4376010bb97e Convert a bunch of print statements to py3k compatible syntax. cmlenz parents: 683 diff changeset	219 >>> print(html \| xform)
505 a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	220 <html>
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	221 <head><title>Some Title</title></head>
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	222 <body>
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	223 Some <u>BODY</u> text.
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	224 </body>
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	225 </html>
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	226
510 ca7d707d51b0 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 a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	228
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	229
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	230 Translator
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	231 ==========
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	232
a332cb9c70d5 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
a332cb9c70d5 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
a332cb9c70d5 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
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	236 ``gettext``-style translation function.
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	237
a332cb9c70d5 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
a332cb9c70d5 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.
a332cb9c70d5 Add transformer/translator filters to the doc page on stream filters. cmlenz parents: 438 diff changeset	240
a332cb9c70d5 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 ca7d707d51b0 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 505 diff changeset	242
ca7d707d51b0 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.

Mercurial > genshi > genshi-test

annotate doc/filters.txt @ 938:a5a1c9a11135 tip