{
"info": {
"author": "Martin Aspeli",
"author_email": "optilude@gmail.com",
"bugtrack_url": null,
"classifiers": [
"Framework :: Plone",
"Framework :: Plone :: 4.3",
"Framework :: Plone :: 5.0",
"Framework :: Plone :: 5.1",
"Programming Language :: Python",
"Programming Language :: Python :: 2.6",
"Programming Language :: Python :: 2.7",
"Topic :: Software Development :: Libraries :: Python Modules"
],
"description": "=====================\nplone.directives.form\n=====================\n\nThis package provides optional, Grok-like directives for configuring\nforms, as defined by the `z3c.form`_ library, using XML schemata as defined by\n`plone.supermodel`_ and/or using widget form layout as defined by\n`plone.autoform`_. It depends on `five.grok`_, which in turn depends on the\nvarious re-usable grokcore.* packages, but not Grok itself.\n\n.. contents:: Contents\n\nInstallation\n------------\n\nTo use this package you must first install it, either by depending on it\nin your own ``setup.py`` (under the ``install_requires`` list), or by adding\nit directly to your buildout.\n\nThis will pull in a number of dependencies. You probably want to pin those\ndown to known-good versions by using a known-good version set. See the\ninstallation instructions of `five.grok`_ for a starting point.\n\nYou must also load the relevant configuration from ``meta.zcml`` and\n``configure.zcml``. For example, you could use statements like the following\nin your ``configure.zcml``::\n\n \n \n\nor if you declare dependencies in setup.py using install_requires::\n\n \n\nSchemata loaded from XML\n------------------------\n\n``plone.directives.form`` used to contain a directive for loading an XML-based\nschema model into a Python interface. This directive has moved to ``plone.supermodel``, as ``plone.supermodel.model.load``.\n\nForm widget hints\n-----------------\n\n``plone.directives.form`` used to contain a number of directives for generating\na form from a schema, using hints stored in tagged values on that schema to\ncontrol the form's layout and field widgets. These directives have now moved\nto other packages to avoid a dependency of Dexterity on grok.\n\nThe ``fieldset`` and ``primary`` directives are now in\n``plone.supermodel.model``.\n\nThe ``omitted``, ``no_omit``, ``mode``, ``widget``, ``order_before``,\n``order_after``, ``read_permission``, and ``write_permission`` directives are\nnow in ``plone.autoform.directives``.\n\nValue adapters\n--------------\n\nz3c.form has the concept of a \"value adapter\", a component that can provide\na value for an attribute (usually of widgets and buttons) at runtime. This\npackage comes with some helpful decorators to register value adapters for\ncomputed values. For example::\n\n from plone.directives import form\n from zope import schema\n\n class IMySchema(form.Schema):\n\n title = schema.TextLine(title=u\"Title\")\n\n @form.default_value(field=IMySchema['title'])\n def default_title(data):\n return data.context.suggested_title\n\nThe decorator takes one or more discriminators. The available discriminators\nfor ``default_value`` are:\n\ncontext\n The type of context (e.g. an interface)\n\nrequest\n The type of request (e.g. a layer marker interface). You can\n use 'layer' as an alias for 'request', but note that the data passed\n to the function will have a 'request' attribute only.\n\nview\n The type of form (e.g. a form instance or interface). You can\n use 'form' as an alias for 'view', but note that the data passed to\n the function will have 'view' attribute only.\n\nfield\n The field instance (or a field interface).\n\nwidget\n The widget type (e.g. an interface).\n\nYou must specify either ``field`` or ``widget``. The object passed to the\ndecorated function has an attribute for each discriminator.\n\nThere are two more decorators:\n\nwidget_label\n Provide a dynamic label for a widget. Takes the same discriminators as the\n ``default_value`` decorator.\n\nbutton_label -- Provide a dynamic label for a button. Takes parameters\n content (alias context), request (alias layer), form (alias view),\n manager and button.\n\nPlease note the rather unfortunate differences in naming between the button\ndescriptors (content vs. context, form vs. view) and the widget ones. The\ndescriptor will accept the same names, but the data object passed to the\nfunction will only contain the names as defined in z3c.form, so be careful.\n\nValidators\n----------\n\nBy default, z3c.form uses fields' native validation, as implemented by the\n``IField.validate()`` method, as well as field constraints (functions passed\nas the ``constraint`` parameter to fields) and schema invariants (using the\n``@zope.interface.invariant`` decorator in a schema interface). In addition,\nyou can define your own widget validators (for an individual field of the\nform) and widget manager validators (which cover the entire form). This is\nuseful if you do not want to define a validator on the schema, e.g. because\nthe schema is also used elsewhere, or if you want to create a more generic\nvalidator that is applied to any fields that match its discriminators.\n\nThis package provides a grokked decorator which you can use to define a simple\nwidget validator, called ``@form.validator()``::\n\n from plone.directives import form\n from zope import schema\n\n class IMySchema(form.Schema):\n\n title = schema.TextLine(title=u\"Title\")\n\n @form.validator(field=IMySchema['title'])\n def validateTitle(value):\n if value == value.upper():\n raise schema.ValidationError(u\"Please don't shout\")\n\nThe validator should return nothing if the field is valid, or raise an\n``zope.schema.ValidationError`` exception with an error message.\n\nThe ``@form.validator()`` decorator can take various keyword arguments that\ndetermine when the validator is invoked. These are:\n\ncontext\n The type of context (e.g. an interface)\n\nrequest\n The type of request (e.g. a layer marker interface).\n\nview\n The type of form (e.g. a form instance or interface).\n\nfield\n The field instance (or a field interface).\n\nwidget\n The widget type (e.g. an interface).\n\nNote that this validator function does not give access to the full context\nof the standard validator, such as the field, widget, context or request.\nIf you need that, you can create a standard validator adapter, e.g. using\n``grok.Adapter``. See the `z3c.form`_ documentation for details.\n\nAlso note that the standard field validator will be called before the custom\nvalidator is invoked. If you need to override the validator wholesale, you\ncan again do so with a custom adapter.\n\nError messages\n--------------\n\nWhen using custom validators, it is easy to supply a tailored error message.\nHowever, the error messages that arise from the default field validation\nmechanism (e.g. when a required field is omitted) are by necessity more\ngeneric. Sometimes, it may be necessary to override these messages to make\nthem more user friendly.\n\nTo customise an error message, you can use the ``@form.error_message`` grokked\ndecorator. For example::\n\n from plone.directives import form\n from zope import schema\n\n from zope.schema.interfaces import TooShort\n\n class IMySchema(form.Schema):\n\n title = schema.TextLine(title=u\"Title\", min_length=2)\n\n @form.error_message(error=TooShort, field=IMySchema['title'])\n def titleTooShort(value):\n return u\"The title '%s' is too short\" % value\n\nThe decorated function will be called when constructing an error message for\nthe given field. It should return a unicode string or translatable message.\nThe value passed is the value that failed validation.\n\nThe ``@form.error_message`` validator takes keyword arguments that determine\nwhen the message is used. It is possible to register a generic error message\nfor a given type of error that applies to all fields, or, as shown above,\na message specific to an individual field and error. The latter is more\ncommon. In general, you should be careful if you omit either or both of the\n``error`` and ``field`` discriminators.\n\nerror\n An exception class that represents the error. All errors inherit from\n ``zope.interface.Invalid``, and most error also inherit from\n ``zope.schema.interfaces.ValidationError``. See below for a list of\n common exception types.\nrequest\n The current request. Use this to tie the error to a specific browser\n layer interface.\nwidget\n The widget that was used. May be either a widget interface or a specific\n widget class.\nfield\n The field that was used, normally given as a field instance obtained from\n an interface, as illustrated above.\nform\n The current form, either as a class or an interface. This is useful if\n the same interface is used in more than one form, but you only want the\n error to be shown in one form.\ncontent\n The content item that is acting as the context for the form. May be given\n as either an interface or a class.\n\nNone of these parameters is required, but you would normally supply at least\n``error``. In most cases, you should also supply the ``field``, as shown\nabove.\n\nThe most common validation error exception types are defined in\n``zope.schema``, and can be imported from ``zope.schema.interfaces``:\n\n* ``RequiredMissing``, used when a required field is submitted without a value\n* ``WrongType``, used when a field is passed a value of an invalid type\n* ``TooBig`` and ``TooSmall``, used when a value is outside the ``min`` and/or\n ``max`` range specified for ordered fields (e.g. numeric or date fields)\n* ``TooLong`` and ``TooShort``, used when a value is outside the\n ``min_length`` and/or ``max_length`` range specified for length-aware fields\n (e.g. text or sequence fields)\n* ``InvalidValue``, used when a value is invalid, e.g. a non-ASCII character\n passed to an ASCII field\n* ``ConstraintNotSatisfied``, used when a ``constraint`` method returns\n ``False``\n* ``WrongContainedType``, used if an object of an invalid type is added\n to a sequence (i.e. the type does not conform to the field's\n ``value_type``)\n* ``NotUnique``, used if a uniqueness constraint is violated\n* ``InvalidURI``, used for ``URI`` fields if the value is not a valid URI\n* ``InvalidId``, used for ``Id`` fields if the value is not a valid id\n* ``InvalidDottedName``, used for ``DottedName`` fields if the value is not\n a valid dotted name\n\nForm base classes\n-----------------\n\nIf you need to create your own forms, this package provides a number of\nconvenient base classes that will be grokked much like a ``grok.View``.\n\nIn Zope 2.10, the grokkers take care of wrapping the form in a\n`plone.z3cform`_ FormWrapper as well. In Zope 2.12 and later, there is no\nwrapper by default. If you want one (e.g. if you are using a custom template\nand you need it to work in both Zope 2.10 and 2.12), you can use the\n``form.wrap()`` directive in the form class.\n\nThe base classes can all be imported from ``plone.directives.form``, e.g::\n\n from five import grok\n from plone.directives import form, button\n from z3c.form import field\n\n class MyForm(form.Form):\n grok.context(ISomeContext)\n grok.require('zope2.View')\n\n fields = field.Fields(IMyFormSchema)\n\n @button.buttonAndHandler(u'Submit')\n def handleApply(self, action):\n data, errors = self.extractData()\n ...\n\nThe allowed directives are:\n\n* ``grok.context()``, to specify the context of form view. If not given, the\n grokker will look for a module-level context, much like the standard\n ``grok.View``.\n* ``grok.require()``, to specify a permission. The default is ``zope2.View``\n for standard forms, ``cmf.ModifyPortalContent`` for edit forms, and\n ``cmf.AddPortalContent`` for add forms.\n* ``grok.layer()`` to specify a browser layer\n* ``grok.name()`` to set a different name. By default your form will be\n available as view @@yourformclassnamelowercase, but you can use\n ``grok.name()`` to set name explicitly.\n* ``form.wrap()`` to wrap the form in a layout wrapper view. You can pass\n an argument of ``True`` or ``False`` to enable or disable wrapping. If no\n argument is given, it defaults to ``True``. If omitted, the global default\n is used, which is to wrap in Zope 2.11 or earlier, and to not wrap in Zope\n 2.12 or later\n\nMore complex example how to use Grok directives with a form::\n\n from plone.directives import form\n from Products.CMFCore.interfaces import ISiteRoot\n\n class CompanyCreationForm(form.SchemaForm):\n \"\"\" A sample form how to \"create companies\".\n\n \"\"\"\n\n # Which plone.directives.form.Schema subclass is used to define\n # fields for this form (not shown on this example)\n schema = ICompanyCreationFormSchema\n\n # Permission required to view/submit the form\n grok.require(\"cmf.ManagePortal\")\n\n # The form does not care about the context object\n # and should not try to extract field value\n # defaults out of it\n ignoreContext = True\n\n # This form is available at the site root only\n grok.context(ISiteRoot)\n\n # The form will be available in Plone site root only\n # Use http://yourhost/@@create_company URL to access this form\n grok.name(\"create_company\")\n\n\n\n\nEach of the form base classes has a \"schema\" equivalent, which can be\ninitialised with a ``schema`` attribute instead of the ``fields`` attribute.\nThese forms use `plone.autoform`_'s ``AutoExtensibleForm`` as a base class,\nallowing schema hints as shown above to be processed::\n\n from plone.directives import form\n from z3c.form import button\n\n class MyForm(form.SchemaForm):\n grok.context(ISomeContext)\n grok.require('zope2.View')\n\n schema = IMySchema\n\n @button.buttonAndHandler(u'Submit')\n def handleApply(self, action):\n data, errors = self.extractData()\n ...\n\nNote that the ``schema`` can be omitted if you are using ``SchemaForm`` or\n``SchemaEditForm`` and you have given an interface as the argument to\n``grok.context()``. In this case, the context interface will be used as the\ndefault schema.\n\nThe available form base classes are:\n\nForm\n A simple page form, basically a grokked version of ``z3c.form.form.Form``.\n\nSchemaForm\n A page form that uses `plone.autoform`_. You must set the ``schema`` class\n variable (or implement it as a property) to a schema interface form which\n the form will be built. Form widget hints will be taken into account.\n\nAddForm\n A simple add form with \"Add\" and \"Cancel\" buttons. You must implement\n the ``create()`` and ``add()`` methods. See the `z3c.form`_ documentation\n for more details.\n\nSchemaAddForm\n An add form using `plone.autoform`_. Again, you must set the ``schema``\n class variable.\n\nEditForm\n A simple edit form with \"Save\" and \"Cancel\" buttons. See the `z3c.form`_\n documentation for more details.\n\nSchemaEditForm\n An edit form using `plone.autoform`_. Again, you must set the ``schema``\n class variable.\n\nDisplayForm\n A view with an automatically associated template (like ``grok.View``),\n that is initialised with display widgets. See `plone.autoform`_'s\n ``WidgetsView`` for more details.\n\nAll of the grokked form base classes above support associating a custom\ntemplate with the form. This uses the same semantics as ``grok.View``. See\n`grokcore.view`_ for details, but briefly:\n\n* If you want to completely customise rendering, you can override the\n ``render()`` method.\n* If you want to use a page template to render a form called ``MyForm`` in\n the module ``my.package.forms``, create a directory inside ``my.package``\n called ``forms_templates`` (the prefix should match the module name),\n and place a file there called ``myform.pt``.\n* If you do neither, the default form template will be used, as is the\n standard behaviour in z3c.form.\n\nNote that the automatically associated form template can use ``grok.View``\nmethods, such as ``view.url()`` and ``view.redirect()``, which are defined\nin the grokked form base classes.\n\nAlso note that you can use the view ``@@ploneform-macros`` from\n`plone.app.z3cform`_ if you want to use some of the standard form markup.\nFor example, the ``titlelessform`` macro will render the ``