# HG changeset patch # User cmlenz # Date 1181039372 0 # Node ID a332cb9c70d5954686fee4a2f5459f9d35126ead # Parent 2db10ef79e66334e43c856eb12fac21c50790be7 Add transformer/translator filters to the doc page on stream filters. diff --git a/doc/filters.txt b/doc/filters.txt --- a/doc/filters.txt +++ b/doc/filters.txt @@ -18,10 +18,11 @@ HTML Form Filler ================ -The filter ``genshi.filters.HTMLFormFiller`` can automatically populate an HTML -form from values provided as a simple dictionary. When using thi filter, you can -basically omit any ``value``, ``selected``, or ``checked`` attributes from form -controls in your templates, and let the filter do all that work for you. +The filter ``genshi.filters.html.HTMLFormFiller`` can automatically populate an +HTML form from values provided as a simple dictionary. When using thi filter, +you can basically omit any ``value``, ``selected``, or ``checked`` attributes +from form controls in your templates, and let the filter do all that work for +you. ``HTMLFormFiller`` takes a dictionary of data to populate the form with, where the keys should match the names of form elements, and the values determine the @@ -29,6 +30,7 @@ >>> from genshi.filters import HTMLFormFiller >>> from genshi.template import MarkupTemplate + >>> template = MarkupTemplate("""
...

...

...

Innocent looking text.

... @@ -116,6 +119,7 @@ >>> from genshi.filters import HTMLSanitizer >>> from genshi.input import HTML + >>> html = HTML("""
...
...
""") @@ -130,3 +134,92 @@ suspect to various browser bugs. If you can somehow get away with not allowing inline styles in user-submitted content, that would definitely be the safer route to follow. + + +Transformer +=========== + +The filter ``genshi.filters.transform.Transformer`` provides a convenient way to +transform or otherwise work with markup event streams. It allows you to specify +which parts of the stream you're interested in with XPath expressions, and then +attach a variety of transformations to the parts that match:: + + >>> from genshi.builder import tag + >>> from genshi.core import TEXT + >>> from genshi.filters import Transformer + >>> from genshi.input import HTML + + >>> html = HTML(''' + ... Some Title + ... + ... Some body text. + ... + ... ''') + + >>> print html | Transformer('body//em').apply(unicode.upper, TEXT) \ + ... .unwrap().wrap(tag.u) + + Some Title + + Some BODY text. + + + +This example sets up a transformation that: + + 1. matches any `` element anywhere in the body, + 2. uppercases any text nodes in the element, + 3. strips off the `` start and close tags, and + 4. wraps the content in a `` tag. + +A number of commonly useful transformations are available for this filter. +Please consult the API documentation a complete list. + +In addition, you can also perform custom transformations. For example, the +following defines a transformation that changes the name of a tag:: + + >>> from genshi import QName + >>> from genshi.filters.transform import ENTER, EXIT + + >>> class RenameTransformation(object): + ... def __init__(self, name): + ... self.name = QName(name) + ... def __call__(self, stream): + ... for mark, (kind, data, pos) in stream: + ... if mark is ENTER: + ... data = self.name, data[1] + ... elif mark is EXIT: + ... data = self.name + ... yield mark, (kind, data, pos) + +A transformation can be any callable object that accepts an augmented event +stream. In this case we define a class, so that we can initialize it with the +tag name. + +Custom transformations can be applied using the `|` operator on the transformer +instance:: + + >>> xform = Transformer('body//em').apply(unicode.upper, TEXT) + >>> xform |= RenameTransformation('u') + >>> print html | xform + + Some Title + + Some BODY text. + + + + + +Translator +========== + +The ``genshi.filters.i18n.Translator`` filter implements basic support for +internationalizing and localizing templates. When used as a filter, it +translates a configurable set of text nodes and attribute values using a +``gettext``-style translation function. + +The ``Translator`` class also defines the ``extract`` class method, which can +be used to extract localizable messages from a template. + +Please refer to the API documentation for more information on this filter.