Getting HTML

Having defined form fields, we can use them to generate HTML forms. Typically, this is done at run time by form class instances. Let's look at an example that displays some input widgets:

>>> class MyForm:
...     form_fields = form.Fields(IOrder, omit_readonly=True)
...
...     def __init__(self, context, request):
...         self.context, self.request = context, request
...
...     def __call__(self, ignore_request=False):
...         widgets = form.setUpWidgets(
...             self.form_fields, 'form', self.context, self.request,
...             ignore_request=ignore_request)
...         return '\n'.join([w() for w in widgets])

Here we used form.setUpWidgets to create widget instances from our form-field specifications. The second argument to setUpWidgets is a form prefix. All of the widgets on this form are given the same prefix. This allows multiple forms to be used within a single form tag, assuming that each form uses a different form prefix.

Now, we can display the form:

>>> from zope.publisher.browser import TestRequest
>>> request = TestRequest()
>>> print MyForm(None, request)() # doctest: +NORMALIZE_WHITESPACE
<input class="textType" id="form.name" name="form.name" size="20"
       type="text" value=""  />
<input class="textType" id="form.min_size" name="form.min_size" size="10"
       type="text" value=""  />
<input class="textType" id="form.max_size" name="form.max_size" size="10"
       type="text" value=""  />
<input class="textType" id="form.color" name="form.color" size="20"
       type="text" value=""  />

If the request contains any form data, that will be reflected in the output:

>>> request.form['form.name'] = u'bob'
>>> print MyForm(None, request)() # doctest: +NORMALIZE_WHITESPACE
<input class="textType" id="form.name" name="form.name" size="20"
       type="text" value="bob"  />
<input class="textType" id="form.min_size" name="form.min_size" size="10"
       type="text" value=""  />
<input class="textType" id="form.max_size" name="form.max_size" size="10"
       type="text" value=""  />
<input class="textType" id="form.color" name="form.color"
       size="20" type="text" value=""  />

Sometimes we don't want this behavior: we want to ignore the request values, particularly after a form has been processed and before it is drawn again. This can be accomplished with the 'ignore_request' argument in setUpWidgets.

>>> print MyForm(None, request)(ignore_request=True)
... # doctest: +NORMALIZE_WHITESPACE
<input class="textType" id="form.name" name="form.name" size="20"
       type="text" value=""  />
<input class="textType" id="form.min_size" name="form.min_size" size="10"
       type="text" value=""  />
<input class="textType" id="form.max_size" name="form.max_size" size="10"
       type="text" value=""  />
<input class="textType" id="form.color" name="form.color" size="20"
       type="text" value=""  />

Reading data

Of course, we don't just want to display inputs. We want to get the input data. We can use getWidgetsData for that:

>>> from pprint import pprint
>>> class MyForm:
...     form_fields = form.Fields(IOrder, omit_readonly=True)
...
...     def __init__(self, context, request):
...         self.context, self.request = context, request
...
...     def __call__(self):
...         widgets = form.setUpWidgets(
...             self.form_fields, 'form', self.context, self.request)
...
...         if 'submit' in self.request:
...             data = {}
...             errors = form.getWidgetsData(widgets, 'form', data)
...             if errors:
...                 print 'There were errors:'
...                 for error in errors:
...                     print error
...         else:
...             data = None
...
...         for w in widgets:
...             print w()
...             error = w.error()
...             if error:
...                 print error
...
...         return data

We check for a 'submit' variable in the form and, if we see it, we try to get the data, and errors. We call getWidgetsData, passing:

• Our widgets
• The form prefix, and
• A data dictionary to contain input values found

The keys in the data dictionary have the form prefix stripped off.

If there are errors, we print them. When we display the widgets, we also check for errors and show them if present. Let's add a submit variable:

>>> request.form['form.min_size'] = u''
>>> request.form['form.max_size'] = u''
>>> request.form['submit'] = u'Submit'
>>> MyForm(None, request)() # doctest: +NORMALIZE_WHITESPACE
There were errors:
('min_size', u'Minimum size', RequiredMissing('min_size'))
('max_size', u'Maximum size', RequiredMissing('max_size'))
<input class="textType" id="form.name" name="form.name" size="20"
       type="text" value="bob"  />
<input class="textType" id="form.min_size" name="form.min_size" size="10"
       type="text" value=""  />
<span class="error">Required input is missing.</span>
<input class="textType" id="form.max_size" name="form.max_size" size="10"
       type="text" value=""  />
<span class="error">Required input is missing.</span>
<input class="textType" id="form.color" name="form.color" size="20"
       type="text" value=""  />
{'name': u'bob'}

Note that we got an error because we omitted the values for min_size and max size. If we provide an invalid value, we'll get an error too:

>>> request.form['form.min_size'] = u'bob'
>>> MyForm(None, request)() # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
There were errors:
(u'Invalid floating point data',
 <exceptions.ValueError instance at ...>)
('max_size', u'Maximum size', RequiredMissing('max_size'))
<input class="textType" id="form.name" name="form.name" size="20"
       type="text" value="bob"  />
<input class="textType" id="form.min_size" name="form.min_size" size="10"
       type="text" value="bob"  />
<span class="error">Invalid floating point data</span>
<input class="textType" id="form.max_size" name="form.max_size" size="10"
       type="text" value=""  />
<span class="error">Required input is missing.</span>
<input class="textType" id="form.color" name="form.color" size="20"
       type="text" value=""  />
{'name': u'bob'}

