zope.app.form 3.6.0

The Original Zope 3 Form Framework
Latest Version: 3.8.0
This package provides a form and widget framework for Zope 3. It also
implements a few high-level ZCML directives for declaring forms. More advanced
alternatives are implemented in ``zope.formlib`` and ``z3c.form``.


Detailed documentation:


===============
Browser Widgets
===============

.. contents::

This directory contains widgets: views on bound schema fields.  Many of these
are straightforward.  For instance, see the `TextWidget` in textwidgets.py,
which is a subclass of BrowserWidget in widget.py.  It is registered as an
`IBrowserRequest` view of an `ITextLine` schema field, providing the
`IInputWidget` interface::

  

The widget then receives the field and the request as arguments to the factory
(i.e., the `TextWidget` class).

Some widgets in Zope 3 extend this pattern.  This extension is configurable:
simply do not load the zope/app/form/browser/configure.zcml file if you do not
wish to participate in the extension.  The widget registration is extended for
`Choice` fields and for the `collection` fields.

Default Choice Field Widget Registration and Lookup
===================================================

As described above, 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 query interface,
particularly if the vocabulary is too big to iterate over.  The vocabulary
may provide a query which implements an interface appropriate for that
vocabulary.  You then can register a query view -- a view registered for the
query interface and the field interface -- that implements
`zope.app.forms.browser.interfaces.IVocabularyQueryView`.

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.

Collections of Choices
----------------------

If a collection field's `value_type` is a `Choice` field, the second widget
again defers its behavior, this time to a third lookup based on the collection
field and the choice's vocabulary.  This means that a widget for a list of
large image choices can be different than a widget for a list of small image
choices (with a different vocabulary interface), different from a widget for a
list of keyword choices, and different from a set of keyword choices.

Some advanced applications may wish to do a further lookup on the basis of the
unique attribute of the collection field--perhaps looking up a named view with
a "unique" or "lenient" token depending on the field's value, but this is not
enabled in the default Zope 3 configuration.

Registering Widgets for a New Collection Field Type
---------------------------------------------------

Because of this lookup pattern, basic widget registrations for new field types
must follow a recipe.  For example, a developer may introduce a new Bag field
type for simple shopping cart functionality and wishes to add widgets for it
within the default Zope 3 collection widget registration.  The bag widgets
should be registered something like this.

The only hard requirement is that the developer must register the bag + choice
widget: the widget is just the factory for the third dispatch as described
above, so the developer can use the already implemented widgets listed below::

  

  

Beyond this, the developer may also have a generic bag widget she wishes to
register.  This might look something like this, assuming there's a
`BagSequenceWidget` available in this package::

  

Then any widgets for the bag and a vocabulary would be registered according to
this general pattern, in which `IIterableVocabulary` would be the interface of
any appropriate vocabulary and `BagWidget` is some appropriate widget::

  


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 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.app.form.browser.itemswidgets.EXPLICIT_EMPTY_SELECTION = False

during application start-up.


============================================================
Simple example showing ObjectWidget and SequenceWidget usage
============================================================

The following implements a Poll product (add it as
zope/app/demo/poll) which has poll options defined as:

label
  A `TextLine` holding the label of the option
description
  Another `TextLine` holding the description of the option

Simple stuff.

Our Poll product holds an editable list of the `PollOption` instances.
This is shown in the ``poll.py`` source below::

    from persistent import Persistent
    from interfaces import IPoll, IPollOption
    from zope.interface import implements, classImplements

    class PollOption(Persistent, object):
        implements(IPollOption)

    class Poll(Persistent, object):
        implements(IPoll)

        def getResponse(self, option):
            return self._responses[option]

        def choose(self, option):
            self._responses[option] += 1
            self._p_changed = 1

        def get_options(self):
            return self._options

        def set_options(self, options):
            self._options = options
            self._responses = {}
            for option in self._options:
                self._responses[option.label] = 0

        options = property(get_options, set_options, None, 'fiddle options')

And the Schemas are defined in the ``interfaces.py`` file below::

    from zope.interface import Interface
    from zope.schema import Object, Tuple, TextLine
    from zope.schema.interfaces import ITextLine
    from zope.i18nmessageid import MessageFactory

    _ = MessageFactory("poll")

    class IPollOption(Interface):
        label = TextLine(title=u'Label', min_length=1)
        description = TextLine(title=u'Description', min_length=1)

    class IPoll(Interface):
        options = Tuple(title=u'Options',
            value_type=Object(IPollOption, title=u'Poll Option'))

        def getResponse(option): "get the response for an option"

        def choose(option): 'user chooses an option'

