=============================
Date and Time Data Converters
=============================

The normal z3c.form data converters for dates and datetimes format the entire
date as a string representation in the current locale.  But the widgets in
this package work with individual components of the date/time, which is easiest
if we provide our own data converters that keep the components separate. (We
can't simply provide a null converter that passes the date values into and out
of the widget unchanged, because z3c.form does not catch validation errors while
extracting a widget's value.)

Let's set up a date field, date widget, and a converter adapting both of them.

    >>> from zope.schema import Date
    >>> from collective.z3cform.datetimewidget import DateWidget
    >>> from collective.z3cform.datetimewidget.converter import DateDataConverter
    >>> from collective.z3cform.datetimewidget.tests import TestRequest
    >>> field = Date()
    >>> request = TestRequest()
    >>> widget = DateWidget(request)
    >>> converter = DateDataConverter(field, widget)

Now we can convert field values to widget values.
  
    >>> from datetime import date
    >>> converter.toWidgetValue(date(2009, 5, 10))
    (2009, 5, 10)

A value of None results in a tuple of empty strings.

    >>> converter.toWidgetValue(None)
    ('', '', '')

We can also convert widget values to field values.

    >>> converter.toFieldValue(('2009', '5', '10'))
    datetime.date(2009, 5, 10)

If day and year of the widget value components is missing, a value of None will be
returned.

    >>> converter.toFieldValue(('', '5', '')) is None
    True

If all of the widget value components are present but they don't correspond to
a valid date, a validation error will be raised.

    >>> converter.toFieldValue(('2009', '42', '42'))
    Traceback (most recent call last):
    ...
    DateValidationError


Let's set up a datetime field, datetime widget, and a converter adapting both of them.

    >>> from zope.schema import Datetime
    >>> from collective.z3cform.datetimewidget import DatetimeWidget
    >>> from collective.z3cform.datetimewidget.converter import DatetimeDataConverter
    >>> field = Datetime()
    >>> request = TestRequest()
    >>> widget = DatetimeWidget(request)
    >>> converter = DatetimeDataConverter(field, widget)

Now we can convert field values to widget values.

    >>> from datetime import datetime
    >>> converter.toWidgetValue(datetime(2009, 5, 10, 15, 35))
    (2009, 5, 10, 15, 35)

A value of None results in a tuple of empty strings.

    >>> converter.toWidgetValue(None)
    ('', '', '', '00', '00')

We can also convert widget values to field values.

    >>> converter.toFieldValue(('2009', '5', '10', '15', '35'))
    datetime.datetime(2009, 5, 10, 15, 35)

If day and year of the widget value components is missing, a value of None will be
returned.

    >>> converter.toFieldValue(('', '5', '', '00', '00')) is None
    True

If all of the widget value components are present but they don't correspond to
a valid date, a validation error will be raised.

    >>> converter.toFieldValue(('2009', '42', '42', '42', '82'))
    Traceback (most recent call last):
    ...
    DatetimeValidationError
