[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