formencode.htmlfill – Fill in HTML forms

Parser for HTML forms, that fills in defaults and errors. See render.

Module Contents

formencode.htmlfill.render(form, defaults=None, errors=None, use_all_keys=False, error_formatters=None, add_attributes=None, auto_insert_errors=True, auto_error_formatter=None, text_as_default=False, checkbox_checked_if_present=False, listener=None, encoding=None, error_class='error', prefix_error=True, force_defaults=True, skip_passwords=False)

Render the form (which should be a string) given the defaults and errors. Defaults are the values that go in the input fields (overwriting any values that are there) and errors are displayed inline in the form (and also effect input classes). Returns the rendered string.

If auto_insert_errors is true (the default) then any errors for which <form:error> tags can’t be found will be put just above the associated input field, or at the top of the form if no field can be found.

If use_all_keys is true, if there are any extra fields from defaults or errors that couldn’t be used in the form it will be an error.

error_formatters is a dictionary of formatter names to one-argument functions that format an error into HTML. Some default formatters are provided if you don’t provide this.

error_class is the class added to input fields when there is an error for that field.

add_attributes is a dictionary of field names to a dictionary of attribute name/values. If the name starts with + then the value will be appended to any existing attribute (e.g., {'+class': ' important'}).

auto_error_formatter is used to create the HTML that goes above the fields. By default it wraps the error message in a span and adds a <br>.

If text_as_default is true (default false) then <input type="unknown"> will be treated as text inputs.

If checkbox_checked_if_present is true (default false) then <input type="checkbox"> will be set to checked if any corresponding key is found in the defaults dictionary, even a value that evaluates to False (like an empty string). This can be used to support pre-filling of checkboxes that do not have a value attribute, since browsers typically will only send the name of the checkbox in the form submission if the checkbox is checked, so simply the presence of the key would mean the box should be checked.

listener can be an object that watches fields pass; the only one currently is in htmlfill_schemabuilder.SchemaBuilder

encoding specifies an encoding to assume when mixing str and unicode text in the template.

prefix_error specifies if the HTML created by auto_error_formatter is put before the input control (default) or after the control.

force_defaults specifies if a field default is not given in the defaults dictionary then the control associated with the field should be set as an unsuccessful control. So checkboxes will be cleared, radio and select controls will have no value selected, and textareas will be emptied. This defaults to True, which is appropriate the defaults are the result of a form submission.

skip_passwords specifies if password fields should be skipped when rendering form-content. If disabled the password fields will not be filled with anything, which is useful when you don’t want to return a user’s password in plain-text source.

class formencode.htmlfill.htmlliteral(html, text=None)

formencode.htmlfill.default_formatter(error)

Formatter that escapes the error, wraps the error in a span with class error-message, and adds a <br>

formencode.htmlfill.escape_formatter(error)

Formatter that escapes HTML, no more.

formencode.htmlfill.escapenl_formatter(error)

Formatter that escapes HTML, and translates newlines to <br>

formencode.htmlfill.ignore_formatter(error)

Formatter that emits nothing, regardless of the error.

formencode.htmlfill.ignore_formatter(error)

Formatter that emits nothing, regardless of the error.

class formencode.htmlfill.FillingParser(defaults, errors=None, use_all_keys=False, error_formatters=None, error_class='error', add_attributes=None, listener=None, auto_error_formatter=None, text_as_default=False, checkbox_checked_if_present=False, encoding=None, prefix_error=True, force_defaults=True, skip_passwords=False)

Fills HTML with default values, as in a form.

Examples:

>>> defaults = dict(name='Bob Jones',
...             occupation='Crazy Cultist',
...             address='14 W. Canal\nNew Guinea',
...             living='no',
...             nice_guy=0)
>>> parser = FillingParser(defaults)
>>> parser.feed('''<input type="text" name="name" value="fill">
... <select name="occupation"> <option value="">Default</option>
... <option value="Crazy Cultist">Crazy cultist</option> </select>
... <textarea cols="20" style="width: 100%" name="address">
... An address</textarea>
... <input type="radio" name="living" value="yes">
... <input type="radio" name="living" value="no">
... <input type="checkbox" name="nice_guy" checked="checked">''')
>>> parser.close()
>>> print parser.text() 
<input type="text" name="name" value="Bob Jones">
<select name="occupation">
<option value="">Default</option>
<option value="Crazy Cultist" selected="selected">Crazy cultist</option>
</select>
<textarea cols="20" style="width: 100%" name="address">14 W. Canal
New Guinea</textarea>
<input type="radio" name="living" value="yes">
<input type="radio" name="living" value="no" checked="checked">
<input type="checkbox" name="nice_guy">