If we provide valid data, we'll get the data back:

>>> request.form['form.min_size'] = u'42'
>>> request.form['form.max_size'] = u'142'
>>> pprint(MyForm(None, request)(), width=1)
... # doctest: +NORMALIZE_WHITESPACE
<input class="textType" id="form.name" name="form.name" size="20"
       type="text" value="bob"  />
<input class="textType" id="form.min_size" name="form.min_size" size="10"
       type="text" value="42.0"  />
<input class="textType" id="form.max_size" name="form.max_size" size="10"
       type="text" value="142.0"  />
<input class="textType" id="form.color" name="form.color" size="20"
       type="text" value=""  />
{'max_size': 142.0,
 'min_size': 42.0,
 'name': u'bob'}

It's up to the form to decide what to do with the information.

Invariants

The getWidgetsData function checks individual field constraints. Interfaces can also provide invariants that we may also want to check. The checkInvariants function can be used to do that.

In our order example, it makes sense to require that the maximum is greater than or equal to the minimum:

>>> class IOrder(interface.Interface):
...     identifier = schema.Int(title=u"Identifier", readonly=True)
...     name = schema.TextLine(title=u"Name")
...     min_size = schema.Float(title=u"Minimum size")
...     max_size = schema.Float(title=u"Maximum size")
...     now = schema.Datetime(title=u"Now", readonly=True)
...
...     @interface.invariant
...     def maxGreaterThanMin(order):
...         if order.max_size < order.min_size:
...             raise interface.Invalid("Maximum is less than Minimum")

We can update our form to check the invariant using 'checkInvariants':

>>> class MyForm:
...     form_fields = form.Fields(IOrder, omit_readonly=True)
...
...     def __init__(self, context, request):
...         self.context, self.request = context, request
...
...     def __call__(self):
...         widgets = form.setUpWidgets(
...             self.form_fields, 'form', self.context, self.request)
...
...         if 'submit' in self.request:
...             data = {}
...             errors = form.getWidgetsData(widgets, 'form', data)
...             invariant_errors = form.checkInvariants(self.form_fields,
...                                                     data)
...             if errors:
...                 print 'There were field errors:'
...                 for error in errors:
...                     print error
...
...             if invariant_errors:
...                 print 'There were invariant errors:'
...                 for error in invariant_errors:
...                     print error
...         else:
...             data = None
...
...         for w in widgets:
...             print w()
...             error = w.error()
...             if error:
...                 print error
...
...         return data

If we display the form again, we'll get the same result:

>>> pprint(MyForm(None, request)(), width=1)
... # doctest: +NORMALIZE_WHITESPACE
<input class="textType" id="form.name" name="form.name" size="20"
       type="text" value="bob"  />
<input class="textType" id="form.min_size" name="form.min_size" size="10"
       type="text" value="42.0"  />
<input class="textType" id="form.max_size" name="form.max_size" size="10"
       type="text" value="142.0"  />
{'max_size': 142.0,
 'min_size': 42.0,
 'name': u'bob'}

But if we reduce the maximum below the minimum, we'll get an invariant error:

>>> request.form['form.min_size'] = u'42'
>>> request.form['form.max_size'] = u'14'

>>> pprint(MyForm(None, request)(), width=1)
... # doctest: +NORMALIZE_WHITESPACE
There were invariant errors:
Maximum is less than Minimum
<input class="textType" id="form.name" name="form.name" size="20"
       type="text" value="bob"  />
<input class="textType" id="form.min_size" name="form.min_size" size="10"
       type="text" value="42.0"  />
<input class="textType" id="form.max_size" name="form.max_size" size="10"
       type="text" value="14.0"  />
{'max_size': 14.0,
 'min_size': 42.0,
 'name': u'bob'}

We can have field errors and invariant errors:

>>> request.form['form.name'] = u''

>>> pprint(MyForm(None, request)(), width=1)
... # doctest: +NORMALIZE_WHITESPACE
There were field errors:
('name', u'Name', RequiredMissing('name'))
There were invariant errors:
Maximum is less than Minimum
<input class="textType" id="form.name" name="form.name" size="20"
       type="text" value=""  />
<span class="error">Required input is missing.</span>
<input class="textType" id="form.min_size" name="form.min_size" size="10"
       type="text" value="42.0"  />
<input class="textType" id="form.max_size" name="form.max_size" size="10"
       type="text" value="14.0"  />
{'max_size': 14.0,
 'min_size': 42.0}

If the inputs for some fields tested by invariants are missing, the invariants are ignored:

>>> request.form['form.max_size'] = u''

>>> pprint(MyForm(None, request)()) # doctest: +NORMALIZE_WHITESPACE
There were field errors:
('name', u'Name', RequiredMissing('name'))
('max_size', u'Maximum size', RequiredMissing('max_size'))
<input class="textType" id="form.name" name="form.name" size="20"
       type="text" value=""  />
<span class="error">Required input is missing.</span>
<input class="textType" id="form.min_size" name="form.min_size" size="10"
       type="text" value="42.0"  />
<input class="textType" id="form.max_size" name="form.max_size" size="10"
       type="text" value=""  />
<span class="error">Required input is missing.</span>
{'min_size': 42.0}

Edit Forms

A common application of forms is edit forms. Edit forms are special in 2 ways:

