[Checkins] SVN: z3c.form/branches/fieldsandcontentproviders/src/z3c/form/contentprovider.txt better wording
Godefroid Chapelle
gotcha at bubblenet.be
Fri Mar 12 06:40:54 EST 2010
Log message for revision 109922:
better wording
Changed:
U z3c.form/branches/fieldsandcontentproviders/src/z3c/form/contentprovider.txt
-=-
Modified: z3c.form/branches/fieldsandcontentproviders/src/z3c/form/contentprovider.txt
===================================================================
--- z3c.form/branches/fieldsandcontentproviders/src/z3c/form/contentprovider.txt 2010-03-12 11:06:00 UTC (rev 109921)
+++ z3c.form/branches/fieldsandcontentproviders/src/z3c/form/contentprovider.txt 2010-03-12 11:40:54 UTC (rev 109922)
@@ -1,9 +1,24 @@
ContentProviders
----------------
-Before we can use a widget manager, we have to register the ``IFieldWidget`` adapter
-for the ``ITextLine`` field:
+We want to mix fields and content providers.
+This allow to enrich the form by interlacing html snippets produced by content
+providers.
+
+For instance, we might want to include the table of results in a search form.
+
+We might also need to insert html close to a widget as a handle used when
+improving UI with Ajax.
+
+Adding html outside the widgets avoids the systematic need of
+subclassing or changing the full widget rendering.
+
+Test setup
+----------
+Before we can use a widget manager, the ``IFieldWidget`` adapter
+has to be registered for the ``ITextLine`` field:
+
>>> import zope.component
>>> import zope.interface
>>> from z3c.form import interfaces, widget
@@ -20,7 +35,7 @@
>>> zope.component.provideAdapter(converter.FieldDataConverter)
>>> zope.component.provideAdapter(converter.FieldWidgetDataConverter)
-Now that everything we need is defined. We can define a simple schema with fields::
+We define a simple test schema with fields::
>>> import zope.interface
>>> import zope.schema
@@ -32,28 +47,49 @@
... description=u"The person's ID.",
... required=True)
...
+ ... fullname = zope.schema.TextLine(
+ ... title=u'FullName',
+ ... description=u"The person's name.",
+ ... required=True)
+ ...
-We want to mix fields and a content provider. We define a very simple
-content provider that will print extra help text after a widget::
+We want to insert a content provider between the fields.
- >>> from z3c.form import field, form
- >>> from z3c.form.interfaces import IFieldsAndContentProviderForm
- >>> from z3c.form import widget
+We define a test content provider that prints extra help text::
+
>>> from zope.contentprovider.provider import ContentProviderBase
- >>> from zope.interface import implements
-
>>> class ExtendedHelp(ContentProviderBase):
...
... def update(self):
... self.person = self.context.id
...
... def render(self):
- ... return '<div class="extendedhelp">Some very long help text about person %s</div>' % self.person
+ ... return '<div class="ex-help">Help about person %s</div>' % self.person
- >>> from z3c.form.contentprovider import ContentProviders
+
>>> from z3c.form.testing import setupFormDefaults
>>> setupFormDefaults()
+Form definition
+---------------
+
+The meat of the tests begins here.
+
+We define a form as usual by inheriting from ``form.Form``::
+
+ >>> from z3c.form import field, form
+ >>> from zope.interface import implements
+
+To insert content providers, the following steps are needed :
+
+ 1. the form class must implement ``IFieldsAndContentProviderForm``
+
+ 2. the class must have a ``contentProviders`` attribute that is an instance
+ of the ``ContentProviders`` class.
+
+ >>> from z3c.form.contentprovider import ContentProviders
+ >>> from z3c.form.interfaces import IFieldsAndContentProviderForm
+
>>> class PersonForm(form.Form):
... implements(IFieldsAndContentProviderForm)
... prefix = 'form.'
@@ -67,6 +103,7 @@
>>> request = TestRequest()
>>> class Person(object):
... id = 'james'
+ ... fullname = 'James Bond'
>>> context = Person()
>>> personForm = PersonForm(context, request)
@@ -74,10 +111,19 @@
>>> manager = FieldWidgetsAndProviders(personForm, request, context)
>>> manager.ignoreContext = True
>>> manager.update()
- >>> manager._data
- {'longHelp': <ExtendedHelp object at ...>, 'id': <Widget 'form.widgets.id'>}
+ >>> widgets = manager._data
+ >>> ids = widgets.keys()
+ >>> ids.sort()
+ >>> ids
+ ['fullname', 'id', 'longHelp']
+ >>> widgets['longHelp']
+ <ExtendedHelp object at ...>
+ >>> widgets['id']
+ <Widget 'form.widgets.id'>
+ >>> widgets['fullname']
+ <Widget 'form.widgets.fullname'>
>>> manager.get('longHelp').render()
- '<div class="extendedhelp">Some very long help text about person james</div>'
+ '<div class="ex-help">Help about person james</div>'
We can also define content provider by adaptation::
@@ -102,7 +148,16 @@
>>> manager = FieldWidgetsAndProviders(personForm, request, context)
>>> manager.ignoreContext = True
>>> manager.update()
- >>> manager._data
- {'longHelp': <ExtendedHelp object at ...>, 'id': <Widget 'form.widgets.id'>}
+ >>> widgets = manager._data
+ >>> ids = widgets.keys()
+ >>> ids.sort()
+ >>> ids
+ ['fullname', 'id', 'longHelp']
+ >>> widgets['longHelp']
+ <ExtendedHelp object at ...>
+ >>> widgets['id']
+ <Widget 'form.widgets.id'>
+ >>> widgets['fullname']
+ <Widget 'form.widgets.fullname'>
>>> manager.get('longHelp').render()
- '<div class="extendedhelp">Some very long help text about person james</div>'
+ '<div class="ex-help">Help about person james</div>'
More information about the checkins
mailing list