Package: dolmen.forms.base
dolmen.forms.baseis a package in charge of providing basic
functionalities to work withzeam.formForms.From the form to the fielddolmen.forms.baseprovides few functions dedicated to the task of
applying dict datas to object fields and to trigger events in order to
inform handlers of the updatesApplying valuesWe create our test model:>>> from zope.schema import TextLine, Choice
>>> from zope.interface import Interface, implements

>>> class ICaveman(Interface):
...    name = TextLine(title=u'a name')
...    weapon = Choice(title=u'a weapon',
...                    values=[u'none', u'a club', u'a spear'])

>>> class Neanderthal(object):
...    implements(ICaveman)
...    def __init__(self):
...       self.name = u"no name"
...       self.weapon = u"none"

>>> moshe = Neanderthal()
>>> moshe.name
u'no name'
>>> moshe.weapon
u'none'We can now use the first function,set_fields_data. It takes the
fields list, extracted thanks to theFieldscollection, the content
and the data dictionnary. The result of this call is a dictionnary,
with the interface in which the field is defined and the field
identifier as a value:>>> from dolmen.forms.base import Fields, set_fields_data

>>> fields = Fields(ICaveman)
>>> for field in fields: print field
<TextLineField a name>
<ChoiceField a weapon>

>>> data = {u'name': u'Grok', u'weapon': u'a club'}

>>> changes = set_fields_data(fields, moshe, data)
>>> print changes
{<InterfaceClass __builtin__.ICaveman>: [u'weapon', u'name']}

>>> moshe.name
u'Grok'
>>> moshe.weapon
u'a club'Values of the data dict can contain markers, to warn of a possible
special case : the value is missing or there are no changes. In these
two cases, the value assignation is skipped:>>> from dolmen.forms.base import NO_VALUE, NO_CHANGE
>>> data = {u'name': NO_VALUE, u'weapon': NO_CHANGE}

>>> changes = set_fields_data(fields, moshe, data)
>>> print changes
{}Generating changes Attributes for eventsOne advantage of generating a dict of changes is that you can trigger
event that are aware of a certain format of changes. The
IObjectModifiedEvent, for exemple, uses the changes log to trigger the
reindexation of the modified fields. The functionnotify_changesis
dedicated to notifying a given event of the applied changes. It takes
the content, the changes dict and an event as arguments. If the event
argument is omitted, ObjectModifiedEvent is used by default.We first generate a changes dict:>>> data = {u'name': u'Grok', u'weapon': u'a club'}
>>> changes = set_fields_data(fields, moshe, data)
>>> print changes
{<InterfaceClass __builtin__.ICaveman>: [u'weapon', u'name']}We can now set a logger for the IObjectModifiedEvent, in order to
check if the changes are being broadcasted:>>> from zope.component import adapter, provideHandler
>>> from zope.lifecycleevent import IObjectModifiedEvent
>>> from zope.event import subscribers


>>> logger = []

>>> @adapter(ICaveman, IObjectModifiedEvent)
... def changes_broadcasted(content, event):
...    logger.append(event.descriptions)

>>> provideHandler(changes_broadcasted)We can now feed it to the function:>>> from dolmen.forms.base import notify_changes
>>> change_log = notify_changes(moshe, changes)The logger must have been trigged. We can check its value:>>> logger
[(<zope.lifecycleevent.Attributes object at ...>,)]

>>> for attrs in logger[0]:
...     print attrs.interface, attrs.attributes
<InterfaceClass __builtin__.ICaveman> (u'weapon', u'name')Field update eventdolmen.forms.basealso proposes the definition of a new component that
can be used to atomize the updating process of an object:IFieldUpdate.To demonstrate thisIFieldUpdate, we are going to implement a simple
usecase where we instanciate a content, change a value and notify theIFieldUpdatecomponents. For that, we’ll use a basic logger object:>>> logger = []Once this is done, we can define twoIFieldUpdatecomponents. We
implement them as named adapters. We’ll retrieve them thanks to a
“getAdapters” call:>>> from zope.interface import implementer
>>> from dolmen.forms.base import IFieldUpdate