• We want to get the initial data for widgets from the object being edited.
• If there are no errors, we want to apply the changes back to the object being edited.

The form package provides some functions to assist with creating edit forms. When we set up our form_fields, we use the render_context option, which uses data from the context passed to setUpWidgets. Let's create a content class that provides IOrder and a simple form that uses it:

>>> import datetime
>>> class Order:
...     interface.implements(IOrder)
...
...     def __init__(self, identifier):
...         self.identifier = identifier
...         self.name = 'unknown'
...         self.min_size = 0.0
...         self.max_size = 0.0
...
...     now = property(lambda self: datetime.datetime.now())

>>> order = Order(1)

>>> class MyForm:
...     form_fields = form.Fields(
...                  IOrder, omit_readonly=True, render_context=True)
...
...     def __init__(self, context, request):
...         self.context, self.request = context, request
...
...     def __call__(self, ignore_request=False):
...         widgets = form.setUpWidgets(
...             self.form_fields, 'form', self.context, self.request,
...             ignore_request=ignore_request)
...
...         return '\n'.join([w() for w in widgets])

>>> print MyForm(order, request)() # doctest: +NORMALIZE_WHITESPACE
<input class="textType" id="form.name" name="form.name" size="20"
       type="text" value="" />
<input class="textType" id="form.min_size" name="form.min_size" size="10"
       type="text" value="42.0" />
<input class="textType" id="form.max_size" name="form.max_size" size="10"
       type="text" value="" />

Note that, in this case, we got the values from the request, because we used an old request. If we want to redraw the form after processing a request, it is safest to pass ignore_request = True to setUpWidgets so that the form is redrawn with the values as found in the object, not on the request.

>>> print MyForm(order, request)(ignore_request=True)
... # doctest: +NORMALIZE_WHITESPACE
<input class="textType" id="form.name" name="form.name" size="20"
       type="text" value="unknown"  />
<input class="textType" id="form.min_size" name="form.min_size" size="10"
       type="text" value="0.0"  />
<input class="textType" id="form.max_size" name="form.max_size" size="10"
       type="text" value="0.0"  />

If we use a new request, we will of course get the same result:

>>> request = TestRequest()
>>> print MyForm(order, request)() # doctest: +NORMALIZE_WHITESPACE
<input class="textType" id="form.name" name="form.name" size="20"
       type="text" value="unknown"  />
<input class="textType" id="form.min_size" name="form.min_size" size="10"
       type="text" value="0.0"  />
<input class="textType" id="form.max_size" name="form.max_size" size="10"
       type="text" value="0.0"  />

If we include read-only fields in an edit form, they will get display widgets:

>>> class MyForm:
...     form_fields = form.Fields(IOrder, render_context=True)
...     form_fields = form_fields.omit('now')
...
...     def __init__(self, context, request):
...         self.context, self.request = context, request
...
...     def __call__(self):
...         widgets = form.setUpWidgets(
...             self.form_fields, 'form', self.context, self.request)
...
...         return '\n'.join([w() for w in widgets])

>>> print MyForm(order, request)() # doctest: +NORMALIZE_WHITESPACE
1
<input class="textType" id="form.name" name="form.name" size="20"
       type="text" value="unknown"  />
<input class="textType" id="form.min_size" name="form.min_size" size="10"
       type="text" value="0.0"  />
<input class="textType" id="form.max_size" name="form.max_size" size="10"
       type="text" value="0.0"  />

When the form is submitted, we need to apply the changes back to the object. We can use the applyChanges function for that:

>>> class MyForm:
...     form_fields = form.Fields(IOrder, render_context=True)
...     form_fields = form_fields.omit('now')
...
...     def __init__(self, context, request):
...         self.context, self.request = context, request
...
...     def __call__(self):
...         widgets = form.setUpWidgets(
...             self.form_fields, 'form', self.context, self.request)
...
...         if 'submit' in self.request:
...             data = {}
...             errors = form.getWidgetsData(widgets, 'form', data)
...             invariant_errors = form.checkInvariants(self.form_fields,
...                                                     data)
...             if errors:
...                 print 'There were field errors:'
...                 for error in errors:
...                     print error
...
...             if invariant_errors:
...                 print 'There were invariant errors:'
...                 for error in invariant_errors:
...                     print error
...
...             if not errors and not invariant_errors:
...                 changed = form.applyChanges(
...                     self.context, self.form_fields, data)
...
...         else:
...             data = changed = None
...
...         for w in widgets:
...             print w()
...             error = w.error()
...             if error:
...                 print error
...
...         if changed:
...             print 'Object updated'
...         else:
...             print 'No changes'
...
...         return data

Now, if we submit the form with some data:

>>> request.form['form.name'] = u'bob'
>>> request.form['form.min_size'] = u'42'
>>> request.form['form.max_size'] = u'142'
>>> request.form['submit'] = u''
>>> pprint(MyForm(order, request)(), width=1)
... # doctest: +NORMALIZE_WHITESPACE
1
<input class="textType" id="form.name" name="form.name" size="20"
       type="text" value="bob"  />
<input class="textType" id="form.min_size" name="form.min_size" size="10"
       type="text" value="42.0"  />
<input class="textType" id="form.max_size" name="form.max_size" size="10"
       type="text" value="142.0"  />
Object updated
{'max_size': 142.0,
 'min_size': 42.0,
 'name': u'bob'}

>>> order.name
u'bob'

>>> order.max_size
142.0

