A collection of widgets and templates, and other components for with z3c.form in Plone
Project description
=================
plone.app.z3cform
=================
Abstract
========
A collection of widgets and templates, and other components for use
with `z3c.form`_ in Plone_. This is much related to `plone.z3cform`_,
the library that enables Zope 2 applications to use z3c.form.
.. _z3c.form: http://pypi.python.org/pypi/z3c.form
.. _Plone: http://plone.org
.. _plone.z3cform: http://pypi.python.org/pypi/plone.z3cform
WYSIWYG widget
==============
The ``wysiwyg`` package provides an implementation of the Plone
WYSIWYG widget compatible with ``z3c.form``. This will allow you to
use Kupu, FCKeditor and other editors compatible with the Plone
WYSIWYG interface in your ``z3c.form`` forms.
To use, simply set the widget factory for the widget you'd like to be
displayed with the WYSIWYG widget:
>>> from zope import interface, schema
>>> from z3c.form import form, field
>>> from z3c.form.interfaces import INPUT_MODE
>>> from plone.app.z3cform.wysiwyg.widget import WysiwygFieldWidget
>>> class IProfile(interface.Interface):
... name = schema.TextLine(title=u"Name")
... age = schema.Int(title=u"Age")
... bio = schema.Text(title=u"Bio")
>>> class MyForm(form.Form):
... fields = field.Fields(IProfile)
... fields['bio'].widgetFactory[INPUT_MODE] = WysiwygFieldWidget
Query select widget
===================
The ``queryselect`` module provides a query source compatible with
``z3c.formwidget.query`` which combines to a selection field that can
be queried.
The native value type for the widget is Archetypes UID collections.
The default implementation will simply search using the
``SearchableText`` index in the portal catalog.
This is how your form schema could look like:
>>> from zope import interface, schema
>>> from plone.app.z3cform.queryselect import ArchetypesContentSourceBinder
>>> class ISelection(interface.Interface):
... items = schema.Set(
... title=u"Selection",
... description=u"Search for content",
... value_type=schema.Choice(
... source=ArchetypesContentSourceBinder()))
Optionally, instead of storing Archetypes UIDs, you can choose to use
``persistent.wref``, i.e. weak references, instead of UIDs:
>>> from plone.app.z3cform.queryselect import uid2wref
>>> factory = uid2wref(ISelection['items'])
To store weak references instead of UIDs you would register such a
factory as a component adapting the context. The factory
automatically provides the interface which defines the field.
(XXX: Please rewrite this paragraph.)
=====================
KSS inline validation
=====================
First, let's set up KSS debug mode:
>>> from zope.interface import alsoProvides
>>> from kss.core.tests.base import IDebugRequest
>>> from zope.publisher.browser import TestRequest
>>> from zope.annotation.interfaces import IAttributeAnnotatable
>>> def make_request(form={}):
... request = TestRequest()
... request.form.update(form)
... alsoProvides(request, IDebugRequest)
... alsoProvides(request, IAttributeAnnotatable)
... return request
Then we create a simple z3c form
>>> from zope import interface, schema
>>> from z3c.form import form, field, button
>>> from plone.app.z3cform.layout import FormWrapper
>>> class MySchema(interface.Interface):
... age = schema.Int(title=u"Age")
>>> class MyForm(form.Form):
... fields = field.Fields(MySchema)
... ignoreContext = True # don't use context to get widget data
...
... @button.buttonAndHandler(u'Apply')
... def handleApply(self, action):
... data, errors = self.extractData()
... print data['age'] # ... or do stuff
>>> class MyFormWrapper(FormWrapper):
... form = MyForm
... label = u"Please enter your age"
>>> from zope.component import provideAdapter
>>> from zope.publisher.interfaces.browser import IBrowserRequest
>>> from zope.interface import Interface
>>> provideAdapter(adapts=(Interface, IBrowserRequest),
... provides=Interface,
... factory=MyFormWrapper,
... name=u"test-form")
Let's verify that worked:
>>> from zope.component import getMultiAdapter
>>> context = object()
>>> request = make_request()
>>> formWrapper = getMultiAdapter((context, request), name=u"test-form")
>>> formWrapper
<Products.Five.metaclass.MyFormWrapper object ...>
>>> formWrapper.form
<class 'plone.app.z3cform.tests.example.MyForm'>
>>> del context, request
Inline validation
-----------------
Inline validation is invoked via the @@kss_z3cform_inline_validation view.
>>> from zope.interface import Interface, implements
>>> class Bar(object):
... implements(Interface)
>>> context = Bar()
>>> request = make_request(form={'form.widgets.age': 'Title'})
>>> view = getMultiAdapter((context, request), name=u"kss_z3cform_inline_validation")
This is wired up with KSS. When the user leaves a form control with inline
validation enabled, it will be called with the following parameters:
>>> view.validate_input(formname=u'test-form', fieldname=u'form.widgets.age', value='Title')
[{'selectorType': 'css', 'params': {'html': u'<![CDATA[The entered value is not a valid integer literal.]]>', 'withKssSetup': u'True'},
'name': 'replaceInnerHTML',
'selector': u'#formfield-form-widgets-age div.fieldErrorBox'},
{'selectorType': 'htmlid',
'params': {'value': u'error'},
'name': 'addClass',
'selector': u'formfield-form-widgets-age'}]
>>> request = make_request(form={'form.widgets.age': '20'})
>>> view = getMultiAdapter((context, request), name=u"kss_z3cform_inline_validation")
>>> view.validate_input(formname=u'test-form', fieldname=u'form.widgets.age', value='20')
[{'selectorType': 'css', 'params': {}, 'name': 'clearChildNodes', 'selector': u'#formfield-form-widgets-age div.fieldErrorBox'},
{'selectorType': 'htmlid', 'params': {'value': u'error'}, 'name': 'removeClass', 'selector': u'formfield-form-widgets-age'},
{'selectorType': 'css', 'params': {'name': u'display', 'value': u'none'}, 'name': 'setStyle', 'selector': '.portalMessage'},
{'selectorType': 'htmlid', 'params': {'html': u'<![CDATA[<dt>info</dt><dd></dd>]]>', 'withKssSetup': u'True'},
'name': 'replaceInnerHTML', 'selector': 'kssPortalMessage'},
{'selectorType': 'htmlid', 'params': {'name': u'class', 'value': u'portalMessage info'},
'name': 'setAttribute', 'selector': 'kssPortalMessage'},
{'selectorType': 'htmlid', 'params': {'name': u'display', 'value': u'none'}, 'name': 'setStyle', 'selector': 'kssPortalMessage'}]
Changelog
=========
0.4.0 - 2008-07-31
------------------
* Add inline validation support with KSS
* Require zope.component <= 3.4.0 to prevent compatibility issues with
five.localsitemanager, of which a buggy version (0.3) is pinned by
plone.recipe.plone 3.1.4. Upgrade to this version if you're seeing::
...
Module five.localsitemanager.registry, line 176, in registeredUtilities
ValueError: too many values to unpack
0.3.2 - 2008-07-25
------------------
* Fixed a bug in macros.pt where 'has_groups' and 'show_default_label'
for fieldsets were set in the 'form' macro, rendering the 'field'
macro unusable by itself.
0.3.1 - 2008-07-24
------------------
* Fixed a bug where we would use the form macros defined in
plone.z3cform instead of our own.
0.3 - 2008-07-24
----------------
* Create this package from Plone-specific bits that have been factored
out of plone.z3cform.
plone.app.z3cform
=================
Abstract
========
A collection of widgets and templates, and other components for use
with `z3c.form`_ in Plone_. This is much related to `plone.z3cform`_,
the library that enables Zope 2 applications to use z3c.form.
.. _z3c.form: http://pypi.python.org/pypi/z3c.form
.. _Plone: http://plone.org
.. _plone.z3cform: http://pypi.python.org/pypi/plone.z3cform
WYSIWYG widget
==============
The ``wysiwyg`` package provides an implementation of the Plone
WYSIWYG widget compatible with ``z3c.form``. This will allow you to
use Kupu, FCKeditor and other editors compatible with the Plone
WYSIWYG interface in your ``z3c.form`` forms.
To use, simply set the widget factory for the widget you'd like to be
displayed with the WYSIWYG widget:
>>> from zope import interface, schema
>>> from z3c.form import form, field
>>> from z3c.form.interfaces import INPUT_MODE
>>> from plone.app.z3cform.wysiwyg.widget import WysiwygFieldWidget
>>> class IProfile(interface.Interface):
... name = schema.TextLine(title=u"Name")
... age = schema.Int(title=u"Age")
... bio = schema.Text(title=u"Bio")
>>> class MyForm(form.Form):
... fields = field.Fields(IProfile)
... fields['bio'].widgetFactory[INPUT_MODE] = WysiwygFieldWidget
Query select widget
===================
The ``queryselect`` module provides a query source compatible with
``z3c.formwidget.query`` which combines to a selection field that can
be queried.
The native value type for the widget is Archetypes UID collections.
The default implementation will simply search using the
``SearchableText`` index in the portal catalog.
This is how your form schema could look like:
>>> from zope import interface, schema
>>> from plone.app.z3cform.queryselect import ArchetypesContentSourceBinder
>>> class ISelection(interface.Interface):
... items = schema.Set(
... title=u"Selection",
... description=u"Search for content",
... value_type=schema.Choice(
... source=ArchetypesContentSourceBinder()))
Optionally, instead of storing Archetypes UIDs, you can choose to use
``persistent.wref``, i.e. weak references, instead of UIDs:
>>> from plone.app.z3cform.queryselect import uid2wref
>>> factory = uid2wref(ISelection['items'])
To store weak references instead of UIDs you would register such a
factory as a component adapting the context. The factory
automatically provides the interface which defines the field.
(XXX: Please rewrite this paragraph.)
=====================
KSS inline validation
=====================
First, let's set up KSS debug mode:
>>> from zope.interface import alsoProvides
>>> from kss.core.tests.base import IDebugRequest
>>> from zope.publisher.browser import TestRequest
>>> from zope.annotation.interfaces import IAttributeAnnotatable
>>> def make_request(form={}):
... request = TestRequest()
... request.form.update(form)
... alsoProvides(request, IDebugRequest)
... alsoProvides(request, IAttributeAnnotatable)
... return request
Then we create a simple z3c form
>>> from zope import interface, schema
>>> from z3c.form import form, field, button
>>> from plone.app.z3cform.layout import FormWrapper
>>> class MySchema(interface.Interface):
... age = schema.Int(title=u"Age")
>>> class MyForm(form.Form):
... fields = field.Fields(MySchema)
... ignoreContext = True # don't use context to get widget data
...
... @button.buttonAndHandler(u'Apply')
... def handleApply(self, action):
... data, errors = self.extractData()
... print data['age'] # ... or do stuff
>>> class MyFormWrapper(FormWrapper):
... form = MyForm
... label = u"Please enter your age"
>>> from zope.component import provideAdapter
>>> from zope.publisher.interfaces.browser import IBrowserRequest
>>> from zope.interface import Interface
>>> provideAdapter(adapts=(Interface, IBrowserRequest),
... provides=Interface,
... factory=MyFormWrapper,
... name=u"test-form")
Let's verify that worked:
>>> from zope.component import getMultiAdapter
>>> context = object()
>>> request = make_request()
>>> formWrapper = getMultiAdapter((context, request), name=u"test-form")
>>> formWrapper
<Products.Five.metaclass.MyFormWrapper object ...>
>>> formWrapper.form
<class 'plone.app.z3cform.tests.example.MyForm'>
>>> del context, request
Inline validation
-----------------
Inline validation is invoked via the @@kss_z3cform_inline_validation view.
>>> from zope.interface import Interface, implements
>>> class Bar(object):
... implements(Interface)
>>> context = Bar()
>>> request = make_request(form={'form.widgets.age': 'Title'})
>>> view = getMultiAdapter((context, request), name=u"kss_z3cform_inline_validation")
This is wired up with KSS. When the user leaves a form control with inline
validation enabled, it will be called with the following parameters:
>>> view.validate_input(formname=u'test-form', fieldname=u'form.widgets.age', value='Title')
[{'selectorType': 'css', 'params': {'html': u'<![CDATA[The entered value is not a valid integer literal.]]>', 'withKssSetup': u'True'},
'name': 'replaceInnerHTML',
'selector': u'#formfield-form-widgets-age div.fieldErrorBox'},
{'selectorType': 'htmlid',
'params': {'value': u'error'},
'name': 'addClass',
'selector': u'formfield-form-widgets-age'}]
>>> request = make_request(form={'form.widgets.age': '20'})
>>> view = getMultiAdapter((context, request), name=u"kss_z3cform_inline_validation")
>>> view.validate_input(formname=u'test-form', fieldname=u'form.widgets.age', value='20')
[{'selectorType': 'css', 'params': {}, 'name': 'clearChildNodes', 'selector': u'#formfield-form-widgets-age div.fieldErrorBox'},
{'selectorType': 'htmlid', 'params': {'value': u'error'}, 'name': 'removeClass', 'selector': u'formfield-form-widgets-age'},
{'selectorType': 'css', 'params': {'name': u'display', 'value': u'none'}, 'name': 'setStyle', 'selector': '.portalMessage'},
{'selectorType': 'htmlid', 'params': {'html': u'<![CDATA[<dt>info</dt><dd></dd>]]>', 'withKssSetup': u'True'},
'name': 'replaceInnerHTML', 'selector': 'kssPortalMessage'},
{'selectorType': 'htmlid', 'params': {'name': u'class', 'value': u'portalMessage info'},
'name': 'setAttribute', 'selector': 'kssPortalMessage'},
{'selectorType': 'htmlid', 'params': {'name': u'display', 'value': u'none'}, 'name': 'setStyle', 'selector': 'kssPortalMessage'}]
Changelog
=========
0.4.0 - 2008-07-31
------------------
* Add inline validation support with KSS
* Require zope.component <= 3.4.0 to prevent compatibility issues with
five.localsitemanager, of which a buggy version (0.3) is pinned by
plone.recipe.plone 3.1.4. Upgrade to this version if you're seeing::
...
Module five.localsitemanager.registry, line 176, in registeredUtilities
ValueError: too many values to unpack
0.3.2 - 2008-07-25
------------------
* Fixed a bug in macros.pt where 'has_groups' and 'show_default_label'
for fieldsets were set in the 'form' macro, rendering the 'field'
macro unusable by itself.
0.3.1 - 2008-07-24
------------------
* Fixed a bug where we would use the form macros defined in
plone.z3cform instead of our own.
0.3 - 2008-07-24
----------------
* Create this package from Plone-specific bits that have been factored
out of plone.z3cform.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
plone.app.z3cform-0.4.0.tar.gz
(20.3 kB
view hashes)
