Widget Mapping

The main resposibility of the manager is to provide the IEnumerableMapping? interface and an update() method. Initially the mapping, going from widget id to widget value, is empty:

>>> from zope.interface.common.mapping import IEnumerableMapping
>>> IEnumerableMapping.providedBy(manager)
True

>>> manager.keys()
[]

Only by "updating" the manager, the widgets will become available. But before we can use the update method we have to register the IFieldWidget? adapter for the ITextLine? field:

>>> from z3c.form import interfaces, widget

>>> @zope.component.adapter(zope.schema.TextLine, TestRequest)
... @zope.interface.implementer(interfaces.IFieldWidget)
... def TextFieldWidget(field, request):
...     return widget.FieldWidget(field, widget.Widget(request))

>>> zope.component.provideAdapter(TextFieldWidget)

>>> from z3c.form import converter
>>> zope.component.provideAdapter(converter.FieldDataConverter)
>>> zope.component.provideAdapter(converter.FieldWidgetDataConverter)

>>> manager.update()

Other than usual mappings in Python, the widget manager's widgets are always in a particular order:

>>> manager.keys()
['id', 'lastName', 'firstName']

Let's make sure that all enumerable mapping functions work correctly:

>>> manager['lastName']
<Widget 'form.widgets.lastName'>

>>> manager['unknown']
Traceback (most recent call last):
...
KeyError: 'unknown'

>>> manager.get('lastName')
<Widget 'form.widgets.lastName'>

>>> manager.get('unknown', 'default')
'default'

>>> 'lastName' in manager
True
>>> 'unknown' in manager
False

>>> [key for key in manager]
['id', 'lastName', 'firstName']

>>> manager.values()
[<Widget 'form.widgets.id'>,
 <Widget 'form.widgets.lastName'>,
 <Widget 'form.widgets.firstName'>]

>>> manager.items()
[('id', <Widget 'form.widgets.id'>),
 ('lastName', <Widget 'form.widgets.lastName'>),
 ('firstName', <Widget 'form.widgets.firstName'>)]

>>> len(manager)
3

Properties of widgets within a manager

When a widget is added to the widget manager, it is located:

>>> lname = manager['lastName']

>>> lname.__name__
'lastName'
>>> lname.__parent__
<z3c.form.field.FieldWidgets object at ...>

All widgets created by this widget manager are context aware:

>>> interfaces.IContextAware.providedBy(lname)
True
>>> lname.context is context
True

Determination of the widget mode

By default, all widgets will also assume the mode of the manager:

>>> manager['lastName'].mode
'input'

>>> manager.mode = interfaces.DISPLAY_MODE
>>> manager.update()

>>> manager['lastName'].mode
'display'

The exception is when some fields specifically desire a different mode. In the first case, all "readonly" fields will be shown in display mode:

>>> manager.mode = interfaces.INPUT_MODE
>>> manager.update()

>>> manager['id'].mode
'display'

An exception is made when the flag, "ignoreReadonly" is set:

>>> manager.ignoreReadonly = True
>>> manager.update()

>>> manager['id'].mode
'input'

In the second case, the last name will inherit the mode from the widget manager, while the first name will want to use a display wdget:

>>> personForm.fields = field.Fields(IPerson).select('lastName')
>>> personForm.fields += field.Fields(
...     IPerson, mode=interfaces.DISPLAY_MODE).select('firstName')

>>> manager.mode = interfaces.INPUT_MODE
>>> manager.update()

>>> manager['lastName'].mode
'input'
>>> manager['firstName'].mode
'display'

In a third case, the widget will be shown in display mode, if the attribute of the context is not writable. Clearly this can never occur in add forms, since there the context is ignored, but is an important use case in edit forms.

Thus we need an implementation of the IPerson? interface including some security declarations:

>>> from zope.security import checker

>>> class Person(object):
...     zope.interface.implements(IPerson)
...
...     def __init__(self, firstName, lastName):
...         self.id = firstName[0].lower() + lastName.lower()
...         self.firstName = firstName
...         self.lastName = lastName

>>> PersonChecker = checker.Checker(
...     get_permissions = {'id': checker.CheckerPublic,
...                        'firstName': checker.CheckerPublic,
...                        'lastName': checker.CheckerPublic},
...     set_permissions = {'firstName': 'test.Edit',
...                        'lastName': checker.CheckerPublic}
...     )

>>> srichter = checker.ProxyFactory(
...     Person(u'Stephan', u'Richter'), PersonChecker)

