How to make forms for Plone 3 the easy way
How to use z3c.form in Plone to create easy and flexible forms. Forget about complicated ways of making forms!
plone.app.z3cform is a Zope package that allows you to easily use z3c.form in your Plone add-on.
Why you should consider using z3c.form
- Because Archetypes forms are hard to use independently of content types. This has led to several hacks in the past, where Archetypes content types were misused as tools, survey forms etc.
- Because zope.formlib is often too inflexible and hacky, due to its lack of adaptability and lack of a solid set of widgets.
I've been using z3c.form within Plone extensively for the Singing & Dancing newsletter add-on, and it's been like a breath of fresh air! No hackery, no getting in the way; it's a powerful set of tools for doing what you want to do: make forms.
What is plone.app.z3cform?
plone.app.z3cform is a package that provides widgets and other utilities for making forms in Plone. It also, contains templates for Plone for its big brother, the plone.z3cform package. plone.z3cform in turn is a very thin layer around z3c.form. Forms that you make with plone.app.z3cform are essentially the same as pure Zope 3 forms built with z3c.form. No strings attached, and no special Zope 2/Plone hacks required (like self.context.aq_inner). z3c.form comes with excellent documentation, found in both the z3c.form source tree and online.
How do I use it?
plone.app.z3cform requires Plone 3.0 or higher, and the use of buildout.
Depending on z3c.form
plone.app.z3cform is available PyPI. If you already know how to depend on another package in your application, you can read ahead. A dependency is simply declared by adding the following to the install_requires section of your package's setup.py:
# ...
setup(
# ...
install_requires=[
'plone.app.z3cform',
'my.other.package',
],
# ...
)
In your application package's configure.zcml file you have to declare a dependency on the plone.app.z3cform configuration, like this:
<configure xmlns="http://namespaces.zope.org/zope">
<include package="plone.app.z3cform" />
...
</configure>
Using version pins in buildout
To use plone.z3cform, you will need to add a few version pins to your buildout, since plone.z3cform depends on newer versions of some core components. Something like this should work:
[buildout] ... versions = versions [versions] z3c.form = 1.9.0 zope.i18n = 3.4.0 zope.testing = 3.4.0 zope.component = 3.4.0 zope.securitypolicy = 3.4.0 zope.app.zcmlfiles = 3.4.3
Your mileage may vary. The Singing & Dancing development buildout is an example of a buildout that uses plone.z3cform, through a dedicated "extends file".
Examples
Tons of examples of using z3c.form can be found online. This is an example of a simple form for Plone:
>>> from zope import interface, schema
>>> from z3c.form import form, field, button
>>> from plone.app.z3cform.layout import wrap_form
>>> 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
... label = u"Please enter your age"
...
... @button.buttonAndHandler(u'Apply')
... def handleApply(self, action):
... data, errors = self.extractData()
... print data['age'] # ... or do stuff
>>> MyView = wrap_form(MyForm)
By using the wrap_form method, we make sure that our form is wrapped in a standard Plone layout, and is placed in the content area. This means that you can use your form class independently of layout in any part of your Plone site, e.g. in portlets or viewlets. It also means that you don't need your form classes to inherit from Acquisition or Five.
The MyView class is now ready for registration via your standard browser:page directive. For more details on the wrap_form function and how the layout works, see the plone.z3cform.layout module.
For more examples of forms within Plone, please refer to the project's homepage, Kamon Ayeva's two blog posts: 1 and 2, and see the Singing & Dancing packages.
If you have questions, don't hesitate to contact Plone's Add-on Product Developers list, or the authors of Singing & Dancing.
Visit our