Note the use of the `Tuple` and `Object` schema fields above.  The
`Tuple` could optionally have restrictions on the min or max number of
items - these will be enforced by the `SequenceWidget` form handling
code. The `Object` must specify the schema that is used to generate its
data.

Now we have to specify the actual add and edit views. We use the existing
AddView and EditView, but we pre-define the widget for the sequence because
we need to pass in additional information. This is given in the
``browser.py`` file::

    from zope.app.form.browser.editview import EditView
    from zope.app.form.browser.add import AddView
    from zope.app.form import CustomWidgetFactory
    from zope.app.form.browser import SequenceWidget, ObjectWidget

    from interfaces import IPoll
    from poll import Poll, PollOption

    class PollVoteView:
        __used_for__ = IPoll

        def choose(self, option):
            self.context.choose(option)
            self.request.response.redirect('.')

    ow = CustomWidgetFactory(ObjectWidget, PollOption)
    sw = CustomWidgetFactory(SequenceWidget, subwidget=ow)

    class PollEditView(EditView):
        __used_for__ = IPoll

        options_widget = sw

    class PollAddView(AddView):
        __used_for__ = IPoll

        options_widget = sw

Note the creation of the widget via a `CustomWidgetFactory`.  So,
whenever the options_widget is used, a new
``SequenceWidget(subwidget=CustomWidgetFactory(ObjectWidget,
PollOption))`` is created. The subwidget argument indicates that each
item in the sequence should be represented by the indicated widget
instead of their default. If the contents of the sequence were just
`Text` fields, then the default would be just fine - the only odd cases
are Sequence and Object Widgets because they need additional arguments
when they're created.

Each item in the sequence will be represented by a
``CustomWidgetFactory(ObjectWidget, PollOption)`` - thus a new
``ObjectWidget(context, request, PollOption)`` is created for each
one. The `PollOption` class ("factory") is used to create new instances
when new data is created in add forms (or edit forms when we're adding
new items to a Sequence).

Tying all this together is the ``configure.zcml``::

    

    
    

    

    

    
    

    
    
    

    

    
        
        
    

    

    


    

    

Note the use of the ``class`` attribute on the ``addform`` and
``editform`` elements.  Otherwise, nothing much exciting here.

Finally, we have some additional views...

``results.zpt``::

    
    Poll results
    
    
    Poll results
    
        Option Results Description
    
    
        
        Option
        Result
        Option
        
    
    
    
    

``vote.zpt``::

    
    Poll voting
    
    
    
    Poll voting
    
        
        
        Option
        Option
        
    
    
    
    
    
    



=============
Object Widget
=============

The following example shows a Family with Mother and Father.
First define the interface for a person:

  >>> from zope.interface import Interface, implements
  >>> from zope.schema import TextLine

  >>> class IPerson(Interface):
  ...     """Interface for Persons."""
  ...
  ...     name = TextLine(title=u'Name', description=u'The first name')

Let's define the class:

  >>> class Person(object):
  ...
  ...     implements(IPerson)
  ...
  ...     def __init__(self, name=''):
  ...         self.name = name

Let's define the interface family:

  >>> from zope.schema import Object

  >>> class IFamily(Interface):
  ...     """The familiy interface."""
  ...
  ...     mother = Object(title=u'Mother',
  ...                     required=False,
  ...                     schema=IPerson)
  ...
  ...     father = Object(title=u'Father',
  ...                     required=False,
  ...                     schema=IPerson)

Let's define the class family with FieldProperty's mother and father
FieldProperty validate the values if they get added:

  >>> from zope.schema.fieldproperty import FieldProperty

  >>> class Family(object):
  ...     """The familiy interface."""
  ...
  ...     implements(IFamily)
  ...
  ...     mother = FieldProperty(IFamily['mother'])
  ...     father = FieldProperty(IFamily['father'])
  ...
  ...     def __init__(self, mother=None, father=None):
  ...         self.mother = mother
  ...         self.father = father

Let's make a instance of Family with None attributes:

  >>> family = Family()
  >>> bool(family.mother == None)
  True

  >>> bool(family.father == None)
  True

Let's make a instance of Family with None attributes:

  >>> mother = Person(u'Margrith')
  >>> father = Person(u'Joe')
  >>> family = Family(mother, father)
  >>> IPerson.providedBy(family.mother)
  True

  >>> IPerson.providedBy(family.father)
  True