>>> @implementer(IFieldUpdate)
... @adapter(TextLine, ICaveman)
... def updated_title(field, context):
...    if field.__name__ == u"name":
...       logger.append('Name updated on %r with `%s`' %
...                     (context, getattr(context, field.__name__)))

>>> @implementer(IFieldUpdate)
... @adapter(TextLine, Interface)
... def updated_textfield(field, context):
...    logger.append('A text field has been updated')The components need to be named since they are adapters: we don’t want
them to override each other. For the example, we want them both. let’s
register them:>>> from zope.component import provideAdapter
>>> provideAdapter(updated_title, name="updatetitle")
>>> provideAdapter(updated_textfield, name="updatetext")Now, we develop the small scenarii : we instanciate a Content,
add a value for thenameattribute and call the adapters:>>> manfred = Neanderthal()
>>> manfred.name = u"Manfred the Mighty"

>>> from zope.component import getAdapters
>>> adapters = getAdapters((ICaveman['name'], manfred), IFieldUpdate)
>>> for adapter in adapters:
...   # We run through the generator
...   pass

>>> for line in logger: print line
Name updated on <Neanderthal object at ...> with `Manfred the Mighty`
A text field has been updatedThe form modeldolmen.forms.baseprovides a form baseclass defining several
useful methods and overriding some default behavior fromzeam.form.>>> from zope.interface import implementedBy
>>> from dolmen.forms.base import ApplicationFormThe provided component,ApplicationForm, inherits from the basezeam.formcomponents and implements some extra methods, allowing
it to fit into your application, such asflash, to emit messages
to given sources. It’s also layout aware:>>> for interface in implementedBy(ApplicationForm):
...     print interface
<InterfaceClass grokcore.layout.interfaces.IPage>
<InterfaceClass zeam.form.base.interfaces.ISimpleForm>
<InterfaceClass zeam.form.base.interfaces.ISimpleFormCanvas>
<InterfaceClass zeam.form.base.interfaces.IGrokViewSupport>
<InterfaceClass zeam.form.base.interfaces.IFormData>
<InterfaceClass zope.publisher.interfaces.browser.IBrowserPage>
<InterfaceClass zope.browser.interfaces.IBrowserView>
<InterfaceClass zope.location.interfaces.ILocation>Aszeam.formuses Chameleon as a template engine, it is import we
are able to compute the current request locale, in order to get the
right translation environment:>>> from zope.publisher.browser import TestRequest
>>> request = TestRequest()

>>> from zope import site
>>> from zope.location import Location
>>> from zope.location.interfaces import IRoot
>>> from zope.interface import implements

>>> class MyApp(Location, site.SiteManagerContainer):
...     implements(IRoot)
...     __name__ = ''

>>> item = MyApp()
>>> sm = site.LocalSiteManager(item)
>>> item.setSiteManager(sm)

>>> form = ApplicationForm(item, request)
>>> print form.i18nLanguage
None