In this case, the last name is always editable but for the first name the user will need the edit "test.Edit" permission.

We also need to register the data manager and setup a new security policy:

>>> from z3c.form import datamanager
>>> zope.component.provideAdapter(datamanager.AttributeField)

>>> from zope.security import management
>>> from z3c.form import testing
>>> management.endInteraction()
>>> newPolicy = testing.SimpleSecurityPolicy()
>>> oldpolicy = management.setSecurityPolicy(newPolicy)
>>> management.newInteraction()

Now we can create the widget manager:

>>> personForm = PersonForm()
>>> request = TestRequest()
>>> manager = field.FieldWidgets(personForm, request, srichter)

After updating the widget manager, the fields are available as widgets, the first name being in display and the last name is input mode:

>>> manager.update()
>>> manager['id'].mode
'display'
>>> manager['firstName'].mode
'display'
>>> manager['lastName'].mode
'input'

However, explicitely overriding the mode in the field declaration, overrides this selection for you:

>>> personForm.fields['firstName'].mode = interfaces.INPUT_MODE

>>> manager.update()
>>> manager['id'].mode
'display'
>>> manager['firstName'].mode
'input'
>>> manager['lastName'].mode
'input'

Data extraction and validation

Besides managing widgets, the widget manager also controls the process of extracting and validating extracted data. Let's start with the validation first, which only validates the data as a whole, assuming each individual value being already validated.

Before we can use the method, we have to register a "manager validator":

>>> from z3c.form import validator
>>> zope.component.provideAdapter(validator.InvariantsValidator)

>>> personForm.fields = field.Fields(IPerson)
>>> manager.update()

>>> manager.validate(
...     {'firstName': u'Stephan', 'lastName': u'Richter'})
()

The result of this method is a tuple of errors that occured during the validation. An empty tuple means the validation succeeded. Let's now make the validation fail:

>>> errors = manager.validate(
...     {'firstName': u'Stephan', 'lastName': u'Richter-Richter'})

>>> [error.doc() for error in errors]
['The last name is too short.']

A special case occurs when the schema fields are not associated with an interface:

>>> name = zope.schema.TextLine(__name__='name')

>>> class PersonNameForm(object):
...     prefix = 'form.'
...     fields = field.Fields(name)
>>> personNameForm = PersonNameForm()

>>> manager = field.FieldWidgets(personNameForm, request, context)

In this case, the widget manager's validate() method should simply ignore the field and not try to look up any invariants:

>>> manager.validate({'name': u'Stephan'})
()

Let's now have a look at the widget manager's extract(), which returns a data dictionary and the collection of errors. Before we can validate, we have to register a validator for the widget:

>>> zope.component.provideAdapter(validator.SimpleFieldValidator)

When all goes well, the data dictionary is complete and the error collection empty:

>>> request = TestRequest(form={
...     'form.widgets.id': u'srichter',
...     'form.widgets.firstName': u'Stephan',
...     'form.widgets.lastName': u'Richter'})
>>> manager = field.FieldWidgets(personForm, request, context)
>>> manager.ignoreContext = True
>>> manager.update()

>>> from zope.testing.doctestunit import pprint
>>> pprint(manager.extract())
({'firstName': u'Stephan', 'lastName': u'Richter'}, ())

Since all errors are immediately converted to error view snippets, we have to provide the adapter from a validation error to an error view snippet first:

>>> from z3c.form import error
>>> zope.component.provideAdapter(error.ErrorViewSnippet)

Let's now cause a widget-level error by not submitting the required last name:

>>> request = TestRequest(form={
...     'form.widgets.firstName': u'Stephan', 'form.widgets.id': u'srichter'})
>>> manager = field.FieldWidgets(personForm, request, context)
>>> manager.ignoreContext = True
>>> manager.update()
>>> manager.extract()
({'firstName': u'Stephan'}, (<ErrorViewSnippet for RequiredMissing>,))

Finally, let's ensure that invariant failures are also caught:

>>> request = TestRequest(form={
...     'form.widgets.id': u'srichter',
...     'form.widgets.firstName': u'Stephan',
...     'form.widgets.lastName': u'Richter-Richter'})
>>> manager = field.FieldWidgets(personForm, request, context)
>>> manager.ignoreContext = True
>>> manager.update()
>>> data, errors = manager.extract()
>>> errors[0].doc()
'The last name is too short.'

And that's all.