Supermodel handlers
===================
This package contains handlers for two plone.supermodel namespaces: ``form``,
which can be used to set widgets, omitted fields, field modes and field
order, and ``security``, which can be used to set field read and write
permissions.
Test setup
----------
First, let's load this package's ZCML so that we can run the tests:
>>> configuration = """\
...
...
...
...
...
...
... """
>>> from StringIO import StringIO
>>> from zope.configuration import xmlconfig
>>> xmlconfig.xmlconfig(StringIO(configuration))
XML sample
----------
Next, let's define a sample model that exercises the various ``form`` and
``security`` attributes.
>>> schema = """\
...
...
...
...
... One
...
...
... Two
...
...
... Three
...
...
...
... """
Notes:
* To omit a field from all forms, use ``form:omitted="true"``. To omit a field
only from some forms, specify a form interface like
``form:omitted="z3c.form.interfaces.IForm:true"``. Multiple interface:value
settings may be specified, separated by spaces.
* To re-order fields, use ``form:after`` or ``form:before``. The value should
be either ``'*'``, to put the field first/last in the form, or the name of a
another field. Use ``'.fieldname'`` to refer to field in the current schema
(or a base schema). Use a fully prefixed name (e.g.
``'my.package.ISomeSchema'``) to refer to a field in another schema. Use an
unprefixed name to refer to a field in the default schema for the form.
* To turn a field into a view mode or hidden field, use ``form:mode``. The
mode may be set for only some forms by specifying a form interface in the
same manner as for ``form:omitted``.
* To set a custom widget for a field, use ``form:widget`` to give a fully
qualified name to the field widget factory.
* To set a custom validator for a field, use ``form:validator`` to give a fully
qualified name to the field validator factory.
* To set a read or write permission, use ``security:read-permission`` or
``security:write-permission``. The value should be the name of an
``IPermission`` utility.
We can load this using plone.supermodel:
>>> from plone.supermodel import loadString
>>> model = loadString(schema)
The interface defined in the model should now have the relevant form data:
>>> from plone.autoform.interfaces import OMITTED_KEY, WIDGETS_KEY, \
... MODES_KEY, ORDER_KEY, READ_PERMISSIONS_KEY, WRITE_PERMISSIONS_KEY
>>> model.schema.getTaggedValue(WIDGETS_KEY)
{'three': 'z3c.form.browser.password.PasswordFieldWidget'}
>>> model.schema.getTaggedValue(OMITTED_KEY)
[(, 'one', 'true'), (, 'three', 'true'), (, 'three', 'false')]
>>> model.schema.getTaggedValue(ORDER_KEY)
[('one', 'after', 'two'), ('three', 'before', 'two')]
>>> model.schema.getTaggedValue(MODES_KEY)
[(, 'three', 'input'), (, 'two', 'hidden')]
>>> model.schema.getTaggedValue(READ_PERMISSIONS_KEY)
{'one': 'zope2.View'}
>>> model.schema.getTaggedValue(WRITE_PERMISSIONS_KEY)
{'one': 'cmf.ModifyPortalContent'}
See autoform.txt for details on how this form data is used to manipulate
form layout.