Attribute Value Adapters

In advanced, highly customized projects it is often the case that a property wants to be overridden for a particular customer in a particular case. A prime example is the label of a widget. Until this implementation of a form framework was written, widgets only could get their label from the field they were representing. Thus, wanting to change the label of a widget meant implementing a custom schema and re-registering the form in question for the custom schema. It is needless to say that this was very annoying.

For this form framework, we are providing multiple levels of customization. The user has the choice to change the value of an attribute through attribute assignment or adapter lookup. The chronological order of an attribute value assignment is as follows:

1. During initialization or right thereafter, the attribute value can be set by direct attribute assignment, i.e. obj.attr = value
2. While updating the object, an adapter is looked up for the attribute. If an adapter is found, the attribute value will be overridden. Of course, if the object does not have an update() method, one can choose another location to do the adapter lookup.
3. After updating, the developer again has the choice to override the attribute allowing granularity above and beyond the adapter.

The purpose of this module is to implement the availability of an attribute value using an adapter.

>>> from z3c.form import value

The module provides helper functions and classes, to create those adapters with as little code as possible.

Static Value Adapter

To demonstrate the static value adapter, let’s go back to our widget label example. Let’s create a couple of simple widgets and forms first:

>>> class TextWidget(object):
...    label = u'Text'
>>> tw = TextWidget()

>>> class CheckboxWidget(object):
...    label = u'Checkbox'
>>> cbw = CheckboxWidget()

>>> class Form1(object):
...    pass
>>> form1 = Form1()

>>> class Form2(object):
...    pass
>>> form2 = Form2()

We can now create a generic widget property adapter:

>>> WidgetAttribute = value.StaticValueCreator(
...     discriminators = ('widget', 'view')
...     )

Creating the widget attribute object, using the helper function above, allows us to define the discriminators (or the granulatrity) that can be used to control a widget attribute by an adapter. In our case this is the widget itself and the form/view in which the widget is displayed. In other words, it will be possible to register a widget attribute value specifically for a particular widget, a particular form, or a combination thereof.

Let’s now create a label attribute adapter for the text widget, since our customer does not like the default label:

>>> TextLabel = WidgetAttribute(u'My Text', widget=TextWidget)

The first argument of any static attribute value is the value itself, in our case the string “My Text”. The following keyword arguments are the discriminators specified in the property factory. Since we only specify the widget, the label will be available to all widgets. But first we have to register the adapter:

>>> import zope.component
>>> zope.component.provideAdapter(TextLabel, name='label')

The name of the adapter is the attribute name of the widget. Let’s now see how we can get the label:

>>> from z3c.form import interfaces
>>> staticValue = zope.component.getMultiAdapter(
...     (tw, form1), interfaces.IValue, name='label')
>>> staticValue
<StaticValue u'My Text'>

The resulting value object has one public method get(), which returns the actual value:

>>> staticValue.get()
u'My Text'

As we said before, the value should be available to all forms, ...

>>> zope.component.getMultiAdapter(
...     (tw, form2), interfaces.IValue, name='label')
<StaticValue u'My Text'>

... but only to the TextWidget:

>>> zope.component.getMultiAdapter(
...     (cbw, form2), interfaces.IValue, name='label')
Traceback (most recent call last):
...
ComponentLookupError: ((<CheckboxWidget...>, <Form2...>),
                        <InterfaceClass ...IValue>, 'label')

By the way, the attribute adapter factory notices, if you specify a discriminator that was not specified:

>>> WidgetAttribute(u'My Text', form=Form2)
Traceback (most recent call last):
...
ValueError: One or more keyword arguments did not match the discriminators.

>>> WidgetAttribute.discriminators
('widget', 'view')

Computed Value Adapter

A second implementation of the value adapter in the evaluated value, where one can specify a function that computes the value to be returned. The only argument to the function is the value adapter instance itself, which then contains all the discriminators as specified when creating the generic widget attribute factory. Let’s take the same use case as before, but generating the value as follows:

>>> def getLabelValue(adapter):
...     return adapter.widget.label + ' (1)'

Now we create the value adapter for it:

>>> WidgetAttribute = value.ComputedValueCreator(
...     discriminators = ('widget', 'view')
...     )

>>> TextLabel = WidgetAttribute(getLabelValue, widget=TextWidget)

After registering the adapter, ...

>>> zope.component.provideAdapter(TextLabel, name='label')

we now get the answers:

>>> from z3c.form import interfaces
>>> zope.component.getMultiAdapter(
...     (tw, form1), interfaces.IValue, name='label')
<ComputedValue u'Text (1)'>

__Note__: The two implementations of the attribute value adapters are not

meant to be canonical features that must always be used. The API is kept simple to allow you to quickly implement your own value adapter.

Automatic Interface Assignment

Oftentimes it is desirable to register an attribute value adapter for an instance. A good example is a field, so let’s create a small schema:

>>> import zope.interface
>>> import zope.schema
>>> class IPerson(zope.interface.Interface):
...     firstName = zope.schema.TextLine(title=u'First Name')
...     lastName = zope.schema.TextLine(title=u'Last Name')

The customer now requires that the title – which is the basis of the widget label for field widgets – of the last name should be “Surname”. Until now the option was to write a new schema changing the title. With this attribute value module, as introduced thus far, we would need to provide a special interface for the last name field, since registering a label adapter for all text fields would also change the first name.

Before demonstrating the solution to this problem, let’s first create a field attribute value:

>>> FieldAttribute = value.StaticValueCreator(
...     discriminators = ('field',)
...     )

We can now create the last name title, changing only the title of the lastName field. Instead of passing in an interface of class as the field discriminator, we pass in the field instance:

>>> LastNameTitle = FieldAttribute(u'Surname', field=IPerson['lastName'])

The attribute value factory will automatically detect instances, create an interface on the fly, directly provide it on the field and makes it the discriminator interface for the adapter registratioon.

So after registering the adapter, ...

>>> zope.component.provideAdapter(LastNameTitle, name='title')

the adapter is only available to the last name field and not the first name:

>>> zope.component.queryMultiAdapter(
...     (IPerson['lastName'],), interfaces.IValue, name='title')
<StaticValue u'Surname'>

>>> zope.component.queryMultiAdapter(
...     (IPerson['firstName'],), interfaces.IValue, name='title')