>>> order.min_size
42.0

Note, however, that if we submit the same request, we'll see that no changes were applied:

>>> pprint(MyForm(order, request)(), width=1)
... # doctest: +NORMALIZE_WHITESPACE
1
<input class="textType" id="form.name" name="form.name" size="20"
       type="text" value="bob"  />
<input class="textType" id="form.min_size" name="form.min_size" size="10"
       type="text" value="42.0"  />
<input class="textType" id="form.max_size" name="form.max_size" size="10"
       type="text" value="142.0"  />
No changes
{'max_size': 142.0,
 'min_size': 42.0,
 'name': u'bob'}

because the new and old values are the same.

The code we included in MyForm above is generic: it applies to any edit form.

Actions

Our commit logic is a little complicated. It would be far more complicated if there were multiple submit buttons.

We can use action objects to provide some distribution of application logic.

An action is an object that represents a handler for a submit button.

In the most common case, an action accepts a label and zero or more options provided as keyword parameters:

condition

A callable or name of a method to call to test whether the action is applicable. if the value is a method name, then the method will be passed the action when called, otherwise, the callable will be passed the form and the action.

validator

A callable or name of a method to call to validate and collect inputs. This is called only if the action was submitted and if the action either has no condition, or the condition evaluates to a true value. If the validator is provided as a method name, the method will be called with the action and a dictionary in which to save data. If the validator is provided as a callable, the callable will be called with the form, the action, and a dictionary in which to save data. The validator normally returns a (usually empty) list of widget input errors. It may also return None to behave as if the action wasn't submitted.

success

A handler, called when the the action was submitted and there are no validation errors. The handler may be provided as either a callable or a method name. If the handler is provided as a method name, the method will be called with the action and a dictionary containing the form data. If the success handler is provided as a callable, the callable will be called with the form, the action, and a dictionary containing the data. The handler may return a form result (e.g. page), or may return None to indicate that the form should generate it's own output.

failure

A handler, called when the the action was submitted and there are validation errors. The handler may be provided as either a callable or a method name. If the handler is provided as a method name, the method will be called with the action, a dictionary containing the form data, and a list of errors. If the failure handler is provided as a callable, the callable will be called with the form, the action, a dictionary containing the data, and a list of errors. The handler may return a form result (e.g. page), or may return None to indicate that the form should generate it's own output.

prefix

A form prefix for the action. When generating submit actions, the prefix should be combined with the action name, separating the two with a dot. The default prefix is "actions"form.

name

The action name, without a prefix. If the label is a valid Python identifier, then the lower-case label will be used, otherwise, a hex encoding of the label will be used. If for some strange reason the labels in a set of actions with the same prefix is not unique, a name will have to be given for some actions to get unique names.

data

A bag of extra information that can be used by handlers, validators, or conditions.

Let's update our edit form to use an action. We are also going to rearrange our form quite a bit to make things more modular:

• We've created a separate validation method to validate inputs and compute errors.
• We've created a handle_edit_action method for applying changes.
• We've created a template method for displaying the form. Normally, this would be a ZPT template, but we just provide a Python version here.
• We've created a call method that is described below
• We've defined a number of instance attributes for passing information between the various methods:
  • status is a string that, if set, is displayed at the top of the form.
  • errors is the set of errors found when validating.
  • widgets is a list of set-up widgets

Here's the new version:

>>> class MyForm:
...     form_fields = form.Fields(IOrder, render_context=True)
...     form_fields = form_fields.omit('now')
...
...     status = errors = None
...     prefix = 'form'
...
...     actions = form.Actions(
...         form.Action('Edit', success='handle_edit_action'),
...         )
...
...     def __init__(self, context, request):
...         self.context, self.request = context, request
...
...     def validate(self, action, data):
...         return (form.getWidgetsData(self.widgets, self.prefix, data) +
...                 form.checkInvariants(self.form_fields, data))
...
...     def handle_edit_action(self, action, data):
...         if form.applyChanges(self.context, self.form_fields, data):
...             self.status = 'Object updated'
...         else:
...             self.status = 'No changes'
...
...     def template(self):
...         if self.status:
...             print self.status
...
...         result = []
...
...         if self.errors:
...             result.append('There were errors:')
...             for error in self.errors:
...                 result.append(str(error))
...
...         for w in self.widgets:
...             result.append(w())
...             error = w.error()
...             if error:
...                 result.append(str(error))
...
...         for action in self.actions:
...             result.append(action.render())
...
...         return '\n'.join(result)
...
...     def __call__(self):
...         self.widgets = form.setUpWidgets(
...             self.form_fields, self.prefix, self.context, self.request)
...
...         data = {}
...         errors, action = form.handleSubmit(
...                              self.actions, data, self.validate)
...         self.errors = errors
...
...         if errors:
...             result = action.failure(data, errors)
...         elif errors is not None:
...             result = action.success(data)
...         else:
...             result = None
...
...         if result is None:
...             result = self.template()
...
...         return result

Lets walk through the __call__ method.

