[Checkins] SVN: z3c.form/branches/zagy-sources/ made contextual sources working

[Michael Howitz]

Log message for revision 91084:
  made contextual sources working

Changed:
  U   z3c.form/branches/zagy-sources/CHANGES.txt
  U   z3c.form/branches/zagy-sources/src/z3c/form/term.py
  U   z3c.form/branches/zagy-sources/src/z3c/form/term.txt

-=-
Modified: z3c.form/branches/zagy-sources/CHANGES.txt
===================================================================
--- z3c.form/branches/zagy-sources/CHANGES.txt	2008-09-12 13:46:35 UTC (rev 91083)
+++ z3c.form/branches/zagy-sources/CHANGES.txt	2008-09-12 14:01:02 UTC (rev 91084)
@@ -3,7 +3,8 @@
 =======
 
 - Added Support for using sources: where is was previosly possible to
-  use a vocabulary it is now also possible to use a source.
+  use a vocabulary it is now also possible to use a source. (Works
+  both for basic and contextual sources.)
 
 Version 1.7.0 (9/??/2007)
 -------------------------

Modified: z3c.form/branches/zagy-sources/src/z3c/form/term.py
===================================================================
--- z3c.form/branches/zagy-sources/src/z3c/form/term.py	2008-09-12 13:46:35 UTC (rev 91083)
+++ z3c.form/branches/zagy-sources/src/z3c/form/term.py	2008-09-12 14:01:02 UTC (rev 91084)
@@ -94,8 +94,7 @@
     zope.schema.interfaces.IChoice,
     interfaces.IWidget)
 def choice_terms_multiplexer(context, request, form, field, widget):
-    if field.vocabulary is None:
-        field = field.bind(context)
+    field = field.bind(context)
     terms = field.vocabulary
     return zope.component.queryMultiAdapter(
         (context, request, form, field, terms, widget),

Modified: z3c.form/branches/zagy-sources/src/z3c/form/term.txt
===================================================================
--- z3c.form/branches/zagy-sources/src/z3c/form/term.txt	2008-09-12 13:46:35 UTC (rev 91083)
+++ z3c.form/branches/zagy-sources/src/z3c/form/term.txt	2008-09-12 14:01:02 UTC (rev 91084)
@@ -180,8 +180,12 @@
 Sources
 =======
 
-Let's create a source first:
+Basic sources
+-------------
 
+Basic sources need no context to compute their value. Let's create a
+source first:
+
   >>> from zc.sourcefactory.basic import BasicSourceFactory 
   >>> class RatingSourceFactory(BasicSourceFactory):
   ...     _mapping = {10: u'ugly', 20: u'nice', 30: u'great'}
@@ -204,7 +208,7 @@
   >>> zope.component.provideAdapter(term.ChoiceTermsSource)
 
 Choice fields
--------------
+~~~~~~~~~~~~~
 
 Sources can be used with ``Choice`` fields like vocabularies.  First
 we create a field based on the source:
@@ -247,7 +251,7 @@
   False 
 
 Collections
------------
+~~~~~~~~~~~
 
 Finally, there are terms adapters for all collections:
 
@@ -259,3 +263,92 @@
   ...     None, request, None, sourceRatingsField, widget)
   >>> [entry.title for entry in terms]
   [u'ugly', u'nice', u'great']
+
+
+Contextual sources
+------------------
+
+Contextual sources depend on the context they are called on. Let's
+create a context and a contextual source:
+
+  >>> from zc.sourcefactory.contextual import BasicContextualSourceFactory
+  >>> class RatingContext(object):
+  ...     base_value = 10 
+  >>> class ContextualRatingSourceFactory(BasicContextualSourceFactory):
+  ...     _mapping = {10: u'ugly', 20: u'nice', 30: u'great'}
+  ...     def getValues(self, context):
+  ...         return [context.base_value + x for x in self._mapping.keys()]
+  ...     def getTitle(self, context, value):
+  ...         return self._mapping[value - context.base_value]
+
+As we did not include the configure.zcml of zc.sourcefactory we have
+to register some required adapters manually. We also need the
+ChoiceTermsSource adapter:
+
+  >>> import zope.component
+  >>> import zc.sourcefactory.browser.source
+  >>> import zc.sourcefactory.browser.token
+  >>> zope.component.provideAdapter(
+  ...     zc.sourcefactory.browser.source.FactoredContextualTerms)
+  >>> zope.component.provideAdapter(
+  ...     zc.sourcefactory.browser.token.fromInteger)
+  >>> zope.component.provideAdapter(term.ChoiceTermsSource)
+
+Choice fields
+~~~~~~~~~~~~~
+
+Contextual sources can be used with ``Choice`` fields like
+vocabularies.  First we create a field based on the source:
+
+  >>> contextualSourceRatingField = zope.schema.Choice(
+  ...     title=u'Context Sourced Rating',
+  ...     source=ContextualRatingSourceFactory())
+
+We create an context object and connect the field to a widget to see
+the ITerms adapter for sources at work:
+
+  >>> rating_context = RatingContext()
+  >>> rating_context.base_value = 100
+  >>> terms = term.choice_terms_multiplexer(
+  ...     rating_context, request, None, contextualSourceRatingField, widget)
+
+Iterating over the terms adapter returnes the term objects:
+
+  >>> [entry for entry in terms]
+  [<zc.sourcefactory.browser.source.FactoredTerm object at 0x...>,
+   <zc.sourcefactory.browser.source.FactoredTerm object at 0x...>, 
+   <zc.sourcefactory.browser.source.FactoredTerm object at 0x...>]
+  >>> len(terms)
+  3
+  >>> [entry.token for entry in terms]
+  ['110', '120', '130']
+  >>> [entry.title for entry in terms]
+  [u'ugly', u'nice', u'great']
+
+Using a token, it is possible to look up the term and the value:
+
+  >>> terms.getTermByToken('120').title
+  u'nice'
+  >>> terms.getValue('130')
+  130
+
+With can test if a value is in the source:
+
+  >>> 130 in terms
+  True
+  >>> 125 in terms
+  False 
+
+Collections
+~~~~~~~~~~~
+
+Finally, there are terms adapters for all collections:
+
+  >>> contextualSourceRatingsField = zope.schema.List(
+  ...     title=u'Contextual Sourced Ratings',
+  ...     value_type=contextualSourceRatingField)
+
+  >>> terms = term.collection_terms_multiplexer(
+  ...     rating_context, request, None, contextualSourceRatingsField, widget)
+  >>> [entry.title for entry in terms]
+  [u'ugly', u'nice', u'great']