[Zope3-checkins] SVN: Zope3/trunk/src/zope/app/form/browser/tests/test_textwidget.py Added doctest for TextWidget convert_missing_value attribute.

[Garrett Smith]

Log message for revision 25130:
Added doctest for TextWidget convert_missing_value attribute.


-=-
Modified: Zope3/trunk/src/zope/app/form/browser/tests/test_textwidget.py
===================================================================
--- Zope3/trunk/src/zope/app/form/browser/tests/test_textwidget.py	2004-05-29 16:03:20 UTC (rev 25129)
+++ Zope3/trunk/src/zope/app/form/browser/tests/test_textwidget.py	2004-05-29 17:15:59 UTC (rev 25130)
@@ -18,16 +18,78 @@
 
 from zope.interface.verify import verifyClass
 from zope.schema import TextLine
+from zope.publisher.browser import TestRequest
 
 from zope.app.form.interfaces import IInputWidget
 from zope.app.form.browser import TextWidget
+from zope.app.tests.placelesssetup import setUp, tearDown
 from zope.app.form.browser.tests.test_browserwidget import SimpleInputWidgetTest
 
+
 class TextWidgetTest(SimpleInputWidgetTest):
     """Documents and tests the text widget.
+    >>> setUp()
 
         >>> verifyClass(IInputWidget, TextWidget)
         True
+
+    Converting Missing Values
+    -------------------------
+    String fields (TextLine, Text, etc.) values can be classified as one of the
+    following:
+
+      - Non-empty string
+      - Empty string
+      - None
+
+    Text browser widgets only support the first two types: non-empty strings
+    and empty strings. There's no facility to explicitly set a None value in a
+    text browser widget.
+
+    However, it is possible to interpret an empty string as None for some
+    applications. For example, when inputing a User Name, an empty string means
+    'the user hasn't provided a value'. In another application, an empty string
+    may mean 'the user has provided a value, specifically <empty string>'.
+
+    To support both modes, the text widget provides a 'convert_missing_value'
+    flag. When True, empty strings will be converted by the widget to the
+    field's 'missing_value' (None by default). This mode accommodates the
+    'user hasn't provided a value' scenario.
+
+    To illustrate this mode, we'll use an optional field, where missing_value
+    is None:
+
+        >>> field = TextLine(
+        ...     __name__='foo',
+        ...     missing_value=None,
+        ...     required=False)
+
+    The HTTP form submission contains an empty string for the field value:
+
+        >>> request = TestRequest(form={'field.foo':u''})
+
+    A text widget configured for the field, where convert_missing_value is True
+    (the default value)...
+
+        >>> widget = TextWidget(field, request)
+        >>> widget.convert_missing_value
+        True
+
+    will convert the form's empty string into the field's missing_value, which
+    is None:
+
+        >>> widget.getInputValue() is None
+        True
+
+    When 'convert_missing_value' is False, the text widget will not convert
+    an empty string to the field's missing_value. This supports the 'user has
+    provided a value, specifically <empty string>' mode:
+
+        >>> widget.convert_missing_value = False
+        >>> widget.getInputValue()
+        u''
+
+    >>> tearDown()
     """
 
     _WidgetFactory = TextWidget