Let's define a dummy class which doesn't implements IPerson:

  >>> class Dummy(object):
  ...     """Dummy class."""
  ...     def __init__(self, name=''):
  ...         self.name = name

Raise a SchemaNotProvided exception if we add a Dummy instance to a Family
object:

  >>> foo = Dummy('foo')
  >>> bar = Dummy('bar')
  >>> family = Family(foo, bar)
  Traceback (most recent call last):
  ...
  SchemaNotProvided

Now let's setup a enviroment for use the widget like in a real application:

  >>> from zope.app.testing import ztapi
  >>> from zope.publisher.browser import TestRequest
  >>> from zope.schema.interfaces import ITextLine
  >>> from zope.schema import TextLine
  >>> from zope.app.form.browser import TextWidget
  >>> from zope.app.form.browser import ObjectWidget
  >>> from zope.app.form.interfaces import IInputWidget

Register the TextLine widget used in the IPerson interface for the field 'name'.

  >>> ztapi.browserViewProviding(ITextLine, TextWidget, IInputWidget)

Let's define a request and provide input value for the mothers name used
in the family object:

  >>> request = TestRequest(HTTP_ACCEPT_LANGUAGE='pl')
  >>> request.form['field.mother.name'] = u'Margrith Ineichen'

Before we update the object let's check the value name of the mother
instance on the family object:

  >>> family.mother.name
  u'Margrith'

Now let's initialize a ObjectWidget with the right attributes:

  >>> mother_field = IFamily['mother']
  >>> factory = Person
  >>> widget = ObjectWidget(mother_field, request, factory)

Now comes the magic. Apply changes means we force the ObjectWidget to read
the request, extract the value and save it on the content. The ObjectWidget
instance uses a real Person class (factory) for add the value. The value is
temporary stored in this factory class. The ObjectWidget reads the value from
this factory and set it to the attribute 'name' of the instance mother
(The object mother is allready there). If we don't have a instance mother
allready store in the family object, the factory instance will be stored
directly to the family attribute mother. For more information see the method
'applyChanges()' in the interface
zope.app.form.browser.objectwidget.ObjectWidget.

  >>> widget.applyChanges(family)
  True

Test the updated mother's name value on the object family:

  >>> family.mother.name
  u'Margrith Ineichen'

  >>> IPerson.providedBy(family.mother)
  True

So, now you know my mothers and fathers name. I hope it's also clear how to
use the Object field and the ObjectWidget.


==============
Source Widgets
==============

Sources are objects that represent sets of values from which one might
choose and are used with Choice schema fields.  Source widgets
currently fall into two categories:

- widgets for iterable sources

- widgets for queryable sources

Sources (combined with the available adapters) may support both
approaches, but no widgets currently support both.

In both cases, the widgets need views that can be used to get tokens
to represent source values in forms, as well as textual
representations of values.  We use the
`zope.app.form.browser.interfaces.ITerms` views for that.

All of our examples will be using the component architecture::

  >>> import zope.interface
  >>> import zope.component
  >>> import zope.schema

This `ITerms` implementation can be used for the sources involved in
our tests::

  >>> import zope.publisher.interfaces.browser
  >>> import zope.app.form.browser.interfaces
  >>> from zope.schema.vocabulary import SimpleTerm
  >>> class ListTerms:
  ...
  ...     zope.interface.implements(
  ...         zope.app.form.browser.interfaces.ITerms)
  ...
  ...     def __init__(self, source, request):
  ...         pass # We don't actually need the source or the request :)
  ...
  ...     def getTerm(self, value):
  ...         title = unicode(value)
  ...         try:
  ...             token = title.encode('base64').strip()
  ...         except binascii.Error:
  ...             raise LookupError(token)
  ...         return SimpleTerm(value, token=token, title=title)
  ...
  ...     def getValue(self, token):
  ...         return token.decode('base64')

This view just uses the unicode representations of values as titles
and the base-64 encoding of the titles as tokens.  This is a very
simple strategy that's only approriate when the values have short and
unique unicode representations.

All of the source widgets are in a single module::

  >>> import zope.app.form.browser.source

We'll also need request objects::

  >>> from zope.publisher.browser import TestRequest


Iterable Source Widgets
=======================

Iterable sources are expected to be simpler than queriable sources, so
they represent a good place to start.  The most important aspect of
iterable sources for widgets is that it's actually possible to
enumerate all the values from the source.  This allows each possible
value to be listed in a
Not Logged In

zope.app.form 3.6.0