• We set up our widgets as before.
• We use form.handleSubmit to validate our data. We pass the form, actions, prefix, and validate method. For each action, form.handleSubmit checks to see if the action was submitted. If the action was submitted, it checks to see if it has a validator. If the action has a validator, the action's validator is called, otherwise the validator passed is called. The validator result (a list of widget input errors) and the action are returned. If no action was submitted, then None is returned for the errors and the action.
• If a action was submitted and there were no errors, we call the success method on the action. If the action has a handler defined, it will be called and the return value is returned, otherwise None is returned. A return value of None indicates that the form should generate it's own result.
• If a action was submitted but there were errors, we call the action's failure method. If the action has a failure handler defined, it will be called and the return value is returned, otherwise None is returned. A return value of None indicates that the form should generate it's own result.
• No action was submitted, the result is set to None.
• If we don't have a result, we generate one with our template.

Let's try the new version of our form:

>>> print MyForm(order, request)() # doctest: +NORMALIZE_WHITESPACE
1
<input class="textType" id="form.name" name="form.name" size="20"
       type="text" value="bob"  />
<input class="textType" id="form.min_size" name="form.min_size" size="10"
       type="text" value="42.0"  />
<input class="textType" id="form.max_size" name="form.max_size" size="10"
       type="text" value="142.0"  />
<input type="submit" id="form.actions.edit" name="form.actions.edit"
       value="Edit" class="button" />

In this case, we didn't get any output about changes because the request form data didn't include a submit action that matched our action definition. Let's add one and try again:

>>> request.form['form.actions.edit'] = u''
>>> print MyForm(order, request)() # doctest: +NORMALIZE_WHITESPACE
No changes
1
<input class="textType" id="form.name" name="form.name" size="20"
       type="text" value="bob"  />
<input class="textType" id="form.min_size" name="form.min_size" size="10"
       type="text" value="42.0"  />
<input class="textType" id="form.max_size" name="form.max_size" size="10"
       type="text" value="142.0"  />
<input type="submit" id="form.actions.edit" name="form.actions.edit"
       value="Edit" class="button" />

This time, we got a status message indicating that there weren't any changes.

Let's try changing some data:

>>> request.form['form.max_size'] = u'10/0'
>>> print MyForm(order, request)()
... # doctest: +NORMALIZE_WHITESPACE
There were errors:
(u'Invalid floating point data', <exceptions.ValueError instance at ...>)
1
<input class="textType" id="form.name" name="form.name" size="20"
       type="text" value="bob"  />
<input class="textType" id="form.min_size" name="form.min_size" size="10"
       type="text" value="42.0"  />
<input class="textType" id="form.max_size" name="form.max_size" size="10"
       type="text" value="10/0"  />
<span class="error">Invalid floating point data</span>
<input type="submit" id="form.actions.edit" name="form.actions.edit"
       value="Edit" class="button" />

Oops, we had a typo, let's fix it:

>>> request.form['form.max_size'] = u'10.0'
>>> print MyForm(order, request)() # doctest: +NORMALIZE_WHITESPACE
There were errors:
Maximum is less than Minimum
1
<input class="textType" id="form.name" name="form.name" size="20"
       type="text" value="bob"  />
<input class="textType" id="form.min_size" name="form.min_size" size="10"
       type="text" value="42.0"  />
<input class="textType" id="form.max_size" name="form.max_size" size="10"
       type="text" value="10.0"  />
<input type="submit" id="form.actions.edit" name="form.actions.edit"
       value="Edit" class="button" />

Oh yeah, we need to reduce the minimum too: :)

>>> request.form['form.min_size'] = u'1.0'
>>> print MyForm(order, request)() # doctest: +NORMALIZE_WHITESPACE
Object updated
1
<input class="textType" id="form.name" name="form.name" size="20"
       type="text" value="bob"  />
<input class="textType" id="form.min_size" name="form.min_size" size="10"
       type="text" value="1.0"  />
<input class="textType" id="form.max_size" name="form.max_size" size="10"
       type="text" value="10.0"  />
<input type="submit" id="form.actions.edit" name="form.actions.edit"
       value="Edit" class="button" />

Ah, much better. And our order has been updated:

>>> order.max_size
10.0

>>> order.min_size
1.0

Helpful base classes

Our form has a lot of repetitive code. A number of helpful base classes provide standard form implementation.

Multiple Schemas and Adapters

Forms can use fields from multiple schemas. This can be done in a number of ways. For example, multiple schemas can be passed to form.Fields:

>>> class IDescriptive(interface.Interface):
...     title = schema.TextLine(title=u"Title")
...     description = schema.TextLine(title=u"Description")

>>> class MyForm(form.EditForm):
...     form_fields = form.Fields(IOrder, IDescriptive)
...     form_fields = form_fields.omit('now')

In addition, if the the object being edited doesn't provide any of the schemas, it will be adapted to the schemas it doesn't provide.

Suppose we have a generic adapter for storing descriptive information on objects:

>>> from zope import component
>>> class Descriptive(object):
...     component.adapts(interface.Interface)
...     interface.implements(IDescriptive)
...     def __init__(self, context):
...         self.context = context
...
...     def title():
...         def get(self):
...             try:
...                 return self.context.__title
...             except AttributeError:
...                 return ''
...         def set(self, v):
...             self.context.__title = v
...         return property(get, set)
...     title = title()
...
...     def description():
...         def get(self):
...             try:
...                 return self.context.__description
...             except AttributeError:
...                 return ''
...         def set(self, v):
...             self.context.__description = v
...         return property(get, set)
...     description = description()

>>> component.provideAdapter(Descriptive)

Now, we can use a single form to edit both the regular order data and the descriptive data:

>>> request = TestRequest()
>>> print MyForm(order, request)() # doctest: +NORMALIZE_WHITESPACE
1
<input class="textType" id="form.name" name="form.name" size="20"
       type="text" value="bob"  />
<input class="textType" id="form.min_size" name="form.min_size" size="10"
       type="text" value="40.0"  />
<input class="textType" id="form.max_size" name="form.max_size" size="10"
       type="text" value="50.0"  />
<input class="textType" id="form.title" name="form.title" size="20"
       type="text" value=""  />
<input class="textType" id="form.description" name="form.description"
       size="20"
       type="text" value=""  />
<input type="submit" id="form.actions.apply" name="form.actions.apply"
       value="Apply" class="button" />

>>> request.form['form.name'] = u'bob'
>>> request.form['form.min_size'] = u'10.0'
>>> request.form['form.max_size'] = u'20.0'
>>> request.form['form.title'] = u'Widgets'
>>> request.form['form.description'] = u'Need more widgets'
>>> request.form['form.actions.apply'] = u''
>>> myform = MyForm(order, request)
>>> print myform()
... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
Updated on ... ... ...  ...:...:...
1
<input class="textType" id="form.name" name="form.name" size="20"
       type="text" value="bob"  />
<input class="textType" id="form.min_size" name="form.min_size" size="10"
       type="text" value="10.0"  />
<input class="textType" id="form.max_size" name="form.max_size" size="10"
       type="text" value="20.0"  />
<input class="textType" id="form.title" name="form.title" size="20"
       type="text" value="Widgets"  />
<input class="textType" id="form.description" name="form.description"
       size="20"
       type="text" value="Need more widgets"  />
<input type="submit" id="form.actions.apply" name="form.actions.apply"
       value="Apply" class="button" />

>>> order.min_size
10.0

>>> order.title
Traceback (most recent call last):
...
AttributeError: Order instance has no attribute 'title'

>>> Descriptive(order).title
u'Widgets'

Often, we'd like to get at the adapters used. If EditForm is used, the adapters are available in the adapters attribute, which is a dictionary that allows adapters to be looked up by by schema or schema name:

>>> myform.adapters[IOrder].__class__.__name__
'Order'

>>> myform.adapters['IOrder'].__class__.__name__
'Order'

>>> myform.adapters[IDescriptive].__class__.__name__
'Descriptive'

>>> myform.adapters['IDescriptive'].__class__.__name__
'Descriptive'

If you aren't using EditForm, you can get a dictionary populated in the same way by setUpWidgets by passing the dictionary as an adapters keyword argument.

Named Widget Access

The value returned from setUpWidgets supports named-based lookup as well as iteration:

>>> myform.widgets['name'].__class__.__name__
'TextWidget'

>>> myform.widgets['name'].name
'form.name'

>>> myform.widgets['title'].__class__.__name__
'TextWidget'

>>> myform.widgets['title'].name
'form.title'

Form-field manipulations

The form-field constructor is very flexible. We've already seen that we can supply multiple schemas. Here are some other things you can do.

Displaying or editing raw data

Sometimes, you want to display or edit data that doesn't come from an object. One way to do this is to pass the data to setUpWidgets.

Lets look at an example:

>>> class MyForm(form.Form):
...
...     form_fields = form.Fields(IOrder)
...     form_fields = form_fields.omit('now')
...
...     actions = ()
...
...     def setUpWidgets(self, ignore_request=False):
...         self.widgets = form.setUpWidgets(
...             self.form_fields, self.prefix, self.context, self.request,
...             data=dict(identifier=42, name=u'sally'),
...             ignore_request=ignore_request
...             )

In this case, we supplied initial data for the identifier and the name. Now if we display the form, we'll see our data and defaults for the fields we didn't supply data for:

>>> print MyForm(None, TestRequest())() # doctest: +NORMALIZE_WHITESPACE
42
<input class="textType" id="form.name" name="form.name"
       size="20" type="text" value="sally"  />
<input class="textType" id="form.min_size" name="form.min_size"
       size="10" type="text" value=""  />
<input class="textType" id="form.max_size" name="form.max_size"
       size="10" type="text" value=""  />

If data are passed in the request, they override initial data for input fields:

>>> request = TestRequest()
>>> request.form['form.name'] = u'fred'
>>> request.form['form.identifier'] = u'0'
>>> request.form['form.max_size'] = u'100'
>>> print MyForm(None, request)() # doctest: +NORMALIZE_WHITESPACE
42
<input class="textType" id="form.name" name="form.name"
       size="20" type="text" value="fred"  />
<input class="textType" id="form.min_size" name="form.min_size"
       size="10" type="text" value=""  />
<input class="textType" id="form.max_size" name="form.max_size"
       size="10" type="text" value="100.0"  />

We'll get display fields if we ask for display fields when setting up our form fields:

>>> class MyForm(form.Form):
...
...     form_fields = form.Fields(IOrder, for_display=True)
...     form_fields = form_fields.omit('now')
...
...     actions = ()
...
...     def setUpWidgets(self, ignore_request=False):
...         self.widgets = form.setUpWidgets(
...             self.form_fields, self.prefix, self.context, self.request,
...             data=dict(identifier=42, name=u'sally'),
...             ignore_request=ignore_request
...             )

>>> print MyForm(None, request)() # doctest: +NORMALIZE_WHITESPACE
42
sally
<BLANKLINE>
<BLANKLINE>

Note that we didn't get data from the request because we are using all display widgets.