>>> request = TestRequest(environ={'HTTP_ACCEPT_LANGUAGE': "en,fr"})
>>> form = ApplicationForm(item, request)
>>> print form.i18nLanguage
enFurther more, theApplicationFormoverrides theextractDatamethod from thezeam.formForm in order to compute the interfaces
invariants.>>> from grokcore.site.interfaces import IApplication
>>> from zope.interface import alsoProvides
>>> from zope.component.hooks import setSite>>> setSite(item)
>>> alsoProvides(item, IApplication)
>>> form.application_url()
'http://127.0.0.1'Declaring the invariants>>> from zope.schema import Password
>>> from zope.interface import invariant, Interface
>>> from zope.interface.exceptions import Invalid>>> class IPasswords(Interface):
...     passwd = Password(
...         title=u"Password",
...         description=u"Type the password.",
...         required=True)
...
...     verify = Password(
...         title=u"Password checking",
...         description=u"Retype the password.",
...         required=True)
...
...     @invariant
...     def check_pass(data):
...         if data.passwd != data.verify:
...             raise Invalid(u"Mismatching passwords!")>>> from zeam.form.base import Fields
>>> from grokcore.component import testing>>> class MyForm(ApplicationForm):
...     ignoreContent = True
...     ignoreRequest = False
...     fields = Fields(IPasswords)Default behavior>>> form = MyForm(item, request)
>>> form.update()
>>> form.updateForm()
>>> data, errors = form.extractData()>>> print data
{'passwd': <Marker NO_VALUE>, 'verify': <Marker NO_VALUE>}>>> for error in errors:
...     print error.title
Missing required value.
Missing required value.
There were errors.>>> for error in form.formErrors:
...     print error.title
There were errors.Errors computing>>> post = TestRequest(form = {'form.field.passwd': u'test',
...                            'form.field.verify': u'fail'})
>>> form = MyForm(item, post)
>>> form.update()
>>> form.updateForm()
>>> data, errors = form.extractData()>>> print data
{'passwd': u'test', 'verify': u'fail'}The returned error is a collection of Error components. Using the form
prefix as an identifier, it logically wraps all the errors created by
the invariants validation:>>> for error in form.formErrors:
...     print error.title
Mismatching passwords!

>>> form.errors.get(form.prefix) == form.formErrors[0]
TrueMixed FieldsThere are two types of fields, one fromzeam.form.base, the other
fromzope.schema. They are both useable in a form, separately or
mixed:>>> from zeam.form.base import Field
>>> from dolmen.forms.base import Fields
>>> class MixedForm(ApplicationForm):
...     ignoreContent = True
...     ignoreRequest = False
...     fields = Fields(IPasswords) + Field(u'Name')

>>> mixedform = MixedForm(item, post)
>>> mixedform.update()
>>> [x.title for x in mixedform.fields]
[u'Password', u'Password checking', u'Name']

>>> mixedform.updateForm()
>>> data, errors = mixedform.extractData()

>>> print form.formErrors
[<Error Mismatching passwords!>]

>>> for error in form.formErrors:
...     print error.title
Mismatching passwords!Changelog1.2.1 (2014-11-20)Updated the ‘application_url’ method to work with the latest changes in
thegrokcorestack. Also updated the versions in the standalone buildout.1.2 (2014-11-18)Added theapplication_urlandflashmethods to forms.
This implied the use ofgrokcore.site, now a dependency.1.1 (2014-06-18)grokcore.layouttook the place ofmegrok.layout. All imports and
tests were changed accordingly.1.0 (2012-10-24)Fixed the new dependencies and changes in the related packages.1.0b3 (2010-10-27)Util methodset_fields_datanow makes sure that, even if a data
entry doesn’t have a corresponding field, it doesn’t raise an error,
as it was supposed to do.1.0b2 (2010-10-20)Bothzeam.formandzope.schemaFields are useable in a Form,
now. The changes have been made in the inline validation, to take
care of both types.Now we are using formErrors fromzeam.form.baseForm instead of our
own formError method.TheInvariantsValidationis now declared thanks to thedataValidatorsmechanism introduces byzeam.form.base1.0.The package is now tested under Grok 1.2.1.0b1 (2010-06-25)The package now uses the latest version ofzeam.form.base, that
separates theextractDatafrom thevalidateData. It allows to
validate invariants in a cleaner way, without overriding generic
code.The DeprecationWarning in invariants validation is gone. It now uses
the representation of the exception and no longer themessageattribute.The package now exposes the basezeam.formmarkers.1.0a2 (2010-06-25)ApplicationFormnow validates interfaces invariants.ApplicationFormis now localized, since it provides a contextual
i18nLanguage attribute.Added tests1.0a1 (2010-06-02)Added a base Form model :ApplicationFormdolmen.forms.baseno longer usesz3c.formbut is now based
on thezeam.formForm frameworkAdded several helpers functions, to extract changes Attributes and
notify eventsAdded tests0.1 (2009-10-25)Initial release