plone.autoform
==============
.. contents:: Contents
Introduction
------------
``plone.autoform`` builds custom `z3c.form`_ forms based on a model (schema)
of what fields to include and what widgets and options should be used for each
field. This model is defined as a `zope.schema`_-based schema, but additional
hints can be supplied to control aspects of form display not normally specified
in a Zope schema.
Basic schema-based forms
------------------------
To use the automatic form setup, mix in the following base class in your
forms::
>>> from plone.autoform.form import AutoExtensibleForm
and then provide the ``schema`` (a schema interface) and optionally the
``additionalSchemata`` (a list of schema interfaces) attributes on your form::
class MyForm(AutoExtensibleForm, form.EditForm):
schema = IMySchema
additionalSchemata = (ISchemaOne, ISchemaTwo,)
# ...
For dynamic forms, you could of course make ``schema`` and
``additionalSchemata`` into properties. For example, `plone.dexterity`_ extends the
basic AutoExtensibleForm so that ``schema`` is the content type schema and
``additionalSchemata`` is a list of field provider schemas associated with
behaviors.
Controlling form presentation
-----------------------------
Directives can be specified in the schema to control aspects of form presentation.
Changing a field's display mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A field's widget can be displayed in several "modes":
* input - allows the user to enter data into the field
* display - a read-only indication of the field's value
* hidden - a record of the field's value that is included only in the HTML source
The mode can be controlled using the ``mode`` directive::
from plone.supermodel import model
from plone.autoform import directives as form
class IMySchema(model.Schema):
form.mode(secret='hidden')
form.mode(IEditForm, secret='input')
secret = schema.TextLine(
title=u"Secret",
default=u"Secret stuff (except on edit forms)"
)
In this case the mode for the ``secret`` field is set to 'hidden' for most forms,
but 'input' for forms that provide the IEditForm interface.
The corresponding supermodel XML directive is ``form:mode``::
<field type="zope.schema.TextLine"
name="secret"
form:mode="z3c.form.interfaces.IForm:hidden z3c.form.interfaces.IEditForm:input">
<title>Secret</title>
<description>Secret stuff (except on edit forms)</description>
</field>
The mode can be specified briefly if it should be the same for all forms::
<field type="zope.schema.TextLine"
name="secret"
form:mode="hidden">
<title>Secret</title>
<description>Secret stuff</description>
</field>
In other words, ``form:mode`` may be either a single mode, or a space-separated
list of form_interface:mode pairs.
Omitting fields
~~~~~~~~~~~~~~~
A field can be omitted entirely from all forms, or from some forms,
using the ``omitted`` and ``no_omit`` directives. In this example,
the ``dummy`` field is omitted from all forms, and the ``edit_only``
field is omitted from all forms except those that provide the
IEditForm interface::
from z3c.form.interfaces import IEditForm
from plone.supermodel import model
from plone.autoform import directives as form
class IMySchema(model.Schema):
form.omitted('dummy')
dummy = schema.Text(
title=u"Dummy"
)
form.omitted('edit_only')
form.no_omit(IEditForm, 'edit_only')
edit_only = schema.TextLine(
title = u'Only included on edit forms',
)
In supermodel XML, this can be specified as::
<field type="zope.schema.TextLine"
name="dummy"
form:omitted="true">
<title>Dummy</title>
</field>
<field type="zope.schema.TextLine"
name="edit-only"
form:omitted="z3c.form.interfaces.IForm:true z3c.form.interfaces.IEditForm:false">
<title>Only included on edit form</title>
</field>
``form:omitted`` may be either a single boolean value, or a space-separated
list of form_interface:boolean pairs.
Re-ordering fields
~~~~~~~~~~~~~~~~~~
A field's position in the form can be influenced using the ``order_before``
and ``order_after`` directives. In this example, the ``not_last`` field
is placed before the ``summary`` field even though it is defined afterward::
from plone.supermodel import model
from plone.autoform import directives as form
class IMySchema(model.Schema):
summary = schema.Text(
title=u"Summary",
description=u"Summary of the body",
readonly=True
)
form.order_before(not_last='summary')
not_last = schema.TextLine(
title=u"Not last",
)
The value passed to the directive may be either '*' (indicating before or after
all fields) or the name of another field. Use ``'.fieldname'`` to refer to
field in the current schema or a base schema. Prefix with the schema name (e.g.
``'IDublinCore.title'``) to refer to a field in another schema. Use an
unprefixed name to refer to a field in the current or the default schema for
the form.
In supermodel XML, the directives are called ``form:before`` and ``form:after``.
For example::
<field type="zope.schema.TextLine"
name="not_last"
form:before="*">
<title>Not last</title>
</field>
Organizing fields into fieldsets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Fields can be grouped into fieldsets, which will be rendered within an HTML
``<fieldset>`` tag. In this example the ``footer`` and ``dummy`` fields
are placed within the ``extra`` fieldset::
from plone.supermodel import model
from plone.autoform import directives as form
class IMySchema(model.Schema):
model.fieldset('extra',
label=u"Extra info",
fields=['footer', 'dummy']
)
footer = schema.Text(
title=u"Footer text",
)
dummy = schema.Text(
title=u"Dummy"
)
In supermodel XML fieldsets are specified by grouping fields within a
``<fieldset>`` tag::
<fieldset name="extra" label="Extra info">
<field name="footer" type="zope.schema.TextLine">
<title>Footer text</title>
</field>
<field name="dummy" type="zope.schema.TextLine">
<title>Dummy</title>
</field>
</fieldset>
Changing a field's widget
~~~~~~~~~~~~~~~~~~~~~~~~~
Usually, z3c.form picks a widget based on the type of your field.
You can change the widget using the ``widget`` directive if you want
users to enter or view data in a different format. For example,
here we change the widget for the ``human`` field to use yes/no
radio buttons instead of a checkbox::
from plone.supermodel import model
from plone.autoform import directives as form
from z3c.form.browser.radio import RadioFieldWidget
class IMySchema(model.Schema):
form.widget('human', RadioFieldWidget)
human = schema.Bool(
title = u'Are you human?',
)
You can also pass widget parameters to control attributes of the
widget. For example, here we keep the default widget, but
set a CSS class::
from plone.supermodel import model
from plone.autoform import directives as form
from z3c.form.browser.radio import RadioWidget
class IMySchema(model.Schema):
form.widget('human', klass='annoying')
human = schema.Bool(
title = u'Are you human?',
)
In supermodel XML the widget is specified using a ``<form:widget>`` tag, which
can have its own elements specifying parameters::
<field name="human" type="zope.schema.TextLine">
<title>Are you human?</title>
<form:widget type="z3c.form.browser.radio.RadioWidget">
<klass>annoying</klass>
</form:widget>
</field>
Note: In order to be included in the XML representation of a schema,
widget parameters must be handled by a WidgetExportImportHandler utility.
There is a default one which handles the attributes defined in
``z3c.form.browser.interfaces.IHTMLFormElement``.
Protect a field with a permission
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By default, fields are included in the form regardless of the user's
permissions. Fields can be protected using the ``read_permission``
and ``write_permission`` directives. The read permission is checked when
the field is in display mode, and the write permission is checked when
the field is in input mode. The permission should be given with its
Zope 3-style name (i.e. cmf.ManagePortal rather than 'Manage portal').
In this example, the ``secret`` field is protected by the
``cmf.ManagePortal`` permission as both a read and write permission.
This means that in both display and input modes, the field will
only be included in the form for users who have that permission::
from plone.supermodel import model
from plone.autoform import directives as form
class IMySchema(model.Schema):
form.read_permission(secret='cmf.ManagePortal')
form.write_permission(secret='cmf.ManagePortal')
secret = schema.TextLine(
title = u'Secret',
)
In supermodel XML the directives are ``security:read-permission`` and
``security:write-permission``::
<field type="zope.schema.TextLine"
name="secret"
security:read-permission="cmf.ManagePortal"
security:write-permission="cmf.ManagePortal">
<title>Secret</title>
</field>
Display Forms
-------------
Sometimes rather than rendering a form for data entry, you want to display
stored values based on the same schema. This can be done using a "display form."
The display form renders each field's widget in "display mode," which means
that it shows the field value in read-only form rather than as a form input.
To use the display form, create a view that extends ``WidgetsView`` like this:
>>> from plone.autoform.view import WidgetsView
>>> class MyView(WidgetsView):
... schema = IMySchema
... additionalSchemata = (ISchemaOne, ISchemaTwo,)
...
... # ...
To render the form, do not override ``__call__()``. Instead, either implement
the ``render()`` method, set an ``index`` attribute to a page template or
other callable, or use the ``template`` attribute of the ``<browser:page />``
ZCML directive when registering the view.
In the template, you can use the following variables:
* ``view/w`` is a dictionary of all widgets, including those from non-default
fieldsets (by contrast, the ``widgets`` variable contains only those
widgets in the default fieldset). The keys are the field names, and the
values are widget instances. To render a widget (in display mode), you can
do ``tal:replace="structure view/w/myfield/render" />``.
* ``view/fieldsets`` is a dictionary of all fieldsets (not including the
default fieldset, i.e. those widgets not placed into a fieldset). They keys
are the fieldset names, and the values are the fieldset form instances,
which in turn have variables like ``widgets`` given a list of all widgets.
Behind the scenes: how autoform directives work
-----------------------------------------------
Zope schema fields do not allow storing arbitrary key-value data associated
with a particular field. However, arbitrary data can be stored in a
dictionary on the schema (interface) known as the "tagged values."
This is where ``plone.autoform`` keeps track of its extra hints,
whether they are configured via Python directives, an XML model, or some
other way.
The tagged values are stored under various keys, which are defined
in the ``plone.autoform.interfaces`` module. They can be set several ways:
* Manually, by using ``setTaggedValue()`` on an interface.
* By loading the schema from a `plone.supermodel`_ XML file and using the
``form:`` prefix
* By using the directives from ``plone.autoform.directives`` while defining
a schema in Python.
Source Code
===========
Contributors please read the document `Process for Plone core's development <https://docs.plone.org/develop/coredev/docs/index.html>`_
Sources are at the `Plone code repository hosted at Github <https://github.com/plone/plone.autoform>`_.
.. _z3c.form: http://pypi.python.org/pypi/z3c.form
.. _zope.schema: http://pypi.python.org/pypi/zope.schema
.. _plone.supermodel: http://pypi.python.org/pypi/plone.supermodel
.. _plone.dexterity: http://pypi.python.org/pypi/plone.dexterity
Changelog
=========
.. You should *NOT* be adding new change log entries to this file.
You should create a file in the news directory instead.
For helpful instructions, please see:
https://github.com/plone/plone.releaser/blob/master/ADD-A-NEWS-ITEM.rst
.. towncrier release notes start
2.0.2 (2024-01-19)
------------------
Internal:
- Update configuration files.
[plone devs] (55bda5c9)
2.0.1 (2023-03-22)
------------------
Internal:
- Update configuration files.
[plone devs] (243ca9ec)
2.0.0 (2022-11-23)
------------------
Bug fixes:
- Final release for Plone 6.0.0. [maurits] (#600)
2.0.0a1 (2022-03-23)
--------------------
Breaking changes:
- Plone 6 only. (#41)
New features:
- Fixes for latest z3c.form
[petschki] (#40)
- Reimplementation of backported ObjectSubForm and ISubformFactory
[petschki] (#41)
1.9.0 (2020-04-20)
------------------
New features:
- Support for zope.interface 5.
See https://github.com/zopefoundation/zope.interface/pull/183#issuecomment-599547556
[jensens] (#39)
1.8.2 (2020-03-09)
------------------
Bug fixes:
- Decrease the loglevel of "Field move to non-existing: ..." (#21)
1.8.1 (2018-10-31)
------------------
Bug fixes:
- Remove the dummy security manager on test tear down
[ale-rt]
1.8.0 (2018-09-26)
------------------
New features:
- Add support for python 3
[pbauer]
1.7.5 (2018-02-04)
------------------
Bug fixes:
- Prepare for Python 2 / 3 compatibility
[pbauer]
- Minor fixes on testing that could avoid having test isolation problems.
[gforcada]
1.7.4 (2017-11-24)
------------------
New features:
- Allow configuration of fieldsets via ``plone.supermodel`` fieldset directives via a schema without fields.
This can be used to create a Plone behavior for stable ordering of fieldsets.
[thet]
- Add handler registration for text input widgets to support e.g. 'placeholder'
parameter in parameterized widgets
[datakurre]
1.7.3 (2017-06-03)
------------------
Bug fixes:
- Reduce field move failure logging from error to warning.
Log more information like full rule.
[jensens]
- Fix traceback in updateFieldsFromSchemata for forms with no schema.
[davisagli]
- Clean up code.
[gforcada]
- Remove unittest2 dependency
[kakshay21]
1.7.2 (2017-04-01)
------------------
New features:
- Make of tracebacks of ``plone.autoform.widgets.ParameterizedWidget`` calls more verbose in order to ease debugging.
[jensens]
1.7.1 (2017-02-12)
------------------
Bug fixes:
- Make sure WidgetsView doesn't use acquisition in Zope 4. [davisagli]
1.7.0 (2016-06-07)
------------------
Incompatibilities:
- Because of the ordering fix the field order in forms may be different.
Before this fix the order was a gamble dependent on schema order.
Schema form hints ``order_after`` and ``order_before`` may need minor adjustments.
``plone.autoform.utils.processFieldMoves`` was deprecated,
but still works as before.
The new functionality is now part of ``plone.autoform.base.AutoFields``.
[jensens]
New:
- Fieldset labels/descriptions we're taken from first occurrence.
It was not possible to override them in a subsequent directive.
Also it was not possible to set them in a subsequent directive, if it was not set before.
Now subsequent directives w/o a label/description are just adding the field to the fieldset.
If a different label and/or description is given, it replaces the existing prior loaded one.
[jensens]
- The order of the fieldsets can be defined now explicitly with the ``plone.supermodel.directives.fieldset`` directive.
``plone.autoform`` now does the sorting while fieldset processing.
[jensens]
Fixes:
- Implementation on how field ordering happens was unreproducible if same schemas are coming in in different orders.
New implementation build a well defined rule tree and processes then the field moves,
almost independent from the schema order.
[jensens]
- Update setup.py url
[esteele]
1.6.2 (2016-02-20)
------------------
Fixes:
- Fix test for changed ``zope.interface`` comparison method, which
incorrectly reports two different Interfaces from the same module
but with empty name as being equal. [thet]
1.6.1 (2014-10-20)
------------------
- pep8 cleanup, utf8-header,sorted imports, readability, ...
[jensens]
- Fix issue where multiple (plone.supermodel) fieldset directive calls for the
same fieldset name resulted to duplicate fieldsets (e.g. when updating
fieldset with new fields in a subschema)
[datakurre]
1.6 (2014-02-22)
----------------
- Replace deprecated test assert statements.
[timo]
- Support anonymous schema (dynamic interfaces with and empty
__name__ attribute) in autoGroups, opting to use prefix as
group name for such cases. This allows subclasses of
AutoExtensibleForm to implement getPrefix() method as
a sufficient condition to support an unnamed schema.
[seanupton]
1.5 (2013-08-14)
----------------
- Added an option on form to allow display of empty fieldsets.
[thomasdesvenain]
- fix tests
[vangheem]
1.4 (2013-05-23)
----------------
- Enhance the widget directive to allow for specifying widget parameters
within the schema.
[davisagli]
- Support passing widget classes in the widget directive in addition to
IFieldWidgets.
[davisagli]
- Support serializing widget parameters to XML. This requires implementing
a IWidgetExportImportHandler utility for the widget type.
[davisagli]
1.3 (2012-08-30)
----------------
- Avoid dependency on z3c.form.testing.
[hannosch]
1.2 (2012-04-15)
----------------
- Moved form schema directives here from plone.directives.form, and
reimplemented them as plone.supermodel directives to avoid depending on
grok. Included directives: omitted, no_omit, mode, widget, order_before,
order_after, read_permission, write_permission
[davisagli]
1.1 - 2012-02-20
----------------
- Added the AutoObjectSubForm class to support form hints for
object widget subforms.
[jcbrand]
1.0 - 2011-05-13
----------------
- Raise a NotImplementedError instead of NotImplemented as that is not
an exception but meant for comparisons and is not callable.
[maurits]
1.0b7 - 2011-04-29
------------------
- Check to make sure that interfaces and field widgets resolved by the
supermodel handler are of the correct type.
[elro]
- Add form:validator support for supermodel.
[elro]
- Fix issue where permission checks were not applied correctly to schemas being
added with prefixes.
[davisagli]
- Add MANIFEST.in.
[WouterVH]
1.0b6 - 2011-02-11
------------------
- Fix WidgetsView so that _update and update do not clash.
[elro]
- Fix view.txt doctest to test actual behaviour, not artifacts from test setup.
[elro]
1.0b5 - 2011-01-11
------------------
- Use five.ManageSite permission to check field permissions. We'll avoid
sniffing for Five/CMFCore permissions.zcml difference between Zope 2.12 and
2.13. [esteele]
1.0b4 - 2010-08-05
------------------
- Fixed widget traversal for WidgetsView
http://groups.google.com/group/dexterity-development/browse_frm/thread/280016ece3ed1462
[29.08.2010, jbaumann]
- Make field permission checks use the field mode rather than the form mode.
Fixes http://code.google.com/p/dexterity/issues/detail?id=110
[optilude]
- Removed some dead code.
Fixes http://code.google.com/p/dexterity/issues/detail?id=132
[optilude, shywolf9982]
1.0b3 - 2010-04-20
------------------
- Properly handle the 'omitted' tagged value when it is set to 'false' for a
field.
[davisagli]
- Make it possible to set the 'omitted' and 'mode' settings only for particular
form interfaces.
[davisagli]
- Do not omit read-only fields when rendering a form in DISPLAY mode.
http://code.google.com/p/dexterity/issues/detail?id=118
[mj]
1.0b2 - 2009-07-12
------------------
- Changed API methods and arguments to mixedCase to be more consistent with
the rest of Zope. This is a non-backwards-compatible change. Our profuse
apologies, but it's now or never. :-/
If you find that you get import errors or unknown keyword arguments in your
code, please change names from foo_bar too fooBar, e.g. process_fields()
becomes processFields().
Note in particular that the additional_schemata property is now called
additionalSchemata. If you have implemented this property yourself, you will
need to rename it!
[optilude]
1.0b1 - 2009-04-17
------------------
- Initial release
Raw data
{
"_id": null,
"home_page": "http://github.com/plone/plone.autoform",
"name": "plone.autoform",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "plone form z3c.form",
"author": "Martin Aspeli",
"author_email": "optilude@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/58/a3/19bd060921eff7cbcab280efa1f6d78d29fcebd894a56a90b2612bccec94/plone.autoform-2.0.2.tar.gz",
"platform": null,
"description": "plone.autoform\n==============\n\n.. contents:: Contents\n\nIntroduction\n------------\n\n``plone.autoform`` builds custom `z3c.form`_ forms based on a model (schema)\nof what fields to include and what widgets and options should be used for each\nfield. This model is defined as a `zope.schema`_-based schema, but additional\nhints can be supplied to control aspects of form display not normally specified\nin a Zope schema.\n\n\nBasic schema-based forms\n------------------------\n\nTo use the automatic form setup, mix in the following base class in your\nforms::\n\n >>> from plone.autoform.form import AutoExtensibleForm\n\nand then provide the ``schema`` (a schema interface) and optionally the\n``additionalSchemata`` (a list of schema interfaces) attributes on your form::\n\n class MyForm(AutoExtensibleForm, form.EditForm):\n schema = IMySchema\n additionalSchemata = (ISchemaOne, ISchemaTwo,)\n # ...\n\nFor dynamic forms, you could of course make ``schema`` and\n``additionalSchemata`` into properties. For example, `plone.dexterity`_ extends the\nbasic AutoExtensibleForm so that ``schema`` is the content type schema and\n``additionalSchemata`` is a list of field provider schemas associated with\nbehaviors.\n\n\nControlling form presentation\n-----------------------------\n\nDirectives can be specified in the schema to control aspects of form presentation.\n\nChanging a field's display mode\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nA field's widget can be displayed in several \"modes\":\n\n* input - allows the user to enter data into the field\n* display - a read-only indication of the field's value\n* hidden - a record of the field's value that is included only in the HTML source\n\nThe mode can be controlled using the ``mode`` directive::\n\n from plone.supermodel import model\n from plone.autoform import directives as form\n\n class IMySchema(model.Schema):\n\n form.mode(secret='hidden')\n form.mode(IEditForm, secret='input')\n secret = schema.TextLine(\n title=u\"Secret\",\n default=u\"Secret stuff (except on edit forms)\"\n )\n\nIn this case the mode for the ``secret`` field is set to 'hidden' for most forms,\nbut 'input' for forms that provide the IEditForm interface.\n\nThe corresponding supermodel XML directive is ``form:mode``::\n\n <field type=\"zope.schema.TextLine\"\n name=\"secret\"\n form:mode=\"z3c.form.interfaces.IForm:hidden z3c.form.interfaces.IEditForm:input\">\n <title>Secret</title>\n <description>Secret stuff (except on edit forms)</description>\n </field>\n\nThe mode can be specified briefly if it should be the same for all forms::\n\n <field type=\"zope.schema.TextLine\"\n name=\"secret\"\n form:mode=\"hidden\">\n <title>Secret</title>\n <description>Secret stuff</description>\n </field>\n\nIn other words, ``form:mode`` may be either a single mode, or a space-separated\nlist of form_interface:mode pairs.\n\n\nOmitting fields\n~~~~~~~~~~~~~~~\n\nA field can be omitted entirely from all forms, or from some forms,\nusing the ``omitted`` and ``no_omit`` directives. In this example,\nthe ``dummy`` field is omitted from all forms, and the ``edit_only``\nfield is omitted from all forms except those that provide the\nIEditForm interface::\n\n from z3c.form.interfaces import IEditForm\n from plone.supermodel import model\n from plone.autoform import directives as form\n\n class IMySchema(model.Schema):\n\n form.omitted('dummy')\n dummy = schema.Text(\n title=u\"Dummy\"\n )\n\n form.omitted('edit_only')\n form.no_omit(IEditForm, 'edit_only')\n edit_only = schema.TextLine(\n title = u'Only included on edit forms',\n )\n\nIn supermodel XML, this can be specified as::\n\n <field type=\"zope.schema.TextLine\"\n name=\"dummy\"\n form:omitted=\"true\">\n <title>Dummy</title>\n </field>\n\n <field type=\"zope.schema.TextLine\"\n name=\"edit-only\"\n form:omitted=\"z3c.form.interfaces.IForm:true z3c.form.interfaces.IEditForm:false\">\n <title>Only included on edit form</title>\n </field>\n\n``form:omitted`` may be either a single boolean value, or a space-separated\nlist of form_interface:boolean pairs.\n\n\nRe-ordering fields\n~~~~~~~~~~~~~~~~~~\n\nA field's position in the form can be influenced using the ``order_before``\nand ``order_after`` directives. In this example, the ``not_last`` field\nis placed before the ``summary`` field even though it is defined afterward::\n\n from plone.supermodel import model\n from plone.autoform import directives as form\n\n class IMySchema(model.Schema):\n\n summary = schema.Text(\n title=u\"Summary\",\n description=u\"Summary of the body\",\n readonly=True\n )\n\n form.order_before(not_last='summary')\n not_last = schema.TextLine(\n title=u\"Not last\",\n )\n\nThe value passed to the directive may be either '*' (indicating before or after\nall fields) or the name of another field. Use ``'.fieldname'`` to refer to\nfield in the current schema or a base schema. Prefix with the schema name (e.g.\n``'IDublinCore.title'``) to refer to a field in another schema. Use an\nunprefixed name to refer to a field in the current or the default schema for\nthe form.\n\nIn supermodel XML, the directives are called ``form:before`` and ``form:after``.\nFor example::\n\n <field type=\"zope.schema.TextLine\"\n name=\"not_last\"\n form:before=\"*\">\n <title>Not last</title>\n </field>\n\n\nOrganizing fields into fieldsets\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nFields can be grouped into fieldsets, which will be rendered within an HTML\n``<fieldset>`` tag. In this example the ``footer`` and ``dummy`` fields\nare placed within the ``extra`` fieldset::\n\n from plone.supermodel import model\n from plone.autoform import directives as form\n\n class IMySchema(model.Schema):\n\n model.fieldset('extra',\n label=u\"Extra info\",\n fields=['footer', 'dummy']\n )\n\n footer = schema.Text(\n title=u\"Footer text\",\n )\n\n dummy = schema.Text(\n title=u\"Dummy\"\n )\n\nIn supermodel XML fieldsets are specified by grouping fields within a\n``<fieldset>`` tag::\n\n <fieldset name=\"extra\" label=\"Extra info\">\n <field name=\"footer\" type=\"zope.schema.TextLine\">\n <title>Footer text</title>\n </field>\n <field name=\"dummy\" type=\"zope.schema.TextLine\">\n <title>Dummy</title>\n </field>\n </fieldset>\n\n\nChanging a field's widget\n~~~~~~~~~~~~~~~~~~~~~~~~~\n\nUsually, z3c.form picks a widget based on the type of your field.\nYou can change the widget using the ``widget`` directive if you want\nusers to enter or view data in a different format. For example,\nhere we change the widget for the ``human`` field to use yes/no\nradio buttons instead of a checkbox::\n\n from plone.supermodel import model\n from plone.autoform import directives as form\n from z3c.form.browser.radio import RadioFieldWidget\n\n class IMySchema(model.Schema):\n form.widget('human', RadioFieldWidget)\n human = schema.Bool(\n title = u'Are you human?',\n )\n\nYou can also pass widget parameters to control attributes of the\nwidget. For example, here we keep the default widget, but\nset a CSS class::\n\n from plone.supermodel import model\n from plone.autoform import directives as form\n from z3c.form.browser.radio import RadioWidget\n\n class IMySchema(model.Schema):\n form.widget('human', klass='annoying')\n human = schema.Bool(\n title = u'Are you human?',\n )\n\nIn supermodel XML the widget is specified using a ``<form:widget>`` tag, which\ncan have its own elements specifying parameters::\n\n <field name=\"human\" type=\"zope.schema.TextLine\">\n <title>Are you human?</title>\n <form:widget type=\"z3c.form.browser.radio.RadioWidget\">\n <klass>annoying</klass>\n </form:widget>\n </field>\n\nNote: In order to be included in the XML representation of a schema,\nwidget parameters must be handled by a WidgetExportImportHandler utility.\nThere is a default one which handles the attributes defined in\n``z3c.form.browser.interfaces.IHTMLFormElement``.\n\nProtect a field with a permission\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nBy default, fields are included in the form regardless of the user's\npermissions. Fields can be protected using the ``read_permission``\nand ``write_permission`` directives. The read permission is checked when\nthe field is in display mode, and the write permission is checked when\nthe field is in input mode. The permission should be given with its\nZope 3-style name (i.e. cmf.ManagePortal rather than 'Manage portal').\n\nIn this example, the ``secret`` field is protected by the\n``cmf.ManagePortal`` permission as both a read and write permission.\nThis means that in both display and input modes, the field will\nonly be included in the form for users who have that permission::\n\n from plone.supermodel import model\n from plone.autoform import directives as form\n\n class IMySchema(model.Schema):\n form.read_permission(secret='cmf.ManagePortal')\n form.write_permission(secret='cmf.ManagePortal')\n secret = schema.TextLine(\n title = u'Secret',\n )\n\nIn supermodel XML the directives are ``security:read-permission`` and\n``security:write-permission``::\n\n <field type=\"zope.schema.TextLine\"\n name=\"secret\"\n security:read-permission=\"cmf.ManagePortal\"\n security:write-permission=\"cmf.ManagePortal\">\n <title>Secret</title>\n </field>\n\nDisplay Forms\n-------------\n\nSometimes rather than rendering a form for data entry, you want to display\nstored values based on the same schema. This can be done using a \"display form.\"\nThe display form renders each field's widget in \"display mode,\" which means\nthat it shows the field value in read-only form rather than as a form input.\n\nTo use the display form, create a view that extends ``WidgetsView`` like this:\n\n >>> from plone.autoform.view import WidgetsView\n >>> class MyView(WidgetsView):\n ... schema = IMySchema\n ... additionalSchemata = (ISchemaOne, ISchemaTwo,)\n ...\n ... # ...\n\nTo render the form, do not override ``__call__()``. Instead, either implement\nthe ``render()`` method, set an ``index`` attribute to a page template or\nother callable, or use the ``template`` attribute of the ``<browser:page />``\nZCML directive when registering the view.\n\nIn the template, you can use the following variables:\n\n* ``view/w`` is a dictionary of all widgets, including those from non-default\n fieldsets (by contrast, the ``widgets`` variable contains only those\n widgets in the default fieldset). The keys are the field names, and the\n values are widget instances. To render a widget (in display mode), you can\n do ``tal:replace=\"structure view/w/myfield/render\" />``.\n* ``view/fieldsets`` is a dictionary of all fieldsets (not including the\n default fieldset, i.e. those widgets not placed into a fieldset). They keys\n are the fieldset names, and the values are the fieldset form instances,\n which in turn have variables like ``widgets`` given a list of all widgets.\n\n\nBehind the scenes: how autoform directives work\n-----------------------------------------------\n\nZope schema fields do not allow storing arbitrary key-value data associated\nwith a particular field. However, arbitrary data can be stored in a\ndictionary on the schema (interface) known as the \"tagged values.\"\nThis is where ``plone.autoform`` keeps track of its extra hints,\nwhether they are configured via Python directives, an XML model, or some\nother way.\n\nThe tagged values are stored under various keys, which are defined\nin the ``plone.autoform.interfaces`` module. They can be set several ways:\n\n* Manually, by using ``setTaggedValue()`` on an interface.\n* By loading the schema from a `plone.supermodel`_ XML file and using the\n ``form:`` prefix\n* By using the directives from ``plone.autoform.directives`` while defining\n a schema in Python.\n\nSource Code\n===========\n\nContributors please read the document `Process for Plone core's development <https://docs.plone.org/develop/coredev/docs/index.html>`_\n\nSources are at the `Plone code repository hosted at Github <https://github.com/plone/plone.autoform>`_.\n\n\n.. _z3c.form: http://pypi.python.org/pypi/z3c.form\n.. _zope.schema: http://pypi.python.org/pypi/zope.schema\n.. _plone.supermodel: http://pypi.python.org/pypi/plone.supermodel\n.. _plone.dexterity: http://pypi.python.org/pypi/plone.dexterity\n\nChangelog\n=========\n\n.. You should *NOT* be adding new change log entries to this file.\n You should create a file in the news directory instead.\n For helpful instructions, please see:\n https://github.com/plone/plone.releaser/blob/master/ADD-A-NEWS-ITEM.rst\n\n.. towncrier release notes start\n\n2.0.2 (2024-01-19)\n------------------\n\nInternal:\n\n\n- Update configuration files.\n [plone devs] (55bda5c9)\n\n\n2.0.1 (2023-03-22)\n------------------\n\nInternal:\n\n\n- Update configuration files.\n [plone devs] (243ca9ec)\n\n\n2.0.0 (2022-11-23)\n------------------\n\nBug fixes:\n\n\n- Final release for Plone 6.0.0. [maurits] (#600)\n\n\n2.0.0a1 (2022-03-23)\n--------------------\n\nBreaking changes:\n\n\n- Plone 6 only. (#41)\n\n\nNew features:\n\n\n- Fixes for latest z3c.form\n [petschki] (#40)\n- Reimplementation of backported ObjectSubForm and ISubformFactory\n [petschki] (#41)\n\n\n1.9.0 (2020-04-20)\n------------------\n\nNew features:\n\n\n- Support for zope.interface 5. \n See https://github.com/zopefoundation/zope.interface/pull/183#issuecomment-599547556\n [jensens] (#39)\n\n\n1.8.2 (2020-03-09)\n------------------\n\nBug fixes:\n\n\n- Decrease the loglevel of \"Field move to non-existing: ...\" (#21)\n\n\n1.8.1 (2018-10-31)\n------------------\n\nBug fixes:\n\n- Remove the dummy security manager on test tear down\n [ale-rt]\n\n\n1.8.0 (2018-09-26)\n------------------\n\nNew features:\n\n- Add support for python 3\n [pbauer]\n\n\n1.7.5 (2018-02-04)\n------------------\n\nBug fixes:\n\n- Prepare for Python 2 / 3 compatibility\n [pbauer]\n\n- Minor fixes on testing that could avoid having test isolation problems.\n [gforcada]\n\n1.7.4 (2017-11-24)\n------------------\n\nNew features:\n\n- Allow configuration of fieldsets via ``plone.supermodel`` fieldset directives via a schema without fields.\n This can be used to create a Plone behavior for stable ordering of fieldsets.\n [thet]\n\n- Add handler registration for text input widgets to support e.g. 'placeholder'\n parameter in parameterized widgets\n [datakurre]\n\n\n\n1.7.3 (2017-06-03)\n------------------\n\nBug fixes:\n\n- Reduce field move failure logging from error to warning.\n Log more information like full rule.\n [jensens]\n\n- Fix traceback in updateFieldsFromSchemata for forms with no schema.\n [davisagli]\n\n- Clean up code.\n [gforcada]\n\n- Remove unittest2 dependency\n [kakshay21]\n\n\n1.7.2 (2017-04-01)\n------------------\n\nNew features:\n\n- Make of tracebacks of ``plone.autoform.widgets.ParameterizedWidget`` calls more verbose in order to ease debugging.\n [jensens]\n\n\n1.7.1 (2017-02-12)\n------------------\n\nBug fixes:\n\n- Make sure WidgetsView doesn't use acquisition in Zope 4. [davisagli]\n\n\n1.7.0 (2016-06-07)\n------------------\n\nIncompatibilities:\n\n- Because of the ordering fix the field order in forms may be different.\n Before this fix the order was a gamble dependent on schema order.\n Schema form hints ``order_after`` and ``order_before`` may need minor adjustments.\n ``plone.autoform.utils.processFieldMoves`` was deprecated,\n but still works as before.\n The new functionality is now part of ``plone.autoform.base.AutoFields``.\n [jensens]\n\nNew:\n\n- Fieldset labels/descriptions we're taken from first occurrence.\n It was not possible to override them in a subsequent directive.\n Also it was not possible to set them in a subsequent directive, if it was not set before.\n Now subsequent directives w/o a label/description are just adding the field to the fieldset.\n If a different label and/or description is given, it replaces the existing prior loaded one.\n [jensens]\n\n- The order of the fieldsets can be defined now explicitly with the ``plone.supermodel.directives.fieldset`` directive.\n ``plone.autoform`` now does the sorting while fieldset processing.\n [jensens]\n\nFixes:\n\n- Implementation on how field ordering happens was unreproducible if same schemas are coming in in different orders.\n New implementation build a well defined rule tree and processes then the field moves,\n almost independent from the schema order.\n [jensens]\n\n- Update setup.py url\n [esteele]\n\n\n1.6.2 (2016-02-20)\n------------------\n\nFixes:\n\n- Fix test for changed ``zope.interface`` comparison method, which\n incorrectly reports two different Interfaces from the same module\n but with empty name as being equal. [thet]\n\n\n1.6.1 (2014-10-20)\n------------------\n\n- pep8 cleanup, utf8-header,sorted imports, readability, ...\n [jensens]\n\n- Fix issue where multiple (plone.supermodel) fieldset directive calls for the\n same fieldset name resulted to duplicate fieldsets (e.g. when updating\n fieldset with new fields in a subschema)\n [datakurre]\n\n\n1.6 (2014-02-22)\n----------------\n\n- Replace deprecated test assert statements.\n [timo]\n\n- Support anonymous schema (dynamic interfaces with and empty\n __name__ attribute) in autoGroups, opting to use prefix as\n group name for such cases. This allows subclasses of\n AutoExtensibleForm to implement getPrefix() method as\n a sufficient condition to support an unnamed schema.\n [seanupton]\n\n\n1.5 (2013-08-14)\n----------------\n\n- Added an option on form to allow display of empty fieldsets.\n [thomasdesvenain]\n\n- fix tests\n [vangheem]\n\n\n1.4 (2013-05-23)\n----------------\n\n- Enhance the widget directive to allow for specifying widget parameters\n within the schema.\n [davisagli]\n\n- Support passing widget classes in the widget directive in addition to\n IFieldWidgets.\n [davisagli]\n\n- Support serializing widget parameters to XML. This requires implementing\n a IWidgetExportImportHandler utility for the widget type.\n [davisagli]\n\n\n1.3 (2012-08-30)\n----------------\n\n- Avoid dependency on z3c.form.testing.\n [hannosch]\n\n1.2 (2012-04-15)\n----------------\n\n- Moved form schema directives here from plone.directives.form, and\n reimplemented them as plone.supermodel directives to avoid depending on\n grok. Included directives: omitted, no_omit, mode, widget, order_before,\n order_after, read_permission, write_permission\n [davisagli]\n\n1.1 - 2012-02-20\n----------------\n\n- Added the AutoObjectSubForm class to support form hints for\n object widget subforms.\n [jcbrand]\n\n1.0 - 2011-05-13\n----------------\n\n- Raise a NotImplementedError instead of NotImplemented as that is not\n an exception but meant for comparisons and is not callable.\n [maurits]\n\n\n1.0b7 - 2011-04-29\n------------------\n\n- Check to make sure that interfaces and field widgets resolved by the\n supermodel handler are of the correct type.\n [elro]\n\n- Add form:validator support for supermodel.\n [elro]\n\n- Fix issue where permission checks were not applied correctly to schemas being\n added with prefixes.\n [davisagli]\n\n- Add MANIFEST.in.\n [WouterVH]\n\n\n1.0b6 - 2011-02-11\n------------------\n\n- Fix WidgetsView so that _update and update do not clash.\n [elro]\n\n- Fix view.txt doctest to test actual behaviour, not artifacts from test setup.\n [elro]\n\n\n1.0b5 - 2011-01-11\n------------------\n\n- Use five.ManageSite permission to check field permissions. We'll avoid\n sniffing for Five/CMFCore permissions.zcml difference between Zope 2.12 and\n 2.13. [esteele]\n\n\n1.0b4 - 2010-08-05\n------------------\n\n- Fixed widget traversal for WidgetsView\n http://groups.google.com/group/dexterity-development/browse_frm/thread/280016ece3ed1462\n [29.08.2010, jbaumann]\n\n- Make field permission checks use the field mode rather than the form mode.\n Fixes http://code.google.com/p/dexterity/issues/detail?id=110\n [optilude]\n\n- Removed some dead code.\n Fixes http://code.google.com/p/dexterity/issues/detail?id=132\n [optilude, shywolf9982]\n\n\n1.0b3 - 2010-04-20\n------------------\n\n- Properly handle the 'omitted' tagged value when it is set to 'false' for a\n field.\n [davisagli]\n\n- Make it possible to set the 'omitted' and 'mode' settings only for particular\n form interfaces.\n [davisagli]\n\n- Do not omit read-only fields when rendering a form in DISPLAY mode.\n http://code.google.com/p/dexterity/issues/detail?id=118\n [mj]\n\n\n1.0b2 - 2009-07-12\n------------------\n\n- Changed API methods and arguments to mixedCase to be more consistent with\n the rest of Zope. This is a non-backwards-compatible change. Our profuse\n apologies, but it's now or never. :-/\n\n If you find that you get import errors or unknown keyword arguments in your\n code, please change names from foo_bar too fooBar, e.g. process_fields()\n becomes processFields().\n\n Note in particular that the additional_schemata property is now called\n additionalSchemata. If you have implemented this property yourself, you will\n need to rename it!\n [optilude]\n\n\n1.0b1 - 2009-04-17\n------------------\n\n- Initial release\n",
"bugtrack_url": null,
"license": "LGPL",
"summary": "Tools to construct z3c.form forms",
"version": "2.0.2",
"project_urls": {
"Homepage": "http://github.com/plone/plone.autoform"
},
"split_keywords": [
"plone",
"form",
"z3c.form"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d86c22a1cd28b3b5f325c6736f075614a317c58ac5a43fc944e693c132b0e4ec",
"md5": "587ee7b73bc4dde9fdcd7e61bbd1bfde",
"sha256": "3f6d799b1dafed3b277d2193ecc7367bbb2deb8793627479ec30122dd4274ff0"
},
"downloads": -1,
"filename": "plone.autoform-2.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "587ee7b73bc4dde9fdcd7e61bbd1bfde",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 45160,
"upload_time": "2024-01-19T09:37:21",
"upload_time_iso_8601": "2024-01-19T09:37:21.357261Z",
"url": "https://files.pythonhosted.org/packages/d8/6c/22a1cd28b3b5f325c6736f075614a317c58ac5a43fc944e693c132b0e4ec/plone.autoform-2.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "58a319bd060921eff7cbcab280efa1f6d78d29fcebd894a56a90b2612bccec94",
"md5": "fa67ba2c524d1ab978bb2f48a9dc3a20",
"sha256": "64a43d345c8d10fb86f87267cb94ed6484e2443e6be40740ffa673184b0b2cf5"
},
"downloads": -1,
"filename": "plone.autoform-2.0.2.tar.gz",
"has_sig": false,
"md5_digest": "fa67ba2c524d1ab978bb2f48a9dc3a20",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 51290,
"upload_time": "2024-01-19T09:37:23",
"upload_time_iso_8601": "2024-01-19T09:37:23.318286Z",
"url": "https://files.pythonhosted.org/packages/58/a3/19bd060921eff7cbcab280efa1f6d78d29fcebd894a56a90b2612bccec94/plone.autoform-2.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-19 09:37:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "plone",
"github_project": "plone.autoform",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "plone.autoform"
}
JSON