Passing ignore_request=True to the setUpWidgets function ignores the request for all values passed in the data dictionary, in order to help with redrawing a form after a successful action handler. We'll fake that quickly by forcing ignore_request to be True.

>>> class MyForm(form.Form):
...
...     form_fields = form.Fields(IOrder)
...     form_fields = form_fields.omit('now')
...
...     actions = ()
...
...     def setUpWidgets(self, ignore_request=False):
...         self.widgets = form.setUpWidgets(
...             self.form_fields, self.prefix, self.context, self.request,
...             data=dict(identifier=42, name=u'sally'),
...             ignore_request=True # =ignore_request
...             )

>>> print MyForm(None, request)() # doctest: +NORMALIZE_WHITESPACE
42
<input class="textType" id="form.name" name="form.name"
       size="20" type="text" value="sally"  />
<input class="textType" id="form.min_size" name="form.min_size"
       size="10" type="text" value=""  />
<input class="textType" id="form.max_size" name="form.max_size"
       size="10" type="text" value=""  />

Specifying Custom Widgets

It is possible to use custom widgets for specific fields. This can be done for a variety of reasons, but the provided mechanism should work for any of them.

Custom widgets are specified by providing a widget factory that should be used instead of the registered field view. The factory will be called in the same way as any other field view factory, with the bound field and the request as arguments.

Let's create a simple custom widget to use in our demonstration:

>>> import zope.formlib.widget

>>> class ISODisplayWidget(zope.formlib.widget.DisplayWidget):
...
...     def __call__(self):
...         return '<span class="iso-datetime">2005-05-04</span>'

To set the custom widget factory for a field, assign to the custom_widget attribute of the form field object:

>>> class MyForm(form.Form):
...     actions = ()
...
...     form_fields = form.Fields(IOrder).select("now")
...
...     # Here we set the custom widget:
...
...     form_fields["now"].custom_widget = ISODisplayWidget

>>> print MyForm(None, request)()
<span class="iso-datetime">2005-05-04</span>

Advanced Usage Hints

This section documents patterns for advanced usage of the formlib package.

Additional Cases

Default Choice Field Widget Registration and Lookup

All field widgets are obtained by looking up a browser IInputWidget or IDisplayWidget view for the field object. For Choice fields, the default registered widget defers all of its behavior to the result of another lookup: a browser widget view for the field and the Choice field's vocabulary.

This allows registration of Choice widgets that differ on the basis of the vocabulary type. For example, a widget for a vocabulary of images might have a significantly different user interface than a widget for a vocabulary of words. A dynamic vocabulary might implement IIterableVocabulary if its contents are below a certain length, but not implement the marker "iterable" interface if the number of possible values is above the threshhold.

This also means that choice widget factories are called with with an additional argument. Rather than being called with the field and the request as arguments, choice widgets receive the field, vocabulary, and request as arguments.

Some Choice widgets may also need to provide a source interface, particularly if the vocabulary is too big to iterate over.

Default Collection Field Widget Registration and Lookup

The default configured lookup for collection fields -- List, Tuple, and Set, for instance -- begins with the usual lookup for a browser widget view for the field object. This widget defers its display to the result of another lookup: a browser widget view registered for the field and the field's value_type (the type of the contained values). This allows registrations for collection widgets that differ on the basis of the members -- a widget for entering a list of text strings might differ significantly from a widget for entering a list of dates...or even a list of choices, as discussed below.

This registration pattern has three implications that should be highlighted.

• First, collection fields that do not specify a value_type probably cannot have a reasonable widget.
• Second, collection widgets that wish to be the default widget for a collection with any value_type should be registered for the collection field and a generic value_type: the IField interface. Do not register the generic widget for the collection field only or you will break the lookup behavior as described here.
• Third, like choice widget factories, sequence widget factories (classes or functions) take three arguments. Typical sequence widgets receive the field, the value_type, and the request as arguments.

<view
    type="zope.publisher.interfaces.browser.IBrowserRequest"
    for="zope.schema.interfaces.IBag
         zope.schema.interfaces.IChoice"
    provides="zope.formlib.interfaces.IDisplayWidget"
    factory=".ChoiceCollectionDisplayWidget"
    permission="zope.Public"
    />

<view
    type="zope.publisher.interfaces.browser.IBrowserRequest"
    for="zope.schema.interfaces.IBag
         zope.schema.interfaces.IChoice"
    provides="zope.formlib.interfaces.IInputWidget"
    factory=".ChoiceCollectionInputWidget"
    permission="zope.Public"
    />

<view
    type="zope.publisher.interfaces.browser.IBrowserRequest"
    for="zope.schema.interfaces.IBag
         zope.schema.interfaces.IField"
    provides="zope.formlib.interfaces.IInputWidget"
    factory=".BagSequenceWidget"
    permission="zope.Public"
    />

<view
    type="zope.publisher.interfaces.browser.IBrowserRequest"
    for="zope.schema.interfaces.IBag
         zope.schema.interfaces.IIterableVocabulary"
    provides="zope.formlib.interfaces.IInputWidget"
    factory=".BagWidget"
    permission="zope.Public"
    />

Choice widgets and the missing value

Choice widgets for a non-required field include a "no value" item to allow for not selecting any value at all. This value used to be omitted for required fields on the assumption that the widget should avoid invalid input from the start.

