5.3.4 draco.form - Form handling

The module draco.form contains a set of utility classes that facilitate form handling.

To verify a form, you can use the Form class.

class Form( )
Utility class to verify forms.

The public methods of Form are:

addField( field)
Add the field field to the form. The field argument must be a Field instance. The set of fields added to a form determines which input parameters to parse, their acceptable format and the output type.

parse( namespace)
Parse the namespace namespace according to the fields that were added with addField. If the form verifies successfully, the output variables are available by using the namespace API on the form. If the form doesn't verify, a FormError exception is raised (see below).

A Form verifies its input in three phases:

  1. Verify that for all required fields an input parameter is present. Default values are filled in for optional field that have no input parameter.
  2. Verify that all the fields contain a correct value.
  3. Optionally, check dependencies between fields and/or external data.

Steps 1 and 2 are performed by the standard parse() method that uses the fields that were added to the form to describe the input. Step 3 can be performed in a customized parse() function.

The following fields are available:

class Field( name[, default=None][, absent=None][, illegal=None])
Base class for all fields. The name argument specified the name of the input parameter to parse. If a default value is given, this is an optional field so that if no value is present, the value specified by default is used. The parameters absent and illegal specify error messages to use when the field is absent or has an illegal value respectively.

The Field class has one method:

parse( value)
Verify the input parameter value and return a processed version as the output variable. The parse() implementation of the Field class does no verification and literally passes the input value. To do something interesting, you should subclass Field and implement your own parse() method.

The following subclasses of Field are available:

class TextField( name[, default=None][, absent=None][, illegal=None][, minlen=None][, maxlen=None])
Verify that the input parameter name contains text. If minlen or maxlen are given, verify that the length of this parameter is at least minlen or at most maxlen.

class StringField( name[, default=None][, absent=None][, illegal=None][, minlen=None][, maxlen=None])
Verify that the input parameter name is a single line string without control characters. If minlen or maxlen are given, verify that its length is at least minlen or at most maxlen. The output variable will be a Python string with heading and trailing whitespace stripped off. This stripped whitespace does not count when checking the string length.

class AsciiField( name[, default=None][, absent=None][, illegal=None])
Verify that the input parameter name is a single line string with only ascii characters in the ascii range and no control characters. If minlen or maxlen are given, verify that its length is at least minlen or at most maxlen. The output variable will be a Python string with heading and trailing whitespace stripped off. This stripped whitespace does not count when checking the string length.

class IntField( name[, default=None][, absent=None][, illegal=None][, minval=None][, maxval=None])
Verify that the input parameter name contains a valid integer. If minval or maxval are given, verify that the value is at least minval or at most maxval. The output variable will be a Python int.

class FloatField( name[, default=None][, absent=None][, illegal=None][, minval=None][, maxval=None])
Verify that the input parameter name is a valid floating point number. If minval or maxval are given, verify that the value is at least minval or at most maxval. The output variable will be a Python float.

class DateField( name[, default=None][, absent=None][, illegal=None])
Verify that the input parameter name is a date in one of the supported input formats. The output variable will be a Date instance.

class EnumField( name, values[, default=None][, absent=None][, illegal=None])
Verify that the input parameter name is a string that is contained in the sequence values. The output variable will be a Python string containing the selected value.

class FileUploadField( name[, default=None][, absent=None][, illegal=None])
Verify that the input parameter name is a file upload parameter. The output variable will be a FileUpload instance.

If form fails to verify, a FormError exception is raised.

class FormError( [status=''][, err_fields=[]])
Error that is raised when a form fails to verify.

The FormError class has two attributes:

status
A message describing the error that has occurred. By default, this is a terse english phrase, but it can be customized using the absent and illegal keyword argument in the Field constructor.

err_fields
A list containing the field names that are in error. The default parse() function quits at the first error so using that, err_fields will contain only one field name.

The class FormRewriter can be used to put back values in an html form. It uses Draco's tag rewriting system to achieve this.

class FormRewriter( namespace, [formid=None])
A Rewriter subclass that puts back variables from the namespace namespace to the input elements in an html form. If formid is not given, the values are put back to all input elements. If it is specified, only input elements inside the form with an id attribute equal to formid will be processed.

Finally, two utility functions are defined:

ischecked( value[, ref=None])
If ref is not specified, return the string 'checked' if value evaluates to True. If ref is specified, return the string 'checked' if the stringifications of value and ref are equal, or, in case ref is a list, when ref contains an element whose stringification is equal to value. In all other cases the empty string is returned.

isselected( value, ref)
Return the string 'selected' if the stringifications of var and ref are equal, or, in case ref is a list, when ref contains an element whose stringification is equal to value. In all other cases the empty string is returned.