Mercurial > genshi > mirror
changeset 505:1cc1c38c6d6d trunk
Add transformer/translator filters to the doc page on stream filters.
| author | cmlenz |
|---|---|
| date | Tue, 05 Jun 2007 10:29:32 +0000 |
| parents | a2dca8066a5a |
| children | 0ea38a6cf173 |
| files | doc/filters.txt |
| diffstat | 1 files changed, 98 insertions(+), 5 deletions(-) [+] |
line wrap: on
line diff
--- 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("""<form> ... <p> ... <label>User name: @@ -86,12 +88,13 @@ HTML Sanitizer ============== -The filter ``genshi.filters.HTMLSanitizer`` filter can be used to clean up +The filter ``genshi.filters.html.HTMLSanitizer`` filter can be used to clean up user-submitted HTML markup, removing potentially dangerous constructs that could be used for various kinds of abuse, such as cross-site scripting (XSS) attacks:: >>> from genshi.filters import HTMLSanitizer >>> from genshi.input import HTML + >>> html = HTML("""<div> ... <p>Innocent looking text.</p> ... <script>alert("Danger: " + document.cookie)</script> @@ -116,6 +119,7 @@ >>> from genshi.filters import HTMLSanitizer >>> from genshi.input import HTML + >>> html = HTML("""<div> ... <br style="background: url(javascript:alert(document.cookie); color: #000" /> ... </div>""") @@ -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('''<html> + ... <head><title>Some Title</title></head> + ... <body> + ... Some <em>body</em> text. + ... </body> + ... </html>''') + + >>> print html | Transformer('body//em').apply(unicode.upper, TEXT) \ + ... .unwrap().wrap(tag.u) + <html> + <head><title>Some Title</title></head> + <body> + Some <u>BODY</u> text. + </body> + </html> + +This example sets up a transformation that: + + 1. matches any `<em>` element anywhere in the body, + 2. uppercases any text nodes in the element, + 3. strips off the `<em>` start and close tags, and + 4. wraps the content in a `<u>` 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 + <html> + <head><title>Some Title</title></head> + <body> + Some <u>BODY</u> text. + </body> + </html> + + + +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.