Mercurial > genshi > mirror
diff doc/filters.txt @ 820:9755836bb396 experimental-inline
Sync (old) experimental inline branch with trunk@1027.
| author | cmlenz |
|---|---|
| date | Wed, 11 Mar 2009 17:51:06 +0000 |
| parents | 3eb30e4ece8c |
| children | fe25855324dd |
line wrap: on
line diff
--- a/doc/filters.txt +++ b/doc/filters.txt @@ -18,17 +18,21 @@ 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 this 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 -values of those controls. For example:: +values of those controls. For example: + +.. code-block:: pycon >>> from genshi.filters import HTMLFormFiller >>> from genshi.template import MarkupTemplate + >>> template = MarkupTemplate("""<form> ... <p> ... <label>User name: @@ -86,12 +90,15 @@ 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:: +be used for various kinds of abuse, such as cross-site scripting (XSS) attacks: + +.. code-block:: pycon >>> from genshi.filters import HTMLSanitizer >>> from genshi.input import HTML + >>> html = HTML("""<div> ... <p>Innocent looking text.</p> ... <script>alert("Danger: " + document.cookie)</script> @@ -112,10 +119,13 @@ filter will still perform sanitization on the contents any encountered inline styles: the proprietary ``expression()`` function (supported only by Internet Explorer) is removed, and any property using an ``url()`` which a potentially -dangerous URL scheme (such as ``javascript:``) are also stripped out:: +dangerous URL scheme (such as ``javascript:``) are also stripped out: + +.. code-block:: pycon >>> 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 +140,104 @@ 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: + +.. code-block:: pycon + + >>> 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').map(unicode.upper, TEXT) \ + ... .unwrap().wrap(tag.u).end() \ + ... .select('body/u') \ + ... .prepend('underlined ') + <html> + <head><title>Some Title</title></head> + <body> + Some <u>underlined 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, + 4. wraps the content in a `<u>` tag, and + 5. inserts the text `underlined` inside the `<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: + +.. code-block:: pycon + + >>> 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 `apply()` method of a +transformer instance: + +.. code-block:: pycon + + >>> xform = Transformer('body//em').map(unicode.upper, TEXT) \ + >>> xform = xform.apply(RenameTransformation('u')) + >>> print html | xform + <html> + <head><title>Some Title</title></head> + <body> + Some <u>BODY</u> text. + </body> + </html> + +.. note:: The transformation filter was added in Genshi 0.5. + + +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. + +.. note:: The translation filter was added in Genshi 0.4.