Permalink
Switch branches/tags
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
103 lines (74 sloc) 3.26 KB
.. comment (set Emacs mode) -*- doctest -*-
>>> import formencode
++++++++
htmlfill
++++++++
:author: Ian Bicking <ianb@colorstudy.com>
.. contents::
Introduction
============
:mod:`formencode.htmlfill` is a library to fill out forms, both with default
values and error messages. It's like a template library, but more
limited, and it can be used with the output from other templates. It
has no prerequesites, and can be used without any other parts of
FormEncode.
Usage
=====
The basic usage is something like this::
>>> from formencode import htmlfill
>>> form = '<input type="text" name="fname">'
>>> defaults = {'fname': 'Joe'}
>>> htmlfill.render(form, defaults)
'<input type="text" name="fname" value="Joe">'
The parser looks for HTML input elements (including ``select`` and
``textarea``) and fills in the defaults. The quintessential way to
use this would be with a form submission that had errors -- you can
return the form to the user with the values they entered, in addition
to errors.
See :func:`formencode.htmlfill.render` for more.
Errors
------
Since errors are a common issue, this also has some features for
filling the form with error messages. It defines two special tags for
this purpose:
``<form:error name="field_name" format="formatter">``:
This tag is eliminated completely if there is no error for the
named field. Otherwise the error is passed through the given
formatter (``"default"`` if no ``format`` attribute is given).
``<form:iferror name="field_name">...</form:iferror>``:
If the named field doesn't have an error, everything between the
tags will be eliminated. Use ``name="not field_name"`` to invert
the behavior (i.e., include text only if there are no errors for
the field).
Formatters are functions that take the error text as a single
argument. (In the future they may take extra arguments as well.)
They return a string that is inserted into the template. By default,
the formatter returns::
<span class="error-message">(message)</span><br>
In addition to explicit error tags, any leftover errors will be placed
immediately above the associated input field.
The default formatters available to you:
``default``:
HTML-quotes the error and wraps it in ``<span class="error-message">``
``none``:
Puts the error message in with no quoting of any kind. This
allows you to put HTML in the error message, but might also expose
you to cross-site scripting vulnerabilities.
``escape``:
HTML-quotes the error, but doesn't wrap it in anything.
``escapenl``:
HTML-quotes the error, and translates newlines to ``<br>``
``ignore``:
Swallows the error, emitting nothing. You can use this when you
never want an error for a field to display.
Valid form templates
--------------------
When you call ``parser.close()`` (also called by ``render()``) the
parser will check that you've fully used all the defaults and errors
that were given in the constructor if you pass in
``use_all_keys=True``. If there are leftover fields an
``AssertionError`` will be raised.
In most cases, htmlfill tries to keep the template the way it found
it, without reformatting it too much. If HTMLParser_ chokes on the
code, so will htmlfill.
.. _HTMLParser: http://docs.python.org/library/htmlparser.html