    =====================
    Ordered-Select Widget
    =====================

    The ordered select widget allows you to select one or more values from a set
    of given options and sort those options. Unfortunately, HTML does not provide
    such a widget as part of its specification, so that the system has to use a
    combnation of "option" elements, buttons and Javascript.

    As for all widgets, the select widget must provide the new ``IWidget``
    interface:

      >>> from zope.interface import verify
      >>> from z3c.form import interfaces
      >>> from z3c.form.browser import orderedselect

      >>> verify.verifyClass(interfaces.IWidget, orderedselect.OrderedSelectWidget)
      True

    The widget can be instantiated only using the request:

      >>> from z3c.form.testing import TestRequest
      >>> request = TestRequest()

      >>> widget = orderedselect.OrderedSelectWidget(request)

    Before rendering the widget, one has to set the name and id of the widget:

      >>> widget.id = u'widget-id'
      >>> widget.name = u'widget.name'

    We also need to register the template for at least the widget and request:

      >>> import zope.component
      >>> from zope.pagetemplate.interfaces import IPageTemplate
      >>> from z3c.form.testing import getPath
      >>> from z3c.form.widget import WidgetTemplateFactory

      >>> zope.component.provideAdapter(
      ...     WidgetTemplateFactory(getPath('orderedselect_input.pt'), 'text/html'),
      ...     (None, None, None, None, interfaces.IOrderedSelectWidget),
      ...     IPageTemplate, name=interfaces.INPUT_MODE)

    If we render the widget we get an emtpy widget:

      >>> print widget.render()

    Let's provide some values for this widget. We can do this by defining a source
    providing ``ITerms``. This source uses descriminators wich will fit our setup.

      >>> import zope.schema.interfaces
      >>> from zope.schema.vocabulary import SimpleVocabulary
      >>> import z3c.form.term

      >>> class SelectionTerms(z3c.form.term.Terms):
      ...     def __init__(self, context, request, form, field, widget):
      ...         self.terms = SimpleVocabulary([
      ...              SimpleVocabulary.createTerm(1, 'a', u'A'),
      ...              SimpleVocabulary.createTerm(2, 'b', u'B'),
      ...              SimpleVocabulary.createTerm(3, 'c', u'C')
      ...              ])

      >>> zope.component.provideAdapter(SelectionTerms,
      ...     (None, interfaces.IFormLayer, None, None,
      ...      interfaces.IOrderedSelectWidget) )

    Now let's try if we get widget values:

      >>> widget.update()
      >>> print widget.render()

...

    If we select item "b", then it should be selected:

      >>> widget.value = ['b']
      >>> widget.update()
      >>> print widget.render()

... | ...

    Let's now make sure that we can extract user entered data from a widget:

      >>> widget.request = TestRequest(form={'widget.name': ['c']})
      >>> widget.update()
      >>> widget.extract()
      ['c']

    Unfortunately, when nothing is selected, we do not get an empty list sent into
    the request, but simply no entry at all. For this we have the empty marker, so
    that:

      >>> widget.request = TestRequest(form={'widget.name-empty-marker': '1'})
      >>> widget.update()
      >>> widget.extract()
      []

    If nothing is found in the request, the default is returned:

      >>> widget.request = TestRequest()
      >>> widget.update()
      >>> widget.extract()
    Let's now make sure that a bogus value causes extract to return the default as
    described by the interface:

      >>> widget.request = TestRequest(form={'widget.name': ['x']})
      >>> widget.update()
      >>> widget.extract()