{
"info": {
"author": "Plone Foundation",
"author_email": "releasemanager@plone.org",
"bugtrack_url": null,
"classifiers": [
"Development Status :: 5 - Production/Stable",
"Framework :: Plone",
"Framework :: Plone :: 5.2",
"Framework :: Zope :: 4",
"Programming Language :: Python",
"Programming Language :: Python :: 2.7",
"Programming Language :: Python :: 3.6",
"Programming Language :: Python :: 3.7"
],
"description": "=============\nplone.z3cform\n=============\n\nplone.z3cform is a library that enables the use of `z3c.form`_ in Zope.\nIt depends only on Zope and z3c.form.\n\nFor Plone integration, there is also `plone.app.z3cform`_, which can be\ninstalled to make the default form templates more Ploneish. That package\npulls in this one as a dependency.\n\nIn addition to pure interoperability support, a few patterns which are useful\nin Zope 2 applications are implemented here.\n\n.. contents:: Contents\n\nInstallation\n============\n\nTo use this package, simply install it as a dependency of the package where\nyou are using forms, via the ``install_requires`` line in ``setup.py``. Then\nloads its configuration via ZCML::\n\n \n\nStandalone forms\n================\n\nIf you are using Zope 2.12 or later, z3c.form forms will *almost* work\nout of the box. However, two obstacles remain:\n\n* The standard file upload data converter does not work with Zope 2, so\n fields (like ``zope.schema.Bytes``) using the file widget will not work\n correctly.\n* z3c.form expects request values to be decoded to unicode strings by the\n publisher, which does not happen in Zope 2.\n\nTo address the first problem, this package provides an override for the\nstandard data converter adapter (registered on the ``zope.schema.Bytes`` class\ndirectly, so as to override the default, which is registered for the less\ngeneral ``IBytes`` interface). To address the second, it applies a monkey\npatch to the ``update()`` methods of ``BaseForm`` and ``GroupForm`` from\n``z3c.form`` which performs the necessary decoding in a way that is consistent\nwith the Zope 3-style publisher.\n\nNote: If you override ``update()`` in your own form you must either call the\nbase class version or call the function ``plone.z3cform.z2.processInputs()``\non the request *before* any values in the request are used. For example::\n\n from plone.z3cform.z2 import processInputs\n from z3c.form import form\n\n ...\n\n class MyForm(form.Form):\n\n ...\n\n def update(self):\n processInputs(self.request)\n ...\n\nOther than that, you can create a form using standard `z3c.form`_ conventions.\nFor example::\n\n from zope.interface import Interface\n from zope import schema\n from z3c.form import form, button\n\n class IMyFormSchema(Interface):\n field1 = schema.TextLine(title=u\"A field\")\n field2 = schema.Int(title=u\"Another field\")\n\n class MyForm(form.Form):\n fields = field.Fields(IMyformSchema)\n\n @button.buttonAndHandler(u'Submit')\n def handleApply(self, action):\n data, errors = self.extractData()\n # do something\n\nYou can register this as a view in ZCML using the standard ````\ndirective::\n\n \n\nA default template will be used to render the form. If you want to associate\na custom template, you should do so by setting the ``template`` class variable\ninstead of using the ``template`` attribute of the ZCML directive::\n\n from Products.Five.browser.pagetemplatefile import ViewPageTemplateFile\n\n class MyForm(form.Form):\n fields = field.Fields(IMyformSchema)\n template = ViewPageTemplateFile('mytemplate.pt')\n\n @button.buttonAndHandler(u'Submit')\n def handleApply(self, action):\n data, errors = self.extractData()\n # do something\n\nSee below for more details about standard form macros.\n\nNote that to render any of the standard widgets, you will also need to make\nsure the request is marked with ``z3c.form.interfaces.IFormLayer``, as is\nthe norm with z3c.form. If you install `plone.app.z3cform`_ in Plone, that\nis already done for you, but in other scenarios, you will need to do this\nin whichever way Zope browser layers are normally applied.\n\nLayout form wrapper\n===================\n\nIn versions of Zope prior to 2.12, z3c.form instances cannot be registered\nas views directly, because they do not support Zope 2 security (via the\nacquisition mechanism). Whilst it may be possible to support this via custom\nmix-ins, the preferred approach is to use a wrapper view, which separates the\nrendering of the form from the page layout.\n\nThere are a few other reasons why you may want to use the wrapper view, even\nin later versions of Zope:\n\n* To support both an earlier version of Zope and Zope 2.12+\n* To re-use the same form in multiple views or viewlets\n* To use the ``IPageTemplate`` adapter lookup semantics from z3c.form to\n provide a different default or override template for the overall page\n layout, while retaining (or indeed customising independently) the default\n layout of the form.\n\nWhen using the wrapper view, you do *not* need to ensure your requests are\nmarked with ``IFormLayer``, as it is applied automatically during the\nrendering of the wrapper view.\n\nThe easiest way to create a wrapper view is to call the ``wrap_form()``\nfunction::\n\n from zope.interface import Interface\n from zope import schema\n from z3c.form import form, button\n\n from plone.z3cform import layout\n\n class IMyFormSchema(Interface):\n field1 = schema.TextLine(title=u\"A field\")\n field2 = schema.Int(title=u\"Another field\")\n\n class MyForm(form.Form):\n fields = field.Fields(IMyformSchema)\n\n @button.buttonAndHandler(u'Submit')\n def handleApply(self, action):\n data, errors = self.extractData()\n # do something\n\n MyFormView = layout.wrap_form(MyForm)\n\nYou can now register the (generated) ``MyFormView`` class as a browser view::\n\n \n\nIf you want to have more control, you can define the wrapper class manually.\nYou should derive from the default version to get the correct semantics. The\nfollowing is equivalent to the ``wrap_form()`` call above::\n\n class MyFormView(layout.FormWrapper):\n form = MyForm\n\nYou can of then add additional methods to the class, use a custom page\ntemplate, and so on.\n\nThe default ``FormWrapper`` class exposes a few methods and properties:\n\n* ``update()`` is called to prepare the request and then update the wrapped\n form.\n* ``render()`` is called to render the wrapper view. If a template has\n been set (normally via the ``template`` attribute of the\n ```` directive), it will be rendered here. Otherwise,\n a default page template is found by adapting the view (``self``) and\n the request to ``zope.pagetemplate.interfaces.IPageTemplate``, in the\n same way that ``z3c.form`` does for its views. A default template is\n supplied with this package (and customised in `plone.app.z3cform`_ to\n achieve a standard Plone look and feel).\n* ``form`` is a class variable referring to the form class, as set above.\n* ``form_instance`` is an instance variable set to the current form instance\n once the view has been initialised.\n\nWhen a form is rendered in a wrapper view, the form instance is temporarily\nmarked with ``plone.z3cform.interfaces.IWrappedForm`` (unless the form is\na subform), to allow custom adapter registrations. Specifically, this is used\nto ensure that a form rendered \"standalone\" gets a full-page template applied,\nwhile a form rendered in a wrapper is rendered using a template that renders\nthe form elements only.\n\nDefault templates and macros\n============================\n\nSeveral standard templates are provided with this package. These are all\nregistered as adapters from ``(view, request)`` to ``IPageTemplate``, as is\nthe convention in z3c.form. It therefore follows that these defaults can be\ncustomised with an adapter override, e.g. for a specific browser layer. This\nis useful if you want to override the standard rendering of all forms. If you\njust want to provide a custom template for a particular form or wrapper view,\nyou can specify a template directly on the form or view, as shown above.\n\n* ``templates/layout.pt`` is the default template for the layout wrapper view.\n It uses the CMFDefault ``main_template`` and fills the ``header`` slot.\n* ``templates/wrappedform.pt`` is the default template for wrapped forms.\n It renders the ``titlelessform`` macro from the ``@@ploneform-macros`` view.\n* ``templates/subform.pt`` is the default template for sub-forms.\n It uses the macros in ``@@ploneform-macros`` view to render a heading,\n top/bottom content (verbatim) and the fields and actions of the subform (but\n does not) render the ```` tag itself.\n* ``templates/form.pt`` is the default template for a standalone form. It uses\n the macro ``context/@@standard_macros/page`` (supplied by Five and normally\n delegating to CMF's ``main_template``) to render a form where the form label\n is the page heading.\n\nAs hinted, this package also registers a view ``@@ploneform-macros``, which\ncontains a set of macros that be used to construct forms with a standard\nlayout, error message display, and so on. It contains the following macros:\n\n* ``form`` is a full page form, including the label (output as an ````),\n description, and all the elements of ``titlelessform``. It defines two\n slots: ``title`` contains the label, and ``description`` contains the\n description.\n* ``titlelessform`` includes the form ``status`` at the top, the ````\n element, and the contents of the ``fields`` and ``actions`` macros. It also\n defines four slots: ``formtop`` is just inside the opening ```` tag;\n ``fields`` contains the ``fields`` macro; and ``actions`` contains the\n ``actions`` macro.\n* ``fields`` iterates over all widgets in the form and renders each, using the\n contents of the ``field`` macro. It also defines one slot, ``field`` which\n contains the ``field`` macro.\n* ``field`` renders a single field. It expects the variable ``widget`` to be\n defined in the TAL scope, referring to a z3c.form widget instance. It will\n output an error message if there is a field validation error, a label,\n a marker to say whether the field is required, the field description, and\n the widget itself (normally just an ```` element).\n* ``actions`` renders all actions (buttons) on the form. This normally results\n in a row of ```` elements.\n\nThus, to use the ``titlelessform`` macro, you could add something like the\nfollowing in a custom form template::\n\n \n\nNote that all of the templates mentioned above are customised by\n`plone.app.z3cform`_ to use standard Plone markup (but still retain the same\nmacros), so if you are using that package to configure this one, you should\nlook for the Plone-specific versions there.\n\nTemplate factories\n==================\n\nIf you want to provide an ``IPageTemplate`` adapter to customise the default\npage template used for wrapper views, forms or sub-forms, this package\nprovides helper classes to create an adapter factory for that purpose. You\nshould use these instead of ``z3c.form.form.FormTemplateFactory`` and\n(possibly) ``z3c.form.widget.WidgetTemplateFactory`` to get page templates\nwith Zope 2 semantics. These factories are also `Chameleon`_ aware, if you\nhave `five.pt`_ installed.\n\nThe most commonly used factory is\n``plone.z3cform.templates.ZopeTwoFormTemplateFactory``, which can be used to\nrender a wrapper view or a standalone form.\n\nTo render a wrapped form, you can use\n``plone.z3cform.templates.FormTemplateFactory``, which is closer to the\ndefault ``z3c.form`` version, but adds Chameleon-awareness.\n\nTo render a widget, the default ``WidgetTemplateFactory`` from z3c.form should\nsuffice, but if you need Zope 2 semantics for any reason, you can use\n``plone.z3cform.templates.ZopeTwoWidgetTemplateFactory``.\n\nAs an example, here are the default registrations from this package::\n\n import z3c.form.interfaces\n import plone.z3cform.interfaces\n\n from plone.z3cform.templates import ZopeTwoFormTemplateFactory\n from plone.z3cform.templates import FormTemplateFactory\n\n path = lambda p: os.path.join(os.path.dirname(plone.z3cform.__file__), 'templates', p)\n\n layout_factory = ZopeTwoFormTemplateFactory(path('layout.pt'),\n form=plone.z3cform.interfaces.IFormWrapper\n )\n\n wrapped_form_factory = FormTemplateFactory(path('wrappedform.pt'),\n form=plone.z3cform.interfaces.IWrappedForm,\n )\n\n # Default templates for the standalone form use case\n\n standalone_form_factory = ZopeTwoFormTemplateFactory(path('form.pt'),\n form=z3c.form.interfaces.IForm\n )\n\n subform_factory = FormTemplateFactory(path('subform.pt'),\n form=z3c.form.interfaces.ISubForm\n )\n\nThese are registered in ZCML like so::\n\n \n \n \n\n \n \n \n\nThe widget traverser\n====================\n\nIt is sometimes useful to be able to register a view on a *widget* and be\nable to traverse to that view, for example during a background AJAX request.\nAs an example of widget doing this, see `plone.formwidget.autocomplete`_.\n\nThis package provides a ``++widget++`` namespace traversal adapter which can\nbe used for this purpose. It is looked up on either the form wrapper view,\nor the form itself (in the case of standalone) forms. Thus, if you have a\nform view called ``@@my-form``, with a field called ``myfield``, you could\ntraverse to the widget for that view using::\n\n http://example.com/@@my-form/++widget++myfield\n\nThe widget may be on the form itself, or in a group (fieldset). If it exists\nin multiple groups, the first one found will be used.\n\nThe example above will yield widget, but it is probably not publishable.\nYou would therefore commonly register a view on the widget itself and use\nthat. In this case, ``self.context`` in the view is the widget instance. Such\na view could be looked up with::\n\n http://example.com/@@my-form/++widget++myfield/@@some-view\n\nA caveat about security\n-----------------------\n\nIn Zope 2.12 and later, the security machinery is aware of ``__parent__``\npointers. Thus, traversal and authorisation on ``@@some-view`` in the example\nabove will work just fine for a standard widget. In earlier versions of Zope,\nyou will need to mix acquisition into your widget (which rules out using any\nof the standard ``z3c.form`` widgets). For example::\n\n from Acquisition import Explicit\n from z3c.form.widget import Widget\n\n class MyWidget(Widget, Explicit):\n ...\n\nUnfortunately, in Zope 2.12, this will cause some problems during traversal\nunless you also mix acquisition into the view you registered on the widget\n(``@@some-view`` above). Specifically, you will get an error as the publisher\ntries to wrap the view in the widget.\n\nTo stay compatible with both Zope 2.12+ and earlier versions, you have two\noptions:\n\n* Ensure that you mix acquisition into the view on the widget\n* Ensure that the widget inherits from ``Explicit``, but does *not* provide\n the ``IAcquirer`` interface. This tricks the publisiher into relying on\n ``__parent__`` pointers in Zope 2.12.\n\nTo do the latter, you can use ``implementsOnly()``, e.g.::\n\n from zope.interface import implementsOnly\n from Acquisition import Explicit\n from z3c.form.widget import Widget\n\n ...\n\n class MyWidget(Widget, Explicit):\n implementsOnly(IMyWidget) # or just IWdget from z3c.form\n ...\n\n.. _z3c.form: http://pypi.python.org/pypi/z3c.form\n.. _plone.app.z3cform: http://pypi.python.org/pypi/plone.app.z3cform\n.. _CMF: http://www.zope.org/Products/CMF\n.. _Chameleon: http://pypi.python.org/pypi/Chameleon\n.. _five.pt: http://pypi.python.org/pypi/five.pt\n.. _plone.formwidget.autocomplete: http://pypi.python.org/pypi/plone.formwidget.autocomplete\n\nFieldsets and form extenders\n============================\n\nThe ``plone.z3cform.fieldsets`` package provides support for z3c.form groups\n(fieldsets) and other modifications via \"extender\" adapters. The idea is that\na third party component can modify the fields in the form and the way that\nthey are grouped and ordered.\n\nThis support relies on a mixin class, which is itself a subclass of\nz3c.form's ``GroupForm``::\n\n >>> from plone.z3cform.fieldsets import group, extensible\n\nTo use this, you have to mix it into another form as the *first* base class::\n\n >>> from zope.annotation import IAttributeAnnotatable\n >>> from z3c.form import form, field, tests, group\n >>> from zope.interface import Interface\n >>> from zope.interface import implementer\n >>> from zope import schema\n\n >>> class ITest(Interface):\n ... title = schema.TextLine(title=u\"Title\")\n\n >>> @implementer(ITest, IAttributeAnnotatable)\n ... class Test(object):\n ... # avoid needing an acl_users for this test in Zope 2.10\n ... __allow_access_to_unprotected_subobjects__ = 1\n ...\n ... title = u\"\"\n ... def getPhysicalRoot(self): # needed for template to acquire REQUEST in Zope 2.10\n ... return self\n\n >>> class TestForm(extensible.ExtensibleForm, form.Form):\n ... fields = field.Fields(ITest)\n\nHere, note the order of the base classes. Also note that we use an ordinary\nset of fields directly on the form. This known as the default fieldset.\n\nThis form should work as-is, i.e. we can update it. First we need to fake a\nrequest::\n\n >>> from plone.z3cform.tests import TestRequest\n\n >>> request = TestRequest()\n >>> request.other = {}\n >>> context = Test()\n >>> context.REQUEST = request\n\n >>> form = TestForm(context, request)\n >>> form.update()\n >>> form.fields.keys()\n ['title']\n\nNow let's register an adapter that adds two new fields - one in the\ndefault fieldset as the first field, and one in a new group. To do this,\nwe only need to register a named multi-adapter. However, we can use a\nconvenience base class to make it easier to manipulate the fields of the\nform::\n\n >>> from plone.z3cform.fieldsets.interfaces import IFormExtender\n >>> from zope.component import adapter\n >>> from zope.component import provideAdapter\n\n >>> class IExtraBehavior(Interface):\n ... foo = schema.TextLine(title=u\"Foo\")\n ... bar = schema.TextLine(title=u\"Bar\")\n ... baz = schema.TextLine(title=u\"Baz\")\n ... fub = schema.TextLine(title=u\"Fub\")\n ... qux = schema.TextLine(title=u\"Qux\")\n\nOne plausible implementation is to use an annotation to store this data.\n\n::\n\n >>> from zope.annotation import factory\n >>> from zope.annotation.attribute import AttributeAnnotations\n >>> from persistent import Persistent\n >>> @implementer(IExtraBehavior)\n ... @adapter(Test)\n ... class ExtraBehavior(Persistent):\n ...\n ...\n ... foo = u\"\"\n ... bar = u\"\"\n ... baz = u\"\"\n ... fub = u\"\"\n ... qux = u\"\"\n\n >>> ExtraBehavior = factory(ExtraBehavior)\n >>> provideAdapter(ExtraBehavior)\n >>> provideAdapter(AttributeAnnotations)\n\nWe can now write the extender. The base class gives us some helper methods\nto add, remove and move fields. Here, we do a bit of unnecessary work just\nto exercise these methods.\n\n::\n\n >>> @adapter(Test, TestRequest, TestForm) # context, request, form\n ... class ExtraBehaviorExtender(extensible.FormExtender):\n ...\n ... def __init__(self, context, request, form):\n ... self.context = context\n ... self.request = request\n ... self.form = form\n ...\n ... def update(self):\n ... # Add all fields from an interface\n ... self.add(IExtraBehavior, prefix=\"extra\")\n ...\n ... # Remove the fub field\n ... self.remove('fub', prefix=\"extra\")\n ...\n ... all_fields = field.Fields(IExtraBehavior, prefix=\"extra\")\n ...\n ... # Insert fub again, this time at the top\n ... self.add(all_fields.select(\"fub\", prefix=\"extra\"), index=0)\n ...\n ... # Move 'baz' above 'fub'\n ... self.move('baz', before='fub', prefix='extra', relative_prefix='extra')\n ...\n ... # Move 'foo' after 'bar' - here we specify prefix manually\n ... self.move('foo', after='extra.bar', prefix='extra')\n ...\n ... # Remove 'bar' and re-insert into a new group\n ... self.remove('bar', prefix='extra')\n ... self.add(all_fields.select('bar', prefix='extra'), group='Second')\n ...\n ... # Move 'baz' after 'bar'. This means it also moves group.\n ... self.move('extra.baz', after='extra.bar')\n ...\n ... # Remove 'qux' and re-insert into 'Second' group,\n ... # then move it before 'baz'\n ... self.remove('qux', prefix='extra')\n ... self.add(all_fields.select('qux', prefix='extra'), group='Second')\n ... self.move('qux', before='baz', prefix='extra', relative_prefix='extra')\n\n >>> provideAdapter(factory=ExtraBehaviorExtender, name=u\"test.extender\")\n\nWith this in place, let's update the form once again::\n\n >>> form = TestForm(context, request)\n >>> form.update()\n\nAt this point, we should have a set of default fields that represent the\nones set in the adapter::\n\n >>> form.fields.keys()\n ['extra.fub', 'title', 'extra.foo']\n\nAnd we should have one group created by the group factory::\n\n >>> form.groups # doctest: +ELLIPSIS\n (,)\n\nNote that the created group is of a subtype of the standard z3c.form group,\nwhich has got support for a separate label and description as well as a\ncanonical name::\n\n >>> isinstance(form.groups[0], group.Group)\n True\n\nThis should have the group fields provided by the adapter as well::\n\n >>> form.groups[0].fields.keys()\n ['extra.bar', 'extra.qux', 'extra.baz']\n\nCRUD (Create, Read, Update and Delete) forms\n============================================\n\nThis module provides an abstract base class to create CRUD forms.\nBy default, such forms provide a tabular view of multiple objects, whose\nattributes can be edited in-place.\n\nPlease refer to the ``ICrudForm`` interface for more details.\n\n >>> from plone.z3cform.crud import crud\n\nSetup\n-----\n\n >>> from plone.z3cform.tests import setup_defaults\n >>> setup_defaults()\n\n\nA simple form\n-------------\n\nFirst, let's define an interface and a class to play with:\n\n >>> from zope import interface, schema\n >>> class IPerson(interface.Interface) :\n ... name = schema.TextLine()\n ... age = schema.Int()\n\n >>> @interface.implementer(IPerson)\n ... class Person(object):\n ... def __init__(self, name=None, age=None):\n ... self.name, self.age = name, age\n ... def __repr__(self):\n ... return \"\" % (self.name, self.age)\n\nFor this test, we take the the name of our persons as keys in our\nstorage:\n\n >>> storage = {'Peter': Person(u'Peter', 16),\n ... 'Martha': Person(u'Martha', 32)}\n\nOur simple form looks like this:\n\n >>> class MyForm(crud.CrudForm):\n ... update_schema = IPerson\n ...\n ... def get_items(self):\n ... return sorted(storage.items(), key=lambda x: x[1].name)\n ...\n ... def add(self, data):\n ... person = Person(**data)\n ... storage[str(person.name)] = person\n ... return person\n ...\n ... def remove(self, id_item):\n ... id, item = id_item\n ... del storage[id]\n\nThis is all that we need to render a combined edit add form containing\nall our items:\n\n >>> class FakeContext(object):\n ... def absolute_url(self):\n ... return 'http://nohost/context'\n >>> fake_context = FakeContext()\n\n >>> from plone.z3cform.tests import TestRequest\n >>> print(MyForm(fake_context, TestRequest())()) \\\n ... # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE\n
...Martha...Peter...
\n\nEditing items with our form\n---------------------------\n\nBefore we start with editing objects, let's log all events that the\nform fires for us:\n\n >>> from zope.lifecycleevent.interfaces import IObjectModifiedEvent\n >>> from plone.z3cform.tests import create_eventlog\n >>> log = create_eventlog(IObjectModifiedEvent)\n\n >>> request = TestRequest()\n >>> request.form['crud-edit.Martha.widgets.select-empty-marker'] = u'1'\n >>> request.form['crud-edit.Peter.widgets.select-empty-marker'] = u'1'\n >>> request.form['crud-edit.Martha.widgets.name'] = u'Martha'\n >>> request.form['crud-edit.Martha.widgets.age'] = u'55'\n >>> request.form['crud-edit.Peter.widgets.name'] = u'Franz'\n >>> request.form['crud-edit.Peter.widgets.age'] = u'16'\n >>> request.form['crud-edit.form.buttons.edit'] = u'Apply changes'\n >>> html = MyForm(fake_context, request)()\n >>> \"Successfully updated\" in html\n True\n\nTwo modified events should have been fired:\n\n >>> event1, event2 = log.pop(), log.pop()\n >>> storage['Peter'] in (event1.object, event2.object)\n True\n >>> storage['Martha'] in (event1.object, event2.object)\n True\n >>> log\n []\n\nIf we don't make any changes, we'll get a message that says so:\n\n >>> html = MyForm(fake_context, request)()\n >>> \"No changes made\" in html\n True\n >>> log\n []\n\nNow that we renamed Peter to Franz, it would be also nice to have\nFranz use 'Franz' as the id in the storage, wouldn't it?\n\n >>> storage['Peter']\n \n\nWe can override the CrudForm's ``before_update`` method to perform a\nrename whenever the name of a person is changed:\n\n >>> class MyRenamingForm(MyForm):\n ... def before_update(self, item, data):\n ... if data['name'] != item.name:\n ... del storage[item.name]\n ... storage[str(data['name'])] = item\n\nLet's rename Martha to Maria. This will give her another key in our\nstorage:\n\n >>> request.form['crud-edit.Martha.widgets.name'] = u'Maria'\n >>> html = MyRenamingForm(fake_context, request)()\n >>> \"Successfully updated\" in html\n True\n >>> log.pop().object == storage['Maria']\n True\n >>> log\n []\n >>> sorted(storage.keys())\n ['Maria', 'Peter']\n\nNext, we'll submit the form for edit, but we'll make no changes.\nInstead, we'll select one time. This shouldn't do anything, since we\nclicked the 'Apply changes' button:\n\n >>> request.form['crud-edit.Maria.widgets.name'] = u'Maria'\n >>> request.form['crud-edit.Maria.widgets.age'] = u'55'\n >>> request.form['crud-edit.Maria.widgets.select'] = [u'selected']\n >>> html = MyRenamingForm(fake_context, request)()\n >>> \"No changes\" in html\n True\n >>> log\n []\n\nAnd what if we do have changes *and* click the checkbox?\n\n >>> request.form['crud-edit.Maria.widgets.age'] = u'50'\n >>> html = MyRenamingForm(fake_context, request)()\n >>> \"Successfully updated\" in html\n True\n >>> log.pop().object == storage['Maria']\n True\n >>> log\n []\n\nIf we omit the name, we'll get an error:\n\n >>> request.form['crud-edit.Maria.widgets.name'] = u''\n >>> html = MyRenamingForm(fake_context, request)()\n >>> \"There were some errors\" in html\n True\n >>> \"Required input is missing\" in html\n True\n\nWe expect an error message in the title cell of Maria:\n\n >>> checkbox_pos = html.index('crud-edit.Maria.widgets.select-empty-marker')\n >>> \"Required input is missing\" in html[checkbox_pos:]\n True\n\nDelete an item with our form\n----------------------------\n\nWe can delete an item by selecting the item we want to delete and\nclicking the \"Delete\" button:\n\n >>> request = TestRequest()\n >>> request.form['crud-edit.Peter.widgets.select'] = ['selected']\n >>> request.form['crud-edit.form.buttons.delete'] = u'Delete'\n >>> html = MyForm(fake_context, request)()\n >>> \"Successfully deleted items\" in html\n True\n >>> 'Franz' in html\n False\n >>> storage\n {'Maria': }\n\nAdd an item with our form\n-------------------------\n\n >>> from zope.lifecycleevent.interfaces import IObjectCreatedEvent\n >>> from plone.z3cform.tests import create_eventlog\n >>> log = create_eventlog(IObjectCreatedEvent)\n\n >>> request = TestRequest()\n >>> request.form['crud-add.form.widgets.name'] = u'Daniel'\n >>> request.form['crud-add.form.widgets.age'] = u'28'\n >>> request.form['crud-add.form.buttons.add'] = u'Add'\n >>> html = MyForm(fake_context, request)()\n >>> \"Item added successfully\" in html\n True\n\nAdded items should show up right away:\n\n >>> \"Daniel\" in html\n True\n\n >>> storage['Daniel']\n \n >>> log.pop().object == storage['Daniel']\n True\n >>> log\n []\n\nWhat if we try to add \"Daniel\" twice? Our current implementation of\nthe add form will simply overwrite the data:\n\n >>> save_daniel = storage['Daniel']\n >>> html = MyForm(fake_context, request)()\n >>> \"Item added successfully\" in html\n True\n >>> save_daniel is storage['Daniel']\n False\n >>> log.pop().object is storage['Daniel']\n True\n\nLet's implement a class that prevents this:\n\n >>> class MyCarefulForm(MyForm):\n ... def add(self, data):\n ... name = data['name']\n ... if name not in storage:\n ... return super(MyCarefulForm, self).add(data)\n ... else:\n ... raise schema.ValidationError(\n ... u\"There's already an item with the name '%s'\" % name)\n\n >>> save_daniel = storage['Daniel']\n >>> html = MyCarefulForm(fake_context, request)()\n >>> \"Item added successfully\" in html\n False\n >>> \"There's already an item with the name 'Daniel'\" in html\n True\n >>> save_daniel is storage['Daniel']\n True\n >>> len(log) == 0\n True\n\nRender some of the fields in view mode\n--------------------------------------\n\nWe can implement in our form a ``view_schema`` attribute, which will\nthen be used to view information in our form's table. Let's say we\nwanted the name of our persons to be viewable only in the table:\n\n >>> from z3c.form import field\n >>> class MyAdvancedForm(MyForm):\n ... update_schema = field.Fields(IPerson).select('age')\n ... view_schema = field.Fields(IPerson).select('name')\n ... add_schema = IPerson\n\n >>> print(MyAdvancedForm(fake_context, TestRequest())()) \\\n ... # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE\n
...Daniel...Maria...
\n\nWe can still edit the age of our Persons:\n\n >>> request = TestRequest()\n >>> request.form['crud-edit.Maria.widgets.age'] = u'40'\n >>> request.form['crud-edit.Daniel.widgets.age'] = u'35'\n >>> request.form['crud-edit.form.buttons.edit'] = u'Apply Changes'\n >>> html = MyAdvancedForm(fake_context, request)()\n >>> \"Successfully updated\" in html\n True\n\n >>> storage['Maria'].age\n 40\n >>> storage['Daniel'].age\n 35\n\nWe can still add a Person using both name and age:\n\n >>> request = TestRequest()\n >>> request.form['crud-add.form.widgets.name'] = u'Thomas'\n >>> request.form['crud-add.form.widgets.age'] = u'28'\n >>> request.form['crud-add.form.buttons.add'] = u'Add'\n >>> html = MyAdvancedForm(fake_context, request)()\n >>> \"Item added successfully\" in html\n True\n >>> len(storage)\n 3\n >>> storage['Thomas']\n \n\nOur form can also contain links to our items:\n\n >>> class MyAdvancedLinkingForm(MyAdvancedForm):\n ... def link(self, item, field):\n ... if field == 'name':\n ... return 'http://en.wikipedia.org/wiki/%s' % item.name\n\n >>> print(MyAdvancedLinkingForm(fake_context, TestRequest())()) \\\n ... # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE\n
\n >>> storage['Thomas'].name = u'Thomas'\n\nDon't render one part\n---------------------\n\nWhat if we wanted our form to display only one part, that is, only the\nadd *or* the edit form. Our CrudForm can implement\n``editform_factory`` and ``addform_factory`` to override one or both\nforms. Seeting one of these to ``crud.NullForm`` will make them\ndisappear:\n\n >>> class OnlyEditForm(MyForm):\n ... addform_factory = crud.NullForm\n >>> html = OnlyEditForm(fake_context, TestRequest())()\n >>> 'Edit' in html, 'Add' in html\n (True, False)\n\n >>> class OnlyAddForm(MyForm):\n ... editform_factory = crud.NullForm\n >>> html = OnlyAddForm(fake_context, TestRequest())()\n >>> 'Edit' in html, 'Add' in html\n (False, True)\n\nRender only in view, and define own actions\n-------------------------------------------\n\nSometimes you want to present a list of items, possibly in view mode\nonly, and have the user select one or more of the items to perform\nsome action with them. We'll present a minimal example that does this\nhere.\n\nWe can simply leave the ``update_schema`` class attribute out (it\ndefaults to ``None``). Furthermore, we'll need to override the\nediform_factory with our custom version that provides other buttons\nthan the 'edit' and 'delete' ones:\n\n >>> from pprint import pprint\n >>> from z3c.form import button\n\n >>> class MyEditForm(crud.EditForm):\n ... @button.buttonAndHandler(u'Capitalize', name='capitalize')\n ... def handle_capitalize(self, action):\n ... self.status = u\"Please select items to capitalize first.\"\n ... selected = self.selected_items()\n ... if selected:\n ... self.status = u\"Capitalized items\"\n ... for id, item in selected:\n ... item.name = item.name.upper()\n\n >>> class MyCustomForm(crud.CrudForm):\n ... view_schema = IPerson\n ... editform_factory = MyEditForm\n ... addform_factory = crud.NullForm # We don't want an add part.\n ...\n ... def get_items(self):\n ... return sorted(storage.items(), key=lambda x: x[1].name)\n\n >>> request = TestRequest()\n >>> html = MyCustomForm(fake_context, TestRequest())()\n >>> \"Delete\" in html, \"Apply changes\" in html, \"Capitalize\" in html\n (False, False, True)\n >>> pprint(storage)\n {'Daniel': ,\n 'Maria': ,\n 'Thomas': }\n\n >>> request.form['crud-edit.Thomas.widgets.select'] = ['selected']\n >>> request.form['crud-edit.form.buttons.capitalize'] = u'Capitalize'\n >>> html = MyCustomForm(fake_context, request)()\n >>> \"Capitalized items\" in html\n True\n >>> pprint(storage)\n {'Daniel': ,\n 'Maria': ,\n 'Thomas': }\n\nWe *cannot* use any of the other buttons:\n\n >>> del request.form['crud-edit.form.buttons.capitalize']\n >>> request.form['crud-edit.form.buttons.delete'] = u'Delete'\n >>> html = MyCustomForm(fake_context, request)()\n >>> \"Successfully deleted items\" in html\n False\n >>> 'Thomas' in storage\n True\n\nCustomizing sub forms\n---------------------\n\nThe EditForm class allows you to specify an editsubform_factory-a classs\ninherits from EditSubForm. This allows you to say, override the crud-row.pt\npage template and customize the look of the fields.\n\n >>> import zope.schema\n >>> class MyCustomEditSubForm(crud.EditSubForm):\n ...\n ... def _select_field(self):\n ... \"\"\"I want to customize the field that it comes with...\"\"\"\n ... select_field = field.Field(\n ... zope.schema.TextLine(__name__='select',\n ... required=False,\n ... title=u'select'))\n ... return select_field\n\n >>> class MyCustomEditForm(MyEditForm):\n ... editsubform_factory = MyCustomEditSubForm\n\n >>> class MyCustomFormWithCustomSubForm(MyCustomForm):\n ... editform_factory = MyCustomEditForm\n\n >>> request = TestRequest()\n >>> html = MyCustomFormWithCustomSubForm(fake_context, TestRequest())()\n\nStill uses same form as before\n >>> \"Delete\" in html, \"Apply changes\" in html, \"Capitalize\" in html\n (False, False, True)\n\nJust changes the widget used for selecting...\n >>> 'type=\"checkbox\"' in html\n False\n\nUsing batching\n--------------\n\nThe CrudForm base class supports batching. When setting the\n``batch_size`` attribute to a value greater than ``0``, we'll only get\nas many items displayed per page.\n\n >>> class MyBatchingForm(MyForm):\n ... batch_size = 2\n >>> request = TestRequest()\n >>> html = MyBatchingForm(fake_context, request)()\n >>> \"Daniel\" in html, \"Maria\" in html\n (True, True)\n >>> \"THOMAS\" in html\n False\n\nMake sure, the batch link to the next page is available\n\n >>> 'crud-edit.form.page=1' in html\n True\n\nShow next page and check content\n\n >>> request = TestRequest(QUERY_STRING='crud-edit.form.page=1')\n >>> request.form['crud-edit.form.page'] = '1'\n >>> html = MyBatchingForm(fake_context, request)()\n >>> \"Daniel\" in html, \"Maria\" in html\n (False, False)\n >>> \"THOMAS\" in html\n True\n\nThe form action also includes the batch page information so\nthe correct set of subforms can be processed::\n\n >>> print(html) \\\n ... # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE\n \n ...\n