==============
CheckBoxWidget
==============
Note: the checkbox widget isn't registered for a field by default. You can use
the ``widgetFactory`` argument of a ``IField`` object if you construct fields
or set the custom widget factory on selected fields later.
The ``CheckBoxWidget`` widget renders a checkbox input type field e.g.
>>> from zope.interface.verify import verifyClass
>>> from z3c.form import interfaces
>>> from z3c.form.browser import checkbox
The ``CheckboxWidget`` is a widget:
>>> verifyClass(interfaces.IWidget, checkbox.CheckBoxWidget)
True
The widget can render a input field only by adapting a request:
>>> from z3c.form.testing import TestRequest
>>> request = TestRequest()
>>> widget = checkbox.CheckBoxWidget(request)
Set a name and id for the widget:
>>> widget.id = 'widget-id'
>>> widget.name = 'widget.name'
Such a field provides IWidget:
>>> interfaces.IWidget.providedBy(widget)
True
We also need to register the template for at least the widget and request:
>>> import os.path
>>> import zope.interface
>>> from zope.publisher.interfaces.browser import IDefaultBrowserLayer
>>> from zope.pagetemplate.interfaces import IPageTemplate
>>> import z3c.form.browser
>>> import z3c.form.widget
>>> template = os.path.join(os.path.dirname(z3c.form.browser.__file__),
... 'checkbox_input.pt')
>>> factory = z3c.form.widget.WidgetTemplateFactory(template)
>>> zope.component.provideAdapter(factory,
... (zope.interface.Interface, IDefaultBrowserLayer, None, None, None),
... IPageTemplate, name='input')
If we render the widget we only get the empty marker:
>>> print widget.render()
Let's provide some values for this widget. We can do this by defining
a vocabulary providing ``ITerms``. This vocabulary uses descriminators
wich will fit for our setup.
>>> import zope.schema.interfaces
>>> from zope.schema.vocabulary import SimpleVocabulary
>>> import z3c.form.term
>>> class MyTerms(z3c.form.term.ChoiceTermsVocabulary):
... def __init__(self, context, request, form, field, widget):
... self.terms = SimpleVocabulary.fromValues(['yes', 'no'])
>>> zope.component.provideAdapter(z3c.form.term.BoolTerms,
... adapts=(zope.interface.Interface,
... interfaces.IFormLayer, zope.interface.Interface,
... zope.interface.Interface, interfaces.ICheckBoxWidget))
Now let's try if we get widget values:
>>> widget.update()
>>> print widget.render()
If we set the value for the widget to ``yes``, we can se that the checkbox
field get rendered with a checked flag:
>>> widget.value = 'true'
>>> widget.update()
>>> print widget.render()
Check HIDDEN_MODE:
>>> template = os.path.join(os.path.dirname(z3c.form.browser.__file__),
... 'checkbox_hidden.pt')
>>> factory = z3c.form.widget.WidgetTemplateFactory(template)
>>> zope.component.provideAdapter(factory,
... (zope.interface.Interface, IDefaultBrowserLayer, None, None, None),
... IPageTemplate, name='hidden')
>>> widget.value = 'true'
>>> widget.mode = interfaces.HIDDEN_MODE
>>> print widget.render()
Single Checkbox Widget
----------------------
Instead of using the checkbox widget as an UI component to allow multiple
selection from a list of choices, it can be also used by itself to toggle a
selection, effectively making it a binary selector. So in this case it lends
itself well as a boolean UI input component.
The ``SingleCheckboxWidget`` is a widget:
>>> verifyClass(interfaces.IWidget, checkbox.SingleCheckBoxWidget)
True
The widget can render a input field only by adapting a request:
>>> request = TestRequest()
>>> widget = checkbox.SingleCheckBoxWidget(request)
Set a name and id for the widget:
>>> widget.id = 'widget-id'
>>> widget.name = 'widget.name'
Such a widget provides the ``IWidget`` interface:
>>> interfaces.IWidget.providedBy(widget)
True
For there to be a sensible output, we need to give the widget a label:
>>> widget.label = u'Do you want that?'
>>> widget.update()
>>> print widget.render()
Initially, the box is not checked. Changing the widget value to the selection
value, ...
>>> widget.value = ['selected']
will make the box checked:
>>> widget.update()
>>> print widget.render()
If you do not specify the label on the widget directly, it is taken from the
field
>>> from zope.schema import Bool
>>> widget = checkbox.SingleCheckBoxWidget(request)
>>> widget.id = 'widget-id'
>>> widget.name = 'widget.name'
>>> widget.field = Bool(title=u"Do you REALLY want that?")
>>> widget.update()
>>> print widget.render()
Check HIDDEN_MODE:
>>> template = os.path.join(os.path.dirname(z3c.form.browser.__file__),
... 'checkbox_hidden.pt')
>>> factory = z3c.form.widget.WidgetTemplateFactory(template)
>>> zope.component.provideAdapter(factory,
... (zope.interface.Interface, IDefaultBrowserLayer, None, None, None),
... IPageTemplate, name='hidden')
>>> widget.value = 'true'
>>> widget.mode = interfaces.HIDDEN_MODE
>>> print widget.render()