However, if the context object doesn't yet have a field value set and there's no default value, a dropdown widget would have to select an arbitrary value due to the way it is displayed in the browser. This way, the field would always validate, but possibly with a value the user never chose consciously.

Starting with version zope.app.form 3.6.0, dropdown widgets for required fields display a "no value" item even for required fields if an arbitrary value would have to be selected by the widget otherwise.

To switch the old behaviour back on for backwards compatibility, do

zope.formlib.itemswidgets.EXPLICIT_EMPTY_SELECTION = False

during application start-up.

Displaying invalidation errors

Validation errors, e.g. cause by invariants, are converted into readable text by adapting them to IWidgetInputErrorView:

>>> from zope.publisher.browser import TestRequest
>>> from zope.interface.exceptions import Invalid
>>> from zope.component import getMultiAdapter
>>> from zope.formlib.interfaces import IWidgetInputErrorView
>>> error = Invalid("You are wrong!")
>>> message = getMultiAdapter((error, TestRequest()),
...         IWidgetInputErrorView).snippet()
>>> message
u'<span class="error">You are wrong!</span>'

Interface invariant methods raise zope.interface.Invalid exception. Test if this exception gets handled by the error_views.

>>> myError = Invalid('My error message')
>>> import zope.formlib.form
>>> mybase = zope.formlib.form.FormBase(None, TestRequest())
>>> mybase.errors = (myError,)
>>> save = mybase.error_views()
>>> save.next()
u'<span class="error">My error message</span>'

Now we need to set up the translation framework:

>>> from zope import component, interface
>>> from zope.i18n.interfaces import INegotiator
>>> class Negotiator:
...     interface.implements(INegotiator)
...     def getLanguage(*ignored): return 'test'
>>> component.provideUtility(Negotiator())
>>> from zope.i18n.testmessagecatalog import TestMessageFallbackDomain
>>> component.provideUtility(TestMessageFallbackDomain)

And yes, we can even handle an i18n message in an Invalid exception:

>>> from zope.i18nmessageid import MessageFactory
>>> _ = MessageFactory('my.domain')
>>> myError = Invalid(_('My i18n error message'))
>>> mybase = zope.formlib.form.FormBase(None, TestRequest())
>>> mybase.errors = (myError,)
>>> save = mybase.error_views()
>>> save.next()
u'<span class="error">[[my.domain][My i18n error message]]</span>'

Displaying widget input errors

WidgetInputError exceptions also work with i18n messages:

>>> from zope.formlib.interfaces import WidgetInputError
>>> myError = WidgetInputError(
...     field_name='summary',
...     widget_title=_(u'Summary'),
...     errors=_(u'Foo'))
>>> mybase = zope.formlib.form.FormBase(None, TestRequest())
>>> mybase.errors = (myError,)
>>> save = mybase.error_views()
>>> save.next()
u'[[my.domain][Summary]]: <span class="error">[[my.domain][Foo]]</span>'

4.0.6 (unreleased)

• Nothing changed yet.

4.0.5 (2010-09-16)

• Fixed Action name parameter handling, since 4.0.3 all passed names were lowercased.

4.0.4 (2010-07-06)

• Fixed tests to pass under Python 2.7.
• Fix validation of "multiple" attributes in orderedSelectionList.pt.

4.0.3 (2010-05-06)

• Keep Actions from raising exceptions when passed Unicode lables [LP:528468].
• Improve display of the "nothing selected" case for optional Choice fields [LP:269782].
• Improve truth testing for ItemDisplayWidget [LP:159232].
• Don't blow up if TypeError raised during token conversion [LP:98491].

4.0.2 (2010-03-07)

• Adapted tests for Python 2.4 (enforce sorting for short pprint output)

4.0.1 (2010-02-21)

• Documentation uploaded to PyPI now contains widget documentation.
• Escape MultiCheckBoxWidget content [LP:302427].

4.0 (2010-01-08)

• Widget implementation and all widgets from zope.app.form have been moved into zope.formlib, breaking zope.formlib's dependency on zope.app.form (instead zope.app.form now depends on zope.formlib).

  Widgets can all be imported from zope.formlib.widgets.

  Widget base classes and render functionality is in zope.formlib.widget.

  All relevant widget interfaces are now in zope.formlib.interfaces.

3.10.0 (2009-12-22)

• Use named template from zope.browserpage in favor of zope.app.pagetemplate.

3.9.0 (2009-12-22)

• Use ViewPageTemplateFile from zope.browserpage.

3.8.0 (2009-12-22)

• Adjusted test output to new zope.schema release.

3.7.0 (2009-12-18)

• Rid ourselves from zope.app test dependencies.
• Fix: Button label needs escaping

3.6.0 (2009-05-18)

• Remove deprecated imports.
• Remove dependency on zope.app.container (use IAdding from zope.browser.interfaces) instead. Depend on zope.browser>=1.1 (the version with IAdding).
• Moved namedtemplate to zope.app.pagetemplate, to cut some dependencies on zope.formlib when using this feature. Left BBB imports here.

3.5.2 (2009-02-21)

• Adapt tests for Python 2.5 output.

3.5.1 (2009-01-31)

• Adapt tests to upcoming zope.schema release 3.5.1.

3.5.0 (2009-01-26)

3.4.0 (2007-09-28)

No further changes since 3.4.0a1.

3.4.0a1 (2007-04-22)

Initial release as a separate project, corresponds to zope.formlib from Zope 3.4.0a1